rampway 0.5.0 → 0.5.2

package/build/src/velocious/client.js

@@ -0,0 +1,292 @@
+// @ts-check
+import { execFile } from "node:child_process";
+import { releaseIdFromDate } from "../core/release-id.js";
+import { redactText } from "../core/redaction.js";
+import { Reporter } from "../core/reporter.js";
+import { remoteGitRepoLabel } from "../core/git-source.js";
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 30000;
+const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const TERMINAL_STATUSES = ["succeeded", "failed", "interrupted", "reconciliation_required"];
+/**
+ * @name DeploymentRun
+ * @description Public representation of a control-plane deployment run.
+ * @typedef {object} DeploymentRun
+ * @property {string} id
+ * @property {string} status
+ * @property {Record<string, any>} [result]
+ * @property {{message?: string, recovery?: any}} [error]
+ */
+/**
+ * Control-plane failure that must not trigger a transport fallback: an
+ * authenticated admission decision (401/403/409/422), a 5xx that already
+ * admitted a run, or an interruption after a run was admitted.
+ */
+export class ControlPlaneError extends Error {
+    /**
+     * @param {string} message
+     * @param {{status?: number, cause?: unknown, runId?: string|null}} [opts]
+     */
+    constructor(message, { status, cause, runId = null } = {}) {
+        super(message, cause === undefined ? undefined : { cause });
+        /** @type {number|null} */
+        this.status = status ?? null;
+        /** @type {string|null} */
+        this.runId = runId;
+    }
+}
+/**
+ * Control-plane unavailability that may fall back to the direct transport:
+ * network-level failure, a not-deployed endpoint/target (404), or a 5xx
+ * without any admitted run.
+ */
+export class ControlPlaneUnavailableError extends ControlPlaneError {
+    /**
+     * @param {string} message
+     * @param {{status?: number, cause?: unknown}} [opts]
+     */
+    constructor(message, { status, cause } = {}) {
+        super(message, { status, cause });
+    }
+}
+/**
+ * Whether a control-plane failure is eligible for the SSH/direct fallback.
+ *
+ * The control plane is tried first only while it is unavailable or not
+ * deployed; authentication and validation decisions (401/403/409/422) and any
+ * failure after a run was admitted are always surfaced instead.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isFallbackEligible(error) {
+    return error instanceof ControlPlaneUnavailableError;
+}
+/**
+ * @param {unknown} value
+ * @returns {value is string} Whether the value is a full 40-character commit SHA.
+ */
+export function isFullCommitSha(value) {
+    return typeof value === "string" && FULL_SHA_PATTERN.test(value);
+}
+/**
+ * Resolves the immutable revision a control-plane deploy requires. A full
+ * 40-character SHA is used as-is; otherwise the configured release branch is
+ * resolved to its current tip with `git ls-remote`.
+ *
+ * @param {{repo?: string, revision?: string, branch?: string}} args
+ * @returns {Promise<string>} Full commit SHA.
+ */
+export async function resolveControlPlaneRevision({ repo, revision, branch = "master" }) {
+    if (isFullCommitSha(revision))
+        return revision;
+    if (revision)
+        throw new Error(`Control-plane deploys require a full 40-character Git revision, got '${revision}'. Pass the full commit SHA or use --transport=ssh.`);
+    if (!repo)
+        throw new Error("Control-plane deploys require stage.repo to resolve the release branch to a commit SHA");
+    let output;
+    try {
+        output = (await runGit(["ls-remote", "--exit-code", repo, `refs/heads/${branch}`])).output;
+    }
+    catch (error) {
+        throw new Error(`Could not resolve branch '${branch}' of ${remoteGitRepoLabel(repo)} to a commit SHA`, { cause: error });
+    }
+    const sha = output.trim().split(/\s+/u)[0] ?? "";
+    if (!isFullCommitSha(sha))
+        throw new Error(`Could not resolve branch '${branch}' of ${remoteGitRepoLabel(repo)} to a commit SHA`);
+    return sha;
+}
+/**
+ * Creates a deployment run on the control plane and classifies the outcome.
+ *
+ * @param {{endpoint: string, accessToken: string, project: string, stage: string, revision: string, idempotencyKey: string, fetchImpl?: typeof fetch}} args
+ * @returns {Promise<{run: DeploymentRun, replayed: boolean}>}
+ */
+export async function createDeploymentRun({ endpoint, accessToken, project, stage, revision, idempotencyKey, fetchImpl = fetch }) {
+    const url = `${stripTrailingSlash(endpoint)}/runs`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ project, stage, revision, idempotencyKey }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+    }
+    catch (error) {
+        throw new ControlPlaneUnavailableError(`Control plane unavailable at ${redactText(url, [accessToken])}: ${errorMessage(error)}`, { cause: error });
+    }
+    const body = await readJsonResponse(response).catch(() => null);
+    if (response.status === 200 || response.status === 202) {
+        const run = body?.run;
+        if (!run || typeof run.id !== "string" || run.id.length === 0) {
+            throw new ControlPlaneError(`Control plane returned HTTP ${response.status} without a run`, { status: response.status });
+        }
+        return { run: /** @type {DeploymentRun} */ (run), replayed: response.status === 200 };
+    }
+    if (response.status === 404) {
+        throw new ControlPlaneUnavailableError("Control plane endpoint or target is not deployed (HTTP 404)", { status: response.status });
+    }
+    if (response.status >= 500 && !body?.run) {
+        throw new ControlPlaneUnavailableError(`Control plane server unavailable (HTTP ${response.status})`, { status: response.status });
+    }
+    const reason = typeof body?.error === "string" ? body.error : `HTTP ${response.status}`;
+    throw new ControlPlaneError(redactText(`Control plane rejected the deployment request: ${reason}`, [accessToken]), { status: response.status });
+}
+/**
+ * Polls a control-plane run until it reaches a terminal status. Any failure
+ * after admission (including lost contact) is a hard error: the run exists on
+ * the control plane, so there is nothing left to fall back to.
+ *
+ * @param {{endpoint: string, accessToken: string, runId: string, pollIntervalMs?: number, timeoutMs?: number, fetchImpl?: typeof fetch, now?: () => number, reporter?: Reporter}} args
+ * @returns {Promise<DeploymentRun>}
+ */
+export async function pollDeploymentRun({ endpoint, accessToken, runId, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = fetch, now = Date.now, reporter = new Reporter({ lifecycle: false }) }) {
+    const url = `${stripTrailingSlash(endpoint)}/runs/${encodeURIComponent(runId)}`;
+    const startedAt = now();
+    /** @type {string|undefined} */
+    let lastStatus;
+    for (;;) {
+        if (now() - startedAt > timeoutMs) {
+            throw new ControlPlaneError(`Control plane run ${runId} did not reach a terminal status within ${Math.round(timeoutMs / 1000)}s (last status '${lastStatus ?? "pending"}')`);
+        }
+        let response;
+        try {
+            response = await fetchImpl(url, { headers: { Authorization: `Bearer ${accessToken}` }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        }
+        catch (error) {
+            throw new ControlPlaneError(`Lost contact with control plane while waiting for run ${runId}: ${errorMessage(error)}`, { cause: error, runId });
+        }
+        const body = await readJsonResponse(response).catch(() => null);
+        const run = body?.run;
+        if (response.status === 404 || !run) {
+            throw new ControlPlaneError(`Control plane no longer reports run ${runId} (HTTP ${response.status})`, { runId, status: response.status });
+        }
+        if (run.status !== lastStatus) {
+            lastStatus = run.status;
+            reporter.line(`  * Control-plane run ${runId} status: ${run.status}`);
+        }
+        if (TERMINAL_STATUSES.includes(run.status))
+            return /** @type {DeploymentRun} */ (run);
+        await delay(pollIntervalMs);
+    }
+}
+/**
+ * Deploys a stage through the mounted control plane: resolves the immutable
+ * revision, creates an idempotent run, polls it to completion, and returns the
+ * control-plane deploy report annotated with the run identifier.
+ *
+ * @param {{stage: import('#types').StageConfig, httpConfig: import('#types').HttpTransportConfig, revision?: string, reporter?: Reporter, fetchImpl?: typeof fetch}} args
+ * @returns {Promise<import('#types').DeployReport>}
+ */
+export async function deployViaControlPlane({ stage, httpConfig, revision, reporter = new Reporter({ lifecycle: false }), fetchImpl = fetch }) {
+    const endpoint = httpConfig.endpoint;
+    const accessToken = await resolveAccessToken(httpConfig);
+    const project = httpConfig.project ?? stage.application;
+    const releaseRevision = await resolveControlPlaneRevision({ repo: stage.repo, revision, branch: stage.branch });
+    const idempotencyKey = controlPlaneIdempotencyKey(project, stage.stageName, releaseRevision);
+    reporter.line(`  * Requesting control-plane deploy of ${project}/${stage.stageName} revision ${releaseRevision}`);
+    const { run, replayed } = await createDeploymentRun({ endpoint, accessToken, fetchImpl, project, stage: stage.stageName, revision: releaseRevision, idempotencyKey });
+    reporter.line(replayed
+        ? `  * Control plane replayed run ${run.id} for idempotency key ${idempotencyKey}`
+        : `  * Control plane admitted run ${run.id}`);
+    const finalRun = await pollDeploymentRun({ endpoint, accessToken, fetchImpl, runId: run.id, pollIntervalMs: httpConfig.pollIntervalMs, timeoutMs: httpConfig.timeoutMs, reporter });
+    if (finalRun.status !== "succeeded") {
+        const detail = finalRun.error && typeof finalRun.error === "object" && typeof finalRun.error.message === "string"
+            ? finalRun.error.message
+            : "no failure detail recorded";
+        throw new Error(redactText(`Control-plane run ${finalRun.id} ended with status '${finalRun.status}': ${detail}`, [accessToken]));
+    }
+    const result = finalRun.result && typeof finalRun.result === "object" ? finalRun.result : {};
+    reporter.line(`  * Control-plane run ${finalRun.id} succeeded`);
+    return {
+        ...result,
+        application: result.application ?? stage.application,
+        stage: result.stage ?? stage.stageName,
+        releaseId: result.releaseId ?? null,
+        revision: result.revision ?? releaseRevision,
+        event: result.event ?? "deploy",
+        runId: finalRun.id,
+        transport: "http"
+    };
+}
+/**
+ * Builds a client-generated idempotency key that is stable per invocation, so
+ * retrying the same command replays an existing admitted run instead of
+ * creating a duplicate.
+ *
+ * @param {string} project
+ * @param {string} stage
+ * @param {string} revision
+ * @returns {string}
+ */
+export function controlPlaneIdempotencyKey(project, stage, revision) {
+    return `${project}-${stage}-${revision}-${releaseIdFromDate()}`;
+}
+/**
+ * @param {import('#types').HttpTransportConfig} httpConfig
+ * @returns {string} Bearer token.
+ */
+function resolveAccessToken(httpConfig) {
+    if (httpConfig.accessToken)
+        return httpConfig.accessToken;
+    if (httpConfig.accessTokenEnv) {
+        const value = process.env[httpConfig.accessTokenEnv];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new Error(`stage.http.accessTokenEnv '${httpConfig.accessTokenEnv}' is not set in the environment`);
+        }
+        return value;
+    }
+    throw new Error("stage.http requires accessToken or accessTokenEnv");
+}
+/**
+ * @param {string[]} args
+ * @returns {Promise<{output: string}>}
+ */
+function runGit(args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { timeout: REQUEST_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                const detail = String(stderr || error.message).trim();
+                reject(new Error(`git ${args[0]} failed: ${redactText(detail)}`));
+                return;
+            }
+            resolve({ output: String(stdout) });
+        });
+    });
+}
+/**
+ * @param {string} endpoint
+ * @returns {string}
+ */
+function stripTrailingSlash(endpoint) {
+    return endpoint.replace(/\/+$/u, "");
+}
+/**
+ * @param {Response} response
+ * @returns {Promise<Record<string, any>|null>}
+ */
+async function readJsonResponse(response) {
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+}
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorMessage(error) {
+    const cause = error instanceof Error && error.cause instanceof Error ? error.cause.message : null;
+    return cause ?? (error instanceof Error ? error.message : String(error));
+}
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=client.js.map

