Tutorials / A guestbook, on a server

Tutorials

Tutorial: a guestbook, from soda new to running

This builds an app on Soda: Guestbook, one book that anyone who opens it can sign. Each note shows for everyone at once, its writer can take it back, and the whole book downloads as text. The finished app is in examples/guestbook, kept building and passing its browser tests with the SDK: when this page shows a file, that's the file.

It runs on Soda's server backend: the app is a program (axum underneath) that draws every page from what it keeps. The first paint is the server's own HTML, so a page reads with no script at all, and every open page holds one stream that the server draws it again on after any action, anyone's. A page is a function of what it reads and its address; there are no loaders, caches or client state to keep in step.

If you've used Next.js or SvelteKit, you know where everything is: a folder under src/routes is an address, a page.rs draws it, forms post to actions written beside it, and markup is JSX-like (view!). framework.md is the design behind it. Soda's other backend runs an app in each person's browser instead, local-first: local-first.md builds one, with the same pages.

What you need: Rust (with rustup: each app pins its toolchain) and Node 22.

1. A new app#

Install the SDK's CLI from a checkout of it, once:

cargo install --path soda/cli

Then make the app, and serve it:

soda new guestbook   # called Guestbook, from its folder's name
cd guestbook
soda dev

It starts as the SDK's server template: a checklist that everyone who opens it shares, kept in SQLite, which builds and passes its tests as it is. Open the address soda dev prints in two windows, and add an item in one: it's in the other at once, drawn again on its stream. Now change something in src/routes/layout.rs (the words under "Guestbook", say) and save. Both windows show it in about a second, without reloading, and the list is still there: soda dev runs the server under dx, which patches the change into it as it runs, so what it holds is kept (hot-patching.md).

What's there:

WhereWhat
src/list.rsWhat the server keeps: the list, in SQLite (data/checklist.db)
migrations/The database's schema, a file per change, run as the server starts
src/routes/The pages: a folder is an address, page.rs draws it, actions.rs is what its forms post
src/components.rsWhat the pages share, as #[component]s
src/main.rsThe program: soda_server::app! names what the server keeps
web/app.html, web/app.cssThe page shell, and the look: design tokens everything is drawn with
tests/e2e.mjsReal browsers, two people at once, end to end

The guestbook won't need the checklist's own parts: delete src/list.rs, src/components.rs, src/routes/items/, migrations/0001_items.sql, and web/components/ (and its import in web/kit.js). data/ is where the server keeps what it keeps (its database, the key its sessions are sealed with): delete it too, for a fresh start.

2. What the server keeps#

An app on a server names one type, its state: made once as the server starts, and shared by every request after (so it's Send + Sync). The guestbook's is the book: a connection pool to its SQLite database, in the app's data folder (soda_server::data(): data/ beside the crate, or SODA_DATA), which outlives the program. The schema is migrations/0001_entries.sql:

-- The book's entries: who signed, what they wrote, when (ms since 1970), and which session wrote it
-- (so it can take its note back).
CREATE TABLE entries (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    text TEXT NOT NULL,
    at INTEGER NOT NULL,
    by_session TEXT NOT NULL
);
CREATE INDEX entries_by_time ON entries (at);

and src/book.rs is the state, and every function the pages and actions call:

//! The book: its entries, newest last, kept in SQLite in the app's data folder (`guestbook.db`), so
//! they outlive the server: a restart, a deploy, a whole build under `soda dev`. Its schema is
//! `migrations/`, run as it opens. What's wrong with the database is said in the book's words (the
//! server's log has the rest), so a page or an action takes it with `?`.

use std::path::Path;

use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePool, SqlitePoolOptions};

/// One signature: who, what they wrote, when, and which session wrote it (so it can take it back).
#[derive(Clone, Debug, sqlx::FromRow)]
pub struct Entry {
    pub id: String,
    pub name: String,
    pub text: String,
    #[sqlx(try_from = "i64")]
    pub at: u64,
    #[sqlx(rename = "by_session")]
    pub by: String,
}

