Forem: Jakub Barszczewski

Basics of Asynchronous Rust with Tokio

Jakub Barszczewski — Fri, 28 Jan 2022 15:27:38 +0000

Introduction

Asynchronous code is everywhere now. It's basically a must when you write anything that needs to scale, like API/backend applications. There are different ways to tackle async code in Rust, but we will use the most popular crate for it, called Tokio. Ultimately, we will create a very simple API that can handle multiple requests at a time. Let's start!

The final code can be found here: Tokio tutorial Github repo.

Simple async hello-rust

Let's start by creating a basic program that executes a task. Create a project:

$ cargo new tokio-tutorial
$ cd tokio-tutorial

For this task we will need just one dependency. So open Cargo.toml and add it:

[dependencies]
tokio = {version = "1.14.0", features = ["full"]}

Now got to src/main.rs and replace content with:

#[tokio::main]
async fn main() {
    let task = tokio::spawn(async {
        println!("Hello, rust!");
    });

    task.await.unwrap();
}

And that's all you need to run (cargo run) a simple async hello-rust task!
The full code for this chapter can be found on my Github.
Of course, this example doesn't show the real power of Tokio runtime so let's jump on to more useful example.

Savings Balance API

Ok, to spare you from creating another ToDo list API we will do something even simpler: Savings Balance API. The aim is simple, we will expose two methods: GET and POST, to manage our balance. GET will return the current value and POST will add/substract from it. If you went through the Rust Book you probably stumbled across the Multithreaded Web Server project. It's a really great starting point to get your head around threads but requires a lot of boilerplate code (manual thread management etc.). This is where Tokio comes in.

First response

We will start with a simple server that listens for incoming requests. Replace the content of main.rs with:

use tokio::io::AsyncWriteExt;
use tokio::net::{TcpListener, TcpStream};

#[tokio::main]
async fn main() {
    let listener = TcpListener::bind("127.0.0.1:8181").await.unwrap();

    loop {
        let (stream, _) = listener.accept().await.unwrap();
        handle_connection(stream).await;
    }
}

async fn handle_connection(mut stream: TcpStream) {
    let contents = "{\"balance\": 0.00}";

    let response = format!(
        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
        contents.len(),
        contents
    );
    stream.write(response.as_bytes()).await.unwrap();
    stream.flush().await.unwrap();
}

Run it and in your browser navigate to http://127.0.0.1:8181 to see your first response from the server. Some code explanaition:

TCP listener is created and bound to our local address.
In a loop we await for an incoming connection.
Once connection is made, we pass the stream to our handler

Ok but it's not multitasking!
Exacly, our code is processing only one request at a time. So how do we make it process connections concurrently? Very simple. Just wrap the handle_connection() in a tokio::spawn function:

tokio::spawn(async move {
    handle_connection(stream).await;
});

And that's it! You now can process multiple connections at a time!
Code so far Can be found on GitHub here

GET and POST

Before we move to the last part of the tutorial: modyfing balance value, we need to make sure we can read and change the balance.

To keep things simple, we will have two scenarion:

GET http://127.0.0.1:8181 As soon as we detect GET request, we return balance.
POST http://127.0.0.1:8181/62.32 If the method is POST we will read value (max 10 characters) from route, update our balance and return it.

Of course, this is not the most RESTful or scalable approach but will work for this tutorial just fine.

The new handle_connection is looking like this:

async fn handle_connection(mut stream: TcpStream) {
    // Read the first 16 characters from the incoming stream.
    let mut buffer = [0; 16];
    stream.read(&mut buffer).await.unwrap();
    // First 4 characters are used to detect HTTP method
    let method_type = match str::from_utf8(&buffer[0..4]) {
        Ok(v) => v,
        Err(e) => panic!("Invalid UTF-8 sequence: {}", e),
    };

    let contents = match method_type {
        "GET " => {
            // todo: return real balance
            format!("{{\"balance\": {}}}", 0.0)
        }
        "POST" => {
            // Take characters after 'POST /' until whitespace is detected.
            let input: String = buffer[6..16]
                .iter()
                .take_while(|x| **x != 32u8)
                .map(|x| *x as char)
                .collect();
            let balance_update = input.parse::<f32>().unwrap();
            // todo: add balance update handling
            format!("{{\"balance\": {}}}", balance_update)
        }
        _ => {
            panic!("Invalid HTTP method!")
        }
    };

    let response = format!(
        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
        contents.len(),
        contents
    );
    stream.write(response.as_bytes()).await.unwrap();
    stream.flush().await.unwrap();
}

The idea is that we read first n characters from the incoming request and use that to perform selected operation. For the demo purpouse and simplicity we limit our input to a maximum of 10 characters.
Try running it now and see how response changes depending on chosen method. Example cURL command:

curl --request POST 'http://127.0.0.1:8181/-12.98'

Handling The Balance

So far, our handler returns hardcoded results. Let's introduce a variable that will keep the value inbetween the calls. Our balance variable will be shared across tasks and potentially threads so to support this it is wrapped in Arc<Mutex<_>>. Arc<> allows variable to be referenced concurrently from many tasks, and Mutex<> is a guard that make sure only one tasks can change it at a time (other tasks will have to wait for their turn).

Below is the full code with balance update. Check the comments on new lines:

use std::str;
use std::sync::{Arc, Mutex, MutexGuard};
use tokio::io::AsyncReadExt;
use tokio::io::AsyncWriteExt;
use tokio::net::{TcpListener, TcpStream};

