DEV Community: Javier Viola

Exploring Substrate

Javier Viola — Sun, 05 Sep 2021 17:48:54 +0000

Hi there! welcome back, this will be the first post of a new serie exploring the Substrate framework. We will be using the tutorials and recipes from the Substrate Developer Hub as our road map to exploring and learning.

As the landing page of the hub says, Substrate is a modular framework that enables you to create purpose-built blockchains by composing custom or pre-built components., that means that you can create your first Substrate Chain by using the pre-built components that the framework offer. And that is what the first tutorial is about.

You can follow the first tutorial for detailed instructions, but make sure to review the installation page for setup your environment.

Let's continue with the exploration, assuming that you already cloned the needed templates, first we need to build the node (in release mode).

# node
$ cargo build --release

And then you can run both front-end and node in different terminals

First the node using the --dev and --tmp flags

$ ./target/release/node-template --dev --tmp

2021-09-03 19:39:37 Running in --dev mode, RPC CORS has been disabled.
2021-09-03 19:39:37 Substrate Node
2021-09-03 19:39:37 ✌️  version 3.0.0-monthly-2021-08-cd936fc-x86_64-macos
2021-09-03 19:39:37 ❤️  by Substrate DevHub <https://github.com/substrate-developer-hub>, 2017-2021
2021-09-03 19:39:37 📋 Chain specification: Development
2021-09-03 19:39:37 🏷 Node name: efficacious-cart-4351

And the front-end

# front-end
yarn i
yarn start
...
You can now view substrate-front-end-template in the browser.

  Local:            http://localhost:8000/substrate-front-end-template
  On Your Network:  http://192.168.0.175:8000/substrate-front-end-template

You will get a nice UI that allow you to interact with your first Substrate Chain :)

And even you can interact and make transfers between the test accounts :)

Great!! we complete the first tutorial, we can also explore other options un the UI and interact with our first chain :)

Let's now continue, we will first add add the nicks pallet following the next tutorial. But first a little definition from the KB page:

Pallets are a special kind of Rust module made up of a set of types, trait implementations and functions from which Substrate runtimes can be composed. FRAME not only provides a library of commonly used Substrate pallets but also a framework to build custom domain-specific pallets, giving runtime engineers the flexibility to define their runtime's behaviour according to their target use case. The result: each pallet has its own discrete logic which can modify the features and functionality of your blockchain's state transition functions.

You can follow the detailed explanation in the tutorial, but in a nutshell to add the pallet you need to modify two files. First you need to add the dep to the runtime crate.

// runtime/Cargo.toml
(...)
[dependencies.pallet-nicks]
default-features = false
git = 'https://github.com/paritytech/substrate.git'
tag = 'monthly-2021-08'
version = '4.0.0-dev'

Note: The version and tag may be outdate, you can check the latest ones.

And also we need to add the feature to the std features of the runtime crate ( you can read in the tutorial for a nice explanation)

// runtime/Cargo.toml
std = [
(...)
    'pallet-balances/std',
    'pallet-nicks/std',
(...)

Great! Now is time to configure the pallet, since every pallet needs to implement the Config trait in order to be included in the runtime (by the construct_runtime macro).

We can here use the help of the rust-analyzer to get the skeleton of the needed members.

// runtime/src/lib.rs
impl pallet_nicks::Config for Runtime {
    type Event;

    type Currency;

    type ReservationFee;

    type Slashed;

    type ForceOrigin;

    type MinLength;

    type MaxLength;
}

And, also detailed in the tutorial, we had another macro (parameter_types) to help us defined constant values. Let use this macro to define some constants needed in the configuration.

// runtime/src/lib.rs
parameter_types! {
    pub const NickReservationFee: u128 = 100;
    pub const MinNickLength: usize = 8;
    pub const MaxNickLength: usize = 16;
}

And now let go to the trait implementation block and complete the needed config (using the code from the tutorial).

// runtime/src/lib.rs
    // The Balances pallet implements the ReservableCurrency trait.
    // `Balances` is defined in `construct_runtimes!` macro. See below.
    // https://substrate.dev/rustdocs/latest/pallet_balances/index.html#implementations-2
    type Currency = Balances;

    // Use the NickReservationFee from the parameter_types block.
    type ReservationFee = NickReservationFee;

    // No action is taken when deposits are forfeited.
    type Slashed = ();

    // Configure the FRAME System Root origin as the Nick pallet admin.
    // https://substrate.dev/rustdocs/latest/frame_system/enum.RawOrigin.html#variant.Root
    type ForceOrigin = frame_system::EnsureRoot<AccountId>;

    // Use the MinNickLength from the parameter_types block.
    type MinLength = MinNickLength;

    // Use the MaxNickLength from the parameter_types block.
    type MaxLength = MaxNickLength;

    // The ubiquitous event type.
    type Event = Event;

Last, we need to add the pallet to the runtime by adding to the construct_runtime macro call.

// runtime/src/lib.rs
construct_runtime!(
    pub enum Runtime where
        Block = Block,
        NodeBlock = opaque::Block,
        UncheckedExtrinsic = UncheckedExtrinsic
    {
        System: frame_system::{Pallet, Call, Config, Storage, Event<T>},
        RandomnessCollectiveFlip: pallet_randomness_collective_flip::{Pallet, Storage},
        Timestamp: pallet_timestamp::{Pallet, Call, Storage, Inherent},
        Aura: pallet_aura::{Pallet, Config<T>},
        Grandpa: pallet_grandpa::{Pallet, Call, Storage, Config, Event},
        Balances: pallet_balances::{Pallet, Call, Storage, Config<T>, Event<T>},
        TransactionPayment: pallet_transaction_payment::{Pallet, Storage},
        Sudo: pallet_sudo::{Pallet, Call, Config<T>, Storage, Event<T>},
        // Include the custom logic from the pallet-template in the runtime.
        TemplateModule: pallet_template::{Pallet, Call, Storage, Event<T>},
        // add nicks pallet
        Nicks: pallet_nicks::{Pallet, Call, Storage, Event<T>},
    }
);

Awesome! Time to compile again and see it in action :)

$ cargo build --release

And we get an error, the trait From<usize> is not implemented for u32.

We can look at the Get trait in the substrate repo for more details in the implementation, but for now let go to our code and change the usize to u32. Update: there is already a PR in the tutorial repo to fix this and use u32.


// runtime/src/lib.rs
parameter_types! {
    pub const NickReservationFee: u128 = 100;
    pub const MinNickLength: u32 = 8;
    pub const MaxNickLength: u32 = 16;
}

Let try to compile again...

$ cargo build --release
(...)
Finished release [optimized] target(s) in 18m 57s

Nice! we can run again and interact with the nicks pallet.

$ ./target/release/node-template --dev --tmp

Set the nick of Alice address

Wait, looking at the Events there is an error in the execution

system:ExtrinsicFailed:: (phase={"applyExtrinsic":1})-2
DispatchError: {"module":{"index":9,"error":1}}, DispatchInfo: {"weight":50000000,"class":"Normal","paysFee":"Yes"}
An extrinsic failed. \[error, info\]

After looking how to read this errors I found a nice explanation in this so answer

For future occasions there it goes a tip when a dispatch error happens. index:9 and error:0 are the index of the pallet in construct_runtime! which is throwing the error, and the index of the error in the #[pallet::error] definition of the pallet concerned.

So, in our case index:9 is the nicks pallet and we error:1 is TooLong (defined in this line), since remember we set the MaxNickLength to 16. Let's try with a nick with an accepted length(between 8 and 16).

Nice! works as expected! We can also check by querying the nameOf using the address of Alice.

Great! we get the Alice'snick (hex-encoded) and amount used for reserve the nick.

That's all for today, we followed the first two tutorials of the
Substrate Developer Hub and make our first interactions with the framework :)

As always, I write this as a learning journal and any feedback is welcome 🙌. In the next post I will try to write a simple pallet and integrate with our current chain, stay tune 😃

Thanks!

Basic crud with rust using tide - Adding OAuth

Javier Viola — Mon, 19 Jul 2021 10:24:06 +0000

Hi there! welcome back, in the last post of this serie we made a final refactor and completed the process of ci/cd but I found a couple of bonus to add that could be useful. In this first bonus post I will be add OAuth to our app to allow users to login and manage their dinos.

Until now we are not tracking the user that create a dino, so everyone can edit or delete dinos despite of if they created or not. Now we can introduce the user concept and those dinos created by an user can only be updated/deleted by that user, we will still supporting create dinos without been logged and those will have the same behavior as they have now.

So, our roadmap for this note will be :

Implement OAuth, so the visitors can authenticate with a provider ( e.g google, github, etc )
Track the user that create the dino, if we have one.
Add an authorization mechanism for the update and delete operations.

Implement OAuth

We will be using google as OAuth provider, so before start we need to get your credentials ( here is the Setting up OAuth 2.0 documentation ).

Great, now that we had the credentials we can continue with the implementation. We will using this two examples as inspiration for our implementation tide-tera-example and tide-google-oauth-example.

Also, @jmn was the one to give me the idea of adding this OAuth bonus to this serie, thanks 🙌 🙌!

Let's started, we need to add the deps we will be using, first we will add oauth2 but we will try the last alpha version and with reqwest to use with async/await.

oauth2 = { version = "4.0.0-alpha.3", features = ["reqwest"], default-features = false  }

Move on and create the basic scaffolding, first we need to create the auth.rs file inside the controllers directory and put the basic skeleton

// controllers/auth.rs
use super::*;

use tide::{Request, Result};

pub async fn auth_google(req: Request<State>) -> Result {
    unimplemented!();
}

