Getting Started with SurrealDB 2 and Axum for Web Development

2024-11-29T00:00:00+00:00

The goal of this blog post is to help beginners grasp the basics of using SurrealDB 2 and Axum for web development.

I find the technology fascinating, but readers should be aware that SurrealDB v1 upset many users due to the lack of documentation and poor performance </blockquote>

However, version 2 fixes several performance and bug issues. One such improvement is that the in-memory storage is now powered by SurrealKV, which is concurrent, meaning that read/write operations scale with the number of CPUs.

Understanding SurrealDB's Architecture</h2>
SurrealDB separates its query language (called SurrealQL</a>) from its data storage backend. This flexibility allows you to choose the best storage option for your project. While I'll be using SurrealKV locally for simplicity, other options</a> are available, such as TikV for distributed storage or other in-memory solutions.
SurrealQL</a> from the data storage. I'll be using SurrealKV locally but there are other options including TikV for distributed and in memory to name a few</a>.
Check out the SurrealDB getting started</a> page to start up an in memory data store. I would recommend clicking on "Using CLI" to learn how to connect to the database in the terminal.
I found the book</a> very helpful in learning the language.

Prerequisites</h2>

Before getting started, make sure you have the following installed:

Rust</a> installed </li>

SurrealDB</a> installed </li> </ul>

Step 1. Create the Project</h2>

cargo</span> new webapp
</span></code></pre>
add dependencies</p>
cd</span> webapp
</span>
</span>cargo</span> add axum
</span>cargo</span> add serde</span> --features</span> derive
</span>cargo</span> add surrealdb</span> --features</span> kv-surrealkv
</span>cargo</span> add thiserror
</span>cargo</span> add tokio</span> --features</span> full
</span>cargo</span> add serde_json
</span></code></pre>


Now start up a SurrealKV storage engine at localhost:8080</p>
surreal</span> start</span> --user</span> root</span> --pass</span> password</span> --bind</span> 127.0.0.1:8080 surrealkv://mydb
</span></code></pre>
In depth examples of using surreal start here</a>. Make sure to select V2.x</p>
From a second terminal, connect to the engine and set the database to test_db and namespace to test_ns</p>
surreal</span> sql</span> --endpoint</span> http://127.0.0.1:8080</span> --user</span> root</span> --pass</span> password</span> --ns</span> test_ns</span> --db</span> test_db
</span></code></pre>
In depth examples of using surreal sql here</a></p>
Step 2. Insert some data in the database</h2>
After the last surreal sql ... statement you should be connected:</p>
test_ns/test_db</span>>
</span></code></pre>
I will create a TABLE</a> called users and set the table to have structured, predictable data types with a Schema</a>.</p>
DEFINE TABLE IF NOT EXISTS users SCHEMAFULL;
</span></code></pre>
Scrolling down in that last Schema link will show the user that at any point we can add a field to our table that is schemaless using FLELXIBLE. Perhaps for metatdata.</p>
Let's add a username FIELD</a> to the table that's only allowed to be under 14 characters long</p>
DEFINE FIELD username ON TABLE users TYPE string ASSERT string::len($value) < </span>14</span>;
</span></code></pre>
Next we can define an INDEX</a> for the username to make it a unique field.</p>
Reading through the docs tells us that indexes are used to speed up query execution times dramatically.</p>
DEFINE INDEX usernameIndex ON TABLE users COLUMNS username UNIQUE;
</span></code></pre>
Now let's CREATE</a> a user</p>
CREATE users </span>SET</span> username = </span>"User1"</span>;
</span></code></pre>
and we can see from the output that SurrealDB automatically gives us an id field</p>
[[{</span> id: users:2272f7xnqi502d9it9q4, username: </span>'User1' </span>}</span>]]
</span></code></pre>
we could have also created the unique id with this command (skip, just for example):</p>
CREATE users:</span>1 </span>SET</span> username = </span>"User1"</span>;
</span></code></pre>


