@jimhoyd/urlcode 0.3.0

package/dist/types/runtime.d.ts

@@ -0,0 +1,91 @@
+import type { ProjectPlan } from './readiness.ts';
+import type { OperatorPolicy } from './policy.ts';
+import type { LinkStoreOptions } from './link-store.ts';
+import type { Plugin } from './plugins.ts';
+import type { MetricsSnapshot, Observer } from './observability.ts';
+import type { HandlerResult, HeaderPair } from './http-response.ts';
+import type { LogFn, PolicyInventory, TargetName } from './types.ts';
+/** A stored link as a link store returns it; the runtime validates the fields it uses. */
+export interface LinkLookup {
+    url?: unknown;
+    status?: unknown;
+    enabled?: unknown;
+    expires?: unknown;
+}
+/** What a `linkStores` binding must provide: a reader and, optionally, its health. */
+export interface LinkReader {
+    get(collection: string, code: string): Promise<LinkLookup | null | undefined>;
+    readonly readHealthy?: boolean;
+    readonly healthy?: boolean;
+}
+/** An operator-owned SQLite link store the runtime opens read-only for one collection. */
+export interface LinkStoreBinding extends LinkStoreOptions {
+    collection: string;
+}
+export type { OperatorPolicy } from './policy.ts';
+/** An operator plugin (src/plugins.ts). */
+export type HostPlugin = Plugin;
+export type { Observer, MetricsSnapshot } from './observability.ts';
+export interface TestPlan extends ProjectPlan {
+    dynamicLinks: boolean;
+    policies: Record<string, PolicyInventory>;
+}
+export interface RuntimeOptions {
+    observers?: Observer[] | undefined;
+    log?: LogFn | undefined;
+    origin?: string | undefined;
+    local?: boolean | undefined;
+    environment?: NodeJS.ProcessEnv | undefined;
+    permissions?: OperatorPolicy | undefined;
+    linkStore?: LinkStoreBinding | undefined;
+    linkStores?: Record<string, LinkReader> | undefined;
+    target?: TargetName | undefined;
+    plugins?: HostPlugin[] | undefined;
+    workers?: number | undefined;
+    timeoutMs?: number | undefined;
+    maxBytes?: number | undefined;
+}
+/** Per-request facts the host may read after handle() settles; never request text. */
+export interface LinkTrace {
+    collection: string;
+    code: string | null;
+    result: string;
+}
+export interface RequestTrace {
+    route?: string;
+    probe?: boolean;
+    client?: string | null;
+    link?: LinkTrace;
+}
+export interface RuntimeRequest {
+    target: string;
+    method?: string | undefined;
+    headers?: Headers | undefined;
+    body?: Uint8Array | undefined;
+    headerCounts?: Record<string, number> | undefined;
+    trace?: RequestTrace | undefined;
+    origin?: string | undefined;
+    client?: string | undefined;
+}
+export interface Runtime {
+    readonly healthy: boolean;
+    assetWatch: string[];
+    version: string;
+    count: number;
+    root: string;
+    testPlan(): TestPlan;
+    readonly plugins: {
+        name: string;
+        version: string;
+    }[];
+    readonly workers: {
+        healthy: number;
+        slots: number;
+    };
+    metrics(): MetricsSnapshot;
+    errorHeaders(error: unknown, origin: string): HeaderPair[];
+    requestLimit(target: string): number | undefined;
+    handle(request: RuntimeRequest): Promise<HandlerResult>;
+    close(): Promise<void>;
+}
+export declare function createRuntime(project: string, rawOptions?: RuntimeOptions): Promise<Runtime>;

package/dist/types/scaffold.d.ts

