@lunora/do

@lunora/do ships the two Durable Object base classes the runtime expects. 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.

SessionDO

Stateful session record for @lunora/auth. Holds short-lived session state and expires records after SESSION_DO_TTL_DEFAULT seconds (7 days) unless a shorter TTL is requested. 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.

import { SessionDO } from "lunorash/do";

export class MySessionDO extends SessionDO {}

Most apps re-export the default class; subclass it only if you need to extend the session shape.

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 and SessionDO both run with WebSocket hibernation enabled — inactive sockets cost zero CPU until a message arrives. Exposed via the HibernatableWebSocket type for unit tests.

ShardDOState / SocketAttachment / MutationDelta / RpcRequest / SubscriptionEnvelope / SubscriptionQuery

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

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)

See also

• @lunora/runtime
• Concepts: sharding