@benclmnt/postmock 0.0.3 → 0.0.4

package/dist/src/config.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import type { PostmockConfig } from "./server.ts";
 /** Every setting is one of these env keys. Plugins read their own keys when they start. */
-export declare const ENV_KEYS: readonly ["POSTMOCK_HOST", "POSTMOCK_API_PORT", "POSTMOCK_CONTROL_PORT", "POSTMOCK_SEED", "POSTMOCK_HTTPS_PORT", "POSTMOCK_HTTPS_TLS_KEY", "POSTMOCK_HTTPS_TLS_CERT", "POSTMOCK_SMTP_PORTS", "POSTMOCK_SMTP_TLS_KEY", "POSTMOCK_SMTP_TLS_CERT", "POSTMOCK_WEBHOOKS_ALLOW_HOSTS"];
+export declare const ENV_KEYS: readonly ["POSTMOCK_HOST", "POSTMOCK_API_PORT", "POSTMOCK_CONTROL_PORT", "POSTMOCK_SEED", "POSTMOCK_CLOCK", "POSTMOCK_HTTPS_PORT", "POSTMOCK_HTTPS_TLS_KEY", "POSTMOCK_HTTPS_TLS_CERT", "POSTMOCK_SMTP_PORTS", "POSTMOCK_SMTP_TLS_KEY", "POSTMOCK_SMTP_TLS_CERT", "POSTMOCK_WEBHOOKS_ALLOW_HOSTS"];
 export declare const flagOf: (key: string) => string;
 export declare const USAGE: string;
 /**

package/dist/src/config.js

@@ -7,6 +7,7 @@ export const ENV_KEYS = [
     "POSTMOCK_API_PORT",
     "POSTMOCK_CONTROL_PORT",
     "POSTMOCK_SEED",
+    "POSTMOCK_CLOCK",
     "POSTMOCK_HTTPS_PORT",
     "POSTMOCK_HTTPS_TLS_KEY",
     "POSTMOCK_HTTPS_TLS_CERT",
@@ -63,6 +64,7 @@ const envSchema = z.object({
     POSTMOCK_API_PORT: portSchema.default(8080),
     POSTMOCK_CONTROL_PORT: portSchema.default(8025),
     POSTMOCK_SEED: z.string().min(1).default("empty"),
+    POSTMOCK_CLOCK: z.enum(["real", "manual"]).default("real"),
     POSTMOCK_HTTPS_PORT: portSchema.optional(),
     POSTMOCK_HTTPS_TLS_KEY: z.string().min(1).optional(),
     POSTMOCK_HTTPS_TLS_CERT: z.string().min(1).optional(),
@@ -75,6 +77,7 @@ export function configFromEnv(env) {
         apiPort: e.POSTMOCK_API_PORT,
         controlPort: e.POSTMOCK_CONTROL_PORT,
         seed: e.POSTMOCK_SEED,
+        clock: e.POSTMOCK_CLOCK,
     };
     const https = [e.POSTMOCK_HTTPS_PORT, e.POSTMOCK_HTTPS_TLS_KEY, e.POSTMOCK_HTTPS_TLS_CERT];
     if (https.every((v) => v === undefined))

package/dist/src/control/endpoints/core.js

@@ -3,7 +3,7 @@ import { apiError, ERROR_FAMILIES, isSummaryRow } from "../../errors.js";
 import { formatTimestamp } from "../../time.js";
 import { ControlError, controlInput, defineControl } from "../registry.js";
 import { seedAtomically } from "../seeding.js";
-// docs/09 §5: reset, seed, clock, faults, messages.
+// docs/09 §5: reset, seed, clock, latency, faults, messages.
 defineControl({
     method: "POST",
     path: "/control/reset",
@@ -28,7 +28,34 @@ defineControl({
     handler: async (ctx) => {
         const { ms } = controlInput(z.object({ ms: z.int().nonnegative() }), ctx.body);
         await ctx.clock.advance(ms);
-        return { now: formatTimestamp(ctx.clock.now(), "utc") };
+        return clockState(ctx.clock);
+    },
+});
+defineControl({
+    method: "GET",
+    path: "/control/clock",
+    handler: (ctx) => clockState(ctx.clock),
+});
+function clockState(clock) {
+    return { now: formatTimestamp(clock.now(), "utc"), pending: clock.pending };
+}
+const requestMatch = z.object({ method: z.string(), path: z.string().startsWith("/") });
+defineControl({
+    method: "POST",
+    path: "/control/latency",
+    handler: (ctx) => {
+        const { match, times, ms } = controlInput(z.object({
+            match: requestMatch,
+            times: z.int().positive().default(1),
+            ms: z.int().positive(),
+        }), ctx.body);
+        ctx.store.state.latencies.push({
+            method: match.method,
+            path: match.path,
+            remaining: times,
+            ms,
+        });
+        return { latencies: ctx.store.state.latencies.length };
     },
 });
 const errorReply = z.object({
@@ -38,7 +65,7 @@ const errorReply = z.object({
     message: z.string().optional(),
 });
 const faultSchema = z.object({
-    match: z.object({ method: z.string(), path: z.string().startsWith("/") }),
+    match: requestMatch,
     times: z.int().positive().default(1),
     reply: z.unknown(),
 });

package/dist/src/http/app.js

@@ -12,7 +12,7 @@ export function createApiApp(runtime) {
     app.all("*", async (c) => {
         const request = c.req.raw;
         const url = new URL(request.url);
-        const fault = await applyFault(runtime.store.state, request.method, url.pathname, c.env);
+        const fault = await applyFault(runtime, request.method, url.pathname, c.env);
         if (fault)
             return fault;
         const matched = apiRoutes.match(request.method, url.pathname);

package/dist/src/http/faults.d.ts

@@ -1,8 +1,8 @@
 import type { HttpBindings } from "@hono/node-server";
-import type { State } from "../state/store.ts";
+import type { Runtime } from "../runtime.ts";
 /**
- * Applies the first fault that matches the request and uses one of its `times`
- * (docs/09 §5 `POST /control/faults`). `timeout` holds the request open until the client gives up;
- * `reset` destroys the socket.
+ * Holds the request for the first matching latency rule, then applies the first matching fault
+ * (docs/09 §5 `POST /control/latency`, `POST /control/faults`). Each match uses one of the rule's
+ * `times`. `timeout` holds the request open until the client gives up; `reset` destroys the socket.
  */