@@ -0,0 +1,17 @@
+export interface Unresolved {
+    path?: string;
+    reason: string;
+    collection?: string;
+}
+export interface ScaffoldReport {
+    dryRun: boolean;
+    dynamicLinks: boolean;
+    created: string[];
+    preserved: string[];
+    unresolved: Unresolved[];
+    requiredBindings: string[];
+    needsImplementation: true;
+}
+export declare function scaffoldProject(project: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<ScaffoldReport>;

package/dist/types/server.d.ts

@@ -0,0 +1,37 @@
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { RuntimeOptions, TestPlan } from './runtime.ts';
+import type { LinkObserverStats } from './link-events.ts';
+import type { MetricsSnapshot, Observer } from './observability.ts';
+export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
+    project?: string | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+    watch?: boolean | undefined;
+    maxBodyBytes?: number | undefined;
+    maxInFlightRequests?: number | undefined;
+    maxInFlightHealthRequests?: number | undefined;
+    requestLog?: string | undefined;
+    trustRequestId?: boolean | undefined;
+    linkEvents?: unknown;
+    trustedProxies?: string | string[] | undefined;
+    observers?: Observer[] | undefined;
+    metrics?: boolean | undefined;
+    metricsIntervalMs?: number | undefined;
+}
+export interface Server {
+    server: http.Server;
+    reload(): Promise<boolean>;
+    address: AddressInfo;
+    root: string;
+    testPlan(): TestPlan;
+    linkEventStats(): LinkObserverStats | undefined;
+    metrics(): MetricsSnapshot;
+    readonly observers: {
+        name: string;
+        version: string;
+    }[];
+    origin: string;
+    close(): Promise<void>;
+}
+export declare function startServer({ project, host, port, watch, local, log, maxBodyBytes, maxInFlightRequests, maxInFlightHealthRequests, requestLog, trustRequestId, origin, linkEvents, trustedProxies, observers, metrics, metricsIntervalMs, ...runtimeOptions }?: ServerOptions): Promise<Server>;

package/dist/types/site.d.ts

@@ -0,0 +1,12 @@
+import type { LoadedDocument, LogFn, ProjectDocument, RouteConfig, SiteConfig } from './types.ts';
+export interface SiteOptions {
+    origin?: string | undefined;
+    log?: LogFn;
+    routes?: Record<string, RouteConfig>;
+}
+type SiteKey = keyof SiteConfig;
+export declare const generatedPaths: Readonly<Record<SiteKey, string>>;
+export declare const MAX_SITEMAP_URLS = 50000;
+export declare function expandSite(document: ProjectDocument, root: string, { origin, log, routes }?: SiteOptions): Promise<Record<string, RouteConfig>>;
+export declare function applySite(loaded: LoadedDocument, options?: SiteOptions): Promise<Record<string, RouteConfig>>;
+export {};

package/dist/types/sqlite-version.d.ts

@@ -0,0 +1 @@
+export declare function supportsConcurrentWal(version: unknown): boolean;

package/dist/types/types.d.ts