pub async fn auth_google_authorized(req: Request<State>) -> Result {
    unimplemented!();
}

pub async fn logout(req: Request<State>) -> Result {
    unimplemented!();
}

So, we will be handle three routes:

/auth/google will start the process and redirect the user to authorize our app.
/auth/google/authorized will handle the callback from the provider ( google in this case ), get the user info and create the session.
/logout will destroy the session.

Wait! session you say... Yes, we will use cookie based sessions in this example, so we need to add the Session middleware to our server.

// main.rs

async fn server(db_pool: PgPool) -> Server<State> {
 (...)
    app.with(tide::sessions::SessionMiddleware::new(
        tide::sessions::MemoryStore::new(),
        std::env::var("TIDE_SECRET")
            .expect("Please provide a TIDE_SECRET value of at least 32 bytes")
            .as_bytes(),
    ));

To keep things simple we will use the builtin MemoryStore but it's recommended to use one of the others stores in production.

Great! let's add also the routes in our main.rs


    // auth
    app.at("/auth/google")
        .get(auth::login)
        .at( "/authorized").get(auth::login_authorized);

    app.at("/logout").get(auth::logout);

Nice! so, now we had a bunch of env vars to add, remember to add those to our .env file.

We had all the structure in place, now we need to actually implement the OAuth client, let's add a helper function to create the basic client

fn make_oauth_google_client() -> tide::Result<BasicClient> {
    let client  =  BasicClient::new(
    ClientId::new(std::env::var("OAUTH_GOOGLE_CLIENT_ID").expect("missing env var OAUTH_GOOGLE_CLIENT_ID")),
Some(ClientSecret::new(std::env::var("OAUTH_GOOGLE_CLIENT_SECRET").expect("missing env var OAUTH_GOOGLE_CLIENT_SECRET"))),
    AuthUrl::new(AUTH_URL.to_string())?,Some(TokenUrl::new(TOKEN_URL.to_string())?),
    )
    .set_redirect_url(RedirectUrl::new(std::env::var("OAUTH_GOOGLE_REDIRECT_URL").expect("missing env var OAUTH_GOOGLE_REDIRECT_URL"))?);

    Ok(client)
}

and store in our State

#[derive(Clone, Debug)]
pub struct State {
    db_pool: PgPool,
    tera: Tera,
    oauth_google_client: BasicClient
}

(...)

    let oauth_google_client = make_oauth_google_client().unwrap();

    let state = State { db_pool, tera, oauth_google_client };

    let mut app = tide::with_state(state);

Nice! we can move on and work in the auth logic.

First, we need to handle the get request that start the OAuth flow in our auth_google fn. We are getting the client from the state and adding the scopes we want to use. With the goal of keep the things simple we will only request the profile since we will use the firstName and the id only.

The rest of the code have the email commented in case you also want to use.

pub async fn auth_google(req: Request<State>) -> Result {
    let client  = &req.state().oauth_google_client;
    let (auth_url, _csrf_token) = client
    .authorize_url(CsrfToken::new_random)
    // Set the desired scopes.
    // .add_scope(Scope::new(AUTH_GOOGLE_SCOPE_EMAIL.to_string()))
    .add_scope(Scope::new(AUTH_GOOGLE_SCOPE_PROFILE.to_string()))
    .url();

    Ok(Redirect::see_other(auth_url).into())
}

The last line redirect the user to the google page to ask the user if grant the request permissions/data to our app.

After accept the user will be redirected to our callback fn, so now let's complete the flow to get the user info.

#[derive(Debug, Deserialize)]
struct AuthRequestQuery {
    code: String,
    state: String,
    scope: String,
}

#[derive(Debug, Deserialize)]
struct UserInfoResponse {
    // email: String,
    id: String,
    given_name: String
}
(...)

pub async fn auth_google_authorized(mut req: Request<State>) -> Result {
    let client  = &req.state().oauth_google_client;
    let query: AuthRequestQuery = req.query()?;
    let token_result = client
        .exchange_code(AuthorizationCode::new(query.code))
        .request_async(async_http_client)
        .await;

    let token_result = match token_result {
        Ok(token) => token,
        Err(_) => return Err(tide::Error::from_str(401, "error"))
    };

    let userinfo: UserInfoResponse = surf::get("https://www.googleapis.com/oauth2/v2/userinfo")
    .header(
        http::headers::AUTHORIZATION,
        format!("Bearer {}", token_result.access_token().secret()),
    )
    .recv_json()
    .await?;

    let session = req.session_mut();
    session.insert("user_name", userinfo.given_name)?;
    session.insert("user_id", userinfo.id)?;

    Ok(Redirect::new("/").into())

Again, we are first getting the client from the store to exchange the auth code that we extract from the query string to the AuthRequestQuery struct.
Then, with the code we request the userInfo and deserialize the response into the UserInfoResponse struct. In the last lines we are storing the user_id and user_name into the session and redirect the logged in user to the home again.

So, let's add the link to log in and test this flow...

Whoops... the flow works but the browser is not sending the right cookie.

After checking this issue, I found this so answer that point me to check the SameSite policy. And set the policy to Lax make the flow works :-)

    app.with(tide::sessions::SessionMiddleware::new(
        tide::sessions::MemoryStore::new(),
        std::env::var("TIDE_SECRET")
            .expect("Please provide a TIDE_SECRET value of at least 32 bytes")
            .as_bytes(),
        ).with_same_site_policy(SameSite::Lax)
    );

Awesome!!! We just need to implement the logout and we will finish the first item of our goals.

pub async fn logout(mut req: Request<State>) -> Result {
    let session = req.session_mut();
    session.destroy();

    Ok(Redirect::new("/").into())
}

Nice, this will handle the logout and redirect the user to home again.

Save the user, if there is one

The next item in our list is to track the user in the database, for this task we need another field in our db that could be null or an string that represente the user_id.

After adding the field in our dinos table, we need to update our Dino struct.

[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Dino {
    id: Uuid,
    name: String,
    weight: i32,
    diet: String,
    user_id: Option<String>
}

so, user_id is an Option that can hold an String. Now we need to add an extra logic to add the user_id in our controller

pub async fn create(mut req: Request<State>) -> tide::Result {
    let mut dino: Dino = req.body_json().await?;
    let db_pool = req.state().db_pool.clone();

    let session = req.session();
    match session.get("user_id") {
        Some(id) => dino.user_id = Some(id),
        None => dino.user_id = None
    };

    let row = handlers::dino::create(dino, &db_pool).await?;

    let mut res = Response::new(201);
    res.set_body(Body::from_json(&row)?);
    Ok(res)
}

And update the handlerfns to use the new field

pub async fn create(dino: Dino, db_pool: &PgPool) -> tide::Result<Dino> {
    let row: Dino = query_as!(
        Dino,
        r#"
        INSERT INTO dinos (id, name, weight, diet, user_id) VALUES
        ($1, $2, $3, $4, $5) returning id as "id!", name, weight, diet, user_id
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet,
        dino.user_id
    )
    .fetch_one(db_pool)
    .await
    .map_err(|e| Error::new(409, e))?;

    Ok(row)
}

(...)

Now you can login, create a new dino and see that the new row has the user_id set. Also, if you create a new dino without been logged in this column should be null.

Nice! second goal done, we are tracking the id of the users when they create a new dino.

Authorize update and delete operations

The last item in our list is restrict the update and delete operations. If a dino was created by a logged in user only this user is authorized to delete or edit this dino. We will add this auth rule in two different places.

First in the ui, the edit and delete options should only be available for public dinos or the ones that the user created.

We can archive this with some logic in the tera template

                {% if dino.user_id %}
                    {%if user_id != "" and dino.user_id == user_id %}
                        <td><a href="/dinos/{{dino.id}}/edit"> Edit </a></td>
                        <td><a class="delete" data-id="{{dino.id}}"href="#"> Delete </a></td>
                    {% else %}
                        <td></td>
                        <td></td>
                    {% endif %}
                {% else %}
                    <td><a href="/dinos/{{dino.id}}/edit"> Edit </a></td>
                    <td><a class="delete" data-id="{{dino.id}}"href="#"> Delete </a></td>
                {% endif %}

Nice!! we are half way, we just restrict the ui but we also need to check this restriction in the controller.

//controllers/dino.rs

(...)
    // auth operation
    let session = req.session();
    let user_id: String = session.get("user_id").unwrap_or("".to_string());
    let row = handlers::dino::get(id, &db_pool).await?;
    if let Some(dino) = row {
        if dino.user_id.is_some() && dino.user_id.unwrap() != user_id {
            // 401
            return Ok(Response::new(401));
        }
    }
(...)

We are checking that the user_id ( if is set ) is the same of the session, and if not we just return a 401 Unauthorized.

Nice! we have to add some tests now to check if this works as expected

    #[async_std::test]
    async fn updatet_dino_create_by_another_user_should_reject_with_401() -> tide::Result<()> {
        dotenv::dotenv().ok();

        let mut dino = Dino {
            id: Uuid::new_v4(),
            name: String::from("test_update"),
            weight: 500,
            diet: String::from("carnivorous"),
            user_id: Some(String::from("123"))
        };

        let db_pool = make_db_pool(&DB_URL).await;

        // create the dino for update
        query!(
            r#"
            INSERT INTO dinos (id, name, weight, diet, user_id) VALUES
            ($1, $2, $3, $4, $5) returning id
            "#,
            dino.id,
            dino.name,
            dino.weight,
            dino.diet,
            dino.user_id
        )
        .fetch_one(&db_pool)
        .await?;

        // change the dino
        dino.name = String::from("updated from test");

        // start the server
        let app = server(db_pool).await;

        let res = surf::Client::with_http_client(app)
            .put(format!("https://example.com/dinos/{}", &dino.id))
            .body(serde_json::to_string(&dino)?)
            .await?;

        assert_eq!(401, res.status());

        Ok(())
    }

    #[async_std::test]
    async fn delete_dino_create_by_another_user_should_reject_with_401() -> tide::Result<()> {
        dotenv::dotenv().ok();

        let dino = Dino {
            id: Uuid::new_v4(),
            name: String::from("test_delete"),
            weight: 500,
            diet: String::from("carnivorous"),
            user_id: Some(String::from("123"))
        };

        let db_pool = make_db_pool(&DB_URL).await;

        // create the dino for delete
        query!(
            r#"
            INSERT INTO dinos (id, name, weight, diet, user_id) VALUES
            ($1, $2, $3, $4, $5) returning id
            "#,
            dino.id,
            dino.name,
            dino.weight,
            dino.diet,
            dino.user_id
        )
        .fetch_one(&db_pool)
        .await?;

        // start the server
        let app = server(db_pool).await;

        let res = surf::Client::with_http_client(app)
            .delete(format!("https://example.com/dinos/{}", &dino.id))
            .await?;

        assert_eq!(401, res.status());

        Ok(())
    }

Nice, now we can run those test :)

cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.31s
     Running target/debug/deps/tide_basic_crud-b16dbe7e8764d4d3

running 12 tests
test tests::clear ... ok
test tests::create_dino_with_existing_key ... ok
test tests::delete_dino_create_by_another_user_should_reject_with_401 ... ok
test tests::delete_dino ... ok
test tests::create_dino ... ok
test tests::get_dino_non_existing_key ... ok
test tests::get_dino ... ok
test tests::delete_dino_non_existing_key ... ok
test tests::list_dinos ... ok
test tests::updatet_dino_create_by_another_user_should_reject_with_401 ... ok
test tests::update_dino ... ok
test tests::updatet_dino_non_existing_key ... ok

test result: ok. 12 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Awesome!! we just finished the third item in our list.

That's all for today... first bonus of this serie, we just implemented OAuth ( with google as provider ) and now users can track his dinos :-), you can check the complete code in the PR.
I think there are still room to improve ( like adding a mechanism to authorize api calls ) but we can leave for the next bonus post.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

Thanks!

Basic CRUD with rust using tide - Refactor and complete CI/CD

Javier Viola — Mon, 19 Jul 2021 09:17:22 +0000

Welcome back! this will be the last post of this serie, making the final refactor to our application and tiding the loose ends to complete the ci/cd setup.

Refactor

Let's start to tackle the issue prompted in the las post

but we are starting to have some duplicate code between the endpoints > for the rest api and the endpoint for some pages.

Since we added new endpoints, for each page, we dup some code to get the information from the database. We can resolve this decoupling the that logic from the endpoints and creating a new reusable layer.

The final goal is two have two separate layers, with a clear separation of roles and responsibilities between each one. For the purpose of this post we are going to use two layers, one for controllers and one for the business or domain logic.

So, let's start with the controller layer creating a new directory inside src and two controller files. One for the views ( or pages ) and the other one for the api.

mkdir controllers && cd controllers
touch {mod.rs,dino.rs,views.rs}

Now we can move the endpoint function to each one and declare the modules in our mod file.

// dino.rs

pub async fn create(mut req: Request<State>) -> tide::Result {
    todo!();
}

pub async fn list(req: tide::Request<State>) -> tide::Result {
    todo!();
}

pub async fn get(req: tide::Request<State>) -> tide::Result {
    todo!();
}

pub async fn update(mut req: tide::Request<State>) -> tide::Result {
    todo!();
}

pub async fn delete(req: tide::Request<State>) -> tide::Result {
    todo!();
}

Great!, the idea behind this refactor is decoupling the endpoint logic to the one used to interact to the database. So, this functions will receive the request and call the other layer ( let's call handler ) to make crud operations.

Now we need to create the new handler layer and expose the api to be used by the controllers. So again inside our src directory.

mkdir handlers && cd handlers
touch {mod.rs,dino.rs}

// handlers/dino.rs
pub async fn create(dino: Dino, db_pool: PgPool) -> tide::Result<Dino> {
    todo!();
}
pub async fn list(db_pool: PgPool) -> tide::Result<Vec<Dino>> {
    todo!();
}

pub async fn get(id: Uuid, db_pool: PgPool) -> tide::Result<Option<Dino>> {
    todo!();
}
pub async fn delete(id: Uuid, db_pool: PgPool) -> tide::Result<Option<()>> {
    todo!();
}

pub async fn update(id: Uuid, dino: Dino, db_pool: PgPool) -> tide::Result<Option<Dino>> {
    todo!();
}

Each function will receive as argument an instance of the database pool and the needed arguments for the operation ( e.g uuid or dino ).

Now we can start filling the todo!() and implement the actual logic, here is an example of the create operation but you can check the PR to see the full code.

// controllers/dino.rs

use crate::handlers;

pub async fn create(mut req: Request<State>) -> tide::Result {
    let dino: Dino = req.body_json().await?;
    let db_pool = req.state().db_pool.clone();

    let row = handlers::dino::create(dino, db_pool).await?;

    let mut res = Response::new(201);
    res.set_body(Body::from_json(&row)?);
    Ok(res)
}

pub async fn create(dino: Dino, db_pool: PgPool) -> tide::Result<Dino> {
    let row: Dino = query_as!(
        Dino,
        r#"
        INSERT INTO dinos (id, name, weight, diet) VALUES
        ($1, $2, $3, $4) returning id, name, weight, diet
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet
    )
    .fetch_one(&db_pool)
    .await
    .map_err(|e| Error::new(409, e))?;

    Ok(row)
}

Great! After complete the implementation of the others functions we can move on and complete our view controller.

We have 3 views ( index, new and edit )

// controllers/views.rs

pub async fn index(req: Request<State>) -> tide::Result {
    let tera = req.state().tera.clone();
    let db_pool = req.state().db_pool.clone();
    let rows = handlers::dino::list(db_pool).await?;

    tera.render_response(
        "index.html",
        &context! {
           "title" => String::from("Tide basic CRUD"),
           "dinos" => rows
        },
    )
}

pub async fn new(req: Request<State>) -> tide::Result {
    let tera = req.state().tera.clone();

    tera.render_response(
        "form.html",
        &context! {
            "title" => String::from("Create new dino")
        },
    )
}

pub async fn edit(req: Request<State>) -> tide::Result {
    let tera = req.state().tera.clone();
    let db_pool = req.state().db_pool.clone();
    let id: Uuid = Uuid::parse_str(req.param("id")?).unwrap();
    let row = handlers::dino::get(id, db_pool).await?;

    let res = match row {
        None => Response::new(404),
        Some(row) => {
            let mut r = Response::new(200);
            let b = tera.render_body(
                "form.html",
                &context! {
                    "title" => String::from("Edit dino"),
                    "dino" => row
                },
            )?;
            r.set_body(b);
            r
        }
    };

    Ok(res)
}

Awesome! each one now call the handler to retrieve the dinos information. We are almost there, we need now to clean our main file and add tide the routes to the controllers. We can start by removing all the restEntity logic in main and just tide the routes to the controller functions in our server fn

    // views
    app.at("/").get(views::index);
    app.at("/dinos/new").get(views::new);
    app.at("/dinos/:id/edit").get(views::edit);

    // api
    app.at("/dinos").get(dino::list).post(dino::create);

    app.at("dinos/:id")
        .get(dino::get)
        .put(dino::update)
        .delete(dino::delete);

    app.at("/public")
        .serve_dir("./public/")
        .expect("Invalid static file directory");

    app

Great! so, we can now run the tests

cargo test

running 10 tests
test tests::clear ... ok
test tests::delete_dino ... ok
test tests::create_dino_with_existing_key ... ok
test tests::delete_dino_non_existing_key ... ok
test tests::create_dino ... ok
test tests::get_dino ... ok
test tests::update_dino ... ok
test tests::get_dino_non_existing_key ... ok
test tests::list_dinos ... ok
test tests::updatet_dino_non_existing_key ... ok

test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Nice! we almost finish the refactor, we still have some code to clean and remove unused imports.

CI/CD

Next, we need to finish the pipeline for CI/CD, we are already running the test in GH Actions so this part is cover but we want to setup the cd part for deploy our app in each commit to main.

Updating sqlx

First let's start to update sqlx to enable offline mode and allow us to build our app without connecting to the database.

// Cargo.toml
sqlx = { version = "0.4.2", features = ["runtime-async-std-rustls", "offline", "macros", "chrono", "json", "postgres", "uuid"] }

We need to add the offline feature and change runtime-async-std for one of the supported ones in the new version ( in our case runtime-async-std-rustls ).

Also, we need to make a couple of changes in our code to work with the new version:

Pool::new is now replaced by Pool::connect

pub async fn make_db_pool(db_url: &str) -> PgPool {
    Pool::connect(db_url).await.unwrap()
}

We need to use as "id!" in the query for inserting a Dino to prevent the inferred field type (Option)

// use as "id!" here to prevent sqlx use the inferred ( nulleable ) type
// since we know that id should not be null
// see : https://github.com/launchbadge/sqlx/blob/master/src/macros.rs#L482
pub async fn create(dino: Dino, db_pool: &PgPool) -> tide::Result<Dino> {
    let row: Dino = query_as!(
        Dino,
        r#"
        INSERT INTO dinos (id, name, weight, diet) VALUES
        ($1, $2, $3, $4) returning id as "id!", name, weight, diet
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet
    )
    .fetch_one(db_pool)
    .await
    .map_err(|e| Error::new(409, e))?;

    Ok(row)
}

Great! now we can install the sqlx-cli and generate the needed file to build without need a db connection.

cargo install sqlx-cli
cargo sqlx prepare
(...)
query data written to `sqlx-data.json` in the current directory; please check this into version control

Nice! we can now build our code with out a db connection :)

Selecting a provider

For deploy our app we will use qovery, they offer container as a service and his tag line are The simplest way to deploy your full-stack apps. Also, they have a community plan so let's try and see how it's go.

For deploy our app we need to files:

Dockerfile : for build and run our application
.qovery.yml : fir describe the needed infra of our project.

For the Dockerfile we will use a template from cargo chef enabling multi-stage builds.

You can check the complete files in the repo .

Now, we can see the deployment in action in the qovery console

And each commit will trigger a new build of our app, that is now live :-)

