Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

Data, Files and Jobs

An app that uses none of this pays nothing.

Tables

// src/db.rs
pub static USERS: Table<User> = Table::saved("users")
    .unique("email", |u: &User| &u.email) // no two rows share it
    .migrate(|row| {
        // old rows, as they are read
        if let Some(m) = row.as_object_mut() {
            for (k, _) in m.iter_mut().filter(|(k, _)| k == "mail") {
                *k = "email".into();
            }
        }
    })
    .live(); // each change is sent on channel "users"
  • set(id, v) -> Option<()> replaces a row. clear() removes every row (ids are not reused).
  • unique: by(&email) finds the row without a scan. A unique Email field matches ASCII case aside; any other unique value matches byte for byte.
  • Every write returns a Result, so an action can ? it: USERS.update(id, |u| u.name = name)?;. add, set, update and add_unless give a 422 on the field for a taken value (email: is taken) or a broken rule, and a 500 for an unhashed Password or a failed store. remove and clear give a 500 when the store fails. set, update and remove of a missing id are a 404. has(id) and get(id) ask without a 404. A failed call changes nothing.
  • Every table the build knows is read at start. An unreadable store, or two tables with one name, stops the server with the reason. A table first used later with an unreadable store has no rows and answers each change with a 500; it is retried a second later.
  • A saved table checks a row against its type's #[validate] rules on add and change. #[derive(Rest)] routes do the same.
  • #[model] makes the struct and its fields pub and derives Json, FromJson and Clone. A model with a borrowed field (name: &'static str) derives no FromJson.
  • On a #[model] field: #[unique] is the same as .unique(..). #[json(default)] or #[json(default = expr)] fills a field old rows lack. #[json(was = "old")] reads it under its old name.
  • #[json(skip)] on a field keeps it out of the JSON, the TypeScript and the OpenAPI schema. Use it for a secret, such as a token. A body or a form cannot set it: it gets its #[json(default = ..)] value, else Default::default(). A saved table keeps it: the store has every field, and a row reads back with its value. A queued job, put_json/get_json of a KV store and the rows of a SQL database keep it too. Store a value with put_json, not a raw body: get_json, all, first and a job read skipped keys from the stored text, so a raw client body stored with put can set them. It works only on a named field of a struct: on the type, it stops the build. A skipped field takes no #[validate(...)]: that stops the build too. With #[cfg_attr(cond, json(skip))], the OpenAPI schema and the form leave the field out even when cond is false. A #[derive(Rest)] filter or sort cannot name it, and a PUT or PATCH keeps its value (its type must be Clone).
  • migrate(|v: &mut Value| ..) runs on each stored row's JSON when read (at load, and by WISP_STORE_POLL), before it becomes the type.
  • live() calls wisp::channel(name).send("change") after each change, only when someone listens. A page listens with listen('/users/events', invalidate), a +server.rs with wisp::channel("users").events(). A page that names a live table's static rows refreshes itself through /_wisp/live/<name>.
  • For several servers on one store, a Store can answer changes(table, since), and with WISP_STORE_POLL=5 (seconds) every table follows it.
  • Tables are whole in memory: the store's size is the RAM bound.

Rules

#[validate(url, one_of = "a b c", pattern = "[a-z]{3}-\\d+", with = ok)] beside len min max min_len max_len email.

  • url is an absolute http(s) address.
  • pattern matches the whole value (up to 1000 characters). It supports literals, ., [a-z_], [^x], \d \w \s, \n \r \t \f \v \0, \ before a sign that the browser takes (^$\.*+?()[]{}|/, and in a class also -&!#%,:;<=>@~), groups, |, ? * + {n} {n,m} (digits only), and ^ and $ at the ends, outside groups. . takes no line end, and \s is the browser's white space. Too much backtracking does not match. Valid input that needs more than 100000 steps does not match too: the check fails closed. Another escape (\b, A, \x41, \1, \- outside a class, \0 before a digit), ^ or $ in a group, a lone ] or }, or a class the browser's v flag reads otherwise ([], a [, && or -- inside one) stops the build. A literal pattern is also the pattern of the field that <form fields> writes, with a \ before each sign in a class ([a-z0-9-] becomes [a-z0-9\-]). So the browser's v flag reads the same sets as the server.
  • with = f calls f(&v) -> Option<String>, the problem.

Jobs

// init
wisp::work("mail", |m: Mail| async move { send(&m).await });
wisp::cron("0 3 * * *", || async { purge().await }); // UTC
// anywhere
wisp::queue("mail").push(&Mail { to, body })?; // .later(secs, &job)?; a store that fails is a 500
  • Use a few fixed queue names. Each lives as long as the process, so never make one per user; the payload says whose. Jobs live in the saved table queue-mail.
  • After a failure (Err or a panic), Wisp retries after 4, 8, 16... seconds (an hour at most), up to five tries, counted when each starts, so a job that kills the process is dead after five restarts. A dead job stays dead with its last error (queue.dead(), queue.retry(id), queue.drop_dead(id); retry revives only a dead job and returns false otherwise, and drop_dead deletes only a dead job and returns false otherwise).
  • Jobs run at least once, one at a time per queue, in order. A job running when the process died runs again a minute later. A running job's claim renews every 30 s, so servers sharing a store never run it twice at once.
  • cron takes five fields (*, n, a-b, */n, lists; Sunday is 0 or 7), in UTC. As in Vixie cron, a day field starting with * is not a restriction on the day. A minute that already ran never runs again; a run missed while the machine slept runs once on waking.
  • On Cloudflare, Vercel and Netlify (wisp build --target ...) the same code runs from the host's cron: wisp build writes each cron schedule (a string literal) into the trigger config, and a trigger also runs the queues' due jobs. Set CRON_SECRET and WISP_STORE there. See Edge and serverless targets.
  • On AWS Lambda the process freezes between invocations, so work, every and spawn run only while an invocation is answered. The build writes eventbridge.sh: an EventBridge Scheduler schedule per wisp::cron and one each minute for queues.
  • A worker whose store fails logs it and retries 5 s later. The job stays queued.

Cache

wisp::cache("top", 60, || async { top_posts().await }).await keeps an answer for 60 s per process (at most 1024 answers; per isolate on the edge; concurrent misses are not merged). wisp::uncache("/posts") forgets cache keys starting with it and the pages const CACHE keeps, on every worker, for /posts and below (/ is all). wisp::cache_tagged("top", 60, &["posts"], || async { top_posts().await }).await is the same, and wisp::revalidate_tag("posts") also forgets it. An answer made across that call is not kept. Tags are fixed names, so a tag per id is not possible: put the id in the key and call wisp::uncache("post:42"). wisp::stale_tag("posts") keeps the kept pages of the tag but marks them stale, as revalidateTag(tag, "max") of Next.js. The next request gets the stale page at once, and one refresh per page and worker thread makes it again in the background. On an error, the stale page stays until its CACHE and CACHE_STALE time ends. It drops cache_tagged answers and PPR shells of the tag, as revalidate_tag does. wisp::revalidate_path("/posts/1") drops the kept page at that path alone. It ignores any query, a last /, percent-encoding and the base path.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.