@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/examples/egress/urlcode.yaml

@@ -0,0 +1,19 @@
+version: "1"
+routes:
+  /proxy/{id}:
+    proxy:
+      url: https://api.example.com/items/{id}
+      query: [page]
+      requestHeaders: [accept]
+      responseHeaders: [content-type, content-encoding]
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+  /event:
+    respond:
+      text: Accepted
+    signals:
+      - url: https://hooks.example.com/events

package/examples/extensions/README.md

@@ -0,0 +1,7 @@
+# Operator extension fixture
+
+This project declares two logical extensions and two protected routes: `/private` spells out `policies.extensions.demo`, while `/account` uses the route-level `auth` short form that expands to `policies.extensions.auth`. It contains no host modules or credentials. `test/extensions.test.ts` loads this exact YAML with an explicitly supplied demo registry and exercises both endpoints.
+
+Runtime activation requires an external operator registry with a reviewed, static `projectSha256` matching `inspectExtensionRevision(project)`, plus an explicit canonical origin. Inspecting a revision does not grant it. The registry supplies versioned configuration and policy schemas and trusted host callbacks. Missing providers or mismatched revisions fail before activation. Cloudflare refuses this feature until an explicit Worker implementation exists.
+
+The demo provider in the test is a protocol fixture, not authentication suitable for deployment. Real auth and admin services live in separate packages and supply their own registries.

package/examples/extensions/example.yaml

@@ -0,0 +1,21 @@
+id: extensions
+description: Two declared operator extensions, one mount and two protected routes, one through the route-level auth short form.
+tags: [extensions, auth, operator, mount, protected, policies.extensions, registry, revision]
+complexity: advanced
+capabilities: [enabled, extension, methods, policies.extensions, respond]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+routes: 3
+services:
+  - name: operator registry
+    description: RuntimeExtension registrations for demo and auth with a reviewed projectSha256; test/extensions.test.ts supplies one.
+grants:
+  - kind: extension
+    description: Each registration pins this revision; inspecting the hash grants nothing.
+  - kind: origin
+    description: The canonical origin every activation needs.
+files: [urlcode.yaml, README.md]
+tests:
+  commands:
+    - node src/cli.ts validate --local --project examples/extensions --host-file /operator/host.mjs --origin https://extensions.example.test
+behavior:
+  - "/account uses auth: {role: member}; routes and audit show the expanded policies.extensions.auth form"

package/examples/extensions/urlcode.yaml

