@mcp-b/do-runtime 0.1.0

package/dist/src/api/sql.d.ts

@@ -0,0 +1,188 @@
+/**
+ * ← workerd `src/workerd/api/sql.{h,c++}`
+ *
+ * `SqlStorage` and its two nested types. ~330 call sites depend on this — it is
+ * the real storage layer, not KV.
+ *
+ * Four things about the translation, in descending order of how much they cost:
+ *
+ *  1. **The cursor is materialised, not live.** Upstream's `Cursor` owns a
+ *     running `SqliteDatabase::Query` and pulls one row at a time; the backend
+ *     seam this package chose (`SqlDatabase.exec` → `SqlResult`) has already
+ *     collected every row before a cursor exists. Everything downstream of that
+ *     follows: there is no statement cache, so `CachedStatement`, the 1 MiB LRU
+ *     and `reusedCachedQueryForTest` are absent with it; there is no live
+ *     statement to cancel, so `Cursor::canceled` and `selfRef` — both already
+ *     dead upstream, written but never assigned — have nothing to guard; and
+ *     `endQuery`'s job of returning a statement to the cache is nothing here, so
+ *     the counters it saves off are simply the counters. What is kept is every
+ *     observable: the position is shared across `next`/`toArray`/`one`/`raw`,
+ *     and a drained cursor keeps yielding done.
+ *  2. **`Cursor` and `Statement` must be constructible with no arguments**, or
+ *     `SqlStorage` cannot satisfy workers-types without a cast: the interface
+ *     types them `typeof SqlStorageCursor` / `typeof SqlStorageStatement`, and
+ *     both are `abstract` there, so their construct signatures take none.
+ *     Upstream's are unconstructible from JS for the same reason they are
+ *     `abstract` in the types — JSG nested types have no JS constructor — so the
+ *     faithful shape is a constructor that refuses. `sql.Cursor` exists for
+ *     `instanceof`, which is all upstream exposes it for.
+ *  3. **The regulator is ported whole; what is missing is the authorizer that
+ *     calls it.** All three callbacks are here and none of them needed the
+ *     authorizer to compute anything — `isAllowedName` is a prefix test,
+ *     `isAllowedTrigger` is `return true`, `allowTransactions` throws. What the
+ *     authorizer supplied was the *identifiers*, not the decisions. With no
+ *     authorizer the statement text is the only source, so `exec` tokenizes it
+ *     and runs `isAllowedName` over every identifier-shaped token. That is
+ *     deliberately STRICTER than upstream — see `SQL_RESERVED_PREFIX_MESSAGE`.
+ *  4. **`ingest` stays at upstream's SQLite seam.** `SqliteDatabase.ingest()`
+ *     executes every complete statement and returns the partial tail, using the
+ *     same compiled boundaries and regulator as `exec`.
+ *
+ * Spec: §1.4, §2.4 in docs/decisions.md.
+ */
+import type { IoContext } from "../io/io-context.js";
+import type { SqlIngestResult, SqliteDatabase } from "../util/sqlite.js";
+/**
+ * ← `SqlStorage::BindingValue`. JSG converts these public JavaScript values
+ * to workerd's `Maybe<OneOf<Array<byte>, String, double>>` before C++ sees them;
+ * `toSqlBindingValue()` is that conversion for this no-isolate runtime.
+ */
+export type BindingValue = ArrayBuffer | ArrayBufferView | string | number | boolean | null | undefined;
+/** ← the `SqlStorageValue` `JSG_TS_DEFINE` on `Cursor`. */
+export type SqlRow = Record<string, SqlStorageValue>;
+/** ← `SqlStorage::IngestResult`. */
+export type SqlStorageIngestResult = SqlIngestResult;
+/**
+ * ← `SqlStorageRegulator::allowTransactions()`, copied verbatim. Users match on
+ * it and it is the one regulator callback our substrate can still answer.
+ */
+export declare const SQL_TRANSACTION_REFUSED_MESSAGE: string;
+/** See translation 2 in the header: the class is exposed for `instanceof` only. */
+export declare const CURSOR_NOT_CONSTRUCTIBLE_MESSAGE = "Illegal invocation: SqlStorage.Cursor cannot be constructed directly. Use sql.exec().";
+/** Same, for the prepared-statement compatibility shim. */
+export declare const STATEMENT_NOT_CONSTRUCTIBLE_MESSAGE = "Illegal invocation: SqlStorage.Statement cannot be constructed directly. Use sql.prepare().";
+/**
+ * ← SQLite's own denial text, with the reason appended.
+ *
+ * There is no upstream string to copy here: `SqlStorageRegulator::onError` just
+ * rethrows whatever SQLite produced, and SQLite produces `not authorized` for an
+ * authorizer denial (`access to X.Y is prohibited` for the column-read case,
+ * which needs a resolved identifier we do not have). The prefix is kept so that
+ * anything matching upstream still matches; the rest is here because a bare
+ * `not authorized` is not debuggable.
+ */
+export declare const SQL_RESERVED_PREFIX_MESSAGE: string;
+/**
+ * ← `SqlStorageRegulator` (`sql.h:15-22`, `sql.c++:143-173`), whole.
+ *
+ * Upstream reaches these through the SQLite authorizer while a statement is
+ * being compiled. `exec` calls them from the statement text instead, which is
+ * the same translation Section 3 made for the write classifier and for
+ * transaction state.
+ */
+export declare const SqlStorageRegulator: {
+    /**
+     * Upstream's body is `return !name.startsWith("_cf_")`, with an autogate that
+     * makes the comparison case-insensitive and logs a warning until it lands. The
+     * case-insensitive form is taken here: it is the direction upstream is moving,
+     * and there is no logger for the warning half.
+     */
+    isAllowedName(name: string): boolean;
+    /** Upstream's body is `return true`. */
+    isAllowedTrigger(_name: string): boolean;
+    /** Upstream's body is a `JSG_FAIL_REQUIRE` with this message. */
+    allowTransactions(): never;
+    /** "Bill for queries executed from JavaScript." Nothing reads it — `SqliteObserver` has no port. */
+    shouldAddQueryStats(): boolean;
+};
+/**
+ * ← the `jsg::Ref<DurableObjectStorage>` `SqlStorage` holds, narrowed to the one
+ * member it reaches through (`SqlStorage::getDb`). `DurableObjectStorage`
+ * satisfies it; narrowing is what keeps this file free of a value-level import
+ * cycle, which upstream tolerates because C++ headers do not have one.
+ */
+export interface SqlStorageOwner {
+    /** ← `DurableObjectStorage::getSqliteDb`. Throws if not SQLite-backed. */
+    getSqliteDb(): SqliteDatabase;
+}
+/** The rows a cursor walks, plus the counters that outlive them. */
+type CursorState = {
+    readonly columnNames: string[];
+    readonly rawRows: readonly (readonly SqlStorageValue[])[];
+    readonly rowsWritten: number;
+};
+/**
+ * ← `SqlStorage::Cursor`.
+ *
+ * `rowsRead` is the one counter that is not upstream's. Upstream reads
+ * `Query::getRowsRead()`, a billing counter sourced from libsql's
+ * `STMTSTATUS_ROWS_READ` that counts index rows and that neither backend
+ * exposes — the same absence the README already records for `SqlResult`. The
+ * interface requires a number, so this returns the rows the cursor has yielded,
+ * which is what today's browser host returns and what its tests assert. It
+ * undercounts any query that scans more rows than it returns.
+ */
+export declare class Cursor<T extends SqlRow = SqlRow> implements SqlStorageCursor<T> {
+    #private;
+    readonly columnNames: string[];
+    constructor(state?: CursorState);
+    /** ← `Cursor::next`, whose `RowIterator::Next` is this exact shape. */
+    next(): {
+        done?: false;
+        value: T;
+    } | {
+        done: true;
+        value?: never;
+    };
+    /** ← `Cursor::toArray`, which drains from the current position. */
+    toArray(): T[];
+    /** ← `Cursor::one`. Both messages are upstream's, verbatim. */
+    one(): T;
+    /** ← `Cursor::raw`, which shares this cursor's position rather than restarting. */
+    raw<U extends SqlStorageValue[]>(): IterableIterator<U>;
+    /** ← `JSG_ITERABLE(rows)`. */
+    [Symbol.iterator](): IterableIterator<T>;
+    get rowsRead(): number;
+    /** ← `Cursor::getRowsWritten`, which is `SqlResult.rowsWritten` here. */
+    get rowsWritten(): number;
+}
+/**
+ * ← `SqlStorage::Statement`, which upstream describes as "supported only for
+ * backwards compatibility ... it is actually just a wrapper around `exec()`".
+ * `JSG_CALLABLE(run)` makes the object itself callable, so `prepare()` returns a
+ * function wearing this prototype rather than an object with a `run` method.
+ */
+export declare class Statement {
+    constructor();
+}
+/** What `prepare()` hands back: `Statement::run`, reachable by calling it. */
+export interface PreparedStatement {
+    <T extends SqlRow = SqlRow>(...bindings: BindingValue[]): Cursor<T>;
+}
+export declare class SqlStorage implements globalThis.SqlStorage {
+    #private;
+    constructor(ctx: IoContext, owner: SqlStorageOwner);
+    /** ← `JSG_NESTED_TYPE(Cursor)`. Exposed so `instanceof` works, as upstream's is. */
+    readonly Cursor: typeof Cursor;
+    /** ← `JSG_NESTED_TYPE(Statement)`. */
+    readonly Statement: typeof Statement;
+    exec<T extends SqlRow = SqlRow>(query: string, ...bindings: BindingValue[]): Cursor<T>;
+    /**
+     * ← `SqlStorage::getDatabaseSize`.
+     *
+     * Upstream's second query is `PRAGMA page_size;`, which `sqlite3_stmt_readonly()`
+     * reports read-only. With no such call the text is the only source and §1.7.1's
+     * rule is write-unless-provably-a-read, so a bare `PRAGMA` would open a
+     * transaction and take an output-gate lock to answer a size question. The
+     * `pragma_page_size` table-valued function is the same value read through the
+     * `SELECT` upstream already uses for the page count.
+     */
+    get databaseSize(): number;
+    /** ← `SqlStorage::prepare`. Experimental and deprecated upstream; `exec` caches for you. */
+    prepare(query: string): PreparedStatement;
+    /** ← `SqlStorage::ingest`. */
+    ingest(query: string): SqlStorageIngestResult;
+    /** ← `SqlStorage::setMaxPageCountForTest`, which is what its name says. */
+    setMaxPageCountForTest(count: number): void;
+}
+export {};

