You write a Lua file and publish it. It answers HTTP requests. That is the whole program. Storage, background work, scheduled work and live updates are declared in the file, never attached to it. Declarations kv "visits" declares that this script uses a key value namespace called visits . Databases, queues, workflows, object classes and secrets are declared the same way, at the top level of the entry point. A script can only reach what its declarations name. Ask for a namespace you never declared and the call fails. The platform derives the list by running your file with every surface stubbed out, then stores it with the revision. actias check prints the same list locally before you publish. What is available Surface Use it for kv small values read by name database SQL, migrations, queries across rows object one entity's state, serialized access, its own alarm queue retried background work workflow processes lasting minutes to days streams + sockets pushing events to objects and browsers secret versioned credentials on "cron:..." scheduled jobs Each has a chapter in [How it runs](/docs/runtime/requests) and a page in the [reference](/docs/reference/kv). Under construction. Surfaces change without notice. These docs describe what works today.

What Actias is

Actias is a durable execution engine with a Lua scripting layer on top. The engine runs units of work on a fleet of nodes, gives some of them an identity and a private database, and guarantees that anything it acknowledged survives the loss of the machine that produced it. The mechanisms are in [Internals](/docs/internals/cluster/topology). Units and objects Everything that runs is one of two things. A unit is a script handler run once for one cause: an HTTP request, a queue message, a cron tick, a workflow step. It has no identity. Any node can run it from the bundle it caches by hash. Nothing about it outlives the run except what it wrote elsewhere. Units scale by adding nodes. An object is a named entity with a mailbox and its own SQLite database. Auction("lot 42") names one. The platform assigns it a home node, runs its methods one at a time, and keeps its database durable. An object is an actor with three things the actor model does not give you: a real database instead of in memory state, durability without writing it yourself, and placement you never see. Units call objects. Objects call objects and publish to followers. Queues, workflows, connections, scheduled work and the directory are built from these two. What durable execution means here Four properties, each with a mechanism. Acknowledged means durable. A caller that was told "done" finds the work done after any single failure. Every reply from an object is held until the object's writes are safe off the machine: on a quorum of replica nodes that hold the write ahead log frames, or in the blob store's manifest when there are no replicas. A write's own reply waits. Every other reply from the object also waits while writes are in flight, because a read must not return state that may be lost. The cost is latency, not throughput: the mailbox keeps running while replies are held, and a burst of writes rides one flight and releases together. One writer, always. An object's file is written by one process at a time, chosen by a lease in a placement store and fenced by an epoch. A node that lost its lease without noticing cannot land a write: replicas refuse frames under a stale epoch, and the manifest check refuses them at the store. Failover replaces one writer with the next under a lease the store hands out. Primary backup under an external lease, as in Aurora, Kafka and Cloudflare's object storage. No consensus group per object. State outlives any node. The object's SQLite file is a leased cache. The truth is the shipped log: content addressed base chunks plus WAL segments in the region's bucket, indexed by a manifest. A new home restores from a live replica when there is one and from the bucket when there is not. Losing every node in a region loses nothing acknowledged, except what cross region storage replication had not yet copied. Retry is safe. Queues redeliver until a handler accepts. Workflows replay a journal rather than rerunning steps. A call whose outcome is unknown returns a typed unknown, not a guess. The actor model's problems, and what is done about them Objects are actors: one mailbox, one method at a time, private state, addressed by name. The model has four well known problems. Unbounded mailboxes. Actor frameworks let a hot actor's queue grow until memory runs out. An Actias mailbox holds 128 waiting calls. Callers past that wait; nothing is dropped; the wait shows up as latency. Connection inboxes are bounded the same way, and a connection that cannot keep up has its subscriptions severed. Lost messages. In memory actors lose their queue with the process. Here nothing an object was asked to do exists only in memory. A queue message is in a queue object's durable log. A delivery is a row in the publisher's log until the follower has it. An alarm is a row in the placement store until it fires. Work that was in flight when a node died is redone from those rows. Reentrancy and deadlock. An actor that calls another which calls back deadlocks. Every call

The engine

The tools The [download page](/download) has the same instructions. A local platform to publish to is one command in the repository root: Service Where api http://localhost:3001 console http://localhost:3000 worker http://localhost:3002 An account and a project Register at the console, http://localhost:3000/register . A local compose accepts registrations; a deployment with INVITE ONLY=true needs an invite from an admin. login asks for the server URL, which is the api origin ( http://localhost:3001 , no /api ), then your username or email and password. The login lives in your user config directory under actias/settings.json ; running login again replaces it. project create prints the project's id and the init line that uses it. A project owns scripts and everything they declare; kv namespaces, databases, objects and secrets are scoped to it. Project names are 6 to 36 characters. actias projects lists the ones you can reach; the console shows the same set. A script Argument Meaning auctions the folder to create basic the template: basic , router or todo ; omitted, the cli asks &lt;project id&gt; registers the script under the project, so script.json carries its id; omitted, the first publish asks What you get What it is main.lua the entry point script.json the script's id, its entry point, which files belong to the bundle, and an optional build command run before each publish tests/ tests actias test runs definitions/ the platform's types for your editor; rewritten by every check , publish and dev , so never edited .luaurc , .vscode/ point the editor at those definitions main.lua from the basic template: Check check runs the declaration pass the server runs at publish, then type checks every .lua file in the bundle. The printed list is the script's contract: kv namespaces, handled events, secrets, object classes, databases, queues, connections, workflows, lifecycle hooks, streams published and received, and migrations. The last line names the type checker that ran. Checker When What it sees language service actias luau is beside the binary, on your PATH, or named by ACTIAS LUAU resolves require against your bundle; a type crossing a module boundary is checked luau analyze a stock luau analyze is on your PATH resolves against the filesystem; every import is any none neither is installed the type check is skipped, with a warning actias luau is built from the repository's luau web/ directory; there is no packaged release of it yet. Gotchas A publish can still be refused for something check cannot see: another script in the project already declaring the same class, queue or workflow. Check in an editor actias lsp speaks the language server protocol over stdio and answers with the same checker as check . Diagnostics, hover, completion and go to definition resolve through your bundle, so a method call lands on the file that defines it. Attach it to .lua files in a directory holding a script.json . In Neovim: The server needs actias luau , found the same three ways check finds it; without it the server refuses to start and says so. Publish Only changed files upload. The server derives the contract from your code again and the revision goes live at / / : Run it live while editing dev opens a live session on the worker ( worker url , default http://127.0.0.1:3002 ) and prints its URL, / live/ / / . Every save in the project directory uploads the bundle again, so the URL always serves the file on disk. The script needs an id first, so init with a project id, or publish once. Something that remembers Declare a key value namespace at the top level and use it inside the handler: Publish again and refresh a few times. The counter survives requests, restarts and deploys, and the console's KV page shows it changing. Related [How a request runs](/docs/runtime/requests): the execution model, one concept per chapter. [The Lua reference](/docs/reference/kv): every namespace with signatures and examples.

Your first script

What a workflow is A workflow is a function that runs like ordinary code but can pause for days and resume where it stopped, including across crashes and deploys. Start a run with an id you choose. The id is the run's identity, so a retried start joins the run instead of making a second one: Replay Each step, signal and timer is journaled before it takes effect. A resuming run replays the function from the top, and steps that already ran return their recorded results instead of running again. Run code must take the same path given the same journal. The platform makes the usual sources of drift deterministic and refuses the rest: In run code Behaviour os.time() , os.clock() , math.random() , uuid.v4() journaled on first run, replayed identically secret "name" pinned to the version the run first resolved os.date , math.randomseed refused kv, database and object calls outside a step refused: effects belong inside wf:step http , crypto , Jwt absent, inside step bodies too Reach the network by calling an [object](/docs/runtime/objects) from a step. The step records what the object returned, so replay does not call again: Steps Option Default Means retries 1 total attempts, not attempts after the first; 0 is read as 1 backoff 2s wait before attempt 2, doubling after that, with no cap timeout none how long one attempt may run; past it the attempt fails with step 'name' timed out after Nms Step names must be stable across revisions, because replay matches recorded results to them by name. When a step exhausts its attempts the run parks as failed with step 'name' failed after N attempts , keeps its journal, and the console can resume it. Making an effect safe to repeat A step records its result after the body returns, so a crash in between leaves the platform unable to know whether the effect happened. wf.step id names the effect the body is performing, so the outside world can recognise a repeat: Across wf.step id a crash between the effect and its recorded result stays the same, so the repeat is recognised a retry after a recorded failure changes, because that attempt is a new effect the same step name reached again, in a loop changes, because each pass is its own effect outside a step body an error; there is no effect to name The same string works anywhere a repeat needs recognising: a row id, an object key, a filename. The [reference](/docs/reference/workflow) has its shape. Waiting Verb Returns sleep nothing; resumes after the duration await the signal payload, or nil on timeout race the payload and the name that arrived first; the others keep their signals consumable all payloads in argument order; a timed out entry is nil. The timeout is per entry, waited in order A parked run holds no resources. It is journal rows and a timer. Signals Signals come from outside the run, addressed by the run id: A run id is a non empty string without / . Choose it so a route can address the run without a lookup table. Duplicate signals are safe. An unconsumed extra is set aside rather than breaking replay, which matters because buttons get clicked twice. Inspecting The console lists runs with status and current step, shows the journal as a timeline, and offers resume for failed runs and cancel for the rest. Cancelling a run cancels the runs it spawned. Workflow or queue If anyone will ask how one specific job is doing, use a workflow: runs are named, inspectable and signalable, and each carries a journal. Otherwise use a [queue](/docs/runtime/queues): anonymous, cheap, retried in bulk. A queue handler can start a workflow when a message turns out to need one. Gotchas retries = 3 is three attempts in total, not one plus three. Steps do not nest. One effect per step; a wf:step inside a step body is an error. Renaming a step breaks runs already in flight. Replay compares the journal against the code it re executes, and a mismatch fails the run with journal divergence: expected step, code reached step 'other' rather than guessing. One script per proj