Step 3. Write some Rust code</h2>
Open src/main.rs and grab all the dependencies we added</p>
use </span>axum::{extract::State, routing::get, Router, Json, extract::Path, response::IntoResponse };
</span>use </span>surrealdb::Surreal;
</span>use </span>serde::{Deserialize, Serialize};
</span>use </span>std::sync::Arc;
</span>use </span>tokio::sync::Mutex;
</span>use </span>surrealdb::engine::any::Any;
</span></code></pre>
We should pause here and take a look at the official SurrealDB example of using the Rust SDK</a></p>
Ok so it says we should convert Surreal errors into Axum responses (copy paste the boilerplate)</p>
mod </span>error {
</span>    </span>use </span>axum::http::StatusCode;
</span>    </span>use </span>axum::response::IntoResponse;
</span>    </span>use </span>axum::response::Response;
</span>    </span>use </span>axum::Json;
</span>    </span>use </span>thiserror::Error;
</span>
</span>    #[</span>derive</span>(Error, Debug)]
</span>    </span>pub enum </span>Error {
</span>        #[</span>error</span>(</span>"database error"</span>)]
</span>        Db,
</span>    }
</span>
</span>    </span>impl </span>IntoResponse </span>for </span>Error {
</span>        </span>fn </span>into_response</span>(</span>self</span>) -> Response {
</span>            </span>match </span>self </span>{
</span>            Error::Db=> (StatusCode::</span>INTERNAL_SERVER_ERROR</span>, Json(</span>"An error has occurred. Please try again later."</span>.</span>to_string</span>())).</span>into_response</span>(),
</span>            }
</span>        }
</span>    }
</span>
</span>    </span>impl </span>From<surrealdb::Error> </span>for </span>Error {
</span>        </span>fn </span>from</span>(</span>error</span>: surrealdb::Error) -> </span>Self </span>{
</span>            eprintln!(</span>"</span>{error}</span>"</span>);
</span>            </span>Self</span>::Db
</span>        }
</span>    }
</span>}
</span></code></pre>
Alright with the boilerplate out of the way I want to discuss surrealdb::engine::any</a></p>
I mentioned that I would be using SurrealKV as the database engine, but really SurrealDB doesn't force us to stick with one. The link right above explains how the query language is completely separate from the database engine.</p>
// make sure our database is accessible from all routes
</span>#[</span>derive</span>(Clone)]
</span>struct </span>AppState {
</span>    </span>db</span>: Arc<Mutex<Surreal<Any>>>,
</span>}
</span></code></pre>
#[</span>tokio</span>::</span>main</span>]
</span>async </span>fn </span>main</span>() -> Result<(), error::Error>{
</span>    </span>// any allows us to swap between rocksdb://mydb, mem://, etc. 
</span>    </span>let</span> db = surrealdb::engine::any::connect(</span>"surrealkv://mydb"</span>).await?;
</span>
</span>// authenticate
</span>db.</span>signin</span>(surrealdb::opt::auth::Root {
</span>    username: </span>"root"</span>,
</span>    password: </span>"password"</span>,
</span>}).await?;
</span>
</span>// select a namespace and a database inside that namespace
</span>db.</span>use_ns</span>(</span>"test_ns"</span>).</span>use_db</span>(</span>"test_db"</span>).await?;
</span>
</span>// for routes to access the database, Axum provides AppState
</span>let</span> app_state = AppState {
</span>    db: Arc::new(Mutex::new(db))
</span>};
</span>
</span>// define our routes to create, delete, get users
</span>let</span> app = Router::new()
</span>    .</span>route</span>(</span>"/"</span>, </span>get</span>(get_users))
</span>    .</span>route</span>(</span>"/create/:uname"</span>, </span>get</span>(create_user))
</span>    .</span>route</span>(</span>"/delete/:uname"</span>, </span>get</span>(delete_user))
</span>    .</span>with_state</span>(app_state);
</span>
</span>let</span> listener = tokio::net::TcpListener::bind(</span>"0.0.0.0:3000"</span>).await.</span>unwrap</span>();
</span>
</span>axum::serve(listener, app).await.</span>unwrap</span>();
</span>
</span>Ok(())
</span>}
</span></code></pre>
For brevity I'll just use get requests with the data directly in the path.</p>
However, you can use RESTful APIs such as delete, post, etc. Then access the endpoints</a> with curl</p>
curl -I</span> http://localhost:8080/status
</span>
</span>HTTP/1.1</span> 200 OK
</span>content-length:</span> 0
</span>vary:</span> origin, access-control-request-method, access-control-request-headers
</span>access-control-allow-origin: </span>*
</span>surreal-version:</span> surrealdb-2.0.0+20240910.8f30ee08
</span>server:</span> SurrealDB
</span>x-request-id:</span> 3dedcc96-4d8a-451e-b60d-4eaac14fa3f8
</span>date:</span> Wed, 11 Sep 2024 00:52:49 GMT
</span></code></pre>
Now we should write a database query to define our table if it doesn't exist. Just like we did manually at the start of the tutorial.</p>
db.</span>query</span>(
</span>    </span>"DEFINE TABLE IF NOT EXISTS users SCHEMAFULL;
</span>    DEFINE FIELD IF NOT EXISTS username ON TABLE users TYPE string ASSERT string::len($value) < 14;
</span>    DEFINE INDEX IF NOT EXISTS usernameIndex ON TABLE users COLUMNS username UNIQUE;
</span>    "
</span>).await?;
</span></code></pre>
And now we create the routes</p>
// schema to insert or get users 
</span>#[</span>derive</span>(Serialize, Deserialize, Clone)]
</span>pub struct </span>User {
</span>    </span>username</span>: String,
</span>}
</span>
</span>// retrieve all users 
</span>// 127.0.0.1:3000/
</span>async </span>fn </span>get_users</span>(State(</span>state</span>): State<AppState>) -> Result<Json<Vec<User>>, error::Error>{
</span>    </span>let</span> db = state.db.</span>lock</span>().await;
</span>    </span>let mut</span> response = db.</span>query</span>(</span>"SELECT * FROM users"</span>).await?;
</span>
</span>    </span>let</span> result: Vec<User> = response.</span>take</span>(</span>0</span>)?;
</span>
</span>    Ok(Json(result))
</span>
</span>}
</span></code></pre>
Now to create a user at localhost:3000/create/newusername</p>
async </span>fn </span>create_user</span>(Path(</span>uname</span>): Path<String>, State(</span>state</span>): State<AppState>) -> Result<impl IntoResponse, error::Error>{
</span>   </span>let</span> db = state.db.</span>lock</span>().await;
</span>
</span>   </span>let</span> newUser: Option<User> = db.</span>create</span>(</span>"users"</span>).</span>content</span>(User {
</span>        username: uname,
</span>    }).await?;
</span>
</span>    Ok(</span>"Success creating new user"</span>)
</span>}
</span></code></pre>
And we can delete a user at localhost:3000/delete/newusername</p>
async </span>fn </span>delete_user</span>(Path(</span>uname</span>): Path<String>, State(</span>state</span>): State<AppState>) -> Result<impl IntoResponse, error::Error>{
</span>   </span>let</span> db = state.db.</span>lock</span>().await;
</span>
</span>    db.</span>query</span>(</span>"DELETE FROM users WHERE username = $username"</span>)
</span>        .</span>bind</span>((</span>"username"</span>, uname)).await?;
</span>
</span>    Ok(</span>"Success deleting user"</span>)
</span>}
</span></code></pre>
With this basic setup in place, you can start experimenting with more complex queries, adding authentication, or introducing new features to your app. The full code is available on Github</a></p>
Happy coding!</p>

