API reference

Start the endpoint (background thread in the shim). object=True registers a Virtual Object — keyed, with state and single-writer concurrency per key; False a plain (stateless) Service. workflow=True registers a Workflow: the handler named "run" is the workflow handler (runs once per key), the rest are shared and may use the promise operations to signal it.

Durable sleep. Journaled; long sleeps suspend the invocation.

Durable request/response call to another handler. A non-empty key targets a virtual object; empty targets a plain service.

Durable one-way message (optionally delayed).

Create an awakeable — a durable promise resolvable from outside (another service, or the ingress HTTP API). Returns its id: hand it to the outside world (inside run_enter/run_exit or via call), then awakeable_await it.

Await an awakeable created in this invocation; returns its resolved payload. Suspends if unresolved.

Resolve another invocation's awakeable with a payload.

Reject another invocation's awakeable with a terminal error.

Await a named workflow promise (workflow services only).

Peek a named workflow promise: its value, or None if unresolved.

Resolve a named workflow promise (from a shared handler).

Reject a named workflow promise with a terminal error.

Cancel another invocation by id.

Enter a journaled side-effect block. Returns the journaled value on replay; None means: execute the side effect now, then close the block with run_exit (it succeeded) or run_fail (it did not).

Exactly one of those must follow. Leaving the block open makes the invocation unreplayable: every later attempt raises "protocol error: expected rst_run_exit".

Journal the side-effect result produced after run_enter returned None. Returns the journaled value.

run_enter, with a retry policy for this block's non-terminal failures.

Plain run_enter leaves retries to Restate's server-side invoker policy, which retries indefinitely. Set any of these to bound it; 0 means "leave that knob alone", and max_attempts or max_duration_ms of 0 mean unbounded.

When attempts or duration run out the SDK fails the block terminally, which arrives here the same way run_fail(terminal=True) does — as a raised error the handler can compensate for.

One journaled step: replay it, or run f and journal what it returned.

def charge() raises {imm reservation_id} -> String: return charge_card(reservation_id)

var charge_id = app.step(inv, charge)

f is passed by value with an explicit capture list, which keeps what it captures alive until step returns. Its type is a parameter, so each closure still gets its own monomorphised step.

This is run_enter / run_exit / run_fail with the protocol handled. It matters less for brevity than for the fact that a block cannot be left open: if f raises, the step is closed as a non-terminal failure and Restate runs it again, which is what the hand-written form has to remember to do every time.

The retry arguments are run_enter_policy's, and bound the retries of f itself. Passing none leaves them to Restate's invoker policy, which does not give up.

A step that should fail terminally — a downstream that is not coming back, where the handler compensates and finishes — wants the explicit protocol instead: run_enter, then run_fail(terminal=True).

Abort the run block opened by run_enter, rather than closing it with run_exit.

Every run_enter that returns None must be closed by exactly one of run_exit or run_fail. Leaving one open makes the invocation unreplayable: the next attempt raises "protocol error: expected rst_run_exit" and keeps doing so forever.

terminal=True journals the failure. The step is recorded as failed, replay reproduces the failure instead of executing again, and this raises so the handler can compensate and finish.

terminal=False journals nothing and lets Restate re-run the block under its own retry policy. The return value is then the next execute slot: None means "run the side effect again", and a value means the journal answered in the meantime.

Finish the invocation successfully with output.

Finish the invocation with a terminal error (not retried).

Drop an invocation without completing it (after suspension or an internal error). Restate retries/resumes it with journal replay.

Unblock every next() — in this thread or any other — so driver loops can end.

Setting a flag in Mojo cannot reach a thread parked inside the shim's blocking receiver, so this goes through the shim (rst_stop), which sets a process-wide flag its receive loop rechecks. Idempotent, and safe to call from inside a handler: that is how a service gives itself a shutdown endpoint.

The endpoint itself keeps listening — this ends the Mojo driver, not the HTTP server. There is no un-stop.

Whether stop() has been called.

Discover the module's handlers, serve them, and block until stopped.

The whole driver:

@fieldwise_init
struct Stats(Copyable, Movable):
    var seen: Int64

def handle_add(app: App, inv: Invocation, w: Int, ctx: Ctx[Stats]) raises:
    app.complete(inv, String("ok"))

def main() raises:
    var stats = Stats(0)
    _ = App.run[Stats, __functions_in_module()]("Counter", stats)

Every handle_* in the calling module is registered under its name without the prefix and dispatched to by that name. There is no list to keep in step with the handlers, because there is no list.

Pass __functions_in_module() for funcs. state is process-local and shared by every worker — see Ctx.

Returns how many invocations completed without raising.

serve, with the process-local state carried as a typed Ctx[T].

The same driver; the only difference is that the handler receives Ctx[T] instead of a raw OpaquePtr, so it can say ctx[].field rather than computing offsets. state must outlive the call, which it does: serve joins every worker before returning.

Prefer this over serve. The untyped form remains for handlers whose state is genuinely not a single struct.

Run handler on num_workers threads until stop() is called.

The concurrent counterpart to the while True: app.next() loop, and the reason a handler may now call another handler served by this same process: with two or more workers, one thread waits for the callee while another picks it up. With one worker that is still a deadlock, exactly as before.

Blocks until every worker has left its loop, then returns.

A Ctx over state, the one erasure served mode still performs: state is an argument of serve_with, which joins every worker before it returns, so it outlives the workers by construction even though the pointer no longer carries the origin that would say so.

Rebuild the typed view inside a worker, from what serve passed.