@databricks/appkit 0.0.2

package/dist/shared/src/tunnel.d.ts

@@ -0,0 +1,30 @@
+import { WebSocket } from "ws";
+
+//#region ../shared/src/tunnel.d.ts
+interface TunnelConnection {
+  ws: WebSocket;
+  owner: string;
+  approvedViewers: Set<string>;
+  pendingRequests: Set<string>;
+  rejectedViewers: Set<string>;
+  pendingFetches: Map<string, PendingFetch>;
+  pendingFileReads: Map<string, PendingFileRead>;
+  waitingForBinaryBody: string | null;
+}
+interface PendingFetch {
+  resolve: (data: any) => void;
+  reject: (err: Error) => void;
+  timeout: NodeJS.Timeout;
+  metadata?: {
+    status: number;
+    headers: Record<string, any>;
+  };
+}
+interface PendingFileRead {
+  resolve: (content: string) => void;
+  reject: (err: Error) => void;
+  timeout: NodeJS.Timeout;
+}
+//#endregion
+export { TunnelConnection };
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/shared/src/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../../../shared/src/tunnel.ts"],"sourcesContent":[],"mappings":";;;UAEiB,gBAAA;MACX;EADW,KAAA,EAAA,MAAA;EAAgB,eAAA,EAGd,GAHc,CAAA,MAAA,CAAA;iBAC3B,EAGa,GAHb,CAAA,MAAA,CAAA;iBAEa,EAEA,GAFA,CAAA,MAAA,CAAA;gBACA,EAED,GAFC,CAAA,MAAA,EAEW,YAFX,CAAA;kBACA,EAEC,GAFD,CAAA,MAAA,EAEa,eAFb,CAAA;sBACW,EAAA,MAAA,GAAA,IAAA;;AACE,UAIf,YAAA,CAJe;SAAZ,EAAA,CAAA,IAAA,EAAA,GAAA,EAAA,GAAA,IAAA;EAAG,MAAA,EAAA,CAAA,GAAA,EAMP,KANO,EAAA,GAAA,IAAA;EAIN,OAAA,EAGN,MAAA,CAAO,OAHW;EAAA,QAAA,CAAA,EAAA;IAEb,MAAA,EAAA,MAAA;IACL,OAAO,EAGL,MAHK,CAAA,MAAA,EAAA,GAAA,CAAA;;;AAOD,UAAA,eAAA,CAAe;EAAA,OAAA,EAAA,CAAA,OAAA,EAAA,MAAA,EAAA,GAAA,IAAA;QAEhB,EAAA,CAAA,GAAA,EAAA,KAAA,EAAA,GAAA,IAAA;SACL,EAAA,MAAA,CAAO,OAAA"}

package/dist/stream/arrow-stream-processor.js