How to Properly Learn Rust Programming

2023-08-06T00:00:00+00:00

The goal, in this blog post, will be to help beginner Rust programmers overcome the notion that Rust is a difficult language.

First and foremost, I will advocate for the Rust book from Brown University over the regular one. Here: https://rust-book.cs.brown.edu/</a> (it requires you to scroll all the way down and accept to participate).

It provides a more thorough explanation of Rust and includes simple quizzes to test your new gained knowledge. The original book does not contain quizzes and so many people believe they understand Rust but are completely mistaken.

Alongside with the book, you'll want to test the examples using either a local programming environment or the online environment https://play.rust-lang.org/</a>

How to set up a local workspace (skip if you prefer the online Rust Playground)</h3>

I'm assuming Rust is already installed on your system.

Create a new directory

mkdir</span> project && </span>cd</span> project
</span></code></pre>
Manually create a Cargo.toml for the workspace</p>
vim</span> Cargo.toml
</span></code></pre>
[workspace]
</span>
</span>members </span>= [
</span>	</span>"app"</span>,
</span>	</span>"applib"</span>,
</span>]
</span></code></pre>
Initialize the binary directory and the library directory</p>
cargo</span> init</span> --bin</span> app && </span>cargo</span> init</span> --lib</span> applib
</span></code></pre>
Make applib available inside of app by editing app/Cargo.toml</code></p>
[package]
</span>name </span>= </span>"app"
</span>version </span>= </span>"0.1.0"
</span>edition </span>= </span>"2021"
</span>
</span>[dependencies]
</span>#add this
</span>applib </span>= {</span>path </span>= </span>"../applib"</span>}
</span></code></pre>
Now applib's functions can be imported into the app binary. Edit app/src/main.rs</code></p>
use</span> applib;
</span>
</span>fn </span>main</span>() {
</span>   </span>// applib::add() is located in applib/src/lib.rs
</span>   println!(</span>"100 + 100 = </span>{}</span>"</span>, applib::add(</span>100</span>, </span>100</span>)); 
</span>}
</span></code></pre>
and run it:</p>
cargo</span> run</span> --bin</span> app
</span>
</span># 200 
</span></code></pre>


Memory safety</h2>
I believe Rust's memory safe idiosyncrasies are what intimidate most people from this language. However, this is what makes it a safe language that doesn't require a garbage collector. It's essential to master this part of the language to write memory safe code.</p>
The good news is that even if you write unsafe code it won't compile.</p>
Ownership</h3>
Since there exists no garbage collector, owned variables are destructed once they go out of scope. Essentially, once a function or block expression</a> returns. Unless the variable is returned or the variable was passed by borrowing (also known as pass by reference).</p>
The following variable will be immutable for the entire duration of the program.</p>
fn </span>main</span>() {
</span>    </span>let</span> num = </span>14</span>;
</span>    println!(</span>"</span>{}</span>"</span>, num); </span>// prints 14
</span>}
</span></code></pre>

