@durable-streams/client-conformance-tests 0.1.1 → 0.1.2

package/dist/protocol-3cf94Xyb.d.cts

@@ -0,0 +1,472 @@
+//#region src/protocol.d.ts
+/**
+* Protocol types for client conformance testing.
+*
+* This module defines the stdin/stdout protocol used for communication
+* between the test runner and client adapters in any language.
+*
+* Communication is line-based JSON over stdin/stdout:
+* - Test runner writes TestCommand as JSON line to client's stdin
+* - Client writes TestResult as JSON line to stdout
+* - Each command expects exactly one result
+*/
+/**
+* Initialize the client adapter with configuration.
+* Must be the first command sent.
+*/
+interface InitCommand {
+  type: `init`;
+  /** Base URL of the reference server */
+  serverUrl: string;
+  /** Optional timeout in milliseconds for operations */
+  timeoutMs?: number;
+}
+/**
+* Create a new stream (PUT request).
+*/
+interface CreateCommand {
+  type: `create`;
+  /** Full URL path for the stream (relative to serverUrl) */
+  path: string;
+  /** Content type for the stream */
+  contentType?: string;
+  /** Optional TTL in seconds */
+  ttlSeconds?: number;
+  /** Optional absolute expiry timestamp (ISO 8601) */
+  expiresAt?: string;
+  /** Custom headers to include */
+  headers?: Record<string, string>;
+}
+/**
+* Connect to an existing stream without creating it.
+*/
+interface ConnectCommand {
+  type: `connect`;
+  path: string;
+  headers?: Record<string, string>;
+}
+/**
+* Append data to a stream (POST request).
+*/
+interface AppendCommand {
+  type: `append`;
+  path: string;
+  /** Data to append - string for text, base64 for binary */
+  data: string;
+  /** Whether data is base64 encoded binary */
+  binary?: boolean;
+  /** Optional sequence number for ordering */
+  seq?: number;
+  /** Custom headers to include */
+  headers?: Record<string, string>;
+}
+/**
+* Read from a stream (GET request).
+*/
+interface ReadCommand {
+  type: `read`;
+  path: string;
+  /** Starting offset (opaque string from previous reads) */
+  offset?: string;
+  /** Live mode: false for catch-up only, "long-poll" or "sse" for live */
+  live?: false | `long-poll` | `sse`;
+  /** Timeout for long-poll in milliseconds */
+  timeoutMs?: number;
+  /** Maximum number of chunks to read (for testing) */
+  maxChunks?: number;
+  /** Whether to wait until up-to-date before returning */
+  waitForUpToDate?: boolean;
+  /** Custom headers to include */
+  headers?: Record<string, string>;
+}
+/**
+* Get stream metadata (HEAD request).
+*/
+interface HeadCommand {
+  type: `head`;
+  path: string;
+  headers?: Record<string, string>;
+}
+/**
+* Delete a stream (DELETE request).
+*/
+interface DeleteCommand {
+  type: `delete`;
+  path: string;
+  headers?: Record<string, string>;
+}
+/**
+* Shutdown the client adapter gracefully.
+*/
+interface ShutdownCommand {
+  type: `shutdown`;
+}
+/**
+* Configure a dynamic header that is evaluated per-request.
+* The adapter should store this and apply it to subsequent operations.
+*
+* This tests the client's ability to support header functions for scenarios
+* like OAuth token refresh, request correlation IDs, etc.
+*/
+interface SetDynamicHeaderCommand {
+  type: `set-dynamic-header`;
+  /** Header name to set */
+  name: string;
+  /** Type of dynamic value */
+  valueType: `counter` | `timestamp` | `token`;
+  /** Initial value (for token type) */
+  initialValue?: string;
+}
+/**
+* Configure a dynamic URL parameter that is evaluated per-request.
+*/
+interface SetDynamicParamCommand {
+  type: `set-dynamic-param`;
+  /** Param name to set */
+  name: string;
+  /** Type of dynamic value */
+  valueType: `counter` | `timestamp`;
+}
+/**
+* Clear all dynamic headers and params.
+*/
+interface ClearDynamicCommand {
+  type: `clear-dynamic`;
+}
+/**
+* Execute a timed benchmark operation.
+* The adapter times the operation internally using high-resolution timing.
+*/
+interface BenchmarkCommand {
+  type: `benchmark`;
+  /** Unique ID for this benchmark iteration */
+  iterationId: string;
+  /** The operation to benchmark */
+  operation: BenchmarkOperation;
+}
+/**
+* Benchmark operation types - what to measure.
+*/
+type BenchmarkOperation = BenchmarkAppendOp | BenchmarkReadOp | BenchmarkRoundtripOp | BenchmarkCreateOp | BenchmarkThroughputAppendOp | BenchmarkThroughputReadOp;
+interface BenchmarkAppendOp {
+  op: `append`;
+  path: string;
+  /** Size in bytes - adapter generates random payload */
+  size: number;
+}
+interface BenchmarkReadOp {
+  op: `read`;
+  path: string;
+  offset?: string;
+}
+interface BenchmarkRoundtripOp {
+  op: `roundtrip`;
+  path: string;
+  /** Size in bytes */
+  size: number;
+  /** Live mode for reading */
+  live?: `long-poll` | `sse`;
+  /** Content type for SSE compatibility */
+  contentType?: string;
+}
+interface BenchmarkCreateOp {
+  op: `create`;
+  path: string;
+  contentType?: string;
+}
+interface BenchmarkThroughputAppendOp {
+  op: `throughput_append`;
+  path: string;
+  /** Number of messages to send */
+  count: number;
+  /** Size per message in bytes */
+  size: number;
+  /** Concurrency level */
+  concurrency: number;
+}
+interface BenchmarkThroughputReadOp {
+  op: `throughput_read`;
+  path: string;
+  /** Expected number of JSON messages to read and parse */
+  expectedCount?: number;
+}
+/**
+* All possible commands from test runner to client.
+*/
+type TestCommand = InitCommand | CreateCommand | ConnectCommand | AppendCommand | ReadCommand | HeadCommand | DeleteCommand | ShutdownCommand | SetDynamicHeaderCommand | SetDynamicParamCommand | ClearDynamicCommand | BenchmarkCommand;
+/**
+* Successful initialization result.
+*/
+interface InitResult {
+  type: `init`;
+  success: true;
+  /** Client implementation name (e.g., "typescript", "python", "go") */
+  clientName: string;
+  /** Client implementation version */
+  clientVersion: string;
+  /** Supported features */
+  features?: {
+    /** Supports automatic batching */
+    batching?: boolean;
+    /** Supports SSE mode */
+    sse?: boolean;
+    /** Supports long-poll mode */
+    longPoll?: boolean;
+    /** Supports streaming reads */
+    streaming?: boolean;
+    /** Supports dynamic headers/params (functions evaluated per-request) */
+    dynamicHeaders?: boolean;
+  };
+}
+/**
+* Successful create result.
+*/
+interface CreateResult {
+  type: `create`;
+  success: true;
+  /** HTTP status code received */
+  status: number;
+  /** Stream offset after creation */
+  offset?: string;
+  /** Response headers of interest */
+  headers?: Record<string, string>;
+}
+/**
+* Successful connect result.
+*/
+interface ConnectResult {
+  type: `connect`;
+  success: true;
+  status: number;
+  offset?: string;
+  headers?: Record<string, string>;
+}
+/**
+* Successful append result.
+*/
+interface AppendResult {
+  type: `append`;
+  success: true;
+  status: number;
+  /** New offset after append */
+  offset?: string;
+  /** Response headers */
+  headers?: Record<string, string>;
+  /** Headers that were sent in the request (for dynamic header testing) */
+  headersSent?: Record<string, string>;
+  /** Params that were sent in the request (for dynamic param testing) */
+  paramsSent?: Record<string, string>;
+}
+/**
+* A chunk of data read from the stream.
+*/
+interface ReadChunk {
+  /** Data content - string for text, base64 for binary */
+  data: string;
+  /** Whether data is base64 encoded */
+  binary?: boolean;
+  /** Offset of this chunk */
+  offset?: string;
+}
+/**
+* Successful read result.
+*/
+interface ReadResult {
+  type: `read`;
+  success: true;
+  status: number;
+  /** Chunks of data read */
+  chunks: Array<ReadChunk>;
+  /** Final offset after reading */
+  offset?: string;
+  /** Whether stream is up-to-date (caught up to head) */
+  upToDate?: boolean;
+  /** Cursor value if provided */
+  cursor?: string;
+  /** Response headers */
+  headers?: Record<string, string>;
+  /** Headers that were sent in the request (for dynamic header testing) */
+  headersSent?: Record<string, string>;
+  /** Params that were sent in the request (for dynamic param testing) */
+  paramsSent?: Record<string, string>;
+}
+/**
+* Successful head result.
+*/
+interface HeadResult {
+  type: `head`;
+  success: true;
+  status: number;
+  /** Current tail offset */
+  offset?: string;
+  /** Stream content type */
+  contentType?: string;
+  /** TTL remaining in seconds */
+  ttlSeconds?: number;
+  /** Absolute expiry (ISO 8601) */
+  expiresAt?: string;
+  headers?: Record<string, string>;
+}
+/**
+* Successful delete result.
+*/
+interface DeleteResult {
+  type: `delete`;
+  success: true;
+  status: number;
+  headers?: Record<string, string>;
+}
+/**
+* Successful shutdown result.
+*/
+interface ShutdownResult {
+  type: `shutdown`;
+  success: true;
+}
+/**
+* Successful set-dynamic-header result.
+*/
+interface SetDynamicHeaderResult {
+  type: `set-dynamic-header`;
+  success: true;
+}
+/**
+* Successful set-dynamic-param result.
+*/
+interface SetDynamicParamResult {
+  type: `set-dynamic-param`;
+  success: true;
+}
+/**
+* Successful clear-dynamic result.
+*/
+interface ClearDynamicResult {
+  type: `clear-dynamic`;
+  success: true;
+}
+/**
+* Successful benchmark result with timing.
+*/
+interface BenchmarkResult {
+  type: `benchmark`;
+  success: true;
+  iterationId: string;
+  /** Timing in nanoseconds (as string since bigint doesn't JSON serialize) */
+  durationNs: string;
+  /** Optional metrics */
+  metrics?: {
+    /** Bytes transferred */
+    bytesTransferred?: number;
+    /** Messages processed */
+    messagesProcessed?: number;
+    /** Operations per second (for throughput tests) */
+    opsPerSecond?: number;
+    /** Bytes per second (for throughput tests) */
+    bytesPerSecond?: number;
+  };
+}
+/**
+* Error result for any failed operation.
+*/
+interface ErrorResult {
+  type: `error`;
+  success: false;
+  /** Original command type that failed */
+  commandType: TestCommand[`type`];
+  /** HTTP status code if available */
+  status?: number;
+  /** Error code (e.g., "NETWORK_ERROR", "TIMEOUT", "CONFLICT") */
+  errorCode: string;
+  /** Human-readable error message */
+  message: string;
+  /** Additional error details */
+  details?: Record<string, unknown>;
+}
+/**
+* All possible results from client to test runner.
+*/
+type TestResult = InitResult | CreateResult | ConnectResult | AppendResult | ReadResult | HeadResult | DeleteResult | ShutdownResult | SetDynamicHeaderResult | SetDynamicParamResult | ClearDynamicResult | BenchmarkResult | ErrorResult;
+/**
+* Parse a JSON line into a TestCommand.
+*/
+declare function parseCommand(line: string): TestCommand;
+/**
+* Serialize a TestResult to a JSON line.
+*/
+declare function serializeResult(result: TestResult): string;
+/**
+* Parse a JSON line into a TestResult.
+*/
+declare function parseResult(line: string): TestResult;
+/**
+* Serialize a TestCommand to a JSON line.
+*/
+declare function serializeCommand(command: TestCommand): string;
+/**
+* Encode binary data to base64 for transmission.
+*/
+declare function encodeBase64(data: Uint8Array): string;
+/**
+* Decode base64 string back to binary data.
+*/
+declare function decodeBase64(encoded: string): Uint8Array;
+/**
+* Standard error codes for ErrorResult.
+*/
+declare const ErrorCodes: {
+  /** Network connection failed */
+  readonly NETWORK_ERROR: "NETWORK_ERROR";
+  /** Operation timed out */
+  readonly TIMEOUT: "TIMEOUT";
+  /** Stream already exists (409 Conflict) */
+  readonly CONFLICT: "CONFLICT";
+  /** Stream not found (404) */
+  readonly NOT_FOUND: "NOT_FOUND";
+  /** Sequence number conflict (409) */
+  readonly SEQUENCE_CONFLICT: "SEQUENCE_CONFLICT";
+  /** Invalid offset format */
+  readonly INVALID_OFFSET: "INVALID_OFFSET";
+  /** Server returned unexpected status */
+  readonly UNEXPECTED_STATUS: "UNEXPECTED_STATUS";
+  /** Failed to parse response */
+  readonly PARSE_ERROR: "PARSE_ERROR";
+  /** Client internal error */
+  readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+  /** Operation not supported by this client */
+  readonly NOT_SUPPORTED: "NOT_SUPPORTED";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+* Statistical summary of benchmark results.
+*/
+interface BenchmarkStats {
+  /** Minimum value in milliseconds */
+  min: number;
+  /** Maximum value in milliseconds */
+  max: number;
+  /** Arithmetic mean in milliseconds */
+  mean: number;
+  /** Median (p50) in milliseconds */
+  median: number;
+  /** 75th percentile in milliseconds */
+  p75: number;
+  /** 95th percentile in milliseconds */
+  p95: number;
+  /** 99th percentile in milliseconds */
+  p99: number;
+  /** Standard deviation in milliseconds */
+  stdDev: number;
+  /** Margin of error (95% confidence) in milliseconds */
+  marginOfError: number;
+  /** Number of samples */
+  sampleCount: number;
+}
+/**
+* Calculate statistics from an array of durations in nanoseconds.
+*/
+declare function calculateStats(durationsNs: Array<bigint>): BenchmarkStats;
+/**
+* Format a BenchmarkStats object for display.
+*/
+declare function formatStats(stats: BenchmarkStats, unit?: string): Record<string, string>; //#endregion
+export { AppendCommand, AppendResult, BenchmarkAppendOp, BenchmarkCommand, BenchmarkCreateOp, BenchmarkOperation, BenchmarkReadOp, BenchmarkResult, BenchmarkRoundtripOp, BenchmarkStats, BenchmarkThroughputAppendOp, BenchmarkThroughputReadOp, ClearDynamicCommand, ClearDynamicResult, ConnectCommand, ConnectResult, CreateCommand, CreateResult, DeleteCommand, DeleteResult, ErrorCode, ErrorCodes, ErrorResult, HeadCommand, HeadResult, InitCommand, InitResult, ReadChunk, ReadCommand, ReadResult, SetDynamicHeaderCommand, SetDynamicHeaderResult, SetDynamicParamCommand, SetDynamicParamResult, ShutdownCommand, ShutdownResult, TestCommand, TestResult, calculateStats, decodeBase64, encodeBase64, formatStats, parseCommand, parseResult, serializeCommand, serializeResult };

package/dist/protocol-XeAOKBD-.cjs

@@ -0,0 +1,175 @@
+"use strict";
+
+//#region src/protocol.ts
+/**
+* Parse a JSON line into a TestCommand.
+*/
+function parseCommand(line) {
+	return JSON.parse(line);
+}
+/**
+* Serialize a TestResult to a JSON line.
+*/
+function serializeResult(result) {
+	return JSON.stringify(result);
+}
+/**
+* Parse a JSON line into a TestResult.
+*/
+function parseResult(line) {
+	return JSON.parse(line);
+}
+/**
+* Serialize a TestCommand to a JSON line.
+*/
+function serializeCommand(command) {
+	return JSON.stringify(command);
+}
+/**
+* Encode binary data to base64 for transmission.
+*/
+function encodeBase64(data) {
+	return Buffer.from(data).toString(`base64`);
+}
+/**
+* Decode base64 string back to binary data.
+*/
+function decodeBase64(encoded) {
+	return new Uint8Array(Buffer.from(encoded, `base64`));
+}
+/**
+* Standard error codes for ErrorResult.
+*/
+const ErrorCodes = {
+	NETWORK_ERROR: `NETWORK_ERROR`,
+	TIMEOUT: `TIMEOUT`,
+	CONFLICT: `CONFLICT`,
+	NOT_FOUND: `NOT_FOUND`,
+	SEQUENCE_CONFLICT: `SEQUENCE_CONFLICT`,
+	INVALID_OFFSET: `INVALID_OFFSET`,
+	UNEXPECTED_STATUS: `UNEXPECTED_STATUS`,
+	PARSE_ERROR: `PARSE_ERROR`,
+	INTERNAL_ERROR: `INTERNAL_ERROR`,
+	NOT_SUPPORTED: `NOT_SUPPORTED`
+};
+/**
+* Calculate statistics from an array of durations in nanoseconds.
+*/
+function calculateStats(durationsNs) {
+	if (durationsNs.length === 0) return {
+		min: 0,
+		max: 0,
+		mean: 0,
+		median: 0,
+		p75: 0,
+		p95: 0,
+		p99: 0,
+		stdDev: 0,
+		marginOfError: 0,
+		sampleCount: 0
+	};
+	const samplesMs = durationsNs.map((ns) => Number(ns) / 1e6);
+	const sorted = [...samplesMs].sort((a, b) => a - b);
+	const n = sorted.length;
+	const min = sorted[0];
+	const max = sorted[n - 1];
+	const mean = samplesMs.reduce((a, b) => a + b, 0) / n;
+	const percentile = (p) => {
+		const idx = Math.floor((n - 1) * p);
+		return sorted[idx];
+	};
+	const median = percentile(.5);
+	const p75 = percentile(.75);
+	const p95 = percentile(.95);
+	const p99 = percentile(.99);
+	const squaredDiffs = samplesMs.map((v) => Math.pow(v - mean, 2));
+	const variance = squaredDiffs.reduce((a, b) => a + b, 0) / n;
+	const stdDev = Math.sqrt(variance);
+	const marginOfError = 1.96 * stdDev / Math.sqrt(n);
+	return {
+		min,
+		max,
+		mean,
+		median,
+		p75,
+		p95,
+		p99,
+		stdDev,
+		marginOfError,
+		sampleCount: n
+	};
+}
+/**
+* Format a BenchmarkStats object for display.
+*/
+function formatStats(stats, unit = `ms`) {
+	const fmt = (v) => `${v.toFixed(2)} ${unit}`;
+	return {
+		Min: fmt(stats.min),
+		Max: fmt(stats.max),
+		Mean: fmt(stats.mean),
+		Median: fmt(stats.median),
+		P75: fmt(stats.p75),
+		P95: fmt(stats.p95),
+		P99: fmt(stats.p99),
+		StdDev: fmt(stats.stdDev),
+		"Margin of Error": fmt(stats.marginOfError),
+		Samples: stats.sampleCount.toString()
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'ErrorCodes', {
+  enumerable: true,
+  get: function () {
+    return ErrorCodes;
+  }
+});
+Object.defineProperty(exports, 'calculateStats', {
+  enumerable: true,
+  get: function () {
+    return calculateStats;
+  }
+});
+Object.defineProperty(exports, 'decodeBase64', {
+  enumerable: true,
+  get: function () {
+    return decodeBase64;
+  }
+});
+Object.defineProperty(exports, 'encodeBase64', {
+  enumerable: true,
+  get: function () {
+    return encodeBase64;
+  }
+});
+Object.defineProperty(exports, 'formatStats', {
+  enumerable: true,
+  get: function () {
+    return formatStats;
+  }
+});
+Object.defineProperty(exports, 'parseCommand', {
+  enumerable: true,
+  get: function () {
+    return parseCommand;
+  }
+});
+Object.defineProperty(exports, 'parseResult', {
+  enumerable: true,
+  get: function () {
+    return parseResult;
+  }
+});
+Object.defineProperty(exports, 'serializeCommand', {
+  enumerable: true,
+  get: function () {
+    return serializeCommand;
+  }
+});
+Object.defineProperty(exports, 'serializeResult', {
+  enumerable: true,
+  get: function () {
+    return serializeResult;
+  }
+});

package/dist/protocol.cjs

@@ -0,0 +1,11 @@
+const require_protocol = require('./protocol-XeAOKBD-.cjs');
+
+exports.ErrorCodes = require_protocol.ErrorCodes
+exports.calculateStats = require_protocol.calculateStats
+exports.decodeBase64 = require_protocol.decodeBase64
+exports.encodeBase64 = require_protocol.encodeBase64
+exports.formatStats = require_protocol.formatStats
+exports.parseCommand = require_protocol.parseCommand
+exports.parseResult = require_protocol.parseResult
+exports.serializeCommand = require_protocol.serializeCommand
+exports.serializeResult = require_protocol.serializeResult

package/dist/protocol.d.cts

@@ -0,0 +1,2 @@
+import { AppendCommand, AppendResult, BenchmarkAppendOp, BenchmarkCommand, BenchmarkCreateOp, BenchmarkOperation, BenchmarkReadOp, BenchmarkResult, BenchmarkRoundtripOp, BenchmarkStats, BenchmarkThroughputAppendOp, BenchmarkThroughputReadOp, ClearDynamicCommand, ClearDynamicResult, ConnectCommand, ConnectResult, CreateCommand, CreateResult, DeleteCommand, DeleteResult, ErrorCode, ErrorCodes, ErrorResult, HeadCommand, HeadResult, InitCommand, InitResult, ReadChunk, ReadCommand, ReadResult, SetDynamicHeaderCommand, SetDynamicHeaderResult, SetDynamicParamCommand, SetDynamicParamResult, ShutdownCommand, ShutdownResult, TestCommand, TestResult, calculateStats, decodeBase64, encodeBase64, formatStats, parseCommand, parseResult, serializeCommand, serializeResult } from "./protocol-3cf94Xyb.cjs";
+export { AppendCommand, AppendResult, BenchmarkAppendOp, BenchmarkCommand, BenchmarkCreateOp, BenchmarkOperation, BenchmarkReadOp, BenchmarkResult, BenchmarkRoundtripOp, BenchmarkStats, BenchmarkThroughputAppendOp, BenchmarkThroughputReadOp, ClearDynamicCommand, ClearDynamicResult, ConnectCommand, ConnectResult, CreateCommand, CreateResult, DeleteCommand, DeleteResult, ErrorCode, ErrorCodes, ErrorResult, HeadCommand, HeadResult, InitCommand, InitResult, ReadChunk, ReadCommand, ReadResult, SetDynamicHeaderCommand, SetDynamicHeaderResult, SetDynamicParamCommand, SetDynamicParamResult, ShutdownCommand, ShutdownResult, TestCommand, TestResult, calculateStats, decodeBase64, encodeBase64, formatStats, parseCommand, parseResult, serializeCommand, serializeResult };