@@ -0,0 +1,154 @@
+//#region src/stream/arrow-stream-processor.ts
+const BACKOFF_MULTIPLIER = 1e3;
+var ArrowStreamProcessor = class ArrowStreamProcessor {
+	static {
+		this.DEFAULT_MAX_CONCURRENT_DOWNLOADS = 5;
+	}
+	static {
+		this.DEFAULT_TIMEOUT = 3e4;
+	}
+	static {
+		this.DEFAULT_RETRIES = 3;
+	}
+	constructor(options = {
+		maxConcurrentDownloads: ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,
+		timeout: ArrowStreamProcessor.DEFAULT_TIMEOUT,
+		retries: ArrowStreamProcessor.DEFAULT_RETRIES
+	}) {
+		this.options = options;
+		this.options = {
+			maxConcurrentDownloads: options.maxConcurrentDownloads ?? ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,
+			timeout: options.timeout ?? ArrowStreamProcessor.DEFAULT_TIMEOUT,
+			retries: options.retries ?? ArrowStreamProcessor.DEFAULT_RETRIES
+		};
+	}
+	/**
+	* Process Arrow chunks using zero-copy proxy pattern.
+	*
+	* Downloads raw IPC bytes from external links and concatenates them
+	* without parsing into Arrow Tables on the server. This reduces:
+	* - Memory usage by ~50% (no parsed Table representation)
+	* - CPU usage (no tableFromIPC/tableToIPC calls)
+	*
+	* The client is responsible for parsing the IPC bytes.
+	*
+	* @param chunks - External links to Arrow IPC data
+	* @param schema - Schema from Databricks manifest
+	* @param signal - Optional abort signal
+	* @returns Raw concatenated IPC bytes with schema
+	*/
+	async processChunks(chunks, schema, signal) {
+		if (chunks.length === 0) throw new Error("No Arrow chunks provided");
+		const buffers = await this.downloadChunksRaw(chunks, signal);
+		return {
+			data: this.concatenateBuffers(buffers),
+			schema
+		};
+	}
+	/**
+	* Download all chunks as raw bytes with concurrency control.
+	*/
+	async downloadChunksRaw(chunks, signal) {
+		const semaphore = new Semaphore(this.options.maxConcurrentDownloads);
+		const downloadPromises = chunks.map(async (chunk) => {
+			await semaphore.acquire();
+			try {
+				return await this.downloadChunkRaw(chunk, signal);
+			} finally {
+				semaphore.release();
+			}
+		});
+		return Promise.all(downloadPromises);
+	}
+	/**
+	* Download a single chunk as raw bytes with retry logic.
+	*/
+	async downloadChunkRaw(chunk, signal) {
+		let lastError = null;
+		for (let attempt = 0; attempt < this.options.retries; attempt++) {
+			const timeoutController = new AbortController();
+			const timeoutId = setTimeout(() => {
+				timeoutController.abort();
+			}, this.options.timeout);
+			const combinedSignal = signal ? this.combineAbortSignals(signal, timeoutController.signal) : timeoutController.signal;
+			try {
+				const externalLink = chunk.external_link;
+				if (!externalLink) {
+					console.error("External link is required", chunk);
+					continue;
+				}
+				const response = await fetch(externalLink, { signal: combinedSignal });
+				if (!response.ok) throw new Error(`Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`);
+				const arrayBuffer = await response.arrayBuffer();
+				return new Uint8Array(arrayBuffer);
+			} catch (error) {
+				lastError = error;
+				if (timeoutController.signal.aborted) lastError = /* @__PURE__ */ new Error(`Chunk ${chunk.chunk_index} download timed out after ${this.options.timeout}ms`);
+				if (signal?.aborted) throw new Error("Arrow stream processing was aborted");
+				if (attempt < this.options.retries - 1) await this.delay(2 ** attempt * BACKOFF_MULTIPLIER);
+			} finally {
+				clearTimeout(timeoutId);
+			}
+		}
+		throw new Error(`Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`);
+	}
+	/**
+	* Concatenate multiple Uint8Array buffers into a single buffer.
+	* Pre-allocates the result array for efficiency.
+	*/
+	concatenateBuffers(buffers) {
+		if (buffers.length === 0) throw new Error("No buffers to concatenate");
+		if (buffers.length === 1) return buffers[0];
+		const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);
+		const result = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const buffer of buffers) {
+			result.set(buffer, offset);
+			offset += buffer.length;
+		}
+		return result;
+	}
+	/**
+	* Combines multiple AbortSignals into one.
+	* The combined signal aborts when any of the input signals abort.
+	*/
+	combineAbortSignals(...signals) {
+		const controller = new AbortController();
+		for (const signal of signals) {
+			if (signal.aborted) {
+				controller.abort();
+				return controller.signal;
+			}
+			signal.addEventListener("abort", () => controller.abort(), { once: true });
+		}
+		return controller.signal;
+	}
+	delay(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+var Semaphore = class {
+	constructor(permits) {
+		this.waiting = [];
+		this.permits = permits;
+	}
+	async acquire() {
+		if (this.permits > 0) {
+			this.permits--;
+			return;
+		}
+		return new Promise((resolve) => {
+			this.waiting.push(resolve);
+		});
+	}
+	release() {
+		if (this.waiting.length > 0) {
+			const next = this.waiting.shift();
+			if (next) next();
+		} else this.permits++;
+	}
+};
+
+//#endregion
+export { ArrowStreamProcessor };
+//# sourceMappingURL=arrow-stream-processor.js.map

package/dist/stream/arrow-stream-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrow-stream-processor.js","names":["options: ArrowStreamOptions","lastError: Error | null"],"sources":["../../src/stream/arrow-stream-processor.ts"],"sourcesContent":["import type { sql } from \"@databricks/sdk-experimental\";\n\ntype ResultManifest = sql.ResultManifest;\ntype ExternalLink = sql.ExternalLink;\n\nexport interface ArrowStreamOptions {\n  maxConcurrentDownloads: number;\n  timeout: number;\n  retries: number;\n}\n\n/**\n * Result from zero-copy Arrow chunk processing.\n * Contains raw IPC bytes without server-side parsing.\n */\nexport interface ArrowRawResult {\n  /** Concatenated raw Arrow IPC bytes */\n  data: Uint8Array;\n  /** Schema from Databricks manifest (not parsed from Arrow) */\n  schema: ResultManifest[\"schema\"];\n}\n\nconst BACKOFF_MULTIPLIER = 1000;\n\nexport class ArrowStreamProcessor {\n  static readonly DEFAULT_MAX_CONCURRENT_DOWNLOADS = 5;\n  static readonly DEFAULT_TIMEOUT = 30000;\n  static readonly DEFAULT_RETRIES = 3;\n\n  constructor(\n    private options: ArrowStreamOptions = {\n      maxConcurrentDownloads:\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: ArrowStreamProcessor.DEFAULT_RETRIES,\n    },\n  ) {\n    this.options = {\n      maxConcurrentDownloads:\n        options.maxConcurrentDownloads ??\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: options.timeout ?? ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: options.retries ?? ArrowStreamProcessor.DEFAULT_RETRIES,\n    };\n  }\n\n  /**\n   * Process Arrow chunks using zero-copy proxy pattern.\n   *\n   * Downloads raw IPC bytes from external links and concatenates them\n   * without parsing into Arrow Tables on the server. This reduces:\n   * - Memory usage by ~50% (no parsed Table representation)\n   * - CPU usage (no tableFromIPC/tableToIPC calls)\n   *\n   * The client is responsible for parsing the IPC bytes.\n   *\n   * @param chunks - External links to Arrow IPC data\n   * @param schema - Schema from Databricks manifest\n   * @param signal - Optional abort signal\n   * @returns Raw concatenated IPC bytes with schema\n   */\n  async processChunks(\n    chunks: ExternalLink[],\n    schema: ResultManifest[\"schema\"],\n    signal?: AbortSignal,\n  ): Promise<ArrowRawResult> {\n    if (chunks.length === 0) {\n      throw new Error(\"No Arrow chunks provided\");\n    }\n\n    const buffers = await this.downloadChunksRaw(chunks, signal);\n    const data = this.concatenateBuffers(buffers);\n\n    return { data, schema };\n  }\n\n  /**\n   * Download all chunks as raw bytes with concurrency control.\n   */\n  private async downloadChunksRaw(\n    chunks: ExternalLink[],\n    signal?: AbortSignal,\n  ): Promise<Uint8Array[]> {\n    const semaphore = new Semaphore(this.options.maxConcurrentDownloads);\n\n    const downloadPromises = chunks.map(async (chunk) => {\n      await semaphore.acquire();\n      try {\n        return await this.downloadChunkRaw(chunk, signal);\n      } finally {\n        semaphore.release();\n      }\n    });\n\n    return Promise.all(downloadPromises);\n  }\n\n  /**\n   * Download a single chunk as raw bytes with retry logic.\n   */\n  private async downloadChunkRaw(\n    chunk: ExternalLink,\n    signal?: AbortSignal,\n  ): Promise<Uint8Array> {\n    let lastError: Error | null = null;\n\n    for (let attempt = 0; attempt < this.options.retries; attempt++) {\n      const timeoutController = new AbortController();\n      const timeoutId = setTimeout(() => {\n        timeoutController.abort();\n      }, this.options.timeout);\n\n      const combinedSignal = signal\n        ? this.combineAbortSignals(signal, timeoutController.signal)\n        : timeoutController.signal;\n\n      try {\n        const externalLink = chunk.external_link;\n        if (!externalLink) {\n          console.error(\"External link is required\", chunk);\n          continue;\n        }\n\n        const response = await fetch(externalLink, {\n          signal: combinedSignal,\n        });\n\n        if (!response.ok) {\n          throw new Error(\n            `Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`,\n          );\n        }\n\n        const arrayBuffer = await response.arrayBuffer();\n        return new Uint8Array(arrayBuffer);\n      } catch (error) {\n        lastError = error as Error;\n\n        if (timeoutController.signal.aborted) {\n          lastError = new Error(\n            `Chunk ${chunk.chunk_index} download timed out after ${this.options.timeout}ms`,\n          );\n        }\n\n        if (signal?.aborted) {\n          throw new Error(\"Arrow stream processing was aborted\");\n        }\n\n        if (attempt < this.options.retries - 1) {\n          await this.delay(2 ** attempt * BACKOFF_MULTIPLIER);\n        }\n      } finally {\n        clearTimeout(timeoutId);\n      }\n    }\n\n    throw new Error(\n      `Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`,\n    );\n  }\n\n  /**\n   * Concatenate multiple Uint8Array buffers into a single buffer.\n   * Pre-allocates the result array for efficiency.\n   */\n  private concatenateBuffers(buffers: Uint8Array[]): Uint8Array {\n    if (buffers.length === 0) {\n      throw new Error(\"No buffers to concatenate\");\n    }\n\n    if (buffers.length === 1) {\n      return buffers[0];\n    }\n\n    const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);\n    const result = new Uint8Array(totalLength);\n\n    let offset = 0;\n    for (const buffer of buffers) {\n      result.set(buffer, offset);\n      offset += buffer.length;\n    }\n\n    return result;\n  }\n\n  /**\n   * Combines multiple AbortSignals into one.\n   * The combined signal aborts when any of the input signals abort.\n   */\n  private combineAbortSignals(...signals: AbortSignal[]): AbortSignal {\n    const controller = new AbortController();\n\n    for (const signal of signals) {\n      if (signal.aborted) {\n        controller.abort();\n        return controller.signal;\n      }\n      signal.addEventListener(\"abort\", () => controller.abort(), {\n        once: true,\n      });\n    }\n\n    return controller.signal;\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\nclass Semaphore {\n  private permits: number;\n  private waiting: (() => void)[] = [];\n\n  constructor(permits: number) {\n    this.permits = permits;\n  }\n\n  async acquire(): Promise<void> {\n    if (this.permits > 0) {\n      this.permits--;\n      return;\n    }\n\n    return new Promise<void>((resolve) => {\n      this.waiting.push(resolve);\n    });\n  }\n\n  release(): void {\n    if (this.waiting.length > 0) {\n      const next = this.waiting.shift();\n\n      if (next) {\n        next();\n      }\n    } else {\n      this.permits++;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/stream/buffers.js

@@ -0,0 +1,88 @@
+//#region src/stream/buffers.ts
+var RingBuffer = class {
+	constructor(capacity, keyExtractor) {
+		if (capacity <= 0) throw new Error("Capacity must be greater than 0");
+		this.capacity = capacity;
+		this.buffer = new Array(capacity).fill(null);
+		this.writeIndex = 0;
+		this.size = 0;
+		this.keyExtractor = keyExtractor;
+		this.keyIndex = /* @__PURE__ */ new Map();
+	}
+	add(item) {
+		const key = this.keyExtractor(item);
+		const existingIndex = this.keyIndex.get(key);
+		if (existingIndex !== void 0) {
+			this.buffer[existingIndex] = item;
+			return;
+		}
+		const evicted = this.buffer[this.writeIndex];
+		if (evicted !== null) {
+			const evictedKey = this.keyExtractor(evicted);
+			this.keyIndex.delete(evictedKey);
+		}
+		this.buffer[this.writeIndex] = item;
+		this.keyIndex.set(key, this.writeIndex);
+		this.writeIndex = (this.writeIndex + 1) % this.capacity;
+		this.size = Math.min(this.size + 1, this.capacity);
+	}
+	get(key) {
+		const index = this.keyIndex.get(key);
+		if (index === void 0) return null;
+		return this.buffer[index];
+	}
+	has(key) {
+		return this.keyIndex.has(key);
+	}
+	remove(key) {
+		const index = this.keyIndex.get(key);
+		if (index === void 0) return;
+		this.buffer[index] = null;
+		this.keyIndex.delete(key);
+		this.size = Math.max(this.size - 1, 0);
+	}
+	getAll() {
+		const result = [];
+		for (let i = 0; i < this.size; i++) {
+			const index = (this.writeIndex - this.size + i + this.capacity) % this.capacity;
+			const item = this.buffer[index];
+			if (item !== null) result.push(item);
+		}
+		return result;
+	}
+	getSize() {
+		return this.size;
+	}
+	clear() {
+		this.buffer = new Array(this.capacity).fill(null);
+		this.keyIndex.clear();
+		this.writeIndex = 0;
+		this.size = 0;
+	}
+};
+var EventRingBuffer = class {
+	constructor(capacity = 100) {
+		this.buffer = new RingBuffer(capacity, (event) => event.id);
+	}
+	add(event) {
+		this.buffer.add(event);
+	}
+	has(eventId) {
+		return this.buffer.has(eventId);
+	}
+	getEventsSince(lastEventId) {
+		const allEvents = this.buffer.getAll();
+		const result = [];
+		let foundLastEvent = false;
+		for (const event of allEvents) if (foundLastEvent) result.push(event);
+		else if (event.id === lastEventId) foundLastEvent = true;
+		return result;
+	}
+	clear() {
+		this.buffer.clear();
+	}
+};
+
+//#endregion
+export { EventRingBuffer, RingBuffer };
+//# sourceMappingURL=buffers.js.map

package/dist/stream/buffers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffers.js","names":["result: T[]","result: BufferedEvent[]"],"sources":["../../src/stream/buffers.ts"],"sourcesContent":["import type { BufferedEvent } from \"./types\";\n\n// generic ring buffer implementation\nexport class RingBuffer<T> {\n  public buffer: (T | null)[];\n  public capacity: number;\n  private writeIndex: number;\n  private size: number;\n  private keyExtractor: (item: T) => string;\n  private keyIndex: Map<string, number>;\n\n  constructor(capacity: number, keyExtractor: (item: T) => string) {\n    if (capacity <= 0) {\n      throw new Error(\"Capacity must be greater than 0\");\n    }\n\n    this.capacity = capacity;\n    this.buffer = new Array(capacity).fill(null);\n    this.writeIndex = 0;\n    this.size = 0;\n    this.keyExtractor = keyExtractor;\n    this.keyIndex = new Map();\n  }\n\n  // add an item to the buffer\n  add(item: T): void {\n    const key = this.keyExtractor(item);\n\n    // check if item already exists\n    const existingIndex = this.keyIndex.get(key);\n    if (existingIndex !== undefined) {\n      // update existing item\n      this.buffer[existingIndex] = item;\n      return;\n    }\n\n    // evict least recently used item if at capacity\n    const evicted = this.buffer[this.writeIndex];\n    if (evicted !== null) {\n      const evictedKey = this.keyExtractor(evicted);\n      this.keyIndex.delete(evictedKey);\n    }\n\n    // add new item\n    this.buffer[this.writeIndex] = item;\n    this.keyIndex.set(key, this.writeIndex);\n\n    // update write index and size\n    this.writeIndex = (this.writeIndex + 1) % this.capacity;\n    this.size = Math.min(this.size + 1, this.capacity);\n  }\n\n  // get an item from the buffer\n  get(key: string): T | null {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return null;\n\n    return this.buffer[index];\n  }\n\n  // check if an item exists in the buffer\n  has(key: string): boolean {\n    return this.keyIndex.has(key);\n  }\n\n  // remove an item from the buffer\n  remove(key: string): void {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return;\n\n    // remove item from buffer\n    this.buffer[index] = null;\n    this.keyIndex.delete(key);\n\n    // update size\n    this.size = Math.max(this.size - 1, 0);\n  }\n\n  // get all items from the buffer\n  getAll(): T[] {\n    const result: T[] = [];\n\n    // iterate over buffer in order of insertion\n    for (let i = 0; i < this.size; i++) {\n      // calculate index of item in buffer\n      const index =\n        (this.writeIndex - this.size + i + this.capacity) % this.capacity;\n      // add item to result if not null\n      const item = this.buffer[index];\n      if (item !== null) {\n        result.push(item);\n      }\n    }\n    return result;\n  }\n\n  // get the size of the buffer\n  getSize(): number {\n    return this.size;\n  }\n\n  // clear the buffer\n  clear(): void {\n    this.buffer = new Array(this.capacity).fill(null);\n    this.keyIndex.clear();\n    this.writeIndex = 0;\n    this.size = 0;\n  }\n}\n\n// event ring buffer implementation\nexport class EventRingBuffer {\n  private buffer: RingBuffer<BufferedEvent>;\n\n  constructor(capacity: number = 100) {\n    this.buffer = new RingBuffer<BufferedEvent>(capacity, (event) => event.id);\n  }\n\n  // add an event to the buffer\n  add(event: BufferedEvent): void {\n    this.buffer.add(event);\n  }\n\n  // check if an event exists in the buffer\n  has(eventId: string): boolean {\n    return this.buffer.has(eventId);\n  }\n\n  // get all events since a given event id\n  getEventsSince(lastEventId: string): BufferedEvent[] {\n    const allEvents = this.buffer.getAll();\n    const result: BufferedEvent[] = [];\n    // flag to track if we've found the last event\n    let foundLastEvent = false;\n\n    // iterate over all events\n    for (const event of allEvents) {\n      // if found, add to result\n      if (foundLastEvent) {\n        result.push(event);\n        // if not found, check if it's the last event\n      } else if (event.id === lastEventId) {\n        foundLastEvent = true;\n      }\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.buffer.clear();\n  }\n}\n"],"mappings":";AAGA,IAAa,aAAb,MAA2B;CAQzB,YAAY,UAAkB,cAAmC;AAC/D,MAAI,YAAY,EACd,OAAM,IAAI,MAAM,kCAAkC;AAGpD,OAAK,WAAW;AAChB,OAAK,SAAS,IAAI,MAAM,SAAS,CAAC,KAAK,KAAK;AAC5C,OAAK,aAAa;AAClB,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,2BAAW,IAAI,KAAK;;CAI3B,IAAI,MAAe;EACjB,MAAM,MAAM,KAAK,aAAa,KAAK;EAGnC,MAAM,gBAAgB,KAAK,SAAS,IAAI,IAAI;AAC5C,MAAI,kBAAkB,QAAW;AAE/B,QAAK,OAAO,iBAAiB;AAC7B;;EAIF,MAAM,UAAU,KAAK,OAAO,KAAK;AACjC,MAAI,YAAY,MAAM;GACpB,MAAM,aAAa,KAAK,aAAa,QAAQ;AAC7C,QAAK,SAAS,OAAO,WAAW;;AAIlC,OAAK,OAAO,KAAK,cAAc;AAC/B,OAAK,SAAS,IAAI,KAAK,KAAK,WAAW;AAGvC,OAAK,cAAc,KAAK,aAAa,KAAK,KAAK;AAC/C,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,KAAK,SAAS;;CAIpD,IAAI,KAAuB;EACzB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,SAAO,KAAK,OAAO;;CAIrB,IAAI,KAAsB;AACxB,SAAO,KAAK,SAAS,IAAI,IAAI;;CAI/B,OAAO,KAAmB;EACxB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW;AAGzB,OAAK,OAAO,SAAS;AACrB,OAAK,SAAS,OAAO,IAAI;AAGzB,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,EAAE;;CAIxC,SAAc;EACZ,MAAMA,SAAc,EAAE;AAGtB,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;GAElC,MAAM,SACH,KAAK,aAAa,KAAK,OAAO,IAAI,KAAK,YAAY,KAAK;GAE3D,MAAM,OAAO,KAAK,OAAO;AACzB,OAAI,SAAS,KACX,QAAO,KAAK,KAAK;;AAGrB,SAAO;;CAIT,UAAkB;AAChB,SAAO,KAAK;;CAId,QAAc;AACZ,OAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC,KAAK,KAAK;AACjD,OAAK,SAAS,OAAO;AACrB,OAAK,aAAa;AAClB,OAAK,OAAO;;;AAKhB,IAAa,kBAAb,MAA6B;CAG3B,YAAY,WAAmB,KAAK;AAClC,OAAK,SAAS,IAAI,WAA0B,WAAW,UAAU,MAAM,GAAG;;CAI5E,IAAI,OAA4B;AAC9B,OAAK,OAAO,IAAI,MAAM;;CAIxB,IAAI,SAA0B;AAC5B,SAAO,KAAK,OAAO,IAAI,QAAQ;;CAIjC,eAAe,aAAsC;EACnD,MAAM,YAAY,KAAK,OAAO,QAAQ;EACtC,MAAMC,SAA0B,EAAE;EAElC,IAAI,iBAAiB;AAGrB,OAAK,MAAM,SAAS,UAElB,KAAI,eACF,QAAO,KAAK,MAAM;WAET,MAAM,OAAO,YACtB,kBAAiB;AAGrB,SAAO;;CAGT,QAAc;AACZ,OAAK,OAAO,OAAO"}