note: notice how num's type is implicitly assigned; a const variable would require explicitly assigning the type as so:</p>
const NUM: i32 = 10;</p>
</blockquote>
In order to make it mutable we must add the keyword mut:</p>
fn </span>main</span>() {
</span>    </span>let mut</span> num = </span>14</span>;
</span>    num = </span>100</span>;
</span>    println!(</span>"</span>{}</span>"</span>, num); </span>// prints 100
</span>}
</span></code></pre>
Suppose we pass this variable into a function</p>
fn </span>plusOne</span>(</span>num</span>: </span>i32</span>) {
</span>    println!(</span>"</span>{}</span>"</span>, num + </span>1</span>); </span>// prints 101
</span>} 
</span>
</span>fn </span>main</span>() {
</span>   </span>let</span> num = </span>14</span>; 
</span>   plusOne(num);
</span>   println!(</span>"</span>{}</span>"</span>, num); </span>// prints 100
</span>}
</span></code></pre>
Notice how the code was able to call println! on num after calling the function plusOne.</p>
Normally Rust would not compile this program because any variable passed into a function (without an ampersand &) would destroy the variable.</p>
However, Rust primitives such as u64 implement the Copy</a> trait. The function plusOne implicitly received a Copy of the variable num and thus we did not transfer ownership.</p>
Let's see how Rust transfers ownership of a struct that doesn't implement Copy</p>
struct </span>Person{
</span>    </span>name</span>: String
</span>}
</span>
</span>fn </span>getName</span>(</span>pers</span>: Person) {
</span>    println!(</span>"name is </span>{}</span>"</span>, pers.name); </span>// drops the variable
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let</span> Carl = Person{name: String::from(</span>"Carl"</span>)};
</span>    getName(Carl); </span>// prints name is Carl
</span>    </span>// but we can no longer user Carl as it was dropped 
</span>    </span>// println!("{}", Carl.name); would not work here as it did with num above
</span>}
</span></code></pre>
In order to use Carl, after calling getName, we'd be required to pass it as a reference using &</p>
... 
</span>
</span>fn </span>getName</span>(</span>pers</span>: &Person) {
</span>    println!(</span>"name is </span>{}</span>"</span>, pers.name); </span>// does not drop the variable
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let</span> Carl = Person{name: String::from(</span>"Carl"</span>)};
</span>    </span>// placing an & before the variable passes it as borrowed
</span>    getName(&Carl); </span>// prints name is Carl
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name); </span>// prints Carl 
</span>}
</span></code></pre>
We could also transfer ownership of Carl to another variable just as we could into a function.</p>
...
</span>
</span>fn </span>main</span>() {
</span>    </span>let</span> Carl = Person{name: String::from(</span>"Carl"</span>)};            
</span>    </span>// move ownership
</span>    </span>let</span> Carl2 = Carl;
</span>
</span>    </span>// Carl is no longer available 
</span>    </span>// Carl2 is available
</span>    println!(</span>"</span>{}</span>"</span>, Carl2.name); </span>// prints Carl
</span>}
</span></code></pre>
A variable can also be converted to mutable when moving it</p>
...
</span>
</span>fn </span>main</span>() {
</span>    </span>let</span> Carl = Person{name: String::from(</span>"Carl"</span>)};            
</span>    </span>// move to mutable ownership
</span>    </span>let mut</span> Carl2 = Carl;
</span>    Carl2.name = </span>"Carl2"</span>.</span>to_string</span>();
</span>
</span>    println!(</span>"</span>{}</span>"</span>, Carl2.name); </span>// prints Carl2
</span>}
</span></code></pre>
Alternatively, a function can take a mutable borrow and change the value without deleting the variable.</p>
...
</span>
</span>// changes the borrowed variable without dropping it 
</span>fn </span>changeName</span>(</span>pers</span>: &</span>mut</span> Person) {
</span>    pers.name = </span>"Carl2"</span>.</span>to_string</span>();
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let</span> Carl = Person{name: String::from(</span>"Carl"</span>)};            
</span>    </span>let mut</span> Carl2 = Carl;
</span>
</span>    changeName(&</span>mut</span> Carl2);
</span>    println!(</span>"</span>{}</span>"</span>, Carl2.name); </span>// prints Carl2
</span>}
</span></code></pre>
However, if the variable is a primitive then ownership is not transferred.</p>
fn </span>main</span>() {
</span>    </span>let</span> a = </span>10</span>;
</span>    </span>// a is cloned and thus is not dropped
</span>    </span>let</span> b = a; 
</span>
</span>    println!(</span>"</span>{a}</span> and </span>{b}</span> are clones"</span>); </span>// prints 10 and 10
</span>}
</span></code></pre>
While a variable is borrowed mutably it cannot also be borrowed immutably. Only when the variable is no longer referenced by the borrower can it be again borrowed.</p>
struct </span>Person {
</span>    </span>name</span>: String
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let mut</span> Carl = Person{name: </span>"Carl"</span>.</span>to_string</span>()}; 
</span>    </span>// borrow Carl mutably
</span>    </span>let</span> borrowCarlMutably = &</span>mut</span> Carl;
</span>    </span>// Carl's name is indirectly changed to Carl2
</span>    borrowCarlMutably.name = </span>"Carl2"</span>.</span>to_string</span>();
</span>    
</span>    </span>// Carl cannot be assigned to an immutable variable as so:
</span>    </span>// let c = &Carl;
</span>    println!(</span>"</span>{}</span>"</span>, borrowCarlMutably.name); </span>// prints Carl2
</span>
</span>    </span>// Carl can now again be borrowed immutably because 
</span>    </span>// borrowCarlMutably is no longer referenced
</span>
</span>    </span>let</span> borrowCarlImmutably = &Carl;
</span>    println!(</span>"</span>{}</span>"</span>, borrowCarlImmutably.name); </span>// prints Carl2
</span>
</span>    </span>// Carl is still the owner as we only borrowed it above 
</span>    </span>// Now that the mutable borrow is dropped we can use it again
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name); </span>// prints Carl2
</span>}
</span></code></pre>
Variables stored as an Option</a> type will be dropped in a match statement unless the unpacked variable is prefixed with ref</code>.</p>
fn </span>main</span>(){
</span>    </span>let</span> name = Some(String::from(</span>"Carl"</span>));
</span>    </span>match</span> name {
</span>        </span>// notice the ref keyword
</span>        </span>// Using Some(n) .. will not compile 
</span>        Some(</span>ref</span> n) => println!(</span>"Hello </span>{}</span>"</span>, n),
</span>        _ => println!(</span>"no value"</span>),
</span>    }
</span>    </span>// if ref is not added, this would cause the program to not compile 
</span>    </span>// since name would have been dropped in the match statement
</span>    println!(</span>"Hello again </span>{}</span>"</span>, name.</span>unwrap</span>());
</span>}
</span></code></pre>
Lifetimes</h3>
Rust also requires that a borrowed variable's data have a lifetime. Simply because you wouldn't want your borrowed variable to be dropped before you're done using it.</p>
In fact the mutable variable we declared in the code right above was implementing lifetimes.</p>
This code will NOT compile because the lifetime of borrowCarlMutably ends when we use Carl.</p>
...
</span>
</span>fn </span>main</span>() {
</span>    </span>let mut</span> Carl = Person{name: </span>"Carl"</span>.</span>to_string</span>()}; 
</span>    </span>// borrow Carl mutably
</span>    </span>let</span> borrowCarlMutably = &</span>mut</span> Carl;
</span>
</span>    </span>// using Carl means borrowCarlMutably can no longer be used
</span>    </span>// because its lifetime has gone out of scope 
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name); 
</span>    
</span>    </span>// WRONG! 
</span>    </span>// this should be moved above println before using Carl 
</span>    borrowCarlMutably.name = </span>"john"</span>.</span>to_string</span>();
</span>}
</span></code></pre>
So far we haven't seen the syntax of lifetimes, even though I have passed borrowed variables into functions above.</p>
The reason is that Rust elides (omits) them for for simple functions that don't cause the compiler to decide which to return.</p>
struct </span>Person {
</span>    </span>name</span>: String
</span>}
</span>
</span>// Elided 
</span>fn </span>changeName</span>(</span>pers</span>: &</span>mut</span> Person) {
</span>    pers.name = </span>"joe"</span>.</span>to_string</span>();
</span>}
</span>
</span>// Expanded
</span>fn </span>changeName</span><</span>'a</span>>(</span>pers</span>: &</span>'a mut</span> Person) {
</span>    pers.name = </span>"joe"</span>.</span>to_string</span>();
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let mut</span> Carl = Person{name: </span>"Carl"</span>.</span>to_string</span>()}; 
</span>    changeName(&</span>mut</span> Carl);
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name);
</span>}
</span></code></pre>
However more complicated functions that have borrowed variables with different lifetimes will require explicitly telling the compiler.</p>
Note that an apostraphe is required for a lifetime's syntax however the name can be anything. It's common convention to use different letters for different lifetimes (e.g., 'a</code>, 'b</code>)</p>
struct </span>Person {
</span>    </span>name</span>: String
</span>}
</span>
</span>fn </span>changeName</span><</span>'a</span>, </span>'b</span>>(</span>pers</span>: &</span>'a mut</span> Person, </span>newName</span>: &</span>'b str</span>) {
</span>    pers.name = newName.</span>to_string</span>();
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let mut</span> Carl = Person{name: </span>"Carl"</span>.</span>to_string</span>()}; 
</span>    
</span>    {
</span>        </span>// variables in this scope have different lifetimes 
</span>        </span>// than those outside of {}
</span>        </span>let</span> newName = </span>"Mario"</span>;
</span>        changeName(&</span>mut</span> Carl, newName);
</span>    }
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name); </span>// prints Mario
</span>}
</span></code></pre>
Essentially, Rust is making sure that any borrowed value returned from the function will live at least as long as the lifetime of one of the inputs. The compiler can then make a decision as to whether your code is valid.</p>
struct </span>Person {
</span>    </span>name</span>: String
</span>}
</span>
</span>// now we return a borrowed variable with a lifetime 
</span>// of newName
</span>fn </span>changeName</span><</span>'a</span>, </span>'b</span>>(</span>pers</span>: &</span>'a mut</span> Person, </span>newName</span>: &</span>'b str</span>) -> &</span>'b str </span>{
</span>    pers.name = newName.</span>to_string</span>();
</span>    &newName
</span>}
</span>
</span>fn </span>main</span>() {
</span>    </span>let mut</span> Carl = Person{name: </span>"Carl"</span>.</span>to_string</span>()}; 
</span>    {
</span>       </span>let</span> newName = </span>"Mario"</span>;
</span>       </span>let </span>_ =  changeName(&</span>mut</span> Carl, newName);
</span>    }
</span>    println!(</span>"</span>{}</span>"</span>, Carl.name);
</span>}
</span></code></pre>
There exists a reserved lifetime called 'static</code> that signifies to the compiler that the variable will live for the entire lifetime of the program. The variable will be embedded into the binary.</p>
static </span>GLOBAL</span>: &</span>'static str </span>= </span>"global static variable"</span>;
</span>
</span>fn </span>main</span>() {
</span>    println!(</span>"</span>{}</span>"</span>, </span>GLOBAL</span>);
</span>}
</span></code></pre>
In my opinion, much of the struggle that people have wrestling with the borrow checker stems from gaps in knowledge related to ownership and lifetimes.</p>
The quizzes in the brown.edu git book definitely help filling those gaps.</p>
If Rust still seems confusing then I recommend A half-hour to learn Rust</a>.</p>