@@ -0,0 +1,332 @@
+import type { HandlerResult, HeaderPair } from './http-response.ts';
+import type { CompiledParameter, MatchableRoute, ParameterLocation, ParameterSchema, RedirectSpec, Scalar, ValueRef } from './match.ts';
+import type { HttpRoute, Reply, RequestBodyPolicy, RespondSpec } from './http-policy.ts';
+import type { AgentsConfig, AgentsDescription, AgentsState } from './policies/agents.ts';
+import type { SecurityConfig, SecurityDescription, SecurityState } from './policies/security.ts';
+import type { CacheConfig, CacheDescription, CacheState, CacheStore } from './policies/cache.ts';
+import type { CompressionConfig, CompressionDescription, CompressionState } from './policies/compression.ts';
+import type { ThrottleConfig, ThrottleDescription, ThrottleState, ThrottleTable } from './policies/throttle.ts';
+/** An operator log sink; every record is a flat JSON object with an `event` name. */
+export type LogFn = (event: Record<string, unknown>) => void;
+/** One declared input: a path placeholder, a query parameter or a request header. */
+export interface ParameterConfig {
+    name: string;
+    in: ParameterLocation;
+    required?: boolean;
+    schema: ParameterSchema;
+}
+/** `env` binding: a literal `value`, or the `env` name to read from the process environment. */
+export interface EnvBinding {
+    value?: string;
+    env?: string;
+}
+/** `secrets` binding: the `secret` name to read from the process environment. */
+export interface SecretBinding {
+    secret: string;
+}
+export interface FunctionConfig {
+    source: string;
+    export?: string;
+    args?: Record<string, ValueRef | Scalar>;
+}
+export interface MiddlewareConfig {
+    source: string;
+    export?: string;
+}
+export interface LinkConfig {
+    collection: string;
+    code: ValueRef;
+}
+export interface PageConfig {
+    file: string;
+    contentType?: string;
+    cacheControl?: string;
+}
+export interface DownloadConfig extends PageConfig {
+    filename?: string;
+}
+export interface StaticConfig {
+    directory: string;
+    contentType?: string;
+    cacheControl?: string;
+    index?: string;
+}
+/** `redirect` as declared: `query.pass` may be `false` (the schema allows it; readers treat it as an empty list). */
+export interface RedirectConfig {
+    url: string;
+    status?: 301 | 302 | 303 | 307 | 308;
+    query?: {
+        pass?: string[] | false;
+        map?: Record<string, ValueRef | Scalar>;
+    };
+}
+export type PolicyName = 'agents' | 'throttle' | 'cache' | 'security' | 'compression';
+/** Each first-party policy's YAML configuration, keyed by its `policies` name. */
+export interface PolicyConfigs {
+    agents: AgentsConfig;
+    throttle: ThrottleConfig;
+    cache: CacheConfig;
+    security: SecurityConfig;
+    compression: CompressionConfig;
+}
+/** One `policies` block or profile layer: every policy optional, `false` disables it. */
+/** One layer of policy configuration (profile, project or route); a layer may declare part of a policy, the merge supplies the rest. */
+export type PolicyLayer = {
+    [K in PolicyName]?: Partial<PolicyConfigs[K]> | false;
+};
+export interface PoliciesConfig extends PolicyLayer {
+    profile?: string;
+}
+/** The result of layering profiles and route keys: what compiles, per policy. */
+export type EffectivePolicies = Partial<PolicyConfigs>;
+export interface RobotsConfig {
+    disallow?: string[];
+    allow?: string[];
+    sitemap?: boolean;
+    extra?: string[];
+}
+export type Changefreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+export interface SitemapConfig {
+    exclude?: string[];
+    changefreq?: Changefreq;
+    priority?: number;
+}
+export interface SecurityTxtConfig {
+    contact: string[];
+    expires: string;
+    policy?: string[];
+    acknowledgments?: string[];
+    preferredLanguages?: string[];
+    canonical?: string[];
+    encryption?: string[];
+}
+export interface SiteConfig {
+    robots?: RobotsConfig;
+    sitemap?: true | SitemapConfig;
+    favicon?: string;
+    securityTxt?: SecurityTxtConfig;
+    llms?: string;
+}
+/** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
+export interface RouteConfig {
+    methods?: string[];
+    enabled?: boolean;
+    expires?: string;
+    description?: string;
+    parameters?: ParameterConfig[];
+    redirect?: RedirectConfig;
+    function?: FunctionConfig;
+    env?: Record<string, EnvBinding>;
+    secrets?: Record<string, SecretBinding>;
+    page?: PageConfig;
+    download?: DownloadConfig;
+    static?: StaticConfig;
+    request?: {
+        body?: RequestBodyPolicy;
+    };
+    response?: {
+        headers?: Record<string, string | string[]>;
+    };
+    respond?: RespondSpec;
+    middleware?: MiddlewareConfig[];
+    link?: LinkConfig;
+    policies?: PoliciesConfig;
+    /** Set by site.ts on a route it generated (`site.<key>`); never declared in YAML. */
+    generated?: string;
+}
+export interface ProjectDocument {
+    version: '1';
+    routes: Record<string, RouteConfig>;
+    includes?: string[];
+    dynamicLinks?: boolean;
+    policies?: PoliciesConfig;
+    profiles?: Record<string, PolicyLayer>;
+    site?: SiteConfig;
+}
+/** What config.ts returns: the entry document, the merged route table and the files it came from. */
+export interface LoadedDocument {
+    root: string;
+    document: ProjectDocument;
+    routes: Record<string, RouteConfig>;
+    files: string[];
+    version: string;
+}
+export interface CompiledFunction {
+    source: string;
+    export: string;
+    args?: Record<string, ValueRef | Scalar>;
+}
+export interface CompiledMiddleware {
+    source: string;
+    export: string;
+}
+/** One file read into the asset snapshot; a static route holds a Map of them keyed by relative path. */
+export interface Asset {
+    body: Buffer;
+    modified: string;
+    type: string;
+    attachment: string | undefined;
+    etag: string;
+    cache: string;
+    /** Precompressed variants the compression policy attaches at compile time, keyed by content coding. */
+    encoded?: Record<string, Buffer>;
+}
+/** A handler result that came from the asset snapshot, so a later policy can serve a stored variant by identity. */
+export interface AssetResult extends HandlerResult {
+    asset?: Asset;
+}
+/** `redirect` once compiled: `query.pass` is a list or absent (a declared `false` is dropped), so match.ts's RedirectSpec holds. */
+export interface CompiledRedirect extends RedirectSpec {
+    status?: 301 | 302 | 303 | 307 | 308;
+}
+/**
+ * The route the router produces: the YAML route with its bindings resolved,
+ * its parameters compiled and everything request-time matching, the HTTP
+ * policy and the asset snapshot need. Widens MatchableRoute (match.ts).
+ */
+export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters' | 'env' | 'secrets' | 'function' | 'middleware' | 'redirect'>, MatchableRoute, HttpRoute {
+    pattern: string;
+    parts: string[];
+    names: string[];
+    specificity: number;
+    methods: string[];
+    parameters: CompiledParameter[];
+    env: Record<string, string>;
+    secrets: Record<string, string>;
+    redirect?: CompiledRedirect;
+    responseHeaders: HeaderPair[];
+    reply?: Reply;
+    expiresAt?: number;
+    prefix?: string;
+    middleware: CompiledMiddleware[];
+    function?: CompiledFunction;
+    respond?: RespondSpec;
+    page?: PageConfig;
+    download?: DownloadConfig;
+    static?: StaticConfig;
+    /** Attached by compileAssets: one asset for page/download, a Map for static. */
+    asset?: Asset | Map<string, Asset>;
+    /** Attached by the runtime once policies compile; null when the project declares none. */
+    policy?: PolicyChain | null;
+    /** Attached by build-cloudflare: the compiled policy states shipped in the Worker artifact. */
+    compiledPolicies?: Record<string, unknown>;
+}
+export interface CompiledRouteTable {
+    exact: Map<string, CompiledRoute>;
+    byLength: Map<number, CompiledRoute[]>;
+    mounts: CompiledRoute[];
+    /** Absolute paths of every function module the routes reference. */
+    modules: string[];
+    count: number;
+}
+export type TargetName = 'node' | 'vercel' | 'aws' | 'cloudflare';
+export type PolicySupport = 'native' | 'compiled' | 'delegated' | 'refused';
+/** Per-runtime state policies share; released by closePolicies. Each policy owns one key. */
+export interface PolicyShared {
+    target?: string;
+    log?: LogFn;
+    routes?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+    cache?: CacheStore;
+    throttle?: ThrottleTable;
+    compressionBytes?: number;
+}
+/** The route facts a policy may read at compile time; a CompiledRoute satisfies it, tests pass less. */
+export interface PolicyRoute {
+    pattern: string;
+    secrets?: Record<string, string>;
+    methods?: readonly string[];
+    responseHeaders?: readonly HeaderPair[];
+    asset?: Asset | Map<string, Asset>;
+    policies?: PoliciesConfig;
+}
+export interface PolicyContext {
+    route: PolicyRoute;
+    shared: PolicyShared;
+    target?: TargetName;
+    document?: ProjectDocument;
+    root?: string;
+}
+/** The request a policy sees (built by policyRequest): runtime objects, never re-parsed text. */
+export interface PolicyRequest {
+    method: string;
+    target: string;
+    path: string;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    /** The Fetch Headers surface (agents.ts reads it on the Worker); the Node host wraps its header map to match. */
+    headers: {
+        has(name: string): boolean;
+        get(name: string): string | null;
+    };
+    headerCounts: Record<string, number> | undefined;
+    client: string | null;
+    origin: string | undefined;
+    route: string;
+    secrets: boolean;
+}
+/**
+ * One policy module. Hooks are declared as methods so a module typed with its
+ * own Config and State (PolicyModule<CacheConfig, CacheState>) is assignable
+ * to the erased PolicyModule the registry and the compiled chain hold.
+ */
+export interface PolicyModule<Config = unknown, State = unknown, Description extends object = object> {
+    name: string;
+    phases: readonly string[];
+    targets(config: Config): Record<TargetName, PolicySupport>;
+    compile(config: Config, context: PolicyContext): State | Promise<State>;
+    onRequest?(state: State, request: PolicyRequest): HandlerResult | undefined | Promise<HandlerResult | undefined>;
+    onResponse?(state: State, request: PolicyRequest, result: HandlerResult): HandlerResult | Promise<HandlerResult>;
+    onError?(state: State, request: PolicyRequest, error: unknown): HandlerResult | undefined | void | Promise<HandlerResult | undefined | void>;
+    /** A JSON summary for the audit and inventory; each module returns its own description shape. */
+    describe?(state: State): Description;
+    close?(shared: PolicyShared): void | Promise<void>;
+}
+export interface PolicyStates {
+    agents: AgentsState;
+    throttle: ThrottleState;
+    cache: CacheState;
+    security: SecurityState;
+    compression: CompressionState;
+}
+export interface PolicyDescriptions {
+    agents: AgentsDescription;
+    throttle: ThrottleDescription;
+    cache: CacheDescription;
+    security: SecurityDescription;
+    compression: CompressionDescription;
+}
+/** A route's policy inventory: each policy's describe() plus the support it got; a delegated policy carries only `target`. */
+export type PolicyInventory = {
+    [K in PolicyName]?: Partial<PolicyDescriptions[K]> & {
+        target: PolicySupport;
+    };
+};
+/** A module paired with the state it compiled for one route, in phase order. */
+export type PolicyEntry = [PolicyModule, unknown];
+/** What compilePolicies returns for a route: ordered hook chains, the audit summary and each state by name. */
+export type PolicyChain = {
+    request: PolicyEntry[];
+    response: PolicyEntry[];
+    error: PolicyEntry[];
+    describe: PolicyInventory;
+} & Partial<PolicyStates>;
+export type RouteState = 'active' | 'disabled' | 'expired';
+/** One route in the audit inventory: its handler kind, methods and lifecycle state. */
+export interface PlanInventoryEntry {
+    path: string;
+    handler: string | undefined;
+    methods: string[];
+    middleware: number;
+    policies: string[];
+    generated?: string;
+    state: RouteState;
+}
+export interface TestPlan {
+    inventory: PlanInventoryEntry[];
+    cases: unknown[];
+    resolve?(path: string): string | undefined;
+    dynamicLinks?: boolean;
+    policies?: Record<string, PolicyInventory>;
+}

package/dist/types/vercel.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Environment } from './adapters.ts';
+import type { HostPlugin } from './runtime.ts';
+export interface VercelHandlerOptions {
+    project?: string | undefined;
+    origin?: string | undefined;
+    environment?: Environment | undefined;
+    maxBodyBytes?: number | undefined;
+    plugins?: HostPlugin[] | undefined;
+}
+export type VercelHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins }?: VercelHandlerOptions): VercelHandler;