That's all for today and for this series, I think there are still room to improve but we can leave that for the future since we have now a minimal working CRUD with both api and front-end and the CI/CD in place :-)

In the future posts I will be exploring web-sockets with tide.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

Thanks!

Basic CRUD with rust using tide - front-end with tera

Javier Viola — Mon, 19 Jul 2021 09:12:58 +0000

Welcome back! this time our goal is adding the front-end to interact with our api and allow the users to list, create, update and delete dinos.

Meet Tera

Tera is a templating engine, inspired by Jinja2 and Django. There are other options like handlerbars and askama, but in this case I prefer to use tera because I'm familiarized with the syntax.

Adding the rendering machinery

First we need to add the deps we need, in this case we will using tera and tide-tera, the last one exposes an extension trait that adds two functions tera:

render_response
render_body

[dependencies]
...
tera = "1.5.0"
tide-tera = "0.2.2"

Then we need to create a directory to store our templates, in our case at top level of the app directory ( next to the src directory )

mkdir templates

Let's now add our basic templates, we will use a base layout and extend it for each page.

// layout.html

<!DOCTYPE html>
<html lang="en">

<head>
  <title>{% block title %}{% endblock title %}</title>
  <meta charset="utf-8">
  <meta name="description" content="Tide basic CRUD">
  <meta name="author" content="">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta property="og:title" content="Tide basic CRUD" />

  {% block additional_head %}
  {% endblock additional_head %}
