splash
Live pages in the style of Phoenix LiveView. The server renders a view to HTML, and the page keeps
itself current: new state, other visitors' actions and, under auk run --live, saved code all show
up in open tabs within a moment. Buttons, forms and inputs send events to the server, and its
answer updates the page at once. There's no reload and no flash, and the page is patched node by node, so
focus, half-typed input and the scroll position all survive updates.
Effects: net (for serve). Depends on http, url and hash.
fn view(): str uses time = "<h1>It is {time.now()} ms</h1>"
fn main(): int! uses net, time {
await splash.serve(8080, "clock", _ => view())? // open tabs tick along by themselves
0
}
Events
Mark elements in your view, and handle what comes back:
<button splash-click="like">❤ 3</button>
<button splash-click="delete" splash-value="42">delete</button>
<form splash-submit="sign"><input name="name"><button>sign</button></form>
<input splash-input="search" placeholder="search…"> <!-- as you type, 250 ms after a pause -->
<input splash-input="q" splash-debounce="500"> <!-- …or after 500 ms -->
<select splash-change="sort"><option>new</option><option>old</option></select>
<input type="checkbox" splash-change="done" value="7"> <!-- "7" when checked, "" when not -->
fn handle(req: http.server.Req): http.Resp {
match splash.event(req) {
some(splash.Click("like", _)) => likes.send(Like)
some(splash.Submit("sign", fields)) => book.send(Sign(fields.get("name") else ""))
some(splash.Input("search", text)) => query.send(text)
some(_) => {}
none => if splash.is_visit(req) { count_a_visit() }
}
splash.reply(req, "my site", render()) // the new view goes straight back to the page
}
Add http to your own [deps] too, so you can name http.server.Req. A dependency's types aren't
visible to its users.
While an event is waiting on the server, the element that sent it (button, form, select) has the
class splash-loading and aria-busy="true". Clicks and submits on a busy element are ignored, so
a double click counts once. BASE_CSS dims busy elements; style .splash-loading for a spinner.
Security. Other sites can't send events on a visitor's behalf. Every event must carry the
x-splash header: a cross-site form can't set it, and a cross-site fetch with it needs a CORS
preflight that this server never grants. event also rejects any Origin that isn't this host.
Still escape what users typed before showing it (escape).
API
enum Event { Click(name, value), Submit(name, fields), Input(name, value), Change(name, value) }: something the user did.Click: asplash-click="name"element was clicked;splash-valuegivesvalue, else "".Submit: asplash-submit="name"form was submitted, with its fields as{str: str}.Input: the user typed in asplash-input="name"field. It's sent once typing pauses (250 ms, orsplash-debounce="ms"), with the field's text.Change: asplash-change="name"field changed. A select gives its value; a checkbox or radio gives its value when checked and "" when not.
event(req): Event?: the event a request carries, if any. Events from another origin arenone.is_poll(req): bool: is this an open page refreshing itself?is_visit(req)is neither a refresh nor an event. Do a visit's side effects only for visits.reply(req, title, view): http.Resp: the answer to any request for a live page. It sends the whole page, except for a refresh whose view hasn't changed, which gets a bare204.serve(port: int, title: str, view: (http.server.Req) => str): ()!: serves live pages onportforever withreply. Handleevent(req)insideview. Run it undersupto restart it if it crashes.struct Page { title, css, links, every }, built withtitled(title)(withBASE_CSS, no links,EVERYms) and.with_css(css),.with_link(href),.with_every(ms).answer(req, page, view)is the answer to any request for a live page.render(page, view)gives the whole HTML.static(req, read: (str) => str?): http.Resp?andasset(name, text): str: static text files underSTATIC(/static/), with content-versioned URLs (see above).page(title, view): strandpage_every(title, view, every): a whole HTML page withviewas its live part (<main id="splash">) and the client, refreshing everyeveryms (defaultEVERY, 500), styled withBASE_CSS.respond(title, view)wraps that page in a 200 response.styled(title, css, view): str,styled_every(…, every)andreply_styled(req, title, css, view): the same with your own stylesheet, which goes in<head>as<style id="splash-css">. Build on the defaults withsplash.BASE_CSS + mine, or pass""for no CSS.BASE_CSS: the default stylesheet. It gives readable system type, a centered column, plain buttons and inputs, works in light and dark mode, and shows a "reconnecting…" badge while the server is away.script(every: int): str: just the client, for a page you build yourself (its live element needsid="splash").struct Hub,hub(),run_hub(h): ()!,changed(h),stream(req, h): http.server.Reply?andPage.with_hub(h): push (see above).sessions(): Sessions,run_sessions<S>(s, init: () => S, update: (S, Event) => S, view: (S) => str, max: int): ()!,ask(s, req): strandsession_id(req): str?: state per browser session (see above).enum Log { Quiet, Info, Debug },log_level(name): Log, andwith_log(level)on aPage, aHubandSessions: logging (see above).escape(s: str): str: HTML-escapes& < > " '. Put anything a user typed through this.
CSS
let CSS = splash.BASE_CSS + r"""
body { background: #fdf6e3; }
.like { font-size: 1.2em; }
"""
splash.reply_styled(req, "my site", CSS, view)
The stylesheet is live, like the view. Under auk run --live, change a color and save, and open
tabs restyle at their next refresh with no reload. A refresh only gets the page back when the view
or the CSS changed. Use a raw string (r"""…""") for CSS, so its braces aren't read as
interpolation. A <style> inside the view works too, but it's sent with every changed view.
Push
With a hub, open pages don't wait for their next poll. A Server-Sent Events stream tells them to
fetch the moment something changes: after any event, after splash.changed(hub) (for changes no
event caused, such as timers or background jobs), and after each auk run --live reload.
Polling drops to a 5 s fallback.
let hub = splash.hub()
// kids: sup.child("hub", () => splash.run_hub(hub)), and a web child serving with serve_live:
fn handle(req: http.server.Req, hub: splash.Hub): http.server.Reply {
match splash.stream(req, hub) { // the pages' push streams
some(r) => return r
none => {}
}
http.server.Whole(splash.answer(req, splash.titled("my site").with_hub(hub), render()))
}
// await http.server.serve_live("", 8080, req => handle(req, hub))
Streams need http.server.serve_live, which gives each connection a task of its own. The plain
serve answers one connection at a time, so a held-open stream would block everyone else. The hub
keeps idle streams alive with a comment every 15 s, and drops a page's stream once its connection
is gone.
Sessions: a task per browser
State that belongs to one visitor (a cart, a draft, "your clicks") lives in a task of that visitor's own, LiveView's model. You write it as three functions: where a session starts, how an event changes it, and how it looks.
struct Mine { clicks: int }
fn update(m: Mine, splash.Click("mine", _)): Mine = Mine { clicks: m.clicks + 1 }
fn update(m: Mine, _: splash.Event): Mine = m
fn view(m: Mine): str = "<button splash-click=\"mine\">clicked {m.clicks}</button>"
fn main(): int! uses net, time {
let mine = splash.sessions()
let kids = [
sup.child("sessions", () => splash.run_sessions(mine, () => Mine { clicks: 0 }, update, view, 1000)),
sup.child("web", () => web(mine)), // its handler: splash.answer(req, look, splash.ask(mine, req))
]
sup.run(kids, sup.one_for_one(10, 60_000))?
0
}
- Identity. The page's script gives the browser a random session id in a cookie
(
splash-sid, fromcrypto.randomUUID()). A first visit, before the cookie exists, sees a fresh state, and the page asks for its own session's view right away. ask(sessions, req)sends the request's event to its session and returns that session's view. It waits at mostASK_WAIT(5 s); if the session is being restarted, it returns a short notice and the next refresh asks again.run_sessions(sessions, init, update, view, max)runs every session (run it undersup). Each session is a task with its own heap. A panic inupdateorviewstarts that one session over frominit(), and other visitors don't notice. Pastmaxsessions, the least recently used one stops.- With
auk run --live, changing the session state's shape (say, adding a field toMine) restarts only the session tasks; everything else keeps running.
Pages, linked stylesheets and static files
A Page is everything about a page apart from its view: its title, CSS, links and refresh interval.
fn read_static(name: str): str? uses fs = match fs.read("static/{name}") {
ok(text) => some(text)
err(_) => none
}
fn handle(req: http.server.Req): http.Resp uses fs {
match splash.static(req, f => read_static(f)) { // /static/… files
some(r) => return r
none => {}
}
let look = splash.titled("my site")
.with_css(splash.BASE_CSS + MINE)
.with_link(splash.asset("site.css", read_static("site.css") else "")) // /static/site.css?v=…
.with_link("https://cdn.example/lib.css")
splash.answer(req, look, render())
}
static(req, read)serves/static/<name>using yourreadfunction, sosplashitself never touches the file system and needs nofseffect. Unsafe names (.., a leading/, an empty segment) get 403, missing files 404. Files are text only (CSS, JS, SVG, JSON, HTML), sincehttpbodies are text.asset(name, text)is the file's URL with a content hash (?v=…). Versioned URLs are cached for good. Because you build the page on every request, an edited file gets a new URL, and open pages switch to it at their next refresh. That's live CSS from a plain.cssfile, withoutauk run --liveeven noticing.- Links are live too: adding, dropping or re-versioning a link reaches open pages without a reload.
Lists that reorder
When a view changes, the page is patched node by node. Children with a splash-key (or an id)
are matched by key wherever they moved; the rest are matched by position. Give list items keys:
"<ul>{items.map(i => "<li splash-key=\"{i.id}\">{splash.escape(i.name)}</li>").join("")}</ul>"
Then inserting at the top moves the existing rows instead of rewriting every one, so an input or
an open <details> inside a row stays with its row.
Logging
When a page and the server disagree, turn on logging and watch both sides:
let log = splash.log_level(env.get("SPLASH_LOG") else "") // "info" or "debug"
let hub = splash.hub().with_log(log)
let mine = splash.sessions().with_log(log)
let look = splash.titled("my site").with_hub(hub).with_log(log)
- Server (stderr): at
Info, every visit, event and change shown, as in75bbccf2#4 POST / event Submit("sign", {"name": "Ann"}) -> 200 view 1318231027-3710048048, plus pages joining and leaving the hub and sessions starting and stopping. AtDebug, also every refresh (including the empty204answers) and every push. - Browser (console): the page logs at the same level. A visitor can change their own page's
level with
splash.log("debug")in the console, and it's remembered for that browser. You see every request with its number (#4 -> event {...}), every answer and what it did (#4 <- 200 in 5 ms: view …, 3 change(s), ordropped: a newer answer is on the page), each push, and atDebugthe list of changes the patch made, such astext #splash > p > button[splash-click=like]: "❤ 0" -> "❤ 1". - Matching the two: the console's "started" line names the session (
75bbccf2); that tab's request#4is75bbccf2#4in the server log.
Self-check. After every patch, the page compares itself with the server's view. If they differ, which would be a bug in the patcher, it logs a warning naming the first difference (always, at any level) and replaces the live element with the server's version, so the page doesn't stay wrong.
How it works
- Refreshes. Every
everyms the page fetches its own URL in the background, sendingx-splash: polland a fingerprint of the view it shows. If the view is the same, the server answers204with no body; otherwise it sends the page and the client patches#splashin place. - Events. A click, submit, input or change is a form-encoded
POSTto the same URL withx-splash: event. The response is patched in the same way, without waiting for the next refresh. - Ordering. Every request is numbered, and an answer older than the one already on the page is dropped, so a slow refresh can't undo a click that was answered after it.
- Patching. The client walks the old and new live element together, changing only the text, attributes and nodes that differ. An input being typed in is never replaced, so it keeps its focus, cursor and text.
- Event fields show the server's state. A field with
splash-changeorsplash-inputalso gets its live state set (selectedIndex,checked,value), not just its attributes. Browsers stop applyingselectedto an option once the user has picked it, so without this a dropdown could stay stuck on an old choice. A dropdown, checkbox or radio always follows the server: its choice was sent the moment it was made, and it keeps focus long after. A text field is spared only while it's being typed in (focused, in a focused window). Plain form fields, such as an unsent draft, are left alone. - Ordering. Answers to requests sent before the latest event are dropped, so a refresh that raced your click can't briefly show the old state.
- Hidden tabs don't poll; they catch up as soon as they're visible again.
- Server unreachable (for example, while it restarts):
<html>gets the classsplash-offlineand polling backs off up to 5 s. Style it to show "reconnecting…". The last view stays on screen.
Without a hub that's all polling. With one (see Push), pages also listen on a stream and fetch the moment the hub says so.
See examples/live-site for splash together with sup and
auk run --live.