pub struct Book {
    db: SqlitePool,
}

/// The most a book keeps: the oldest go once it's full.
pub const MAX_ENTRIES: i64 = 500;

impl soda_server::App for Book {
    async fn start() -> Result<Self, Box<dyn std::error::Error + Send + Sync>> {
        Ok(Book::open(&soda_server::data().join("guestbook.db")).await?)
    }
}

impl Book {
    /// The book in `file` (made the first time), its schema brought up to date.
    pub async fn open(file: &Path) -> Result<Self, sqlx::Error> {
        let options = SqliteConnectOptions::new().filename(file).create_if_missing(true).journal_mode(SqliteJournalMode::Wal);
        Self::with(SqlitePoolOptions::new().connect_with(options).await?).await
    }

    async fn with(db: SqlitePool) -> Result<Self, sqlx::Error> {
        sqlx::migrate!().run(&db).await?;
        Ok(Self { db })
    }

    /// Its entries, newest last.
    pub async fn entries(&self) -> soda::Result<Vec<Entry>> {
        sqlx::query_as("SELECT id, name, text, at, by_session FROM entries ORDER BY at, rowid").fetch_all(&self.db).await.map_err(unavailable)
    }

    /// Signs the book; the oldest entries go once it's full.
    pub async fn sign(&self, entry: Entry) -> soda::Result {
        sqlx::query("INSERT INTO entries (id, name, text, at, by_session) VALUES (?, ?, ?, ?, ?)")
            .bind(&entry.id)
            .bind(&entry.name)
            .bind(&entry.text)
            .bind(i64::try_from(entry.at).unwrap_or(i64::MAX))
            .bind(&entry.by)
            .execute(&self.db)
            .await
            .map_err(unavailable)?;
        sqlx::query("DELETE FROM entries WHERE rowid NOT IN (SELECT rowid FROM entries ORDER BY at DESC, rowid DESC LIMIT ?)")
            .bind(MAX_ENTRIES)
            .execute(&self.db)
            .await
            .map_err(unavailable)?;
        Ok(())
    }

    /// Takes back the entry `id`, if `by` wrote it: whether it did.
    pub async fn take_back(&self, id: &str, by: &str) -> soda::Result<bool> {
        let done = sqlx::query("DELETE FROM entries WHERE id = ? AND by_session = ?").bind(id).bind(by).execute(&self.db).await.map_err(unavailable)?;
        Ok(done.rows_affected() > 0)
    }
}

/// What a page or an action says when the database fails it: the book's words, not the database's.
fn unavailable(error: sqlx::Error) -> soda::Error {
    eprintln!("guestbook: the database: {error}");
    "The book can't be reached just now. Try again in a moment.".into()
}

It's plain Rust and plain SQL (sqlx, which the template uses): the pages and actions only call entries, sign and take_back. Each says what's wrong with the database in the book's own words (unavailable), as a soda::Error, so a page or an action takes it with ? and its person reads something they can act on. start returning an error stops the server, saying why. Below the code (in the file), the book's tests run against a database in memory, with #[tokio::test]: it keeps the newest 500, and lets only a note's writer take it back.

src/main.rs names it:

//! A guestbook on Soda's server backend: one book, signed from any browser, drawn again for every
//! open page as anyone signs it. Its state is the server's (`book.rs`, in SQLite in its data
//! folder); each browser is a session, which remembers the name it signs with.

mod book;

soda_server::app!(book::Book);

app! reads src/routes as the crate compiles: the router, a typed link for every page (link::about()), and the app's Cx, Act and prelude. It writes the program's main too, which serves the app. Cargo.toml names sqlx (and tokio, for the tests); build.rs has Cargo build again when a migration is added.

3. The page#

src/routes/page.rs is /: the form, and everyone's entries, newest first.