</head>

<body>
  {% block content %}
  {% endblock content %}
</body>

</html>

And now our index page

//index.html

{% extends "layout.html" %}

{% block title %}
 {{title}}
{% endblock title %}

{% block content %}
<h2> Hi there!</div>
{% endblock content %}

So, we just created out first page ( at least the template ). If you are not familiarized with the tera syntax you can check the docs, but in a nutshell:

{{ and }} for expressions
{% or {%- and %} or -%} for statements
{# and #} for comments

And block / endblock allow to extends.

Great! we need now to go back to our tide server and implement the serve ( and rendering ) logic.

First we need to add the declarations for the new deps

...
use tera::Tera;
use tide_tera::prelude::*;

And update our State struct to hold an instance of tera.

#[derive(Clone, Debug)]
struct State {
    db_pool: PgPool,
    tera: Tera
}

Then we need to modify our server fn to add the instantiation of tera and modify the endpoint to render the index.html template

async fn server(db_pool: PgPool) -> Server<State> {
    let mut tera = Tera::new("templates/**/*").expect("Error parsing templates directory");
    tera.autoescape_on(vec!["html"]);

    let state = State { db_pool, tera };

    let mut app = tide::with_state(state);

    // index page
    app.at("/").get( |req: tide::Request<State> | async move {
        let tera = req.state().tera.clone();
        tera.render_response("index.html", &context! { "title" => String::from("Tide basic CRUD") })
    } );

Great! we can now run the server and check our first page!

Awesome! It's doesn't do much but the machinery is in place now :-)

Let's start working on the index, we want to list the dinos we have and allow users to create, update and delete.

List our dinos

The index of our app will produce a list of the dinos stored in our database, so the first thing we need to do is get that list to then inject in the context of our template

    // index page
    app.at("/").get( |req: tide::Request<State> | async move {
        let tera = req.state().tera.clone();
        let db_pool = req.state().db_pool.clone();
        let rows = query_as!(
            Dino,
            r#"
            SELECT id, name, weight, diet from dinos
            "#
        )
        .fetch_all(&db_pool)
        .await?;
        tera.render_response("index.html", &context! {
            "title" => String::from("Tide basic CRUD"),
            "dinos" => rows
         })
    } );

And in our template

{% block content %}
{% if dinos %}
    <table class="u-full-width">
        <thead>
            <tr>
                <th>Id</th>
                <th>Name</th>
                <th>Weight</th>
                <th>Diet</th>
                <th></th>
                <th></th>
            </tr>
        </thead>
        <tbody>
            {%for dino in dinos%}
            <tr>
                <td>{{dino.id}}</td>
                <td>{{dino.name}}</td>
                <td>{{dino.weight}}</td>
                <td>{{dino.diet}}</td>
                <td><a href="/dinos/{{dino.id}}/edit"> Edit </a></td>
                <td><a href="/dinos/{{dino.id}}/delete"> Delete </a></td>
            </tr>
            {% endfor %}
        </tbody>
    </table>
{% endif %}

<a href="/dinos/new">Create new Dino</a>
{% endblock content %}

Awesome! but doesn't looks good yet, let's add some styles to make it looks good.

The front-end of this app is inspired on this example app that use skeleton css and we will use that framework too. So we will need to serve some static files.

Serve static files

Tide have a handy way to serve static files, you can define the path and the directory you want to serve and those files are server statically from disk.

app.at("/public").serve_dir("./public/").expect("Invalid static file directory");

In our case we will serve the public directory, so we need to create that directory and place the static assets we want to serve there.

mkdir -p public/{js,css,images}

And update our base template to include those files

Now look much better! Let's now add the form to create a new dino.

Create and edit

Both create and edit pages will be using the same template, but in the case of edit will be pre-populated with the dino information and each action will have it's own route

/dinos/new
/dinos/{id}/edit

Let's start with the form template

{% extends "layout.html" %}

{% block content %}
<form>
  <input id="id" name="id" type="hidden" value="{% if dino %} dino.id {% endif %}">
  <div class="row">
    <div class="ten columns">
      <label for="name">Name</label>
      <input class="u-full-width" id="name" name="name" type="text" placeholder="T-Rex" value="{% if dino %} dino.name {% endif %}">
    </div>
  </div>
  <div class="row">
    <div class="ten columns">
      <label for="weight">Weight</label>
      <input class="u-full-width" name="weight" id="weight" type="text" placeholder="" value="{% if dino %} dino.weight {% endif %}">
    </div>
  </div>
  <div class="row">
    <div class="ten columns">
      <label for="diet">Diet</label>
      <input class="u-full-width" name="diet" id="diet" type="text" placeholder="" value="{% if dino %} dino.diet {% endif %}">
    </div>
  </div>

  <input class="button-primary" type="submit" value="Submit"> <a class="button" href="/">Cancel</a>
</form>
{% endblock %}

Nothing fancy, just extended our base template and add some inputs with the value pre-populated only if the dino info is present in the context. We could use some macros to generate the fields but works ok for now.

And in the backend we need to add the two endpoints

    // new dino
    app.at("/dinos/new").get( |req: tide::Request<State> | async move {
        let tera = req.state().tera.clone();

        tera.render_response("form.html", &context! {
            "title" => String::from("Create new dino")
         })
    } );
    // edit dino
    app.at("/dinos/:id/edit").get( |req: tide::Request<State> | async move {
        let tera = req.state().tera.clone();
        let db_pool = req.state().db_pool.clone();
        let id: Uuid = Uuid::parse_str(req.param("id")?).unwrap();
        let row = query_as!(
            Dino,
            r#"
            SELECT  id, name, weight, diet from dinos
            WHERE id = $1
            "#,
            id
        )
        .fetch_optional(&db_pool)
        .await?;

        let res = match row {
            None => Response::new(404),
            Some(row) => {
                let mut r = Response::new(200);
                let b = tera.render_body("form.html", &context! {
                        "title" => String::from("Edit dino"),
                        "dino" => row
                    })?;
                r.set_body(b);
                r
            }
        };

        Ok(res)
    } );

Nice!, but we are starting to have some duplicate code between the endpoints for the rest api and the endpoint for this pages. For the moment let's focus in the functionality and we will refactor this in the next post.

Now we need a way to consume our api for persists the dinos, in this case we will create a minimal api client with javascript fetch since we are focused now in how to integrate tera and tide and not in the front-end.
You can check the minimal client api in the PR.

Now we can start adding dinos :)

That's all for today, we have a minimal working CRUD with both api and front-end. In the next post we will be refactoring some of the dup code and adding a new abstraction layer.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

Thanks!

Basic CRUD with rust using tide - tests improvements

Javier Viola — Wed, 14 Jul 2021 14:41:24 +0000

Hi all again, in the last post we refactor the code to persist the information in a relational database, postgresql in our case.

Let's start where we left last time (ci bonus) and tie those loose ends in the ci.

Improving tests

First, one thing to improve in our tests is start using surf as client since is the client recommended by http-rs.

So, let's add surf as dev-dependency

[dev-dependencies]
surf = "2.1.0"

And then in our code, let's use surf as client en each test

(...)
    let res = surf::Client::with_http_client(app)
        .get("https://example.com/dinos")
        .await?;
    assert_eq!(200, res.status());