package/dist/src/api/sync-kv.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ← workerd `src/workerd/api/sync-kv.{h,c++}`
+ *
+ * "Synchronous KV storage. Available as ctx.storage.kv on SQLite-backed DOs."
+ *
+ * This module is not in Section 5's brief and exists because
+ * `DurableObjectStorage` cannot satisfy workers-types without it: the interface
+ * declares `kv: SyncKvStorage` unconditionally, and §2.4's rule is that the
+ * surface is verified by the type system rather than by a cast. It is also a
+ * genuine part of the contract — a whole KV surface that skips the promise
+ * wrapper, over the same `SqliteKv` `DurableObjectStorage` writes through, with
+ * the same codec.
+ *
+ * Two things upstream has that are absent, both already absent below this file:
+ * the trace spans every method opens, and the billing counters. What is kept is
+ * the whole of the behaviour, including the one error that is neither of those:
+ * a `list()` iterator invalidated by a second `list()` says so rather than
+ * silently ending, which is `SqliteKv::ListCursor::wasCanceled()`.
+ *
+ * Spec: §2.4 in docs/decisions.md.
+ */
+import type { IoContext } from "../io/io-context.js";
+import type { SqliteKv } from "../util/sqlite-kv.js";
+/**
+ * ← the `jsg::Ref<DurableObjectStorage>` `SyncKvStorage` holds, narrowed to the
+ * one member it reaches through (`SyncKvStorage::getSqliteKv`).
+ */
+export interface SyncKvStorageOwner {
+    getSqliteKv(): SqliteKv;
+}
+/** ← `SyncKvStorage::ListOptions`, which is `ListOptions` minus the two gate flags. */
+export type SyncKvListOptions = {
+    start?: string;
+    startAfter?: string;
+    end?: string;
+    prefix?: string;
+    reverse?: boolean;
+    limit?: number;
+};
+export declare class SyncKvStorage implements globalThis.SyncKvStorage {
+    #private;
+    constructor(ctx: IoContext, owner: SyncKvStorageOwner);
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * ← `SyncKvStorage::list`, which reuses `compileListOptions` — "This is public
+     * so that SyncKvStorage can reuse it."
+     */
+    list<T = unknown>(options?: SyncKvListOptions): Iterable<[string, T]>;
+    put<T>(key: string, value: T): void;
+    delete(key: string): boolean;
+}

