@forgezero/agent 0.1.33 → 0.1.35

package/dist/capacity-calibration.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded, node-local HTTP concurrency calibration.
+ *
+ * This deliberately benchmarks a real application probe rather than CPU. A
+ * database-bound API can have idle CPU while every request is waiting on I/O.
+ * The caller chooses a representative, idempotent GET endpoint; ForgeZero's
+ * cluster rehearsal uses its typed Arango read query.
+ */
+export interface CapacityStage {
+    concurrency: number;
+    requests: number;
+    succeeded: number;
+    failed: number;
+    overloaded: number;
+    throughputPerSecond: number;
+    p95Ms: number;
+}
+export interface CapacityCalibration {
+    endpoint: string;
+    recommendedConcurrency: number;
+    stopReason: 'maximum-tested' | 'latency' | 'errors' | 'throughput-regression';
+    stages: CapacityStage[];
+}
+export interface CapacityCalibrationOptions {
+    endpoint: string;
+    maxConcurrency?: number;
+    requestsPerWorker?: number;
+    maxP95Ms?: number;
+    maxErrorRate?: number;
+    headroomRatio?: number;
+    requestTimeoutMs?: number;
+}
+export interface ValidatedCapacityCalibrationOptions {
+    endpoint: URL;
+    maxConcurrency: number;
+    requestsPerWorker: number;
+    maxP95Ms: number;
+    maxErrorRate: number;
+    headroomRatio: number;
+    requestTimeoutMs: number;
+}
+/** Only a service on this node may be stressed by an install-time probe. */
+export declare function localCalibrationEndpoint(value: string): URL;
+/** Parse every bound without sending a request; deploy definitions use this fail-closed gate. */
+export declare function validateCapacityCalibrationOptions(options: CapacityCalibrationOptions): ValidatedCapacityCalibrationOptions;
+/**
+ * Increase load geometrically and stop at the first unsafe stage. The returned
+ * limit is the last safe stage with explicit headroom; it is evidence, not a
+ * promise that a different route or future release has the same capacity.
+ */
+export declare function calibrateHttpConcurrency(options: CapacityCalibrationOptions, fetcher?: typeof fetch): Promise<CapacityCalibration>;

package/dist/capacity-calibration.js

@@ -0,0 +1,119 @@
+// src/capacity-calibration.ts
+var percentile95 = (values) => {
+  if (values.length === 0)
+    return Number.POSITIVE_INFINITY;
+  const sorted = values.toSorted((left, right) => left - right);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+};
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const headroomRatio = options.headroomRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(headroomRatio) || headroomRatio < 0.25 || headroomRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs
+  };
+}
+async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher) {
+  const latencies = [];
+  let succeeded = 0;
+  let failed = 0;
+  let overloaded = 0;
+  const started = performance.now();
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (let request = 0;request < requestsPerWorker; request += 1) {
+      const requestStarted = performance.now();
+      try {
+        const response = await fetcher(endpoint, {
+          method: "GET",
+          headers: { accept: "application/json", "user-agent": "forgezero-capacity-calibration/1" },
+          signal: AbortSignal.timeout(timeoutMs),
+          redirect: "error"
+        });
+        await response.body?.cancel();
+        if (response.ok)
+          succeeded += 1;
+        else {
+          failed += 1;
+          if (response.status === 503)
+            overloaded += 1;
+        }
+      } catch {
+        failed += 1;
+      } finally {
+        latencies.push(performance.now() - requestStarted);
+      }
+    }
+  }));
+  const elapsedSeconds = Math.max((performance.now() - started) / 1000, 0.001);
+  return {
+    concurrency,
+    requests: concurrency * requestsPerWorker,
+    succeeded,
+    failed,
+    overloaded,
+    throughputPerSecond: Number(((succeeded + failed) / elapsedSeconds).toFixed(2)),
+    p95Ms: Number(percentile95(latencies).toFixed(2))
+  };
+}
+async function calibrateHttpConcurrency(options, fetcher = fetch) {
+  const {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    headroomRatio,
+    requestTimeoutMs: timeoutMs
+  } = validateCapacityCalibrationOptions(options);
+  const stages = [];
+  let lastSafe = 1;
+  let stopReason = "maximum-tested";
+  for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, fetcher);
+    stages.push(measured);
+    const errorRate = measured.failed / measured.requests;
+    const previous = stages.at(-2);
+    const throughputRegressed = Boolean(previous && concurrency > 1 && measured.throughputPerSecond < previous.throughputPerSecond * 0.9);
+    if (measured.overloaded > 0 || errorRate > maxErrorRate)
+      stopReason = "errors";
+    else if (measured.p95Ms > maxP95Ms)
+      stopReason = "latency";
+    else if (throughputRegressed)
+      stopReason = "throughput-regression";
+    else
+      lastSafe = concurrency;
+    if (stopReason !== "maximum-tested" || concurrency === maxConcurrency)
+      break;
+  }
+  return {
+    endpoint: endpoint.toString(),
+    recommendedConcurrency: Math.max(1, Math.floor(lastSafe * headroomRatio)),
+    stopReason,
+    stages
+  };
+}
+export {
+  validateCapacityCalibrationOptions,
+  localCalibrationEndpoint,
+  calibrateHttpConcurrency
+};

