tywrap 0.6.1 → 0.8.0

package/dist/runtime/subprocess-transport.d.ts

@@ -13,7 +13,7 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 import { DisposableBase } from './bounded-context.js';
-import type { Transport } from './transport.js';
+import { type Transport, type TransportCapabilities } from './transport.js';
 /**
  * Options for the SubprocessTransport.
  */
@@ -32,6 +32,26 @@ export interface SubprocessTransportOptions {
     restartAfterRequests?: number;
     /** Write queue timeout in milliseconds. Default: 30000ms */
     writeQueueTimeoutMs?: number;
+    /**
+     * Enable `tywrap-frame/1` chunked transport negotiation. When `true`, the
+     * transport spawns the bridge with the three `TYWRAP_TRANSPORT_*` env vars and,
+     * during {@link SubprocessTransport.init}, probes the bridge's `meta` for a
+     * `transport.supportsChunking` block. If the bridge advertises chunking,
+     * oversize responses are transparently reassembled from frames; otherwise
+     * behavior is unchanged and an oversize response still fails loud (no silent
+     * single-frame fallback). Default: `false` (no negotiation, legacy behavior).
+     *
+     * Subprocess-only (0.8.0). See docs/transport-framing.md.
+     */
+    enableChunking?: boolean;
+    /**
+     * Cap (UTF-8 bytes) on a single chunked RESPONSE reassembled in memory. A
+     * frame stream whose declared or accumulated payload exceeds this fails loud
+     * instead of buffering, so chunking cannot OOM the process before the codec's
+     * payload cap rejects the result. Should track the codec's `maxPayloadBytes`.
+     * Default: 10 MiB (matches the codec default).
+     */
+    maxReassemblyBytes?: number;
 }
 /**
  * Transport implementation for subprocess-based Python communication.
@@ -64,8 +84,31 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
     private readonly envOverrides;
     private readonly cwd;
     private readonly maxLineLength;
+    private readonly maxReassemblyBytes;
     private readonly restartAfterRequests;
     private readonly writeQueueTimeoutMs;
+    /** Whether `tywrap-frame/1` negotiation was requested by the caller. */
+    private readonly enableChunking;
+    /**
+     * Whether the bridge advertised chunking during the init meta probe. Only
+     * `true` after a successful negotiation; drives {@link capabilities} and the
+     * frame-aware stdout line ceiling.
+     */
+    private negotiatedChunking;
+    /**
+     * The per-frame UTF-8 byte ceiling actually agreed with the bridge:
+     * `min(maxLineLength, the bridge's advertised maxFrameBytes)`. Defaults to
+     * `maxLineLength` and is narrowed during negotiation, so REQUEST frames are
+     * never sized larger than the bridge said it will accept (the reference bridge
+     * echoes the requested value, but a custom bridge may advertise a smaller one).
+     */
+    private negotiatedFrameBytes;
+    /**
+     * Reassembles `tywrap-frame/1` response frames into single logical response
+     * lines. Constructed lazily once chunking is negotiated; per-id discard tracks
+     * timed-out/aborted streams so late frames cannot desync stdout.
+     */
+    private responseReassembler;
     private process;
     private processExited;
     private processError;
@@ -77,6 +120,16 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
     private needsRestart;
     private readonly writeQueue;
     private draining;
+    /**
+     * Per-logical-request write mutex (W5). When a request is chunked into
+     * `tywrap-frame/1` frames, all of that request's frames must reach stdin
+     * contiguously — no other request's frame (or single line) may interleave —
+     * or the Python reassembler would see frames from two ids mixed on one stream.
+     * `writeChunkedRequest` chains the whole frame burst onto this tail; the
+     * single-line write path also serializes behind it so a small request issued
+     * concurrently never slips between another request's frames.
+     */
+    private writeMutex;
     /**
      * Create a new SubprocessTransport.
      *
@@ -93,9 +146,53 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
      */
     send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>;
     /**
-     * Initialize the transport by spawning the Python process.
+     * Static capability descriptor for the subprocess backend.
+     *
+     * Per the {@link Transport.capabilities} contract this is lifecycle-independent
+     * (safe before `init()` / after `dispose()`) and never makes a Python round
+     * trip. Subprocess carries Arrow IPC and arbitrary binary (bytes envelopes)
+     * over the JSONL stream. `supportsChunking` reports the *configured* capability
+     * — `this.enableChunking`, i.e. whether this transport is set up to use the
+     * `tywrap-frame/1` framing path — exactly as `supportsArrow` reports a static
+     * channel capability rather than a runtime fact. Whether the *connected* bridge
+     * actually advertised framing is the negotiated fact, surfaced separately on
+     * `BridgeInfo.transport.supportsChunking`; "will chunking actually happen"
+     * needs both `true`. `supportsStreaming` stays `false` (0.8.0). `maxFrameBytes`
+     * is the configured JSONL line-length limit — the largest single (unchunked)
+     * response line this transport accepts.
+     */
+    capabilities(): TransportCapabilities;
+    /**
+     * Initialize the transport by spawning the Python process and, when chunking
+     * is enabled, negotiating `tywrap-frame/1` via a small unchunked `meta` probe.
      */
     protected doInit(): Promise<void>;