@@ -0,0 +1,25 @@
+version: '1'
+extensions:
+  demo:
+    version: '1'
+    config:
+      label: hello
+  auth:
+    version: '1'
+    config: {}
+routes:
+  /demo/*:
+    extension: demo
+    methods: [GET, HEAD, POST]
+  /private:
+    respond:
+      text: private
+    policies:
+      extensions:
+        demo:
+          role: member
+  /account:
+    respond:
+      text: account
+    auth:
+      role: member

package/examples/live-links/example.yaml

@@ -0,0 +1,21 @@
+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/monitoring/example.yaml

@@ -0,0 +1,8 @@
+id: monitoring
+description: Prometheus scrape jobs, blackbox probes, alert rules and a Vector pipeline for a running URLCode deployment.
+tags: [monitoring, prometheus, alerts, blackbox, vector, metrics, health, ready, observability, logs]
+complexity: intermediate
+runnable: false
+files: [prometheus-scrape.yaml, blackbox-jobs.yaml, prometheus-rules.yaml, vector.toml]
+behavior:
+  - probes /_urlcode/health and /_urlcode/ready separately so a live but not ready process is visible

package/examples/prerender/example.yaml

@@ -0,0 +1,16 @@
+id: prerender
+description: Pages rendered by a function and a template middleware, then prerendered at build time into native page routes.
+tags: [prerender, build, static, pages, template, function, middleware, html, render]
+complexity: advanced
+capabilities: [enabled, function, methods, middleware]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 3
+files: [urlcode.yaml, functions/page.mjs, middleware/template.mjs, prerender.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts test --project examples/prerender
+    - node examples/prerender/prerender.mjs examples/prerender /absolute/out
+    - node src/cli.ts audit --project /absolute/out --expect-routes 3
+behavior:
+  - the rendered project serves the same bytes from native page routes with no sandbox on the request path

package/examples/provider-conformance/README.md

@@ -0,0 +1,12 @@
+# Provider conformance fixture
+
+Deploy only this synthetic project to a disposable, operator-owned environment
+using the documented self-hosted, AWS, Vercel or Cloudflare runtime adapter.
+Never install it into a project containing private/customer routes or credentials.
+The fixture has no function code, bindings, assets, policies or provider settings.
+All redirect destinations use the reserved `example.test` domain; the verifier
+never follows them. POST requests return constants and have no side effects.
+
+See [provider verification](../../docs/PROVIDER-VERIFICATION.md) for the runner,
+evidence format and limitations. CI replays the fixture through local adapters;
+that does not establish that any provider deployment has been verified.

package/examples/provider-conformance/example.yaml

@@ -0,0 +1,14 @@
+id: provider-conformance
+description: Synthetic redirect and respond fixture deployed to a disposable environment so urlcode verify-provider can observe a real adapter.
+tags: [provider, conformance, verify, deployment, fixture, aws, vercel, cloudflare, self-hosted, probes]
+complexity: intermediate
+capabilities: [enabled, methods, parameters, redirect, request.body, respond, response.headers]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+routes: 5
+files: [urlcode.yaml, README.md]
+tests:
+  commands:
+    - node src/cli.ts validate --local --project examples/provider-conformance
+    - node src/cli.ts verify-provider --target self-hosted --origin https://owned-fixture.example
+behavior:
+  - no functions, bindings, assets or policies, so every target activates it; never mix it into a real project

package/examples/provider-conformance/urlcode.yaml

@@ -0,0 +1,34 @@
+version: "1"
+routes:
+  /urlcode-conformance/redirect:
+    redirect:
+      url: https://example.test/destination
+  /urlcode-conformance/people/{name}:
+    parameters:
+      - name: name
+        in: path
+        required: true
+        schema: {type: string}
+    redirect:
+      url: https://example.test/people/{name}
+      status: 307
+  /urlcode-conformance/query:
+    parameters:
+      - name: n
+        in: query
+        required: true
+        schema: {type: integer}
+    redirect:
+      url: https://example.test/query
+      query:
+        map:
+          n: {from: query, name: n}
+  /urlcode-conformance/hello:
+    respond: {text: provider conformance v1}
+    response:
+      headers: {x-conformance: v1}
+  /urlcode-conformance/body:
+    methods: [POST]
+    request:
+      body: {maxBytes: 32}
+    respond: {text: accepted}

package/examples/tunnel/example.yaml

@@ -0,0 +1,8 @@
+id: tunnel
+description: Shell script starting urlcode dev with the public origin of a running ngrok tunnel.
+tags: [tunnel, ngrok, dev, origin, local, script, public-url]
+complexity: starter
+runnable: false
+files: [dev-with-ngrok.sh]
+behavior:
+  - functions, redirects and absolute URLs see the address a visitor used rather than 127.0.0.1

package/examples/vercel/example.yaml

@@ -0,0 +1,19 @@
+id: vercel
+description: Native-handler project deployed as a Vercel Node function through the vercel adapter.
+tags: [vercel, serverless, deploy, adapter, native, page, static, redirect, respond]
+complexity: intermediate
+capabilities: [enabled, methods, page, parameters, redirect, respond, static]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+routes: 5
+services:
+  - name: Vercel
+    description: api/index.js and vercel.json deploy the project; local tests replay the adapter without an account.
+files: [urlcode.yaml, api/index.js, vercel.json, public/index.html, public/notes.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/vercel
+    - node src/cli.ts test --project examples/vercel
+    - node src/cli.ts audit --project examples/vercel --expect-routes 5
+behavior:
+  - every route is native, so the project activates on Vercel without the sandbox