#[tokio::main]
async fn main() {
    // create balance wrapped in Arc and Mutex for cross thread safety
    let balance = Arc::new(Mutex::new(0.00f32));
    let listener = TcpListener::bind("127.0.0.1:8181").await.unwrap();

    loop {
        let (stream, _) = listener.accept().await.unwrap();
        // Clone the balance Arc and pass it to handler
        let balance = balance.clone();
        tokio::spawn(async move {
            handle_connection(stream, balance).await;
        });
    }
}

async fn handle_connection(mut stream: TcpStream, balance: Arc<Mutex<f32>>) {
    // Read the first 16 characters from the incoming stream.
    let mut buffer = [0; 16];
    stream.read(&mut buffer).await.unwrap();
    // First 4 characters are used to detect HTTP method
    let method_type = match str::from_utf8(&buffer[0..4]) {
        Ok(v) => v,
        Err(e) => panic!("Invalid UTF-8 sequence: {}", e),
    };
    let contents = match method_type {
        "GET " => {
            // before using balance we need to lock it.
            format!("{{\"balance\": {}}}", balance.lock().unwrap())
        }
        "POST" => {
            // Take characters after 'POST /' until whitespace is detected.
            let input: String = buffer[6..16]
                .iter()
                .take_while(|x| **x != 32u8)
                .map(|x| *x as char)
                .collect();
            let balance_update = input.parse::<f32>().unwrap();

            // acquire lock on our balance and update the value
            let mut locked_balance: MutexGuard<f32> = balance.lock().unwrap();
            *locked_balance += balance_update;
            format!("{{\"balance\": {}}}", locked_balance)
        }
        _ => {
            panic!("Invalid HTTP method!")
        }
    };

    let response = format!(
        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
        contents.len(),
        contents
    );
    stream.write(response.as_bytes()).await.unwrap();
    stream.flush().await.unwrap();
}

Please note that we are acquiring lock on our balance, but we don't need to unlock it manually. Once the MutexGuard returned by lock() goes out of scope, the lock is automatically removed. In our situation it is straight after we're done with preparing response contents.

Now we are ready to run our app and test if we are getting a proper balance response. Example cURL command:

curl --request POST 'http://127.0.0.1:8181/150.50'

Here is an exercise for you: To see how using lock affects execution of the code try adding some delay (take a look at tokio::timer::Delay), long enough to make multiple API calls, just after acquiring a lock!

Conclusion

As we can see it's really easy to create an application in Rust that handle async operations thans to Tokio runtime. Of course, for API usually you will use a web framework like Actix, Rocket or Warp (among others) but hopefully you will have a better understanding of how it works "under the hood".

The final code can be found here: Tokio tutorial Github repo.

I hope you've enjoyed this tutorial and as always if you have any suggestions/questions don't hesitate to leave a comment below.

Thanks for reading and till the next time!

Rust + Tauri + Svelte Tutorial

Jakub Barszczewski — Wed, 14 Jul 2021 19:31:13 +0000

Rust Tauri

Intro

As Rust is getting more traction and more people want to learn it, I've decided to create another tutorial mainly for beginners. There are few ways to create desktop applications using Rust and Tauri is definitely one that will allow you to make beautiful UI (HTML/JS/CSS) and leverage power of Rust in the background. As Tauri lets you choose any frontend framework (or none) I've created a simple template that use Svelte and Bootstrap (through Sveltestrap) to give developers a nice starting point. To demonstrate how to use it we will create simple password generator.

If lost, here you can find finished project: https://github.com/jbarszczewski/pass-gen-tutorial

Let's start!

Create project

Ok this step is super simple. All you have to do is run this command:
degit jbarszczewski/tauri-svelte-template pass-gen-tutorial

Alternatively you can go to https://github.com/jbarszczewski/tauri-svelte-template and click Use this template button.

Quick overview of the project:

/src contains front-end code with the main view defined in App.svelte file.
/src-tauri here lives 'back-end' Rust code.
README.md provides basic instructions how to work with Tauri.

Add Rust command

Ok we want to create a simple command that will accept password length and return random string.
We will require one package to be added, rand, that generates random numbers. Open src-tauri/Cargo.toml and add rand = "0.8.0" under dependencies. At this point run yarn and thenyarn tauri dev command (from the project main directory) to view the changes in 'real-time'.

Note: First build might take a while as it's building project from scratch.

Now open /src-tauri/src/commands.rs file and replace the existing content with the following:

use rand::Rng;

static CHARS: [char; 70] = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9','a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's','t', 'u', 'v', 'w', 'x', 'y', 'z','A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S','T', 'U', 'V', 'W', 'X', 'Y', 'Z', '!','@','#','$','%','^','&','*'];

#[tauri::command]
fn generate_password(length: u32) -> String{
    let mut rng = rand::thread_rng();
    let mut result = String::new();
    for _x in 0..length {
        result.push(CHARS[rng.gen_range(0..70)]);
    }

    result
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn generates_string() {
        let result = generate_password(8);
        assert_eq!(result.len(), 8);
    }
}

Now let's look what this code does:

Import rand package.
Create array with characters that can be used for password generation.
Define new Tauri command generate_password that accepts password length as an integer.
Create new random generator and an empty string.
In the 'for' loop fill the string with characters from CHARS array
Return string containing password.