Workflows

Publishing An object declares its topics and publishes events on them. state:publish appends the event to this object's log in the same transaction as the write above it. An event therefore never describes a write that did not happen. Delivery runs after the call commits, along whatever edges exist. Publishing an undeclared topic is an error. Who may follow An edge exists only if the publisher accepted it. Spelling Who gets in bare name whoever the follow hook returns true for = "self" only an identity equal to this instance = "public" any identity neither nobody. A missing hook fails closed Use the hook when the answer depends on state: The follower argument is data, not a live handle: follower.name , follower.id , follower.transport ( "object" or "connection" ), and follower:is(SomeClass) for its class. When to use "self" "self" is the personal stream: a user's own notifications, reaching whichever of their devices is connected. A websocket's identity is minted server side after authentication, so a connection following Account("ada"):events genuinely is Account/ada ; anyone speaking as someone else is refused. Following and receiving receives keys are "Class:topic" . publishes and receives at the top of a class show both directions of its data flow. Verb Does state:follow(handle, topic, filter?) creates the edge; returns nothing, and raises follow refused when the publisher declines state:unfollow(handle, topic) removes it state:drop followers(Account(name)) removes every edge that identity holds state:followers(topic?) lists current followers, every topic when none is named; rows carry name , id , topic and transport The optional filter matches equality against top level fields of the event data, so one filtered edge replaces many topic specific ones. Delivery to objects Events reach a sleeping object. The publisher's log keeps them, the edge tracks how far the follower has read, and delivery wakes the follower. An account with nothing running receives every event for what it follows, in order. A new edge starts at the log's head: history is the publisher's state, reached by an ordinary method, never replayed down a fresh edge. Re following an existing edge keeps its cursor. The follower records the event's position in the same transaction as its handler's writes, so a redelivered event is skipped, not re run. An event whose "Class:topic" has no receives entry is consumed and discarded without error. Delivery to browsers Websocket connections are also followers, with weaker promises: at most once, no retry, and the edge dies with the tab. See [sockets](/docs/runtime/sockets). A connection that declares an event handler shapes each delivered event into its own frame. One that declares event = "forward" sends the platform envelope, { type = "event", topic, from, data } , without running any code. Keep anything that must survive on an object edge, one hop back from the connection. A device may miss a frame; the object does not miss the event. Gotchas Delivery to objects is at least once, with the follower's own writes protected by the cursor. Effects that leave the follower's transaction, a call to a third object or a kv write, can repeat after a crash mid handler; make those safe to run twice. Order holds per publisher, not across publishers. If order matters across sources, put a sequence number in the data. An edge that keeps failing is dropped after 8 attempts, 500 ms doubling to 32 s. It is not retried forever and it does not resume by itself. A delivery that runs past 10 seconds counts as a failed attempt. Related [Objects](/docs/runtime/objects): the entities that publish. [Sockets](/docs/runtime/sockets): connection edges and their weaker promises. [Guarantees](/docs/runtime/guarantees): every promise and limit in one table.

Streams

Key value [ kv ](/docs/reference/kv) maps keys to values within a namespace. Use it for small values read by name: flags, counters, cached summaries, session markers. It has no queries, so anything you store must be findable by key alone. SQL databases [ database ](/docs/reference/database) is a SQLite database with migrations. Use it for questions spanning many rows: joins, aggregates, filtered lists. Nothing else here answers those. Schema comes from the .sql files in the declared directory, applied at the first call that touches the database. Declare no directory and nothing is applied: see [migrations](/docs/reference/database migrations). Objects An [object](/docs/runtime/objects) is a named entity that handles one call at a time and owns a private database. Use it when state belongs to one entity, and when concurrent changes to that entity must not interleave. An object's database lives in one SQLite file that can grow to a gigabyte ( OBJECT DB MAX MB ; a write past the budget fails, reads keep working). Its durable copy is kept as content addressed chunks, so a large object that changes a little costs a little to keep durable: what ships after a write is what the write touched. Choosing Question Use Small value, looked up by name kv Search or join across many rows database State owned by one entity object Two simultaneous changes must not collide object Using both an object and a database is normal. An auction keeps its bid history in its own object and writes a row to a shared sales database when it closes. "What sold this week" spans lots. All three are durable, scoped to the project, declared in code, and browsable in the console. Gotchas An object's state.sql is private to that instance. No query spans instances, so "the top ten lots across every auction" needs a shared database. kv remembers the type you wrote. A number comes back a number, a boolean a boolean, a table a table. Nothing is stringified on your behalf. Related [Objects](/docs/runtime/objects): serialization, alarms, placement. [database](/docs/reference/database) and [kv](/docs/reference/kv): every method with signatures.

Where data goes

Declaring a connection A connection's program is a top level declaration, the same shape as an object class: named handlers for the wire's stimuli. Nothing calls a connection, so a body declares handlers, not methods. A key outside open , frame , event , timer and close refuses at declaration, and actias check verifies the shapes. Upgrading A websocket handshake arrives as an HTTP request, so it authenticates in the same router as everything else. request.upgrade is present only when the request is a real handshake. request:upgrade(Class, seed?, identity) names the declared connection class, optionally seeds conn.state , and fixes the identity the connection speaks as. Whatever the handler computed travels only through the seed. conn.state A json serializable table, alive exactly as long as the connection: seeded at upgrade, visible to every handler, written back after each one returns. The seed and every later write cap at 64 KB serialized; past it the handler raises and the connection ends. It is not durable storage. A connection dying with its node loses it, and the client's reconnect path re reads real state from objects. Identity The identity argument is an object handle: User(name) , Account(name) . The connection speaks as that identity, and a [stream gate](/docs/runtime/streams) sees it shaped like any follower. Mint it after authenticating. It is fixed for the life of the connection and cannot be changed by anything the client sends. Sending and receiving frames conn:send(value) writes one JSON text frame. The wire carries JSON text only: a binary frame, or text that does not parse as JSON, is dropped without reaching frame . Apart from the envelope a class asks for with event = "forward" , there is no platform wire protocol: the frames on the wire are the ones your handlers send. To let clients change subscriptions, define a frame for it: Timers timer = { every = "30s", run = function(conn, missed) end } runs on the connection's own clock, one second or longer. missed counts ticks that fell during a previous run; the next deadline realigns to the grid rather than drifting. A tick never queues behind the inbox, so a heartbeat cannot overflow it. A connection with a timer never hibernates. Connection edges conn:follow makes an edge like state:follow does, with different promises: object edge connection edge delivery at least once at most once retry yes, with backoff none on failure retried, then dropped edge removed lifetime until unfollowed dies with the connection A tab that closes takes its edges with it. Nothing accumulates for dead connections. Put durability one hop back: the account object follows what must not be missed; the connection follows the account for live updates. Warm, hibernated, gone State Holds Cost Leaves it warm a vm and everything below a vm 300 s idle drops the vm ( CONNECTION HIBERNATE SECS ; 0 disables) hibernated the socket, the inbox, conn.state , the follows about a file descriptor anything with a declared handler to run rebuilds the vm gone nothing zero is the end Hibernation is invisible from both ends of the wire: the socket stays open, deliveries land in the inbox, and conn.state is exactly what the last handler left. It is a memory economy, not durability. An undeclared handler costs nothing at all: a close with no close handler never builds a vm to discover there is nothing to run. Neither does a delivery to a class that declared event = "forward" , since the platform writes that frame itself. Backpressure and limits Handlers for one connection run one at a time, in arrival order, each as one platform call under the call budget. Each connection has an inbox of 256 items. Inbox full because of What happens edge deliveries the handlers cannot keep up with the delivery is refused and every edge the connection holds is severed; the socket stays open, silent client frames arriving faster than the handlers run the wire is closed A handler throwing, conn:close() , or the peer disconnecting 

Websockets