//! `/`: the book. Sign it (the name is remembered for next time), and read everyone's entries,
//! newest first; one's own can be taken back. Every open page is drawn again as anyone signs.

use super::actions::{Sign, TakeBack};
use super::downloads::Everything;
use crate::prelude::*;

pub fn head(_cx: &Cx) -> Head {
    Head::title("The book")
}

pub async fn page(cx: &Cx) -> Result<View> {
    let entries = cx.state.entries().await?;
    Ok(view! {
        <h1 class="sr-only">"The book"</h1>
        <Card class="grid gap-4 p-5">
            <form action=Sign class="grid gap-4">
                <Field label="Your name" name="name">
                    <Input name="name" value=cx.recall("name") placeholder="Ada" required attr:maxlength="60" attr:autocomplete="name" />
                </Field>
                <Field label="Your note" name="text">
                    <Textarea name="text" placeholder="What brought you here?" required attr:maxlength="280" attr:rows="3" />
                </Field>
                <div><Button primary submit>"Sign the book"</Button></div>
            </form>
        </Card>
        <section class="grid gap-3" aria-label="Entries">
            <div class="flex items-baseline justify-between gap-3">
                <h2 class="font-display text-xl font-semibold">{match entries.len() { 0 => "No one yet".to_string(), 1 => "1 entry".to_string(), n => format!("{n} entries") }}</h2>
                {(!entries.is_empty()).then(|| view! { <a class="soda-btn soda-btn-quiet" href=Everything download>"Download them"</a> })}
            </div>
            {if entries.is_empty() {
                view! { <Empty title="Be the first">"Sign the book above: your note shows here, for everyone who opens it."</Empty> }
            } else {
                view! {
                    <ol id="entries" class="grid gap-3">
                        {entries.iter().rev().map(|e| view! {
                            <li class="entry grid gap-1.5 rounded-card bg-surface p-4 shadow-raised" data-entry=&e.id>
                                <p class="flex items-baseline gap-2">
                                    <strong class="name font-semibold">{&e.name}</strong>
                                    <span class="text-sm text-muted"><Time at=e.at /></span>
                                    {(e.by == cx.session.id).then(|| view! {
                                        <Button quiet small class="ml-auto" on:click=TakeBack(e.id.clone()) attr:aria-label=format!("Take back your note, {}", e.name)>"Take back"</Button>
                                    })}
                                </p>
                                <p class="text whitespace-pre-line">{&e.text}</p>
                            </li>
                        })}
                    </ol>
                }
            }}
        </section>
    })
}

The page is an async fn: it reads the database, and the server awaits it as it draws the page. A page reads two things beyond its address: cx.state, the book, and cx.session, the browser asking (each one gets a session, a cookie the server gives it). cx.recall("name") is what this session remembered under name: the name it last signed with, filled in for next time. The cookie holds the session too, sealed with a key the server keeps in its data folder, so a server that starts again (a deploy, a restart) takes each browser back as it was.

In view!, text is in quotes, Rust is in braces, and an attribute's value is any expression. Card, Field, Input, Textarea, Button, Empty and Time are Soda's components, drawn with the app's design tokens (reference.md has them all); <Time at=…/> shows "5 minutes ago" in the reader's own words and zone. head gives the page its title in the tab.

4. Signing: a form and its action#

A form names the action it posts to (action=Sign), and the action is written beside its page, in src/routes/actions.rs:

//! What the book's page posts to: signing it, and taking one's own note back.

use crate::book::Entry;
use crate::prelude::*;

#[derive(Form)]
pub struct Signing {
    #[form(max = 60)]
    pub name: String,
    #[form(max = 280)]
    pub text: String,
}

/// A note signed, under the name this browser remembers for next time.
#[action]
pub async fn sign(cx: &mut Act, form: Signing) -> Result {
    let entry = Entry { id: new_id(), name: form.name.clone(), text: form.text, at: soda_server::now_ms(), by: cx.session.id.clone() };
    cx.state.sign(entry).await?;
    cx.remember("name", form.name);
    cx.keep(&["name"]);
    cx.say("Signed the book.");
    Ok(())
}