+    /**
+     * Probe the freshly-spawned bridge for `tywrap-frame/1` support.
+     *
+     * Sends a small unchunked `meta` request directly over stdin (NOT via the
+     * public {@link send}, which would re-enter init while we are mid-init) and
+     * reads the single-line response. If the bridge reports
+     * `transport.supportsChunking: true`, response reassembly is enabled. If the
+     * bridge does not advertise chunking (old bridge, or it disabled framing), the
+     * transport stays single-frame and an oversize response still fails loud — no
+     * silent fallback. A probe failure leaves chunking disabled but does not fail
+     * init (small calls must keep working); the loud failure is deferred to the
+     * first oversize response.
+     */
+    private negotiateChunking;
+    /**
+     * Whether a parsed `meta` response advertises `tywrap-frame/1` chunking with a
+     * matching frame protocol. Defensive: any missing/mismatched field => `false`.
+     */
+    private bridgeAdvertisesChunking;
+    /**
+     * Send a single in-init probe message over stdin and resolve with its raw
+     * response line. Registers a pending entry keyed by `probeId` exactly like the
+     * normal send path so {@link handleResponseLine} resolves it, but bypasses the
+     * `isReady`/auto-init guard (we are deliberately running during `doInit`).
+     */
+    private sendProbe;
     /**
      * Dispose the transport by killing the Python process.
      */
@@ -118,14 +215,51 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
      * Works independently of restartAfterRequests setting.
      */
     private markForRestart;
+    /**
+     * Effective stdout line ceiling.
+     *
+     * Without chunking it is exactly {@link maxLineLength} (legacy behavior). With
+     * chunking negotiated, a single wire line is a `tywrap-frame/1` envelope whose
+     * `data` slice is capped at `maxLineLength` UTF-8 bytes by the bridge, but the
+     * JSON envelope adds escaping (`"`/`\`) plus fixed keys; the ceiling is widened
+     * to bound that overhead so a legitimate frame line is never rejected while a
+     * runaway/garbage line still is.
+     */
+    private effectiveLineCeiling;
     /**
      * Handle stdout data from the Python process.
      */
     private handleStdoutData;
     /**
      * Handle a complete response line from stdout.
+     *
+     * When chunking is negotiated, a line may be a `tywrap-frame/1` envelope: it is
+     * routed into the per-id {@link Reassembler}, which returns the reassembled
+     * logical response only once the stream is complete and valid. Single-line
+     * (non-frame) responses keep the original fast path unchanged.
      */
     private handleResponseLine;
+    /**
+     * Route one `tywrap-frame/1` response frame into the reassembler.
+     *
+     * On completion the reassembled logical line resolves the pending request. The
+     * reassembler validates structure, ordering, byte count, and UTF-8 internally
+     * and throws on any framing violation (malformed/duplicate/byte-mismatch/
+     * unknown-protocol) — those reject the pending id and mark the subprocess for
+     * restart, since stdout can no longer be trusted to be frame-aligned. Frames
+     * for a timed-out/aborted id are silently discarded by the reassembler (it
+     * returns `null` and tracks the discard set) so late multi-frame responses
+     * cannot desync the stream.
+     */
+    private handleResponseFrame;
+    /**
+     * Reject the pending request correlated to a frame id, if one exists.
+     *
+     * Used when frame reassembly throws. If the id is unknown (e.g. it already
+     * timed out and was dropped from `pending`), the error still surfaces as a
+     * protocol error so the desync is not swallowed silently.
+     */
+    private rejectFrameId;
     /**
      * Handle stderr data from the Python process.
      */
@@ -169,6 +303,38 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
      * Write data to stdin with backpressure handling.
      */
     private writeToStdin;
+    /**
+     * Write one logical request to stdin, fragmenting it into `tywrap-frame/1`
+     * request frames when chunking is negotiated and the encoded request exceeds
+     * the per-frame ceiling (W5 — the mirror of W4's response chunking).
+     *
+     * Both the chunked and single-line paths run under {@link writeMutex} so a
+     * logical request's bytes (one line, or a burst of frames) reach stdin
+     * contiguously: a small request issued concurrently can never interleave
+     * between another request's frames, which would desync the Python
+     * reassembler (it correlates frames by id, but the JSONL stream itself must
+     * stay frame-aligned). The mutex tail is advanced regardless of success so a
+     * failed write never wedges every subsequent request.
+     *
+     * @param message - the encoded logical JSON request (no trailing newline)
+     * @param messageId - the request's correlation id (already validated integer)
+     * @param signal - optional abort signal; an abort observed between frames
+     *   stops further frames and rejects this send (the pending entry is rejected
+     *   by the abort handler / the caller's `.catch`).
+     */
+    private writeRequest;
+    /**
+     * Fragment a logical request into `tywrap-frame/1` request frames and write
+     * them contiguously (one JSONL line per frame). Runs while holding the write
+     * mutex (see {@link writeRequest}), so no other write interleaves.
+     *
+     * Each frame is awaited in turn so backpressure on stdin is respected. Before
+     * every frame the abort signal and process liveness are re-checked: an abort
+     * mid-burst stops the remaining frames and rejects the send LOUD (the Python
+     * reassembler drops the now-incomplete id when the next request's frames /
+     * timeout arrive, exactly as the response side handles a discarded id).
+     */
+    private writeChunkedRequest;
     /**
      * Reject and clear every entry currently in the write queue.
      * Clears each entry's timeout before rejecting so no late timer fires.
@@ -198,7 +364,15 @@ export declare class SubprocessTransport extends DisposableBase implements Trans
      */
     private withStderrTail;
     /**
-     * Handle a protocol error by rejecting all pending requests.
+     * Handle a protocol error by rejecting all pending requests and marking the
+     * subprocess for restart.
+     *
+     * Every caller represents genuine stdout-stream corruption (a too-long line, a
+     * response with no `id`, a frame with no reassembler, or a truly unexpected id
+     * — benign late responses from timed-out requests are already filtered upstream
+     * via {@link timedOutRequests}). After such an error stdout can no longer be
+     * trusted to be line/frame-aligned, so the process is marked for restart —
+     * matching the frame-reassembly-corruption path and the framing spec.
      */
     private handleProtocolError;
     /**

package/dist/runtime/subprocess-transport.d.ts.map

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