@s2-dev/streamstore 0.17.6 → 0.18.0

package/dist/esm/lib/stream/transport/s2s/index.js

@@ -5,12 +5,15 @@
  * This file should only be imported in Node.js environments
  */
 import * as http2 from "node:http2";
-import { createClient, createConfig, } from "../../../../generated/client/index.js";
+import createDebug from "debug";
+import { makeAppendPreconditionError, makeServerError, RangeNotSatisfiableError, S2Error, } from "../../../../error.js";
 import { AppendAck as ProtoAppendAck, AppendInput as ProtoAppendInput, ReadBatch as ProtoReadBatch, } from "../../../../generated/proto/s2.js";
-import { S2Error } from "../../../../index.js";
-import { meteredSizeBytes } from "../../../../utils.js";
+import { meteredBytes } from "../../../../utils.js";
 import * as Redacted from "../../../redacted.js";
+import { err, errClose, ok, okClose } from "../../../result.js";
+import { RetryAppendSession as AppendSessionImpl, RetryReadSession as ReadSessionImpl, } from "../../../retry.js";
 import { frameMessage, S2SFrameParser } from "./framing.js";
+const debug = createDebug("s2:s2s");
 export function buildProtoAppendInput(records, args) {
     const textEncoder = new TextEncoder();
     return ProtoAppendInput.create({
@@ -40,22 +43,21 @@ export function buildProtoAppendInput(records, args) {
     });
 }
 export class S2STransport {
-    client;
     transportConfig;
     connection;
     connectionPromise;
     constructor(config) {
-        this.client = createClient(createConfig({
-            baseUrl: config.baseUrl,
-            auth: () => Redacted.value(config.accessToken),
-        }));
         this.transportConfig = config;
     }
     async makeAppendSession(stream, sessionOptions, requestOptions) {
-        return S2SAppendSession.create(this.transportConfig.baseUrl, this.transportConfig.accessToken, stream, () => this.getConnection(), sessionOptions, requestOptions);
+        return AppendSessionImpl.create((myOptions) => {
+            return S2SAppendSession.create(this.transportConfig.baseUrl, this.transportConfig.accessToken, stream, () => this.getConnection(), this.transportConfig.basinName, myOptions, requestOptions);
+        }, sessionOptions, this.transportConfig.retry);
     }
     async makeReadSession(stream, args, options) {
-        return S2SReadSession.create(this.transportConfig.baseUrl, this.transportConfig.accessToken, stream, args, options, () => this.getConnection());
+        return ReadSessionImpl.create((myArgs) => {
+            return S2SReadSession.create(this.transportConfig.baseUrl, this.transportConfig.accessToken, stream, myArgs, options, () => this.getConnection(), this.transportConfig.basinName);
+        }, args, this.transportConfig.retry);
     }
     /**
      * Get or create HTTP/2 connection (one per transport)
@@ -117,25 +119,36 @@ class S2SReadSession extends ReadableStream {
     url;
     options;
     getConnection;
+    basinName;
     http2Stream;
     _lastReadPosition;
+    _nextReadPosition;
+    _lastObservedTail;
     parser = new S2SFrameParser();
-    static async create(baseUrl, bearerToken, streamName, args, options, getConnection) {
+    static async create(baseUrl, bearerToken, streamName, args, options, getConnection, basinName) {
         const url = new URL(baseUrl);
-        return new S2SReadSession(streamName, args, bearerToken, url, options, getConnection);
+        return new S2SReadSession(streamName, args, bearerToken, url, options, getConnection, basinName);
     }
-    constructor(streamName, args, authToken, url, options, getConnection) {
+    constructor(streamName, args, authToken, url, options, getConnection, basinName) {
         // Initialize parser and textDecoder before super() call
         const parser = new S2SFrameParser();
         const textDecoder = new TextDecoder();
         let http2Stream;
         let lastReadPosition;
+        // Track timeout for detecting when server stops sending data
+        const TAIL_TIMEOUT_MS = 20000; // 20 seconds
+        let timeoutTimer;
         super({
             start: async (controller) => {
                 let controllerClosed = false;
+                let responseCode;
                 const safeClose = () => {
                     if (!controllerClosed) {
                         controllerClosed = true;
+                        if (timeoutTimer) {
+                            clearTimeout(timeoutTimer);
+                            timeoutTimer = undefined;
+                        }
                         try {
                             controller.close();
                         }
@@ -147,10 +160,37 @@ class S2SReadSession extends ReadableStream {
                 const safeError = (err) => {
                     if (!controllerClosed) {
                         controllerClosed = true;
-                        controller.error(err);
+                        if (timeoutTimer) {
+                            clearTimeout(timeoutTimer);
+                            timeoutTimer = undefined;
+                        }
+                        // Convert error to S2Error and enqueue as error result
+                        const s2Err = err instanceof S2Error
+                            ? err
+                            : new S2Error({ message: String(err), status: 500 });
+                        controller.enqueue({ ok: false, error: s2Err });
+                        controller.close();
+                    }
+                };
+                // Helper to start/reset the timeout timer
+                // Resets on every tail received, fires only if no tail for 20s
+                const resetTimeoutTimer = () => {
+                    if (timeoutTimer) {
+                        clearTimeout(timeoutTimer);
                     }
+                    timeoutTimer = setTimeout(() => {
+                        const timeoutError = new S2Error({
+                            message: `No tail received for ${TAIL_TIMEOUT_MS / 1000}s`,
+                            status: 408, // Request Timeout
+                            code: "TIMEOUT",
+                        });
+                        debug("tail timeout detected");
+                        safeError(timeoutError);
+                    }, TAIL_TIMEOUT_MS);
                 };
                 try {
+                    // Start the timeout timer - will fire in 20s if no tail received
+                    resetTimeoutTimer();
                     const connection = await getConnection();
                     // Build query string
                     const queryParams = new URLSearchParams();
@@ -180,6 +220,7 @@ class S2SReadSession extends ReadableStream {
                         authorization: `Bearer ${Redacted.value(authToken)}`,
                         accept: "application/protobuf",
                         "content-type": "s2s/proto",
+                        ...(basinName ? { "s2-basin": basinName } : {}),
                     });
                     http2Stream = stream;
                     options?.signal?.addEventListener("abort", () => {
@@ -187,64 +228,139 @@ class S2SReadSession extends ReadableStream {
                             stream.close();
                         }
                     });
+                    stream.on("response", (headers) => {
+                        // Cache the status.
+                        // This informs whether we should attempt to parse s2s frames in the "data" handler.
+                        responseCode = headers[":status"] ?? 500;
+                    });
+                    connection.on("goaway", (errorCode, lastStreamID, opaqueData) => {
+                        debug("received GOAWAY from server");
+                    });
+                    stream.on("error", (err) => {
+                        safeError(err);
+                    });
                     stream.on("data", (chunk) => {
-                        // Buffer already extends Uint8Array in Node.js, no need to convert
-                        parser.push(chunk);
-                        let frame = parser.parseFrame();
-                        while (frame) {
-                            if (frame.terminal) {
-                                if (frame.statusCode && frame.statusCode >= 400) {
-                                    const errorText = textDecoder.decode(frame.body);
-                                    try {
-                                        const errorJson = JSON.parse(errorText);
-                                        safeError(new S2Error({
-                                            message: errorJson.message ?? "Unknown error",
-                                            code: errorJson.code,
-                                            status: frame.statusCode,
-                                        }));
-                                    }
-                                    catch {
-                                        safeError(new S2Error({
-                                            message: errorText || "Unknown error",
-                                            status: frame.statusCode,
-                                        }));
-                                    }
+                        try {
+                            if ((responseCode ?? 500) >= 400) {
+                                const errorText = textDecoder.decode(chunk);
+                                try {
+                                    const errorJson = JSON.parse(errorText);
+                                    safeError(new S2Error({
+                                        message: errorJson.message ?? "Unknown error",
+                                        code: errorJson.code,
+                                        status: responseCode,
+                                        origin: "server",
+                                    }));
                                 }
-                                else {
-                                    safeClose();
+                                catch {
+                                    safeError(new S2Error({
+                                        message: errorText || "Unknown error",
+                                        status: responseCode,
+                                        origin: "server",
+                                    }));
                                 }
-                                stream.close();
+                                return;
                             }
-                            else {
-                                // Parse ReadBatch
-                                try {
-                                    const protoBatch = ProtoReadBatch.fromBinary(frame.body);
-                                    // Update position from tail
-                                    if (protoBatch.tail) {
-                                        lastReadPosition = convertStreamPosition(protoBatch.tail);
-                                        // Assign to instance property
-                                        this._lastReadPosition = lastReadPosition;
+                            // Buffer already extends Uint8Array in Node.js, no need to convert
+                            parser.push(chunk);
+                            let frame = parser.parseFrame();
+                            while (frame) {
+                                if (frame.terminal) {
+                                    if (frame.statusCode && frame.statusCode >= 400) {
+                                        const errorText = textDecoder.decode(frame.body);
+                                        try {
+                                            const errorJson = JSON.parse(errorText);
+                                            const status = frame.statusCode ?? 500;
+                                            // Map known read errors
+                                            if (status === 416) {
+                                                safeError(new RangeNotSatisfiableError({ status }));
+                                            }
+                                            else {
+                                                safeError(makeServerError({ status, statusText: undefined }, errorJson));
+                                            }
+                                        }
+                                        catch {
+                                            safeError(makeServerError({
+                                                status: frame.statusCode ?? 500,
+                                                statusText: undefined,
+                                            }, errorText));
+                                        }
                                     }
-                                    // Enqueue each record
-                                    for (const record of protoBatch.records) {
-                                        const converted = this.convertRecord(record, as ?? "string", textDecoder);
-                                        controller.enqueue(converted);
+                                    else {
+                                        safeClose();
                                     }
+                                    stream.close();
                                 }
-                                catch (err) {
-                                    safeError(new S2Error({
-                                        message: `Failed to parse ReadBatch: ${err}`,
-                                    }));
+                                else {
+                                    // Parse ReadBatch
+                                    try {
+                                        const protoBatch = ProtoReadBatch.fromBinary(frame.body);
+                                        resetTimeoutTimer();
+                                        // Update tail from batch
+                                        if (protoBatch.tail) {
+                                            const tail = convertStreamPosition(protoBatch.tail);
+                                            lastReadPosition = tail;
+                                            this._lastReadPosition = tail;
+                                            this._lastObservedTail = tail;
+                                            debug("received tail");
+                                        }
+                                        // Enqueue each record and track next position
+                                        for (const record of protoBatch.records) {
+                                            const converted = this.convertRecord(record, as ?? "string", textDecoder);
+                                            controller.enqueue({ ok: true, value: converted });
+                                            // Update next read position to after this record
+                                            if (record.seqNum !== undefined) {
+                                                this._nextReadPosition = {
+                                                    seq_num: Number(record.seqNum) + 1,
+                                                    timestamp: Number(record.timestamp ?? 0n),
+                                                };
+                                            }
+                                        }
+                                    }
+                                    catch (err) {
+                                        safeError(new S2Error({
+                                            message: `Failed to parse ReadBatch: ${err}`,
+                                            status: 500,
+                                            origin: "sdk",
+                                        }));
+                                    }
                                 }
+                                frame = parser.parseFrame();
                             }
-                            frame = parser.parseFrame();
+                        }
+                        catch (error) {
+                            safeError(error instanceof S2Error
+                                ? error
+                                : new S2Error({
+                                    message: `Failed to process read data: ${error}`,
+                                    status: 500,
+                                    origin: "sdk",
+                                }));
                         }
                     });
-                    stream.on("error", (err) => {
-                        safeError(err);
+                    stream.on("end", () => {
+                        if (stream.rstCode != 0) {
+                            debug("stream reset code=%d", stream.rstCode);
+                            safeError(new S2Error({
+                                message: `Stream ended with error: ${stream.rstCode}`,
+                                status: 500,
+                                code: "stream reset",
+                                origin: "sdk",
+                            }));
+                        }
                     });
                     stream.on("close", () => {
-                        safeClose();
+                        if (parser.hasData()) {
+                            safeError(new S2Error({
+                                message: "Stream closed with unparsed data remaining",
+                                status: 500,
+                                code: "STREAM_CLOSED_PREMATURELY",
+                                origin: "sdk",
+                            }));
+                        }
+                        else {
+                            safeClose();
+                        }
                     });
                 }
                 catch (err) {
@@ -263,6 +379,7 @@ class S2SReadSession extends ReadableStream {
         this.url = url;
         this.options = options;
         this.getConnection = getConnection;
+        this.basinName = basinName;
         // Assign parser to instance property after super() completes
         this.parser = parser;
         this.http2Stream = http2Stream;
@@ -325,163 +442,46 @@ class S2SReadSession extends ReadableStream {
             },
         };
     }
-    lastReadPosition() {
-        return this._lastReadPosition;
+    nextReadPosition() {
+        return this._nextReadPosition;
+    }
+    lastObservedTail() {
+        return this._lastObservedTail;
     }
 }
 /**
  * AcksStream for S2S append session
  */
-class S2SAcksStream extends ReadableStream {
-    constructor(setController) {
-        super({
-            start: (controller) => {
-                setController(controller);
-            },
-        });
-    }
-    async [Symbol.asyncDispose]() {
-        await this.cancel("disposed");
-    }
-    // Polyfill for older browsers
-    [Symbol.asyncIterator]() {
-        const fn = ReadableStream.prototype[Symbol.asyncIterator];
-        if (typeof fn === "function")
-            return fn.call(this);
-        const reader = this.getReader();
-        return {
-            next: async () => {
-                const r = await reader.read();
-                if (r.done) {
-                    reader.releaseLock();
-                    return { done: true, value: undefined };
-                }
-                return { done: false, value: r.value };
-            },
-            throw: async (e) => {
-                await reader.cancel(e);
-                reader.releaseLock();
-                return { done: true, value: undefined };
-            },
-            return: async () => {
-                await reader.cancel("done");
-                reader.releaseLock();
-                return { done: true, value: undefined };
-            },
-            [Symbol.asyncIterator]() {
-                return this;
-            },
-        };
-    }
-}
+// Removed S2SAcksStream - transport sessions no longer expose streams
 /**
- * S2S Append Session for pipelined writes
- * Unlike fetch-based append, writes don't block on acks - only on submission
+ * Fetch-based transport session for appending records via HTTP/2.
+ * Pipelined: multiple requests can be in-flight simultaneously.
+ * No backpressure, no retry logic, no streams - just submit/close with value-encoded errors.
  */
 class S2SAppendSession {
     baseUrl;
     authToken;
     streamName;
     getConnection;
+    basinName;
     options;
     http2Stream;
-    _lastAckedPosition;
     parser = new S2SFrameParser();
-    acksController;
-    _readable;
-    _writable;
     closed = false;
-    queuedBytes = 0;
-    maxQueuedBytes;
-    waitingForCapacity = [];
     pendingAcks = [];
     initPromise;
-    readable;
-    writable;
-    static async create(baseUrl, bearerToken, streamName, getConnection, sessionOptions, requestOptions) {
-        return new S2SAppendSession(baseUrl, bearerToken, streamName, getConnection, sessionOptions, requestOptions);
+    static async create(baseUrl, bearerToken, streamName, getConnection, basinName, sessionOptions, requestOptions) {
+        return new S2SAppendSession(baseUrl, bearerToken, streamName, getConnection, basinName, sessionOptions, requestOptions);
     }
-    constructor(baseUrl, authToken, streamName, getConnection, sessionOptions, options) {
+    constructor(baseUrl, authToken, streamName, getConnection, basinName, sessionOptions, options) {
         this.baseUrl = baseUrl;
         this.authToken = authToken;
         this.streamName = streamName;
         this.getConnection = getConnection;
+        this.basinName = basinName;
         this.options = options;
-        this.maxQueuedBytes = sessionOptions?.maxQueuedBytes ?? 10 * 1024 * 1024; // 10 MiB default
-        // Create the readable stream for acks
-        this._readable = new S2SAcksStream((controller) => {
-            this.acksController = controller;
-        });
-        this.readable = this._readable;
-        // Create the writable stream
-        this._writable = new WritableStream({
-            start: async (controller) => {
-                this.initPromise = this.initializeStream();
-                await this.initPromise;
-            },
-            write: async (chunk) => {
-                if (this.closed) {
-                    throw new S2Error({ message: "AppendSession is closed" });
-                }
-                const recordsArray = Array.isArray(chunk.records)
-                    ? chunk.records
-                    : [chunk.records];
-                // Validate batch size limits
-                if (recordsArray.length > 1000) {
-                    throw new S2Error({
-                        message: `Batch of ${recordsArray.length} exceeds maximum batch size of 1000 records`,
-                    });
-                }
-                // Calculate metered size
-                let batchMeteredSize = 0;
-                for (const record of recordsArray) {
-                    batchMeteredSize += meteredSizeBytes(record);
-                }
-                if (batchMeteredSize > 1024 * 1024) {
-                    throw new S2Error({
-                        message: `Batch size ${batchMeteredSize} bytes exceeds maximum of 1 MiB (1048576 bytes)`,
-                    });
-                }
-                // Wait for capacity if needed (backpressure)
-                while (this.queuedBytes + batchMeteredSize > this.maxQueuedBytes &&
-                    !this.closed) {
-                    await new Promise((resolve) => {
-                        this.waitingForCapacity.push(resolve);
-                    });
-                }
-                if (this.closed) {
-                    throw new S2Error({ message: "AppendSession is closed" });
-                }
-                // Send the batch immediately (pipelined)
-                // Returns when frame is sent, not when ack is received
-                await this.sendBatchNonBlocking(recordsArray, chunk, batchMeteredSize);
-            },
-            close: async () => {
-                this.closed = true;
-                await this.closeStream();
-            },
-            abort: async (reason) => {
-                this.closed = true;
-                this.queuedBytes = 0;
-                // Reject all pending acks
-                const error = new S2Error({
-                    message: `AppendSession was aborted: ${reason}`,
-                });
-                for (const pending of this.pendingAcks) {
-                    pending.reject(error);
-                }
-                this.pendingAcks = [];
-                // Wake up all waiting for capacity
-                for (const resolver of this.waitingForCapacity) {
-                    resolver();
-                }
-                this.waitingForCapacity = [];
-                if (this.http2Stream && !this.http2Stream.closed) {
-                    this.http2Stream.close();
-                }
-            },
-        });
-        this.writable = this._writable;
+        // No stream setup
+        // Initialization happens lazily on first submit
     }
     async initializeStream() {
         const url = new URL(this.baseUrl);
@@ -495,6 +495,7 @@ class S2SAppendSession {
             authorization: `Bearer ${Redacted.value(this.authToken)}`,
             "content-type": "s2s/proto",
             accept: "application/protobuf",
+            ...(this.basinName ? { "s2-basin": this.basinName } : {}),
         });
         this.http2Stream = stream;
         this.options?.signal?.addEventListener("abort", () => {
@@ -503,145 +504,87 @@ class S2SAppendSession {
             }
         });
         const textDecoder = new TextDecoder();
-        let controllerClosed = false;
-        const safeClose = () => {
-            if (!controllerClosed && this.acksController) {
-                controllerClosed = true;
-                try {
-                    this.acksController.close();
-                }
-                catch {
-                    // Controller may already be closed, ignore
-                }
-            }
-        };
-        const safeError = (err) => {
-            if (!controllerClosed && this.acksController) {
-                controllerClosed = true;
-                this.acksController.error(err);
-            }
-            // Reject all pending acks
+        const safeError = (error) => {
+            const s2Err = error instanceof S2Error
+                ? error
+                : new S2Error({ message: String(error), status: 502 });
+            // Resolve all pending acks with error result
             for (const pending of this.pendingAcks) {
-                pending.reject(err);
+                pending.resolve(err(s2Err));
             }
             this.pendingAcks = [];
         };
         // Handle incoming data (acks)
         stream.on("data", (chunk) => {
-            this.parser.push(chunk);
-            let frame = this.parser.parseFrame();
-            while (frame) {
-                if (frame.terminal) {
-                    if (frame.statusCode && frame.statusCode >= 400) {
-                        const errorText = textDecoder.decode(frame.body);
-                        try {
-                            const errorJson = JSON.parse(errorText);
-                            safeError(new S2Error({
-                                message: errorJson.message ?? "Unknown error",
-                                code: errorJson.code,
-                                status: frame.statusCode,
-                            }));
-                        }
-                        catch {
-                            safeError(new S2Error({
-                                message: errorText || "Unknown error",
-                                status: frame.statusCode,
-                            }));
+            try {
+                this.parser.push(chunk);
+                let frame = this.parser.parseFrame();
+                while (frame) {
+                    if (frame.terminal) {
+                        if (frame.statusCode && frame.statusCode >= 400) {
+                            const errorText = textDecoder.decode(frame.body);
+                            const status = frame.statusCode ?? 500;
+                            try {
+                                const errorJson = JSON.parse(errorText);
+                                const err = status === 412
+                                    ? makeAppendPreconditionError(status, errorJson)
+                                    : makeServerError({ status, statusText: undefined }, errorJson);
+                                queueMicrotask(() => safeError(err));
+                            }
+                            catch {
+                                const err = makeServerError({ status, statusText: undefined }, errorText);
+                                queueMicrotask(() => safeError(err));
+                            }
                         }
+                        stream.close();
                     }
                     else {
-                        safeClose();
-                    }
-                    stream.close();
-                }
-                else {
-                    // Parse AppendAck
-                    try {
-                        const protoAck = ProtoAppendAck.fromBinary(frame.body);
-                        const ack = convertAppendAck(protoAck);
-                        this._lastAckedPosition = ack;
-                        // Enqueue to readable stream
-                        if (this.acksController) {
-                            this.acksController.enqueue(ack);
-                        }
-                        // Resolve the pending ack promise
-                        const pending = this.pendingAcks.shift();
-                        if (pending) {
-                            pending.resolve(ack);
-                            // Release capacity
-                            this.queuedBytes -= pending.batchSize;
-                            // Wake up one waiting writer
-                            if (this.waitingForCapacity.length > 0) {
-                                const waiter = this.waitingForCapacity.shift();
-                                waiter();
+                        // Parse AppendAck
+                        try {
+                            const protoAck = ProtoAppendAck.fromBinary(frame.body);
+                            const ack = convertAppendAck(protoAck);
+                            // Resolve the pending ack promise (FIFO)
+                            const pending = this.pendingAcks.shift();
+                            if (pending) {
+                                pending.resolve(ok(ack));
                             }
                         }
+                        catch (parseErr) {
+                            queueMicrotask(() => safeError(new S2Error({
+                                message: `Failed to parse AppendAck: ${parseErr}`,
+                                status: 500,
+                            })));
+                        }
                     }
-                    catch (err) {
-                        safeError(new S2Error({
-                            message: `Failed to parse AppendAck: ${err}`,
-                        }));
-                    }
+                    frame = this.parser.parseFrame();
                 }
-                frame = this.parser.parseFrame();
+            }
+            catch (error) {
+                queueMicrotask(() => safeError(error));
             }
         });
-        stream.on("error", (err) => {
-            safeError(err);
+        stream.on("error", (streamErr) => {
+            queueMicrotask(() => safeError(streamErr));
         });
         stream.on("close", () => {
-            safeClose();
-        });
-    }
-    /**
-     * Send a batch non-blocking (returns when frame is sent, not when ack is received)
-     */
-    sendBatchNonBlocking(records, args, batchMeteredSize) {
-        if (!this.http2Stream || this.http2Stream.closed) {
-            return Promise.reject(new S2Error({ message: "HTTP/2 stream is not open" }));
-        }
-        // Convert to protobuf AppendInput
-        const protoInput = buildProtoAppendInput(records, args);
-        const bodyBytes = ProtoAppendInput.toBinary(protoInput);
-        // Frame the message
-        const frame = frameMessage({
-            terminal: false,
-            body: bodyBytes,
-        });
-        // This promise resolves when the frame is written (not when ack is received)
-        return new Promise((resolve, reject) => {
-            // Track pending ack - will be resolved when ack arrives
-            const ackPromise = {
-                resolve: () => { },
-                reject,
-                batchSize: batchMeteredSize,
-            };
-            this.pendingAcks.push(ackPromise);
-            this.queuedBytes += batchMeteredSize;
-            // Send the frame (pipelined)
-            this.http2Stream.write(frame, (err) => {
-                if (err) {
-                    // Remove from pending acks on write error
-                    const idx = this.pendingAcks.indexOf(ackPromise);
-                    if (idx !== -1) {
-                        this.pendingAcks.splice(idx, 1);
-                        this.queuedBytes -= batchMeteredSize;
-                    }
-                    reject(err);
-                }
-                else {
-                    // Frame written successfully - resolve immediately (pipelined)
-                    resolve();
-                }
-            });
+            // Stream closed - resolve any remaining pending acks with error
+            // This can happen if the server closes the stream without sending all acks
+            if (this.pendingAcks.length > 0) {
+                queueMicrotask(() => safeError(new S2Error({
+                    message: "Stream closed with pending acks",
+                    status: 502,
+                    code: "BAD_GATEWAY",
+                })));
+            }
         });
     }
     /**
-     * Send a batch and wait for ack (used by submit method)
+     * Send a batch and wait for ack. Returns AppendResult (never throws).
+     * Pipelined: multiple sends can be in-flight; acks resolve FIFO.
      */
     sendBatch(records, args, batchMeteredSize) {
         if (!this.http2Stream || this.http2Stream.closed) {
-            return Promise.reject(new S2Error({ message: "HTTP/2 stream is not open" }));
+            return Promise.resolve(err(new S2Error({ message: "HTTP/2 stream is not open", status: 502 })));
         }
         // Convert to protobuf AppendInput
         const protoInput = buildProtoAppendInput(records, args);
@@ -651,82 +594,99 @@ class S2SAppendSession {
             terminal: false,
             body: bodyBytes,
         });
-        // Track pending ack - this promise resolves when the ack is received
-        return new Promise((resolve, reject) => {
+        // Track pending ack - this promise resolves when the ack is received (FIFO)
+        return new Promise((resolve) => {
             this.pendingAcks.push({
                 resolve,
-                reject,
                 batchSize: batchMeteredSize,
             });
-            this.queuedBytes += batchMeteredSize;
-            // Send the frame (non-blocking - pipelined)
-            this.http2Stream.write(frame, (err) => {
-                if (err) {
+            // Send the frame (pipelined - non-blocking)
+            this.http2Stream.write(frame, (writeErr) => {
+                if (writeErr) {
                     // Remove from pending acks on write error
-                    const idx = this.pendingAcks.findIndex((p) => p.reject === reject);
+                    const idx = this.pendingAcks.findIndex((p) => p.resolve === resolve);
                     if (idx !== -1) {
                         this.pendingAcks.splice(idx, 1);
-                        this.queuedBytes -= batchMeteredSize;
                     }
-                    reject(err);
+                    // Resolve with error result
+                    const s2Err = writeErr instanceof S2Error
+                        ? writeErr
+                        : new S2Error({ message: String(writeErr), status: 502 });
+                    resolve(err(s2Err));
                 }
-                // Write completed, but promise resolves when ack is received
+                // Write completed successfully - promise resolves later when ack is received
             });
         });
     }
-    async closeStream() {
-        // Wait for all pending acks
-        while (this.pendingAcks.length > 0) {
-            await new Promise((resolve) => setTimeout(resolve, 10));
-        }
-        // Close the HTTP/2 stream (client doesn't send terminal frame for clean close)
-        if (this.http2Stream && !this.http2Stream.closed) {
-            this.http2Stream.end();
-        }
-    }
-    async [Symbol.asyncDispose]() {
-        await this.close();
-    }
-    /**
-     * Get a stream of acknowledgements for appends.
-     */
-    acks() {
-        return this._readable;
-    }
     /**
      * Close the append session.
      * Waits for all pending appends to complete before resolving.
+     * Never throws - returns CloseResult.
      */
     async close() {
-        await this.writable.close();
+        try {
+            this.closed = true;
+            // Wait for all pending acks to complete
+            while (this.pendingAcks.length > 0) {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+            // Close the HTTP/2 stream (client doesn't send terminal frame for clean close)
+            if (this.http2Stream && !this.http2Stream.closed) {
+                this.http2Stream.end();
+            }
+            return okClose();
+        }
+        catch (error) {
+            const s2Err = error instanceof S2Error
+                ? error
+                : new S2Error({ message: String(error), status: 500 });
+            return errClose(s2Err);
+        }
     }
     /**
      * Submit an append request to the session.
-     * Returns a promise that resolves with the ack when received.
+     * Returns AppendResult (never throws).
+     * Pipelined: multiple submits can be in-flight; acks resolve FIFO.
      */
     async submit(records, args) {
+        // Validate closed state
         if (this.closed) {
-            return Promise.reject(new S2Error({ message: "AppendSession is closed" }));
+            return err(new S2Error({ message: "AppendSession is closed", status: 400 }));
         }
-        // Wait for initialization
-        if (this.initPromise) {
+        // Lazy initialize HTTP/2 stream on first submit
+        if (!this.initPromise) {
+            this.initPromise = this.initializeStream();
+        }
+        try {
             await this.initPromise;
         }
+        catch (initErr) {
+            const s2Err = initErr instanceof S2Error
+                ? initErr
+                : new S2Error({ message: String(initErr), status: 502 });
+            return err(s2Err);
+        }
         const recordsArray = Array.isArray(records) ? records : [records];
-        // Validate batch size limits
+        // Validate batch size limits (non-retryable 400-level error)
         if (recordsArray.length > 1000) {
-            return Promise.reject(new S2Error({
+            return err(new S2Error({
                 message: `Batch of ${recordsArray.length} exceeds maximum batch size of 1000 records`,
+                status: 400,
+                code: "INVALID_ARGUMENT",
             }));
         }
-        // Calculate metered size
-        let batchMeteredSize = 0;
-        for (const record of recordsArray) {
-            batchMeteredSize += meteredSizeBytes(record);
+        // Calculate metered size (use precalculated if provided)
+        let batchMeteredSize = args?.precalculatedSize ?? 0;
+        if (batchMeteredSize === 0) {
+            for (const record of recordsArray) {
+                batchMeteredSize += meteredBytes(record);
+            }
         }
         if (batchMeteredSize > 1024 * 1024) {
-            return Promise.reject(new S2Error({
+            return err(new S2Error({
                 message: `Batch size ${batchMeteredSize} bytes exceeds maximum of 1 MiB (1048576 bytes)`,
+                status: 400,
+                code: "INVALID_ARGUMENT",
             }));
         }
         return this.sendBatch(recordsArray, {
@@ -735,9 +695,6 @@ class S2SAppendSession {
             match_seq_num: args?.match_seq_num,
         }, batchMeteredSize);
     }
-    lastAckedPosition() {
-        return this._lastAckedPosition;
-    }
 }
 /**
  * Convert protobuf StreamPosition to OpenAPI StreamPosition