package/dist/stream/defaults.js

@@ -0,0 +1,14 @@
+//#region src/stream/defaults.ts
+const streamDefaults = {
+	bufferSize: 100,
+	maxEventSize: 1024 * 1024,
+	bufferTTL: 600 * 1e3,
+	cleanupInterval: 300 * 1e3,
+	maxPersistentBuffers: 1e4,
+	heartbeatInterval: 10 * 1e3,
+	maxActiveStreams: 1e3
+};
+
+//#endregion
+export { streamDefaults };
+//# sourceMappingURL=defaults.js.map

package/dist/stream/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","names":[],"sources":["../../src/stream/defaults.ts"],"sourcesContent":["export const streamDefaults = {\n  bufferSize: 100,\n  maxEventSize: 1024 * 1024, // 1MB\n  bufferTTL: 10 * 60 * 1000, // 10 minutes\n  cleanupInterval: 5 * 60 * 1000, // 5 minutes\n  maxPersistentBuffers: 10000, // 10000 buffers\n  heartbeatInterval: 10 * 1000, // 10 seconds\n  maxActiveStreams: 1000, // 1000 streams\n} as const;\n"],"mappings":";AAAA,MAAa,iBAAiB;CAC5B,YAAY;CACZ,cAAc,OAAO;CACrB,WAAW,MAAU;CACrB,iBAAiB,MAAS;CAC1B,sBAAsB;CACtB,mBAAmB,KAAK;CACxB,kBAAkB;CACnB"}

package/dist/stream/index.js

@@ -0,0 +1,6 @@
+import { ArrowStreamProcessor } from "./arrow-stream-processor.js";
+import { streamDefaults } from "./defaults.js";
+import { SSEWarningCode } from "./types.js";
+import { StreamManager } from "./stream-manager.js";
+
+export {  };

package/dist/stream/sse-writer.js

@@ -0,0 +1,61 @@
+import { streamDefaults } from "./defaults.js";
+import { SSEErrorCode, SSEWarningCode } from "./types.js";
+import { StreamValidator } from "./validator.js";
+
+//#region src/stream/sse-writer.ts
+var SSEWriter = class {
+	setupHeaders(res) {
+		res.setHeader("Content-Type", "text/event-stream");
+		res.setHeader("Cache-Control", "no-cache");
+		res.setHeader("Connection", "keep-alive");
+		res.setHeader("Content-Encoding", "none");
+		res.flushHeaders?.();
+	}
+	writeEvent(res, eventId, event) {
+		if (res.writableEnded) return;
+		const eventType = StreamValidator.sanitizeEventType(event.type);
+		const eventData = JSON.stringify(event);
+		res.write(`id: ${eventId}\n`);
+		res.write(`event: ${eventType}\n`);
+		res.write(`data: ${eventData}\n\n`);
+	}
+	writeError(res, eventId, error, code = SSEErrorCode.INTERNAL_ERROR) {
+		if (res.writableEnded) return;
+		const errorData = {
+			error,
+			code
+		};
+		res.write(`id: ${eventId}\n`);
+		res.write(`event: error\n`);
+		res.write(`data: ${JSON.stringify(errorData)}\n\n`);
+	}
+	writeBufferedEvent(res, event) {
+		if (res.writableEnded) return;
+		res.write(`id: ${event.id}\n`);
+		res.write(`event: ${event.type}\n`);
+		res.write(`data: ${event.data}\n\n`);
+	}
+	writeBufferOverflowWarning(res, lastEventId) {
+		if (res.writableEnded) return;
+		try {
+			res.write(`event: warning\n`);
+			res.write(`data: ${JSON.stringify({
+				warning: "Buffer overflow detected - some events were lost",
+				code: SSEWarningCode.BUFFER_OVERFLOW_RESTART,
+				lastEventId
+			})}\n\n`);
+		} catch (_error) {}
+	}
+	startHeartbeat(res, signal, interval) {
+		const heartbeatInterval = interval ?? streamDefaults.heartbeatInterval;
+		return setInterval(() => {
+			if (!signal.aborted && !res.writableEnded) try {
+				res.write(`: heartbeat\n\n`);
+			} catch (_error) {}
+		}, heartbeatInterval);
+	}
+};
+
+//#endregion
+export { SSEWriter };
+//# sourceMappingURL=sse-writer.js.map

package/dist/stream/sse-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-writer.js","names":["errorData: SSEError"],"sources":["../../src/stream/sse-writer.ts"],"sourcesContent":["import type { IAppResponse } from \"shared\";\nimport { streamDefaults } from \"./defaults\";\nimport {\n  type BufferedEvent,\n  type SSEError,\n  SSEErrorCode,\n  SSEWarningCode,\n} from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\nexport class SSEWriter {\n  // setup SSE headers\n  setupHeaders(res: IAppResponse): void {\n    res.setHeader(\"Content-Type\", \"text/event-stream\");\n    res.setHeader(\"Cache-Control\", \"no-cache\");\n    res.setHeader(\"Connection\", \"keep-alive\");\n    res.setHeader(\"Content-Encoding\", \"none\");\n\n    res.flushHeaders?.();\n  }\n\n  // write a single event to the response\n  writeEvent(res: IAppResponse, eventId: string, event: any): void {\n    if (res.writableEnded) return;\n\n    const eventType = StreamValidator.sanitizeEventType(event.type);\n    const eventData = JSON.stringify(event);\n\n    res.write(`id: ${eventId}\\n`);\n    res.write(`event: ${eventType}\\n`);\n    res.write(`data: ${eventData}\\n\\n`);\n  }\n  writeError(\n    res: IAppResponse,\n    eventId: string,\n    error: string,\n    code: SSEErrorCode = SSEErrorCode.INTERNAL_ERROR,\n  ): void {\n    if (res.writableEnded) return;\n\n    const errorData: SSEError = {\n      error,\n      code,\n    };\n\n    res.write(`id: ${eventId}\\n`);\n    res.write(`event: error\\n`);\n    res.write(`data: ${JSON.stringify(errorData)}\\n\\n`);\n  }\n\n  // write a buffered event for replay\n  writeBufferedEvent(res: IAppResponse, event: BufferedEvent): void {\n    if (res.writableEnded) return;\n\n    res.write(`id: ${event.id}\\n`);\n    res.write(`event: ${event.type}\\n`);\n    res.write(`data: ${event.data}\\n\\n`);\n  }\n\n  // write a buffer overflow warning\n  writeBufferOverflowWarning(res: IAppResponse, lastEventId: string): void {\n    if (res.writableEnded) return;\n\n    try {\n      res.write(`event: warning\\n`);\n      res.write(\n        `data: ${JSON.stringify({\n          warning: \"Buffer overflow detected - some events were lost\",\n          code: SSEWarningCode.BUFFER_OVERFLOW_RESTART,\n          lastEventId,\n        })}\\n\\n`,\n      );\n    } catch (_error) {\n      // ignore write errors - client will ignore this event\n    }\n  }\n\n  // start the heartbeat interval\n  startHeartbeat(\n    res: IAppResponse,\n    signal: AbortSignal,\n    interval?: number,\n  ): NodeJS.Timeout {\n    const heartbeatInterval = interval ?? streamDefaults.heartbeatInterval;\n\n    return setInterval(() => {\n      if (!signal.aborted && !res.writableEnded) {\n        try {\n          res.write(`: heartbeat\\n\\n`);\n        } catch (_error) {\n          // ignore write errors - client will ignore this event\n        }\n      }\n    }, heartbeatInterval);\n  }\n}\n"],"mappings":";;;;;AAUA,IAAa,YAAb,MAAuB;CAErB,aAAa,KAAyB;AACpC,MAAI,UAAU,gBAAgB,oBAAoB;AAClD,MAAI,UAAU,iBAAiB,WAAW;AAC1C,MAAI,UAAU,cAAc,aAAa;AACzC,MAAI,UAAU,oBAAoB,OAAO;AAEzC,MAAI,gBAAgB;;CAItB,WAAW,KAAmB,SAAiB,OAAkB;AAC/D,MAAI,IAAI,cAAe;EAEvB,MAAM,YAAY,gBAAgB,kBAAkB,MAAM,KAAK;EAC/D,MAAM,YAAY,KAAK,UAAU,MAAM;AAEvC,MAAI,MAAM,OAAO,QAAQ,IAAI;AAC7B,MAAI,MAAM,UAAU,UAAU,IAAI;AAClC,MAAI,MAAM,SAAS,UAAU,MAAM;;CAErC,WACE,KACA,SACA,OACA,OAAqB,aAAa,gBAC5B;AACN,MAAI,IAAI,cAAe;EAEvB,MAAMA,YAAsB;GAC1B;GACA;GACD;AAED,MAAI,MAAM,OAAO,QAAQ,IAAI;AAC7B,MAAI,MAAM,iBAAiB;AAC3B,MAAI,MAAM,SAAS,KAAK,UAAU,UAAU,CAAC,MAAM;;CAIrD,mBAAmB,KAAmB,OAA4B;AAChE,MAAI,IAAI,cAAe;AAEvB,MAAI,MAAM,OAAO,MAAM,GAAG,IAAI;AAC9B,MAAI,MAAM,UAAU,MAAM,KAAK,IAAI;AACnC,MAAI,MAAM,SAAS,MAAM,KAAK,MAAM;;CAItC,2BAA2B,KAAmB,aAA2B;AACvE,MAAI,IAAI,cAAe;AAEvB,MAAI;AACF,OAAI,MAAM,mBAAmB;AAC7B,OAAI,MACF,SAAS,KAAK,UAAU;IACtB,SAAS;IACT,MAAM,eAAe;IACrB;IACD,CAAC,CAAC,MACJ;WACM,QAAQ;;CAMnB,eACE,KACA,QACA,UACgB;EAChB,MAAM,oBAAoB,YAAY,eAAe;AAErD,SAAO,kBAAkB;AACvB,OAAI,CAAC,OAAO,WAAW,CAAC,IAAI,cAC1B,KAAI;AACF,QAAI,MAAM,kBAAkB;YACrB,QAAQ;KAIlB,kBAAkB"}