Additionally we have a single test that checks if newly created password have proper length (run cargo test from /src-tauri directory). Of course there is a room for improvement, like adding options to select types of characters to be used (only lowercase, no symbols etc.) and expand tests for better coverage. But as mentioned at the beginning this is just a simple app to demonstrate the template.

Last thing to do is rename command imported in main.rs to generate_password rather than standard my_custom_command and Rust code is ready to be used!

Modify Svelte component

We need to modify the front-end Svelte component to call our new command. Changes here are actually simple: we want to modify input to be a slider and pass it's value as a string to invoked command (remember we've changed the default name). Open App.svelte and let's start adding those changes.

In <script> section replace code after imports with following one:

let input: string = '8';
let result: string = '';
const handleClick = async () => {
    result = await invoke('generate_password', {
        length: +input,
    });
};

Difference are:

Default value for input
Command and parameter names with casting string to number: +input

The <main> tag will also look very similar, we update texts and change input to be a range type:

<Container>
    <Card class="mb-3">
        <CardHeader>
            <CardTitle>Password Generator</CardTitle>
        </CardHeader>
        <CardBody>
            <CardSubtitle>Generate random password</CardSubtitle>
            <CardText>Press 'Generate' button to create password with length: {input}.</CardText>
            <input
                type="range"
                id="exampleRange"
                bind:value="{input}"
                min="{1}"
                max="{32}"
                step="{1}"
            />
            <button color="primary" on:click="{handleClick}">Generate</button>
        </CardBody>
        <CardFooter> {#if result.length !== 0} {result} {:else} No result yet. {/if} </CardFooter>
    </Card>
</Container>

And we're done! Congratulations, you've just created your first Tauri app!

Conclusion

As you can see, it's really easy to create application with nice UI leveraging power of Rust in the background. There is a lot more good stuff in Tauri, like: updater if you plan to distribute your app and make sure users don't miss newest releases, splashscreen if app needs some time to load, etc. I really recommend heading to Tauri Docs to learn more about all the possibilities.

The complete project can be found here https://github.com/jbarszczewski/pass-gen-tutorial

I hope you've enjoyed this tutorial and as always if any suggestions/questions don't hesitate to leave a comment below.

Thanks for reading and till the next time!

Rust CLI Game of Life tutorial - PART 2

Jakub Barszczewski — Sun, 14 Feb 2021 13:14:19 +0000

Intro

Welcome to the second part of my Rust CLI tutorial. First one can be found here. In this part we will explore how to make our application configurable by adding command line arguments. Plan is to be able to set game Universe from the input file and control speed by passing its value.

"Final" code can be found on my github repo

Let's start!

Accept The Args

Simple way to accept arguments is to use function provided by standard library std::env::args for very simple situations it will be enough, but I want to show you how to easily create rich experience using external crate clap. There are 3 different ways to configure clap in your application:

'Builder Pattern'
YAML config file
macros

Personally 'Builder Pattern' is my favourite as it allows you to dynamically create args and offer compile time error check. For simple project like this it's totally fine to put the config in the main.rs but as project grow you might consider moving it to separate file for cleaner code and readability.
Time to see this crate in action. First add the dependency in Cargo.toml:

clap = "2.33.3"

and update our main.rs file:

use clap::{crate_version, App, Arg};

//below code goes at the beginning of main() function:
  let matches = App::new("CLI Game Of Life")
        .version(crate_version!())
        .author("jbarszczewski")
        .about("Simple implementation of Conway's Game Of Life in Rust.")
        .after_help("Have fun!")
        .arg(
            Arg::with_name("INPUT")
                .help("Sets the input file to configure initial state of game")
                .short("i")
                .long("input")
                .takes_value(true),
        )
        .arg(
            Arg::with_name("DELAY")
                .help("Sets the delay between game ticks. Value is in miliseconds")
                .short("d")
                .long("delay")
                .takes_value(true)
                .default_value("500"),
        )
        .get_matches();

The clap crate creates two subcommands for you (unless you explicitly override them):

help (-h or --help)
version (-V --version) That's why we provide basic info about the app. You may notice crate_version! macro, this will grab the version number from your Cargo.toml file so you don't need to manually update it. Then we add two arguments, INPUT and DELAY, with some description how to use it. Build your app with cargo build (you will find binary in /target/debug directory) and run like this ./cli-game-of-life -h which will print out help page:

CLI Game of Life 0.2.0
jbarszczewski
Simple implementation of Conway's Game of Life in Rust.

USAGE:
    cli-game-of-life [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -d, --delay <DELAY>    Sets the delay between game ticks. Value is in miliseconds [default: 500]
    -i, --input <INPUT>    Sets the input file to configure initial state of game

Have fun!

Now to get the passed values you can use:

if let Some(input) = matches.value_of("INPUT") {
    println!("A config file was passed: {}", input);
}

value_of() will return Option<T> so you can act accordingly depending if the value exist or not. Notice that our DELAY argument has default value set which means we will always have some value to work with.
Now, we won't use it in our application but often you will have flag arguments as well. By default, all clap arguments are flags that's why we had to add takes_value() when describing INPUT and DELAY. Because flags don't have value you can use them like this:

if matches.is_present("TEST") {
    println!("TEST!");
}

There are so many possible configuration options so I strongly advise checking documentation just be familiar what you can use.

Ok, so we've configured our application to accept arguments, but they don't do anything yet. That will change in a moment

Control the Speed

Let's make use of our DELAY argument. Right now, our game use hard-coded value of 500ms as a delay between each tick. Changing that will be super easy. First, we need to read and parse (Duration::from_millis() accept u64) our argument value:

let delay:u64 = matches.value_of("DELAY").unwrap().parse().unwrap();

We use the first unwrap (which will throw panic if None is returned) because we know that there is a default value of 500 in case user didn't pass the delay value, and the second unwrap (which will throw panic if Err is returned) because if value is not a valid positive integer, we want program to exit. If you want to manualy handle the second error, you could use logic like this:

let delay: u64 = match matches.value_of("DELAY").unwrap().parse() {
    Ok(val) => val,
    Err(e) => {
        println!("Error parsing DELAY argument: {}", e);
        500
    }
};

And then we can replace 500 in our poll function with the delay variable. If you want to test how it works just use command like:
./cli-game-of-life -d 200 (remember that value is in miliseconds).

There is one small issue. Because of how we wrote our loop, we display game after we check for the user input in the delay. That means if we pass DELAY, e.g. 5000, we will need to wait 5 seconds before anything appear on the screen. We can fix it by moving the "drawing" code out of the if statement:

// fixed loop code:
loop {
    queue!(stdout, Clear(ClearType::All))?;
    let mut i = 0;
    while let Some(line) = game.row_as_string(i) {
        queue!(stdout, MoveTo(0, i as u16), Print(line))?;
        i += 1;
    }

    queue!(
        stdout,
        MoveTo(0, (i + 1) as u16),
        Print("Press Esc to exit...")
    )?;
    stdout.flush()?;
    if poll(Duration::from_millis(delay))? {
        if let Event::Key(KeyEvent { code, .. }) = read()? {
            match code {
                KeyCode::Esc => {
                    break;
                }
                _ => {}
            }
        }
    }

    game.tick();
}

Define the Universe

Now it's time to make use of the INPUT argument. The value of this one is a path to universe configuration file. File will be in simple text format like this:

First line is the number of rows, second is the number of columns and following lines describe each cell, 0 being dead and 1 alive. Now there are two locations you can place the file:

In the root of your project, same directory as Cargo.toml is, and you can run your project using cargo run -- -i INPUT. When using Cargo to run your project everything that is after -- is passed as a parameter to your project rather than Cargo.
In ./target/debug. That means you need to run cargo build after each change and then execute target/debug/cli-game-of-life -i starship.

In this tutorial I recommend sticking with first option as it's simpler when developing your application. The above configuration is called starship pattern in Game of Life so let's call the file the same and move on to the next steps.

We will be reading the text file, so we need to add new imports:

use std::fs::File;
use std::io::{BufRead, BufReader};

Below is the function that accept path to the configuration file, reads it and return new game::Universe:

fn create_game_from_file(path: &str) -> game::Universe {
    let file = File::open(path).unwrap();
    let mut reader = BufReader::new(file);
    let mut line = String::new();
    let mut rows_number = 0;
    if let Ok(success) = reader.read_line(&mut line) {
        if success > 0 {
            rows_number = line.trim().parse().unwrap();
            line.clear();
        } else {
            panic!("Rows number not detected!");
        }
    };
    let mut cols_number = 0;
    if let Ok(success) = reader.read_line(&mut line) {
        if success > 0 {
            cols_number = line.trim().parse().unwrap();
            line.clear();
        } else {
            panic!("Columns number not detected!");
        }
    };
    let mut game_universe = game::Universe::new(cols_number, rows_number);
    let mut row = 0;
    let mut live_cells = Vec::<(u32, u32)>::new();
    loop {
        match reader.read_line(&mut line) {
            Ok(0) => break,
            Ok(_) => {
                let mut col = 0;
                for char in line.chars() {
                    match char {
                        '1' => live_cells.push((row, col)),
                        _ => {}
                    }
                    col += 1;
                }
            }
            _ => break,
        }

        line.clear();
        row += 1;
    }
    game_universe.set_cells(&live_cells);
    game_universe
}

It might seem long and for sure there is a room for some refactoring but should be easy to understand what is happening:

We open the file, and we pass it to the BufReader which is optimized for many subsequent reads from the same source.
We create new mutable String called line which will be reused for each line we read from the file.
We try to read line and parse it to number of rows and collumns. reader.read_line(&mut line) Returns Result<usize> which when success will contain number of bytes read. If it reaches the end of file it will return 0. Note that we need to call .trim() before parsing the value as read_line also returns end of line character. We also need to call clear() on our String as the read_line is appending to string rather than replacing it content.
We create new Universe with the specified size and new vector that will hold our live cells coordinates.
Loop that iterates through remaining lines, detects live cells and push them into the live_cells vector.
We pass call set_cells on our game_universe and return it afterwards.

Last thing that we need to do is make use of our new function. In main() delete the lines where we initialize new game (there will be two of them, one that creates new struct, the other that sets live cells), and place this code just under our delay variable initialization:

let mut game = match matches.value_of("INPUT") {
    Some(path) => create_game_from_file(path),
    None => {
        let mut default_game = game::Universe::new(5, 5);
        default_game.set_cells(&[(2, 1), (2, 2), (2, 3)]);
        default_game
    }
};

This is simple one: we try to read INPUT argument, if one is passed then we call create_game_from_file otherwise we fallback to our default universe.

Now we are ready to call cargo run -- -i starship and enjoy the view! You might want to create bigger universe than 5x5 as this new pattern is a moving, try something like 15x15, and because we don't validate line input lenght you don't need to add trailing 0 in each line.

Conclusion

We covered two topics in this tutorial: using command line arguments and reading a file. Both might sound simple but are really important when creating any CLI application.
I hope you've enjoyed this tutorial and as always if any suggestions/questions don't hesitate to leave a comment below.

Thanks for reading and till the next time!

Rust CLI Game of Life tutorial - PART 1

Jakub Barszczewski — Thu, 04 Feb 2021 15:20:27 +0000

Intro

Hi! If you're here that means you are curious about Rust and/or want to learn it. I've written my first Rust tutorial, Rust + Actix + CosmosDB (MongoDB) tutorial api, back in June 2020. This time I've decided I will try to cover another use case for Rust which is CLI. To make it more interesting it will be implementation of Game of Life based on Official Rust WebAssembly tutorial enhanced with some user interaction logic.

This is beginner tutorial, yet I still highly recommend going through official rustlings tutorial.

"Final" code can be found on my github repo

Let's start!

Create The Universe

After creating new project something like cargo new cli-game-of-life (or cargo init if you're already in correct directory) open your favourite editor and... ignore main.rs for now. We're gonna create game logic module first, so go ahead and create a new file src/game.rs. As mentioned in before, I will base the logic on official wasm tutorial so if you've done it before it will be very familiar. Let's start with defining an enum that will represent single cell in our game universe:

#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum Cell {
    Dead = 0,
    Alive = 1,
}

derive attribute will tell the compiler to provide basic implementation of passed traits so that we can assign cells with enum values and compare them.

Note: We could use simple bool value as well but enum will give us better readability while having the same memory footprint.

Our game universe is defined as follows:

pub struct Universe {
    width: u32,
    height: u32,
    cells: Vec<Cell>,
}

Now we can start implementing functions for our game. Let's start with a handy constructor that will initialize Universe with given size and assign Cells starting values and set_cells function that will accept an array of cells coordinates and set them to Alive state.

impl Universe {
    pub fn new(width: u32, height: u32) -> Universe {
        Universe {
            width: width,
            height: height,
            cells: vec![Cell::Dead; (width * height) as usize],
        }
    }

    pub fn set_cells(&mut self, cells: &[(u32, u32)]) {
        for (row, col) in cells.iter().cloned() {
            let idx = self.get_index(row, col);
            self.cells[idx] = Cell::Alive;
        }
    }

    fn get_index(&self, row: u32, column: u32) -> usize {
        (row * self.width + column) as usize
    }
}

The get_index is a helper fumction that will translate Universe coordinates into index of coresponding cell in cells array.

Next, we will implement Display trait for easy printing out current state of our game:

use std::fmt;

impl fmt::Display for Universe {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        for line in self.cells.as_slice().chunks(self.width as usize) {
            for &cell in line {
                let symbol = if cell == Cell::Dead { '◻' } else { '◼' };
                write!(f, "{}", symbol)?;
            }
            write!(f, "\n")?;
        }

        Ok(())
    }
}

Perfect! Now we have something to run. Head over to your main.rs and replace all with the following content:

mod game;

fn main() {
    let mut game = game::Universe::new(5, 5);
    game.set_cells(&[(2, 1), (2, 2), (2, 3)]);
    print!("{}", game);
}

And run your prohect with cargo run. Ok it works! Of course, nothing is really happening here so let's do another step and add the tick function to our code:

pub fn tick(&mut self) {
    let mut next = self.cells.clone();
    for row in 0..self.height {
        for col in 0..self.width {
            let idx = self.get_index(row, col);
            let cell = self.cells[idx];
            let live_neighbours = self.live_neighbour_count(row, col);
            next[idx] = match (cell, live_neighbours) {
                (Cell::Alive, x) if x < 2 => Cell::Dead,
                (Cell::Alive, 2) | (Cell::Alive, 3) => Cell::Alive,
                (Cell::Alive, x) if x > 3 => Cell::Dead,
                (Cell::Dead, 3) => Cell::Alive,
                (otherwise, _) => otherwise,
            };
        }
    }
    self.cells = next;
}

fn live_neighbour_count(&self, row: u32, column: u32) -> u8 {
    let mut count = 0;
    for delta_row in [self.height - 1, 0, 1].iter().cloned() {
        for delta_col in [self.width - 1, 0, 1].iter().cloned() {
            if delta_row == 0 && delta_col == 0 {
                continue;
            }

            let neighbour_row = (row + delta_row) % self.height;
            let neighbour_col = (column + delta_col) % self.width;
            let idx = self.get_index(neighbour_row, neighbour_col);
            count += self.cells[idx] as u8;
        }
    }

    count
}

This code comes straight from the WASM rust book and it applies Conway's Game Of Life rules to our universe while also taking care of edge wrapping so that our universe seems looped (See flavour 3).
Before we can use tick, we need to prepare our terminal to display animated game Universe. Let's hop into that right now!

P.S. - You can find source code for this chapter on my GitHub

Animate The Universe

To work with terminal input/output we will use Crossterm crate, so let's add it to our Cargo.toml:

[dependencies]
crossterm = "0.19.0"

This crate has some really handy functions to manipulate terminal and it's cross platform so we don't need to worry about any differences. Most of the crossterm commands are self-explanatory as they are grouped into relevan modules, like cursor::Hide does exactly what it says: it hides the cursor.

Because our game Universe will be updated and displayed in a loop, we want to clear the screen before each tick. We will move into the alternate screen for the game time and go back to original terminal screen once we are done. First let's make sure we have all the necessery imports:

use crossterm::{
    cursor::{Hide, MoveTo, Show},
    event::{poll, read, Event},
    execute,
    style::{Color, Print, ResetColor, SetForegroundColor},
    terminal::{Clear, ClearType, EnterAlternateScreen, LeaveAlternateScreen},
    Result,
};
use std::io::stdout;
use std::time::Duration;

Also, our main function need complete overhaul and now will look like this:

fn main() -> Result<()> {
    let mut game = game::Universe::new(5, 5);
    game.set_cells(&[(2, 1), (2, 2), (2, 3)]);
    execute!(
        stdout(),
        EnterAlternateScreen,
        SetForegroundColor(Color::Magenta),
        Hide
    )?;

    loop {
        if poll(Duration::from_millis(500))? {
            match read()? {
                Event::Key(_) => break,
                _ => {}
            }
        } else {
            execute!(
                stdout(),
                Clear(ClearType::All),
                MoveTo(0, 0),
                Print(&game),
                Print("Press enter to exit...")
            )?;
            game.tick();
        }
    }
    execute!(stdout(), ResetColor, Show, LeaveAlternateScreen)?;
    Ok(())
}

Ok let's break down what we did here:

main now returns Result type. This will allow us to provide feedback to users and set appropriate exit codes where needed.
We set up our terminal in execute! macro, which accepts std::io::Writer type (stdout in our case) as first argument followed by one or more commands.
In a loop we try to read the user input wrapped in a poll which ensure that we don't block the execution. We break the loop when user press the Enter key. If no user input is available in 500ms then we draw current state of the Universe and compute next state with tick()
Once the loop is over, we leave the alternate screen of the terminal.

Now run the app with cargo run and you should see simple pattern alternating between horizontal and vertical lines.
Ok but pressing Enter is not what user expect when trying to exit the app. Let's modify our code so that it could respond to different keys.

Interact with The Universe

Reason we could only process Enter is that by default input is being processed on enter press. Which makes sense as usually you first want to type in the command and execute when it's all ready. But in our case, we want user to be able to interact with single key presses. That means we need to enable raw mode. New code changes are as follow:

// add required imports:
use terminal::{disable_raw_mode, enable_raw_mode};

// add this line at the very begining of the main() function:
enable_raw_mode()?;

// replace code block when poll returns true, the match statement, with following:

if let Event::Key(KeyEvent { code, .. }) = read()? {
    match code {
        KeyCode::Esc => {
            break;
        }
        _ => {}
    }
}

// finaly disable raw mode at the end of the function before returning Ok(()):
disable_raw_mode()?;

It's very important to add ability to exit from the loop as raw mode disables ctrl+c funcionality.

When you will try to run it now you will notice that formatting is all messed up. That's because raw mode doesn't process new line character. We need now explicitly set the cursor to the correct positions. That also means we cannot use the Display trait anymore. Instead, we will iterate through each row of the game Universe and print it out separately.

Add new method to the Universe:

pub fn row_as_string(&self, row: u32) -> Option<String> {
    if row < self.height {
        let mut row_string = String::new();
        let start = self.get_index(row, 0);
        let end = self.get_index(row, self.width);
        let line = &self.cells[start..end];
        for &cell in line {
            let symbol = if cell == Cell::Dead { '◻' } else { '◼' };
            row_string.push(symbol);
        }
        Some(row_string)
    } else {
        None
    }
}

If the row is withing Universe size we will return all its cells as a String, otherwise None is returned.
In our main.rs add new import from crossterm queue, queue! macro is similar to execute but require manual flush. This makes it really handy if you want to conditionaly build your output. Let's see how it goes. First at the beginning of our main() function initialize a new variable:

let mut stdout = stdout();

Now you can replace stdout() with our new variable name for consistency. Then replace the whole loop with following code:

loop {
    if poll(Duration::from_millis(500))? {
        if let Event::Key(KeyEvent { code, .. }) = read()? {
            match code {
                KeyCode::Esc => {
                    break;
                }
                _ => {}
            }
        }
    } else {
        queue!(stdout, Clear(ClearType::All))?;
        let mut i = 0;
        while let Some(line) = game.row_as_string(i) {
            queue!(stdout, MoveTo(0, i as u16), Print(line))?;
            i += 1;
        }

        queue!(
            stdout,
            MoveTo(0, (i + 1) as u16),
            Print("Press Esc to exit...")
        )?;
        stdout.flush()?;
        game.tick();
    }
}

The key press handling remains unchanged. All the changes are in else block:

We've replaced single execute! with queue! macros.
We iterate through game Universe rows while row_as_string(i) returns results and queue printing them on separate lines. You can see here how handy is to return Option<T>! We don't need any null handling and the code looks super clean.
After all text is ready, we flush() stdout.

Conclusion

And that's it for part 1! A good exercise would be to enhance the app with some more user interactions, like controlling speed or colours. In the next part I will cover how we can process command line arguments to set up our game.
I hope you've enjoyed this tutorial and as always if any suggestions/questions don't hesitate to leave a comment below.

Thanks for reading and till the next time!

Edit: Part 2 now available here!

Rust + Actix + CosmosDB (MongoDB) tutorial api.

Jakub Barszczewski — Sat, 27 Jun 2020 14:18:51 +0000

Intro

When working on one of my projects I decided to create simple logging API and Rust seemed like a perfect choice to learn some new tech. Same goes for going with Azure CosmosDB which now offer free tier that is perfect for learning and small personal projects.

I consider this tutorial to be a good starting point for beginner rustaceans (I'm one of those) but I assume that you know the basics. I highly recommend going through official rustlings tutorial.

"Final" code can be found on my github repo

Setting up "Hello fellow Rustacean!"

First let's create a new projct by either creating new project directory and running cargo init from it or using cargo new {project-name} that also create directory for you. Once you're ready open your editor of choice (VS Code here with official 'Rust' extensions and 'cargo' that helps with staying up do date with dependencies) and let's start!

We will begin by creating simple http server that return us classic greatings. Open Cargo.toml and add two new dependencies:

[dependencies]
actix-rt = "1.1.1"
actix-web = "2.0"

Note: First stick with versions I used for this tutorial and then update. I found that already few crates had some breaking changes so it's safer to application working first.

Then replace code in main.rs with the one below:

use actix_web::{web, App, HttpServer, Responder};
use std::env;

#[actix_rt::main]
async fn main() -> std::io::Result<()> {
    env::set_var("RUST_LOG", "actix_web=debug");
    HttpServer::new(|| App::new().route("/", web::get().to(hello)))
        .bind("127.0.0.1:8000")?
        .run()
        .await
}

async fn hello() -> impl Responder {
    format!("Hello fellow Rustacean!")
}

That's it! now just cargo run and go to 127.0.0.1:8000 in your browser.

Let's quickly see what we did here:

#[actix_rt::main] marked our main async function as to be executed in actix runtime.
"RUST_LOG"sets logger used by actix to output errors.
New App with registered request handler is passed to HttpServer to listen for incoming connections.

Creating service configuration

As you can see, right now we've registered our routes in main function. In this tutorial we won't have many resources but it's good practice to have cleaner structure. Create new file: src\logs_handlers\mod.rs and add code below:

use actix_web::{web, Responder};

pub fn scoped_config(cfg: &mut web::ServiceConfig) {
    cfg.service(
        web::resource("/logs")
            .route(web::get().to(get_logs))
            .route(web::post().to(add_log)),
    );
}

async fn get_logs() -> impl Responder {
    format!("Not yet implemented!")
}

async fn add_log() -> impl Responder {
    format!("Not yet implemented!")
}

The scoped_config() function is responsible for registering logs resource configuration in our service. That means we can create multiple modules for each resource and then just call this configurator function for each of them from our main function. So, let's do that by modifying App builder code:

App::new().service(web::scope("/api").configure(logs_handlers::scoped_config))

Don't forget to import newly created module as well and add

mod logs_handlers;

below the use block.

Now we've set up our api to handle GET and POST methods on route api/logs. Try it!

Connecting to CosmosDB/MongoDB

In this tutorial I use free tier Azure CosmosDB database with MongoDB API, but of course the choice is yours. Let's create db client and return some data. When I was prototyping my API, I was creating client in the handler manually. That is really inefficient way, instead we can utilize client pooling build in MongoDB client crate and setup it on app startup. Add MongoDB dependency to Cargo.toml

bson = "1.0.0"
futures = "0.3.5"
mongodb = "1.0.0"

Open main.rs and add import module:

use mongodb::{options::ClientOptions, Client};
use std::sync::*;

And then modify your main function to look like this:

#[actix_rt::main]
async fn main() -> std::io::Result<()> {
    env::set_var("RUST_LOG", "actix_web=debug");
    let mut client_options = ClientOptions::parse("mongodb://free-tier-db:yfQtNbXyW2h9HUOOplCeHgjzzbJMnfMQn2BZuzAkw5gv0uBkqbdbQPdnQ98e6UtS5Z3p1ZrG4rgkmEKBURNgwg==@free-tier-db.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@free-tier-db@").await.unwrap();
    client_options.app_name = Some("PlantApi".to_string());
    let client = web::Data::new(Mutex::new(Client::with_options(client_options).unwrap()));
    HttpServer::new(move || {
        App::new()
            .app_data(client.clone())
            .service(web::scope("/api").configure(logs_handlers::scoped_config))
    })
    .bind("127.0.0.1:8000")?
    .run()
    .await
}

Note: Replace connection string with yours. Don't worry we will not leave connection string in the code in the final version.

Our new code creates a MongoDB client that is wrapped in mutex object for thread safety and which in turn is passed to application data object that is responsible for making it available in handlers.

Fetching logs

Now we are ready to connect to our DB and make use of it. Go to logs_handlers/mod.rs and import few more modules:

use actix_web::{web, HttpResponse, Responder};
use bson::{doc, Bson};
use futures::stream::StreamExt;
use mongodb::{options::FindOptions, Client};
use std::sync::Mutex;

const MONGO_DB: &'static str = "iotPlantDB";
const MONGO_COLL_LOGS: &'static str = "logs";

...// no changes in  scoped_config

async fn get_logs(data: web::Data<Mutex<Client>>) -> impl Responder {
    let logs_collection = data
        .lock()
        .unwrap()
        .database(MONGO_DB)
        .collection(MONGO_COLL_LOGS);

    let filter = doc! {};
    let find_options = FindOptions::builder().sort(doc! { "_id": -1}).build();
    let mut cursor = logs_collection.find(filter, find_options).await.unwrap();

    let mut results = Vec::new();
    while let Some(result) = cursor.next().await {
        match result {
            Ok(document) => {
                results.push(document);
            }
            _ => {
                return HttpResponse::InternalServerError().finish();
            }
        }
    }
    HttpResponse::Ok().json(results)
}

... // no changes in add_log

Ok, let's see what we did here.

We created two constants to hold our DB and collection names.
Our get_logs function accept application data (our MongoDB client that we've set up in main function).
We use client to give us handle to the logs collection.
find function is used with no filter (returns everything) and simple sort by _id
We iterate results using cursor returned by findand populate result vector with incoming documents which then is returned in json format.

Now make sure you have some data in your DB and you're ready to test first call. My test data, and the one I will be using in add_log handler looks like this:

{
    "_id": {
        "$oid": "5ee3bb1f00bc6d3b007b79ca"
    },
    "deviceId": "mock_device-01",
    "message": "test message",
    "createdOn": {
        "$date": "2020-06-12T17:27:59.404Z"
    }
}

Before we move to implementing POST handler let's do one more change. We should move the connection string out from the code. Let's save it as environmental variable named CONNECTION_STRING_LOGS and then we can replace line responsible for creating client options in main.rs with this:

 let mongo_url = env::var("CONNECTION_STRING_LOGS").unwrap();
 let mut client_options = ClientOptions::parse(&mongo_url).await.unwrap();

Much nicer solution!

Adding logs

It's time to finish our api with the add_log handler. Add two more dependencies, chrono and serde, first will help us with DateTime and latter is the most popular serialize/deserialize crate. Your final dependency list should look like this:

[dependencies]
actix-rt = "1.1.1"
actix-web = "2.0"
bson = "1.0.0"
chrono = "0.4.11"
futures = "0.3.5"
mongodb = "1.0.0"
serde = { version = "1.0", features = ["derive"] }

Let's go back to logs_handlers/mod.rs, import newly added modules and add struct for new logs:

use chrono::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
pub struct NewLog {
    pub id: String,
    pub message: String,
}

NewLog has derive(Deserialize) trait as this will be used to deserialize incoming POST body. We only need device/source id and a message to log, timestamp will be created in the handler function and MongoDB object id by the database.
Replace add_log function with:

async fn add_log(data: web::Data<Mutex<Client>>, new_log: web::Json<NewLog>) -> impl Responder {
    let logs_collection = data
        .lock()
        .unwrap()
        .database(MONGO_DB)
        .collection(MONGO_COLL_LOGS);

    match logs_collection.insert_one(doc! {"deviceId": &new_log.id, "message": &new_log.message, "createdOn": Bson::DateTime(Utc::now())}, None).await {
        Ok(db_result) => {
            if let Some(new_id) = db_result.inserted_id.as_object_id() {
                println!("New document inserted with id {}", new_id);   
            }
            return HttpResponse::Created().json(db_result.inserted_id)
        }
        Err(err) =>
        {
            println!("Failed! {}", err);
            return HttpResponse::InternalServerError().finish()
        }
    }
}

As with get_logs this function makes use of mongo client stored in application data to get handle to the logs collection. Notice additional parameter new_log of type NewLog that we've created before. If your body match the struct (names and value types) it will be properly deserialized and ready to use. What this function does is:

Dynamically creates document using new_log data and fill createdOn with current UTC date and time.
Check the results and returns new document id if success.

And we're done! Two simple functions that can handle incoming GET and POST requests. Run the application and test it by adding new logs:

curl --location --request POST 'localhost:8000/api/logs' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id":"tutorial-client",
    "message":"I'\''m a Rustacean!"
}'

Optional `get_logs` code

This is a simple example so our get_logs function returns documents in the format it receives them. But what if we want to perform some operations on the results before we return them? We can easily deserialize document (and check if it matches our model) by modifying code slightly:
We add few more imports:

use bson::{doc, oid::ObjectId, Bson, UtcDateTime};
use serde::{Deserialize, Serialize};

Specify Log structure as it wil be different than NewLog

#[derive(Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
pub struct Log {    
    #[serde(rename = "_id")]
    pub id: ObjectId,
    #[serde(rename = "deviceId")]   
    pub device_id: String,  
    pub message: String,
    pub timestamp: UtcDateTime,
}

And just above the line where we push received document into the results vector, deserialize it using model above:

let log: Log = bson::from_bson(Bson::Document(document)).unwrap();

Conclusion

We arrived at the end of this tutorial. As you can see it's not that complicated to create APIs in Rust. Of course, the example above is quite simple, but I think it's a good starting point even if you're not that familiar with Rust.
Please leave a comment if you liked (or not) this article or if something doesn't seem right etc.

Thanks for reading and till the next time!

Forem: Jakub Barszczewski

Basics of Asynchronous Rust with Tokio

Introduction

Simple async hello-rust

Savings Balance API

First response

GET and POST

Handling The Balance

Conclusion

Rust + Tauri + Svelte Tutorial

Rust Tauri

Intro

Create project

Add Rust command

Modify Svelte component

Conclusion

Rust CLI Game of Life tutorial - PART 2

Intro

Accept The Args

Control the Speed

Define the Universe

Conclusion

Rust CLI Game of Life tutorial - PART 1

Intro

Create The Universe

Animate The Universe

Interact with The Universe

Conclusion

Rust + Actix + CosmosDB (MongoDB) tutorial api.

Intro

Setting up "Hello fellow Rustacean!"

Creating service configuration

Connecting to CosmosDB/MongoDB

Fetching logs

Adding logs

Optional get_logs code

Conclusion

Optional `get_logs` code