package/build/src/velocious/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/velocious/client.js"],"names":[],"mappings":"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"}

package/docs/config-reference.md

@@ -34,6 +34,7 @@ Each stage under `stages` supports:
 | `strategy` | string | no | Transport-dependent | Deploy strategy: `"local-copy"`, `"remote-git"`, or reserved `"archive-upload"`. Defaults to `"local-copy"` for local transport and `"remote-git"` for SSH transport. `archive-upload` is recognized but not yet deployable. |
 | `transport` | object | no | `{type: "ssh"}` | Transport configuration. See Transport below. |
 | `hosts` | array | no | `[]` | For SSH transport: list of hosts with `host`, `user`, and `roles`. |
+| `http` | object | no | — | Optional control-plane transport config. Enables `rampway <stage> deploy --transport=http|auto`. See HTTP control plane below. |
 | `keepReleases` | number | no | `5` | Number of old releases to keep after cleanup. |
 | `linkedFiles` | array | no | `[]` | Files symlinked from `shared/` into each release. See Linked files below. |
 | `linkedDirs` | array | no | `[]` | Directories symlinked from `shared/` into each release. |
@@ -78,6 +79,75 @@ transport: {type: "ssh"},
 hosts: [{host: "server.example", user: "dev", roles: ["app", "web"]}]
 ```
 
+### http (control plane)
+
+Optional transport that runs the deploy through the authenticated Velocious
+deployment API mounted by the application. When `http` is configured,
+`rampway <stage> deploy` defaults to `--transport=auto`; see Deploy transports
+below.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `endpoint` | string | yes | — | Base URL where the API is mounted, e.g. `https://app.example/rampway/deployments`. Must be an `http(s)` URL. |
+| `accessToken` | string | no | — | Bearer token to authenticate the client. Exactly one of `accessToken` or `accessTokenEnv` is required. |
+| `accessTokenEnv` | string | no | — | Name of an environment variable holding the bearer token. Exactly one of `accessToken` or `accessTokenEnv` is required. The token value is never printed. |
+| `project` | string | no | `stage.application` | Project the control plane is allowlisted for. |
+| `pollIntervalMs` | positive integer | no | `2000` | How often to poll the run while it is pending/running. |
+| `timeoutMs` | positive integer | no | `1800000` | How long to keep polling before failing the deploy. |
+
+```js
+http: {
+  endpoint: "https://app.example/rampway/deployments",
+  accessTokenEnv: "RAMPWAY_DEPLOY_TOKEN",
+  project: "my-app",
+  pollIntervalMs: 2000,
+  timeoutMs: 1800000
+}
+```
+
+The CLI resolves the release revision as a full 40-character SHA; a branch name
+is resolved with `git ls-remote` against `stage.repo`. The control plane only
+accepts full SHAs reachable from the stage's approved release branch. Malformed
+`http` config fails loudly: a missing or non-`http(s)` endpoint, an absent or
+invalid token source, a non-string `project`, or non-positive interval/timeout
+values are all rejected.
+
+### Deploy transports
+
+`rampway <stage> deploy --transport=http|ssh|auto` selects how the deploy is
+executed:
+
+- `http` — requires `stage.http`; runs entirely through the control plane and
+  fails if the stage has no `http` config.
+- `ssh` — runs directly over the stage's `transport` (ssh or local),
+  bypassing the control plane.
+- `auto` (default) — uses the control plane when `stage.http` is configured,
+  and falls back to the direct transport only when the control plane is
+  unreachable (network failure), not deployed for the project/stage (`404`),
+  or unavailable (`5xx` without an admitted run). It never falls back on
+  authentication or validation errors (`401`, `403`, `409`, `422`), on a
+  `5xx` that carries an admitted run, or once a run has been admitted and is
+  being polled.
+
+Dry runs (`--dry-run`) always print a direct-transport plan and never contact
+the control plane.
+
+### Structural deploy plans
+
+`rampway <stage> plan [revision]` renders the deploy structure after loading
+and validating configuration. With no positional revision, selection remains
+`--revision`, then `--branch`, then `stage.revision`, then `stage.branch`. A
+positional revision takes precedence over all four sources and must contain 7
+to 64 hexadecimal characters. The selected value appears in both human and
+JSON output.
+
+Planning is structural only: it does not prove that a SHA exists, check branch
+or remote-git reachability, or obtain HTTP control-plane approval. It performs
+no SSH, Git fetch/clone, local-copy, temporary checkout, control-plane request,
+deploy lock, release-directory, runtime, filesystem deployment, or transport
+operation. `local-copy` and `remote-git` steps are descriptions of what a later
+deploy would do, not actions or admission checks.
+
 ## Linked files and directories
 
 Linked files and directories are symlinked from `shared/` into every release before tasks run.