Where it is The project has one shell: the Shell entry in the console's sidebar, or actias shell in the cli. Every class page's open the shell lands there with that class filled in. The line is typed by the analyser that checks a script: a misspelled field underlines before anything is sent, and after page = Auction:find { ... } the next line completes page.entries . Names complete from what the project holds, inside the quotes of kv(" and database(" . What binds Binding Spelled Resolves into a class with a directory Auction:list {'{…}'} , Auction:find {'{…}'} , Auction:visit {'{…}'} the class page's directory query an instance Auction("lot 42"):bid("ada", 120) one call through the object's own lane (write mode) a kv namespace kv("users"):get("ada") , :list() , :set("k", v) , :delete("k") the KV page's requests a database database("main"):query(sql, params) , :exec(sql, params) the database page's query and execute Each of those is one statement : it resolves where you typed it into the request the corresponding console page already makes, and nothing is woken. \resources lists what the project holds; \fields Auction lists a class's declared fields and methods. Read only and write mode A session starts read only. \write lifts it; \read puts it back. Runs read only Needs \write list , find , visit ; kv get , list ; database query kv set , delete ; database exec ; every method call A method call goes through the object's own lane, serialized with every other call, exactly as a script's call would. Nothing declares which methods write, so a read only session refuses a call rather than hiding it. Naming an instance that does not exist creates it, admission permitting. In write mode every call and every chunk is logged by the api against your account, one line per action: Chunks A loop, an expression, a value used as an argument: those are not one statement, and the shell does not pretend otherwise. Such a line runs as a chunk , in a fresh vm on a worker, under your grants. So does anything you give to \run or \paste . In a chunk What it is kv "…" , database "…" , objects "…" the bindings a script has, scoped to every namespace, database and class the project holds Auction , every class by name pre bound class handles Auction:get("lot 42") a handle to call, as in a script; the row is Auction:find({'{ name = "lot 42" }'}).entries[1] a bare expression returned, the way a repl does print and log. captured and shown in order with the value the budget a request's work budget, and 30 seconds of wall time (60 at most) errors reported with the line number in what you pasted The session's mode travels with the chunk. In a read only session the vm refuses kv set , set batch and delete , database exec and every method call inside the chunk, naming \write : A chunk is possible and not encouraged: the one statement forms are what the shell is for, and a chunk you would run twice is a script. Commands Command Does \write , \read switch the session's mode \fields Auction the class's declared fields and methods \resources the classes, kv namespaces and databases the project holds \run (console) open a buffer for a chunk; ctrl+enter runs it \run &lt;path&gt; (cli) run a file as a chunk \paste … \end (cli) read lines until \end , then run them as a chunk \clear forget the history and the names it bound \help , \quit as named A line starting with is a comment and does nothing. From a pipe The cli shell reads statements from stdin when it is not a terminal, one per line, and prints each answer, so a scripted check is a heredoc: Completions come from the language service when actias luau is beside the binary or on your PATH, and from the project's contract otherwise; the banner says which. Access Statement Needs on the project directory reads, database query database read kv get , list kv read kv set , delete kv write database exec , method calls, chunks database write, whatever the session's mode Limits Limit Value rows per directory page 500, whateve

The shell

The rule A durable name scopes to the project. Two scripts saying queue "mailroom" talk to one queue; Auction("lot 42") is one instance with one mailbox, whichever script addresses it. Declaration Scope object classes project queue project database project workflow definitions project on "cron:..." schedules script Cron is the exception on purpose: a schedule belongs to the script that declared it, so equal expressions across scripts never collide. Objects from another script One script declares the class and owns its behavior: Any other script in the project references it by name: objects "Auction" claims nothing and needs no body. The call routes to the instance, and the method runs in the declaring script's current published revision. Republishing the declaring script moves every caller to the new code. Queues across scripts Any script may declare queue "mailroom" and send. The script that declares on "queue:mailroom" is the consumer, and the consumer's code drains the queue. Each message records which script produced it; the console's journal shows the producer. Workflows across scripts workflows "settle sale" is the cross script handle to a definition declared elsewhere: start mints a run, get addresses one. Gotchas The editor types objects "Auction" instances as any : the checker reads one bundle at a time, so another script's class body is out of reach. The call still routes; the completions stop at the boundary. Keep one declarer per class. The declaring script owns the code that runs; siblings use objects . Two scripts declaring the same class leaves ownership to contract resolution instead of your intent. Ownership follows the current revision pointer. Deleting the declaring script strands its instances' data until another script declares the class. Related [Objects](/docs/runtime/objects): classes, state, alarms. [Queues](/docs/runtime/queues): delivery, retries, dead letters. [Workflows](/docs/runtime/workflows): staged jobs you can ask about.

Sharing across scripts

Cron A cron handler runs on a schedule for the whole script. Expression Fields /2 minute, hour, day, month, weekday 0 /2 the same, with seconds at the front The event carries event.cron , the handler's full name including the prefix ( "cron: /2 " ), and event.scheduled at , the platform clock in milliseconds when the run started. The schedule arms itself the first time a worker touches the revision. The next occurrence is armed before your handler runs, so nothing the handler does can kill the schedule. Cron or alarm Use cron when the schedule belongs to the site: a nightly digest, a cache rebuild, a periodic cleanup. Use an [alarm](/docs/runtime/objects alarms) when the deadline belongs to one entity: this auction closes at 14:02, this trial ends on the 30th. The entity arms it, so no query has to find overdue rows. One cron scanning a table of deadlines gets slower as the table grows. A million objects with their own alarms cost nothing until they fire. Gotchas Downtime collapses. A schedule that should have fired four times while no worker was up fires once when one returns, not four times. A failing handler is logged and not retried. There is no cron retry; the next occurrence is the next attempt. scheduled at is when the run started, so it drifts from the nominal minute. Do not use it as an occurrence identifier.

Scheduled work

One environment per request Nothing survives in memory between requests. Each request gets its own copy of the script's state. Nothing is shared between requests, and nothing needs cleaning up after one finishes. Compiled code is shared, and the environment is built ahead: the platform keeps a few fresh ones per revision, each having run the top level once and served nothing, so a request takes one rather than building it. A top level value such as os.time() or a secret was read when the environment was built, at most 30 seconds earlier. Anything you need to keep goes in [kv](/docs/reference/kv), a [database](/docs/reference/database), or an [object](/docs/runtime/objects). The top level runs once Code outside your handler runs when the environment is built. That is where declarations go: Declarations are only valid at the top level. To collect them the platform runs your entry point with every effectful surface stubbed out, so it derives the contract without executing a single handler. Request and response The handler takes a request table and returns a response table. request.path is relative to your script: one served at /hello/ sees /api/echo , not /hello/api/echo . request.query is a decoded table. Every field is in the [http reference](/docs/reference/http). Budget A request is bounded by work, not by time: waiting on io costs nothing, computing costs. The ceiling is about a second of solid computation, which no ordinary handler comes near. Bound Value Covers work budget 5,000,000 work units computation in the vm wall backstop 10 seconds code stuck inside a host call that never returns to the vm request deadline 30 seconds the whole request, waiting included request body 10 MB larger bodies are refused with 413 Work that does not fit belongs in a [queue](/docs/runtime/queues) or a [workflow](/docs/runtime/workflows). Gotchas Top level state looks like a cache and is not one. The counter above resets on every request, including in production. Work at the top level is paid on every request, since the environment is rebuilt each time. Put it in the handler. kv "visits" inside a handler is an error, not a late declaration. The declaration forms are top level only.

How a request runs

What a queue is A queue is a durable message list with a handler. Sending returns immediately. The platform delivers, retries with backoff when the handler throws, and dead letters the message after enough failures. The handler is declared with on "queue: " matching the queue's name. actias check refuses a queue nothing handles, and a handler for a queue nothing declares. Delivery At least once delivery. A handler that throws gets the message again after a delay, then a longer one. Make a second run harmless: check an id, or write INSERT OR IGNORE and UPDATE ... WHERE state = 'pending' . One message, one handler run. Queues distribute work, they do not broadcast. A queue drains on one node, in order, one message at a time; a thousand messages are a thousand handler runs, never more. Bounded retries. A message gets 5 attempts by default. The first retry waits 2 seconds and each further one doubles, capped at an hour. Attempt Runs after 1 immediately 2 2s 3 4s 4 8s 5 16s After the last one the message moves to the dead letter list. It stops retrying, does not block the queue, and stays there until you look at it. Operators tune the two numbers with QUEUE MAX ATTEMPTS and QUEUE BACKOFF BASE MS . What belongs in a queue Email, push notifications, webhooks, thumbnail fetches, anything where a minute of delay is acceptable and the request path should not wait. What does not Addressed work. "Tell this account it was outbid" is a call to that object, not a queue message. Queues are for work no specific entity owns. Multi step processes. If the job waits on a human or has stages, use a [workflow](/docs/runtime/workflows). Queue messages are anonymous, so a queue cannot answer "how is that one doing". Inspecting The console shows the depth, the messages due now, the delivery journal (the last 300 entries, payloads kept to 32 KB), the dead letters, and requeue and drop actions. A requeued message starts its attempts over under a new id. Gotchas A handler that throws is a retry, not a failure you see at the call site. send returned long before the handler ran. Retries are per message. A poison message does not stall the ones behind it; it dead letters and the queue keeps draining. The handler name must match the queue name exactly. on "queue:mailroom" serves queue "mailroom" and nothing else. One script per project handles a given queue. Any script in the project may send to it. Related [Workflows](/docs/runtime/workflows): staged jobs you can ask about. [Sharing across scripts](/docs/runtime/sharing): any script in the project may send; the handler's script drains. [queue reference](/docs/reference/queue): every method.

Queues

Declare a class Call an instance by name: One call at a time An object handles one call at a time. Two bids arriving together cannot interleave the read and the write above, so exactly one wins. No lock, transaction or retry loop. Serialization applies per instance. Auction("lot 42") and Auction("lot 43") run in parallel with separate storage. An object may call other objects from a method. A chain that returns to an object already in it would wait on itself, so it is refused rather than deadlocked, as is a chain 32 calls deep. Up to 128 calls wait in an instance's mailbox; past that, callers wait for room. Lazy instances An instance costs nothing until something calls it. There is no create step, and a name nobody calls does not exist. Arguments and return values must be JSON representable, since a call can cross machines. state Field What it is state.sql this instance's private database state.store key value face on the same storage state.name the instance name state.now() platform clock, milliseconds state:set alarm(duration) schedule the alarm hook state:other method(...) a sibling method of the same class, run directly inside this call any other key scratch: in memory, gone when the object sleeps Streams add more verbs to state ; see [Streams](/docs/runtime/streams). In a !strict file, annotate each method's state the way a typed React component declares its props: state: ObjectState for the platform's fields alone, or name your own type on top of it to also cover scratch keys and sibling methods. A bare function(state) stays untyped in strict mode and the checker will say so. The worked pattern lives in definitions/objects.d.luau , which ships with every project. Small state A counter, a phase, a timestamp: state that small does not deserve a migrations directory. state.store holds it with nothing declared: It takes [kv](/docs/reference/kv)'s verbs ( get , set , delete , set batch , list ) over the object's own storage, so a call that touches both faces commits once. Values cap at 64 KB each; state past that, or state worth querying, wants a table in state.sql . The [object reference](/docs/reference/objects) has the exact shapes. Schema Form Schema init is for with migrations the .sql files, applied before the first call seeding rows without whatever init creates creating tables init runs once per instance, ever. It does not run again on restart or after a deploy, so an instance created before a schema change keeps its old tables unless migrations move it forward. Alarms Durations are written "500ms" , "30s" , "10m" , "24h" , "7d" ; set alarm also takes a bare number of seconds. One alarm per object; setting another replaces it. It fires with no browser open and no request arriving, and it survives restarts: whichever machine holds the object next re arms it from storage. Use alarms for deadlines an entity owns. Do not sweep a table looking for overdue rows. Finding instances A class can declare a directory : one row per object, derived from its own state, queryable with Auction:list , Auction:find and Auction:visit without waking anything. See [Directory](/docs/runtime/directory). Lifecycle An instance exists from its first call until something ends it, and three declarations shape that span: expire declares a lifespan measured in idleness: an instance untouched for that long is deleted by the platform. A call renews the clock, at most once every ten minutes, and a pending alarm postpones the sweep, so a busy or scheduled object never expires under you. admit gates creation, not access: it runs once when a name would first come to exist, with only the name, before any storage does. A refused name leaves nothing behind. The refusal is remembered for a while, so an immediate retry is refused too. state:destroy() ends the instance from inside a method. The current call still returns its value; then storage, snapshot and edges are reclaimed. Calls arriving afterwards refuse with The object was destroyed. while the deletion

Objects

Delivery Surface Promise What your code must do Object method call a call the platform answered ran exactly once, serialized per object a call that failed with an unknown outcome may have run; retry it the way any timed out request is retried Queue message at least once handler safe to run twice Object stream edge at least once, in order per publisher; a handler that committed never re runs for the same event effects outside the follower's own transaction safe to run twice Connection edge at most once client re reads state on reconnect Workflow step recorded once, replayed after keep run code deterministic Alarm fires once per set, survives restarts; its handler's writes are not gated, so a crash mid handler loses them without a re fire an alarm handler's work that must not be lost re arms itself Directory row every object that matched is present; a row may briefly still match after the object changed plan for over inclusion, never for omission At least once means a repeat is possible after a machine failure at the wrong moment. Make repeated work harmless: check an id, use INSERT OR IGNORE , or update conditionally on current state. Stream edges narrow the window: the follower records the event in the same transaction as its handler's writes, so a redelivered event is skipped, not re run. Effects that leave that transaction are the part to keep idempotent. At most once means loss is possible. Only connection edges promise this, because a tab can vanish mid frame. Anything that must survive belongs on the object one hop back. Ordering Events from one publisher reach one follower in publish order. There is no ordering promise across different publishers. If order matters across sources, put a sequence number in the data. Calls to one object are ordered. Calls to different objects are not. Transactions A method's writes to state.sql commit together when the method returns. A state:publish inside the method is part of the same commit, so an event never describes a write that did not happen. The directory row, if the class declares one, is derived inside the same transaction. The answer waits for one thing more than the commit: the writes leaving the machine. Calls that arrive while an answer is waiting still run, so a busy object commits at its own speed and a burst of writes leaves together. A request that makes several calls to objects on its own node gets each answer at commit and waits once, before its response and before any outbound request, for all of them. Migrations apply inside the transaction of the call that triggered them: a failing migration applies nothing and surfaces as that call's error. Workflow steps commit their journal entry with their result. A crash between two steps replays from the last recorded one. Limits Defaults, all operator tunable on a self hosted worker. Limit Value What happens at it Guest work budget 5,000,000 work units ( GUEST WORK LIMIT ), about a second of solid computation, per request, object call and connection item the run is cut off Wall backstop 10 seconds ( GUEST WALL SECS ), for code stuck outside the vm the run is cut off Request deadline 30 seconds, waiting included the request fails Request body 10 MB 413 Object database 1 GB per instance ( OBJECT DB MAX MB ) writes fail, reads keep working Object mailbox 128 waiting calls callers wait; nothing is dropped Object call chain 32 deep; an object calling itself, directly or through others, is a cycle refused, naming the cycle or the depth Writes from one request answered at commit; the response waits once for all of them; a later read of the same object in that request sees them a write that cannot be confirmed makes the whole response fail with an unknown outcome Database read anywhere sees every write answered before it began, whichever node serves it nothing Any reply from an object waits while the object has writes still in flight, whoever wrote them; a settled object answers at once the same unknown outcome as a write, after the 

Guarantees and limits

One row per object A class declares a directory : one read that runs per derivation, and the fields it feeds. Each field names its own kind. The platform recomputes the row after any call that wrote. Methods are never edited for indexing, and the row cannot drift from the state it is computed from. Kind Accepts f.string a string f.integer a whole number; a fraction fails the derivation f.number any number, whole numbers included f.boolean true or false f.array an array of scalars, up to 256 members An extractor receives the value from returned and the same restricted state . The fields are a table, not something a function returns: the publish reads the field set without running anything, so a field cannot hide inside a branch that only some objects take. Gotchas A derivation sees state.name , state.sql , state.store and state.now() only. It is read only; a write inside it is an error. It runs on every write under a 5 ms budget, so it reads state the methods keep current. An aggregate per write (a MAX over a table) is the shape the budget exists to refuse. A value of the wrong kind, or a field the declaration does not name, fails the derivation the way a thrown error does. If from returns nothing, every field is absent for that object, which is what a brand new instance looks like. A class with a directory needs storage to derive from: migrations or an init that creates its schema. A directory with no fields is refused at publish. Query the class Entries carry name plus the declared fields; an array field comes back as a table. Pass cursor = page.cursor to continue a page. With no limit a page holds 100 entries; the console and the api cap a page at 500. order takes one field. A Lua table has no order between its keys, so a second sort key's precedence could not be read from it; sort by the one that matters and page by the cursor. Absent values sort last in both directions, and name is the final tie break, so the order is total. actias check types the query and the declaration alike: a kind that is not a kind ( f.txt ) and a misspelled operator are type errors before anything is published. Predicates Top level fields are ANDed. Values match exactly, or take an operator table: Operator Meaning eq equal; the same as a bare value lt , lte , gt , gte comparison ne not equal one of any of a list, at most 1024 values; an empty list matches nothing starts with text prefix contains membership, for array fields exists presence; exists = false matches absence any , all and none combine full where tables, and nest: name is always queryable. Every query runs against an indexed local copy; equality, ranges and starts with walk an index, while contains , ne and exists scan the candidate rows. Gotchas An unknown operator is refused, never ignored: a filter that widens silently would be worse than an error. A nil operand is refused with a hint: a table cannot hold one, and absence is spelled exists = false . An empty any , all or none is refused. Auction:list {} and Auction:find() list everything, 100 at a time. Arrays, dotted names, and absence A field can hold an array of scalars, and a name may carry dots, which is how a nested shape is exposed one leaf at a time: Arrays take contains and exists only. They have no order, so comparing or sorting by one is refused. A dotted name is one field with a dot in it, not a path the platform walks; the extractor is what reaches into the shape. exists = false is the one way to match an absent field. Comparisons, ne included, never match absence. Members and leaves are scalars. An array inside an array is refused. Three ways to read Call Cost Freshness Auction:list , Auction:find cheapest; nothing woken rows trail writes by seconds Auction:visit rechecks each candidate against its object's saved state; nothing woken stale rows are dropped or refreshed Auction(name):method() a real call, serialized the truth find is list with the predicate as the whole argument, for the common read that wants default or

workflow

Declare a class Each handler is optional; a key outside these five refuses at declaration. Nothing calls a connection, so there are no methods: handlers run when the wire, an edge or the timer delivers. Handler Runs open(conn) once, before any item; the follow calls usually live here frame(conn, data) per JSON text frame the client sent; binary and non JSON frames are dropped event(conn, event) per delivered edge event; takes a policy instead of a function (below) timer.run(conn, missed) every timer.every , one second or more; missed counts ticks that fell during a previous run close(conn) after the wire ends, either side; edges sever after it returns Handlers for one connection run one at a time, in arrival order, each under the per call budget. A tick is never queued behind the inbox, and a connection with a timer never hibernates. The forward policy event takes a policy in place of a function, the same hook or policy shape publishes uses for topics: Each delivery then reaches the client as built by the platform, with no vm involved, so a hibernated connection stays hibernated while it relays. Declare a function instead to choose your own wire shape, and pay a handler call per event for it. Declaring neither drops deliveries, which is what you want only when the follow exists to be counted ( state:followers ) rather than heard. Upgrading request:upgrade(Class, seed?, identity) returns the value your fetch handler should return. The seed becomes the initial conn.state ; the identity is an object handle the connection speaks as for the rest of its life. Two arguments means no seed. Refused Text a class that is not a declared connection upgrade takes a declared connection class a connection declared in another script Connection 'X' is not declared in this script. an identity that is not an object handle refused; a platform class refuses with a connection cannot speak as a platform class. a seed over 64 KB serialized refused at upgrade a second upgrade in one request one upgrade per request. conn Field Meaning conn.state json serializable session table, seeded at upgrade, kept across handlers; past 64 KB the handler raises and the connection ends conn.name the identity's instance name conn.class the identity's class conn:send(value) writes one JSON text frame conn:follow(target, topic, filter?) makes a connection edge; returns true conn:unfollow(target, topic) removes it conn:close() ends the connection conn.closed on the close handler only: {'{ by, reason? }'} , where by is peer , program , error or overflow The event a handler receives is shaped { topic = "...", from = { id, class, name }, data = {...} } . Opening a wire outward The same class dials as well as accepts: Argument Meaning url ws:// or wss:// ; the egress policy applies, and every address the host resolves to is checked before any is dialled seed the initial conn.state , optional, 64 KB cap options.headers request headers for the handshake options.protocols the subprotocol list returns the instance name, once the handshake is up; the call raises with the reason otherwise, and gives up after 10 s The connection speaks as its own class and the minted name, lives on the node that opened it, and is listed in the console's Connections page beside the inbound ones. There is no socket handle: to send up the wire, publish on a topic the connection follows, and send the payload from its event handler. See [wires this project opened](/docs/runtime/sockets wires this project opened) for the pattern and who should own the reopen. Streaming a response The same class reads an HTTP response as frames: Argument Meaning request.url http:// or https:// ; the egress policy applies request.method default POST with a body, GET without request.headers request headers request.body a string, or a table sent as json with content type: application/json unless a content type is given seed the initial conn.state , optional, 64 KB cap returns the instance name once the response headers are in

connection

Declare The handle is the value itself, resolved at declaration, once per environment. Set it with the CLI or the console; it never lives in the bundle. Rotation Putting a new value creates a new version. Later resolutions get the new one. A [workflow](/docs/reference/workflow) run pins the version it first resolved, so a long run keeps signing with one key even if the secret rotates while it is parked. Example Console The secrets view shows names, versions, who declared them, and which scripts reach them. Values are never shown after they are set. Gotchas Build the signer inside the handler. The top level runs the declaration pass, where runtime surfaces are inert. A secret that is not set fails every request of the script with Secret 'name' is not set for this project. , not the code path that uses it, because it resolves at declaration. A rotation does not reach a parked workflow run. That is the point: the run finishes on the key it started with. There is no way to read a value back. Losing it means putting a new one and rotating whatever trusted the old. Related [Jwt and crypto](/docs/reference/misc): what usually consumes a secret.

secret

Declare Top level only. The handler name must match the queue name exactly, and actias check refuses a queue with no handler or a handler with no queue. Methods Method Returns send(payload) true once the message is durable; a queue that cannot store it raises stats() depth , in flight , oldest pending , dead letters Field Meaning depth every message still queued in flight messages due now, attempted or not oldest pending when the oldest queued message was sent, platform clock in milliseconds dead letters messages on the dead letter list The payload must be JSON representable, since a message can cross machines. A queue is one 64 MB file; a send past that raises. Delivery Promise What your handler must do at least once tolerate running twice on one message one message, one run, in order on one node nothing; queues distribute, they do not broadcast 5 attempts, then dead lettered throw when the input can never work The first retry waits 2 seconds and each further one doubles, capped at an hour. A dead letter stops retrying, does not block the queue, and waits in the console until you requeue or drop it. Example Gotchas Throwing is how you dead letter deliberately. A job whose input can never work should throw rather than silently succeed. send returns before the handler runs, so a handler failure never surfaces at the call site. The console is where you see it. A message delivered while its handler's script is unpublished counts as a failed attempt and dead letters after five; it is not held. Related [Queues](/docs/runtime/queues): when a queue is the wrong tool. [workflow](/docs/reference/workflow): for jobs someone will ask about by name.

queue

Declare a class Seven reserved keys; every other key is a method. Key Meaning migrations directory of .sql files that build each instance's schema publishes topics this class emits; name = "self" or = "public" sets a policy instead of using the hook receives ["Class:topic"] = handler for streams it consumes; the class must be declared in the project expire a duration string; an instance untouched that long is deleted. Touch renews it, a pending alarm postpones it admit function(name) , decides whether a NEW instance may exist; truthy admits. A refused name leaves nothing behind directory {'{ from, fields }'} : one queryable row per instance; see Directory hooks init , alarm , follow A class name starting with is reserved for the platform and refused. Referencing a class declared elsewhere: Instances Arguments and return values must be JSON representable. A name is yours: any non empty string, and it says nothing about where the object lives, which is the platform's business. Class verbs All three read the class's [directory](/docs/runtime/directory) and wake nothing. A class without a directory declaration has no rows to read. state Field Meaning state.sql this instance's private database state.store key value face on the same storage state.name instance name state.now() platform clock, milliseconds state:set alarm(duration) schedule the alarm hook state:destroy() ends this instance after the current call replies: storage, snapshot and edges reclaimed, the name recreatable fresh state:publish(topic, event) emit on a declared topic; an undeclared topic raises state:follow(handle, topic, filter?) follow another object; returns nothing, raises follow refused when the publisher declines state:unfollow(handle, topic) drop that edge state:followers(topic?) current followers, every topic when none is named state:drop followers(handle) drop every edge an identity holds state:method(...) a sibling method of this class, run directly in this call any other key in memory scratch, lost when the object sleeps state.sql takes the same exec / query / query one / batch as a [database](/docs/reference/database), minus the read variants. state.store The key value face on the same file, for state too small to deserve a table. No migrations key, no declaration at all: The verbs are [kv](/docs/reference/kv)'s, page shape included: Method Returns get(key) the value, or nil set(key, value) nothing; a nil value is a delete set batch(table) nothing; writes every pair, deletes the nil ones delete(key) nothing; one key, where kv takes several list(options?) one page: {'{ entries, cursor }'} One transaction. A call that touches state.store and state.sql commits once; the two faces are one file and can never disagree. Values are JSON representable and at most 65,536 bytes each as stored text. Past that, the write is refused naming the key, and the state wants a table in state.sql . list takes { prefix?, limit?, cursor? } ; entries are { key, value } in ascending key order, limit defaults to 100 and a value outside 1 to 1000 is refused, and a page without a cursor is the last. The pairs live in a reserved table that SQL cannot see, from methods and the console alike. Listing them is what list is for. Hooks Hook Runs init once per instance ever, before its first call proceeds alarm when a set alarm comes due follow to decide whether follower may follow topic ; truthy accepts Hooks are called by the platform. Calling one through a handle is refused: 'init' is a platform hook; only the platform calls it. With migrations declared, the files apply before init , so init only ever seeds rows. Without it, init is where the tables get created. follower The identity a follow hook receives: Field Meaning follower.name instance name it speaks as follower.id "Class/name" follower.transport "object" or "connection" follower:is(Class) class check against a class value Rows from state:followers carry the same fields plus topic . Durations set alarm and workflow timeouts ta

object

json Wrap parse with pcall when the input is untrusted. uuid In [workflow](/docs/reference/workflow) run code, generated ids are journaled so replay reproduces them. log Several arguments are joined with spaces; a table is rendered as JSON. Lines appear in the console's live log for the script, and in actias dev sessions. require and dofile Both resolve against the published bundle, never the filesystem. getfile Reads a file from the published bundle and returns its bytes, or nil when the path is not in the bundle. Return it as a response body directly: Include the files in script.json 's includes so they ship. crypto Jwt Algorithms: HS256 , HS384 , HS512 . The key is a shared secret, so the public key families are refused. decode requires an exp claim and checks it; a token without one decodes to nil. script Gotchas crypto and Jwt are absent from a workflow environment, step bodies included. Call an object from a step when a run needs them. json.parse raises on bad input. Wrap it in pcall whenever the text came from outside. getfile returns nil for a path that is not in the bundle. Add the file to script.json 's includes or it does not ship. Related [secret](/docs/reference/secret): what Jwt.new usually signs with. [http](/docs/reference/http): returning getfile output as a response body.

Globals

Declare Top level only. Scoped to the project, so two scripts in one project declaring kv "visits" share it. Methods Method Returns get(key) the value, or nil set(key, value) nothing; a nil value is a delete set batch(table) nothing; writes every pair, deletes the nil ones delete(...keys) nothing; several keys go in one call list(options?) one page: {'{ entries, cursor }'} Listing One page per call, in ascending key order. entries is an array of { key, value } ; cursor names where the next page starts, and a page without one is the last. limit defaults to 100; a value outside 1 to 1000 is refused, not clamped. The options are { limit, cursor } . A page is a snapshot of a range, not a lock: writes that land between pages appear or not depending on where their keys sort. Types kv stores the type you wrote and returns it. You write You get back string string integer integer number number boolean boolean table table, through JSON Example Gotchas Listing pages by key order; there is no query by value. Anything richer than a key range wants a [database](/docs/reference/database). Functions and userdata cannot be stored. Tables go through JSON, so what comes back is a copy, not the table you put in. A nil value in set or set batch is a delete, not a stored nil. A value has no fixed size limit. state.store on an object caps at 64 KB; kv does not. A namespace name starting with is reserved for the platform and refused. Related [Where data goes](/docs/runtime/storage) compares kv with databases and objects. [state.store](/docs/reference/objects statestore) is the same surface on a durable object's own storage: kv for state one object owns.

request Field Type Notes request.method string "GET" , "POST" , … request.path string relative to your script request.query table decoded query parameters request.headers table lowercase keys request.body string, or a byte array raw body; a body that is not valid UTF 8 arrives as an array of bytes. Bodies over 10 MB are refused with 413 request.uri string full uri request.upgrade function or nil present on websocket handshakes request.path has the routing prefix removed: a script served at /hello/ sees /api/thing , not /hello/api/thing . response body takes a string or a byte array, so [ getfile ](/docs/reference/misc getfile) output can be returned directly. Outbound requests Outbound calls go through a guarded client. A refused or unreachable host raises an error, so wrap calls that may fail in pcall or let a [queue](/docs/reference/queue) handler retry them. Uri Gotchas http is absent from a [workflow](/docs/reference/workflow) environment, step bodies included. Call an object from a step to reach the network. Waiting on a response spends no work budget, but it does spend the request's ten second wall backstop and its 30 second deadline. A slow host takes the whole request down with it. request.headers keys are lowercase. request.headers["Content Type"] is nil. Related [How a request runs](/docs/runtime/requests): the environment around these tables. [Websockets](/docs/runtime/sockets): what request.upgrade does, and how a script opens a wire outward with Class:open .

http, request, response

Declare Top level only. Scoped to the project, so two scripts in one project declaring database "catalog" share it. The body is optional: Form Schema comes from database "catalog" & 123; migrations = "dir" & 125; the .sql files in dir database "notes" nothing. Manual mode: the platform never touches the schema In manual mode the file starts empty and stays yours: nothing is created, migrated or checked. Add the key later and the files apply at the next touch. Query Method Returns exec(sql, params?) rows affected query(sql, params?) rows query one(sql, params?) first row, or nil read(sql, params?) rows, from the nearest copy, up to 30 seconds behind the last write read one(sql, params?) first row, or nil, from the nearest copy batch(statements) several statements in one transaction; each entry is {'{ sql, params }'} ; returns the rows affected per statement Parameters are bound, never interpolated. read and read one see every write any caller was told succeeded before the read began, from any node. A node that replicates the database answers from its own copy once the owner has confirmed the copy is current, which costs one small round trip and no data; any other node asks the owner for the read itself; a request that already wrote to the database reads it at the owner. query and query one always run at the owner and see writes not yet answered too. Migrations Create the files with the CLI: That writes migrations/catalog/0001 listings.sql . Fill in the SQL: Declare the directory on the database, and the platform applies the files in filename order at the first call that touches it, inside that call's transaction. The declaration is what makes files apply. A directory nothing declares is never read, whatever it is named. Adding 0003 .sql and publishing upgrades the schema on the next touch. Nothing runs at publish time. Gotchas A failed migration applies nothing and surfaces as that call's error. Fix the file and publish again; the next touch retries. The first caller after a deploy pays for the migration. Keep migrations cheap, or touch the database yourself after publishing. actias check fails if the declared directory holds no .sql files, or if a directory of .sql files is declared by nothing. Related [Where data goes](/docs/runtime/storage) compares databases with kv and objects. [object](/docs/reference/objects) takes the same migrations key for a class's private storage.

database

A deployment is one control plane and one or more regions. The division of labor, the one kind of traffic that crosses a region boundary, and the two operations that involve more than one region. The parts A region is a placement store, an object bucket, and workers, all carrying one region name ( REGION ). Everything that makes an object work is inside it: leases, membership, alarms, the instance directory, replicas, the shipped log. A node dying is the region's own affair, handled exactly as on a single region cluster. Placement stores never talk to each other. The control plane is shared: projects, scripts, revisions, bundles, secrets, project policy, and the registry of regions. Every region's workers read it, cached on the pointer ttl, the way they read the script pointer. Bundles live in its blob bucket, immutable and content addressed, and workers everywhere cache them by hash. The placement store A region's placement store is Postgres or Scylla, chosen per region at deployment. Both pass the same conformance suite; nothing above the store can tell them apart. Postgres is one primary with transactions. A claim is one statement and failover is the database's own. It is the right store for one region on one node or a few. Scylla is leaderless: every row lives on several nodes of one datacenter and a claim is a lightweight transaction across them, so the store survives the loss of a node with no failover step and scales with the region's workers. That benefit exists only when the store spans several nodes. A one node Scylla is a slower Postgres with more memory and no transactions across rows. Scylla gives a region a store that survives node loss without an operator; it does not give regions a shared store. Placement stores never talk to each other under either backend. Where an object lives Every project has a home region , recorded when it is created: the region of the ingress that received the create request, else the control plane's own. A class may pin its instances elsewhere by declaration ( placement = { region = "eu west" } ). An object is born in the pin's region or, without one, the project's home. Every caller computes that from the class and the project, which it already holds. No service is asked where an object is. The platform may later move an object away from its birth region. Then the birth region's placement store keeps one forwarding row for it, and a claim there answers the row's region instead of a lease. This is the only mutable placement state in the design, and it is written only by a move and read only for an object that moved. The one thing that crosses A call that lands in a region other than the object's forwards once to that region's data plane ingress and answers over the same connection. The receiving region claims locally, spawns or finds the object, and answers. If the object was born there and has since moved on, the reply says so and the caller forwards once more, remembering the region for next time. Nothing else crosses. Streams between objects in different regions ride the same one hop forward, asynchronously, on a path nobody waits on. A region the control plane does not know is served where the call landed rather than failed, so a misconfigured name is served locally rather than failed. The home is a fence A worker checks its object's current region before every flight. When the region is not its own, because the project was moved or failed over, the flight ships nothing and the residency ends. A sweep also walks residents and puts to sleep any whose project is moving or whose home is elsewhere. So a region that comes back after an outage cannot write over what the new home has done, and a worker still holding an object the platform moved cannot either. Moving a project A project moves as a job, because its bytes live in a bucket and its homes are leased caches: 1. Mark. The project is marked moving. New claims for it are refused everywhere with a retryable answer. 2. Drain. Every w

Regions

One call to an object that writes, and one that does not, from the mailbox to the reply. The numbers named are settings; everything else is fixed. The call arrives A unit calls Auction("lot 42"):bid("ada", 25) . The worker that runs the unit resolves the object's home ([placement](/docs/internals/objects/placement)): resident here, forward one hop, or claim. On the home node the call enters the object's mailbox , a queue of at most 128 waiting calls in arrival order, drained by the object's one task. The task runs one call at a time, to completion, before the next. An object has no concurrency. The transaction Before the method runs, the task opens a transaction on the object's SQLite file. Every state.sql and state.store operation inside the method rides that transaction. When the method returns, the task commits; when it throws, the task rolls back and the reply is the error. A method's writes are therefore atomic with respect to each other and with respect to the reply: a caller never sees half of them, and a rolled back method wrote nothing. The file runs with synchronous=NORMAL . A commit reaches the file's WAL and not necessarily the disk. That is deliberate: the local file is not the durability point, the ship is, and paying for an fsync on a file that a lease may take away is paying twice. The directory row If the class declares a directory , the task derives the object's row from its state inside the same transaction, before the commit, so the row and the state it describes can never disagree. A derivation that fails (throws, blows its 5 ms budget, produces a row the kernel refuses) keeps the last good row and marks the failure; it never fails the write. A derived index may not veto a business write ([the directory](/docs/internals/objects/directory)). The write gate After the commit the task asks the object's shipper for a ticket. The shipper is one per resident object; it owns the file's checkpoints and ships what changed. The ticket resolves when a flight covering the write has landed. A flight is one round of shipping: the shipper reads the WAL frames that appeared since the last flight (a delta, not the file), fans them out to the object's replica nodes, and writes them to the region's bucket as a WAL segment behind a manifest. Coverage is by flight number, not by byte offset: a ticket taken while flight N is still running is covered by flight N+1, which had not started reading the file when the ticket was taken. The ticket can wait one flight too many, never one too few. The flight releases the tickets it covers at the earlier of two moments: a quorum of the object's replicas has acknowledged the frames ( OBJECT QUORUM , 2 of 3 by default), or the manifest naming the segment is written to the bucket. With replicas the first comes in a few milliseconds; the bucket write then completes in the background. With no replicas (a single node) the manifest is the release, which is the in cluster store's round trip, tens of milliseconds. The reply leaves when the ticket resolves. The task does not wait: it hands the ticket and the result to a side task and takes the next call from the mailbox. That is what keeps the gate a latency cost rather than a throughput cost: ten writes in a burst commit one after another, ride one flight, and release together. Ordering is the mailbox's property and is untouched by answering out of order. A ticket that does not resolve within OBJECT ACK GATE MS (10 s) fails the reply with a typed unknown outcome. The write is still committed locally and the shipper keeps retrying; the caller is told the outcome is unknown. The read gate A method that wrote nothing has no ticket of its own. It still cannot be answered freely: the object may have writes from earlier calls whose flights have not landed, and a reply computed over them would describe state a crash could take back. So the task asks the shipper a cheaper question: is anything dirty or flying? If not, which is the common case, the reply le

The write path

An object's writes are acknowledged on a quorum of replica nodes before the bucket has them. What a replica is, what crosses the wire, how the set changes, and how a takeover finds the freshest bytes. The replica set When an object becomes resident, its owner picks OBJECT REPLICAS minus one other live nodes by rendezvous hashing over the object id and the node id: every node computes the same ranking from membership alone, so two owners of the same object in succession mostly agree and a node leaving moves only the objects it replicated. The set is recorded in the object's manifest with every flight, so a takeover knows who to ask. Replica choice is made per residency and repaired on failure, never rebalanced on its own: churn elsewhere does not shuffle every object's copies. The quorum of acks releases the callers; the bucket write completes behind it. A flight, on the wire A flight carries WAL frames: the bytes SQLite appended since the last flight. To each replica it sends an append naming the object, the owner's epoch, the generation it belongs to, and the frames. The replica checks three things before it writes: 1. The epoch. A replica remembers the highest epoch it has seen for the object. An append under a lower epoch is refused as fenced: a zombie owner cannot land a frame anywhere a quorum counts. 2. The generation. A generation is a base (a snapshot of the file) plus the WAL that follows it. A replica that has no copy of the generation, because it is new to the set, asks for the whole generation instead of the delta; the owner lays it, chunk by chunk, on the next flight. 3. The length. Frames are idempotent by offset. A replica that missed a flight reports its length and the owner resends from there; a replica that already has the frames acknowledges again. The replica fsyncs ( OBJECT REPLICA SYNC , fsync by default) and acknowledges. The owner counts acknowledgments; at the quorum it releases every ticket the flight covers; stragglers get a short grace and are then resent next flight. When a replica dies Its appends fail. The flight still releases on the quorum. After the flight answers, never before, the owner repairs the set: a member the membership snapshot no longer lists leaves it, a set short of its size takes the best ranked live node it lacks, and a join forces the next flight to rotate, so the newcomer receives a whole generation rather than a delta it cannot apply. Membership is the shared ten second snapshot every node keeps; no flight reads the placement store. Rotation A generation cannot grow forever. When its WAL passes OBJECT WAL ROTATE KB or a fraction of the base ( OBJECT WAL ROTATE FRACTION ) or OBJECT MAX SEGMENTS segments, the next flight rotates: the owner checkpoints the file, snapshots it as content addressed chunks, lays the new base on every replica and in the bucket, and starts a fresh WAL. A rotation is the one flight that carries a whole file; everything else is a delta. Takeover The owner dies. Its lease ages out of the placement store after NODE TTL SECS of silence, or is freed at once by a graceful deregister. The next call for the object, anywhere, claims the lease, and the claimant must find the freshest bytes. It reads the manifest from the bucket, which names the last generation the bucket has and the replica set. Then it asks each listed replica what it holds: the epoch, the generation, the WAL length. The rule: a live replica whose copy is of the manifest's generation and at or past the bucket's length wins; the claimant copies its file and WAL over the data plane and continues from there, without touching the bucket's segments; otherwise the bucket is the source: base chunks by hash, segments in order, checkpointed into a fresh file. The claimant's epoch is minted above everything the identity ever held, so its first flight fences any replica still holding the dead owner's frames, and its manifest write fences the bucket. A takeover that finds fewer live replicas than the quoru

Replication and takeover

Identity and home An object's identity is the triple (scope, class, name). Its platform wide id is the blake3 hash of that triple; the scope is the project for resource classes and the script for cron schedules. An object lives on exactly one node at a time: the lease holder . The first call to a non resident object claims the lease for the node the call landed on, so objects home where their traffic arrives. The region Every project has a home region, recorded when it is created (the region of the ingress that received the request, else the control plane's own). A class may pin its instances to another region by declaration, placement = { region = "eu west" } , which actias check validates. An object is born in the class's pinned region or, without a pin, the project's home; every caller computes that from the class and the project, which it already holds, so no service is asked where an object is. A call that lands in another region forwards once to the object's region and answers over the same connection. The promise is simple: an object is fast from its own region and one hop slower from any other. A region the control plane has not registered is served where the call landed rather than failed. The platform may later move an object away from its birth region. When it does, the birth region's placement store keeps one forwarding row for it; a caller that goes there learns the region from the answer, remembers it, and forwards once more. Names never encode a region: the name is yours, the placement is the platform's. Moving a project A project moves between regions as a job, not a migration, because its bytes live in a bucket and its homes are leased caches: the control plane marks the project moving, waits for the old region's residencies to end, copies the project's object prefixes and directory between the two regions' storage with each object's manifest last, repeating until a pass finds nothing new, flips the home, and clears the mark. Calls during the move are refused with a retryable answer, "the project is moving between regions", so a caller retries rather than losing anything; every write answered before the move is present after it. The console's policy page follows the move; GET /project/:id/move is its source. Leases and epochs Rule Number a lease lives exactly as long as its holder stays in the node registry; there is no per lease clock a node ages out after 45 s without a heartbeat ( NODE TTL SECS ) a claim against a dead holder frees the lease and wins; recovery is the same path as first placement a graceful shutdown deregisters at the signal, freeing every lease at once; a crash waits for age out, and calls forwarded to the dead node fail until then 45 s at most a resident object refreshes its claim on a call, throttled once per 10 minutes every claim draws the object's epoch from one cluster wide sequence; a delete takes the next value with its tombstone a cold object's first call goes to a live node its manifest names as a replica, so it wakes on its own bytes; a node that is itself a replica claims at once one hop at most a replica copy the store covers entirely leaves the disk once idle (a deleted object's copy leaves with its fence) 1800 s ( OBJECT REPLICA IDLE SECS ) Durability Writes mark the object dirty and one background flight per object carries the committed write ahead log frames since the last flight, coalescing bursts, to two places: the object's replicas and the blob store. The base is the object's file at a checkpoint, kept as a list of 1 MiB chunks named by their content hash. Every frame in the write ahead log names the page it carries, so when the log folds into the file the owner knows which chunks changed without reading the rest, and a rotation costs what was written, not what is stored. A replica holds the assembled file and patches it in place from the same chunks. A node laying the file from the store fetches the chunks it lacks in parallel, through a cache keyed by hash, so a copy 

Object placement

The contract Queries can recheck candidates against the objects themselves, so the directory only has to be a superset of the truth. Failure Cost Verdict stale row still matches one skipped candidate on recheck free row missing or lost an object no query can ever find fatal Everything below follows from that asymmetry. The write path is lazy, coalesced, and outside every acknowledgment; the one hard job is never losing a row. Declaration at publish The field set is data fields is a table of kind markers, so the publish reads the field set without running anything. The contract records the names and kinds. Refused at publish Why a class with a directory and neither migrations nor an init a row derives from state, and the class has no schema to hold any a directory with no fields a listing of names is what every class already has a field named any , all , none or name reserved by the predicate grammar an empty name, a name over 128 bytes, or one containing , : = the name is carried in the contract's own text form a kind that is not one of the five string , integer , number , boolean , array dver Every publish gives the class's field set a version, dver . A publish whose field set is unchanged keeps the previous dver; a changed set takes the next one; a class's first publish is 1. A deploy that only changes values renumbers nothing and rebuilds nothing. The row Derived in the call's transaction After a method that wrote returns, before its transaction commits, the platform runs from and the extractors on the call's own connection. The row lands in two reserved tables in the object's file, actias directory and actias directory meta , which script SQL cannot see. It ships with the object's write ahead log like every other byte of state. The derivation runs read only: the connection's authorizer refuses any write, and the state it sees is name , sql , store and now only. A row identical to the last one at the same dver bumps nothing and produces no delta, so a hot object with a stable row costs the index nothing. Contained failure from and each extractor are guest code the platform evaluates, so a failure is contained, never propagated. Read only enforcement means a failed evaluation has nothing to roll back. Event Effect throws on a live write the write commits; the row keeps its last good value plus a failed marker naming the rev and dver exceeds the 5 ms budget same as a throw returns an undeclared field, or a value of the wrong kind same as a throw; an integer satisfies number , a fraction never satisfies integer the encoded row exceeds 4 KB same as a throw; nothing is truncated throws during backfill same marker, same counters fixed function published the new version's backfill re evaluates exactly the marked rows The budget is separate from the caller's call budget, but the evaluation runs on the object's pinned task, so 5 ms is also the bound it can add to the mailbox. A class with a broken function stays findable by every last good row. Merge order Rows carry (epoch, rev, dver) and merge last writer wins, compared in that order. Deltas are an unordered bag of content addressed files, so this comparison is the entire ordering story. Component Minted by Settles epoch the placement sequence, at each lease claim; a delete takes the next value with its tombstone a reborn name outranks its own gravestone; a new holder's rows beat a dead node's ghost revs rev each derivation within an epoch a later write beats an earlier one; a placeholder is rev 0 and loses to any real row dver the publish that declared the field set a backfilled row beats a manifest copy of the same state under an older declaration equal equal versions carry equal rows; keeping either is correct A zombie ex holder can keep uploading deltas forever. It cannot settle new state, because the object manifest's epoch fence refuses its flights, so its rows describe old durable states and lose on epoch. The syncer One syncer per node, not per object. It collects the rows

The directory

The log and the edges state:publish appends the event to a log inside the publisher's own SQLite file, in the same transaction as the method's writes. Beside the log sit the edges : one row per approved follower, each recording the node its follower lives on. The edge list is the access control, computed once: the follow hook runs when the edge is created, never during delivery. Delivery walks rows. A new edge starts at the log's head; nothing is replayed down it. Fan out by node Between the publisher's calls, its pump partitions due edges by the follower's node. Local edges deliver directly. Remote edges batch into one call per node. Edge kind What a remote batch carries Publish cost connection the due events once, in publish order, beside every edge on that node with its topic, cursor and filter; the receiving node slices one call and one copy per node holding sockets object one delivery per edge, with that edge's events inline up to 32 KB, else the sequence range one call per follower object A channel with 5,000 live watchers spread over 8 nodes costs 8 sends per message. A publisher with 50 object followers costs 50, because each follower's cursor is its own. Connection edges Connection edges promise at most once. A local follower's events are pushed into its connection inbox of 256 items. Remote batches fan out to the receiving node's own inboxes. On the receiving node Effect the inbox has room the item lands; the program's event handler runs, or the platform writes the forward envelope with no vm the inbox is full the delivery is refused and the publisher prunes every edge that connection holds; the socket stays open the socket is gone reported back; the publisher prunes its edges The edge cursor advances whether or not the push landed. A miss is not retried: anything that must survive a tab closing belongs on the durable object one hop back. Durable edges Object edges promise at least once delivery with exactly once effect on the follower's own storage. The follower keeps a receive cursor per publisher and topic, checked before the handler runs and advanced inside the handler's own transaction. A handler that committed never runs again for that event: redelivery after a crash skips instead of repeating. Effects that leave the follower's transaction, a call to a third object or a kv write, are the window the handler side idempotence in [guarantees](/docs/runtime/guarantees) covers. Failure Effect the handler throws, or runs past 10 seconds a failed attempt; the edge backs off 500 ms, doubling 8 failed attempts (the last wait is 32 s) the edge is dropped the follower's recorded node no longer exists not a failure: delivery routes the follower's identity to wherever it rehomed a connection's recorded node no longer exists its edges are pruned; node ids never return Large payloads Events ride inline in a durable delivery up to 32 KB. Past that, the delivery carries only the sequence range and the edge's filter, and the receiving node materializes the events through the platform read path: its own copy of the publisher's file, else the holder, else the shipped replica. Connection batches have no range form and always ride inline, which they can afford because a node's copy is one per event however many sockets are owed it. Ordering The log has one home, so per publisher order is global no matter which path an event took: inline or range, local or forwarded. Events from one publisher reach one follower in publish order; across publishers there is no promise. Related [Streams](/docs/runtime/streams): the surface this implements. [Object placement](/docs/internals/objects/placement): replicas, which serve the catch up reads. [Guarantees and limits](/docs/runtime/guarantees): the delivery table with every number.

Event delivery

None of this is needed to build on Actias. It explains how the platform behaves under load, for readers who want the mechanics behind the promises in [guarantees](/docs/runtime/guarantees). Services Service Stores Role worker SQLite per object, local caches runs scripts, hosts objects, serves HTTP and the node to node data plane script service Postgres, Redis, blob storage scripts and revisions, project policy, live dev sessions placement service Postgres the placement store: object leases, node membership, alarms, the instance directory; one per region kv service Postgres by default; ScyllaDB selectable typed key value pairs by project and namespace secret service Postgres envelope encrypted secrets; workers hold no key material api Postgres public REST gateway: auth, projects, access control Services speak gRPC to each other. Workers also speak gRPC among themselves: forwarded object calls, delivery batches, directory hops, holder reads, and the write ahead log an owner fans out to the nodes that replicate its objects, with the chunks of a base a rotation changed streamed to the same nodes, all node to node without a coordinator. The control plane's availability The control plane is one Postgres primary with the api, script service and secret service in front of it. Its writes are rare: a publish, a policy edit, a region registration. Its reads are what every worker asks at runtime, cached on the pointer ttl: script pointers, revisions, aliases, project policy, regions, secrets. Those reads can go to a Postgres read replica ( READ DATABASE URL on the script and secret services; one replica per region in a multi region deployment), while writes and the console's own listings stay on the primary, so a publisher sees its publish at once. With the primary unreachable, everything already running keeps running: workers serve from their caches and then from the replica, objects ship to their region's bucket, placement is regional and unaffected. What stops is the control plane's writes, until the replica is promoted. Bundles are in the blob store, replicated by the store; no worker needs the primary to run a published script. Regions A deployment is one control plane and one or more regions, each a placement store, an object bucket and workers under one name. Nothing inside a region depends on another region; the one thing that crosses is an object call whose home is elsewhere, forwarded once. The [Regions](/docs/internals/regions/regions) page has the parts, the fence, and how a project moves. Node membership Membership is the root fact of the cluster: object leases and alarm rows hang off it. Every departure, graceful or reaped, writes a record of what the node held before its leases are freed, which is what the directory's crash sweep and the placement fence read. Related [Object placement](/docs/internals/objects/placement): leases, homes, and what membership changes do to them. [Event delivery](/docs/internals/objects/delivery): the node to node fan out path. [Guarantees and limits](/docs/runtime/guarantees): the promises this machinery upholds.

The cluster

Per surface Surface Scales with Serializes at HTTP request worker count, stateless nothing Object call instance count the instance's home task Object first touch one placement store claim the placement store; the holder cache absorbs repeats Database read , read one worker count, via replicas nothing Directory query class count; one reader per class the class's reader node Publish nodes holding followers, plus one per object follower the publisher's pump KV the kv store (Postgres, or ScyllaDB at volume) nothing Queue message queue count the queue's home task, 16 messages per firing The unit of serialization The object instance. One task runs its calls one at a time, which is what makes its transactions and its event log trivial; the price is that one instance is bounded by one core and one file. A hot instance is therefore a modelling problem, not a tuning problem. Split hot state across instances: a Channel per room rather than one router object, a counter per shard rather than one global counter. What one node absorbs Followers: delivery cost is per node for sockets, so co located sockets are nearly free. See [event delivery](/docs/internals/objects/delivery). Database reads: read and read one answer from a replica without touching the home. Every object method reaches the home. See [placement](/docs/internals/objects/placement). Scripts: pointer and blob caches keep the steady state node local. See [the cluster](/docs/internals/cluster/topology). Misrouted object calls: the holder cache forwards them from memory; the placement store is consulted on first touch and after a home moves, not per call. Where each queue is bounded Bound At Behaviour object mailbox 128 calls backpressure: the caller waits, nothing is dropped ack gate 10 s ( OBJECT ACK GATE MS ) for a replica quorum or the store a written call answers "outcome unknown"; the write keeps trying to ship ship concurrency 32 flights, 8 reserved ( OBJECT SHIP CONCURRENCY , OBJECT SHIP RESERVED ) flights a caller is waiting on always find a slot connection inbox 256 items deliveries: refused and the edges severed; client frames: the wire closes object edge 8 attempts, 500 ms doubling the edge is dropped queue message 5 attempts, 2 s doubling to 1 h dead lettered The platform sheds at the edges and blocks in the middle: the one bound that waits rather than drops is the mailbox, because a call has a caller to answer. Related [Event delivery](/docs/internals/objects/delivery): the fan out mechanics. [Object placement](/docs/internals/objects/placement): homes, replicas, and recovery. [Guarantees and limits](/docs/runtime/guarantees): the numbers.

Where load goes

A node is shared. Its bounds are node wide numbers, and the projects on it would otherwise compete for them by arrival order. Fair share turns every node wide bound into a per project one, computed from who is actually there, with no configuration per tenant. The pools Six things on a node are bounded, each a pool of permits: Pool Permits Setting requests in flight 1,024 REQUEST CONCURRENCY blocking work (overlay builds, folds, scans) 64 BLOCKING CONCURRENCY open connections 4,096 CONNECTION LIMIT resident objects 10,000 OBJECT RESIDENT LIMIT directory queries 64 DIRECTORY QUERY CONCURRENCY shipping flights, general lane 24 OBJECT SHIP CONCURRENCY minus the reserved lane A request holds a permit for its life; a connection for its life; a resident object for its residency; a flight for its store call. The permit is released when the holder ends, and the release wakes whoever waits. The rule Three consequences: 1. A node with room refuses nothing. A project alone on a node gets the node. A project over its share keeps taking what nobody else is using. The share is not a cap; it is a priority that exists only under pressure. 2. A floor's worth stays free for a late arrival. A project past its share stops one floor short of filling the pool, so a project that shows up to a busy node always finds its floor at once. That floor is its guarantee: 5% of the pool, which on a real node is fifty concurrent requests. 3. A full node refuses the project over its share first. When the pool is full and a permit is asked for, the project holding at or past its share is the one refused (429 with Retry After for a request; TOO MANY RESIDENTS for a spawn). A project under its share gets in as soon as anything is released, which for requests is milliseconds. Nothing is reserved for a project that is not there, which is what makes a single tenant cluster and a shared one the same code with the same numbers. Resident objects: eviction, not refusal Objects are the one pool where refusing is the wrong answer, because the thing asking is a call that will succeed once something idle makes room. When the residents pool is full and a spawn cannot fit: a project over its share puts its own idlest object to sleep (the one with the oldest last call) and the spawn proceeds; a project under its share puts to sleep the idlest object of whichever project is furthest over its share. A sleeping object loses nothing: its state is on disk and shipped, and it wakes on its next call. Only a pool where nothing is evicted within a second refuses. Nothing is evicted on a node with room. What it looks like The fair share drill in the repository runs two projects on one node with the request pool cut to eight: a big one with sixteen writers, a small one with two. Under the rule the small project's p99 stays within three times its solo number while the big one is refused at the floor, and the big project alone afterwards holds the whole node. The numbers are in the drill's output. Rates, by policy Fair share bounds what a project may hold on one node. A project's [policy](/docs/runtime/guarantees) bounds what it may spend per second: requests per second and work units per second, each a token bucket per node refilled from the policy, with a burst of one second's worth. Over the rate a request answers 429 before any vm is built; over the work rate the project is in debt until the bucket refills. Both are zero, meaning unbounded, unless set on the project's policy page.

Field	Type	Notes
`request.method`	string	`"GET"`, `"POST"`, …
`request.path`	string	relative to your script
`request.query`	table	decoded query parameters
`request.headers`	table	lowercase keys
`request.body`	string, or a byte array	raw body; a body that is not valid UTF-8 arrives as an array of bytes. Bodies over 10 MB are refused with 413
`request.uri`	string	full uri
`request.upgrade`	function or nil	present on websocket handshakes