package/dist/cli/cloudflare-bootstrap.d.ts

@@ -0,0 +1,11 @@
+import { type AttendedCloudflareBootstrapRequest, type CloudflareBootstrapEvidence, type CloudflareBootstrapPhaseRunner } from '../cloudflare-bootstrap';
+export interface CloudflareBootstrapCommandDependencies {
+    run?: CloudflareBootstrapPhaseRunner;
+    write?: (text: string) => void;
+}
+/**
+ * Read reviewed non-secret coordinates and token-file paths for the attended
+ * operator phase. Raw token values and a persisted mode are not schema fields.
+ */
+export declare function readCloudflareBootstrapCommandConfig(path: string, mode: 'plan' | 'apply'): AttendedCloudflareBootstrapRequest;
+export declare function runCloudflareBootstrapCommand(configPath: string, apply: boolean, dependencies?: CloudflareBootstrapCommandDependencies): Promise<CloudflareBootstrapEvidence>;

package/dist/cloudflare-bootstrap.d.ts

@@ -0,0 +1,218 @@
+import { type CloudflareAccessCredentials, type CloudflareAccountRuntimeToken, type CloudflareApiTokens } from './cloudflare-edge';
+export interface CloudflareBootstrapNodeCoordinates {
+    nodeName: string;
+    hostname: string;
+    service: string;
+    tunnelName: string;
+    applicationName: string;
+    /** Present only on DB nodes that publish an exact private host route. */
+    privateAddress?: string;
+}
+export interface CloudflarePrivateNetworkCoordinates {
+    warpOrganization: string;
+    virtualNetworkName: string;
+    deviceProfileName: string;
+    enrollmentApplicationName: string;
+    deviceProfilePrecedence?: number;
+}
+export interface CloudflareBootstrapCoordinates {
+    accountId: string;
+    zoneId: string;
+    /** Legacy single-node coordinates; normalized into `nodes[0]`. */
+    hostname: string;
+    service: string;
+    tunnelName: string;
+    kvNamespaceTitle: string;
+    workerScriptName: string;
+    serviceTokenName: string;
+    policyName: string;
+    applicationName: string;
+    workerDirectory: string;
+    workerMain: string;
+    workerCompatibilityDate: string;
+    publicDomains: string[];
+    createRuntimeTokens: boolean;
+    createPrivateNetworkRuntimeToken: boolean;
+    runtimeTokenNamePrefix: string;
+    nodes?: CloudflareBootstrapNodeCoordinates[];
+    privateNetwork?: CloudflarePrivateNetworkCoordinates;
+}
+export interface CloudflareBootstrapTokenFiles {
+    apiTokenFile?: string;
+    tunnelApiTokenFile?: string;
+    dnsApiTokenFile?: string;
+    kvApiTokenFile?: string;
+    accessApiTokenFile?: string;
+    workerApiTokenFile?: string;
+}
+interface CloudflareBootstrapResources {
+    tunnelId: string;
+    kvNamespaceId: string;
+    hostname: string;
+    service: string;
+    connectorToken: string;
+    access?: CloudflareAccessCredentials & {
+        policyId?: string;
+        applicationId?: string;
+    };
+    nodes: Array<{
+        nodeName: string;
+        hostname: string;
+        service: string;
+        tunnelName: string;
+        tunnelId: string;
+        connectorToken: string;
+        applicationId?: string;
+    }>;
+    worker?: {
+        scriptName: string;
+        publicDomains: string[];
+        deployed: true;
+    };
+    runtimeTokens?: {
+        kv: CloudflareAccountRuntimeToken;
+        privateNetwork?: CloudflareAccountRuntimeToken;
+    };
+    privateNetwork?: {
+        warpOrganization: string;
+        virtualNetworkId: string;
+        deviceProfileId: string;
+        enrollmentApplicationId: string;
+        routes: Array<{
+            nodeName: string;
+            routeId: string;
+            privateAddress: string;
+        }>;
+    };
+}
+export interface CloudflareBootstrapOutput {
+    format: 1;
+    kind: 'forgezero-cloudflare-bootstrap';
+    phase: 'edge-resources-provisioned' | 'runtime-tokens-created' | 'worker-deployed' | 'access-token-provisioned' | 'complete';
+    updatedAt: string;
+    coordinates: CloudflareBootstrapCoordinates;
+    resources: CloudflareBootstrapResources;
+    created?: {
+        tunnel: boolean;
+        kvNamespace: boolean;
+        serviceToken: boolean;
+        policy: boolean;
+        application: boolean;
+        privateNetwork: boolean;
+        workerDeployed: true;
+        nodes: Array<{
+            nodeName: string;
+            tunnel: boolean;
+            application: boolean;
+        }>;
+    };
+}
+export interface CloudflareBootstrapPlan {
+    format: 1;
+    kind: 'forgezero-cloudflare-bootstrap-plan';
+    mode: 'attended-token-file';
+    outputFile: string;
+    coordinates: CloudflareBootstrapCoordinates;
+    operations: readonly string[];
+    secrets: readonly string[];
+}
+/**
+ * The published `fz bootstrap platform` boundary. It deliberately accepts
+ * token *paths*, never token values, so a caller cannot accidentally put the
+ * Cloudflare management credential into a platform manifest, runtime config,
+ * child argv, or evidence journal.
+ */
+export interface AttendedCloudflareBootstrapRequest {
+    mode: 'plan' | 'apply';
+    coordinates: CloudflareBootstrapCoordinates;
+    tokenFiles?: CloudflareBootstrapTokenFiles;
+    checkpointPath: string;
+}
+/** Secret-free evidence safe to embed in the platform bootstrap journal. */
+export interface CloudflareBootstrapEvidence {
+    format: 1;
+    kind: 'forgezero-cloudflare-bootstrap-evidence';
+    phase: 'planned' | 'complete';
+    checkpointFile: string;
+    kvNamespaceId?: string;
+    workerScriptName: string;
+    publicDomains: readonly string[];
+    runtimeTokenIds?: {
+        kv?: string;
+        privateNetwork?: string;
+    };
+    nodes: ReadonlyArray<{
+        nodeName: string;
+        hostname: string;
+        tunnelId?: string;
+        applicationId?: string;
+    }>;
+}
+export interface CloudflareBootstrapDependencies {
+    fetcher?: typeof fetch;
+    workerRunner?: CloudflareWorkerCommandRunner;
+}
+export type CloudflareBootstrapPhaseRunner = (request: AttendedCloudflareBootstrapRequest) => Promise<CloudflareBootstrapEvidence>;
+/** Read exactly one API token from a non-symlinked, owner-only regular file. */
+export declare function readOwnerApiToken(path: string): Promise<string>;
+export declare function readCloudflareBootstrapTokens(files: CloudflareBootstrapTokenFiles): Promise<CloudflareApiTokens>;
+export declare function validateCloudflareBootstrapCoordinates(input: CloudflareBootstrapCoordinates): CloudflareBootstrapCoordinates;
+export declare function planCloudflareBootstrap(input: CloudflareBootstrapCoordinates, outputPath: string): CloudflareBootstrapPlan;
+export interface CloudflareWorkerCommand {
+    command: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+}
+export type CloudflareWorkerCommandRunner = (request: CloudflareWorkerCommand) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Deploy one Worker from an ephemeral config containing the runtime-created KV id. */
+export declare function deployCloudflareWorker(coordinates: CloudflareBootstrapCoordinates, kvNamespaceId: string, apiToken: string, runner?: CloudflareWorkerCommandRunner): Promise<void>;
+export interface CloudflareConnectorHandoff {
+    nodeName: string;
+    hostname: string;
+    service: string;
+    tunnelId: string;
+    connectorToken: string;
+}
+export interface CloudflareHostHandoff extends CloudflareConnectorHandoff {
+    accountId: string;
+    zoneId: string;
+    kvNamespaceId: string;
+    kvRuntimeToken: string;
+    privateNetworkRuntimeToken?: string;
+    warp?: {
+        organization: string;
+        clientId: string;
+        clientSecret: string;
+        virtualNetworkId: string;
+        deviceProfileId: string;
+    };
+}
+/**
+ * Select one node's connector credential directly from the completed fleet
+ * checkpoint. Host bootstrap can pipe this value into `systemd-creds` without
+ * creating another plaintext token file or accepting the whole JSON as a
+ * connector token.
+ */
+export declare function readCloudflareConnectorHandoff(checkpointPath: string, nodeName: string): Promise<CloudflareConnectorHandoff>;
+/** Complete secret-bearing handoff consumed once by root host bootstrap. */
+export declare function readCloudflareHostHandoff(checkpointPath: string, nodeName: string): Promise<CloudflareHostHandoff>;
+/** Atomically persist sensitive bootstrap material without making it runtime configuration. */
+export declare function writeOwnerBootstrapOutput(path: string, output: CloudflareBootstrapOutput): Promise<void>;
+/**
+ * Attended, resumable Cloudflare bootstrap. The output is checkpointed after
+ * every one-time secret is obtained, so a later API failure cannot orphan it.
+ */
+export declare function applyCloudflareBootstrap(input: CloudflareBootstrapCoordinates, tokens: CloudflareApiTokens, outputPath: string, fetcher?: typeof fetch, workerRunner?: CloudflareWorkerCommandRunner): Promise<CloudflareBootstrapOutput>;
+/**
+ * Run the attended Cloudflare phase for `fz bootstrap platform`.
+ *
+ * Plans are offline. Applies read management tokens only inside this function,
+ * persist one-time handoff values only in the owner-only checkpoint, and return
+ * a deliberately secret-free evidence record to the outer bootstrap journal.
+ */
+export declare function runAttendedCloudflareBootstrap(request: AttendedCloudflareBootstrapRequest, dependencies?: CloudflareBootstrapDependencies): Promise<CloudflareBootstrapEvidence>;
+export {};