@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

package/dist/herdr/test-kit/fake-herdr.d.ts

@@ -0,0 +1,13 @@
+import type { Socket } from 'node:net';
+import { AckSwitches, FakeScript, HeldConnections, Subscribers } from './fake-protocol.js';
+import type { PongSettings } from './fake-protocol.js';
+import type { CreateFakeHerdr } from './types.js';
+export interface ServingContext {
+    readonly script: FakeScript;
+    readonly pong: PongSettings;
+    readonly subscribers: Subscribers;
+    readonly acks: AckSwitches;
+    readonly held: HeldConnections;
+}
+export declare function serveConnection(socket: Socket, context: ServingContext): void;
+export declare const createFakeHerdr: CreateFakeHerdr;

package/dist/herdr/test-kit/fake-herdr.js

@@ -0,0 +1,216 @@
+// Role: createFakeHerdr(): a fake herdr on a temporary socket, serving each connection from the protocol in fake-protocol.ts.
+// Informs HERDR-ADR-0016, plan 5, HERDR-ADR-0008; merged by HERDR-ADR-0021 from fake-connection.ts, fake-herdr.ts.
+import { createServer } from 'node:net';
+import { AnswerKind, EMPTY_REPLY_ID, ServedState, TEXT_ENCODING, WireField, Fake, WireFact } from '../../constants.js';
+import { Method, PROTOCOL } from '../generated/index.js';
+import { isObject, LineSplitter } from '../wire/codec.js';
+import { answerFor, errorAnswer, invalidRequestAnswer, AckSwitches, FakeScript, HeldConnections, isHeldMethod, specsOf, subscribeRefusal, Subscribers, endSocket, lineOf, safeWrite, fieldOf, isText, advertisedCapabilities, fakeSocketLocation, removeOwnedDir } from './fake-protocol.js';
+export function serveConnection(socket, context) {
+    const splitter = new LineSplitter();
+    let state = ServedState.Fresh;
+    socket.setEncoding(TEXT_ENCODING);
+    // A client may destroy its socket at any time; the fake must not crash on the write that follows.
+    socket.on('error', () => undefined);
+    socket.on('close', () => {
+        context.subscribers.forget(socket);
+        context.held.forget(socket);
+    });
+    socket.on('data', (chunk) => {
+        for (const line of splitter.push(chunk)) {
+            state = serveLine(socket, line, state, context);
+        }
+    });
+}
+// Returns the state of the connection after this line. A subscriber and an answered connection take no more requests.
+function serveLine(socket, line, state, context) {
+    if (state === ServedState.Answered || state === ServedState.Subscriber) {
+        return state;
+    }
+    const request = parseRequest(line);
+    if (request === undefined) {
+        // W3: the unparseable line gets the empty id and the connection ends, even when it was held.
+        writeAndEnd(socket, invalidRequestAnswer(), context);
+        return ServedState.Answered;
+    }
+    context.script.record(request);
+    if (request.method === Method.EventsSubscribe && !context.script.hasScriptedOutcome(request.method)) {
+        return subscribe(socket, request, context);
+    }
+    const answer = answerFor(context.script, request, context.pong);
+    return finish(socket, answer, state, context, request.method);
+}
+// An events.subscribe is refused (W6: invalid_params, then the connection ends) or acknowledged, and then the connection carries pushes (W2).
+function subscribe(socket, request, context) {
+    const refusal = subscribeRefusal(request.params);
+    if (refusal !== undefined) {
+        writeAndEnd(socket, errorAnswer(request.id, refusal), context);
+        return ServedState.Answered;
+    }
+    context.held.forget(socket);
+    context.acks.acknowledge(socket, request.id);
+    context.subscribers.add(socket, specsOf(request.params));
+    return ServedState.Subscriber;
+}
+// Writes the answer. A result for a class C method (or on a held connection) keeps the connection open as held; anything else ends it (W1).
+// An error envelope always ends it: how herdr treats a refused class C request is not measured; the fake takes the conservative reading and ends the connection.
+function finish(socket, answer, state, context, method) {
+    if (answer.kind === AnswerKind.Silent) {
+        return state;
+    }
+    writeAnswer(socket, answer);
+    const keepsOpen = answer.kind === AnswerKind.Envelope && WireField.Result in answer.body && (state === ServedState.Held || isHeldMethod(method));
+    if (!keepsOpen) {
+        closeConnection(socket, context);
+        return ServedState.Answered;
+    }
+    context.held.add(socket);
+    return ServedState.Held;
+}
+function writeAndEnd(socket, answer, context) {
+    writeAnswer(socket, answer);
+    closeConnection(socket, context);
+}
+// Ends the connection from the server side and leaves the held set at once, so heldCount() never counts a connection the client has already lost.
+function closeConnection(socket, context) {
+    context.held.forget(socket);
+    endSocket(socket);
+}
+// A silent answer writes nothing; a raw answer is written as it is; an envelope is serialised.
+function writeAnswer(socket, answer) {
+    if (answer.kind === AnswerKind.Silent) {
+        return;
+    }
+    safeWrite(socket, lineOf(answer.kind === AnswerKind.Raw ? answer.line : answer.body));
+}
+// A request is a JSON object with a string method; anything else is not a request.
+function parseRequest(line) {
+    const parsed = parseJson(line);
+    if (!isObject(parsed)) {
+        return undefined;
+    }
+    const method = fieldOf(parsed, WireField.Method);
+    if (!isText(method)) {
+        return undefined;
+    }
+    const id = fieldOf(parsed, WireField.Id);
+    return { id: isText(id) ? id : EMPTY_REPLY_ID, method, params: fieldOf(parsed, WireField.Params) };
+}
+function parseJson(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+export const createFakeHerdr = async function createFakeHerdr(options = {}) {
+    const location = fakeSocketLocation(options.socketPath);
+    const pong = {
+        protocol: options.protocol ?? PROTOCOL,
+        version: options.version ?? Fake.Version,
+        capabilities: advertisedCapabilities(options.capabilities),
+    };
+    const context = {
+        script: new FakeScript(),
+        pong,
+        subscribers: new Subscribers(),
+        acks: new AckSwitches(),
+        held: new HeldConnections(),
+    };
+    const sockets = new Set();
+    const server = createServer((socket) => {
+        sockets.add(socket);
+        socket.on('close', () => {
+            sockets.delete(socket);
+        });
+        serveConnection(socket, context);
+    });
+    await listen(server, location.path);
+    return handleFor(location, context, sockets, server);
+};
+function handleFor(location, context, sockets, server) {
+    const { script, subscribers, acks, held } = context;
+    return {
+        path: location.path,
+        capabilities: context.pong.capabilities,
+        reproduces: [
+            WireFact.W1CloseAfterResponse,
+            WireFact.W2AckThenStream,
+            WireFact.W3EmptyIdOnUnparseable,
+            WireFact.W4SchemaOverSocketIsEmpty,
+            WireFact.W5NoHistoryReplay,
+            WireFact.W6PerPaneNeedsPaneId,
+        ],
+        reply(method, result) {
+            script.setReply(method, result);
+        },
+        fail(method, error) {
+            script.setFailure(method, error);
+        },
+        silent(method) {
+            script.setSilent(method);
+        },
+        rawReply(method, line) {
+            script.setRawLine(method, line);
+        },
+        replySequence(method, steps) {
+            script.setSequence(method, steps);
+        },
+        receivedMethods() {
+            return script.methods();
+        },
+        requests() {
+            return script.requests();
+        },
+        connectionCount() {
+            return sockets.size;
+        },
+        push(frame) {
+            subscribers.push(frame);
+        },
+        closeSubscribers() {
+            subscribers.closeAll();
+        },
+        subscriberCount() {
+            return subscribers.count();
+        },
+        holdPushes() {
+            return subscribers.holdPushes();
+        },
+        splitAck() {
+            acks.splitNextAck();
+        },
+        strayLine(line) {
+            acks.strayBeforeAck(line);
+        },
+        heldCount() {
+            return held.count();
+        },
+        closeHeld() {
+            held.closeAll();
+        },
+        async stop() {
+            for (const socket of sockets) {
+                socket.destroy();
+            }
+            await close(server);
+            removeOwnedDir(location);
+        },
+    };
+}
+function listen(server, path) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+}
+function close(server) {
+    return new Promise((resolve) => {
+        server.close(() => {
+            resolve();
+        });
+    });
+}