Using Rust, Tauri, and SvelteKit to Build a Note Taking App

2023-04-05T00:00:00+00:00

In this blog post, I'll be guiding you through the process of building a note taking app using Tauri. Move over Electron :)</h2>

Tauri allows us to build fast, cross-platform, and small sized apps using HTML, CSS, and JavaScript.
It accomplishes this by using WebViews</a>. A WebView lets you embed web content (HTML,CSS, JavaScript) into an application without needing a full-fledged web browser.
Rust is used for the backend logic and SvelteKit</a> for the frontend.
Each OS uses a different WebView rendering engine:

Windows uses WebView2</li>
Linux uses WebKit</li> </ul>
Setting up the project</h2>
Make sure Rust and the Tauri dependencies are installed as described here</a>.
SvelteKit requires Node.js. I install it using Fedora's package manager.
`sudo dnf install nodejs </code></pre> Instead of npm, I'll install pnpm as the Node.js package manager`
`sudo npm install -g pnpm </code></pre> Now we can initialize a new svelte project.`
$ mkdir notes && cd notes $ pnpm create svelte // hit enter to create the project in the current directory // use down arrow key to select Skeleton project // use down arrow key to select Yes, using Typescript syntax // use space bar to select // * Add ESLint for code linting // * Add Prettier for code formatting // @next gets latest version $ pnpm add -D @sveltejs/adapter-static@next </code></pre> edit svelte.config.js
`// change adapter-auto to adapter-static import adapter from '@sveltejs/adapter-static'; ... // add prerender entries kit: { adapter: adapter(), prerender: { entries: ['', '/edit/'] } } </code></pre> Disable SSR by creating src/routes/+layout.ts`
`export const prerender = true; export const ssr = false; </code></pre> Check your node.js version and make sure pnpm uses the correct one`
`$ node -v v18.15.0 // edit .npmrc $ vi .npmrc // add your version number as so use-node-version=18.15.0 </code></pre> Setup Tauri`
$ pnpm add -D @tauri-apps/cli $ pnpm tauri init // What is your app name? notes // What should the window title be? notes // Where are your web assets ..? ../build // What is the URL of your dev server? http://localhost:5173 // What is your frontend dev command? pnpm run dev // What is your frontend build command? pnpm run build </code></pre> Run the app
`// will be slow the first time running but after much faster $ pnpm tauri dev </code></pre>`
Setting up components</h2>
I recommend for beginners to go through the official Svelte tutorial here</a> to grasp its fundamentals.
This is an excerpt of what a component is:

In Svelte, an application is composed from one or more components. A component is a reusable self-contained block of code that encapsulates HTML, CSS and JavaScript that belong together, written into a .svelte file. The 'hello world' example in the code editor is a simple component. </blockquote>
I'll be creating two components inside of `src/lib</code>. One called Notes.svelte</code> will display all notes created. The other called CreateNote.svelte</code> will be a text box where we can add new notes.`
`Create src/lib/Notes.svelte</code>`
`<script lang="ts"> let title = "First Note"; </script> <div id="notes"> {title} </p> </div> </code></pre> Create src/lib/CreateNote.svelte</code>`
<script lang="ts"> let newNote; let newTitle; </script> <div id="new-note"> <h1> Create a Note </h1> <textarea bind:value={newTitle} id="new-note-title" placeholder="Note title"></textarea> <textarea bind:value={newNote} id="new-note-box" placeholder="Note body"></textarea> </div> </code></pre> A page is a route to a certain path. src/routes/+page.svelte</code> will be the homepage, for instance. Import the components into the page by editing src/routes/+page.svelte</code>
<script lang="ts"> import Notes from '$lib/Notes.svelte' import CreateNote from '$lib/CreateNote.svelte' </script> <div id="container"> <CreateNote/> <Notes/> </div> </code></pre> You could place CSS style tags into each Page or Component, but I prefer a global CSS file. Create static/global.css</code>
/* CSS reset / , ::before, ::after { box-sizing: border-box; } * { margin: 0; } html, body { height: 100%; } body { line-height: 1.5; -webkit-font-smoothing: antialiased; } img, picture, video, canvas, svg { display: block; max-width: 100%; } input, button, textarea, select { font: inherit; } p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; } #root, #__next { isolation: isolate; } /* Component and Page CSS / #container { box-sizing: border-box; width: 100%; height: 100%; display: flex; white-space: nowrap; } #notes { background: #eee; } </code></pre> Add it to src/app.html</code> inside of the head tag
`<link rel="stylesheet" type="text/css" href="%sveltekit.assets%/global.css"> </code></pre> I'll be saving the notes in the frontend. For this we require Tauri's frontend API.`
`$ pnpm add -D @tauri-apps/api </code></pre> We must tell Tauri which paths are available to our app. In this case I'll be writing to a file called db.bson in the user's home/notes-db directory. Edit src-tauri/tauri.conf.json</code>`
"tauri": { "allowlist": { "all": false, "fs": { "scope": ["$HOME/notes-db/", "$HOME/notes-db"], "all": true }, "path": { "all": true } }, </code></pre> Also scroll down in the conf.json file and find "identifier" . It should be unique to your app. I'll set it to com.random.random.
"bundle": { "identifier": "com.random.random", } </code></pre> Handling data in the backend</h2> I've chosen to store the data as bson (Binary JSON). Read more about bson here</a>. Basically it's how MongoDB stores JSON data on disk as binary. Tauri lets the frontend pass data back and forth to the backend (Rust) using Tauri commands. For the sake of brevity I'll just show the complete Rust backend code. Edit src-tauri/src/main.rs</code> with: #![cfg_attr( all(not(debug_assertions), target_os = "windows"), windows_subsystem = "windows" )] use bson::{Document}; use serde::{Serialize, Deserialize}; use std::io::{Cursor}; use serde_json; #[derive(Serialize, Deserialize, Debug)] struct Note { bson_uuid: String, date_time: bson::DateTime, title: String, body: String, } // builds a new Note object for the froteend // we then convert it to a bson document // lastly we convert it into a vec of bytes to store on disk (frontend handles appending then saving this to disk) #[tauri::command] fn saveNote(title: &str, body: &str) -> Vec<u8> { let note = Note { bson_uuid: bson::Uuid::new().to_string(), date_time: bson::DateTime::now(), title: title.to_string(), body: body.to_string() }; let note_doc = bson::to_document(&note).unwrap(); return bson::to_vec(&note_doc).unwrap(); } // after the frontend edits or deletes a note // it must be saved back to db.bson #[tauri::command] fn editNote(data: &str) -> Vec<u8> { let vecNotes: Vec<Note> = serde_json::from_str(data).unwrap(); let vecDocs: Vec<Document> = vecNotes.iter().map(|e| bson::to_document(&e).unwrap() ).collect(); let docsArray: Vec<u8> = vecDocs.clone().into_iter().flat_map(|e| bson::to_vec(&e.clone()).unwrap()).collect(); return docsArray; } // loading the raw data from db.bson requires us to convert it to JSON // for the frontend to interact with #[tauri::command] fn loadNotes(data: &str) -> String{ // check if database is empty. // Return if it is otherwise the program will crash if data.chars().count() == 0 { return String::from("no data"); } // frontend passes the database as a string array of bytes // parse it into bytes let mybytes: Vec<u8> = data .trim_matches(|c| c == '[' || c== ']') .split(',') .map(|s| s.parse().unwrap()) .collect(); // now we iterate through the bytes and convert it // to a Vec of bson Document let mut curs = Cursor::new(mybytes); curs.set_position(0); let array_len = curs.get_ref().len() as u64; let mut docs = Vec::new(); for _ in 0..array_len { match Document::from_reader(&mut curs) { Ok(doc) => {println!("{} \n\n", doc); docs.push(doc);}, Err(e) => { println!("Error {:?}", e); break; } } } // return to the frontend an array of bson documents as JSON return serde_json::to_string(&docs).unwrap(); } fn main() { tauri::Builder::default() .invoke_handler(tauri::generate_handler![saveNote, editNote, loadNotes]) .run(tauri::generate_context!()) .expect("error while running tauri application"); } </code></pre> I create a Tauri app with three functions available to the frontend: saveNote, editNote, loadNotes saveNote will be called from the frontend and be passed two values: title, body. I then create a new Note struct with those values then convert it to a bson::Document. Lastly I convert the document to a bson::Array (Vec of bytes) and return it to the frontend to handle storing it to disk. editNote receives from the frontend an updated/modified version of the data stored on disk. The frontend requires this function to rebuild the bson database. We then return the binary bson back to the frontend to store to disk. loadNotes takes what's stored on disk "[123],[100],etc.." and converts it to JSON for the frontend. Also, edit src-tauri/Cargo.toml</code> to include bson as a dependency [dependencies] bson = {version = "2.6.0"} </code></pre> Handling data in the frontend</h2> Svelte's writable</a> store allows each component or page to individually modify/read a global state. Whenever it changes, all components get the newly changed value. Create and edit src/lib/store.js</code> import { writable } from 'svelte/store'; import { homeDir, join } from '@tauri-apps/api/path'; import { exists, BaseDirectory, createDir, writeBinaryFile, readBinaryFile } from '@tauri-apps/api/fs'; import {invoke} from '@tauri-apps/api/tauri'; // This value gets initialized when loadStore() is called // contains all bson stored on disk but as JSON export const myStore = writable({}); // initialize myStore with the contents in the database // let Rust convert the binary to an array of JSON export async function loadStore() { let binData = await readBinaryFile('./notes-db/db.bson', {dir: BaseDirectory.Home}); invoke('loadNotes', {data: binData.toString()}).then((dat) => { myStore.set(JSON.parse(dat)); }); } // send the updated JSON to the backend as a string // the backend converts it to an array of bson documents as bytes and we store it to db.bson export async function editStore(newVal) { let jsonToString = JSON.stringify(newVal); // send the updated store to the backend invoke('editNote', {data: jsonToString}).then((dat) => { // store the updated bson to disk let data = new Uint8Array(dat); writeBinaryFile('./notes-db/db.bson', data, {dir: BaseDirectory.Home}); loadStore(); }); } </code></pre> Edit src/routes/+pages.svelte</code> to call loadStore from above. Also to pass the store to the components. <script> import { myStore, loadStore } from '$lib/store.js'; import { homeDir, join } from '@tauri-apps/api/path'; import { exists, BaseDirectory, createDir, writeBinaryFile, readBinaryFile } from '@tauri-apps/api/fs'; import {invoke} from '@tauri-apps/api/tauri'; import { onMount } from 'svelte'; import Notes from '$lib/Notes.svelte' import CreateNote from '$lib/CreateNote.svelte' var db; // gets called whenever the page/component gets mounted onMount(async () => { // get the user's home directory let home = await homeDir(); // append the directory we'll create db = await join(home, 'notes-db'); // check if notes-db directory exists. If not then create it let checkDB = await exists('notes-db', {dir: BaseDirectory.Home}); if (!checkDB) { // if the directory doesn't exist then create it await createDir('notes-db', {dir: BaseDirectory.Home, recursive: true }); } // check if db.bson exists. If not then create it. let checkFile = await exists('./notes-db/db.bson', {dir: BaseDirectory.Home}); if (!checkFile) { await writeBinaryFile('./notes-db/db.bson', new Uint8Array([]), {dir: BaseDirectory.Home}); } // load myStore with what's on disk loadStore(); }); </script> <div id="container"> <CreateNote/> / Pass myStore to the component / <Notes allNotes={$myStore} /> </div> </code></pre> Edit src/lib/Notes.svelte</code> <script lang="ts"> // This value gets bound to myStore // <Notes allNotes={$myStore}> export let allNotes; // bson stores Date as milliseconds // Convert the date from milliseconds to human readbale function numToDate(num) { let toInt = parseInt(num, 10); let date = new Date(toInt); let options = { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', }; return date.toLocaleString(undefined, options); } </script> // Loop through each note and render it <div id="notes"> {#if allNotes.length > 0} {#each allNotes as note } <div id="note"> <a href="/edit/{note.bson_uuid}">Edit</a> {note.title} </p> { numToDate(note.date_time.$date.$numberLong) } </p> </div> {/each} / either still loading or no data exists / {:else} Try saving a note</p> {/if} </div> </code></pre> Edit src/lib/CreateNote.svelte</code> <script> import { invoke } from '@tauri-apps/api/tauri' import { loadStore } from '$lib/store.js' import {BaseDirectory, writeBinaryFile, readBinaryFile} from '@tauri-apps/api/fs' // bound to value of title textarea let newNote; // bound to value of body textarea let newTitle; // This isn't bound to $myStore as above // This gets assigned the raw binary stored on disk let allNotes; async function save(){ // sets allNotes to contain the binary stored on disk await load(); // Let the backend handle creating a new binary document invoke('saveNote', {title: newTitle, body: newNote} ).then((response) => { // Here I simply merge the returned data with allNotes let loaded = new Uint8Array(allNotes); response = new Uint8Array(response); let mergeArray = new Uint8Array(loaded.length + response.length); mergeArray.set(loaded); mergeArray.set(response, loaded.length); // and save it to disk writeBinaryFile('./notes-db/db.bson', mergeArray, {dir: BaseDirectory.Home}); // after saving, reload writable myStore with saved data on disk loadStore(); // empty textarea contents after save newNote = ""; newTitle = ""; }); } async function load() { allNotes = await readBinaryFile('./notes-db/db.bson', { dir: BaseDirectory.Home}); } </script> <div id = "new-note"> <h1> Create a note </h1> <button on:click={save}>Save</button> <textarea bind:value={newTitle} id="new-note-title" placeholder="Note title"></textarea> <textarea bind:value={newNote} id="new-note-box" placeholder="Note body"></textarea> </div> </code></pre> Lastly, I'll create another page that will be used to let the user edit a note. [slug] will be the note's UUID. Create src/routes/edit/[slug]/+page.svelte</code> <script> import { myStore, editStore } from '$lib/store.js'; import { page } from '$app/stores'; import { onMount} from 'svelte'; let oneNote; let oneNoteBody; let oneNoteTitle; let slug; function save(){ let currentStore = $myStore; // get the index of the current note that we're editing let index = currentStore.findIndex(item => item.bson_uuid === slug); // grab the values for editing let updatedObject = {...currentStore[index]}; // edit the values with what's in the textareas updatedObject.title = oneNoteTitle; updatedObject.body = oneNoteBody; // update the store myStore.update(store => { let updatedStore = [...store]; updatedStore[index] = updatedObject; return updatedStore; }); // save to disk editStore($myStore); } // deletes this note function del() { // filter out this note in myStore myStore.update(objects => objects.filter(obj => obj.bson_uuid !== slug)); // give the updated store to the backend editStore($myStore); // redirect to / window.location.href="/"; } // check the slug to match a UUID in myStore onMount(async () => { slug = $page.params.slug.toString(); $myStore.forEach(element => { if (element.bson_uuid === slug) { // grab the values and render them to the DOM oneNote = element; oneNoteTitle = element.title; oneNoteBody = element.body; return; } }); }); </script> <div id = "new-note"> <h1> Edit note </h1> <a href="/" id="home-button">BACK</a> <button on:click={save}>Save</button> <button on:click={del}>Delete</button> <textarea bind:value={oneNoteTitle} id="edit-note-title"></textarea> <textarea bind:value={oneNoteBody} id="edit-note-box"></textarea> </div> </code></pre> Done</h2> Running the following command will build the app into a binary located at src-tauri/target/release/</code> pnpm tauri build </code></pre> My binary says it's at 10M, but I get it down to 3.0M by using UPX</a> $ upx notes </code></pre> For cross platform compilation check out the official Tauri docs</a>. Here is the complete code on Github</a> Final notes</h3> My initial goal was to have drag and drop functionality of images or videos. This would have made this tutorial way longer which is not my goal. I chose to store the data as bson (binary JSON) as I was planning to store the images/videos as blobs. I'm not sure that this would even work as MongoDB's docs</a> mention that a bson document can only store 16MB. I guess something like IndexedDB would serve my goals better.

Wrap up</h3>
The main benefits of using Podman over Docker are security related. I won't rehash it all here so if you want to learn more check out linode's explanation</a>.</p>
I suggest learning more about plug and its router from elixirschool</a>.</p>

Getting Started with SurrealDB 2 and Axum for Web Development

How to Properly Learn Rust Programming

Dockerless, Elixir Web Application using Podman and Plug

Using Rust, Tauri, and SvelteKit to Build a Note Taking App

Security Hardening Linux OS

These are some extra steps that you can implement to harden a Linux system.</h2>

Using Rust, Axum, PostgreSQL, and Tokio to build a Blog

In this demonstration, we'll be using Axum to make a very minimal blog.</h3>

Storing the blogs written in markdown into PostgreSQL, and lastly using Askama to render those blog posts.</h3>
</p>

Getting Started with SurrealDB 2 and Axum for Web Development

Step 3. Write some Rust code</h2> Open src/main.rs and grab all the dependencies we added</p>

How to Properly Learn Rust Programming

Dockerless, Elixir Web Application using Podman and Plug

Connect to container and install Elixir:</h3> Make sure the container is running first:</p>

Wrap up</h3> The main benefits of using Podman over Docker are security related. I won't rehash it all here so if you want to learn more check out linode's explanation</a>.</p> I suggest learning more about plug and its router from elixirschool</a>.</p>

Using Rust, Tauri, and SvelteKit to Build a Note Taking App

In this blog post, I'll be guiding you through the process of building a note taking app using Tauri. Move over Electron :)</h2> </p> Tauri allows us to build fast, cross-platform, and small sized apps using HTML, CSS, and JavaScript.</p>

Done</h2> Running the following command will build the app into a binary located at src-tauri/target/release/</code></p>

Security Hardening Linux OS

These are some extra steps that you can implement to harden a Linux system.</h2>

ICMP tunneling</h3> ICMP is another protocol that can be abused by an attacker to exfiltrate private data. It can also be abused as a DDoS attack.</p> In Fedora ICMP's echo request/ echo reply can be disabled with the firwall:</p>

Hardening the Kernel</h3> The simplest way to pass arguments to the kernel is with sysctl.</p> Simply edit /etc/sysctl.conf</code></p>

Using Rust, Axum, PostgreSQL, and Tokio to build a Blog

In this demonstration, we'll be using Axum to make a very minimal blog.</h3>

Storing the blogs written in markdown into PostgreSQL, and lastly using Askama to render those blog posts.</h3> </p>

Setup up a new project</h2> Create a Rust binary (--bin is default and we could omit)</p>

A brief introduction to Tokio and Axum</h2> Let's unpack Axum and Tokio a bit.</p>

Inserting markdown into the database</h2> I suggest creating a new binary where we simply pass it a title and a markdown file as arguments.</p> Edit Cargo.toml to include a second binary that will insert a markdown file into the database</p>

Wrap up</h3>
The main benefits of using Podman over Docker are security related. I won't rehash it all here so if you want to learn more check out linode's explanation</a>.</p>
I suggest learning more about plug and its router from elixirschool</a>.</p>

Storing the blogs written in markdown into PostgreSQL, and lastly using Askama to render those blog posts.</h3>
</p>