package/dist/stream/stream-manager.d.ts

@@ -0,0 +1,27 @@
+import { IAppResponse } from "../shared/src/plugin.js";
+import { StreamConfig } from "../shared/src/execute.js";
+
+//#region src/stream/stream-manager.d.ts
+declare class StreamManager {
+  private activeOperations;
+  private streamRegistry;
+  private sseWriter;
+  private maxEventSize;
+  private bufferTTL;
+  constructor(options?: StreamConfig);
+  stream(res: IAppResponse, handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>, options?: StreamConfig): Promise<void>;
+  abortAll(): void;
+  getActiveCount(): number;
+  private _attachToExistingStream;
+  private _createNewStream;
+  private _processGeneratorInBackground;
+  private _combineSignals;
+  private _broadcastEventsToClients;
+  private _broadcastErrorToClients;
+  private _closeAllClients;
+  private _cleanupStream;
+  private _categorizeError;
+}
+//#endregion
+export { StreamManager };
+//# sourceMappingURL=stream-manager.d.ts.map

package/dist/stream/stream-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":[],"mappings":";;;;cAUa,aAAA;;;EAAA,QAAA,SAAa;EAAA,QAAA,YAAA;UAOF,SAAA;aAYf,CAAA,OAAA,CAAA,EAZe,YAYf;QACa,CAAA,GAAA,EADb,YACa,EAAA,OAAA,EAAA,CAAA,MAAA,EAAA,WAAA,EAAA,GAAgB,cAAhB,CAAA,GAAA,EAAA,IAAA,EAAA,OAAA,CAAA,EAAA,OAAA,CAAA,EACR,YADQ,CAAA,EAEjB,OAFiB,CAAA,IAAA,CAAA;UAAgB,CAAA,CAAA,EAAA,IAAA;gBACxB,CAAA,CAAA,EAAA,MAAA;UACT,uBAAA;EAAO,QAAA,gBAAA"}