(...)

    let mut res = surf::Client::with_http_client(app)
        .post("https://example.com/dinos")
        .body(serde_json::to_string(&dino)?)
        .await?;

Great, let's run the tests...

❯ cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.20s
     Running target/debug/deps/tide_basic_crud-1a926f88350611fd

running 5 tests
test tests::list_dinos ... ok
test tests::create_dino ... ok
test tests::delete_dino ... ok
test tests::get_dino ... ok
test tests::update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Awesome! But at this point we are only asserting the status code. Let's check now also the returned payload, for that we will use the crate assert-json-diff that add two macros:

assert_json_eq : macro used to compare two JSON values for an exact match.
assert_json_include : macro used to compare two JSON values for an inclusive match.

For example, add this lines to the get_dino test

let d: Dino = res.body_json().await?;
assert_json_eq!(dino, d);

Let's run the tests again ones we add the json asserts...

❯ cargo test
    Finished test [unoptimized + debuginfo] target(s) in 1.44s
     Running target/debug/deps/tide_basic_crud-1a926f88350611fd

running 5 tests
test tests::list_dinos ... ok
test tests::create_dino ... ok
test tests::delete_dino ... ok
test tests::get_dino ... ok
test tests::update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Great! now we are also validating the returned payload.

We have a couple more of TODOs before finish the improvements. First, we need to clear the dinos table before run each test since we always want to create an isolated test case. To accomplish that, let's create a module (mod) in our main file for the tests and add a helper function to clear the dinos table.

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

    async fn clear_dinos() -> Result<(),Box<dyn std::error::Error>> {
        let db_pool = make_db_pool(&DB_URL).await;

        sqlx::query("DELETE FROM dinos").execute(&db_pool).await?;
        Ok(())
    }
(...)

And in each test we need to run clear_dinos before make any change/request.

    #[async_std::test]
    async fn create_dino() -> tide::Result<()> {
        dotenv::dotenv().ok();
        clear_dinos().await.expect("Failed to clear the dinos table");
(...)

Great, so one more task to go. We need to set the ci (gh actions) to run the tests. For that we set a new block in ci.yml to run those tests

    - name: Run test
      run: cargo test
      env:
          DATABASE_URL: postgres://postgres:postgres@localhost:${{ job.services.postgres.ports[5432] }}/tide

And we are ready to create a new PR with this test improvements and check if all the steps works as expected

Nice! we now have the ci configured.

Beyond the happy path

Until now our test only check the happy path and we are not testing errors. Let's add some basic test cases for cover those

Create a duplicate dino with an existing key, should return 409

We need to handler the insert error and return the appropriated error since using the ? here will bubble the error to the caller.

        let row : Dino =  match query_as!(
            Dino,
            r#"
            INSERT INTO dinos (id, name, weight, diet) VALUES
            ($1, $2, $3, $4) returning id, name, weight, diet
            "#,
            dino.id,
            dino.name,
            dino.weight,
            dino.diet
        )
        .fetch_one(&db_pool)
        .await {
            Ok( r) => r,
            Err( e ) => {
                // TODO: we may want to cast the error here.
                let err = Error::new(409,e);
                return Err(err);
            }
        };

(...)

Get/Delete/Update dino with a non existing key, should return 404

In this cases we only need to send an invalid key ( e.g. a new one and should works )

        let  res = surf::Client::with_http_client(app)
            .delete(format!("https://example.com/dinos/{}", &Uuid::new_v4()))
            .await?;

        assert_eq!(404, res.status());

Upgrade bonus

Also, this week a new version of tide was released with a new way to start the servers

Tide v0.15.0 introduces a new way to start servers: Server::bind. This enables separating "open the socket" from "start accepting connections" which Server::listen does for you in a single call.

Let's update our code to use this new version, first the deps in cargo

[dependencies]
tide = "0.15.0"
async-std = { version = "1.7.0", features = ["attributes"] }

And in our code the main function now looks like this

#[async_std::main]
async fn main() {
    dotenv::dotenv().ok();

    tide::log::start();
    let db_url = std::env::var("DATABASE_URL").unwrap();
    let db_pool = make_db_pool(&db_url).await;

    let app = server(db_pool).await;
    let mut listener = app.bind("127.0.0.1:8080").await.expect("can't bind the port");

    for info in listener.info().iter() {
        println!("Server listening on {}", info);
    }
    listener.accept().await.unwrap();
}

That's all for today, I was planned to add the implementation of tera as render engine but will cover that in the next post and keep this one focused in tests.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

Thanks!

Basic CRUD with rust using tide - move to db

Javier Viola — Mon, 12 Jul 2021 14:23:43 +0000

From in memory to db

In the last post we refactored the api to be more ergonomic but we still used the in memory store ( a.k.a HashMap ). In this note will move the information to a persistent store ( a postgresql database ).

We will use the awesome sqlx crate to interact with our db and check our queries in compile time.

With this goal in mind, let's start changing the code. First let's add the deps we will need.

sqlx = { version = "0.3", features = ["runtime-async-std", "macros", "chrono", "json", "postgres", "uuid"] }
chrono = "0.4"
dotenv = "0.15"
uuid = { version = "0.8", features = ["v4", "serde"] }

And replace those in main.rs

- use async_std::sync::RwLock;
+ use dotenv;
+ use uuid::Uuid;
use serde::{Deserialize, Serialize};
- use std::collections::hash_map::{Entry, HashMap};
- use std::sync::Arc;
+ use sqlx::Pool;
+ use sqlx::{query, query_as, PgPool};
use tide::{Body, Request, Response, Server};

To recap, we will use

dotenv to load env vars from .env file.
Uuid as a type for the dinos id.
sqlx:: we will create a Pool ( a PgPool ) to handle the db connection and query / query_as are macros used to make queries to the database.

But, we didn't talk about the db yet. We will use postgresql and you can download or run inside docker.

I prefer the second options so, let's create a postgresql container with a persistent volume for the data.

I assume in this part that you already have docker installed

$ mkdir ~/pg-rust-data
$ docker run --name -p -p 5432:5432 rust-postgres -e POSTGRES_PASSWORD=postgres -v ~/pg-rust-data:/var/lib/postgresql/data  -d postgres

With this commands we have a container running postgres exposing the port 5432 and mounting a persistent volume for the data.

Now we can connect ( using your favorite client ) and create the database and the schema.

CREATE database rust_crud;

-- change connection to the created database e.g: \c rust_crud;

CREATE TABLE dinos (
    id uuid NOT NULL,
    name text,
    weight integer,
    diet text
);


ALTER TABLE dinos OWNER TO postgres;

ALTER TABLE ONLY dinos
    ADD CONSTRAINT dinos_pkey PRIMARY KEY (id);

So now, let's move back to rust :-)

Let's now change our State to hold the connection pool instead of the memory store

struct State {
    db_pool: PgPool,
}

And create a new fn to create the connection pool

pub async fn make_db_pool() -> PgPool {
    let db_url = std::env::var("DATABASE_URL").unwrap();
    Pool::new(&db_url).await.unwrap()
}

And now our server function take a PgPool as argument and in main we need to create the pool and passing to create the app.

#[async_std::main]
async fn main() {
    dotenv::dotenv().ok();

    tide::log::start();
    let db_pool = make_db_pool().await;
    let app = server(db_pool).await;

    app.listen("127.0.0.1:8080").await.unwrap();
}

Good!, with this changes all our entity endpoints can access the db through the db pool in the state, now we need to update the code to interact with the database in the routes.

In our handlers we had something like this to access the shared HashMap that holds the information.

        let mut dinos = req.state().dinos.write().await;

Now we can replace with this line to get a db connection from the pool.

let db_pool = req.state().db_pool.clone();

And use the query_as! and query! macros to run sql statements, for example our create endpoint now looks like this

    async fn create(mut req: Request<State>) -> tide::Result {
        let dino: Dino = req.body_json().await?;
        let db_pool = req.state().db_pool.clone();
        let row = query_as!(
            Dino,
            r#"
            INSERT INTO dinos (id, name, weight, diet) VALUES
            ($1, $2, $3, $4) returning id, name, weight, diet
            "#,
            dino.id,
            dino.name,
            dino.weight,
            dino.diet
        )
        .fetch_one(&db_pool)
        .await?;

        let mut res = Response::new(201);
        res.set_body(Body::from_json(&row)?);
        Ok(res)
    }

The query_as! macro allow us to run the query and return a struct from the defined type ( in this case Dino ).

Now we need to change also the test to ensure that our code works as expected.

#[async_std::test]
async fn create_dino() -> tide::Result<()> {
    dotenv::dotenv().ok();
    use tide::http::{Method, Request, Response, Url};

    let dino = Dino {
        id: Uuid::new_v4(),
        name: String::from("test"),
        weight: 50,
        diet: String::from("carnivorous"),
    };

    let db_pool = make_db_pool().await;
    let app = server(db_pool).await;

    let url = Url::parse("https://example.com/dinos").unwrap();
    let mut req = Request::new(Method::Post, url);
    req.set_body(serde_json::to_string(&dino)?);
    let res: Response = app.respond(req).await?;
    assert_eq!(201, res.status());
    Ok(())
}

We need to add the db_pool creation and pass to the app like we do in main and also add an id( uuid ) to the Dino Struct. Let's run the test to verify...

$ cargo test --package tide-basic-crud --bin tide-basic-crud -- create_dino --exact --nocapture

   Finished test [unoptimized + debuginfo] target(s) in 10.71s
     Running target/debug/deps/tide_basic_crud-227c59d203ec76fd

running 1 test
test create_dino ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 4 filtered out

Nice! test passed, now we can go ahead and change the other endpoints/tests.

    async fn list(req: tide::Request<State>) -> tide::Result {
        let db_pool = req.state().db_pool.clone();
        let rows = query_as!(
            Dino,
            r#"
            SELECT id, name, weight, diet from dinos
            "#
        )
        .fetch_all(&db_pool)
        .await?;
        let mut res = Response::new(200);
        res.set_body(Body::from_json(&rows)?);
        Ok(res)
    }

    async fn get(req: tide::Request<State>) -> tide::Result {
        let db_pool = req.state().db_pool.clone();
        let id: Uuid = Uuid::parse_str(req.param("id")?).unwrap();
        let row = query_as!(
            Dino,
            r#"
            SELECT  id, name, weight, diet from dinos
            WHERE id = $1
            "#,
            id
        )
        .fetch_optional(&db_pool)
        .await?;

        let res = match row {
            None => Response::new(404),
            Some(row) => {
                let mut r = Response::new(200);
                r.set_body(Body::from_json(&row)?);
                r
            }
        };

        Ok(res)
    }

    async fn update(mut req: tide::Request<State>) -> tide::Result {
        let dino: Dino = req.body_json().await?;
        let db_pool = req.state().db_pool.clone();
        let id: Uuid = Uuid::parse_str(req.param("id")?).unwrap();
        let row = query_as!(
            Dino,
            r#"
            UPDATE dinos SET name = $2, weight = $3, diet = $4
            WHERE id = $1
            returning id, name, weight, diet
            "#,
            id,
            dino.name,
            dino.weight,
            dino.diet
        )
        .fetch_optional(&db_pool)
        .await?;

        let res = match row {
            None => Response::new(404),
            Some(row) => {
                let mut r = Response::new(200);
                r.set_body(Body::from_json(&row)?);
                r
            }
        };

        Ok(res)
    }

    async fn delete(req: tide::Request<State>) -> tide::Result {
        let db_pool = req.state().db_pool.clone();
        let id: Uuid = Uuid::parse_str(req.param("id")?).unwrap();
        let row = query!(
            r#"
            delete from dinos
            WHERE id = $1
            returning id
            "#,
            id
        )
        .fetch_optional(&db_pool)
        .await?;

        let res = match row {
            None => Response::new(404),
            Some(_) => Response::new(204),
        };

        Ok(res)
    }

Couple of things to check here:

using .fetch_all with query_as! will return a Vec ( in our case )
using .fetch_optional will return an Option that we can match agains to check if the resource exist or not.

Also we need to make some changes in the test, and for now we simplify only testing the correct status code.

#[async_std::test]
async fn get_dino() -> tide::Result<()> {
    dotenv::dotenv().ok();
    use tide::http::{Method, Request, Response, Url};

    let dino = Dino {
        id: Uuid::new_v4(),
        name: String::from("test_get"),
        weight: 500,
        diet: String::from("carnivorous"),
    };

    let db_pool = make_db_pool().await;

    // create the dino for get
    query!(
        r#"
        INSERT INTO dinos (id, name, weight, diet) VALUES
        ($1, $2, $3, $4) returning id, name, weight, diet
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet
    )
    .fetch_one(&db_pool)
    .await?;

    // start the server
    let app = server(db_pool).await;

    let url = Url::parse(format!("https://example.com/dinos/{}", &dino.id).as_str()).unwrap();
    let req = Request::new(Method::Get, url);

    let res: Response = app.respond(req).await?;
    assert_eq!(200, res.status());
    Ok(())
}

#[async_std::test]
async fn update_dino() -> tide::Result<()> {
    dotenv::dotenv().ok();
    use tide::http::{Method, Request, Response, Url};

    let mut dino = Dino {
        id: Uuid::new_v4(),
        name: String::from("test_update"),
        weight: 500,
        diet: String::from("carnivorous"),
    };

    let db_pool = make_db_pool().await;

    // create the dino for update
    query!(
        r#"
        INSERT INTO dinos (id, name, weight, diet) VALUES
        ($1, $2, $3, $4) returning id, name, weight, diet
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet
    )
    .fetch_one(&db_pool)
    .await?;

    // change the dino
    dino.name = String::from("updated from test");

    // start the server
    let app = server(db_pool).await;

    let url = Url::parse(format!("https://example.com/dinos/{}", &dino.id).as_str()).unwrap();
    let mut req = Request::new(Method::Put, url);
    let dinos_as_json_string = serde_json::to_string(&dino)?;
    req.set_body(dinos_as_json_string);
    let res: Response = app.respond(req).await?;
    assert_eq!(200, res.status());
    Ok(())
}

#[async_std::test]
async fn delete_dino() -> tide::Result<()> {
    dotenv::dotenv().ok();
    use tide::http::{Method, Request, Response, Url};

    let dino = Dino {
        id: Uuid::new_v4(),
        name: String::from("test_delete"),
        weight: 500,
        diet: String::from("carnivorous"),
    };

    let db_pool = make_db_pool().await;

    // create the dino for delete
    query!(
        r#"
        INSERT INTO dinos (id, name, weight, diet) VALUES
        ($1, $2, $3, $4) returning id, name, weight, diet
        "#,
        dino.id,
        dino.name,
        dino.weight,
        dino.diet
    )
    .fetch_one(&db_pool)
    .await?;

    // start the server
    let app = server(db_pool).await;

    let url = Url::parse(format!("https://example.com/dinos/{}", &dino.id).as_str()).unwrap();
    let req = Request::new(Method::Delete, url);
    let res: Response = app.respond(req).await?;
    assert_eq!(204, res.status());
    Ok(())
}

We are creating the records before operate for update/delete but we are not spin a new database or dropping the existing test db, it's ok for now but we need to work in that area in the future notes.

ci bonus

I thought that having a ci for fmt, linting with clippy and build will be a nice to have at this point, so I add the ci.yml to run the job in github actions and I found an issue with sqlx since is trying to build and validate the queries from the macros. There is a workaround to build *decoupled/offline * but I just add a postgres container to the ci since in the future we want to run the test also there.

That's all for today, in the next iteration I will try to work in the test setup and add some front-end with tera.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

As a reference, this is the repo and the pr for db and pr for ci.

Thanks!

Basic CRUD with rust using tide - refactoring

Javier Viola — Sun, 11 Jul 2021 19:17:37 +0000

In the last post I started a basic crud using tide and we end up with a simple api that allow us to store dinosaurs information.

Starting from there, let's clean the code a little bit to be more organized. First, we had a closure in every route (let's call it endpoint from here) and will be more clear if we extract that to functions.

