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

package/dist/index.d.cts

@@ -0,0 +1,508 @@
+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";
+
+//#region src/test-cases.d.ts
+interface TestSuite {
+  /** Unique identifier for this suite */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description of what this suite tests */
+  description: string;
+  /** Category: producer, consumer, or lifecycle */
+  category: `producer` | `consumer` | `lifecycle`;
+  /** Tags for filtering tests */
+  tags?: Array<string>;
+  /** Required client features for all tests in this suite */
+  requires?: Array<ClientFeature>;
+  /** Test cases in this suite */
+  tests: Array<TestCase>;
+}
+/**
+* A single test case with operations and expectations.
+*/
+interface TestCase {
+  /** Unique identifier within the suite */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description of what this test verifies */
+  description?: string;
+  /** Tags for filtering */
+  tags?: Array<string>;
+  /** Skip this test (with optional reason) */
+  skip?: boolean | string;
+  /** Required client features for this test */
+  requires?: Array<ClientFeature>;
+  /** Setup operations to run before the test */
+  setup?: Array<TestOperation>;
+  /** Test operations to execute */
+  operations: Array<TestOperation>;
+  /** Cleanup operations to run after the test */
+  cleanup?: Array<TestOperation>;
+}
+/**
+* Client features that may be required for certain tests.
+*/
+type ClientFeature = `batching` | `sse` | `long-poll` | `streaming` | `dynamicHeaders`;
+/**
+* Create a stream.
+*/
+interface CreateOperation {
+  action: `create`;
+  /** Stream path (a unique path will be generated if not specified) */
+  path?: string;
+  /** Variable name to store the generated path */
+  as?: string;
+  /** Content type */
+  contentType?: string;
+  /** TTL in seconds */
+  ttlSeconds?: number;
+  /** Absolute expiry (ISO 8601) */
+  expiresAt?: string;
+  /** Custom headers */
+  headers?: Record<string, string>;
+  /** Expected result */
+  expect?: CreateExpectation;
+}
+/**
+* Connect to an existing stream.
+*/
+interface ConnectOperation {
+  action: `connect`;
+  /** Stream path or variable reference like ${streamPath} */
+  path: string;
+  headers?: Record<string, string>;
+  expect?: ConnectExpectation;
+}
+/**
+* Append data to a stream.
+*/
+interface AppendOperation {
+  action: `append`;
+  /** Stream path or variable reference */
+  path: string;
+  /** Data to append (string) */
+  data?: string;
+  /** Binary data (base64 encoded) */
+  binaryData?: string;
+  /** Sequence number for ordering */
+  seq?: number;
+  headers?: Record<string, string>;
+  expect?: AppendExpectation;
+}
+/**
+* Append multiple items (tests batching behavior).
+*/
+interface AppendBatchOperation {
+  action: `append-batch`;
+  path: string;
+  /** Items to append concurrently */
+  items: Array<{
+    data?: string;
+    binaryData?: string;
+    seq?: number;
+  }>;
+  headers?: Record<string, string>;
+  expect?: AppendBatchExpectation;
+}
+/**
+* Read from a stream.
+*/
+interface ReadOperation {
+  action: `read`;
+  path: string;
+  /** Starting offset or variable reference like ${lastOffset} */
+  offset?: string;
+  /** Live mode */
+  live?: false | `long-poll` | `sse`;
+  /** Timeout for long-poll in ms */
+  timeoutMs?: number;
+  /** Maximum chunks to read */
+  maxChunks?: number;
+  /** Wait until up-to-date */
+  waitForUpToDate?: boolean;
+  headers?: Record<string, string>;
+  expect?: ReadExpectation;
+  /** Run in background (don't wait for completion) */
+  background?: boolean;
+  /** Store reference for later await (required if background: true) */
+  as?: string;
+}
+/**
+* Get stream metadata.
+*/
+interface HeadOperation {
+  action: `head`;
+  path: string;
+  headers?: Record<string, string>;
+  expect?: HeadExpectation;
+}
+/**
+* Delete a stream.
+*/
+interface DeleteOperation {
+  action: `delete`;
+  path: string;
+  headers?: Record<string, string>;
+  expect?: DeleteExpectation;
+}
+/**
+* Wait for a duration (for timing-sensitive tests).
+*/
+interface WaitOperation {
+  action: `wait`;
+  /** Duration in milliseconds */
+  ms: number;
+}
+/**
+* Store a value in a variable for later use.
+*/
+interface SetOperation {
+  action: `set`;
+  /** Variable name */
+  name: string;
+  /** Value (can reference other variables) */
+  value: string;
+}
+/**
+* Assert a condition using structured assertions (no eval).
+*/
+interface AssertOperation {
+  action: `assert`;
+  /** Check that two values are equal */
+  equals?: {
+    left: string;
+    right: string;
+  };
+  /** Check that two values are not equal */
+  notEquals?: {
+    left: string;
+    right: string;
+  };
+  /** Check that a string contains a substring */
+  contains?: {
+    value: string;
+    substring: string;
+  };
+  /** Check that a value matches a regex pattern */
+  matches?: {
+    value: string;
+    pattern: string;
+  };
+  /** Message if assertion fails */
+  message?: string;
+}
+/**
+* Append to stream via direct server HTTP (bypasses client adapter).
+* Used for concurrent operations when adapter is blocked on a read.
+*/
+interface ServerAppendOperation {
+  action: `server-append`;
+  path: string;
+  data: string;
+  headers?: Record<string, string>;
+}
+/**
+* Wait for a background operation to complete.
+*/
+interface AwaitOperation {
+  action: `await`;
+  /** Reference to the background operation (from 'as' field) */
+  ref: string;
+  expect?: ReadExpectation;
+}
+/**
+* Inject an error to be returned on the next N requests to a path.
+* Used for testing retry/resilience behavior.
+*/
+interface InjectErrorOperation {
+  action: `inject-error`;
+  /** Stream path to inject error for */
+  path: string;
+  /** HTTP status code to return */
+  status: number;
+  /** Number of times to return this error (default: 1) */
+  count?: number;
+  /** Optional Retry-After header value (seconds) */
+  retryAfter?: number;
+}
+/**
+* Clear all injected errors.
+*/
+interface ClearErrorsOperation {
+  action: `clear-errors`;
+}
+/**
+* Set a dynamic header that is evaluated per-request.
+* Useful for testing token refresh scenarios.
+*/
+interface SetDynamicHeaderOperation {
+  action: `set-dynamic-header`;
+  /** Header name */
+  name: string;
+  /** Type of dynamic value */
+  valueType: `counter` | `timestamp` | `token`;
+  /** Initial value (for token type) */
+  initialValue?: string;
+}
+/**
+* Set a dynamic URL parameter that is evaluated per-request.
+*/
+interface SetDynamicParamOperation {
+  action: `set-dynamic-param`;
+  /** Param name */
+  name: string;
+  /** Type of dynamic value */
+  valueType: `counter` | `timestamp`;
+}
+/**
+* Clear all dynamic headers and params.
+*/
+interface ClearDynamicOperation {
+  action: `clear-dynamic`;
+}
+/**
+* All possible test operations.
+*/
+type TestOperation = CreateOperation | ConnectOperation | AppendOperation | AppendBatchOperation | ReadOperation | HeadOperation | DeleteOperation | WaitOperation | SetOperation | AssertOperation | ServerAppendOperation | AwaitOperation | InjectErrorOperation | ClearErrorsOperation | SetDynamicHeaderOperation | SetDynamicParamOperation | ClearDynamicOperation;
+/**
+* Base expectation fields.
+*/
+interface BaseExpectation {
+  /** Expected HTTP status code */
+  status?: number;
+  /** Expected error code (if operation should fail) */
+  errorCode?: string;
+  /** Store result in variable */
+  storeAs?: string;
+}
+interface CreateExpectation extends BaseExpectation {
+  /** Status should be 201 for new, 200 for existing */
+  status?: 200 | 201 | 409 | number;
+}
+interface ConnectExpectation extends BaseExpectation {
+  status?: 200 | 404 | number;
+}
+interface AppendExpectation extends BaseExpectation {
+  status?: 200 | 404 | 409 | number;
+  /** Store the returned offset */
+  storeOffsetAs?: string;
+  /** Expected headers that were sent (for dynamic header testing) */
+  headersSent?: Record<string, string>;
+  /** Expected params that were sent (for dynamic param testing) */
+  paramsSent?: Record<string, string>;
+}
+interface AppendBatchExpectation extends BaseExpectation {
+  /** All items should succeed */
+  allSucceed?: boolean;
+  /** Specific items should succeed (by index) */
+  succeedIndices?: Array<number>;
+  /** Specific items should fail (by index) */
+  failIndices?: Array<number>;
+}
+interface ReadExpectation extends BaseExpectation {
+  status?: 200 | 204 | 404 | number;
+  /** Expected data content (exact match) */
+  data?: string;
+  /** Expected data to contain (substring) */
+  dataContains?: string;
+  /** Expected data to contain all of these substrings */
+  dataContainsAll?: Array<string>;
+  /** Expected number of chunks */
+  chunkCount?: number;
+  /** Minimum number of chunks */
+  minChunks?: number;
+  /** Maximum number of chunks */
+  maxChunks?: number;
+  /** Should be up-to-date after read */
+  upToDate?: boolean;
+  /** Store final offset */
+  storeOffsetAs?: string;
+  /** Store all data concatenated */
+  storeDataAs?: string;
+  /** Expected headers that were sent (for dynamic header testing) */
+  headersSent?: Record<string, string>;
+  /** Expected params that were sent (for dynamic param testing) */
+  paramsSent?: Record<string, string>;
+}
+interface HeadExpectation extends BaseExpectation {
+  status?: 200 | 404 | number;
+  /** Expected content type */
+  contentType?: string;
+  /** Should have an offset */
+  hasOffset?: boolean;
+}
+interface DeleteExpectation extends BaseExpectation {
+  status?: 200 | 204 | 404 | number;
+}
+/**
+* Load all test suites from a directory.
+*/
+declare function loadTestSuites(dir: string): Array<TestSuite>;
+/**
+* Load test suites from the embedded test-cases directory.
+*/
+declare function loadEmbeddedTestSuites(): Array<TestSuite>;
+/**
+* Filter test suites by category.
+*/
+declare function filterByCategory(suites: Array<TestSuite>, category: TestSuite[`category`]): Array<TestSuite>;
+/**
+* Filter test cases by tags.
+*/
+
+/**
+* Get total test count.
+*/
+declare function countTests(suites: Array<TestSuite>): number; //#endregion
+//#region src/runner.d.ts
+interface RunnerOptions {
+  /** Path to client adapter executable, or "ts" for built-in TypeScript adapter */
+  clientAdapter: string;
+  /** Arguments to pass to client adapter */
+  clientArgs?: Array<string>;
+  /** Test suites to run (default: all) */
+  suites?: Array<`producer` | `consumer` | `lifecycle`>;
+  /** Tags to filter tests */
+  tags?: Array<string>;
+  /** Verbose output */
+  verbose?: boolean;
+  /** Stop on first failure */
+  failFast?: boolean;
+  /** Timeout for each test in ms */
+  testTimeout?: number;
+  /** Port for reference server (0 for random) */
+  serverPort?: number;
+}
+interface TestRunResult {
+  suite: string;
+  test: string;
+  passed: boolean;
+  duration: number;
+  error?: string;
+  skipped?: boolean;
+  skipReason?: string;
+}
+interface RunSummary {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  duration: number;
+  results: Array<TestRunResult>;
+}
+declare function runConformanceTests(options: RunnerOptions): Promise<RunSummary>;
+
+//#endregion
+//#region src/benchmark-scenarios.d.ts
+interface BenchmarkScenario {
+  /** Unique scenario ID */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description */
+  description: string;
+  /** Category for grouping */
+  category: `latency` | `throughput` | `streaming`;
+  /** Required client features */
+  requires?: Array<`batching` | `sse` | `longPoll` | `streaming`>;
+  /** Scenario configuration */
+  config: BenchmarkScenarioConfig;
+  /** Success criteria */
+  criteria?: BenchmarkCriteria;
+  /** Factory to create benchmark operations for each iteration */
+  createOperation: (ctx: ScenarioContext) => BenchmarkOperation;
+  /** Optional setup before running iterations */
+  setup?: (ctx: ScenarioContext) => Promise<SetupResult>;
+  /** Optional cleanup after running iterations */
+  cleanup?: (ctx: ScenarioContext) => Promise<void>;
+}
+interface BenchmarkScenarioConfig {
+  /** Number of warmup iterations (not measured) */
+  warmupIterations: number;
+  /** Number of measured iterations */
+  measureIterations: number;
+  /** Message size in bytes (where applicable) */
+  messageSize: number;
+  /** Concurrency level (for throughput tests) */
+  concurrency?: number;
+}
+interface BenchmarkCriteria {
+  /** Maximum acceptable p50 latency in ms */
+  maxP50Ms?: number;
+  /** Maximum acceptable p99 latency in ms */
+  maxP99Ms?: number;
+  /** Minimum throughput in operations/second */
+  minOpsPerSecond?: number;
+  /** Minimum throughput in MB/second */
+  minMBPerSecond?: number;
+}
+interface ScenarioContext {
+  /** Base path for streams (unique per scenario run) */
+  basePath: string;
+  /** Current iteration number (0-based) */
+  iteration: number;
+  /** Stored values from setup */
+  setupData: Record<string, unknown>;
+}
+interface SetupResult {
+  /** Data to pass to each iteration */
+  data?: Record<string, unknown>;
+}
+declare const allScenarios: Array<BenchmarkScenario>;
+declare const scenariosByCategory: Record<`latency` | `throughput` | `streaming`, Array<BenchmarkScenario>>;
+declare function getScenarioById(id: string): BenchmarkScenario | undefined;
+declare function getScenariosByCategory(category: `latency` | `throughput` | `streaming`): Array<BenchmarkScenario>;
+
+//#endregion
+//#region src/benchmark-runner.d.ts
+interface BenchmarkRunnerOptions {
+  /** Path to client adapter executable, or "ts" for built-in TypeScript adapter */
+  clientAdapter: string;
+  /** Arguments to pass to client adapter */
+  clientArgs?: Array<string>;
+  /** Specific scenarios to run (default: all) */
+  scenarios?: Array<string>;
+  /** Categories to run (default: all) */
+  categories?: Array<`latency` | `throughput` | `streaming`>;
+  /** Verbose output */
+  verbose?: boolean;
+  /** Port for reference server (0 for random) */
+  serverPort?: number;
+  /** Output format */
+  format?: `console` | `json` | `markdown`;
+}
+interface ScenarioResult {
+  scenario: BenchmarkScenario;
+  stats: BenchmarkStats;
+  criteriaMet: boolean;
+  criteriaDetails: Array<CriteriaResult>;
+  skipped: boolean;
+  skipReason?: string;
+  error?: string;
+  /** Computed ops/sec for throughput scenarios */
+  opsPerSec?: number;
+  /** Computed MB/sec for throughput scenarios */
+  mbPerSec?: number;
+}
+interface CriteriaResult {
+  criterion: string;
+  met: boolean;
+  actual: number;
+  expected: number;
+}
+interface BenchmarkSummary {
+  adapter: string;
+  adapterVersion: string;
+  serverUrl: string;
+  timestamp: string;
+  duration: number;
+  results: Array<ScenarioResult>;
+  passed: number;
+  failed: number;
+  skipped: number;
+}
+declare function runBenchmarks(options: BenchmarkRunnerOptions): Promise<BenchmarkSummary>;
+
+//#endregion
+export { AppendCommand, AppendResult, BenchmarkAppendOp, BenchmarkCommand, BenchmarkCreateOp, BenchmarkCriteria, BenchmarkOperation, BenchmarkReadOp, BenchmarkResult, BenchmarkRoundtripOp, BenchmarkRunnerOptions, BenchmarkScenario, BenchmarkScenarioConfig, BenchmarkStats, BenchmarkSummary, BenchmarkThroughputAppendOp, BenchmarkThroughputReadOp, ClearDynamicCommand, ClearDynamicResult, ClientFeature, ConnectCommand, ConnectResult, CreateCommand, CreateResult, DeleteCommand, DeleteResult, ErrorCode, ErrorCodes, ErrorResult, HeadCommand, HeadResult, InitCommand, InitResult, ReadChunk, ReadCommand, ReadResult, RunSummary, RunnerOptions, ScenarioContext, ScenarioResult, SetDynamicHeaderCommand, SetDynamicHeaderResult, SetDynamicParamCommand, SetDynamicParamResult, ShutdownCommand, ShutdownResult, TestCase, TestCommand, TestOperation, TestResult, TestRunResult, TestSuite, allScenarios, calculateStats, countTests, decodeBase64, encodeBase64, filterByCategory, formatStats, getScenarioById, getScenariosByCategory, loadEmbeddedTestSuites, loadTestSuites, parseCommand, parseResult, runBenchmarks, runConformanceTests, scenariosByCategory, serializeCommand, serializeResult };