@zshannon/streamstore 0.22.3

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

@@ -0,0 +1,819 @@
+/**
+ * S2S HTTP/2 transport for Node.js
+ * Uses the s2s binary protocol over HTTP/2 for efficient streaming
+ *
+ * This file should only be imported in Node.js environments
+ */
+import createDebug from "debug";
+import { makeAppendPreconditionError, makeServerError, RangeNotSatisfiableError, S2Error, s2Error, } from "../../../../error.js";
+import * as Proto from "../../../../generated/proto/s2.js";
+import { err, errClose, ok, okClose } from "../../../result.js";
+import { RetryAppendSession as AppendSessionImpl, RetryReadSession as ReadSessionImpl, } from "../../../retry.js";
+import { DEFAULT_USER_AGENT } from "../../runtime.js";
+import { encodeProtoAppendInput } from "../proto.js";
+import { frameMessage, S2SFrameParser } from "./framing.js";
+/**
+ * Gets the auth token from an auth provider.
+ */
+async function getAuthToken(authProvider) {
+    if (authProvider.type === "pki") {
+        return authProvider.context.getToken();
+    }
+    return authProvider.token;
+}
+/**
+ * Signs headers if using PKI auth.
+ */
+async function signHeadersIfPki(authProvider, headers, method, url, body) {
+    if (authProvider.type === "pki") {
+        await authProvider.context.signHeaders({ method, url, headers, body });
+    }
+}
+const debug = createDebug("s2:s2s");
+let http2ModulePromise;
+async function loadHttp2() {
+    // Hint bundlers to skip bundling node:http2 while keeping the specifier static for type inference.
+    if (!http2ModulePromise) {
+        http2ModulePromise = import(
+        /* webpackIgnore: true */
+        /* @vite-ignore */
+        "node:http2");
+    }
+    return http2ModulePromise;
+}
+export class S2STransport {
+    transportConfig;
+    connection;
+    connectionPromise;
+    closingPromise;
+    constructor(config) {
+        this.transportConfig = config;
+    }
+    async makeAppendSession(stream, sessionOptions, requestOptions) {
+        return AppendSessionImpl.create((myOptions) => {
+            return S2SAppendSession.create(this.transportConfig.baseUrl, this.transportConfig.authProvider, stream, () => this.getConnection(), this.transportConfig.basinName, myOptions, requestOptions);
+        }, sessionOptions, this.transportConfig.retry, stream);
+    }
+    async makeReadSession(stream, args, options) {
+        return ReadSessionImpl.create((myArgs) => {
+            return S2SReadSession.create(this.transportConfig.baseUrl, this.transportConfig.authProvider, stream, myArgs, options, () => this.getConnection(), this.transportConfig.basinName);
+        }, args, this.transportConfig.retry);
+    }
+    /**
+     * Get or create HTTP/2 connection (one per transport)
+     */
+    async getConnection() {
+        if (this.connection &&
+            !this.connection.closed &&
+            !this.connection.destroyed) {
+            return this.connection;
+        }
+        // If connection is in progress, wait for it
+        if (this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        // Create new connection
+        this.connectionPromise = this.createConnection();
+        try {
+            this.connection = await this.connectionPromise;
+            return this.connection;
+        }
+        finally {
+            this.connectionPromise = undefined;
+        }
+    }
+    async createConnection() {
+        const http2 = await loadHttp2();
+        const url = new URL(this.transportConfig.baseUrl);
+        const client = http2.connect(url.origin, {
+            // Use HTTPS settings
+            ...(url.protocol === "https:"
+                ? {
+                // TLS options can go here if needed
+                }
+                : {}),
+            settings: {
+                initialWindowSize: 10 * 1024 * 1024, // 10 MB
+            },
+        });
+        const connectPromise = new Promise((resolve, reject) => {
+            client.once("connect", () => {
+                // Guard against session being destroyed before connect fires
+                if (client.destroyed)
+                    return;
+                client.setLocalWindowSize(10 * 1024 * 1024);
+                resolve(client);
+            });
+            client.once("error", (err) => {
+                reject(err);
+            });
+            // Handle connection close
+            client.once("close", () => {
+                if (this.connection === client) {
+                    this.connection = undefined;
+                }
+            });
+        });
+        // Apply connection timeout if configured
+        const connectionTimeout = this.transportConfig.connectionTimeoutMillis ?? 3000;
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                // Destroy the client on timeout
+                if (!client.closed && !client.destroyed) {
+                    client.destroy();
+                }
+                reject(new S2Error({
+                    message: `Connection timeout after ${connectionTimeout}ms`,
+                    status: 408,
+                    code: "CONNECTION_TIMEOUT",
+                    origin: "sdk",
+                }));
+            }, connectionTimeout);
+        });
+        try {
+            return await Promise.race([connectPromise, timeoutPromise]);
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    async close() {
+        if (this.closingPromise) {
+            return this.closingPromise;
+        }
+        this.closingPromise = (async () => {
+            const connection = this.connection ??
+                (await this.connectionPromise?.catch(() => undefined));
+            if (connection && !connection.closed && !connection.destroyed) {
+                await new Promise((resolve) => {
+                    connection.close(() => resolve());
+                });
+            }
+            this.connection = undefined;
+        })();
+        try {
+            await this.closingPromise;
+        }
+        finally {
+            this.closingPromise = undefined;
+        }
+    }
+}
+class S2SReadSession extends ReadableStream {
+    streamName;
+    args;
+    authProvider;
+    url;
+    options;
+    getConnection;
+    basinName;
+    http2Stream;
+    _lastReadPosition;
+    _nextReadPosition;
+    _lastObservedTail;
+    parser = new S2SFrameParser();
+    static async create(baseUrl, authProvider, streamName, args, options, getConnection, basinName) {
+        const url = new URL(baseUrl);
+        return new S2SReadSession(streamName, args, authProvider, url, options, getConnection, basinName);
+    }
+    constructor(streamName, args, authProvider, 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();
+                        }
+                        catch {
+                            // Controller may already be closed, ignore
+                        }
+                    }
+                };
+                const safeError = (err) => {
+                    if (!controllerClosed) {
+                        controllerClosed = true;
+                        if (timeoutTimer) {
+                            clearTimeout(timeoutTimer);
+                            timeoutTimer = undefined;
+                        }
+                        // Convert error to S2Error and enqueue as error result
+                        controller.enqueue({ ok: false, error: s2Error(err) });
+                        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();
+                    const { as, ...readParams } = args ?? {};
+                    if (readParams.seq_num !== undefined)
+                        queryParams.set("seq_num", readParams.seq_num.toString());
+                    if (readParams.timestamp !== undefined)
+                        queryParams.set("timestamp", readParams.timestamp.toString());
+                    if (readParams.tail_offset !== undefined)
+                        queryParams.set("tail_offset", readParams.tail_offset.toString());
+                    if (readParams.count !== undefined)
+                        queryParams.set("count", readParams.count.toString());
+                    if (readParams.bytes !== undefined)
+                        queryParams.set("bytes", readParams.bytes.toString());
+                    if (readParams.wait !== undefined)
+                        queryParams.set("wait", readParams.wait.toString());
+                    if (typeof readParams.until === "number") {
+                        queryParams.set("until", readParams.until.toString());
+                    }
+                    const queryString = queryParams.toString();
+                    const path = `${url.pathname}/streams/${encodeURIComponent(streamName)}/records${queryString ? `?${queryString}` : ""}`;
+                    const fullUrl = `${url.protocol}//${url.host}${path}`;
+                    // Get auth token
+                    const token = await getAuthToken(authProvider);
+                    // Build headers
+                    // Note: We include both :authority (HTTP/2 pseudo-header) and host (for proxy compatibility)
+                    const headers = {
+                        ":method": "GET",
+                        ":path": path,
+                        ":scheme": url.protocol.slice(0, -1),
+                        ":authority": url.host,
+                        host: url.host, // Some proxies (like Fly.io) may need this for proper forwarding
+                        "user-agent": DEFAULT_USER_AGENT,
+                        authorization: `Bearer ${token}`,
+                        accept: "application/protobuf",
+                        "content-type": "s2s/proto",
+                        ...(basinName ? { "s2-basin": basinName } : {}),
+                    };
+                    // Sign headers if using PKI auth
+                    await signHeadersIfPki(authProvider, headers, "GET", fullUrl);
+                    const stream = connection.request(headers);
+                    http2Stream = stream;
+                    options?.signal?.addEventListener("abort", () => {
+                        if (!stream.closed) {
+                            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) => {
+                        try {
+                            const status = responseCode ?? 500;
+                            if (status >= 400) {
+                                const errorText = textDecoder.decode(chunk);
+                                debug("error response: status=%d body=%s", status, errorText);
+                                if (status === 416) {
+                                    try {
+                                        const errorJson = JSON.parse(errorText);
+                                        safeError(new RangeNotSatisfiableError({
+                                            status,
+                                            code: errorJson.code,
+                                            tail: errorJson.tail,
+                                        }));
+                                    }
+                                    catch {
+                                        safeError(new RangeNotSatisfiableError({ status }));
+                                    }
+                                    return;
+                                }
+                                try {
+                                    const errorJson = JSON.parse(errorText);
+                                    safeError(new S2Error({
+                                        message: errorJson.message ?? "Unknown error",
+                                        code: errorJson.code,
+                                        status,
+                                        origin: "server",
+                                    }));
+                                }
+                                catch {
+                                    safeError(new S2Error({
+                                        message: errorText || "Unknown error",
+                                        status,
+                                        origin: "server",
+                                    }));
+                                }
+                                return;
+                            }
+                            // 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,
+                                                    code: errorJson.code,
+                                                    tail: errorJson.tail,
+                                                }));
+                                            }
+                                            else {
+                                                safeError(makeServerError({ status, statusText: undefined }, errorJson));
+                                            }
+                                        }
+                                        catch {
+                                            safeError(makeServerError({
+                                                status: frame.statusCode ?? 500,
+                                                statusText: undefined,
+                                            }, errorText));
+                                        }
+                                    }
+                                    else {
+                                        safeClose();
+                                    }
+                                    stream.close();
+                                }
+                                else {
+                                    // Parse ReadBatch
+                                    try {
+                                        const protoBatch = Proto.ReadBatch.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();
+                            }
+                        }
+                        catch (error) {
+                            safeError(error instanceof S2Error
+                                ? error
+                                : new S2Error({
+                                    message: `Failed to process read data: ${error}`,
+                                    status: 500,
+                                    origin: "sdk",
+                                }));
+                        }
+                    });
+                    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", () => {
+                        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) {
+                    safeError(err);
+                }
+            },
+            cancel: async () => {
+                if (http2Stream && !http2Stream.closed) {
+                    http2Stream.close();
+                }
+            },
+        });
+        this.streamName = streamName;
+        this.args = args;
+        this.authProvider = authProvider;
+        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;
+    }
+    /**
+     * Convert a protobuf SequencedRecord to the requested format
+     */
+    convertRecord(record, format, textDecoder) {
+        if (format === "bytes") {
+            return {
+                seq_num: Number(record.seqNum),
+                timestamp: Number(record.timestamp),
+                headers: record.headers?.map((h) => [h.name ?? new Uint8Array(), h.value ?? new Uint8Array()]),
+                body: record.body,
+            };
+        }
+        else {
+            // Convert to string format with object headers
+            const headerEntries = record.headers?.map((h) => [
+                h.name ? textDecoder.decode(h.name) : "",
+                h.value ? textDecoder.decode(h.value) : "",
+            ]);
+            return {
+                seq_num: Number(record.seqNum),
+                timestamp: Number(record.timestamp),
+                headers: headerEntries ? Object.fromEntries(headerEntries) : undefined,
+                body: record.body ? textDecoder.decode(record.body) : undefined,
+            };
+        }
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cancel("disposed");
+    }
+    // Polyfill for older browsers / Node.js environments
+    [Symbol.asyncIterator]() {
+        const proto = ReadableStream.prototype;
+        const fn = proto[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;
+            },
+        };
+    }
+    nextReadPosition() {
+        return this._nextReadPosition;
+    }
+    lastObservedTail() {
+        return this._lastObservedTail;
+    }
+}
+/**
+ * AcksStream for S2S append session
+ */
+// Removed S2SAcksStream - transport sessions no longer expose streams
+/**
+ * S2S-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;
+    authProvider;
+    streamName;
+    getConnection;
+    basinName;
+    options;
+    http2Stream;
+    parser = new S2SFrameParser();
+    closed = false;
+    pendingAcks = [];
+    initPromise;
+    static async create(baseUrl, authProvider, streamName, getConnection, basinName, sessionOptions, requestOptions) {
+        return new S2SAppendSession(baseUrl, authProvider, streamName, getConnection, basinName, sessionOptions, requestOptions);
+    }
+    constructor(baseUrl, authProvider, streamName, getConnection, basinName, sessionOptions, options) {
+        this.baseUrl = baseUrl;
+        this.authProvider = authProvider;
+        this.streamName = streamName;
+        this.getConnection = getConnection;
+        this.basinName = basinName;
+        this.options = options;
+        // No stream setup
+        // Initialization happens lazily on first submit
+    }
+    async initializeStream() {
+        const url = new URL(this.baseUrl);
+        const connection = await this.getConnection();
+        const path = `${url.pathname}/streams/${encodeURIComponent(this.streamName)}/records`;
+        const fullUrl = `${url.protocol}//${url.host}${path}`;
+        // Get auth token
+        const token = await getAuthToken(this.authProvider);
+        // Build headers
+        // Note: We include both :authority (HTTP/2 pseudo-header) and host (for proxy compatibility)
+        const headers = {
+            ":method": "POST",
+            ":path": path,
+            ":scheme": url.protocol.slice(0, -1),
+            ":authority": url.host,
+            host: url.host, // Some proxies (like Fly.io) may need this for proper forwarding
+            "user-agent": DEFAULT_USER_AGENT,
+            authorization: `Bearer ${token}`,
+            "content-type": "s2s/proto",
+            accept: "application/protobuf",
+            ...(this.basinName ? { "s2-basin": this.basinName } : {}),
+        };
+        // Sign headers if using PKI auth
+        await signHeadersIfPki(this.authProvider, headers, "POST", fullUrl);
+        const stream = connection.request(headers);
+        this.http2Stream = stream;
+        this.options?.signal?.addEventListener("abort", () => {
+            if (!stream.closed) {
+                stream.close();
+            }
+        });
+        const textDecoder = new TextDecoder();
+        let responseCode;
+        const safeError = (error) => {
+            // Resolve all pending acks with error result
+            for (const pending of this.pendingAcks) {
+                pending.resolve(err(s2Error(error)));
+            }
+            this.pendingAcks = [];
+        };
+        // Capture HTTP response status
+        stream.on("response", (headers) => {
+            responseCode = headers[":status"] ?? 500;
+        });
+        // Handle incoming data (acks or error response)
+        stream.on("data", (chunk) => {
+            try {
+                // Check for HTTP-level errors first (before s2s frame parsing)
+                if ((responseCode ?? 200) >= 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",
+                        }));
+                    }
+                    catch {
+                        safeError(new S2Error({
+                            message: errorText || "Unknown error",
+                            status: responseCode,
+                            origin: "server",
+                        }));
+                    }
+                    return;
+                }
+                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 {
+                        // Parse AppendAck
+                        try {
+                            const protoAck = Proto.AppendAck.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,
+                            })));
+                        }
+                    }
+                    frame = this.parser.parseFrame();
+                }
+            }
+            catch (error) {
+                queueMicrotask(() => safeError(error));
+            }
+        });
+        stream.on("error", (streamErr) => {
+            queueMicrotask(() => safeError(streamErr));
+        });
+        stream.on("close", () => {
+            // 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. Returns AppendResult (never throws).
+     * Pipelined: multiple sends can be in-flight; acks resolve FIFO.
+     */
+    sendBatch(input) {
+        if (!this.http2Stream || this.http2Stream.closed) {
+            return Promise.resolve(err(new S2Error({ message: "HTTP/2 stream is not open", status: 502 })));
+        }
+        // Convert to protobuf AppendInput
+        const bodyBytes = encodeProtoAppendInput(input);
+        // Frame the message
+        const frame = frameMessage({
+            terminal: false,
+            body: bodyBytes,
+        });
+        // Track pending ack - this promise resolves when the ack is received (FIFO)
+        return new Promise((resolve) => {
+            this.pendingAcks.push({
+                resolve,
+                batchSize: input.meteredBytes,
+            });
+            // 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.resolve === resolve);
+                    if (idx !== -1) {
+                        this.pendingAcks.splice(idx, 1);
+                    }
+                    // Resolve with error result
+                    resolve(err(s2Error(writeErr)));
+                }
+                // Write completed successfully - promise resolves later when ack is received
+            });
+        });
+    }
+    /**
+     * Close the append session.
+     * Waits for all pending appends to complete before resolving.
+     * Never throws - returns CloseResult.
+     */
+    async 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) {
+            return errClose(s2Error(error));
+        }
+    }
+    /**
+     * Submit an append request to the session.
+     * Returns AppendResult (never throws).
+     * Pipelined: multiple submits can be in-flight; acks resolve FIFO.
+     */
+    async submit(input) {
+        // Validate closed state
+        if (this.closed) {
+            return err(new S2Error({ message: "AppendSession is closed", status: 400 }));
+        }
+        // Lazy initialize HTTP/2 stream on first submit
+        if (!this.initPromise) {
+            this.initPromise = this.initializeStream();
+        }
+        try {
+            await this.initPromise;
+        }
+        catch (initErr) {
+            return err(s2Error(initErr));
+        }
+        const recordsArray = Array.from(input.records);
+        // Validate batch size limits (non-retryable 400-level error)
+        // Note: This should already be validated by AppendInput.create(), but we check defensively
+        if (recordsArray.length > 1000) {
+            return err(new S2Error({
+                message: `Batch of ${recordsArray.length} exceeds maximum batch size of 1000 records`,
+                status: 400,
+                code: "INVALID_ARGUMENT",
+            }));
+        }
+        if (input.meteredBytes > 1024 * 1024) {
+            return err(new S2Error({
+                message: `Batch size ${input.meteredBytes} bytes exceeds maximum of 1 MiB (1048576 bytes)`,
+                status: 400,
+                code: "INVALID_ARGUMENT",
+            }));
+        }
+        return this.sendBatch(input);
+    }
+}
+/**
+ * Convert protobuf StreamPosition to API StreamPosition (internal use)
+ */
+function convertStreamPosition(proto) {
+    return {
+        seq_num: Number(proto.seqNum),
+        timestamp: Number(proto.timestamp),
+    };
+}
+/**
+ * Convert API StreamPosition to SDK StreamPosition (public interface)
+ */
+function toSDKStreamPosition(pos) {
+    return {
+        seqNum: pos.seq_num,
+        timestamp: new Date(pos.timestamp),
+    };
+}
+function convertAppendAck(proto) {
+    if (!proto.start || !proto.end || !proto.tail) {
+        throw new Error("Invariant violation: AppendAck is missing required fields");
+    }
+    return {
+        start: toSDKStreamPosition(convertStreamPosition(proto.start)),
+        end: toSDKStreamPosition(convertStreamPosition(proto.end)),
+        tail: toSDKStreamPosition(convertStreamPosition(proto.tail)),
+    };
+}
+//# sourceMappingURL=index.js.map