async fn dinos_create(mut req: Request<State>) -> tide::Result {
    let dino: Dino = req.body_json().await?;
    // let get a mut ref of our store ( hashMap )
    let mut dinos = req.state().dinos.write().await;
    dinos.insert(String::from(&dino.name), dino.clone());
    let mut res = Response::new(201);
    res.set_body(Body::from_json(&dino)?);
    Ok(res)
}

async fn dinos_list(req: tide::Request<State>) -> tide::Result {
    let dinos = req.state().dinos.read().await;
    // get all the dinos as a vector
    let dinos_vec: Vec<Dino> = dinos.values().cloned().collect();
    let mut res = Response::new(200);
    res.set_body(Body::from_json(&dinos_vec)?);
    Ok(res)
}


( ... )

    app.at("/dinos")
        .post(dinos_create)
        .get(dinos_list);

We moved the closures for this two endpoints to its own functions, let's run the tests to make sure we didn't break anything.

$ cargo test

    Finished test [unoptimized + debuginfo] target(s) in 12.48s
     Running target/debug/deps/tide_basic_crud-3d6db2bae3cd08a5

running 5 tests
test delete_dino ... ok
test index_page ... ok
test list_dinos ... ok
test create_dino ... ok
test update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Great! works as expected. We can move now the rest of the endpoints

    app.at("/dinos/:name")
        .get( dinos_get )
        .put( dinos_update )
        .delete( dinos_delete );

Awesome, but now we have five dinos_ functions in the main file. Let's refactor this to be more organized

First, let's create a new struct to represent a rest entity with a base_path field.

struct RestEntity {
    base_path: String,
}

And implement the same methods we had earlier

impl RestEntity {
    async fn create(mut req: Request<State>) -> tide::Result {
        let dino: Dino = req.body_json().await?;
        // let get a mut ref of our store ( hashMap )
        let mut dinos = req.state().dinos.write().await;
        dinos.insert(String::from(&dino.name), dino.clone());
        let mut res = Response::new(201);
        res.set_body(Body::from_json(&dino)?);
        Ok(res)
    }

    async fn list(req: tide::Request<State>) -> tide::Result {
        let dinos = req.state().dinos.read().await;
        // get all the dinos as a vector
        let dinos_vec: Vec<Dino> = dinos.values().cloned().collect();
        let mut res = Response::new(200);
        res.set_body(Body::from_json(&dinos_vec)?);
        Ok(res)
    }

    async fn get(req: tide::Request<State>) -> tide::Result {
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let res = match dinos.entry(key) {
            Entry::Vacant(_entry) => Response::new(404),
            Entry::Occupied(entry) => {
                let mut res = Response::new(200);
                res.set_body(Body::from_json(&entry.get())?);
                res
            }
        };
        Ok(res)
    }

    async fn update(mut req: tide::Request<State>) -> tide::Result {
        let dino_update: Dino = req.body_json().await?;
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let res = match dinos.entry(key) {
            Entry::Vacant(_entry) => Response::new(404),
            Entry::Occupied(mut entry) => {
                *entry.get_mut() = dino_update;
                let mut res = Response::new(200);
                res.set_body(Body::from_json(&entry.get())?);
                res
            }
        };
        Ok(res)
    }