@@ -338,6 +408,42 @@ deploy without `config` retains its existing forward-deploy behavior, but
 runtime-complete rollback fails closed until a successful deploy with explicit
 stable config has recorded known-good state.
 
+### compose
+
+Compose runtime adapter for a pre-existing, trusted Docker Compose deployment.
+Rampway runs only the two literal commands configured here from a fixed absolute
+Compose root; it does not construct Compose arguments from release IDs, hooks,
+or command-line input.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | yes | `"compose"` |
+| `composeRoot` | absolute path | yes | Fixed directory used as the working directory for both commands. |
+| `handoffCommand` | string | yes | Static trusted command that selects/starts the candidate runtime. |
+| `healthCommand` | string | yes | Static trusted command that performs the runtime health check after handoff. |
+
+```js
+runtime: {
+  type: "compose",
+  composeRoot: "/srv/myapp/compose",
+  handoffCommand: "docker compose up -d --wait web",
+  healthCommand: "docker compose exec -T web node scripts/healthcheck.mjs"
+}
+```
+
+The adapter passes the immutable candidate to both commands through the trusted
+`RAMPWAY_RELEASE_ID` and `RAMPWAY_RELEASE_PATH` environment variables, then runs
+the candidate handoff followed by the configured health command before Rampway runs stage health checks or publishes `current`. Its
+snapshot stores only the fixed Compose root and a contract digest: it never
+stores command text or secrets. Configuration is intentionally conservative:
+all three fields are required, `composeRoot` must be absolute, and no runtime
+`env` or extra adapter fields are accepted. Put sensitive values in the trusted
+Compose environment/secret mechanism, not in these commands.
+
+A failed candidate handoff or health check, and a failed explicit rollback,
+reactivate and health-check the previous Compose runtime through the same
+runtime deploy API before returning the original failure.
+
 ## Rollback and retained releases
 
 `rampway <stage> rollback` selects the latest other safe 14-digit release, or

