@jimhoyd/urlcode 0.3.0

package/dist/types/config.d.ts

@@ -0,0 +1,21 @@
+import type { LoadedDocument, ProjectDocument } from './types.ts';
+/** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
+export type ConfigWorkerResult = {
+    value: LoadedDocument;
+} | {
+    error: string;
+};
+export interface ConfigWorkerData {
+    project: string;
+}
+export declare const MAX_CONFIG_BYTES: number;
+export declare function parseYaml(text: string): unknown;
+export declare function validateDocument(data: unknown): ProjectDocument;
+export declare function safeFile(root: string, file: unknown): Promise<string>;
+export declare const MAX_PROJECT_CONFIG_BYTES: number;
+export declare function loadDocument(project: string, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<LoadedDocument>;
+export declare function loadDocumentInWorker(project: string): Promise<LoadedDocument>;
+export declare function loadBindings(root: string, local?: boolean, environment?: Record<string, string | undefined>): Promise<Record<string, string | undefined>>;
+export declare function functionFile(root: string, file: string): Promise<string>;

package/dist/types/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class ConfigError extends Error {
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function assert(condition: unknown, message: string): asserts condition;

package/dist/types/function-sources.d.ts

@@ -0,0 +1,21 @@
+/** A function or middleware reference with its export named: what the sandbox loads. */
+export interface FunctionDefinition {
+    source: string;
+    export: string;
+}
+/** Any route-like object carrying function definitions (a YAML route, whose `export` may be absent, or a compiled one). */
+export interface FunctionRoute<D = FunctionDefinition> {
+    middleware?: D[] | undefined;
+    function?: D | undefined;
+}
+export interface FunctionSources {
+    /** Module source text keyed by project-relative name (`/lib/a.mjs`). */
+    sources: Record<string, string>;
+    dependencies: Record<string, string[]>;
+    /** Distinct [module, export] entry points. */
+    entries: [string, string][];
+    /** Absolute source path to module name. */
+    names: Map<string, string>;
+}
+export declare function routeFunctions<D>(route: FunctionRoute<D>): D[];
+export declare function collectFunctionSources(routes: FunctionRoute[], root: string): Promise<FunctionSources>;

package/dist/types/function-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/functions.d.ts

@@ -0,0 +1,92 @@
+import { Worker } from 'node:worker_threads';
+import type { FunctionRoute, FunctionSources } from './function-sources.ts';
+import type { HandlerResult, HeaderPair } from './http-response.ts';
+import type { ParameterValue, RequestContext } from './match.ts';
+import type { LogFn } from './types.ts';
+import type { GuestRequestPayload } from './guest-api.ts';
+export type { FunctionDefinition, FunctionRoute } from './function-sources.ts';
+export type { GuestRequestPayload, GuestResponsePayload } from './guest-api.ts';
+export interface FunctionPoolOptions {
+    root?: string | undefined;
+    snapshot?: FunctionSources | undefined;
+    workers?: number | undefined;
+    timeoutMs?: number | undefined;
+    maxBytes?: number | undefined;
+    log?: LogFn | undefined;
+}
+export interface FunctionWorkerData {
+    sources: Record<string, string>;
+    dependencies: Record<string, string[]>;
+    entries: [string, string][];
+}
+export type FunctionContext = RequestContext & {
+    args?: Record<string, ParameterValue>;
+};
+export interface FunctionWorkerRequest {
+    id: string;
+    source: string | undefined;
+    name: string | undefined;
+    chain: {
+        source: string | undefined;
+        name: string;
+    }[];
+    native: {
+        status: number;
+        headers: HeaderPair[];
+    } | undefined;
+    request: GuestRequestPayload;
+    context: FunctionContext;
+    maxBytes: number;
+    timeoutMs: number;
+}
+export interface FunctionResult extends HandlerResult {
+    nativeBody?: boolean;
+}
+export type FunctionWorkerMessage = {
+    ready: true;
+} | {
+    startupError: true;
+} | {
+    id: string;
+    status: number;
+    headers: HeaderPair[];
+    body: Uint8Array;
+    nativeBody: boolean;
+} | {
+    id: string;
+    error: true;
+};
+interface Pending {
+    id: string;
+    timer: NodeJS.Timeout;
+    resolve: (message: FunctionResult) => void;
+    reject: (error: Error) => void;
+}
+interface Slot {
+    worker: Worker;
+    ready: boolean;
+    pending: Pending | null;
+}
+export declare class FunctionPool {
+    root: string | undefined;
+    routes: FunctionRoute[];
+    preparedSnapshot: FunctionSources | undefined;
+    snapshot: FunctionSources | undefined;
+    restarts: Map<number, number>;
+    restartTimers: Set<NodeJS.Timeout>;
+    log: LogFn;
+    timeoutMs: number;
+    maxBytes: number;
+    modules: [string, string[]][];
+    size: number;
+    slots: (Slot | undefined)[];
+    closed: boolean;
+    constructor(routes: FunctionRoute[], { root, snapshot, workers, timeoutMs, maxBytes, log }?: FunctionPoolOptions);
+    start(): Promise<this>;
+    spawn(index: number): Promise<void>;
+    report(status: string, index: number, extra?: object): void;
+    scheduleRespawn(index: number): void;
+    get healthy(): boolean;
+    execute(route: FunctionRoute, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;
+    close(): Promise<void>;
+}

package/dist/types/guest-api.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderPair } from './http-response.ts';
+/** The request the guest receives (stringified as JSON in the worker). */
+export interface GuestRequestPayload {
+    url: string;
+    method: string;
+    headers: HeaderPair[];
+    body?: Uint8Array | undefined;
+}
+/** What the guest returns as JSON text; the worker enforces this shape before trusting it. */
+export interface GuestResponsePayload {
+    status: number;
+    headers: HeaderPair[];
+    body: string;
+    nativeBody?: boolean;
+}
+export declare const guestBootstrap: string;