    async fn delete(req: tide::Request<State>) -> tide::Result {
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let deleted = dinos.remove(&key);
        let res = match deleted {
            None => Response::new(404),
            Some(_) => Response::new(204),
        };
        Ok(res)
    }
}

Now we can create a helper function that allow us to register rest like entities to our server, registering five different endpoints to handle the list/create/read/update/delete operations.

fn register_rest_entity(app: &mut Server<State>, entity: RestEntity) {
    app.at(&entity.base_path)
        .get(RestEntity::list)
        .post(RestEntity::create);

    app.at(&format!("{}/:id", entity.base_path))
        .get(RestEntity::get)
        .put(RestEntity::update)
        .delete(RestEntity::delete);
}

And in the server we just need to create a new instance of the struct with the desired base_path and call the helper fn

    let dinos_endpoint = RestEntity {
        base_path: String::from("/dinos"),
    };

    register_rest_entity(&mut app, dinos_endpoint);

Great, let's just run the test to ensure that all the operations are still working...

cargo test
   Compiling tide-basic-crud v0.1.0
     Running target/debug/deps/tide_basic_crud-3d6db2bae3cd08a5

running 5 tests
test delete_dino ... ok
test list_dinos ... ok
test create_dino ... ok
test index_page ... ok
test update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Awesome, we just create a nice abstraction that allow us to create easily more rest like entities and implement the basic operations.

That's all for today, in the next iteration I will try to move away from the HashMap and persist the entities information in a db.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

I leave here the repo of this example and the pr of the refactor.

Thanks!

blog/content/post on  blog [$!?] on ☁️ (us-east-1)
❯

blog/content/post on  blog [$!?] on ☁️ (us-east-1)

❯ cat basic-crud-with-rust-using-tide-refactoring.md

layout: blog
title: "Basic CRUD with rust using tide - refactoring"
tags:

rust
notes
tide
http_rs
tide-basic-crud date: 2020-10-03T19:20:36.901Z --- In the last post I started a basic crud using tide and we end up with a simple api that allow us to store dinosaurs information.

async fn dinos_create(mut req: Request<State>) -> tide::Result {
    let dino: Dino = req.body_json().await?;
    // let get a mut ref of our store ( hashMap )
    let mut dinos = req.state().dinos.write().await;
    dinos.insert(String::from(&dino.name), dino.clone());
    let mut res = Response::new(201);
    res.set_body(Body::from_json(&dino)?);
    Ok(res)
}

async fn dinos_list(req: tide::Request<State>) -> tide::Result {
    let dinos = req.state().dinos.read().await;
    // get all the dinos as a vector
    let dinos_vec: Vec<Dino> = dinos.values().cloned().collect();
    let mut res = Response::new(200);
    res.set_body(Body::from_json(&dinos_vec)?);
    Ok(res)
}


( ... )

    app.at("/dinos")
        .post(dinos_create)
        .get(dinos_list);

We moved the closures for this two endpoints to its own functions, let's run the tests to make sure we didn't break anything.

$ cargo test

    Finished test [unoptimized + debuginfo] target(s) in 12.48s
     Running target/debug/deps/tide_basic_crud-3d6db2bae3cd08a5

running 5 tests
test delete_dino ... ok
test index_page ... ok
test list_dinos ... ok
test create_dino ... ok
test update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Great! works as expected. We can move now the rest of the endpoints

    app.at("/dinos/:name")
        .get( dinos_get )
        .put( dinos_update )
        .delete( dinos_delete );

Awesome, but now we have five dinos_ functions in the main file. Let's refactor this to be more organized

First, let's create a new struct to represent a rest entity with a base_path field.

struct RestEntity {
    base_path: String,
}

And implement the same methods we had earlier

impl RestEntity {
    async fn create(mut req: Request<State>) -> tide::Result {
        let dino: Dino = req.body_json().await?;
        // let get a mut ref of our store ( hashMap )
        let mut dinos = req.state().dinos.write().await;
        dinos.insert(String::from(&dino.name), dino.clone());
        let mut res = Response::new(201);
        res.set_body(Body::from_json(&dino)?);
        Ok(res)
    }

    async fn list(req: tide::Request<State>) -> tide::Result {
        let dinos = req.state().dinos.read().await;
        // get all the dinos as a vector
        let dinos_vec: Vec<Dino> = dinos.values().cloned().collect();
        let mut res = Response::new(200);
        res.set_body(Body::from_json(&dinos_vec)?);
        Ok(res)
    }

    async fn get(req: tide::Request<State>) -> tide::Result {
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let res = match dinos.entry(key) {
            Entry::Vacant(_entry) => Response::new(404),
            Entry::Occupied(entry) => {
                let mut res = Response::new(200);
                res.set_body(Body::from_json(&entry.get())?);
                res
            }
        };
        Ok(res)
    }

    async fn update(mut req: tide::Request<State>) -> tide::Result {
        let dino_update: Dino = req.body_json().await?;
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let res = match dinos.entry(key) {
            Entry::Vacant(_entry) => Response::new(404),
            Entry::Occupied(mut entry) => {
                *entry.get_mut() = dino_update;
                let mut res = Response::new(200);
                res.set_body(Body::from_json(&entry.get())?);
                res
            }
        };
        Ok(res)
    }

    async fn delete(req: tide::Request<State>) -> tide::Result {
        let mut dinos = req.state().dinos.write().await;
        let key: String = req.param("id")?;
        let deleted = dinos.remove(&key);
        let res = match deleted {
            None => Response::new(404),
            Some(_) => Response::new(204),
        };
        Ok(res)
    }
}

Now we can create a helper function that allow us to register rest like entities to our server, registering five different endpoints to handle the list/create/read/update/delete operations.

fn register_rest_entity(app: &mut Server<State>, entity: RestEntity) {
    app.at(&entity.base_path)
        .get(RestEntity::list)
        .post(RestEntity::create);

    app.at(&format!("{}/:id", entity.base_path))
        .get(RestEntity::get)
        .put(RestEntity::update)
        .delete(RestEntity::delete);
}

And in the server we just need to create a new instance of the struct with the desired base_path and call the helper fn

    let dinos_endpoint = RestEntity {
        base_path: String::from("/dinos"),
    };

    register_rest_entity(&mut app, dinos_endpoint);

Great, let's just run the test to ensure that all the operations are still working...

cargo test
   Compiling tide-basic-crud v0.1.0
     Running target/debug/deps/tide_basic_crud-3d6db2bae3cd08a5

running 5 tests
test delete_dino ... ok
test list_dinos ... ok
test create_dino ... ok
test index_page ... ok
test update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Awesome, we just create a nice abstraction that allow us to create easily more rest like entities and implement the basic operations.

That's all for today, in the next iteration I will try to move away from the HashMap and persist the entities information in a db.

As always, I write this as a learning journal and there could be another more elegant and correct way to do it and any feedback is welcome.

I leave here the repo of this example and the pr of the refactor.

Thanks!

Let's create a basic crud api with Rust using Tide

Javier Viola — Sun, 11 Jul 2021 19:14:42 +0000

Some time ago I started to learn about rust-lang and after read and watch some stuffs I decided to give a try to create a basic CRUD using tide as a web framework.

This example ( and approach ) is heavy inspired in two awesome resources :

Zero to Production in Rust by Luca Palmieri (@algo_luca)
Witter, a twitter clone in Rust by David Pedersen (@davidpdrsn )

Les start by creating a new binary project.

If you don't have rust installed, please check the install page and also can check my notes about rustup and cargo.

$ cargo new tide-basic-crud && cd tide-basic-crud

Next we want to add tide as dependency since is the http framework I selected to use, we can add it by hand editing the Cargo.toml file or install cargo-edit and use the add command.

$ cargo install cargo-edit
$ cargo add tide
    Updating 'https://github.com/rust-lang/crates.io-index' index
      Adding tide v0.13.0 to dependencies

Now following the getting started guide of tide add async-std with the attributes feature enable by adding this line to your deps ( in Cargo.toml file ).

async-std = { version = "1.6.0", features = ["attributes"] }

And edit our main.rs with the basic example.

#[async_std::main]
async fn main() -> Result<(), std::io::Error> {
    tide::log::start();
    let mut app = tide::new();
    app.at("/").get(|_| async { Ok("Hello, world!") });
    app.listen("127.0.0.1:8080").await?;
    Ok(())
}

Now we can compile and run the server with

$ cargo run

[Running 'cargo run']
   Compiling tide-basic-crud v0.1.0 (/Users/pepo/personal/rust/tide-basic-crud)
    Finished dev [unoptimized + debuginfo] target(s) in 5.25s
     Running `target/debug/tide-basic-crud`
tide::log Logger started
    level Info
tide::listener::tcp_listener Server listening on http://127.0.0.1:8080

And check with curl

$ curl localhost:8080
Hello, world!

Awesome! we have our server up and running, but at this point doesn't do much so let's add some code. For the purpose of this example let's create a simple CRUD that allow us to track dinosaurs information.

We will recording the name, weight ( in kilograms ) and the diet ( type ).
First let's create a route for create a dinos, adding the /dinos route ( at ) with the verb post and following the request/response concept

(...)
    app.at("/dinos").post(|mut req: Request<()>| async move {
        let body = req.body_string().await?;
        println!("{:?}", body);
        let mut res = Response::new(201);
        res.set_body(String::from("created!"));
        Ok(res)
    });

And test...

