Skip to content
DocspackagesDocumentation

@lunora/do

The Durable Object base classes — ShardDO and SessionDO.

PackagesDo

@lunora/do ships the Durable Object (DO) base classes. ShardDO is the one the runtime drives on every request; SessionDO is a standalone building block (see the caveat below). You only touch them in src/server/*.ts when you need to add a custom RPC method or wire bespoke storage logic. The defaults are enough for most apps.

ShardDO

Base class for every shard. Owns the per-shard SQLite storage (one DB per DO instance), broadcasts subscription deltas to connected WebSockets, and implements the RPC fan-in.

import { ShardDO } from "lunorash/do";

export class MyShardDO extends ShardDO {
    // Optional: extend with custom RPC methods.
    public async customMethod(input: { foo: string }): Promise<{ ok: true }> {
        return { ok: true };
    }
}

The root shard (when you haven't called .shardBy(...) yet) routes to the DO named ROOT_SHARD_NAME. Storage above ROOT_DO_SIZE_WARN_BYTES emits a console warning so you remember to call .shardBy() before the DO hits its single-instance ceiling.

ShardDOOptions

Per-shard configuration. The generated shard passes these through to super(state, env, options) from the object you hand createShardDO(...), so you set them there rather than subclassing.

Prefer the generated app builder where you have one — defineApp() carries the same knobs as chainable methods and wires the worker half of each capability at the same time:

// src/server/index.ts
import { defineApp } from "../../lunora/_generated/app";

const app = defineApp<Env>()
    .shard((env) => env.SHARD)
    // `true` takes the defaults; an object tunes the caps.
    .reactiveCache({ maxBytes: 4 * 1024 * 1024, maxEntries: 1000 })
    .build();

export const ShardDO = app.ShardDO;

Hand-composing the worker instead, the same options are the createShardDO config:

export const ShardDO = createShardDO({
    // Memoize query results per shard, keyed by caller identity + args.
    // `true` takes the defaults; an object tunes the caps. Omit to disable.
    reactiveCache: { maxBytes: 4 * 1024 * 1024, maxEntries: 1000 },
    // Ceiling on the join keys one relation-crossing `where` may pre-resolve
    // before failing closed. Raise it for a trusted large fan-in relation.
    maxRelationKeys: 5000,
    // How a relation-crossing `where` resolves against a co-located child:
    // "auto" (cost-based, the default), "always" (inline EXISTS), or
    // "never" (universal semijoin). All three return identical rows.
    relationExistsPushDown: "auto",
});

reactiveCache is per-shard and in-memory: it is lost on DO restart and on hibernation, so a cold shard re-runs the query. Only registered query functions are memoized — a mutation or action always runs. Live counters (hits, misses, evictions, entries, bytes) show up on the studio's metrics panel.

Delivery authorization

Opt in with the generated app builder's .deliveryAuthorization(env => callback). The async callback receives { identity, shardKey, functionPath, args, transport, system, admin }. transport is "rpc" | "subscription"; system and admin are booleans. Lunora sets system: true only for server-initiated RPCs at its trusted binding. It sets admin: true only when a reserved admin function passes the configured bearer check. Subscription callbacks receive system: false and admin: false. These flags describe the request. Your callback decides whether either context receives a permit. Return undefined to deny or { scope, epoch } from current authority. Queries still own row and field filtering.

For RPCs, coded LunoraErrors keep their status and code. Explicit INTERNAL verdicts are terminal. Unclassified callback throws, including fetch failures reported as TypeError, return retryable SHARD_UNAVAILABLE (503). Invalid returned permits produce terminal INTERNAL (500). On subscription refresh, FORBIDDEN and INTERNAL authority failures end the registration; other failures retain it and retry on the next write flush. An unclassified throw during the first subscription seed ends that seed with SUBSCRIPTION_SEED_FAILED.

import { installDeliveryFence, type DeliveryPermit } from "@lunora/do";
import { defineApp } from "../../lunora/_generated/app";
import { readCurrentPermit } from "./authority";

const app = defineApp<Env>()
    .shard((env) => env.SHARD)
    .deliveryAuthorization((env) => async (request) => readCurrentPermit(env, request))
    .build();
export const ShardDO = app.ShardDO;

export async function fenceShard(env: Env, shardKey: string, fence: DeliveryPermit) {
    await installDeliveryFence(env.SHARD.getByName(shardKey), { env, shardKey, fence });
}

Implement readCurrentPermit in your application. scope is opaque, nonempty and at most 256 UTF-8 bytes; epoch is a nonnegative safe integer that increases with authority changes. Each subscription's permit is kept on the socket's 16 KiB WebSocket attachment (about 270 bytes at the maximum scope length), which a socket with many subscriptions shares with their metadata. Keep scopes short; a subscription whose permit no longer fits fails with SUBSCRIPTION_PERSIST_FAILED. Set the same nonempty LUNORA_RELAY_SECRET on the installer and shard; pass the target's exact shard key. The helper signs a private binding request and waits for acknowledgement. Commit policy and durable pending invalidations together, deny stale permits immediately, and retry every affected shard's fence before acknowledging revocation.

This supports RPCs and ordinary query-backed subscriptions. Guarded shards refuse shapes, streams, raw subscriptions, whispers, rooms and relays. The legacy broadcastDelta path throws NOT_IMPLEMENTED rather than delivering deltas. Replicas must route to the owner. Query caches and shared subscription evaluations are bypassed. Every write flush calls the authority callback again for guarded subscriptions. If the permit is unchanged, the subscription already has a delivered result and the write leaves its read set untouched, Lunora skips the query and sends a settled frame only when its cursor or client watermark advances. Reconnects send fresh full snapshots.

DELIVERY_FENCED means the operation may have committed. Retry with the same native transport key to check for its receipt. If authority changed, the shard may return terminal DELIVERY_RECEIPT_FENCED (409), without the stored result or another execution. Receipt replay requires the exact original scope and epoch, including after access is regranted: a new epoch can grant different row visibility, so its permit does not authorize returning bytes produced under the old one. Reconcile that operation against your own durable operation key and state before deciding whether to start a new operation. Do not replace the native key just to get past the fence.

Delivery authorization adds receipt markers to native idempotency rows. Rows written before opt-in have no marker. Replaying one while its native row is retained returns DELIVERY_RECEIPT_FENCED; the shard does not migrate or replay its stored result. Native rows and receipt markers use the same 24-hour retention window, so enabling delivery authorization can fence recent pre-opt-in operations.

SessionDO

A TTL'd session store in a Durable Object: records expire after SESSION_DO_TTL_DEFAULT seconds (7 days) unless the request passes its own ttlSeconds, which can be any whole number of seconds up to 90 days. A GC alarm sweeps daily, and instance count stays bounded by keying on the token prefix (idFromName(token.slice(0, 16))). Every request must present the SESSION_DO_SECRET shared secret in the x-lunora-session-do-secret header; when the secret is unset the DO rejects all calls with 401.

@lunora/auth does not use this class. It never has: grep -rn "SessionDO" packages/auth/src/ finds only a comment in auth-do.ts; nothing in that package imports or instantiates it. So exporting SessionDO, binding it as SESSION, and setting SESSION_DO_SECRET gets you a correctly-configured object that nothing ever calls; sessions still live in the auth database.

For auth on Durable Object storage, use LunoraAuthDO / .auth({ namespace }) from @lunora/auth. That path puts the whole better-auth schema, sessions included, in an object with real transactions (which is what @better-auth/scim requires). SessionDO remains usable on its own terms as a TTL'd token store; it is not wired into auth.

import { SessionDO } from "lunorash/do";

export class MySessionDO extends SessionDO {}

SessionRecord

Type-only export. The shape of an entry in the session DO's storage:

interface SessionRecord {
    userId: string;
    createdAt: number;
    expiresAt: number;
}

Hibernation

ShardDO runs with WebSocket hibernation enabled: inactive sockets stay connected while the Durable Object can hibernate until a message arrives. Exposed via the HibernatableWebSocket type for unit tests. (SessionDO has no WebSocket surface at all: it is HTTP-only, so hibernation does not apply to it.)

Alarm re-arm budget

A shard's poll alarm re-arms itself on each tick while a global shape, a source or a TTL backlog still has work. Left unchecked, an always-due source turns that into a loop that wakes the DO as fast as the runtime allows. Each shard therefore gets a budget of 300 re-arms due sooner than the 2 s floor per 60 seconds, a sliding-window count kept in the shard's own SQLite. Re-arms at or beyond the floor are not counted: they are at most one per 2 s, so 30 a minute, and the default is ten times that. Steady workloads never reach it.

When the budget is spent, the re-arm is refused and the shard arms one recovery wake one minute later, one millisecond past the window so the previous window has begun to decay. That wake runs the poll and sweep tiers, so an idle shard resumes polling and sweeping (global-shape refresh, source pulls, TTL deletes) once the window drains. A shard whose workload never drains is throttled, never stopped. It re-arms in bursts of about the limit, with quieter windows between them. Each trip logs one error record, whose message begins alarm re-arm breaker tripped and carries the limit and rearms fields, and counts shard.alarm_rearm.refused. That is about one record per window, not one per refused re-arm.

Writes are never refused. A pending schedule-outbox retry is exempt, so a job the scheduler has not yet accepted still gets its retry. TTL rows and source updates are delayed by about one window, never discarded. The codegen constructor's cold-start arms are refused while the budget is spent, and they are not counted in it.

Only re-arms due sooner than the 2 s floor write the window. A re-arm whose next wake is at least 2 s after its tick began is floor-paced. Those are checked against the window with a SELECT and recorded nowhere, so a healthy 2 s poll writes no window row. A healthy shard still reads the window row once per poll. A re-arm due sooner than 2 s, such as a source that is due now, is counted and written when admitted. Those are the re-arms that can loop, and they are the only ones the budget spends. A source with refresh.everyMs under 2 s is due sooner than the floor on every poll, so each of its polls is counted and written. A source at 2 s or slower is not. The window is one row, so an eviction does not reset it.

Cold starts are floor-paced too. A shard whose schema has a sourced or TTL tier arms that tier from its constructor on every instance, which is one read and no write. A tripped window still refuses that arm, so an eviction-driven loop cannot get around the budget.

Set LUNORA_ALARM_REARM_LIMIT to a positive integer to change the budget, or to 0 to disable it. An unset or malformed value keeps the default. A bulk backfill that drains a large TTL backlog can legitimately exceed the default, so raise the limit for that deployment.

Schedule rate budget

A job that reschedules itself through ctx.scheduler.runAfter never touches the poll alarm, so the alarm budget above does not see it. Each run schedules the next, and nothing else bounds how often that happens. The schedule-rate budget covers that path.

It counts invocations per target per shard, over a 60-second sliding window. A target is the function a schedule runs. An invocation is one mutation or action dispatch. A fan-out of many jobs to one target from one invocation counts once, so a legitimate import that schedules one job per row is not throttled. A self-loop counts once per iteration.

The default is 600 invocations per minute, or 10 per second. A self-loop runs at most one iteration per round trip (the scheduler's alarm pass, the dispatch, the run). At an assumed 100 ms round trip, a loop reaches the budget at 10 iterations per second, and its daily ceiling is 864,000 per target per shard.

The budget is not lowered for slower loops, and a self-loop gets no lower limit. At 600 per minute, a loop that reschedules itself 2 times per second (120 per minute, 172,800 per day per target) is not caught. A blanket limit of 120 would defer any app that schedules one target from more than 2 invocations per second, the whole app being one shard by default. A self-only limit needs the calling function's path, which the generated buildCtx has but does not pass to the scheduler facade. Its composed calls also inherit the outer function's path, so a self-loop through ctx.runMutation would still count as fan-in. Only ctx.scheduler is covered: createWorkpool and createQueueWorkpool enqueues do not pass through this budget.

When the budget is spent, the schedule is deferred one minute, not refused and not dropped. Its due time moves to one window out. A job already due later than that keeps its time. Each trip logs one error record, whose message begins schedule rate breaker tripped and names the target, and counts shard.schedule_rate.deferred. The error record is written at most once per window per target and instance, however many refusals follow, so steady load at the limit does not flood the log.

Known false positive: a steady workload above 10 invocations per second per shard and target, such as one email job per request, is delayed by a window. It still runs. Raise the limit for that deployment.

Ordering: a job admitted after a deferral can run before an earlier deferred job for the same target. Deferred jobs keep their own due times, and the window re-admits in the meantime. A self-loop has one job in flight, so this matters only for fan-in workloads. Do not rely on the order of same-target schedules across a throttle.

Set LUNORA_SCHEDULE_RATE_LIMIT to a positive integer to change the budget, or to 0 to disable it. An unset or malformed value keeps the default.

The window is one row per target in the shard's SQLite. It is written inside the invocation's transaction, so a rolled-back invocation does not count.

ShardDOState / MutationDelta

Internal serialization shapes. Stable across patch releases so add-ons can type their broadcast payloads.

SocketAttachment, RpcRequest, SubscriptionEnvelope and SubscriptionQuery are not exported from here — they belong to the host-neutral engine, so import them from @lunora/shard-engine.

Constants

  • ROOT_SHARD_NAME: the DO instance name used by the root shard
  • ROOT_DO_SIZE_WARN_BYTES: soft cap above which the root DO logs a warning
  • SESSION_DO_TTL_DEFAULT: default session TTL (SessionDO)

Other exports

ExportPurpose
mergeDurableObjects(...), MERGED_ROLESCombines the framework roles listed in MERGED_ROLES (adminRevocations, scheduler, shardRegistry) into one Durable Object class.
AdminRevocationDO, ADMIN_REVOCATION_DO_NAMEDurable Object that records revoked admin tokens outside shard storage, so a point-in-time restore cannot bring a revoked token back.
ShardRegistryDO, hostedShardRegistry, SHARD_REGISTRY_DO_NAMEDurable Object that holds the live set of shard keys per sharded table. The query coordinator reads it to fan out cross-shard reads.
createStableIdFactory(mutationId, scope)Returns the ctx.newId() generator. A replay of the same mutation issues the same ids, so a retried insert does not create a duplicate row.
createShardPlatform, createWorkerPlatformThe Cloudflare composition roots. Each assembles the @lunora/platform contracts from the Durable Object state or the Worker env.