Capability Spec Delta: api-host — reserved-prefix contract

Package: @suaveplan/api-host Status: PROPOSED

ADDED Requirements

Requirement: Publishes the canonical reserved-prefix list

@suaveplan/api-host SHALL export HOST_RESERVED_PREFIXES as a frozen ReadonlyArray<string> of every URL path prefix the host (and any first-party engine that has shipped) reserves. The list MUST be normalised (lowercase, leading-slash, no trailing slash) and deduped. Downstream adapters that mount their own routes MUST consult this list (directly or via isReservedPrefix) before mounting and refuse to install on collision.

Scenario: list contains every always-reserved host route

WHEN an adapter reads HOST_RESERVED_PREFIXES
THEN it contains /_host and /internal (always-reserved); /admin, /graphql, /ws, /sse are included once their respective host modules ship

Scenario: list is frozen

WHEN consumer code attempts HOST_RESERVED_PREFIXES.push("/foo")
THEN the assignment throws TypeError

Verified by: src/reserved-prefix/reserved-prefix.test.ts::"HOST_RESERVED_PREFIXES contains always-reserved prefixes" AND src/reserved-prefix/reserved-prefix.test.ts::"HOST_RESERVED_PREFIXES is frozen"

Requirement: Exposes a predicate + assertion helper

The package SHALL export isReservedPrefix(prefix: string): boolean and assertPrefixAvailable(prefix: string, codeFactory: (collision: string) => Error): void. The predicate MUST treat input prefixes case-insensitively after normalisation and MUST match both exact prefixes (/internal reserves /internal) and child paths (/internal/livez is also reserved). The assertion MUST throw the error produced by codeFactory(collision) when reserved, returning void otherwise — letting each adapter surface its own code namespace (AUTH_BA_*, RBAC_*, …) without coupling.

Scenario: predicate matches exact + child paths

WHEN isReservedPrefix("/internal") and isReservedPrefix("/internal/livez") are called
THEN both return true

Scenario: predicate normalises case and trailing slash

WHEN isReservedPrefix("/Internal/") is called
THEN it returns true

Scenario: assertion throws the factory-supplied error on collision

WHEN assertPrefixAvailable("/_host", () => new MyError("X")) is called
THEN the call throws MyError("X")

Scenario: assertion is a no-op when free

WHEN assertPrefixAvailable("/auth", factory) is called and /auth is not in the list
THEN the call returns void and factory is NOT invoked

Verified by: src/reserved-prefix/reserved-prefix.test.ts::"isReservedPrefix matches exact and child paths" AND src/reserved-prefix/reserved-prefix.test.ts::"isReservedPrefix normalises case and trailing slash" AND src/reserved-prefix/reserved-prefix.test.ts::"assertPrefixAvailable throws supplied error on collision" AND src/reserved-prefix/reserved-prefix.test.ts::"assertPrefixAvailable is no-op when prefix is free"

Requirement: Published via `./reserved-prefix` subpath

The contract MUST be importable from @suaveplan/api-host/reserved-prefix so adapters can pull only the predicate surface without bundling the full host. The subpath MUST forward types and runtime export of the same set documented in HOST_RESERVED_PREFIXES, isReservedPrefix, assertPrefixAvailable, normalisePrefix.

Scenario: subpath import works in TypeScript and at runtime

WHEN import { isReservedPrefix } from "@suaveplan/api-host/reserved-prefix" is used
THEN the symbol resolves AND TypeScript types it as (prefix: string) => boolean

Verified by: src/reserved-prefix/reserved-prefix.test.ts::"subpath export resolves and types are forwarded"

3.7 KiB Raw Blame History