package/dist/types/header-validation.d.ts

@@ -0,0 +1,2 @@
+export declare function validateHeaderName(name: unknown): asserts name is string;
+export declare function validateHeaderValue(name: string, value: unknown): void;

package/dist/types/http-policy.d.ts

@@ -0,0 +1,39 @@
+import type { HandlerResult, HeaderPair } from './http-response.ts';
+import type { HeadersLike } from './match.ts';
+export interface RespondSpec {
+    status?: number;
+    json?: unknown;
+    text?: string;
+}
+export interface RequestBodyPolicy {
+    maxBytes?: number;
+    required?: boolean;
+    contentTypes?: string[];
+    format?: 'json' | 'text';
+}
+/** A static reply compiled from `respond`; the body is bytes so every host, including the Worker, shares the type. */
+export interface Reply {
+    status: number;
+    headers: HeaderPair[];
+    body: Uint8Array;
+}
+/** The declared HTTP surface of a route: response headers, request body policy and a static reply. */
+export interface HttpRoute {
+    response?: {
+        headers?: Record<string, string | string[]>;
+    };
+    request?: {
+        body?: RequestBodyPolicy;
+    };
+    respond?: RespondSpec;
+    page?: unknown;
+    static?: unknown;
+    download?: unknown;
+    responseHeaders?: HeaderPair[];
+    reply?: Reply | undefined;
+}
+export declare function compileHttp(route: HttpRoute): void;
+export declare function checkRequest(route: HttpRoute, body: Uint8Array, headers: HeadersLike, counts?: Record<string, number>): void;
+export declare function decorateResponse(route: HttpRoute & {
+    responseHeaders: HeaderPair[];
+}, result: HandlerResult): HandlerResult;

package/dist/types/http-response.d.ts

@@ -0,0 +1,43 @@
+export type HeaderPair = [string, string];
+export type ResponseBody = string | Uint8Array | null | undefined;
+/** What a handler, policy or asset produced; every host turns it into a wire response here. */
+export interface HandlerResult {
+    status: number;
+    headers: HeaderPair[];
+    body?: ResponseBody;
+    contentLength?: number;
+}
+export interface PreparedResponse {
+    status: number;
+    headers: HeaderPair[];
+    cookies: string[];
+    body: ResponseBody;
+}
+export interface ErrorAnswer {
+    status: number;
+    headers: HeaderPair[];
+    body: string | undefined;
+}
+export interface ResponseOptions {
+    requestId: string;
+    method: string;
+}
+/** The node:http ServerResponse surface this module writes to, kept structural so the module stays Node-free. */
+export interface ResponseWriter {
+    statusCode: number;
+    headersSent: boolean;
+    setHeader(name: string, value: string | string[]): unknown;
+    getHeaderNames(): string[];
+    removeHeader(name: string): void;
+    end(body?: ResponseBody): unknown;
+    destroy(): unknown;
+}
+export declare const forbiddenHeaders: Set<string>;
+export declare function prepareResponse(result: HandlerResult, { requestId, method }: ResponseOptions): PreparedResponse;
+export declare function writeResponse(res: ResponseWriter, result: HandlerResult, options: ResponseOptions): number;
+export declare function errorResponse(error: unknown, { requestId, method, headers }: ResponseOptions & {
+    headers?: HeaderPair[];
+}): ErrorAnswer;
+export declare function writeError(res: ResponseWriter, error: unknown, options: ResponseOptions & {
+    headers?: HeaderPair[];
+}): number;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export { createRuntime } from './runtime.ts';
+export type { Runtime, RuntimeOptions, RuntimeRequest, RequestTrace, LinkReader, LinkStoreBinding, HostPlugin, Observer, TestPlan } from './runtime.ts';
+export { startServer } from './server.ts';
+export type { Server, ServerOptions } from './server.ts';
+export { loadDocument, validateDocument, parseYaml } from './config.ts';
+export { openLinkStore } from './link-store.ts';
+export type { LinkStore, LinkRow, LinkStoreOptions } from './link-store.ts';
+export { startLinkApi } from './link-api.ts';
+export type { LinkApi, LinkApiOptions } from './link-api.ts';
+export type { LinkEvent, LinkObserverOptions, LinkObserverStats } from './link-events.ts';
+export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.ts';

