@nimbus-sh/core 0.1.0

package/dist/runtime/virtual-socket-kernel.d.ts

@@ -0,0 +1,252 @@
+/**
+ * virtual-socket-kernel.ts - shared in-facet loopback socket substrate.
+ *
+ * The kernel has two halves, and they are mirror images of each other.
+ *
+ * Inbound (a guest server accepting a connection). The supervisor-facing
+ * surface stays the existing PortRegistry: /port/<n>/ and
+ * /preview/?port=<n> route a real Worker Request to a facet's
+ * handleHttpRequest(Request). Inside the facet this kernel converts that
+ * Request into an accepted HTTP/1.1 byte stream so guest runtimes can
+ * implement normal socket APIs without Cloudflare inbound TCP support.
+ *
+ * Outbound (a guest client dialing 127.0.0.1:<port>). connect() hands back
+ * a connection whose write side parses the HTTP/1.1 request the guest
+ * emits, hands it to the host's loopback router - the same
+ * SUPERVISOR.routeLoopback the shell's curl and node's patched fetch use -
+ * and streams the Response back as HTTP/1.1 response bytes on the read
+ * side. Cloudflare has no outbound TCP to 127.0.0.1, so a loopback client
+ * socket can only ever be HTTP-shaped; see the connect() doc comment for
+ * exactly what that does and does not support.
+ *
+ * Runtime adapters (Python socket.py, Ruby socket.rb, future
+ * wasm32-wasi-nimbus syscalls) call this shared kernel instead of each
+ * implementing their own preview bridge.
+ *
+ * This file is the typed source of truth. scripts/bundle-facet-workers.mjs
+ * bundles it at build time into virtual-socket-kernel.generated.ts as the
+ * self-contained VIRTUAL_SOCKET_KERNEL_SRC string that python-runner and
+ * ruby-runner splice into dynamic worker module sources. Because that
+ * bundle ships as injected source text, this module must stay free of
+ * runtime imports - supervisor modules are unreachable from facet isolates.
+ */
+/** Hooks the per-runtime adapter glue installs on the facet global scope. */
+export interface VirtualSocketHost {
+    /** Called when a new port starts listening so the adapter can register it with the supervisor. */
+    __nimbusVirtualSocketDidListen?: (port: number) => void;
+    /** Gives the runtime a chance to (re)create a listener before a request 502s. */
+    __nimbusVirtualSocketEnsureListener?: (port: number) => unknown;
+    /**
+     * Cooperative accept pump. Pyodide/ruby.wasm cannot run a background
+     * accept loop (JSPI suspension is only legal on this dedicated pump),
+     * so the kernel queues the connection and then asks the runtime to
+     * process it. Returning false rejects the queued request.
+     */
+    __nimbusVirtualSocketRequestQueued?: (port: number) => Promise<boolean | undefined> | boolean | undefined;
+    /** Detail string surfaced when the request pump returns false. */
+    __nimbusVirtualSocketLastError?: string;
+    /**
+     * Routes an outbound loopback request to whatever is listening on the
+     * port, by delegating to the supervisor's `routeLoopback` RPC. Absent
+     * when the runtime has no supervisor binding, which makes connect()
+     * fail with a clear diagnostic instead of hanging.
+     */
+    __nimbusVirtualSocketRouteLoopback?: (port: number, request: Request) => Promise<Response>;
+}
+/** Facet global scope once the kernel is installed. */
+export interface VirtualSocketGlobalScope extends VirtualSocketHost {
+    __nimbusVirtualSockets?: VirtualSocketKernel;
+}
+/** Buffer and timing bounds enforced by the kernel. */
+export interface VirtualSocketKernelLimits {
+    /** How long handleHttpRequest waits for a complete response before answering 504. */
+    responseTimeoutMs: number;
+    /** Largest request body accepted into the inbound read queue (whole-body buffered in stage 1). */
+    maxRequestBodyBytes: number;
+    /** Largest total response byte count accepted into the outbound write queue (whole-response buffered in stage 1). */
+    maxResponseBufferBytes: number;
+}
+/** Result shape of accept()/acceptNow(); host/port mirror a loopback peer. */
+export interface AcceptedVirtualConnection {
+    id: number;
+    host: string;
+    port: number;
+}
+/** Pyodide proxies cross the FFI boundary with a toJs() converter. */
+interface PyodideProxyLike {
+    toJs(): unknown;
+}
+/** Byte payloads accepted by send(); covers JS, Pyodide, and ruby.wasm callers. */
+export type VirtualSocketBytesLike = Uint8Array | ArrayBuffer | ArrayBufferView | readonly number[] | string | PyodideProxyLike;
+/**
+ * Stage 2 contract: what the kernel must grow before request/response
+ * bodies can stream end-to-end instead of being fully buffered. Stage 1
+ * keeps the cooperative accept model (see
+ * VirtualSocketHost.__nimbusVirtualSocketRequestQueued) - it exists
+ * because Pyodide JSPI can only suspend inside the dedicated pump call,
+ * so these members are the seam, not a replacement for that model.
+ */
+export interface VirtualSocketStreamingStage2 {
+    /**
+     * Suspending read for request bodies streamed into the inbound queue
+     * chunk-by-chunk; replaces buffering the whole request before the
+     * connection is pushed to the listener. Resolves null at EOF.
+     */
+    recvAsync(id: number, maxBytes: number): Promise<Uint8Array | null>;
+    /**
+     * Write-side backpressure: resolves once queued response bytes drop
+     * below the high-water mark, replacing the hard
+     * maxResponseBufferBytes cap with flow control.
+     */
+    awaitWritable(id: number): Promise<void>;
+    /**
+     * Headers-first streaming Response whose body is a ReadableStream fed
+     * from the outbound queue. Requires the runtime pump to interleave
+     * body writes with consumer reads instead of completing one whole
+     * request per __nimbusVirtualSocketRequestQueued call.
+     */
+    streamHttpResponse(port: number, request: Request): Promise<Response>;
+}
+/** What the kernel's recv/send/close operate on, in either direction. */
+interface VirtualSocketConnection {
+    readonly id: number;
+    read(maxBytes: number): number[];
+    readAsync(maxBytes: number): Promise<number[]>;
+    /** Byte-array read. Runtimes that own file descriptors read through this. */
+    readBytesAsync(maxBytes: number): Promise<Uint8Array>;
+    /** True once no further bytes can arrive, so an empty read means EOF, not "not yet". */
+    atEof(): boolean;
+    write(bytesLike: VirtualSocketBytesLike): number;
+    close(): void;
+}
+declare class VirtualConnection implements VirtualSocketConnection {
+    readonly id: number;
+    /** Request bytes the guest server reads; filled in one shot in stage 1. */
+    private readonly inbound;
+    /** Response bytes the guest server writes; drained into the parser. */
+    private readonly outbound;
+    private readonly parser;
+    private readonly responseReady;
+    private settled;
+    private closed;
+    constructor(id: number, requestMethod: string, requestBytes: Uint8Array, limits: VirtualSocketKernelLimits);
+    read(maxBytes: number): number[];
+    /** The whole request is buffered before the connection is accepted, so nothing is ever awaited. */
+    readAsync(maxBytes: number): Promise<number[]>;
+    readBytesAsync(maxBytes: number): Promise<Uint8Array>;
+    /** Same reason: an empty read on an accepted connection is always genuine EOF. */
+    atEof(): boolean;
+    write(bytesLike: VirtualSocketBytesLike): number;
+    /** EOF from the server side (or request teardown); completes until-close bodies. */
+    close(): void;
+    /** Abort propagation: settle the pending preview request with a terminal status. */
+    abort(message: string, status: number): void;
+    response(timeoutMs: number): Promise<Response>;
+    private pumpParser;
+    private settle;
+}
+/**
+ * The subset of Cloudflare's `Socket` that a WASI socket file descriptor needs.
+ *
+ * Every connection the kernel owns can be handed back in this shape, which is
+ * what lets a runtime with real file descriptors keep ONE socket fd kind:
+ * `fd_read`/`fd_write`/`poll_oneoff`/`sock_shutdown`/`fd_close` never learn
+ * whether the peer is a remote host reached through `cloudflare:sockets`, an
+ * in-session port this process dialed, or a connection it accepted.
+ */
+export interface VirtualSocketStream {
+    readonly opened: Promise<void>;
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly writable: WritableStream<Uint8Array>;
+    close(): Promise<void>;
+}
+declare class VirtualListener {
+    readonly port: number;
+    private readonly queue;
+    private readonly acceptWaiters;
+    constructor(port: number);
+    push(conn: VirtualConnection): void;
+    accept(): Promise<VirtualConnection>;
+    take(): VirtualConnection | null;
+    pending(): number;
+    drainQueued(): VirtualConnection[];
+    rejectPendingAccepts(error: Error): void;
+}
+export declare class VirtualSocketKernel {
+    private readonly host;
+    /** Public: runner glue inspects listeners.keys() for the default preview port. */
+    readonly listeners: Map<number, VirtualListener>;
+    private readonly connections;
+    private readonly limits;
+    private nextConnectionId;
+    private nextEphemeralPort;
+    private listenWaiters;
+    private readonly readableWaiters;
+    constructor(host: VirtualSocketHost, limits?: Partial<VirtualSocketKernelLimits>);
+    listen(port: number): number;
+    closeListener(port: number): void;
+    accept(port: number): Promise<AcceptedVirtualConnection>;
+    acceptNow(port: number): AcceptedVirtualConnection | null;
+    /**
+     * Open a client connection to `port` on the session's loopback.
+     *
+     * The returned id is an ordinary connection id: send() writes the
+     * request, recv()/recvAsync() read the response, close() releases it.
+     * Only HTTP/1.1 crosses a loopback connection - see
+     * LoopbackClientConnection for why - and each one carries a single
+     * request/response exchange.
+     */
+    connect(port: number): number;
+    /**
+     * The same client connection as `connect`, handed back in Cloudflare's
+     * `Socket` shape.
+     *
+     * Guests whose sockets are real WASI file descriptors (ruby.wasm, and any
+     * future wasm32-wasi program) reach loopback through this: the WASI shim
+     * stores it in exactly the fd slot a `cloudflare:sockets` connection would
+     * occupy, so `fd_read` on an in-session port is the same suspending read as
+     * `fd_read` on a remote host.
+     */
+    connectStream(port: number): VirtualSocketStream;
+    /**
+     * An already-accepted connection in the same `Socket` shape, so a server's
+     * accepted socket is the same kind of file descriptor as a client's dialed
+     * one. `accept`/`acceptNow` still hand out the connection id, because accept
+     * itself stays on the cooperative pump - this only binds the result.
+     */
+    streamFor(id: number): VirtualSocketStream;
+    private openLoopbackClient;
+    /** Plain number array: Pyodide bytes() and the ruby.wasm base64 bridge both consume it. */
+    recv(id: number, maxBytes: number): number[];
+    /**
+     * Suspending read. A client connection has nothing to hand back until
+     * the loopback response arrives, so guests that can suspend (Pyodide
+     * `run_sync`, a JSPI-suspending WASI call) await this instead of
+     * spinning on recv(). An empty result is EOF.
+     */
+    recvAsync(id: number, maxBytes: number): Promise<number[]>;
+    /**
+     * Whether an empty recv() means end-of-response rather than "not yet".
+     * Guests that poll instead of suspending (ruby.wasm, whose JS bridge is
+     * synchronous) need the two apart to avoid truncating a response.
+     */
+    atEof(id: number): boolean;
+    send(id: number, bytesLike: VirtualSocketBytesLike): number;
+    close(id: number): void;
+    pending(port: number): number;
+    firstListeningPort(): number | null;
+    /** select()-style readiness: resolves ports with queued connections, [] on timeout. */
+    waitReadable(ports: readonly number[], timeoutSeconds?: number | null): Promise<number[]>;
+    waitForListen(timeoutMs?: number): Promise<number | null>;
+    handleHttpRequest(port: number, request: Request): Promise<Response>;
+    private notifyReadable;
+}
+/**
+ * Install the kernel on the facet global scope. The generated injection
+ * bundle (VIRTUAL_SOCKET_KERNEL_SRC) is exactly this call against
+ * globalThis, wrapped in an IIFE so no identifiers leak into the dynamic
+ * worker module scope.
+ */
+export declare function installVirtualSocketKernel(scope?: VirtualSocketGlobalScope): VirtualSocketKernel;
+export {};
+//# sourceMappingURL=virtual-socket-kernel.d.ts.map

package/dist/runtime/virtual-socket-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-socket-kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/virtual-socket-kernel.ts"],"names":[],"mappings":"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"}