$ curl -v -d '{"name":"velociraptor", "weight": 50, "diet":"carnivorous"}' http://localhost:8080/dinos

(...)
* upload completely sent off: 59 out of 59 bytes
< HTTP/1.1 201 Created
(...)
created!

And we can check the payload of the request in the logs

tide::log::middleware <-- Request received
    method POST
    path /dinos
"{\"name\":\"velociraptor\", \"weight\": 50, \"diet\":\"carnivorous\"}"
tide::log::middleware --> Response sent
    method POST
    path /dinos
    status 201
    duration 59.609µs

Nice! But we get the body as string and we need to parse as json. If you are familiarized with node.js and express this could be done with the body-parser middleware, but tide can parse json and form (urlencoded) out of the box with body_json and body_form methods.

Let's change body_string() to body_json and try again.

curl -v -d '{"name":"velociraptor", "weight": 50, "diet":"carnivorous"}' http://localhost:8080/dinos

< HTTP/1.1 422 Unprocessable Entity

422 Unprocessable Entity, doesn't works as expected (or maybe yes). Tide use serde to deserialize the request body and need to be parse into a struct. So, let's create our Dino struct and deserialize the body into.

#[derive(Debug, Deserialize, Serialize)]
struct Dino {
    name: String,
    weight: u16,
    diet: String
}

Here we use the derive attributes to all to serialize/deserialize, now let's change the route to deserialize the body into the the Dino struct and return the json representation.

    app.at("/dinos").post(|mut req: Request<()>| async move {
        let  dino: Dino = req.body_json().await?;
        println!("{:?}", dino);
        let mut res = Response::new(201);
        res.set_body(Body::from_json(&dino)?);
        Ok(res)
    });

And check if works as expected...

$ curl -d '{"name":"velociraptor", "weight": 50, "diet":"carnivorous"}' http://localhost:8080/dinos

{"name":"velociraptor","weight":50,"diet":"carnivorous"}

Nice! let's move forward and store those dinos using a hashMap to store a key/value in memory. We will add a db persistence later.

Looking the tide documentation, we can use tide::with_state to create a server with shared application scoped state.

Let's use the state to store our hashMap.

#[derive(Clone,Debug)]
struct State {
    dinos: Arc<RwLock<HashMap<String,Dino>>>
}

We wrap our hashMap in a mutex here to use in the State ( thanks to the tide awesome community for the tip ).

Then in the main fn

    let state = State {
        dinos: Default::default()
    };

    let mut app = tide::with_state(state);
    app.at("/").get(|_| async { Ok("Hello, world!") });

    app.at("/dinos")
       .post(|mut req: Request<State>| async move {
           let  dino: Dino = req.body_json().await?;
           // let get a mut ref of our store ( hashMap )
           let mut dinos = req.state().dinos.write().await;
           dinos.insert(String::from(&dino.name), dino.clone());
           let mut res = Response::new(201);
           res.set_body(Body::from_json(&dino)?);
          Ok(res)
     })

Nice, let's add a route to list the dinos and check how it's works

    app.at("/dinos")
        .get(|req: Request<State>| async move {
            let dinos = req.state().dinos.read().await;
            // get all the dinos as a vector
            let dinos_vec: Vec<Dino> = dinos.values().cloned().collect();
            let mut res = Response::new(200);
            res.set_body(Body::from_json(&dinos_vec)?);
            Ok(res)
        })

$ curl -d '{"name":"velociraptor", "weight": 50, "diet":"carnivorous"}' http://localhost:8080/dinos

$ curl -d '{"name":"t-rex", "weight": 5000, "diet":"carnivorous"}' http://localhost:8080/dinos

$ curl http://localhost:8080/dinos

[{"name":"velociraptor","weight":50,"diet":"carnivorous"},{"name":"t-rex","weight":5000,"diet":"carnivorous"}]

Nice! now let's try getting and individual dino...

    app.at("/dinos/:name")
        .get(|req: Request<State>| async move {
            let mut dinos = req.state().dinos.write().await;
            let key: String = req.param("name")?;
            let res = match dinos.entry(key) {
                Entry::Vacant(_entry) => Response::new(404),
                Entry::Occupied(entry) => {
                    let mut res = Response::new(200);
                    res.set_body(Body::from_json(&entry.get())?);
                    res
                }
            };
            Ok(res)
        })

We are using the entry api so, before using here we need to bring it to the scope. We can do it adding this line at the top of the file

use std::collections::hash_map::Entry;

Now we can match in the get to return the dino or 404 if the requested name doesn't exists.

$ curl http://localhost:8080/dinos/t-rex

{"name":"t-rex","weight":5000,"diet":"carnivorous"}

$ curl -I http://localhost:8080/dinos/trex
HTTP/1.1 404 Not Found
content-length: 0

Awesome! We are almost there, add the missing routes to complete the CRUD.

        .put(|mut req: Request<State>| async move {
            let dino_update: Dino = req.body_json().await?;
            let mut dinos = req.state().dinos.write().await;
            let key: String = req.param("name")?;
            let res = match dinos.entry(key) {
                Entry::Vacant(_entry) => Response::new(404),
                Entry::Occupied(mut entry) => {
                    *entry.get_mut() = dino_update;
                    let mut res = Response::new(200);
                    res.set_body(Body::from_json(&entry.get())?);
                    res
                }
            };
            Ok(res)
        })
        .delete(|req: Request<State>| async move {
            let mut dinos = req.state().dinos.write().await;
            let key: String = req.param("name")?;
            let deleted = dinos.remove(&key);
            let res = match deleted {
                None => Response::new(404),
                Some(_) => Response::new(204),
            };
            Ok(res)
        });

Let's try update...

$ curl -v -X PUT -d '{"name":"t-rex", "weight": 5, "diet":"carnivorous"}' http://localhost:8080/dinos/t-rex

$ curl http://localhost:8080/dinos/t-rex

{"name":"t-rex","weight":5,"diet":"carnivorous"}

and delete

$ curl -v -X DELETE  http://localhost:8080/dinos/t-rex

$ curl -I http://localhost:8080/dinos/t-rex
HTTP/1.1 404 Not Found

We made it! a complete CRUD with tide. But that was a lot of manual testing, let's add some basic unit test to smooth the next steps.
First decouple our main function of the server creation allowing us to create a server without need to actually listen in any port.

#[async_std::main]
async fn main() {
    tide::log::start();
    let dinos_store = Default::default();
    let app = server(dinos_store).await;

    app.listen("127.0.0.1:8080").await.unwrap();
}

async fn server(dinos_store: Arc<RwLock<HashMap<String, Dino>>>) -> Server<State> {
    let state = State {
        dinos: dinos_store, //Default::default(),
    };

    let mut app = tide::with_state(state);
    app.at("/").get(|_| async { Ok("ok") });

(...)
app

Great, now we can add some basic test using the server function using cargo for running our tests. There is more information about tests in the cargo book but in general

Cargo can run your tests with the cargo test command. Cargo looks for tests to run in two places: in each of your src files and any tests in tests/. Tests in your src files should be unit tests, and tests in tests/ should be integration-style tests. As such, you’ll need to import your crates into the files in tests.

#[async_std::test]
async fn list_dinos() -> tide::Result<()> {
    use tide::http::{Method, Request, Response, Url};

    let dino = Dino {
        name: String::from("test"),
        weight: 50,
        diet: String::from("carnivorous"),
    };

    let mut dinos_store = HashMap::new();
    dinos_store.insert(dino.name.clone(), dino);
    let dinos: Vec<Dino> = dinos_store.values().cloned().collect();
    let dinos_as_json_string = serde_json::to_string(&dinos)?;

    let state = Arc::new(RwLock::new(dinos_store));
    let app = server(state).await;

    let url = Url::parse("https://example.com/dinos").unwrap();
    let req = Request::new(Method::Get, url);
    let mut res: Response = app.respond(req).await?;
    let v = res.body_string().await?;
    assert_eq!(dinos_as_json_string, v);
    Ok(())
}

#[async_std::test]
async fn create_dino() -> tide::Result<()> {
    use tide::http::{Method, Request, Response, Url};

    let dino = Dino {
        name: String::from("test"),
        weight: 50,
        diet: String::from("carnivorous"),
    };

    let dinos_store = HashMap::new();

    let state = Arc::new(RwLock::new(dinos_store));
    let app = server(state).await;

    let url = Url::parse("https://example.com/dinos").unwrap();
    let mut req = Request::new(Method::Post, url);
    req.set_body(serde_json::to_string(&dino)?);
    let res: Response = app.respond(req).await?;
    assert_eq!(201, res.status());
    Ok(())
}

This unit tests are inspired in this gist that was posted on the tide-users discord channel.

The main idea here is that we can create our server ( app ), calling the endpoint with a request without need to make an actual http request and have the server listen in any port.

We can now run cargo test

$  cargo test
   Compiling tide-basic-crud v0.1.0 (/Users/pepo/personal/rust/tide-basic-crud)
    Finished test [unoptimized + debuginfo] target(s) in 5.99s
     Running target/debug/deps/tide_basic_crud-3d6db2bae3cd08a5

running 5 tests
test list_dinos ... ok
test index_page ... ok
test create_dino ... ok
test delete_dino ... ok
test update_dino ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Just one more think to add, cargo is an awesome tool and you can add more functionality like watching changes in you code and react ( for example running test ) with cargo-watch.

This is all for now, my intent to learn by doing. I'm sure that there is other ways ( likely betters ) to create a crud with tide and any feedback is welcome :) .

In the next post I will refactor the code to move the dinos_store to a database ( postgresql / sqlx ).

You can find the complete code in this repo Thanks!