package/docs/velocious-deployment-api.md

@@ -128,6 +128,43 @@ const runResponse = await fetch(`${baseUrl}/runs/${encodeURIComponent(created.ru
 const {run, current} = await runResponse.json()
 ```
 
+## Deploying from the Rampway CLI
+
+A stage that configures `stage.http` can deploy through this API directly from
+the CLI:
+
+```sh
+RAMPWAY_DEPLOY_TOKEN=... rampway production deploy --transport=http
+RAMPWAY_DEPLOY_TOKEN=... rampway production deploy --transport=auto
+```
+
+`--transport=auto` (the default) tries the control plane first and falls back
+to the stage's direct SSH/local transport only when the control plane is
+unreachable, the project/stage is not allowlisted (`404`), or it returns `5xx`
+without having admitted a run. It never falls back on `401`/`403`/`409`/`422`,
+on a `5xx` that carries an admitted run, or once a run has been admitted and is
+being polled. `--transport=ssh` bypasses the control plane entirely;
+`--transport=http` requires `stage.http` and fails if it is missing. Dry runs
+always print a direct-transport plan.
+
+The separate `rampway <stage> plan [revision]` command is purely structural.
+Even for a stage configured with `http`, it never contacts this control plane
+and does not resolve a branch, prove that a supplied SHA exists or is reachable
+from the approved branch, or request deployment admission. Those full-SHA and
+reachability checks remain part of an actual HTTP deployment.
+
+The client posts the stage's project/application name, an immutable full commit
+SHA (resolving `stage.branch` with `git ls-remote` against `stage.repo` when no
+revision is pinned), and an idempotency key derived from the project, stage,
+revision, and release timestamp. It then polls the run until it reaches a
+terminal status. A `succeeded` run is reported as a normal deploy; a
+`failed`/`interrupted`/`reconciliation_required` run fails the deploy with the
+control plane's sanitized error, and Rampway records whether previous live
+state was restored. Polling is bounded by `http.pollIntervalMs` (default
+`2000`) and `http.timeoutMs` (default 30 minutes); losing contact with the
+control plane while a run is admitted fails the deploy rather than retrying
+elsewhere.
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,