package/dist/stream/stream-manager.js

@@ -0,0 +1,191 @@
+import { streamDefaults } from "./defaults.js";
+import { EventRingBuffer } from "./buffers.js";
+import { SSEErrorCode } from "./types.js";
+import { StreamValidator } from "./validator.js";
+import { SSEWriter } from "./sse-writer.js";
+import { StreamRegistry } from "./stream-registry.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/stream/stream-manager.ts
+var StreamManager = class {
+	constructor(options) {
+		this.streamRegistry = new StreamRegistry(options?.maxActiveStreams ?? streamDefaults.maxActiveStreams);
+		this.sseWriter = new SSEWriter();
+		this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;
+		this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;
+		this.activeOperations = /* @__PURE__ */ new Set();
+	}
+	stream(res, handler, options) {
+		const { streamId } = options || {};
+		this.sseWriter.setupHeaders(res);
+		if (streamId && StreamValidator.validateStreamId(streamId)) {
+			const existingStream = this.streamRegistry.get(streamId);
+			if (existingStream) return this._attachToExistingStream(res, existingStream, options);
+		}
+		return this._createNewStream(res, handler, options);
+	}
+	abortAll() {
+		this.activeOperations.forEach((operation) => {
+			if (operation.heartbeat) clearInterval(operation.heartbeat);
+			operation.controller.abort("Server shutdown");
+		});
+		this.activeOperations.clear();
+		this.streamRegistry.clear();
+	}
+	getActiveCount() {
+		return this.activeOperations.size;
+	}
+	async _attachToExistingStream(res, streamEntry, options) {
+		const lastEventId = res.req?.headers["last-event-id"];
+		if (StreamValidator.validateEventId(lastEventId)) {
+			const validEventId = lastEventId;
+			if (streamEntry.eventBuffer.has(validEventId)) {
+				const missedEvents = streamEntry.eventBuffer.getEventsSince(validEventId);
+				for (const event of missedEvents) {
+					if (options?.userSignal?.aborted) break;
+					this.sseWriter.writeBufferedEvent(res, event);
+				}
+			} else this.sseWriter.writeBufferOverflowWarning(res, validEventId);
+		}
+		streamEntry.clients.add(res);
+		streamEntry.lastAccess = Date.now();
+		const combinedSignal = this._combineSignals(streamEntry.abortController.signal, options?.userSignal);
+		const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);
+		const streamOperation = {
+			controller: streamEntry.abortController,
+			type: "stream",
+			heartbeat
+		};
+		this.activeOperations.add(streamOperation);
+		res.on("close", () => {
+			clearInterval(heartbeat);
+			streamEntry.clients.delete(res);
+			this.activeOperations.delete(streamOperation);
+			if (streamEntry.isCompleted && streamEntry.clients.size === 0) setTimeout(() => {
+				if (streamEntry.clients.size === 0) this.streamRegistry.remove(streamEntry.streamId);
+			}, this.bufferTTL);
+		});
+		if (streamEntry.isCompleted) {
+			res.end();
+			this.activeOperations.delete(streamOperation);
+			clearInterval(heartbeat);
+		}
+	}
+	async _createNewStream(res, handler, options) {
+		const streamId = options?.streamId ?? randomUUID();
+		const abortController = new AbortController();
+		const eventBuffer = new EventRingBuffer(options?.bufferSize ?? streamDefaults.bufferSize);
+		const combinedSignal = this._combineSignals(abortController.signal, options?.userSignal);
+		const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);
+		const streamEntry = {
+			streamId,
+			generator: handler(combinedSignal),
+			eventBuffer,
+			clients: new Set([res]),
+			isCompleted: false,
+			lastAccess: Date.now(),
+			abortController
+		};
+		this.streamRegistry.add(streamEntry);
+		const streamOperation = {
+			controller: abortController,
+			type: "stream",
+			heartbeat
+		};
+		this.activeOperations.add(streamOperation);
+		res.on("close", () => {
+			clearInterval(heartbeat);
+			this.activeOperations.delete(streamOperation);
+			streamEntry.clients.delete(res);
+		});
+		await this._processGeneratorInBackground(streamEntry);
+		clearInterval(heartbeat);
+		this.activeOperations.delete(streamOperation);
+	}
+	async _processGeneratorInBackground(streamEntry) {
+		try {
+			for await (const event of streamEntry.generator) {
+				if (streamEntry.abortController.signal.aborted) break;
+				const eventId = randomUUID();
+				const eventData = JSON.stringify(event);
+				if (eventData.length > this.maxEventSize) {
+					const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;
+					const errorCode = SSEErrorCode.INVALID_REQUEST;
+					this._broadcastErrorToClients(streamEntry, eventId, errorMsg, errorCode);
+					continue;
+				}
+				streamEntry.eventBuffer.add({
+					id: eventId,
+					type: event.type,
+					data: eventData,
+					timestamp: Date.now()
+				});
+				this._broadcastEventsToClients(streamEntry, eventId, event);
+				streamEntry.lastAccess = Date.now();
+			}
+			streamEntry.isCompleted = true;
+			this._closeAllClients(streamEntry);
+			this._cleanupStream(streamEntry);
+		} catch (error) {
+			const errorMsg = error instanceof Error ? error.message : "Internal server error";
+			const errorEventId = randomUUID();
+			const errorCode = this._categorizeError(error);
+			streamEntry.eventBuffer.add({
+				id: errorEventId,
+				type: "error",
+				data: JSON.stringify({
+					error: errorMsg,
+					code: errorCode
+				}),
+				timestamp: Date.now()
+			});
+			this._broadcastErrorToClients(streamEntry, errorEventId, errorMsg, errorCode, true);
+			streamEntry.isCompleted = true;
+		}
+	}
+	_combineSignals(internalSignal, userSignal) {
+		if (!userSignal) return internalSignal || new AbortController().signal;
+		const signals = [internalSignal, userSignal].filter(Boolean);
+		const controller = new AbortController();
+		signals.forEach((signal) => {
+			if (signal?.aborted) {
+				controller.abort(signal.reason);
+				return;
+			}
+			signal?.addEventListener("abort", () => {
+				controller.abort(signal.reason);
+			}, { once: true });
+		});
+		return controller.signal;
+	}
+	_broadcastEventsToClients(streamEntry, eventId, event) {
+		for (const client of streamEntry.clients) if (!client.writableEnded) this.sseWriter.writeEvent(client, eventId, event);
+	}
+	_broadcastErrorToClients(streamEntry, eventId, errorMessage, errorCode, closeClients = false) {
+		for (const client of streamEntry.clients) if (!client.writableEnded) {
+			this.sseWriter.writeError(client, eventId, errorMessage, errorCode);
+			if (closeClients) client.end();
+		}
+	}
+	_closeAllClients(streamEntry) {
+		for (const client of streamEntry.clients) if (!client.writableEnded) client.end();
+	}
+	_cleanupStream(streamEntry) {
+		if (streamEntry.clients.size === 0) setTimeout(() => {
+			if (streamEntry.clients.size === 0) this.streamRegistry.remove(streamEntry.streamId);
+		}, this.bufferTTL);
+	}
+	_categorizeError(error) {
+		if (error instanceof Error) {
+			const message = error.message.toLowerCase();
+			if (message.includes("timeout") || message.includes("timed out")) return SSEErrorCode.TIMEOUT;
+			if (message.includes("unavailable") || message.includes("econnrefused")) return SSEErrorCode.TEMPORARY_UNAVAILABLE;
+			if (error.name === "AbortError") return SSEErrorCode.STREAM_ABORTED;
+		}
+		return SSEErrorCode.INTERNAL_ERROR;
+	}
+};
+
+//#endregion
+export { StreamManager };
+//# sourceMappingURL=stream-manager.js.map