responses-proxy 0.1.0

package/dist/kiro-eventstream.js

@@ -0,0 +1,219 @@
+/**
+ * Decoder for the AWS `application/vnd.amazon.eventstream` binary framing used by
+ * CodeWhisperer / Amazon Q streaming responses (the same framing Bedrock and
+ * Transcribe use). Each message is:
+ *
+ *   prelude (12 bytes):
+ *     total length    uint32 (big-endian)   total bytes of the whole message
+ *     headers length  uint32 (big-endian)   bytes of the header section
+ *     prelude crc     uint32 (big-endian)   CRC32 of the first 8 bytes
+ *   headers   (variable, `headers length` bytes)
+ *   payload   (variable, total - 12 - headersLength - 4 bytes)
+ *   message crc uint32 (big-endian)         CRC32 of every byte except itself
+ *
+ * Each header is: name length (uint8), name (utf8), value type (uint8), value.
+ *
+ * The decoder is incremental: feed it chunks and it returns whatever complete
+ * messages are now available, buffering any partial trailing bytes.
+ */
+const PRELUDE_LENGTH = 12;
+const MESSAGE_CRC_LENGTH = 4;
+const MIN_MESSAGE_LENGTH = PRELUDE_LENGTH + MESSAGE_CRC_LENGTH;
+export class EventStreamParseError extends Error {
+}
+const CRC32_TABLE = buildCrc32Table();
+function buildCrc32Table() {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+}
+/** Standard IEEE CRC32 over a byte range, returned as an unsigned 32-bit int. */
+export function crc32(buffer, start = 0, end = buffer.length) {
+    let crc = 0xffffffff;
+    for (let i = start; i < end; i += 1) {
+        crc = CRC32_TABLE[(crc ^ buffer[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Incremental decoder. Push raw bytes as they arrive from the upstream stream and
+ * drain complete messages. Relies on the length prefix (not the CRC) to frame
+ * messages, matching the proven 9router/AWS-SDK behavior; a bad prelude CRC is
+ * tolerated rather than fatal so a single checksum quirk can't kill a valid stream.
+ */
+export class EventStreamParser {
+    buffer = Buffer.alloc(0);
+    push(chunk) {
+        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, incoming]) : incoming;
+        return this.drain();
+    }
+    /** Number of unparsed bytes still buffered (a partial trailing message). */
+    pendingBytes() {
+        return this.buffer.length;
+    }
+    drain() {
+        const messages = [];
+        while (this.buffer.length >= PRELUDE_LENGTH) {
+            const totalLength = this.buffer.readUInt32BE(0);
+            if (totalLength < MIN_MESSAGE_LENGTH) {
+                throw new EventStreamParseError(`event-stream message length ${totalLength} is below the minimum ${MIN_MESSAGE_LENGTH}`);
+            }
+            if (this.buffer.length < totalLength) {
+                // Wait for the rest of this message to arrive.
+                break;
+            }
+            const frame = this.buffer.subarray(0, totalLength);
+            messages.push(decodeMessage(frame));
+            this.buffer = this.buffer.subarray(totalLength);
+        }
+        return messages;
+    }
+}
+/** Decode every complete message in a fully buffered response body. */
+export function parseEventStream(buffer) {
+    const parser = new EventStreamParser();
+    const messages = parser.push(buffer);
+    if (parser.pendingBytes() > 0) {
+        throw new EventStreamParseError(`event-stream buffer ended with ${parser.pendingBytes()} trailing bytes (incomplete message)`);
+    }
+    return messages;
+}
+function decodeMessage(frame) {
+    const totalLength = frame.readUInt32BE(0);
+    const headersLength = frame.readUInt32BE(4);
+    // Note: bytes 8-11 hold the prelude CRC32. 9router (and the AWS SDK in practice)
+    // frame purely by the length prefix and do not reject on CRC mismatch, so we skip
+    // validation here to stay byte-compatible with the proven client.
+    const payloadStart = PRELUDE_LENGTH + headersLength;
+    const payloadEnd = totalLength - MESSAGE_CRC_LENGTH;
+    if (payloadStart > payloadEnd) {
+        throw new EventStreamParseError(`event-stream headers length ${headersLength} overflows message of ${totalLength} bytes`);
+    }
+    const headers = decodeHeaders(frame.subarray(PRELUDE_LENGTH, payloadStart));
+    const payload = Buffer.from(frame.subarray(payloadStart, payloadEnd));
+    return { headers, payload };
+}
+function decodeHeaders(section) {
+    const headers = {};
+    let offset = 0;
+    while (offset < section.length) {
+        const nameLength = section.readUInt8(offset);
+        offset += 1;
+        const name = section.toString("utf8", offset, offset + nameLength);
+        offset += nameLength;
+        const valueType = section.readUInt8(offset);
+        offset += 1;
+        switch (valueType) {
+            case 0: // true
+                headers[name] = true;
+                break;
+            case 1: // false
+                headers[name] = false;
+                break;
+            case 2: // byte
+                headers[name] = section.readInt8(offset);
+                offset += 1;
+                break;
+            case 3: // short
+                headers[name] = section.readInt16BE(offset);
+                offset += 2;
+                break;
+            case 4: // integer
+                headers[name] = section.readInt32BE(offset);
+                offset += 4;
+                break;
+            case 5: // long
+                headers[name] = Number(section.readBigInt64BE(offset));
+                offset += 8;
+                break;
+            case 6: {
+                // byte array
+                const len = section.readUInt16BE(offset);
+                offset += 2;
+                headers[name] = Buffer.from(section.subarray(offset, offset + len));
+                offset += len;
+                break;
+            }
+            case 7: {
+                // string
+                const len = section.readUInt16BE(offset);
+                offset += 2;
+                headers[name] = section.toString("utf8", offset, offset + len);
+                offset += len;
+                break;
+            }
+            case 8: // timestamp (epoch millis)
+                headers[name] = Number(section.readBigInt64BE(offset));
+                offset += 8;
+                break;
+            case 9: // uuid
+                headers[name] = Buffer.from(section.subarray(offset, offset + 16)).toString("hex");
+                offset += 16;
+                break;
+            default:
+                throw new EventStreamParseError(`unknown event-stream header value type ${valueType}`);
+        }
+    }
+    return headers;
+}
+/**
+ * Encode a single event-stream message. Used by tests to build fixtures, but also
+ * generally useful. Header values are emitted as strings (type 7) which matches
+ * how CodeWhisperer tags `:event-type`, `:content-type`, and `:message-type`.
+ */
+export function encodeEventStreamMessage(headers, payload) {
+    const headerChunks = [];
+    for (const [name, value] of Object.entries(headers)) {
+        const nameBuf = Buffer.from(name, "utf8");
+        const valueBuf = Buffer.from(value, "utf8");
+        const head = Buffer.alloc(1 + nameBuf.length + 1 + 2);
+        let o = 0;
+        head.writeUInt8(nameBuf.length, o);
+        o += 1;
+        nameBuf.copy(head, o);
+        o += nameBuf.length;
+        head.writeUInt8(7, o); // string type
+        o += 1;
+        head.writeUInt16BE(valueBuf.length, o);
+        headerChunks.push(Buffer.concat([head, valueBuf]));
+    }
+    const headerSection = Buffer.concat(headerChunks);
+    const totalLength = PRELUDE_LENGTH + headerSection.length + payload.length + MESSAGE_CRC_LENGTH;
+    const message = Buffer.alloc(totalLength);
+    message.writeUInt32BE(totalLength, 0);
+    message.writeUInt32BE(headerSection.length, 4);
+    const preludeCrc = crc32(message, 0, 8);
+    message.writeUInt32BE(preludeCrc, 8);
+    headerSection.copy(message, PRELUDE_LENGTH);
+    payload.copy(message, PRELUDE_LENGTH + headerSection.length);
+    const messageCrc = crc32(message, 0, totalLength - MESSAGE_CRC_LENGTH);
+    message.writeUInt32BE(messageCrc, totalLength - MESSAGE_CRC_LENGTH);
+    return message;
+}
+/** Parse a header-tagged JSON payload, returning undefined on non-JSON payloads. */
+export function decodeJsonPayload(message) {
+    if (message.payload.length === 0) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(message.payload.toString("utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Convenience accessor for the `:event-type` header CodeWhisperer sets on each frame. */
+export function eventType(message) {
+    const value = message.headers[":event-type"];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/kiro-eventstream.test.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EventStreamParser, EventStreamParseError, crc32, decodeJsonPayload, encodeEventStreamMessage, eventType, parseEventStream, } from "./kiro-eventstream.js";
+function assistantFrame(content) {
+    return encodeEventStreamMessage({
+        ":event-type": "assistantResponseEvent",
+        ":content-type": "application/json",
+        ":message-type": "event",
+    }, Buffer.from(JSON.stringify({ content }), "utf8"));
+}
+test("crc32 matches the known check value for 'The quick brown fox...'", () => {
+    // IEEE CRC32 of this canonical string is 0x414fa339.
+    const value = crc32(Buffer.from("The quick brown fox jumps over the lazy dog", "utf8"));
+    assert.equal(value, 0x414fa339);
+});
+test("round-trips a single encoded message", () => {
+    const frame = assistantFrame("hello");
+    const messages = parseEventStream(frame);
+    assert.equal(messages.length, 1);
+    assert.equal(eventType(messages[0]), "assistantResponseEvent");
+    assert.equal(messages[0].headers[":content-type"], "application/json");
+    assert.deepEqual(decodeJsonPayload(messages[0]), { content: "hello" });
+});
+test("parses multiple concatenated messages", () => {
+    const frames = Buffer.concat([
+        assistantFrame("alpha"),
+        assistantFrame("beta"),
+        assistantFrame("gamma"),
+    ]);
+    const messages = parseEventStream(frames);
+    assert.deepEqual(messages.map((m) => decodeJsonPayload(m)?.content), ["alpha", "beta", "gamma"]);
+});
+test("incremental parser buffers partial messages across chunks", () => {
+    const frame = assistantFrame("streamed");
+    const parser = new EventStreamParser();
+    // Feed the message one byte at a time; nothing should complete until the last byte.
+    let completed = 0;
+    for (let i = 0; i < frame.length; i += 1) {
+        const out = parser.push(frame.subarray(i, i + 1));
+        completed += out.length;
+        if (i < frame.length - 1) {
+            assert.equal(out.length, 0, `unexpected completion at byte ${i}`);
+        }
+    }
+    assert.equal(completed, 1);
+    assert.equal(parser.pendingBytes(), 0);
+});
+test("incremental parser handles a chunk that spans a message boundary", () => {
+    const a = assistantFrame("first");
+    const b = assistantFrame("second");
+    const combined = Buffer.concat([a, b]);
+    const parser = new EventStreamParser();
+    const firstHalf = combined.subarray(0, a.length + 5);
+    const secondHalf = combined.subarray(a.length + 5);
+    const out1 = parser.push(firstHalf);
+    assert.equal(out1.length, 1);
+    assert.equal(decodeJsonPayload(out1[0])?.content, "first");
+    const out2 = parser.push(secondHalf);
+    assert.equal(out2.length, 1);
+    assert.equal(decodeJsonPayload(out2[0])?.content, "second");
+});
+test("tolerates a corrupted prelude CRC (frames by length, not checksum)", () => {
+    const frame = assistantFrame("crc-tolerant");
+    // Corrupt only the prelude CRC bytes (offset 8-11), leaving the lengths intact.
+    // 9router frames purely by the length prefix, so this must still decode.
+    frame.writeUInt32BE((frame.readUInt32BE(8) ^ 0xffffffff) >>> 0, 8);
+    const messages = parseEventStream(frame);
+    assert.equal(messages.length, 1);
+    assert.deepEqual(decodeJsonPayload(messages[0]), { content: "crc-tolerant" });
+});
+test("parseEventStream rejects a trailing incomplete message", () => {
+    const frame = assistantFrame("partial");
+    assert.throws(() => parseEventStream(frame.subarray(0, frame.length - 3)), (error) => error instanceof EventStreamParseError);
+});
+test("decodeJsonPayload returns undefined for non-JSON payloads", () => {
+    const frame = encodeEventStreamMessage({ ":event-type": "raw" }, Buffer.from("not json", "utf8"));
+    const [message] = parseEventStream(frame);
+    assert.equal(decodeJsonPayload(message), undefined);
+});