-export declare function applyFault(state: State, method: string, pathname: string, env: HttpBindings): Promise<Response | undefined>;
+export declare function applyFault({ store, clock }: Runtime, method: string, pathname: string, env: HttpBindings): Promise<Response | undefined>;

package/dist/src/http/faults.js

@@ -2,22 +2,28 @@ import { ApiError } from "../errors.js";
 import { errorResponse } from "./respond.js";
 import { RouteTable } from "./routes.js";
 /**
- * Applies the first fault that matches the request and uses one of its `times`
- * (docs/09 §5 `POST /control/faults`). `timeout` holds the request open until the client gives up;
- * `reset` destroys the socket.
+ * Holds the request for the first matching latency rule, then applies the first matching fault
+ * (docs/09 §5 `POST /control/latency`, `POST /control/faults`). Each match uses one of the rule's
+ * `times`. `timeout` holds the request open until the client gives up; `reset` destroys the socket.
  */
-export async function applyFault(state, method, pathname, env) {
-    const fault = state.faults.find((f) => {
-        if (f.remaining <= 0)
+export async function applyFault({ store, clock }, method, pathname, env) {
+    const latency = take(store.state.latencies, method, pathname);
+    if (latency)
+        await clock.hold(latency.ms);
+    const fault = take(store.state.faults, method, pathname);
+    return fault && reply(fault, env);
+}
+function take(rules, method, pathname) {
+    const rule = rules.find((r) => {
+        if (r.remaining <= 0)
             return false;
         const table = new RouteTable();
-        table.add({ method: f.method.toUpperCase(), path: f.path });
+        table.add({ method: r.method.toUpperCase(), path: r.path });
         return table.match(method, pathname) !== undefined;
     });
-    if (!fault)
-        return undefined;
-    fault.remaining -= 1;
-    return reply(fault, env);
+    if (rule)
+        rule.remaining -= 1;
+    return rule;
 }
 async function reply(fault, env) {
     const { reply } = fault;

package/dist/src/server.d.ts

@@ -1,5 +1,6 @@
 import { type Plugin } from "./plugins.ts";
 import { type Runtime } from "./runtime.ts";
+import { type ClockMode } from "./state/clock.ts";
 export interface PostmockConfig {
     host: string;
     /** Plain-http REST port; 0 picks a free port. */
@@ -12,6 +13,8 @@ export interface PostmockConfig {
         cert: string;
     };
     seed: string;
+    /** `manual`: time moves only on `POST /control/clock/advance`. */
+    clock: ClockMode;
     /** Defaults to every plugin in `src/plugins/`. */
     plugins?: readonly Plugin[];
 }

package/dist/src/server.js

@@ -5,6 +5,7 @@ import { applySeed } from "./control/seed.js";
 import { createApiApp } from "./http/app.js";
 import { PLUGINS } from "./plugins.js";
 import { createRuntime } from "./runtime.js";
+import { Clock } from "./state/clock.js";
 function listen(name, fetch, host, port, tls) {
     return new Promise((resolve) => {
         const onListen = (info) => resolve({
@@ -19,7 +20,7 @@ function listen(name, fetch, host, port, tls) {
 }
 /** Seeds the state, then starts the REST, control and plugin listeners. */
 export async function startPostmock(config) {
-    const runtime = createRuntime(config.plugins ?? PLUGINS);
+    const runtime = createRuntime(config.plugins ?? PLUGINS, new Clock(Date.now, config.clock));
     await applySeed(runtime, config.seed);
     const api = createApiApp(runtime);
     const started = [await listen("api", api.fetch, config.host, config.apiPort)];
@@ -41,9 +42,10 @@ export async function startPostmock(config) {
         runtime,
         listeners: Object.fromEntries(started.map((l) => [l.name, l.url])),
         close: async () => {
-            await Promise.all(started.map((l) => l.close()));
+            // Reset first: a listener closes only after its held requests answer.
             await runtime.clock.idle();
             runtime.clock.reset();
+            await Promise.all(started.map((l) => l.close()));
         },
     };
 }

package/dist/src/state/clock.d.ts

@@ -1,19 +1,29 @@
+/** `real`: time follows real time plus advances. `manual`: time moves only on `advance()`. */
+export type ClockMode = "real" | "manual";
 type Run = () => void | Promise<void>;
 /**
  * Real time plus an offset that `advance()` grows (docs/09 §5 `clock/advance`).
  * A scheduled task runs once: when real time reaches it, or when `advance()` passes it.
+ * A `manual` clock starts at real time, stands still, and only `advance()` moves it and runs tasks.
  * Advances and real-timer tasks run one at a time, in the order they start.
  */
 export declare class Clock {
     private offsetMs;
+    /** The instant a manual clock stands at; `undefined` on a real clock. */
+    private manualNow;
     private seq;
     private advancing;
     private queue;
     private readonly tasks;
+    private readonly holds;
     private readonly realNow;
-    constructor(realNow?: () => number);
+    constructor(realNow?: () => number, mode?: ClockMode);
     now(): Date;
+    /** The number of tasks not yet run. */
+    get pending(): number;
     schedule(delayMs: number, run: Run): void;
+    /** Resolves after `delayMs` on the clock, or at `reset()`, so a held request always answers. */
+    hold(delayMs: number): Promise<void>;
     /**
      * Moves time forward by `ms`, after any advance already running. Runs each task due by the end in
      * due order, with `now()` set to its due time, and awaits it. A task scheduled during the advance
@@ -22,9 +32,12 @@ export declare class Clock {
     advance(ms: number): Promise<void>;
     /** Resolves when every advance and real-timer task started so far has finished. */
     idle(): Promise<void>;
-    /** Drops pending tasks and the offset. Throws during an advance, which would undo it. */
+    /**
+     * Drops pending tasks and the offset, and releases every hold; a manual clock stands at real time
+     * again. Throws during an advance, which would undo it.
+     */
     reset(): void;
-    /** Captures offset and pending tasks; the returned function puts them back. */
+    /** Captures time and pending tasks; the returned function puts them back. */
     checkpoint(): () => void;
     private add;
     private enqueue;

package/dist/src/state/clock.js

@@ -3,20 +3,30 @@ const MAX_TIMER_MS = 2 ** 31 - 1;
 /**
  * Real time plus an offset that `advance()` grows (docs/09 §5 `clock/advance`).
  * A scheduled task runs once: when real time reaches it, or when `advance()` passes it.
+ * A `manual` clock starts at real time, stands still, and only `advance()` moves it and runs tasks.
  * Advances and real-timer tasks run one at a time, in the order they start.
  */
 export class Clock {
     offsetMs = 0;
+    /** The instant a manual clock stands at; `undefined` on a real clock. */
+    manualNow;
     seq = 0;
     advancing = false;
     queue = Promise.resolve();
     tasks = new Set();
+    holds = new Set();
     realNow;
-    constructor(realNow = Date.now) {
+    constructor(realNow = Date.now, mode = "real") {
         this.realNow = realNow;
+        if (mode === "manual")
+            this.manualNow = realNow();
     }
     now() {
-        return new Date(this.realNow() + this.offsetMs);
+        return new Date(this.manualNow ?? this.realNow() + this.offsetMs);
+    }
+    /** The number of tasks not yet run. */
+    get pending() {
+        return this.tasks.size;
     }
     schedule(delayMs, run) {
         if (!Number.isInteger(delayMs) || delayMs < 0) {
@@ -24,6 +34,16 @@ export class Clock {
         }
         this.add({ due: this.now().getTime() + delayMs, seq: this.seq++, run, timer: undefined });
     }
+    /** Resolves after `delayMs` on the clock, or at `reset()`, so a held request always answers. */
+    hold(delayMs) {
+        return new Promise((resolve) => {
+            this.holds.add(resolve);
+            this.schedule(delayMs, () => {
+                this.holds.delete(resolve);
+                resolve();
+            });
+        });
+    }
     /**
      * Moves time forward by `ms`, after any advance already running. Runs each task due by the end in
      * due order, with `now()` set to its due time, and awaits it. A task scheduled during the advance
@@ -57,27 +77,39 @@ export class Clock {
     idle() {
         return this.queue;
     }
-    /** Drops pending tasks and the offset. Throws during an advance, which would undo it. */
+    /**
+     * Drops pending tasks and the offset, and releases every hold; a manual clock stands at real time
+     * again. Throws during an advance, which would undo it.
+     */
     reset() {
         if (this.advancing)
             throw new Error("clock.reset during an advance");
         for (const task of this.tasks)
             clearTimeout(task.timer);
         this.tasks.clear();
+        for (const release of this.holds)
+            release();
+        this.holds.clear();
         this.offsetMs = 0;
+        if (this.manualNow !== undefined)
+            this.manualNow = this.realNow();
     }
-    /** Captures offset and pending tasks; the returned function puts them back. */
+    /** Captures time and pending tasks; the returned function puts them back. */
     checkpoint() {
-        const offsetMs = this.offsetMs;
+        const { offsetMs, manualNow } = this;
         const tasks = [...this.tasks].map(({ due, seq, run }) => ({ due, seq, run }));
         return () => {
             this.reset();
             this.offsetMs = offsetMs;
+            this.manualNow = manualNow;
             for (const task of tasks)
                 this.add({ ...task, timer: undefined });
         };
     }
     add(task) {
+        this.tasks.add(task);
+        if (this.manualNow !== undefined)
+            return;
         const delay = task.due - this.now().getTime();
         if (delay <= MAX_TIMER_MS) {
             // A task that throws on a real timer is a postmock bug: rethrow so the process crashes.
@@ -87,7 +119,6 @@ export class Clock {
                 }));
             }, Math.max(0, delay)).unref();
         }
-        this.tasks.add(task);
     }
     enqueue(work) {
         const result = this.queue.then(work);
@@ -96,7 +127,11 @@ export class Clock {
     }
     /** Time never moves back. */
     moveTo(instant) {
-        this.offsetMs = Math.max(this.now().getTime(), instant) - this.realNow();
+        const target = Math.max(this.now().getTime(), instant);
+        if (this.manualNow === undefined)
+            this.offsetMs = target - this.realNow();
+        else
+            this.manualNow = target;
     }
     async take(task) {
         if (!this.tasks.delete(task))

package/dist/src/state/store.d.ts

@@ -1,4 +1,4 @@
-import type { Account, Bounce, BulkRequest, ClickEvent, DataRemoval, Domain, Fault, InboundMessage, InboundRule, MessageStream, OpenEvent, OutboundMessage, SenderSignature, Server, SmtpFault, SmtpToken, StatsFact, Suppression, Template, Webhook, WebhookAttempt } from "./types.ts";
+import type { Account, Bounce, BulkRequest, ClickEvent, DataRemoval, Domain, Fault, InboundMessage, InboundRule, Latency, MessageStream, OpenEvent, OutboundMessage, SenderSignature, Server, SmtpFault, SmtpToken, StatsFact, Suppression, Template, Webhook, WebhookAttempt } from "./types.ts";
 export type IdKind = "server" | "bounce" | "template" | "webhook" | "webhookAttempt" | "inboundRule" | "domain" | "sender" | "dataRemoval";
 export interface State {
     account: Account;
@@ -32,6 +32,7 @@ export interface State {
     /** Key: access key. */
     smtpTokens: Map<string, SmtpToken>;
     faults: Fault[];
+    latencies: Latency[];
     smtpFaults: SmtpFault[];
     usedIds: Record<IdKind, Set<number>>;
     /** Highest used ID per kind. */

package/dist/src/state/store.js

@@ -29,6 +29,7 @@ function emptyState() {
         dataRemovals: new Map(),
         smtpTokens: new Map(),
         faults: [],
+        latencies: [],
         smtpFaults: [],
         usedIds: {
             server: new Set(),

package/dist/src/state/types.d.ts

@@ -521,10 +521,17 @@ export type FaultReply = {
         Message: string;
     };
 } | "timeout" | "reset";
-export interface Fault {
+/** A control-API rule for REST requests: `path` is a route pattern, matched like an API route. */
+export interface RequestRule {
     method: string;
-    /** A route pattern, matched like an API route (`/email`, `/templates/:id`). */
+    /** `/email`, `/templates/:id` */
     path: string;
     remaining: number;
+}
+export interface Fault extends RequestRule {
     reply: FaultReply;
 }
+/** `POST /control/latency`: the request waits `ms` on the clock, then goes on as usual. */
+export interface Latency extends RequestRule {
+    ms: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benclmnt/postmock",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A mock Postmark server for testing code that sends email through Postmark",
   "license": "MIT",
   "repository": {