package/dist/src/api/web-socket.d.ts

@@ -0,0 +1,93 @@
+/**
+ * ← workerd `src/workerd/api/web-socket.{h,c++}` — the gating, and nothing else.
+ *
+ * A socket is the one primitive that is neither of the other two, and §1.8 says
+ * why in three lines: incoming frames "each take a fresh input lock via
+ * `context.run(...)`", the read loop "captures the critical section at
+ * `accept()` time", and outbound messages "each carry their own output-gate
+ * promise captured at `send()` time". Upstream states the first outright, on the
+ * line that does it (`web-socket.c++:1056-1059`):
+ *
+ * > "Re-enter the context with context.run(). This is arguably a bit unusual
+ * > compared to other I/O which is delivered by return from context.awaitIo(),
+ * > but the difference here is that we have a long stream of events over time.
+ * > It makes sense to use context.run() each time a new event arrives."
+ *
+ * So a socket cannot be `awaitIo`: there is no single result to resume from.
+ * `accept()` starts a loop, and the loop is the gate's caller.
+ *
+ * **What is ported and what is not.** The frame protocol, the hibernation
+ * states, auto-response, `WebSocketPair` and the byte accounting are all
+ * absent — the substrate ships a `WebSocket`, and hibernation is a recorded
+ * substrate boundary with no Chrome lifecycle to be faithful to. What is here is
+ * `WebSocket::Accepted`: the three gate properties above, over whatever socket
+ * the host hands in. That is the same division `api/http.ts` makes and for the
+ * same reason.
+ *
+ * **The accept contract, and the hole it leaves.** After `acceptWebSocket`, the
+ * gated view owns the raw socket's events. A consumer that keeps a reference to
+ * the raw socket and registers a listener on it directly gets that listener
+ * called ungated, and nothing here can prevent it — upstream cannot be reached
+ * that way because `accept()` moves the `kj::WebSocket` into `Accepted` and the
+ * JS object never had it. The refusal below covers the case that is detectable
+ * (accepting the same socket twice); the rest is the accept contract, stated.
+ *
+ * Spec: §1.1, §1.8 and decision 5 in
+ * docs/decisions.md.
+ */
+import type { IoContext } from "../io/io-context.js";
+/**
+ * The socket beneath. Deliberately structural and minimal: a real `WebSocket`,
+ * the extension's `WebSocketFacade` over capnweb, and a test double all satisfy
+ * it, and none of them is a type this package should name.
+ */
+export interface RawWebSocket {
+    addEventListener(type: string, listener: (event: Event) => void): void;
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+}
+/** ← the `JSG_REQUIRE(!native.state.is<Accepted>(), ...)` at the head of `accept()`. */
+export declare const ALREADY_ACCEPTED_MESSAGE: string;
+/**
+ * ← `WebSocket::Accepted` (`web-socket.h:~300-360`), reached through
+ * `accept()` → `internalAccept(js, IoContext::current().getCriticalSection())`
+ * → `startReadLoop` (`web-socket.c++:133`, `:426`, `:429-433`, `:507`).
+ *
+ * An `EventTarget`, so a consumer registers listeners the way it would on a real
+ * socket — but on THIS object rather than on the raw one, because this is what
+ * runs them inside a gated slice.
+ */
+export declare class AcceptedWebSocket extends EventTarget {
+    #private;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    constructor(ctx: IoContext, socket: RawWebSocket);
+    /**
+     * ← `WebSocket::send` (`web-socket.c++:~640`), which inserts a
+     * `GatedMessage{IoContext::current().waitForOutputLocksIfNecessary(), …}`.
+     *
+     * Synchronous, as upstream's is: the wait is the pump's, not the caller's. The
+     * output gate is what "blocks all outgoing messages from an actor that would
+     * allow the rest of the world to observe the actor's state" (§1.1), and a
+     * socket frame is exactly such a message.
+     *
+     * `waitForOutputLocksIfNecessary()` collapses to `waitForOutputLocks()` here
+     * for the reason the whole file collapses `kj::Maybe<Worker::Actor&>`: its
+     * body is `actor.map(…)` (`io-context.c++:383-386`) and every context in this
+     * runtime is an actor context.
+     */
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** ← `WebSocket::close`, which enqueues a `Close` through the same gate. */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * ← `accept()` / `state.acceptWebSocket()`, as the one verb.
+ *
+ * Named for what upstream names it, because the critical-section capture is a
+ * property of accepting rather than of constructing: "a socket accepted inside a
+ * `blockConcurrencyWhile` delivers its messages inside that critical section"
+ * (§1.8).
+ */
+export declare function acceptWebSocket(ctx: IoContext, socket: RawWebSocket): AcceptedWebSocket;