package/dist/types/link-api.d.ts

@@ -0,0 +1,30 @@
+import type { AddressInfo } from 'node:net';
+import type { AuditIdentity, LinkRow, ListOptions } from './link-store.ts';
+import type { ManagementAuthorizer } from './management-policy.ts';
+import type { LogFn } from './types.ts';
+/** The store surface management needs: the pooled link store, or anything with the same contract. */
+export interface ManagementStore {
+    readonly atomicAudit?: boolean;
+    get(collection: string, code: string): Promise<LinkRow | null>;
+    list(collection: string, options?: ListOptions): Promise<LinkRow[]>;
+    create(collection: string, data: unknown, code?: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    update(collection: string, code: string, data: unknown, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    delete(collection: string, code: string, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<boolean>;
+}
+export interface LinkApiOptions {
+    store: ManagementStore;
+    collection: string;
+    token?: string | undefined;
+    authorize?: ManagementAuthorizer | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+    maxInFlightRequests?: number | undefined;
+    socketTimeoutMs?: number | undefined;
+    log?: LogFn | undefined;
+}
+export interface LinkApi {
+    address: AddressInfo;
+    close(): Promise<void>;
+}
+export declare function loadLinkToken(file: unknown, project: string): Promise<string>;
+export declare function startLinkApi({ store, collection, token, authorize, host, port, maxInFlightRequests, socketTimeoutMs, log }: LinkApiOptions): Promise<LinkApi>;

package/dist/types/link-cli.d.ts

@@ -0,0 +1,36 @@
+/** The parsed command-line values the links commands read; every flag is a string or absent. */
+export interface LinkCommandValues {
+    project?: string | undefined;
+    store?: string | undefined;
+    collection?: string | undefined;
+    code?: string | undefined;
+    destination?: string | undefined;
+    status?: string | undefined;
+    enabled?: string | undefined;
+    expires?: string | undefined;
+    'if-version'?: string | undefined;
+    limit?: string | undefined;
+    after?: string | undefined;
+    input?: string | undefined;
+    'page-size'?: string | undefined;
+    'auth-file'?: string | undefined;
+    'token-file'?: string | undefined;
+    port?: string | undefined;
+    host?: string | undefined;
+    'link-readers'?: string | undefined;
+    'link-read-limit'?: string | undefined;
+    'link-write-limit'?: string | undefined;
+}
+export type Print = (value: unknown) => unknown;
+export interface LinkPoolOptions {
+    readers?: number;
+    maxReads?: number;
+    maxWrites?: number;
+}
+export interface LinkBinding extends LinkPoolOptions {
+    collection: string;
+    file: string;
+}
+export declare function linkPoolOptions(values: LinkCommandValues): LinkPoolOptions;
+export declare function parseLinkBinding(value: string | undefined, options?: LinkPoolOptions): LinkBinding | undefined;
+export declare function runLinkCommand(action: string | undefined, values: LinkCommandValues, print: Print): Promise<void>;

package/dist/types/link-events.d.ts

@@ -0,0 +1,27 @@
+export interface LinkEvent {
+    outcome: string;
+    code?: string | null;
+    [field: string]: unknown;
+}
+export interface LinkObserverOptions {
+    observe: (event: LinkEvent) => unknown;
+    includeCode?: boolean;
+    maxQueue?: number;
+    timeoutMs?: number;
+}
+export interface LinkObserverStats {
+    queued: number;
+    delivered: number;
+    dropped: number;
+    failed: number;
+    timedOut: number;
+    closed: boolean;
+}
+export interface LinkObserver {
+    emit(event: LinkEvent): void;
+    stats(): LinkObserverStats;
+    close(): Promise<LinkObserverStats>;
+}
+type Log = (event: Record<string, unknown>) => void;
+export declare function createLinkObserver(options: unknown, log?: Log): LinkObserver | undefined;
+export {};

package/dist/types/link-records.d.ts

@@ -0,0 +1,11 @@
+export interface LinkRecord {
+    url: string;
+    status: number;
+    enabled: boolean;
+    expires: string | null;
+}
+export declare function linkCollection(value: unknown): string;
+export declare function linkCode(value: unknown): string;
+export declare function linkVersion(value: unknown): number;
+export declare function linkData(value: unknown): LinkRecord;
+export declare const randomLinkCode: () => string;

package/dist/types/link-store-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/link-store.d.ts

@@ -0,0 +1,130 @@
+import type { LinkRecord } from './link-records.ts';
+import type { LogFn } from './types.ts';
+/** A stored link as the worker returns it. */
+export interface LinkRow extends LinkRecord {
+    collection: string;
+    code: string;
+    version: number;
+}
+export interface ListOptions {
+    limit?: number | undefined;
+    after?: string | undefined;
+}
+export interface AuditIdentity {
+    actor?: string | undefined;
+    requestId?: string | undefined;
+}
+export interface ExportHeader {
+    format: string;
+    schemaVersion: number;
+    applicationId: number;
+    collection: string | null;
+    revision: number;
+    records: number;
+    generatedAt: string;
+}
+export interface ExportPageOptions {
+    afterCollection?: string | undefined;
+    afterCode?: string | undefined;
+    limit?: number | undefined;
+}
+export interface ExportOptions {
+    collection?: string | undefined;
+    pageSize?: number | undefined;
+    deadlineMs?: number | undefined;
+}
+export interface ExportHandlers {
+    onHeader?: ((header: ExportHeader) => unknown) | undefined;
+    onRecords?: ((records: LinkRow[]) => unknown) | undefined;
+}
+export interface ExportSummary extends ExportHeader {
+    exported: number;
+}
+export interface PoolStats {
+    connections: number;
+    healthyConnections: number;
+    limit: number;
+    inFlight: number;
+    completed: number;
+    failed: number;
+    rejected: number;
+    durationMs: number;
+}
+export interface LinkStoreStats {
+    closed: boolean;
+    exporting: boolean;
+    read: PoolStats;
+    write: PoolStats;
+}
+export interface LinkStoreWorkerData {
+    file: string;
+    readOnly: boolean;
+}
+export type LinkStoreOperation = 'get' | 'list' | 'create' | 'update' | 'delete' | 'exportBegin' | 'exportPage' | 'exportEnd' | 'close';
+export interface LinkStoreArgs extends ListOptions, ExportPageOptions {
+    collection?: string | undefined;
+    code?: unknown;
+    data?: unknown;
+    expectedVersion?: unknown;
+    audit?: AuditIdentity | undefined;
+}
+export interface LinkStoreCommand {
+    id: number;
+    operation: LinkStoreOperation;
+    args: LinkStoreArgs;
+}
+export type LinkStoreReply = {
+    ready: true;
+} | {
+    failed: true;
+} | {
+    id: number;
+    value: unknown;
+} | {
+    id: number;
+    error: {
+        status: number;
+        message: string;
+    };
+};
+/** One worker-backed SQLite connection. */
+export interface LinkConnection {
+    readonly healthy: boolean;
+    get(collection: string, code: string): Promise<LinkRow | null>;
+    list(collection: string, options?: ListOptions): Promise<LinkRow[]>;
+    exportBegin(options?: {
+        collection?: string | undefined;
+    }): Promise<ExportHeader>;
+    exportPage(options?: ExportPageOptions): Promise<LinkRow[]>;
+    exportEnd(): Promise<boolean>;
+    create(collection: string, data: unknown, code?: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    update(collection: string, code: string, data: unknown, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    delete(collection: string, code: string, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** The pooled store openLinkStore returns. */
+export interface LinkStore {
+    readonly readHealthy: boolean;
+    readonly writeHealthy: boolean;
+    readonly healthy: boolean;
+    readonly atomicAudit: true;
+    stats(): LinkStoreStats;
+    exportSnapshot(options?: ExportOptions, handlers?: ExportHandlers): Promise<ExportSummary>;
+    get(collection: string, code: string): Promise<LinkRow | null>;
+    list(collection: string, options?: ListOptions): Promise<LinkRow[]>;
+    create(collection: string, data: unknown, code?: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    update(collection: string, code: string, data: unknown, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
+    delete(collection: string, code: string, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<boolean>;
+    close(): Promise<void>;
+}
+export interface LinkStoreOptions {
+    file?: string | undefined;
+    project?: string | undefined;
+    readOnly?: boolean | undefined;
+    readers?: number | undefined;
+    maxReads?: number | undefined;
+    maxWrites?: number | undefined;
+    log?: LogFn | undefined;
+}
+export declare function outsideProject(file: unknown, project: string): Promise<string>;
+export declare function openLinkStore({ file, project, readOnly, readers, maxReads, maxWrites, log }?: LinkStoreOptions): Promise<LinkStore>;

package/dist/types/logging.d.ts

@@ -0,0 +1,9 @@
+export type JsonLogger = (event: object) => void;
+/** What the logger needs from its sink: the members of a Writable it touches. process.stdout satisfies it. */
+export interface LogSink {
+    write(chunk: string): unknown;
+    writableLength: number;
+    destroyed?: boolean;
+    on?(event: 'error', listener: () => void): unknown;
+}
+export declare function createJsonLogger(stream?: LogSink, maxBufferBytes?: number): JsonLogger;

package/dist/types/management-policy.d.ts

@@ -0,0 +1,9 @@
+export type ManagementAction = 'get' | 'list' | 'create' | 'update' | 'delete';
+/** A credential from the operator's management policy file, once it authenticated a request. */
+export interface ManagementPrincipal {
+    id: string;
+    collections: string[];
+    actions: string[];
+}
+export type ManagementAuthorizer = (token: string) => Promise<ManagementPrincipal | undefined>;
+export declare function managementPolicy(file: unknown, project: string): Promise<ManagementAuthorizer>;

package/dist/types/match.d.ts

@@ -0,0 +1,81 @@
+export type ParameterLocation = 'path' | 'query' | 'header';
+export type ScalarType = 'string' | 'integer' | 'number' | 'boolean';
+export type Scalar = string | number | boolean;
+/** A parsed scalar, a parsed array, or a schema default (which the schema may shape freely). */
+export type ParameterValue = Scalar | Scalar[] | unknown;
+export interface ParameterSchema {
+    type: ScalarType | 'array';
+    items?: {
+        type: ScalarType;
+    };
+    default?: unknown;
+    [keyword: string]: unknown;
+}
+export interface CompiledParameter {
+    name: string;
+    in: ParameterLocation;
+    required: boolean;
+    schema: ParameterSchema;
+    validate: (value: unknown) => boolean;
+}
+/** A value taken from a request input or a binding when a redirect is assembled. */
+export interface ValueRef {
+    from?: ParameterLocation;
+    name?: string;
+    env?: string;
+    secret?: string;
+}
+export interface RedirectSpec {
+    url: string;
+    query?: {
+        map?: Record<string, ValueRef | Scalar>;
+        pass?: string[];
+    };
+}
+/** The part of a compiled route that request-time matching reads. router.ts widens it. */
+export interface MatchableRoute {
+    pattern: string;
+    parts: string[];
+    prefix?: string;
+    parameters: CompiledParameter[];
+    env: Record<string, string>;
+    secrets: Record<string, string>;
+    redirect?: RedirectSpec;
+}
+export interface CompiledRoutes<R extends MatchableRoute = MatchableRoute> {
+    exact: Map<string, R>;
+    byLength: Map<number, R[]>;
+    mounts: R[];
+}
+export interface Target {
+    path: string;
+    parts: string[];
+    query: URLSearchParams;
+}
+export interface Match<R extends MatchableRoute = MatchableRoute> {
+    route: R;
+    path: Record<string, string>;
+}
+export interface Inputs {
+    path: Record<string, string>;
+    query: Record<string, ParameterValue>;
+    header: Record<string, ParameterValue>;
+}
+export interface RequestContext {
+    inputs: Inputs;
+    env: Record<string, string>;
+    secrets: Record<string, string>;
+}
+/** The subset of Headers both a node:http-derived map and the Fetch Headers class provide. */
+export interface HeadersLike {
+    has(name: string): boolean;
+    get(name: string): string | null | undefined;
+}
+export declare function parameterName(segment: string): string | null;
+export declare function resolveValue(ref: ValueRef | Scalar | null | undefined, context: RequestContext): ParameterValue;
+export declare function parseTarget(target: string): Target;
+export declare function matchRoute<R extends MatchableRoute>(compiled: CompiledRoutes<R>, target: Target): Match<R> | null;
+export declare function contextFor(route: MatchableRoute, path: Record<string, string>, query: URLSearchParams, headers: HeadersLike, headerCounts?: Record<string, number>): RequestContext;
+export declare function redirectLocation(route: MatchableRoute & {
+    redirect: RedirectSpec;
+}, context: RequestContext, query: URLSearchParams): string;