#[derive(Form)] reads the form's fields into Signing: a field that's missing, or longer than its max, is shown under its field, and the action never runs. #[action] makes Sign, what the page names, and gives the action its address (/api/_/sign).

Then it signs the book, remembers the name for this session, keeps the name field filled as the form empties for the next note (keep), and says so: "Signed the book." shows as a toast on this browser's pages. Once an action is done, every open page is drawn again from the book as it is now, so in the other window the note is there already, with nothing written to make it so.

5. Whose note is it#

Each entry keeps the session that wrote it (by). The page shows "Take back" only on one's own (e.by == cx.session.id), but a page is only what it shows: anyone can post to an action, so the action checks it too.

/// One's own note, taken back.
#[action]
pub async fn take_back(cx: &mut Act, entry: String) -> Result {
    if !cx.state.take_back(&entry, &cx.session.id).await? {
        return Err("That note isn't yours to take back.".into());
    }
    cx.say("Took your note back.");
    Ok(())
}

A button's action takes its values as arguments: on:click=TakeBack(e.id.clone()) posts the id, and take_back gets it as entry. An Err with words is a refusal: its person is told, in those words, and nothing changes. Soda refuses a request from another site before any action sees it (a page of the app sends a header a form elsewhere can't).

6. Another page, and around them all#

A folder is an address: src/routes/about/page.rs is /about.

//! `/about`: what this is.

use crate::prelude::*;

pub fn head(_cx: &Cx) -> Head {
    Head::title("About")
}

pub fn page(_cx: &Cx) -> View {
    view! {
        <article class="grid gap-3 text-lg">
            <h1 class="font-display text-2xl font-semibold">"About this book"</h1>
            <p>"A guestbook on Soda's server backend. The server draws each page from what it keeps, and every open page holds one stream it's drawn again on whenever anyone signs."</p>
            <p><a class="font-semibold text-accent underline underline-offset-4" href=link::root()>"Back to the book"</a></p>
        </article>
    }
}

src/routes/layout.rs is drawn around every page, with the pages as tabs:

//! Around every page: the book's name, and its two pages as tabs.

use crate::prelude::*;

pub fn layout(cx: &Cx, children: View) -> View {
    view! {
        <header class="mx-auto mt-8 mb-6 grid w-full max-w-160 gap-4 px-4">
            <p class="font-display text-3xl font-bold tracking-tight">"Guestbook"</p>
            <Tabs label="Pages">
                <Tab href=cx.link(link::root())>"The book"</Tab>
                <Tab href=cx.link(link::about())>"About"</Tab>
            </Tabs>
        </header>
        <div class="mx-auto grid w-full max-w-160 gap-6 px-4 pb-16">{children}</div>
    }
}

link::about() is the page's typed link: a page that's renamed or removed is a compile error at every link to it, never a broken one. cx.link adds whether it's the page you're on, which the tab shows. A link moves the page in place: the stream draws it at its new address, and Back comes back. src/routes/not_found.rs is what an address the book doesn't have shows (the template's, reworded).

7. A download#

src/routes/downloads.rs:

//! The book, to keep: every entry as text.

use crate::prelude::*;

#[download]
pub async fn everything(cx: &Cx) -> Result<Download> {
    let text: String = cx.state.entries().await?.iter().map(|e| format!("{} ({}):\n{}\n\n", e.name, soda::ui::utc(e.at), e.text)).collect();
    Ok(Download::text("guestbook.txt", "text/plain", text))
}

A download reads what a page does, and the page links to it like any page (href=Everything download, in §3). Download::page is one shown in place instead, for printing.

8. The look#

web/app.css is the app's design tokens: every color, font, radius and shadow the views use (bg-surface, text-muted, rounded-card), and the build refuses any that isn't one. The guestbook warms the accent:

@theme {
  --color-accent: light-dark(oklch(0.55 0.15 40), oklch(0.78 0.12 50));
}

Save it with soda dev running and the open pages take the new sheet in place, in a fifth of a second. styling.md has the tokens and Soda's classes.

9. While it runs#

What soda dev does with each change, on the server:

You changeWhat happens
A page, a layout, a component, an actionPatched into the running server in about a second; every open page is drawn again from the new code, and the book, the sessions and the open pages are all still there
A new route (a folder, a file)Patched in the same way: dx is told of the file
The shell (web/app.html)The pages reload into it: the server reads it from disk while soda dev runs it
web/app.cssSwapped into the open pages in place
A type's shape (a field on Book)The server is built whole and starts again, and the pages reload: the book is still there (it's in the database), and so is each session
A mistakeIt doesn't build, or a file doesn't parse: said over the page, with where, until it's fixed. A page that panics shows the panic in its place, with where, and is drawn again once it's fixed

What the app prints (println!) is in soda dev's terminal.

10. Testing#

soda check   # cargo test (the book's tests, against a database in memory), Clippy, and the token check
soda test    # that, then the build and tests/e2e.mjs in real browsers

The guestbook's tests/e2e.mjs runs the built program on a free port and drives two people, one in Chromium and one in WebKit: the first paint is the server's HTML; Ada signs, and Bob's open page shows it without reloading; Ada takes her note back, and Bob can't take back hers; the About tab moves the page in place and Back returns; the download is the book; a reload keeps the remembered name; and the server starts again partway (a deploy), the book as it was and each browser still the writer of its own notes. It gives the server a data folder of its own (SODA_DATA), so each run starts with an empty book. Read it for the patterns (waiting on what the page shows, never on time).

11. Running it, and shipping it#

soda build            # dist/ (the site the program serves beside it) and target/release/guestbook
cargo run --release   # serves it on http://127.0.0.1:3000

That program, dist/ and a data folder are all a host needs: run it with SODA_ADDR set to the address it gives (0.0.0.0:8080, say), SODA_DATA where it keeps its data, and SODA_DIST if dist/ is somewhere else. soda deploy makes it a container image, and puts it on a server:

soda deploy --to ssh://you@your-server       # built for that server, run there on port 80
soda deploy --to ssh://you@your-server        # again, after a change: the book and the sessions stay
soda deploy                                   # just the image (guestbook:latest), to run anywhere
soda deploy --image registry.example.com/guestbook:1 --platform linux/amd64 --push

It stages the app and the copy of Soda it builds against, and compiles them inside the image's build with the toolchain the app pins, so it builds the same anywhere and needs no key to fetch the SDK. The image is the program and its site on a small base (about 150 MB), serving on 8080, its data folder a volume. --to takes any host Docker reaches (ssh://…, tcp://…): it builds for that host's platform, loads the image there and runs it in place of the one before, restarted if it stops, its data in a volume (guestbook-data) that every deploy keeps, so the book and every browser's session outlive it. A later deploy builds only what changed: 11 s after a one-line change to a page, the first one some minutes.

12. As it grows#

Three things a guestbook doesn't need yet, and a bigger app will:

  • More of a schema. A change to the database is a new file in migrations/ (0002_entries_by_name.sql), run once as the server starts; a page, a layout, a head or a download that reads the database is an async fn, as the book's page is.
  • Drawing fewer pages again. Every open page is drawn again after every action, which is right until it's a lot. A page says what it shows (cx.listen("book")), an action what it changed (cx.notify("book")), and then only the pages listening for it are drawn again (and the acting session's own).
  • Routes of its own. A webhook, a feed, a health check: App::routes returns axum's Router with the app's state, and a handler that changes what pages show takes Pages (pages.notify(["book"])). reference.md has an example.

Where next#

This page is docs/tutorial.md in the SDK, built into this site as it is.

Esc