@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.2

package/docs/links/pools.md

@@ -1,75 +0,0 @@
-# Dynamic links: Reader and writer pools
-
-Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
-
-## Separate reader and writer pools
-
-Pool sizes are operator infrastructure settings, not portable behavior YAML.
-`dynamicLinks: true` and logical collection names stay the same across targets.
-
-```sh
-urlcode serve --project ./my-links \
-  --link-store links=/absolute/links.sqlite \
-  --link-readers 4 --link-read-limit 32
-
-urlcode links api --project ./my-links \
-  --store /absolute/links.sqlite --token-file /absolute/link-admin.token \
-  --link-readers 2 --link-read-limit 16 --link-write-limit 8
-```
-
-| Control | Default | Meaning |
-|---|---|---|
-| `--link-readers` / JS `readers` | 2 | 1–8 read-only connections per store instance |
-| `--link-read-limit` / JS `maxReads` | 32 | 1–32 admitted reads across all readers, not per reader |
-| `--link-write-limit` / JS `maxWrites` | 32 | 1–32 admitted mutations across the single writer |
-
-`get` and `list` use the least-busy healthy reader. `create`, `update` and `delete`
-use the writer. Each worker serializes its own accepted operations. There is no
-additional unbounded acquisition queue. A read flood cannot take writer admission
-and a mutation backlog cannot take reader admission. CPU, disk, database locks
-and the event loop remain shared resources: separation is not an isolation SLA.
-A write response resolves after commit; a subsequent awaited read sees committed
-data on the same database. Reads started before the commit may see the old value.
-There is no replica lag or application cache in this adapter.
-
-`openLinkStore({file, project, readOnly, readers, maxReads, maxWrites})` exposes
-`stats()` with separate read/write connection counts, healthy counts, in-flight
-counts, limits, completed/failed/rejected totals and cumulative durationMs. These
-process-local counters reset at restart and are for trusted operator monitoring;
-there is no public metrics endpoint/exporter yet. `readHealthy` and `writeHealthy`
-are separate. Public runtime readiness uses `readHealthy` when available; management
-operators must monitor writer health separately. A read-only pool has zero writers
-and rejects mutations. Shutdown drains both groups and rejects new admission.
-
-Do not multiply connection counts blindly across processes: N public replicas at
-R readers use N×R connections, plus management readers/writers. Each connection
-has its own worker and memory budget. Measure mixed load and lock contention;
-adding readers can reduce performance on an already saturated disk.
-
-SQLite WAL supports simultaneous readers and a single active writer across the
-database. Multiple writer connections cannot create parallel write throughput.
-All connections must access the same local database on one host; never mount it
-across hosts over a network filesystem. See [SQLite WAL](https://www.sqlite.org/wal.html).
-We require a Node build with SQLite 3.51.3+ or patched branches 3.50.7+/3.44.6+
-to avoid the documented [WAL-reset concurrency bug](https://www.sqlite.org/wal.html#the_wal_reset_bug).
-Live-link initialization checks this before opening files and verifies WAL mode.
-Use `urlcode doctor` to inspect the bundled SQLite version; upgrade Node when
-rejected. Static YAML projects do not require SQLite.
-
-For multi-host scaling, a future server-database adapter must provide distinct
-read/write credentials and pool budgets, connect/acquire/query deadlines,
-transactional version checks, primary-read or explicit replica consistency,
-replica-lag monitoring, migration coordination, backup/restore and failover drills.
-These are adapter acceptance requirements, not implemented PostgreSQL support.
-Keep writes on the primary and avoid automatic retries of ambiguous commits.
-The existing operator adapter boundary remains available, but deploying a custom
-adapter requires its own conformance/load/recovery evidence.
-
-## Shutdown and management defaults
-
-`links api` defaults to private address `127.0.0.1:3001`; public serving defaults
-to port 3000. Endpoint method errors return 405 with an `Allow` header.
-Store shutdown rejects new work, drains accepted operations within each connection and
-then closes SQLite. Repeated `close()` calls share completion. Existing operation
-deadlines still apply: a timeout can leave a mutation outcome unknown, so read
-the record before retrying. Missing/invalid revision metadata rejects startup.

package/docs/links/setup.md

@@ -1,135 +0,0 @@
-# Dynamic links: Setup: requirements, YAML and the example
-
-Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
-
-## Node build requirement
-
-Live links need a Node build carrying the patched SQLite WAL fix: SQLite 3.51.3
-or newer, 3.50.7 or 3.44.6. Node bundles SQLite, so this is a property of the
-build, not something you can install separately, and some current releases on a
-supported Node line ship an unpatched version. Run `urlcode doctor` and check
-`liveLinks`; activation fails closed and names the detected version when the
-build is unsuitable. Everything except live links works on any supported Node.
-
-Available in URLCode 0.1.0. Define a stable route once; create, update and delete
-short-code records while `serve` keeps running. No YAML rewrite, route snapshot
-rebuild, Git commit or public-server restart is needed for record changes.
-
-This first adapter uses optional SQLite storage on one host. Multiple processes
-on that host can share it. No database is required for ordinary YAML-defined
-routes. Network filesystems, multi-host replication and serverless ephemeral disks
-are not supported by this adapter. SQLite WAL requires processes on the same
-host; see [SQLite WAL](https://www.sqlite.org/wal.html).
-
-## Behavior in YAML, data outside Git
-
-```yaml
-version: "1"
-dynamicLinks: true
-routes:
-  /r/{code}:
-    parameters:
-      - name: code
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 128}
-    link:
-      collection: links
-      code: {from: path, name: code}
-```
-
-`link` is a seventh primary handler, exclusive with `function`, `redirect`,
-`respond`, `page`, `static` and `download`. Its `code` is a declared path-input
-reference. `collection` is a logical name, not a filesystem path. GET and HEAD
-are supported; normal route precedence, lifecycle and input validation apply.
-An exact YAML route can intentionally shadow a stored code's URL.
-
-The operator binds `links` to a database outside the project. YAML cannot choose
-a database file or grant itself storage. The built-in public binding opens it
-read-only. It performs an indexed database lookup for each request, with no
-application cache or negative cache. Requests starting after an acknowledged
-mutation can see it immediately; an already-running request can finish with an
-older result. Browser/proxy caches remain outside that guarantee.
-
-Missing or disabled record: 404. Expired record: 410. Unavailable/overloaded
-store: 503. Invalid code syntax: 404 after route input validation. Redirects
-default to 302 and no-store. Query strings are not forwarded. A record's URL is
-literal HTTP(S), with no embedded credentials, control characters or interpolation.
-It is a redirect, not a server-side fetch. The store does not verify destination
-ownership, safety or availability; application abuse prevention remains necessary.
-
-## Run the included example
-
-From the runtime checkout, choose a private data directory **outside the app**.
-Its parent directory must already exist. The following POSIX-shell example uses
-an operator-created directory; on Windows use an absolute local drive path.
-
-```sh
-mkdir -p ../urlcode-data
-URLCODE_DATA="$(cd ../urlcode-data && pwd)"
-node src/cli.ts links init --store "$URLCODE_DATA/links.sqlite"
-node src/cli.ts links create --store "$URLCODE_DATA/links.sqlite" \
-  --code demo --destination https://example.com/demo
-node src/cli.ts serve --project examples/live-links \
-  --link-store "links=$URLCODE_DATA/links.sqlite" --port 3000
-```
-
-Open `/r/demo`. In a second terminal, run another `links create` with an unused
-code against the same absolute file; its URL works immediately. Omit `--code`
-to generate a cryptographically random 16-character base64url code. Codes allow
-1–128 letters, digits, underscores and hyphens; collection names begin with a
-letter and contain at most 64 letters/digits/underscores/hyphens.
-
-The CLI defaults to collection `links`; specify `--collection` to manage another.
-Serving currently accepts one `--link-store collection=/absolute/file` binding;
-embedded applications may supply multiple adapters. Commands do not copy records
-into YAML or create route definitions automatically.
-
-## Explicit project opt-in
-
-Only the entry `urlcode.yaml` may set `dynamicLinks: true`. It defaults to false;
-the starter writes `dynamicLinks: false` explicitly. Included route files cannot
-set or override it. Any `link` handler, including a disabled route, or runtime
-link-store binding requires the opt-in. This flag means live stored-link records,
-not parameterized redirects, custom functions, middleware or development reload.
-
-`validate`, `routes`, `audit` and `scaffold` reports expose `dynamicLinks` as a
-boolean. Enabling it grants no storage access to guest code and starts no
-management endpoint. The operator still supplies the external store binding;
-management remains a separate authenticated service. Standalone `links` CRUD/API
-commands operate the operator's store independently of this public-runtime flag.
-
-Migration: existing live-link projects must add `dynamicLinks: true` to their
-entry file. Refresh revision-pinned function policies for those projects using
-the normal operator review flow; enabling the capability changes the approval
-digest. Projects that omit it or explicitly set false retain their prior digest.
-To disable, remove `link` declarations and serving-store bindings, then set false
-and validate/redeploy. Editing the flag alone does not stop an already running
-production process or management API. Invalid reloads retain the last-good state.
-
-## Middleware, sandbox and tests
-
-Middleware may wrap a successful link response; the usual native metadata/body
-rules apply. Lookup/missing/disabled/expiry errors happen before middleware. The
-handler does not make database objects available to guest code. Functions still
-have no filesystem, SQL, fetch, storage broker or management token capability.
-Link changes do not alter configuration/source digests or invalidate unrelated
-function-binding grants. Changing YAML still does.
-
-`routes` and `audit --expect-routes` count definitions, not stored records. Link
-routes require explicit successful GET/HEAD fixtures; there is no assumed fixture
-for live data. Seed a disposable test database, then pass `--link-store` to
-validate/test/audit/benchmark. Do not run mutation tests against production.
-
-```sh
-node src/cli.ts test --project examples/live-links --link-store links=/absolute/test-links.sqlite
-node src/cli.ts audit --project examples/live-links --link-store links=/absolute/test-links.sqlite --expect-routes 2
-```
-
-The example expects `demo -> https://example.com/demo` and an unused `not-created`
-code. Tests cover create/update/delete visibility without reload, persistence,
-concurrent conflicts, expiry/disabled semantics, scope, public/admin separation,
-body/token boundaries, overload and acknowledged writes after abrupt writer exit.
-Production durability, sustained load and recovery drills still require validation
-on your actual storage. General application state, WebRTC sessions, user-account
-APIs and arbitrary runtime code registration remain separate future work.

package/docs/yaml/links.md

@@ -1,30 +0,0 @@
-# YAML guide: Live short-link records
-
-Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
-
-## 15. Live short-link records
-
-Set `dynamicLinks: true` in the entry `urlcode.yaml` before adding this route.
-It defaults to false and cannot be enabled by an included file.
-
-```yaml
-  /r/{code}:
-    parameters:
-      - name: code
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 128}
-    link:
-      collection: links
-      code: {from: path, name: code}
-```
-
-The seventh handler resolves stored records without rebuilding YAML. It requires
-an external operator store binding; the [live-link example](../../examples/live-links/README.md)
-has separate setup and fixtures. See [dynamic links](../DYNAMIC-LINKS.md) for CLI/API
-creation, optimistic updates, disabled/expired records, persistence and backups.
-This is not a general database capability for sandboxed functions.
-
-Live-link recipes require `dynamicLinks: true` in the entry `urlcode.yaml`. It is
-false by default and cannot be set in included route files. Parameterized routes
-and functions alone do not need it. See [dynamic-link opt-in](../DYNAMIC-LINKS.md#explicit-project-opt-in).

package/examples/live-links/README.md

@@ -1,11 +0,0 @@
-# Live links without route reloads
-
-Follow [the dynamic-link guide](../../docs/DYNAMIC-LINKS.md) to create an external
-SQLite store and seed `demo -> https://example.com/demo`. Then start this project
-with `--link-store links=/absolute/path/links.sqlite`. Its fixtures expect that
-seed and an unused `not-created` code; use a disposable test store, not production.
-
-Create/update/delete records through the CLI or separate authenticated API while
-the public server keeps serving. YAML, code, route counts and health version do
-not change per link. This example deliberately requires explicit operator storage
-binding; the default starter still runs without a database.

package/examples/live-links/example.yaml

@@ -1,21 +0,0 @@
-id: live-links
-description: Stored links served from an external SQLite store without a route reload, with dynamicLinks enabled in the entry file.
-tags: [links, live, dynamic, sqlite, store, short-links, link, redirect]
-complexity: intermediate
-capabilities: [dynamicLinks, enabled, link, methods, parameters, respond]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
-routes: 2
-services:
-  - name: link store
-    description: An operator-owned SQLite store passed as --link-store, seeded with demo -> https://example.com/demo.
-grants:
-  - kind: link-store
-    description: The store binding is an operator flag, never a project file.
-files: [urlcode.yaml, tests/requests.json, README.md]
-tests:
-  fixtures: tests/requests.json
-  commands:
-    - node src/cli.ts links init --store /absolute/links.sqlite
-    - node src/cli.ts test --project examples/live-links --link-store links=/absolute/links.sqlite
-behavior:
-  - "/r/{code} answers the stored destination for a seeded code and 404 for one that was never created"

package/examples/live-links/tests/requests.json

@@ -1,6 +0,0 @@
-[
-  {"path":"/r/demo","status":302,"expectHeaders":{"location":"https://example.com/demo","cache-control":"no-store"}},
-  {"path":"/r/demo","method":"HEAD","status":302,"expectBody":"","expectHeaders":{"location":"https://example.com/demo"}},
-  {"path":"/r/not-created","status":404},
-  {"path":"/r/demo","method":"POST","status":405,"expectHeaders":{"allow":"GET, HEAD"}}
-]

package/examples/live-links/urlcode.yaml

@@ -1,16 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
-version: "1"
-dynamicLinks: true
-routes:
-  /r/{code}:
-    parameters:
-      - name: code
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 128}
-    link:
-      collection: links
-      code: {from: path, name: code}
-  /about:
-    respond:
-      text: Links are stored separately from this YAML.