Live

Path params become a filter: an event is forwarded when each :param that exists on the payload equals the request value. Params missing from the payload are skipped (the event still flows). No params = firehose.

import { on, http } from "okengine";
import { member } from "@/core/gate";
import { orderStatus } from "@/signals/orders";

export const events = on(http.get("/orders/:orderId/events").gate(member).live(orderStatus));

GET /orders/ord_1/events receives { orderId: "ord_1", status: "shipped" } and drops events for other orders.

Pass your own Flow as the second argument to on() when auto-match is not enough. Return fx.live(signal, { match }) from do — do not wrap it with fx.json.stream.

import { on, flow, http } from "okengine";
import { member } from "@/core/gate";
import { orderStatus } from "@/signals/orders";

export const vipFeed = on(
  http.get("/orders/vip/events").gate(member).live(orderStatus),
  flow({
    do: (_input, fx) =>
      fx.live(orderStatus, {
        match: (payload) => payload.status === "shipped",
      }),
  }),
);

Consequence: a custom Flow stamps a distinct match key, so it can coexist with the auto-match route for the same signal (different path). Two synthesized firehoses that share signal and gates fail uniqueness — see Uniqueness.

Resource / table live is not a signal tape. Each subscriber gets classified row events (RLS + list filters). Prefer http.resource + { live: true } when you already mount the five CRUD ops.

Wire events (consumed with useLiveQuery on the typed client):

For a handwritten list, bind the table on GET and open the window with liveQuery — full detail under HTTP · Live Streams.

Boot keys each live HTTP route as (signal, gates, match). Match is the sorted path-param names, or custom:<flow> when you passed a Flow, or (firehose) when there are no params.

OKE1050 cause: Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}). Fix: a different gate, a path-param filter, or drop the extra route.

Confirm on(http.live(signal)) (or a path .live(signal)) is adopted. Names in the default path are URI-encoded (encodeURIComponent). A bare 404 with body Not Found means the router found no match.

.live(signal) only attaches to http.get / http.live. Other verbs reject live synthesis: on(http.*.live(signal)): live exposure must be GET.

Cause: Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match} ). Two firehoses (http.live or param-less .live) that share the signal and gates cannot boot. Change the gate, add a path-param filter, or remove a route.

Cause: {method} {path} is bound twice (flow "{flow}"). Two mounts collide on the same method + path (for example two http.live firehoses that resolve to the same URL). Drop one binding.

Cause: Cursor "{afterId}" missing on "{signal}". That Last-Event-ID was pruned or never existed. Reconnect without it; remaining events replay. autoResubscribe: true does this after backoff.

No subscriber / exposure counted. Set { optional: true } (usual for firehoses) or mount http.live before emitting in tests.

Cause: "{resource}": {detail} from the Standard Schema issues. Align the payload with schema — no client receives a frame.

Live is not competing-consumer physics. Use signal.once for workers, or expose SSE with http.live.

That path is not the engine firehose. Use GET /_oke/live/{name}, a gated .live route, or api.live / useLive from the typed client.

Two routes share the same match shape. Pass via: "unit.flow" or call the exposing Flow (api.orders.events({orderId}, {onEvent})) instead of root api.live.

retention: { maxAge, maxCount } is live-only. Drop it on queue / pub-sub Signals, or switch to signal.live.

Extract: live: true on table "…" requires a primary key column. Runtime needs an RLS-capable SQL driver (postgres / pglite) and a gated identity. That path is resource live — not signal.live. Attach .gate(...) and declare a PK.