rampway 0.3.0 → 0.4.0

package/docs/velocious-deployment-api.md

@@ -0,0 +1,226 @@
+# Velocious callable deployment API
+
+`rampway/velocious` is Rampway's authenticated deployment control plane for a
+Velocious application. Rampway owns every deployment-specific decision and
+calls its normal deploy lifecycle; Velocious supplies only route mounting,
+request/connection scopes, database persistence, background execution, and
+framework error events. Each admitted run is executed by a package-owned
+detached Node worker, not by the request process.
+
+The API accepts no command, path, repository, branch, environment value, log
+request, or arbitrary Git ref. A caller can select only a configured
+project/stage pair, an immutable lowercase 40-character commit SHA reachable
+from that target's approved release branch, and an idempotency key.
+The idempotency key must be a non-secret client-generated value of at most 255
+characters and must not contain any configured bearer token; matching is
+case-sensitive, and such requests are rejected with `422` before run lookup or
+persistence.
+
+## Install and mount
+
+Install Velocious in the application that mounts this optional integration.
+Rampway declares it as an optional peer so applications that only use the CLI
+do not acquire a web-framework dependency.
+
+```sh
+npm install rampway velocious
+```
+
+In the application's Velocious routes file:
+
+```js
+import Routes from "velocious/build/src/routes/index.js"
+import RampwayDeploymentApi from "rampway/velocious"
+import deploymentSecrets from "../config/secrets/deployments.js"
+
+const routes = new Routes()
+
+routes.draw((route) => {
+  route.mount(RampwayDeploymentApi, {
+    at: "/rampway/deployments",
+    accessTokens: deploymentSecrets.rampwayAccessTokens,
+    workerBootstrapPath: "/srv/my-app/control/rampway-velocious-worker.mjs",
+    projects: {
+      "my-app": {
+        stages: {
+          production: {
+            configPath: "/srv/my-app/control/rampway.config.mjs",
+            releaseBranch: "main"
+          }
+        }
+      }
+    }
+  })
+})
+
+export default {routes}
+```
+
+`accessTokens` and every `configPath` are explicit backend configuration.
+`workerBootstrapPath` is also explicit backend configuration. It must be an
+absolute regular module file available in the deployed application release; the
+mount resolves it to its real path before accepting requests. The module is
+loaded only by Rampway's package-owned worker and must default-export a factory
+that reconstructs the host application's Velocious configuration:
+
+```js
+import configurationResolver from "velocious/build/src/configuration-resolver.js"
+
+export default async function createRampwayDeploymentWorkerContext() {
+  return {
+    configuration: await configurationResolver({directory: "/srv/my-app"})
+  }
+}
+```
+
+The factory receives only the bounded stable mount and run identifiers. It must
+load backend-owned configuration and secrets itself; neither bearer tokens nor
+deployment targets are passed to the worker.
+Provision the secrets module outside source control using the application's
+normal secret mechanism. There is deliberately no environment-variable
+fallback. `configPath` must be absolute, and its selected Rampway stage must
+use `remote-git`; the deployment target must have Git access to the stage's
+configured repository. Every `releaseBranch` is checked against Git heads-ref
+rules during mounting, so invalid names such as a trailing dot or `.lock`
+component fail at startup rather than during deployment.
+
+Mount options:
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `at` | yes | HTTP mount prefix. |
+| `accessTokens` | yes | One or more non-empty backend-held bearer tokens. |
+| `projects` | yes | Explicit project/stage allowlist with absolute Rampway config paths and approved release branches. |
+| `databaseIdentifier` | no | Velocious database used for runs/audits; default `default`. |
+| `staleRunTimeoutMs` | no | Ownership lease; default `60000`, minimum `4`. |
+| `workerBootstrapPath` | yes | Absolute backend module that reconstructs the Velocious configuration in the detached worker. |
+
+## Client calls
+
+Create a run from a client whose token is also loaded from explicit backend
+secrets (not an environment fallback or command argument):
+
+```js
+import deploymentClientSecrets from "./config/secrets/deployment-client.js"
+
+const baseUrl = "https://app.example/rampway/deployments"
+const headers = {
+  Authorization: `Bearer ${deploymentClientSecrets.rampwayAccessToken}`,
+  "Content-Type": "application/json"
+}
+const createResponse = await fetch(`${baseUrl}/runs`, {
+  method: "POST",
+  headers,
+  body: JSON.stringify({
+    project: "my-app",
+    stage: "production",
+    revision: "0123456789abcdef0123456789abcdef01234567",
+    idempotencyKey: "release-2026-08-03-1"
+  })
+})
+const created = await createResponse.json()
+```
+
+Read the durable result:
+
+```js
+const runResponse = await fetch(`${baseUrl}/runs/${encodeURIComponent(created.run.id)}`, {headers})
+const {run, current} = await runResponse.json()
+```
+
+Authentication is accepted only from the `Authorization` header. Never place
+the token in a URL or command argument that is logged; clients should obtain it
+from their own secret store and configure the HTTP library's header directly.
+Rampway never includes tokens in response data, run state, audit payloads, Git
+commands, deploy commands, or deployment reports. Adapter values and object
+keys are JSON-normalized and recursively redacted before persistence. Sanitized
+structures are limited to 100 entries per array/object, 1,000 visited values,
+20 levels, 4,000 characters per string, and 64 KiB total serialized output;
+explicit truncation markers and a bounded redacted preview retain diagnostic
+context.
+
+Create responses are bounded:
+
+- `202`: created; execution continues in a separate detached Node process.
+- `200`: matching idempotent replay; the original run is returned.
+- `401`: missing or invalid bearer token.
+- `404`: project/stage is not allowlisted.
+- `409`: key conflict, an active deployment, or operator reconciliation is required.
+- `422`: invalid request parameters.
+
+Run status is one of `pending`, `running`, `succeeded`, `failed`, `interrupted`,
+or `reconciliation_required`. Failed runs include sanitized recovery state.
+An immutable revision that is not reachable from the approved branch is
+recorded as a sanitized failed run rather than discarded before admission.
+Readback also reports the current/previous Rampway release and active revision.
+If live status cannot be read, the response still returns the durable run with
+`live_status: null` and a sanitized `live_status_error` annotation; the outage
+is also sent to Velocious framework error reporting.
+
+## Execution and recovery guarantees
+
+Rampway serializes durable admission and writes the request audit before
+launching the worker. The parent waits for the operating system's child-spawn
+acknowledgement before returning `202`; the worker then claims the pending run
+and writes the heartbeat, lifecycle audits, terminal result, and database
+connections from its own process. Its stdio is ignored rather than inherited,
+and its invocation contains only the immutable bootstrap path and bounded
+mount/run identifiers. A launch error fences the pending run as failed and is
+not retried in the request process.
+
+Rampway serializes durable admission before validating reachability on the
+deployment target, so an idempotent retry storm performs the Git fetch only for
+the created run. It then invokes the same `deploy()` used by the CLI: deploy
+lock, immutable remote-Git release, linked state, build/migration tasks, runtime
+handoff, health checks, `current` link, cleanup, and report persistence. It does
+not implement an alternate deployment engine or arbitrary command bridge. If
+failure occurs after the requested revision becomes active, the executor calls
+Rampway's existing rollback lifecycle with the captured prior current release
+as its explicit target and records whether that previous live state was
+restored.
+
+Runs and audits are stored in `rampway_deployment_runs` and
+`rampway_deployment_api_audit_events`, scoped by a stable hash of the mount.
+Target and idempotency advisory locks prevent duplicate concurrent admission,
+including one key racing across targets. Pending/running/terminal transitions
+are fenced by mount, run, owner, status, and (for stale reconciliation) the
+observed heartbeat. A renewed live owner therefore cannot be reclaimed, and an
+expired owner cannot overwrite a reconciled run.
+
+Pending work is protected by a separate durable launch-to-claim lease while the
+worker imports its bootstrap and reconstructs Velocious. Status polling and
+other admission processes therefore cannot interrupt a legitimately booting
+worker; the lease is cleared atomically by claim or pre-claim failure. If that
+launch lease expires without a claim, the pending run becomes `interrupted` and
+no longer blocks a new run. A stale running run, or a known successful
+activation whose success record could not be persisted, becomes
+`reconciliation_required` and continues to block duplicates until an operator
+verifies live state. Bootstrap failures are recorded as failed and audited when
+the host configuration can still be reconstructed. Audit persistence failure is
+reported through both Velocious `framework-error` and `all-error` events and
+never strands deployment execution.
+Keyed retries and run-status polling evaluate the lease before returning, so a
+dead owner's stale `pending` or `running` state is reconciled without requiring
+a different-key deployment attempt.
+
+## Token rotation and revocation
+
+Use overlapping tokens for zero-downtime rotation:
+
+1. Add a new random token to the backend secrets list and restart/deploy every
+   web worker.
+2. Move every authorized client to the new token.
+3. Remove the old token from backend secrets and restart/deploy every worker
+   again.
+4. Confirm the old token receives `401` on every instance.
+
+For emergency revocation, remove the compromised token and restart all workers
+immediately. Revocation affects new HTTP requests; an already authenticated,
+durably admitted run continues under its owner lease. Inspect the run and audit
+records, reconcile any ambiguous running result, and rotate any repository or
+host credentials independently if they may also be compromised.
+
+Do not print tokens while diagnosing authentication. Record only token version
+or fingerprint metadata in an external secret inventory, never the token
+itself. Rampway framework-error payloads deliberately omit the HTTP request so
+listeners cannot accidentally serialize its Authorization header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,
@@ -54,6 +54,14 @@
       "types": "./build/src/test-helpers.d.ts",
       "default": "./build/src/test-helpers.js"
     },
+    "./velocious": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
+    "./velocious.js": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
     "./package.json": "./package.json"
   },
   "imports": {
@@ -64,8 +72,10 @@
   },
   "scripts": {
     "test": "npm run build && node --test tests/**/*.test.js",
-    "lint": "eslint src/ tests/",
+    "lint": "eslint src/ tests/ scripts/",
     "typecheck": "tsc --noEmit",
+    "verify:docker-dev-environment": "node scripts/verify-docker-dev-environment.js",
+    "test:docker-dev-environment": "node --test tests/docker-dev-environment.test.js",
     "clean": "node scripts/clean.js",
     "compile": "tsc -b",
     "postcompile": "node scripts/ensure-cli-executable.js",
@@ -84,7 +94,16 @@
   "devDependencies": {
     "eslint": "^9.39.2",
     "eslint-plugin-jsdoc": "^61.5.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "velocious": "^1.0.574"
+  },
+  "peerDependencies": {
+    "velocious": "^1.0.574"
+  },
+  "peerDependenciesMeta": {
+    "velocious": {
+      "optional": true
+    }
   },
   "files": [
     "build",