package/dist/herdr/test-kit/fake-protocol.d.ts

@@ -0,0 +1,107 @@
+import { AnswerKind } from '../../constants.js';
+import type { Socket } from 'node:net';
+import { SubscriptionType } from '../generated/index.js';
+import type { ErrorBody } from '../generated/index.js';
+import type { ServerCapabilities } from '../generated/results.js';
+import { JsonKind } from '../generated/test-data/shapes.js';
+import type { ReceivedRequest } from './types.js';
+export declare function fieldOf(value: unknown, name: string): unknown;
+export declare function isText(value: unknown): value is string;
+export declare function lineOf(value: object | string): string;
+export declare function safeWrite(socket: Socket, text: string): void;
+export declare function endSocket(socket: Socket): void;
+export interface FakeSocketLocation {
+    readonly path: string;
+    readonly ownedDir: string | undefined;
+}
+export declare function fakeSocketLocation(socketPath: string | undefined): FakeSocketLocation;
+export declare function removeOwnedDir(location: FakeSocketLocation): void;
+export interface PongSettings {
+    readonly protocol: number;
+    readonly version: string;
+    readonly capabilities: ServerCapabilities | null;
+}
+export declare function advertisedCapabilities(option: ServerCapabilities | null | undefined): ServerCapabilities | null;
+export declare function pongBody(settings: PongSettings): Record<string, unknown>;
+export declare function defaultResultOf(method: string, pong: PongSettings): unknown;
+export declare class AckSwitches {
+    private splitNext;
+    private strayNext;
+    splitNextAck(): void;
+    strayBeforeAck(line: string): void;
+    acknowledge(socket: Socket, id: string): void;
+    private takeStray;
+    private takeSplit;
+}
+export declare function checkParams(method: string, params: unknown): ErrorBody | undefined;
+export declare function jsonKindOf(value: unknown): JsonKind;
+export type ScriptedStep = {
+    readonly result: unknown;
+} | {
+    readonly error: ErrorBody;
+};
+export declare class FakeScript {
+    private readonly replies;
+    private readonly failures;
+    private readonly rawLines;
+    private readonly silences;
+    private readonly sequences;
+    private readonly received;
+    setReply(method: string, result: unknown): void;
+    setFailure(method: string, error: ErrorBody): void;
+    setRawLine(method: string, line: string): void;
+    setSilent(method: string): void;
+    setSequence(method: string, steps: readonly ScriptedStep[]): void;
+    takeStep(method: string): ScriptedStep | undefined;
+    record(request: ReceivedRequest): void;
+    methods(): readonly string[];
+    requests(): readonly ReceivedRequest[];
+    hasScriptedOutcome(method: string): boolean;
+    isSilent(method: string): boolean;
+    rawLineOf(method: string): string | undefined;
+    failureOf(method: string): ErrorBody | undefined;
+    hasReply(method: string): boolean;
+    replyOf(method: string): unknown;
+}
+export type Answer = {
+    readonly kind: typeof AnswerKind.Silent;
+} | {
+    readonly kind: typeof AnswerKind.Raw;
+    readonly line: string;
+} | {
+    readonly kind: typeof AnswerKind.Envelope;
+    readonly body: Record<string, unknown>;
+};
+export declare function answerFor(script: FakeScript, request: ReceivedRequest, pong: PongSettings): Answer;
+export declare function invalidRequestAnswer(): Answer;
+export declare function errorAnswer(id: string, error: ErrorBody): Answer;
+export declare function isHeldMethod(method: string): boolean;
+export declare class HeldConnections {
+    private readonly sockets;
+    add(socket: Socket): void;
+    forget(socket: Socket): void;
+    count(): number;
+    closeAll(): void;
+}
+export interface SubscriptionSpec {
+    readonly type: SubscriptionType;
+    readonly paneId: string | undefined;
+}
+export interface PushLike {
+    readonly event: string;
+    readonly data: unknown;
+}
+export declare function subscribeRefusal(params: unknown): ErrorBody | undefined;
+export declare function specsOf(params: unknown): readonly SubscriptionSpec[];
+export declare function reaches(specs: readonly SubscriptionSpec[], frame: PushLike): boolean;
+export declare class Subscribers {
+    private readonly specsBySocket;
+    private queued;
+    add(socket: Socket, specs: readonly SubscriptionSpec[]): void;
+    forget(socket: Socket): void;
+    count(): number;
+    push(frame: PushLike): void;
+    holdPushes(): () => void;
+    closeAll(): void;
+    private deliver;
+}