@durable-streams/server 0.1.0

package/dist/index.js

@@ -0,0 +1,1592 @@
+import { createServer } from "node:http";
+import { deflateSync, gzipSync } from "node:zlib";
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
+import * as path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { open } from "lmdb";
+import { SieveCache } from "@neophi/sieve-cache";
+import * as fs$1 from "node:fs/promises";
+import { DurableStream } from "@durable-streams/client";
+import { createStateSchema } from "@durable-streams/state";
+
+//#region src/store.ts
+/**
+* Normalize content-type by extracting the media type (before any semicolon).
+* Handles cases like "application/json; charset=utf-8".
+*/
+function normalizeContentType(contentType) {
+	if (!contentType) return ``;
+	return contentType.split(`;`)[0].trim().toLowerCase();
+}
+/**
+* Process JSON data for append in JSON mode.
+* - Validates JSON
+* - Extracts array elements if data is an array
+* - Always appends trailing comma for easy concatenation
+* @param isInitialCreate - If true, empty arrays are allowed (creates empty stream)
+* @throws Error if JSON is invalid or array is empty (for non-create operations)
+*/
+function processJsonAppend(data, isInitialCreate = false) {
+	const text = new TextDecoder().decode(data);
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new Error(`Invalid JSON`);
+	}
+	let result;
+	if (Array.isArray(parsed)) {
+		if (parsed.length === 0) {
+			if (isInitialCreate) return new Uint8Array(0);
+			throw new Error(`Empty arrays are not allowed`);
+		}
+		const elements = parsed.map((item) => JSON.stringify(item));
+		result = elements.join(`,`) + `,`;
+	} else result = JSON.stringify(parsed) + `,`;
+	return new TextEncoder().encode(result);
+}
+/**
+* Format JSON mode response by wrapping in array brackets.
+* Strips trailing comma before wrapping.
+*/
+function formatJsonResponse(data) {
+	if (data.length === 0) return new TextEncoder().encode(`[]`);
+	let text = new TextDecoder().decode(data);
+	text = text.trimEnd();
+	if (text.endsWith(`,`)) text = text.slice(0, -1);
+	const wrapped = `[${text}]`;
+	return new TextEncoder().encode(wrapped);
+}
+/**
+* In-memory store for durable streams.
+*/
+var StreamStore = class {
+	streams = new Map();
+	pendingLongPolls = [];
+	/**
+	* Create a new stream.
+	* @throws Error if stream already exists with different config
+	* @returns existing stream if config matches (idempotent)
+	*/
+	create(path$2, options = {}) {
+		const existing = this.streams.get(path$2);
+		if (existing) {
+			const contentTypeMatches = (normalizeContentType(options.contentType) || `application/octet-stream`) === (normalizeContentType(existing.contentType) || `application/octet-stream`);
+			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
+			const expiresMatches = options.expiresAt === existing.expiresAt;
+			if (contentTypeMatches && ttlMatches && expiresMatches) return existing;
+			else throw new Error(`Stream already exists with different configuration: ${path$2}`);
+		}
+		const stream = {
+			path: path$2,
+			contentType: options.contentType,
+			messages: [],
+			currentOffset: `0000000000000000_0000000000000000`,
+			ttlSeconds: options.ttlSeconds,
+			expiresAt: options.expiresAt,
+			createdAt: Date.now()
+		};
+		if (options.initialData && options.initialData.length > 0) this.appendToStream(stream, options.initialData, true);
+		this.streams.set(path$2, stream);
+		return stream;
+	}
+	/**
+	* Get a stream by path.
+	*/
+	get(path$2) {
+		return this.streams.get(path$2);
+	}
+	/**
+	* Check if a stream exists.
+	*/
+	has(path$2) {
+		return this.streams.has(path$2);
+	}
+	/**
+	* Delete a stream.
+	*/
+	delete(path$2) {
+		this.cancelLongPollsForStream(path$2);
+		return this.streams.delete(path$2);
+	}
+	/**
+	* Append data to a stream.
+	* @throws Error if stream doesn't exist
+	* @throws Error if seq is lower than lastSeq
+	* @throws Error if JSON mode and array is empty
+	*/
+	append(path$2, data, options = {}) {
+		const stream = this.streams.get(path$2);
+		if (!stream) throw new Error(`Stream not found: ${path$2}`);
+		if (options.contentType && stream.contentType) {
+			const providedType = normalizeContentType(options.contentType);
+			const streamType = normalizeContentType(stream.contentType);
+			if (providedType !== streamType) throw new Error(`Content-type mismatch: expected ${stream.contentType}, got ${options.contentType}`);
+		}
+		if (options.seq !== void 0) {
+			if (stream.lastSeq !== void 0 && options.seq <= stream.lastSeq) throw new Error(`Sequence conflict: ${options.seq} <= ${stream.lastSeq}`);
+			stream.lastSeq = options.seq;
+		}
+		const message = this.appendToStream(stream, data);
+		this.notifyLongPolls(path$2);
+		return message;
+	}
+	/**
+	* Read messages from a stream starting at the given offset.
+	*/
+	read(path$2, offset) {
+		const stream = this.streams.get(path$2);
+		if (!stream) throw new Error(`Stream not found: ${path$2}`);
+		if (!offset || offset === `-1`) return {
+			messages: [...stream.messages],
+			upToDate: true
+		};
+		const offsetIndex = this.findOffsetIndex(stream, offset);
+		if (offsetIndex === -1) return {
+			messages: [],
+			upToDate: true
+		};
+		return {
+			messages: stream.messages.slice(offsetIndex),
+			upToDate: true
+		};
+	}
+	/**
+	* Format messages for response.
+	* For JSON mode, wraps concatenated data in array brackets.
+	*/
+	formatResponse(path$2, messages) {
+		const stream = this.streams.get(path$2);
+		if (!stream) throw new Error(`Stream not found: ${path$2}`);
+		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
+		const concatenated = new Uint8Array(totalSize);
+		let offset = 0;
+		for (const msg of messages) {
+			concatenated.set(msg.data, offset);
+			offset += msg.data.length;
+		}
+		if (normalizeContentType(stream.contentType) === `application/json`) return formatJsonResponse(concatenated);
+		return concatenated;
+	}
+	/**
+	* Wait for new messages (long-poll).
+	*/
+	async waitForMessages(path$2, offset, timeoutMs) {
+		const stream = this.streams.get(path$2);
+		if (!stream) throw new Error(`Stream not found: ${path$2}`);
+		const { messages } = this.read(path$2, offset);
+		if (messages.length > 0) return {
+			messages,
+			timedOut: false
+		};
+		return new Promise((resolve) => {
+			const timeoutId = setTimeout(() => {
+				this.removePendingLongPoll(pending);
+				resolve({
+					messages: [],
+					timedOut: true
+				});
+			}, timeoutMs);
+			const pending = {
+				path: path$2,
+				offset,
+				resolve: (msgs) => {
+					clearTimeout(timeoutId);
+					this.removePendingLongPoll(pending);
+					resolve({
+						messages: msgs,
+						timedOut: false
+					});
+				},
+				timeoutId
+			};
+			this.pendingLongPolls.push(pending);
+		});
+	}
+	/**
+	* Get the current offset for a stream.
+	*/
+	getCurrentOffset(path$2) {
+		return this.streams.get(path$2)?.currentOffset;
+	}
+	/**
+	* Clear all streams.
+	*/
+	clear() {
+		for (const pending of this.pendingLongPolls) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = [];
+		this.streams.clear();
+	}
+	/**
+	* Cancel all pending long-polls (used during shutdown).
+	*/
+	cancelAllWaits() {
+		for (const pending of this.pendingLongPolls) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = [];
+	}
+	/**
+	* Get all stream paths.
+	*/
+	list() {
+		return Array.from(this.streams.keys());
+	}
+	appendToStream(stream, data, isInitialCreate = false) {
+		let processedData = data;
+		if (normalizeContentType(stream.contentType) === `application/json`) {
+			processedData = processJsonAppend(data, isInitialCreate);
+			if (processedData.length === 0) return null;
+		}
+		const parts = stream.currentOffset.split(`_`).map(Number);
+		const readSeq = parts[0];
+		const byteOffset = parts[1];
+		const newByteOffset = byteOffset + processedData.length;
+		const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+		const message = {
+			data: processedData,
+			offset: newOffset,
+			timestamp: Date.now()
+		};
+		stream.messages.push(message);
+		stream.currentOffset = newOffset;
+		return message;
+	}
+	findOffsetIndex(stream, offset) {
+		for (let i = 0; i < stream.messages.length; i++) if (stream.messages[i].offset > offset) return i;
+		return -1;
+	}
+	notifyLongPolls(path$2) {
+		const toNotify = this.pendingLongPolls.filter((p) => p.path === path$2);
+		for (const pending of toNotify) {
+			const { messages } = this.read(path$2, pending.offset);
+			if (messages.length > 0) pending.resolve(messages);
+		}
+	}
+	cancelLongPollsForStream(path$2) {
+		const toCancel = this.pendingLongPolls.filter((p) => p.path === path$2);
+		for (const pending of toCancel) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = this.pendingLongPolls.filter((p) => p.path !== path$2);
+	}
+	removePendingLongPoll(pending) {
+		const index = this.pendingLongPolls.indexOf(pending);
+		if (index !== -1) this.pendingLongPolls.splice(index, 1);
+	}
+};
+
+//#endregion
+//#region src/path-encoding.ts
+const MAX_ENCODED_LENGTH = 200;
+/**
+* Encode a stream path to a filesystem-safe directory name using base64url encoding.
+* Long paths (>200 chars) are hashed to keep directory names manageable.
+*
+* @example
+* encodeStreamPath("/stream/users:created") → "L3N0cmVhbS91c2VyczpjcmVhdGVk"
+*/
+function encodeStreamPath(path$2) {
+	const base64 = Buffer.from(path$2, `utf-8`).toString(`base64`).replace(/\+/g, `-`).replace(/\//g, `_`).replace(/=/g, ``);
+	if (base64.length > MAX_ENCODED_LENGTH) {
+		const hash = createHash(`sha256`).update(path$2).digest(`hex`).slice(0, 16);
+		return `${base64.slice(0, 180)}~${hash}`;
+	}
+	return base64;
+}
+/**
+* Decode a filesystem-safe directory name back to the original stream path.
+*
+* @example
+* decodeStreamPath("L3N0cmVhbS91c2VyczpjcmVhdGVk") → "/stream/users:created"
+*/
+function decodeStreamPath(encoded) {
+	let base = encoded;
+	const tildeIndex = encoded.lastIndexOf(`~`);
+	if (tildeIndex !== -1) {
+		const possibleHash = encoded.slice(tildeIndex + 1);
+		if (possibleHash.length === 16 && /^[0-9a-f]+$/.test(possibleHash)) base = encoded.slice(0, tildeIndex);
+	}
+	const normalized = base.replace(/-/g, `+`).replace(/_/g, `/`);
+	const padded = normalized + `=`.repeat((4 - normalized.length % 4) % 4);
+	return Buffer.from(padded, `base64`).toString(`utf-8`);
+}
+
+//#endregion
+//#region src/file-manager.ts
+var StreamFileManager = class {
+	constructor(streamsDir) {
+		this.streamsDir = streamsDir;
+	}
+	/**
+	* Create a directory for a new stream and initialize the first segment file.
+	* Returns the absolute path to the stream directory.
+	*/
+	async createStreamDirectory(streamPath) {
+		const encoded = encodeStreamPath(streamPath);
+		const dir = path$1.join(this.streamsDir, encoded);
+		await fs$1.mkdir(dir, { recursive: true });
+		const segmentPath = path$1.join(dir, `segment_00000.log`);
+		await fs$1.writeFile(segmentPath, ``);
+		return dir;
+	}
+	/**
+	* Delete a stream directory and all its contents.
+	*/
+	async deleteStreamDirectory(streamPath) {
+		const encoded = encodeStreamPath(streamPath);
+		const dir = path$1.join(this.streamsDir, encoded);
+		await fs$1.rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+	/**
+	* Delete a directory by its exact name (used for unique directory names).
+	*/
+	async deleteDirectoryByName(directoryName) {
+		const dir = path$1.join(this.streamsDir, directoryName);
+		await fs$1.rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+	/**
+	* Get the absolute path to a stream's directory.
+	* Returns null if the directory doesn't exist.
+	*/
+	async getStreamDirectory(streamPath) {
+		const encoded = encodeStreamPath(streamPath);
+		const dir = path$1.join(this.streamsDir, encoded);
+		try {
+			await fs$1.access(dir);
+			return dir;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* List all stream paths by scanning the streams directory.
+	*/
+	async listStreamPaths() {
+		try {
+			const entries = await fs$1.readdir(this.streamsDir, { withFileTypes: true });
+			return entries.filter((e) => e.isDirectory()).map((e) => decodeStreamPath(e.name));
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Get the path to a segment file within a stream directory.
+	*
+	* @param streamDir - Absolute path to the stream directory
+	* @param index - Segment index (0-based)
+	*/
+	getSegmentPath(streamDir, index) {
+		const paddedIndex = String(index).padStart(5, `0`);
+		return path$1.join(streamDir, `segment_${paddedIndex}.log`);
+	}
+};
+
+//#endregion
+//#region src/file-store.ts
+var FileHandlePool = class {
+	cache;
+	constructor(maxSize) {
+		this.cache = new SieveCache(maxSize, { evictHook: (_key, handle) => {
+			this.closeHandle(handle).catch((err) => {
+				console.error(`[FileHandlePool] Error closing evicted handle:`, err);
+			});
+		} });
+	}
+	getWriteStream(filePath) {
+		let handle = this.cache.get(filePath);
+		if (!handle) {
+			const stream = fs.createWriteStream(filePath, { flags: `a` });
+			handle = { stream };
+			this.cache.set(filePath, handle);
+		}
+		return handle.stream;
+	}
+	/**
+	* Flush a specific file to disk immediately.
+	* This is called after each append to ensure durability.
+	*/
+	async fsyncFile(filePath) {
+		const handle = this.cache.get(filePath);
+		if (!handle) return;
+		return new Promise((resolve, reject) => {
+			const fd = handle.stream.fd;
+			if (typeof fd !== `number`) {
+				const onOpen = (openedFd) => {
+					handle.stream.off(`error`, onError);
+					fs.fdatasync(openedFd, (err) => {
+						if (err) reject(err);
+						else resolve();
+					});
+				};
+				const onError = (err) => {
+					handle.stream.off(`open`, onOpen);
+					reject(err);
+				};
+				handle.stream.once(`open`, onOpen);
+				handle.stream.once(`error`, onError);
+				return;
+			}
+			fs.fdatasync(fd, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+	}
+	async closeAll() {
+		const promises = [];
+		for (const [_key, handle] of this.cache.entries()) promises.push(this.closeHandle(handle));
+		await Promise.all(promises);
+		this.cache.clear();
+	}
+	/**
+	* Close a specific file handle if it exists in the cache.
+	* Useful for cleanup before deleting files.
+	*/
+	async closeFileHandle(filePath) {
+		const handle = this.cache.get(filePath);
+		if (handle) {
+			await this.closeHandle(handle);
+			this.cache.delete(filePath);
+		}
+	}
+	async closeHandle(handle) {
+		return new Promise((resolve) => {
+			handle.stream.end(() => resolve());
+		});
+	}
+};
+/**
+* Generate a unique directory name for a stream.
+* Format: {encoded_path}~{timestamp}~{random_hex}
+* This allows safe async deletion and immediate reuse of stream paths.
+*/
+function generateUniqueDirectoryName(streamPath) {
+	const encoded = encodeStreamPath(streamPath);
+	const timestamp = Date.now().toString(36);
+	const random = randomBytes(4).toString(`hex`);
+	return `${encoded}~${timestamp}~${random}`;
+}
+/**
+* File-backed implementation of StreamStore.
+* Maintains the same interface as the in-memory StreamStore for drop-in compatibility.
+*/
+var FileBackedStreamStore = class {
+	db;
+	fileManager;
+	fileHandlePool;
+	pendingLongPolls = [];
+	dataDir;
+	constructor(options) {
+		this.dataDir = options.dataDir;
+		this.db = open({
+			path: path.join(this.dataDir, `metadata.lmdb`),
+			compression: true
+		});
+		this.fileManager = new StreamFileManager(path.join(this.dataDir, `streams`));
+		const maxFileHandles = options.maxFileHandles ?? 100;
+		this.fileHandlePool = new FileHandlePool(maxFileHandles);
+		this.recover();
+	}
+	/**
+	* Recover streams from disk on startup.
+	* Validates that LMDB metadata matches actual file contents and reconciles any mismatches.
+	*/
+	recover() {
+		console.log(`[FileBackedStreamStore] Starting recovery...`);
+		let recovered = 0;
+		let reconciled = 0;
+		let errors = 0;
+		const range = this.db.getRange({
+			start: `stream:`,
+			end: `stream:\xFF`
+		});
+		const entries = Array.from(range);
+		for (const { key, value } of entries) try {
+			if (typeof key !== `string`) continue;
+			const streamMeta = value;
+			const streamPath = key.replace(`stream:`, ``);
+			const segmentPath = path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+			if (!fs.existsSync(segmentPath)) {
+				console.warn(`[FileBackedStreamStore] Recovery: Stream file missing for ${streamPath}, removing from LMDB`);
+				this.db.removeSync(key);
+				errors++;
+				continue;
+			}
+			const trueOffset = this.scanFileForTrueOffset(segmentPath);
+			if (trueOffset !== streamMeta.currentOffset) {
+				console.warn(`[FileBackedStreamStore] Recovery: Offset mismatch for ${streamPath}: LMDB says ${streamMeta.currentOffset}, file says ${trueOffset}. Reconciling to file.`);
+				const reconciledMeta = {
+					...streamMeta,
+					currentOffset: trueOffset
+				};
+				this.db.putSync(key, reconciledMeta);
+				reconciled++;
+			}
+			recovered++;
+		} catch (err) {
+			console.error(`[FileBackedStreamStore] Error recovering stream:`, err);
+			errors++;
+		}
+		console.log(`[FileBackedStreamStore] Recovery complete: ${recovered} streams, ${reconciled} reconciled, ${errors} errors`);
+	}
+	/**
+	* Scan a segment file to compute the true last offset.
+	* Handles partial/truncated messages at the end.
+	*/
+	scanFileForTrueOffset(segmentPath) {
+		try {
+			const fileContent = fs.readFileSync(segmentPath);
+			let filePos = 0;
+			let currentDataOffset = 0;
+			while (filePos < fileContent.length) {
+				if (filePos + 4 > fileContent.length) break;
+				const messageLength = fileContent.readUInt32BE(filePos);
+				filePos += 4;
+				if (filePos + messageLength > fileContent.length) break;
+				filePos += messageLength;
+				if (filePos < fileContent.length) filePos += 1;
+				currentDataOffset += messageLength;
+			}
+			return `0000000000000000_${String(currentDataOffset).padStart(16, `0`)}`;
+		} catch (err) {
+			console.error(`[FileBackedStreamStore] Error scanning file ${segmentPath}:`, err);
+			return `0000000000000000_0000000000000000`;
+		}
+	}
+	/**
+	* Convert LMDB metadata to Stream object.
+	*/
+	streamMetaToStream(meta) {
+		return {
+			path: meta.path,
+			contentType: meta.contentType,
+			messages: [],
+			currentOffset: meta.currentOffset,
+			lastSeq: meta.lastSeq,
+			ttlSeconds: meta.ttlSeconds,
+			expiresAt: meta.expiresAt,
+			createdAt: meta.createdAt
+		};
+	}
+	/**
+	* Close the store, closing all file handles and database.
+	* All data is already fsynced on each append, so no final flush needed.
+	*/
+	async close() {
+		await this.fileHandlePool.closeAll();
+		await this.db.close();
+	}
+	async create(streamPath, options = {}) {
+		const key = `stream:${streamPath}`;
+		const existing = this.db.get(key);
+		if (existing) {
+			const normalizeMimeType = (ct) => (ct ?? `application/octet-stream`).toLowerCase();
+			const contentTypeMatches = normalizeMimeType(options.contentType) === normalizeMimeType(existing.contentType);
+			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
+			const expiresMatches = options.expiresAt === existing.expiresAt;
+			if (contentTypeMatches && ttlMatches && expiresMatches) return this.streamMetaToStream(existing);
+			else throw new Error(`Stream already exists with different configuration: ${streamPath}`);
+		}
+		const streamMeta = {
+			path: streamPath,
+			contentType: options.contentType,
+			currentOffset: `0000000000000000_0000000000000000`,
+			lastSeq: void 0,
+			ttlSeconds: options.ttlSeconds,
+			expiresAt: options.expiresAt,
+			createdAt: Date.now(),
+			segmentCount: 1,
+			totalBytes: 0,
+			directoryName: generateUniqueDirectoryName(streamPath)
+		};
+		const streamDir = path.join(this.dataDir, `streams`, streamMeta.directoryName);
+		try {
+			fs.mkdirSync(streamDir, { recursive: true });
+			const segmentPath = path.join(streamDir, `segment_00000.log`);
+			fs.writeFileSync(segmentPath, ``);
+		} catch (err) {
+			console.error(`[FileBackedStreamStore] Error creating stream directory:`, err);
+			throw err;
+		}
+		this.db.putSync(key, streamMeta);
+		if (options.initialData && options.initialData.length > 0) {
+			await this.append(streamPath, options.initialData, {
+				contentType: options.contentType,
+				isInitialCreate: true
+			});
+			const updated = this.db.get(key);
+			return this.streamMetaToStream(updated);
+		}
+		return this.streamMetaToStream(streamMeta);
+	}
+	get(streamPath) {
+		const key = `stream:${streamPath}`;
+		const meta = this.db.get(key);
+		return meta ? this.streamMetaToStream(meta) : void 0;
+	}
+	has(streamPath) {
+		const key = `stream:${streamPath}`;
+		return this.db.get(key) !== void 0;
+	}
+	delete(streamPath) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		if (!streamMeta) return false;
+		this.cancelLongPollsForStream(streamPath);
+		const segmentPath = path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+		this.fileHandlePool.closeFileHandle(segmentPath).catch((err) => {
+			console.error(`[FileBackedStreamStore] Error closing file handle:`, err);
+		});
+		this.db.removeSync(key);
+		this.fileManager.deleteDirectoryByName(streamMeta.directoryName).catch((err) => {
+			console.error(`[FileBackedStreamStore] Error deleting stream directory:`, err);
+		});
+		return true;
+	}
+	async append(streamPath, data, options = {}) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		if (options.contentType && streamMeta.contentType) {
+			const providedType = normalizeContentType(options.contentType);
+			const streamType = normalizeContentType(streamMeta.contentType);
+			if (providedType !== streamType) throw new Error(`Content-type mismatch: expected ${streamMeta.contentType}, got ${options.contentType}`);
+		}
+		if (options.seq !== void 0) {
+			if (streamMeta.lastSeq !== void 0 && options.seq <= streamMeta.lastSeq) throw new Error(`Sequence conflict: ${options.seq} <= ${streamMeta.lastSeq}`);
+		}
+		let processedData = data;
+		if (normalizeContentType(streamMeta.contentType) === `application/json`) {
+			processedData = processJsonAppend(data, options.isInitialCreate ?? false);
+			if (processedData.length === 0) return null;
+		}
+		const parts = streamMeta.currentOffset.split(`_`).map(Number);
+		const readSeq = parts[0];
+		const byteOffset = parts[1];
+		const newByteOffset = byteOffset + processedData.length;
+		const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+		const streamDir = path.join(this.dataDir, `streams`, streamMeta.directoryName);
+		const segmentPath = path.join(streamDir, `segment_00000.log`);
+		const stream = this.fileHandlePool.getWriteStream(segmentPath);
+		const lengthBuf = Buffer.allocUnsafe(4);
+		lengthBuf.writeUInt32BE(processedData.length, 0);
+		const frameBuf = Buffer.concat([
+			lengthBuf,
+			processedData,
+			Buffer.from(`\n`)
+		]);
+		await new Promise((resolve, reject) => {
+			stream.write(frameBuf, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+		const message = {
+			data: processedData,
+			offset: newOffset,
+			timestamp: Date.now()
+		};
+		await this.fileHandlePool.fsyncFile(segmentPath);
+		const updatedMeta = {
+			...streamMeta,
+			currentOffset: newOffset,
+			lastSeq: options.seq ?? streamMeta.lastSeq,
+			totalBytes: streamMeta.totalBytes + processedData.length + 5
+		};
+		this.db.putSync(key, updatedMeta);
+		this.notifyLongPolls(streamPath);
+		return message;
+	}
+	read(streamPath, offset) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		const startOffset = offset ?? `0000000000000000_0000000000000000`;
+		const startParts = startOffset.split(`_`).map(Number);
+		const startByte = startParts[1] ?? 0;
+		const currentParts = streamMeta.currentOffset.split(`_`).map(Number);
+		const currentSeq = currentParts[0] ?? 0;
+		const currentByte = currentParts[1] ?? 0;
+		if (streamMeta.currentOffset === `0000000000000000_0000000000000000`) return {
+			messages: [],
+			upToDate: true
+		};
+		if (startByte >= currentByte) return {
+			messages: [],
+			upToDate: true
+		};
+		const streamDir = path.join(this.dataDir, `streams`, streamMeta.directoryName);
+		const segmentPath = path.join(streamDir, `segment_00000.log`);
+		if (!fs.existsSync(segmentPath)) return {
+			messages: [],
+			upToDate: true
+		};
+		const messages = [];
+		try {
+			const fileContent = fs.readFileSync(segmentPath);
+			let filePos = 0;
+			let currentDataOffset = 0;
+			while (filePos < fileContent.length) {
+				if (filePos + 4 > fileContent.length) break;
+				const messageLength = fileContent.readUInt32BE(filePos);
+				filePos += 4;
+				if (filePos + messageLength > fileContent.length) break;
+				const messageData = fileContent.subarray(filePos, filePos + messageLength);
+				filePos += messageLength;
+				filePos += 1;
+				const messageOffset = currentDataOffset + messageLength;
+				if (messageOffset > startByte) messages.push({
+					data: new Uint8Array(messageData),
+					offset: `${String(currentSeq).padStart(16, `0`)}_${String(messageOffset).padStart(16, `0`)}`,
+					timestamp: 0
+				});
+				currentDataOffset = messageOffset;
+			}
+		} catch (err) {
+			console.error(`[FileBackedStreamStore] Error reading file:`, err);
+		}
+		return {
+			messages,
+			upToDate: true
+		};
+	}
+	async waitForMessages(streamPath, offset, timeoutMs) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		const { messages } = this.read(streamPath, offset);
+		if (messages.length > 0) return {
+			messages,
+			timedOut: false
+		};
+		return new Promise((resolve) => {
+			const timeoutId = setTimeout(() => {
+				this.removePendingLongPoll(pending);
+				resolve({
+					messages: [],
+					timedOut: true
+				});
+			}, timeoutMs);
+			const pending = {
+				path: streamPath,
+				offset,
+				resolve: (msgs) => {
+					clearTimeout(timeoutId);
+					this.removePendingLongPoll(pending);
+					resolve({
+						messages: msgs,
+						timedOut: false
+					});
+				},
+				timeoutId
+			};
+			this.pendingLongPolls.push(pending);
+		});
+	}
+	/**
+	* Format messages for response.
+	* For JSON mode, wraps concatenated data in array brackets.
+	*/
+	formatResponse(streamPath, messages) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
+		const concatenated = new Uint8Array(totalSize);
+		let offset = 0;
+		for (const msg of messages) {
+			concatenated.set(msg.data, offset);
+			offset += msg.data.length;
+		}
+		if (normalizeContentType(streamMeta.contentType) === `application/json`) return formatJsonResponse(concatenated);
+		return concatenated;
+	}
+	getCurrentOffset(streamPath) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		return streamMeta?.currentOffset;
+	}
+	clear() {
+		for (const pending of this.pendingLongPolls) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = [];
+		const range = this.db.getRange({
+			start: `stream:`,
+			end: `stream:\xFF`
+		});
+		const entries = Array.from(range);
+		for (const { key } of entries) this.db.removeSync(key);
+		this.fileHandlePool.closeAll().catch((err) => {
+			console.error(`[FileBackedStreamStore] Error closing handles:`, err);
+		});
+	}
+	/**
+	* Cancel all pending long-polls (used during shutdown).
+	*/
+	cancelAllWaits() {
+		for (const pending of this.pendingLongPolls) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = [];
+	}
+	list() {
+		const paths = [];
+		const range = this.db.getRange({
+			start: `stream:`,
+			end: `stream:\xFF`
+		});
+		const entries = Array.from(range);
+		for (const { key } of entries) if (typeof key === `string`) paths.push(key.replace(`stream:`, ``));
+		return paths;
+	}
+	notifyLongPolls(streamPath) {
+		const toNotify = this.pendingLongPolls.filter((p) => p.path === streamPath);
+		for (const pending of toNotify) {
+			const { messages } = this.read(streamPath, pending.offset);
+			if (messages.length > 0) pending.resolve(messages);
+		}
+	}
+	cancelLongPollsForStream(streamPath) {
+		const toCancel = this.pendingLongPolls.filter((p) => p.path === streamPath);
+		for (const pending of toCancel) {
+			clearTimeout(pending.timeoutId);
+			pending.resolve([]);
+		}
+		this.pendingLongPolls = this.pendingLongPolls.filter((p) => p.path !== streamPath);
+	}
+	removePendingLongPoll(pending) {
+		const index = this.pendingLongPolls.indexOf(pending);
+		if (index !== -1) this.pendingLongPolls.splice(index, 1);
+	}
+};
+
+//#endregion
+//#region src/cursor.ts
+/**
+* Stream cursor calculation for CDN cache collapsing.
+*
+* This module implements interval-based cursor generation to prevent
+* infinite CDN cache loops while enabling request collapsing.
+*
+* The mechanism works by:
+* 1. Dividing time into fixed intervals (default 20 seconds)
+* 2. Computing interval number from an epoch (October 9, 2024)
+* 3. Returning cursor values that change at interval boundaries
+* 4. Ensuring monotonic cursor progression (never going backwards)
+*/
+/**
+* Default epoch for cursor calculation: October 9, 2024 00:00:00 UTC.
+* This is the reference point from which intervals are counted.
+* Using a past date ensures cursors are always positive.
+*/
+const DEFAULT_CURSOR_EPOCH = new Date(`2024-10-09T00:00:00.000Z`);
+/**
+* Default interval duration in seconds.
+*/
+const DEFAULT_CURSOR_INTERVAL_SECONDS = 20;
+/**
+* Maximum jitter in seconds to add on collision.
+* Per protocol spec: random value between 1-3600 seconds.
+*/
+const MAX_JITTER_SECONDS = 3600;
+/**
+* Minimum jitter in seconds.
+*/
+const MIN_JITTER_SECONDS = 1;
+/**
+* Calculate the current cursor value based on time intervals.
+*
+* @param options - Configuration for cursor calculation
+* @returns The current cursor value as a string
+*/
+function calculateCursor(options = {}) {
+	const intervalSeconds = options.intervalSeconds ?? DEFAULT_CURSOR_INTERVAL_SECONDS;
+	const epoch = options.epoch ?? DEFAULT_CURSOR_EPOCH;
+	const now = Date.now();
+	const epochMs = epoch.getTime();
+	const intervalMs = intervalSeconds * 1e3;
+	const intervalNumber = Math.floor((now - epochMs) / intervalMs);
+	return String(intervalNumber);
+}
+/**
+* Generate a random jitter value in intervals.
+*
+* @param intervalSeconds - The interval duration in seconds
+* @returns Number of intervals to add as jitter
+*/
+function generateJitterIntervals(intervalSeconds) {
+	const jitterSeconds = MIN_JITTER_SECONDS + Math.floor(Math.random() * (MAX_JITTER_SECONDS - MIN_JITTER_SECONDS + 1));
+	return Math.max(1, Math.ceil(jitterSeconds / intervalSeconds));
+}
+/**
+* Generate a cursor for a response, ensuring monotonic progression.
+*
+* This function ensures the returned cursor is always greater than or equal
+* to the current time interval, and strictly greater than any client-provided
+* cursor. This prevents cache loops where a client could cycle between
+* cursor values.
+*
+* Algorithm:
+* - If no client cursor: return current interval
+* - If client cursor < current interval: return current interval
+* - If client cursor >= current interval: return client cursor + jitter
+*
+* This guarantees monotonic cursor progression and prevents A→B→A cycles.
+*
+* @param clientCursor - The cursor provided by the client (if any)
+* @param options - Configuration for cursor calculation
+* @returns The cursor value to include in the response
+*/
+function generateResponseCursor(clientCursor, options = {}) {
+	const intervalSeconds = options.intervalSeconds ?? DEFAULT_CURSOR_INTERVAL_SECONDS;
+	const currentCursor = calculateCursor(options);
+	const currentInterval = parseInt(currentCursor, 10);
+	if (!clientCursor) return currentCursor;
+	const clientInterval = parseInt(clientCursor, 10);
+	if (isNaN(clientInterval) || clientInterval < currentInterval) return currentCursor;
+	const jitterIntervals = generateJitterIntervals(intervalSeconds);
+	return String(clientInterval + jitterIntervals);
+}
+/**
+* Handle cursor collision by adding random jitter.
+*
+* @deprecated Use generateResponseCursor instead, which handles all cases
+* including monotonicity guarantees.
+*
+* @param currentCursor - The newly calculated cursor value
+* @param previousCursor - The cursor provided by the client (if any)
+* @param options - Configuration for cursor calculation
+* @returns The cursor value to return, with jitter applied if there's a collision
+*/
+function handleCursorCollision(currentCursor, previousCursor, options = {}) {
+	return generateResponseCursor(previousCursor, options);
+}
+
+//#endregion
+//#region src/server.ts
+const STREAM_OFFSET_HEADER = `Stream-Next-Offset`;
+const STREAM_CURSOR_HEADER = `Stream-Cursor`;
+const STREAM_UP_TO_DATE_HEADER = `Stream-Up-To-Date`;
+const STREAM_SEQ_HEADER = `Stream-Seq`;
+const STREAM_TTL_HEADER = `Stream-TTL`;
+const STREAM_EXPIRES_AT_HEADER = `Stream-Expires-At`;
+const SSE_OFFSET_FIELD = `streamNextOffset`;
+const SSE_CURSOR_FIELD = `streamCursor`;
+const SSE_UP_TO_DATE_FIELD = `upToDate`;
+const OFFSET_QUERY_PARAM = `offset`;
+const LIVE_QUERY_PARAM = `live`;
+const CURSOR_QUERY_PARAM = `cursor`;
+/**
+* Encode data for SSE format.
+* Per SSE spec, each line in the payload needs its own "data:" prefix.
+* Newlines in the payload become separate data: lines.
+*/
+function encodeSSEData(payload) {
+	const lines = payload.split(`\n`);
+	return lines.map((line) => `data: ${line}`).join(`\n`) + `\n\n`;
+}
+/**
+* Minimum response size to consider for compression.
+* Responses smaller than this won't benefit from compression.
+*/
+const COMPRESSION_THRESHOLD = 1024;
+/**
+* Determine the best compression encoding from Accept-Encoding header.
+* Returns 'gzip', 'deflate', or null if no compression should be used.
+*/
+function getCompressionEncoding(acceptEncoding) {
+	if (!acceptEncoding) return null;
+	const encodings = acceptEncoding.toLowerCase().split(`,`).map((e) => e.trim());
+	for (const encoding of encodings) {
+		const name = encoding.split(`;`)[0]?.trim();
+		if (name === `gzip`) return `gzip`;
+	}
+	for (const encoding of encodings) {
+		const name = encoding.split(`;`)[0]?.trim();
+		if (name === `deflate`) return `deflate`;
+	}
+	return null;
+}
+/**
+* Compress data using the specified encoding.
+*/
+function compressData(data, encoding) {
+	if (encoding === `gzip`) return gzipSync(data);
+	else return deflateSync(data);
+}
+var DurableStreamTestServer = class {
+	store;
+	server = null;
+	options;
+	_url = null;
+	activeSSEResponses = new Set();
+	isShuttingDown = false;
+	/** Injected errors for testing retry/resilience */
+	injectedErrors = new Map();
+	constructor(options = {}) {
+		if (options.dataDir) this.store = new FileBackedStreamStore({ dataDir: options.dataDir });
+		else this.store = new StreamStore();
+		this.options = {
+			port: options.port ?? 4437,
+			host: options.host ?? `127.0.0.1`,
+			longPollTimeout: options.longPollTimeout ?? 3e4,
+			dataDir: options.dataDir,
+			onStreamCreated: options.onStreamCreated,
+			onStreamDeleted: options.onStreamDeleted,
+			compression: options.compression ?? true,
+			cursorOptions: {
+				intervalSeconds: options.cursorIntervalSeconds,
+				epoch: options.cursorEpoch
+			}
+		};
+	}
+	/**
+	* Start the server.
+	*/
+	async start() {
+		if (this.server) throw new Error(`Server already started`);
+		return new Promise((resolve, reject) => {
+			this.server = createServer((req, res) => {
+				this.handleRequest(req, res).catch((err) => {
+					console.error(`Request error:`, err);
+					if (!res.headersSent) {
+						res.writeHead(500, { "content-type": `text/plain` });
+						res.end(`Internal server error`);
+					}
+				});
+			});
+			this.server.on(`error`, reject);
+			this.server.listen(this.options.port, this.options.host, () => {
+				const addr = this.server.address();
+				if (typeof addr === `string`) this._url = addr;
+				else if (addr) this._url = `http://${this.options.host}:${addr.port}`;
+				resolve(this._url);
+			});
+		});
+	}
+	/**
+	* Stop the server.
+	*/
+	async stop() {
+		if (!this.server) return;
+		this.isShuttingDown = true;
+		if (`cancelAllWaits` in this.store) this.store.cancelAllWaits();
+		for (const res of this.activeSSEResponses) res.end();
+		this.activeSSEResponses.clear();
+		return new Promise((resolve, reject) => {
+			this.server.close(async (err) => {
+				if (err) {
+					reject(err);
+					return;
+				}
+				try {
+					if (this.store instanceof FileBackedStreamStore) await this.store.close();
+					this.server = null;
+					this._url = null;
+					this.isShuttingDown = false;
+					resolve();
+				} catch (closeErr) {
+					reject(closeErr);
+				}
+			});
+		});
+	}
+	/**
+	* Get the server URL.
+	*/
+	get url() {
+		if (!this._url) throw new Error(`Server not started`);
+		return this._url;
+	}
+	/**
+	* Clear all streams.
+	*/
+	clear() {
+		this.store.clear();
+	}
+	/**
+	* Inject an error to be returned on the next N requests to a path.
+	* Used for testing retry/resilience behavior.
+	*/
+	injectError(path$2, status, count = 1, retryAfter) {
+		this.injectedErrors.set(path$2, {
+			status,
+			count,
+			retryAfter
+		});
+	}
+	/**
+	* Clear all injected errors.
+	*/
+	clearInjectedErrors() {
+		this.injectedErrors.clear();
+	}
+	/**
+	* Check if there's an injected error for this path and consume it.
+	* Returns the error config if one should be returned, null otherwise.
+	*/
+	consumeInjectedError(path$2) {
+		const error = this.injectedErrors.get(path$2);
+		if (!error) return null;
+		error.count--;
+		if (error.count <= 0) this.injectedErrors.delete(path$2);
+		return error;
+	}
+	async handleRequest(req, res) {
+		const url = new URL(req.url ?? `/`, `http://${req.headers.host}`);
+		const path$2 = url.pathname;
+		const method = req.method?.toUpperCase();
+		res.setHeader(`access-control-allow-origin`, `*`);
+		res.setHeader(`access-control-allow-methods`, `GET, POST, PUT, DELETE, HEAD, OPTIONS`);
+		res.setHeader(`access-control-allow-headers`, `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At`);
+		res.setHeader(`access-control-expose-headers`, `Stream-Next-Offset, Stream-Cursor, Stream-Up-To-Date, etag, content-type, content-encoding, vary`);
+		if (method === `OPTIONS`) {
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+		if (path$2 === `/_test/inject-error`) {
+			await this.handleTestInjectError(method, req, res);
+			return;
+		}
+		const injectedError = this.consumeInjectedError(path$2);
+		if (injectedError) {
+			const headers = { "content-type": `text/plain` };
+			if (injectedError.retryAfter !== void 0) headers[`retry-after`] = injectedError.retryAfter.toString();
+			res.writeHead(injectedError.status, headers);
+			res.end(`Injected error for testing`);
+			return;
+		}
+		try {
+			switch (method) {
+				case `PUT`:
+					await this.handleCreate(path$2, req, res);
+					break;
+				case `HEAD`:
+					this.handleHead(path$2, res);
+					break;
+				case `GET`:
+					await this.handleRead(path$2, url, req, res);
+					break;
+				case `POST`:
+					await this.handleAppend(path$2, req, res);
+					break;
+				case `DELETE`:
+					await this.handleDelete(path$2, res);
+					break;
+				default:
+					res.writeHead(405, { "content-type": `text/plain` });
+					res.end(`Method not allowed`);
+			}
+		} catch (err) {
+			if (err instanceof Error) if (err.message.includes(`not found`)) {
+				res.writeHead(404, { "content-type": `text/plain` });
+				res.end(`Stream not found`);
+			} else if (err.message.includes(`already exists with different configuration`)) {
+				res.writeHead(409, { "content-type": `text/plain` });
+				res.end(`Stream already exists with different configuration`);
+			} else if (err.message.includes(`Sequence conflict`)) {
+				res.writeHead(409, { "content-type": `text/plain` });
+				res.end(`Sequence conflict`);
+			} else if (err.message.includes(`Content-type mismatch`)) {
+				res.writeHead(409, { "content-type": `text/plain` });
+				res.end(`Content-type mismatch`);
+			} else if (err.message.includes(`Invalid JSON`)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid JSON`);
+			} else if (err.message.includes(`Empty arrays are not allowed`)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Empty arrays are not allowed`);
+			} else throw err;
+			else throw err;
+		}
+	}
+	/**
+	* Handle PUT - create stream
+	*/
+	async handleCreate(path$2, req, res) {
+		let contentType = req.headers[`content-type`];
+		if (!contentType || contentType.trim() === `` || !/^[\w-]+\/[\w-]+/.test(contentType)) contentType = `application/octet-stream`;
+		const ttlHeader = req.headers[STREAM_TTL_HEADER.toLowerCase()];
+		const expiresAtHeader = req.headers[STREAM_EXPIRES_AT_HEADER.toLowerCase()];
+		if (ttlHeader && expiresAtHeader) {
+			res.writeHead(400, { "content-type": `text/plain` });
+			res.end(`Cannot specify both Stream-TTL and Stream-Expires-At`);
+			return;
+		}
+		let ttlSeconds;
+		if (ttlHeader) {
+			const ttlPattern = /^(0|[1-9]\d*)$/;
+			if (!ttlPattern.test(ttlHeader)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-TTL value`);
+				return;
+			}
+			ttlSeconds = parseInt(ttlHeader, 10);
+			if (isNaN(ttlSeconds) || ttlSeconds < 0) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-TTL value`);
+				return;
+			}
+		}
+		if (expiresAtHeader) {
+			const timestamp = new Date(expiresAtHeader);
+			if (isNaN(timestamp.getTime())) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-Expires-At timestamp`);
+				return;
+			}
+		}
+		const body = await this.readBody(req);
+		const isNew = !this.store.has(path$2);
+		await Promise.resolve(this.store.create(path$2, {
+			contentType,
+			ttlSeconds,
+			expiresAt: expiresAtHeader,
+			initialData: body.length > 0 ? body : void 0
+		}));
+		const stream = this.store.get(path$2);
+		if (isNew && this.options.onStreamCreated) await Promise.resolve(this.options.onStreamCreated({
+			type: `created`,
+			path: path$2,
+			contentType,
+			timestamp: Date.now()
+		}));
+		const headers = {
+			"content-type": contentType,
+			[STREAM_OFFSET_HEADER]: stream.currentOffset
+		};
+		if (isNew) headers[`location`] = `${this._url}${path$2}`;
+		res.writeHead(isNew ? 201 : 200, headers);
+		res.end();
+	}
+	/**
+	* Handle HEAD - get metadata
+	*/
+	handleHead(path$2, res) {
+		const stream = this.store.get(path$2);
+		if (!stream) {
+			res.writeHead(404, { "content-type": `text/plain` });
+			res.end();
+			return;
+		}
+		const headers = { [STREAM_OFFSET_HEADER]: stream.currentOffset };
+		if (stream.contentType) headers[`content-type`] = stream.contentType;
+		headers[`etag`] = `"${Buffer.from(path$2).toString(`base64`)}:-1:${stream.currentOffset}"`;
+		res.writeHead(200, headers);
+		res.end();
+	}
+	/**
+	* Handle GET - read data
+	*/
+	async handleRead(path$2, url, req, res) {
+		const stream = this.store.get(path$2);
+		if (!stream) {
+			res.writeHead(404, { "content-type": `text/plain` });
+			res.end(`Stream not found`);
+			return;
+		}
+		const offset = url.searchParams.get(OFFSET_QUERY_PARAM) ?? void 0;
+		const live = url.searchParams.get(LIVE_QUERY_PARAM);
+		const cursor = url.searchParams.get(CURSOR_QUERY_PARAM) ?? void 0;
+		if (offset !== void 0) {
+			if (offset === ``) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Empty offset parameter`);
+				return;
+			}
+			const allOffsets = url.searchParams.getAll(OFFSET_QUERY_PARAM);
+			if (allOffsets.length > 1) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Multiple offset parameters not allowed`);
+				return;
+			}
+			const validOffsetPattern = /^(-1|\d+_\d+)$/;
+			if (!validOffsetPattern.test(offset)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid offset format`);
+				return;
+			}
+		}
+		if ((live === `long-poll` || live === `sse`) && !offset) {
+			res.writeHead(400, { "content-type": `text/plain` });
+			res.end(`${live === `sse` ? `SSE` : `Long-poll`} requires offset parameter`);
+			return;
+		}
+		if (live === `sse`) {
+			await this.handleSSE(path$2, stream, offset, cursor, res);
+			return;
+		}
+		let { messages, upToDate } = this.store.read(path$2, offset);
+		const clientIsCaughtUp = offset && offset === stream.currentOffset;
+		if (live === `long-poll` && clientIsCaughtUp && messages.length === 0) {
+			const result = await this.store.waitForMessages(path$2, offset, this.options.longPollTimeout);
+			if (result.timedOut) {
+				const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
+				res.writeHead(204, {
+					[STREAM_OFFSET_HEADER]: offset,
+					[STREAM_UP_TO_DATE_HEADER]: `true`,
+					[STREAM_CURSOR_HEADER]: responseCursor
+				});
+				res.end();
+				return;
+			}
+			messages = result.messages;
+			upToDate = true;
+		}
+		const headers = {};
+		if (stream.contentType) headers[`content-type`] = stream.contentType;
+		const lastMessage = messages[messages.length - 1];
+		const responseOffset = lastMessage?.offset ?? stream.currentOffset;
+		headers[STREAM_OFFSET_HEADER] = responseOffset;
+		if (live === `long-poll`) headers[STREAM_CURSOR_HEADER] = generateResponseCursor(cursor, this.options.cursorOptions);
+		if (upToDate) headers[STREAM_UP_TO_DATE_HEADER] = `true`;
+		const startOffset = offset ?? `-1`;
+		const etag = `"${Buffer.from(path$2).toString(`base64`)}:${startOffset}:${responseOffset}"`;
+		headers[`etag`] = etag;
+		const ifNoneMatch = req.headers[`if-none-match`];
+		if (ifNoneMatch && ifNoneMatch === etag) {
+			res.writeHead(304, { etag });
+			res.end();
+			return;
+		}
+		const responseData = this.store.formatResponse(path$2, messages);
+		let finalData = responseData;
+		if (this.options.compression && responseData.length >= COMPRESSION_THRESHOLD) {
+			const acceptEncoding = req.headers[`accept-encoding`];
+			const encoding = getCompressionEncoding(acceptEncoding);
+			if (encoding) {
+				finalData = compressData(responseData, encoding);
+				headers[`content-encoding`] = encoding;
+				headers[`vary`] = `accept-encoding`;
+			}
+		}
+		res.writeHead(200, headers);
+		res.end(Buffer.from(finalData));
+	}
+	/**
+	* Handle SSE (Server-Sent Events) mode
+	*/
+	async handleSSE(path$2, stream, initialOffset, cursor, res) {
+		this.activeSSEResponses.add(res);
+		res.writeHead(200, {
+			"content-type": `text/event-stream`,
+			"cache-control": `no-cache`,
+			connection: `keep-alive`,
+			"access-control-allow-origin": `*`
+		});
+		let currentOffset = initialOffset;
+		let isConnected = true;
+		const decoder = new TextDecoder();
+		res.on(`close`, () => {
+			isConnected = false;
+			this.activeSSEResponses.delete(res);
+		});
+		const isJsonStream = stream?.contentType?.includes(`application/json`);
+		while (isConnected && !this.isShuttingDown) {
+			const { messages, upToDate } = this.store.read(path$2, currentOffset);
+			for (const message of messages) {
+				let dataPayload;
+				if (isJsonStream) {
+					const jsonBytes = this.store.formatResponse(path$2, [message]);
+					dataPayload = decoder.decode(jsonBytes);
+				} else dataPayload = decoder.decode(message.data);
+				res.write(`event: data\n`);
+				res.write(encodeSSEData(dataPayload));
+				currentOffset = message.offset;
+			}
+			const controlOffset = messages[messages.length - 1]?.offset ?? stream.currentOffset;
+			const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
+			const controlData = {
+				[SSE_OFFSET_FIELD]: controlOffset,
+				[SSE_CURSOR_FIELD]: responseCursor
+			};
+			if (upToDate) controlData[SSE_UP_TO_DATE_FIELD] = true;
+			res.write(`event: control\n`);
+			res.write(encodeSSEData(JSON.stringify(controlData)));
+			currentOffset = controlOffset;
+			if (upToDate) {
+				const result = await this.store.waitForMessages(path$2, currentOffset, this.options.longPollTimeout);
+				if (this.isShuttingDown || !isConnected) break;
+				if (result.timedOut) {
+					const keepAliveCursor = generateResponseCursor(cursor, this.options.cursorOptions);
+					const keepAliveData = {
+						[SSE_OFFSET_FIELD]: currentOffset,
+						[SSE_CURSOR_FIELD]: keepAliveCursor,
+						[SSE_UP_TO_DATE_FIELD]: true
+					};
+					res.write(`event: control\n`);
+					res.write(encodeSSEData(JSON.stringify(keepAliveData)));
+				}
+			}
+		}
+		this.activeSSEResponses.delete(res);
+		res.end();
+	}
+	/**
+	* Handle POST - append data
+	*/
+	async handleAppend(path$2, req, res) {
+		const contentType = req.headers[`content-type`];
+		const seq = req.headers[STREAM_SEQ_HEADER.toLowerCase()];
+		const body = await this.readBody(req);
+		if (body.length === 0) {
+			res.writeHead(400, { "content-type": `text/plain` });
+			res.end(`Empty body`);
+			return;
+		}
+		if (!contentType) {
+			res.writeHead(400, { "content-type": `text/plain` });
+			res.end(`Content-Type header is required`);
+			return;
+		}
+		const message = await Promise.resolve(this.store.append(path$2, body, {
+			seq,
+			contentType
+		}));
+		res.writeHead(200, { [STREAM_OFFSET_HEADER]: message.offset });
+		res.end();
+	}
+	/**
+	* Handle DELETE - delete stream
+	*/
+	async handleDelete(path$2, res) {
+		if (!this.store.has(path$2)) {
+			res.writeHead(404, { "content-type": `text/plain` });
+			res.end(`Stream not found`);
+			return;
+		}
+		this.store.delete(path$2);
+		if (this.options.onStreamDeleted) await Promise.resolve(this.options.onStreamDeleted({
+			type: `deleted`,
+			path: path$2,
+			timestamp: Date.now()
+		}));
+		res.writeHead(204);
+		res.end();
+	}
+	/**
+	* Handle test control endpoints for error injection.
+	* POST /_test/inject-error - inject an error
+	* DELETE /_test/inject-error - clear all injected errors
+	*/
+	async handleTestInjectError(method, req, res) {
+		if (method === `POST`) {
+			const body = await this.readBody(req);
+			try {
+				const config = JSON.parse(new TextDecoder().decode(body));
+				if (!config.path || !config.status) {
+					res.writeHead(400, { "content-type": `text/plain` });
+					res.end(`Missing required fields: path, status`);
+					return;
+				}
+				this.injectError(config.path, config.status, config.count ?? 1, config.retryAfter);
+				res.writeHead(200, { "content-type": `application/json` });
+				res.end(JSON.stringify({ ok: true }));
+			} catch {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid JSON body`);
+			}
+		} else if (method === `DELETE`) {
+			this.clearInjectedErrors();
+			res.writeHead(200, { "content-type": `application/json` });
+			res.end(JSON.stringify({ ok: true }));
+		} else {
+			res.writeHead(405, { "content-type": `text/plain` });
+			res.end(`Method not allowed`);
+		}
+	}
+	readBody(req) {
+		return new Promise((resolve, reject) => {
+			const chunks = [];
+			req.on(`data`, (chunk) => {
+				chunks.push(chunk);
+			});
+			req.on(`end`, () => {
+				const body = Buffer.concat(chunks);
+				resolve(new Uint8Array(body));
+			});
+			req.on(`error`, reject);
+		});
+	}
+};
+
+//#endregion
+//#region src/registry-hook.ts
+const REGISTRY_PATH = `/v1/stream/__registry__`;
+const streamMetadataSchema = { "~standard": {
+	version: 1,
+	vendor: `durable-streams`,
+	validate: (value) => {
+		if (typeof value !== `object` || value === null) return { issues: [{ message: `value must be an object` }] };
+		const data = value;
+		if (typeof data.path !== `string` || data.path.length === 0) return { issues: [{ message: `path must be a non-empty string` }] };
+		if (typeof data.contentType !== `string` || data.contentType.length === 0) return { issues: [{ message: `contentType must be a non-empty string` }] };
+		if (typeof data.createdAt !== `number`) return { issues: [{ message: `createdAt must be a number` }] };
+		return { value: data };
+	}
+} };
+const registryStateSchema = createStateSchema({ streams: {
+	schema: streamMetadataSchema,
+	type: `stream`,
+	primaryKey: `path`
+} });
+/**
+* Creates lifecycle hooks that write to a __registry__ stream.
+* Any client can read this stream to discover all streams and their lifecycle events.
+*/
+function createRegistryHooks(store, serverUrl) {
+	const registryStream = new DurableStream({
+		url: `${serverUrl}${REGISTRY_PATH}`,
+		contentType: `application/json`
+	});
+	const ensureRegistryExists = async () => {
+		if (!store.has(REGISTRY_PATH)) await DurableStream.create({
+			url: `${serverUrl}${REGISTRY_PATH}`,
+			contentType: `application/json`
+		});
+	};
+	const extractStreamName = (fullPath) => {
+		return fullPath.replace(/^\/v1\/stream\//, ``);
+	};
+	return {
+		onStreamCreated: async (event) => {
+			await ensureRegistryExists();
+			const streamName = extractStreamName(event.path);
+			const changeEvent = registryStateSchema.streams.insert({
+				key: streamName,
+				value: {
+					path: streamName,
+					contentType: event.contentType || `application/octet-stream`,
+					createdAt: event.timestamp
+				}
+			});
+			await registryStream.append(changeEvent);
+		},
+		onStreamDeleted: async (event) => {
+			await ensureRegistryExists();
+			const streamName = extractStreamName(event.path);
+			const changeEvent = registryStateSchema.streams.delete({ key: streamName });
+			await registryStream.append(changeEvent);
+		}
+	};
+}
+
+//#endregion
+export { DEFAULT_CURSOR_EPOCH, DEFAULT_CURSOR_INTERVAL_SECONDS, DurableStreamTestServer, FileBackedStreamStore, StreamStore, calculateCursor, createRegistryHooks, decodeStreamPath, encodeStreamPath, generateResponseCursor, handleCursorCollision };