chainlesschain 0.163.2 → 0.163.4

package/src/lib/delivery-production-runner.js

@@ -0,0 +1,240 @@
+/**
+ * Crash-safe driver for one production DeliveryCoordinator action.
+ *
+ * The provider call deliberately sits between two short, synchronous locked
+ * transactions:
+ *
+ *   lock -> request + persist pending effect -> unlock
+ *        -> invoke provider exactly once
+ *   lock -> verify exact pending binding + settle + persist -> unlock
+ *
+ * A provider exception, process crash, or settlement write failure therefore
+ * leaves the durable snapshot pending. A later caller must reconcile that
+ * exact effect; this runner never replays a pending provider operation.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  DELIVERY_ACTION,
+  projectDeliveryFlow,
+  requestDeliveryAction,
+  restoreDeliveryFlow,
+  settleDeliveryAction,
+} from "./delivery-coordinator.js";
+import { withFileLock } from "./with-file-lock.js";
+
+const ACTION_TO_METHOD = Object.freeze({
+  [DELIVERY_ACTION.RUN_GATES]: "runGates",
+  [DELIVERY_ACTION.RUN_PREVIEW]: "runPreview",
+  [DELIVERY_ACTION.RUN_REVIEW]: "runReview",
+  [DELIVERY_ACTION.APPLY_FIX]: "applyFix",
+  [DELIVERY_ACTION.CREATE_PR]: "createPr",
+  [DELIVERY_ACTION.REFRESH_CI]: "refreshCi",
+  [DELIVERY_ACTION.PUBLISH_EVIDENCE]: "publishEvidence",
+  [DELIVERY_ACTION.MERGE]: "merge",
+  [DELIVERY_ACTION.ARCHIVE]: "archive",
+});
+
+function normalizeError(error) {
+  if (error instanceof Error) return error;
+  return new Error(String(error || "delivery provider failed"));
+}
+
+function attachPendingEffect(error, state, effect) {
+  const failure = normalizeError(error);
+  failure.deliveryState = state;
+  failure.pendingEffect = effect;
+  return failure;
+}
+
+function assertCallerExpectation(state, options) {
+  if (options.expectedRevision != null) {
+    const expected = Number(options.expectedRevision);
+    if (!Number.isInteger(expected) || expected < 0) {
+      throw new Error("expected revision must be a non-negative integer");
+    }
+    if (state.revision !== expected) {
+      throw new Error(
+        `stale delivery revision: expected ${expected}, found ${state.revision}`,
+      );
+    }
+  }
+  if (
+    options.expectedStateDigest != null &&
+    state.stateDigest !== String(options.expectedStateDigest)
+  ) {
+    throw new Error("stale delivery state digest");
+  }
+}
+
+function assertSettlementBinding(current, requested, effect) {
+  if (current.flowId !== requested.flowId) {
+    throw new Error("stale delivery flow id before settlement");
+  }
+  if (current.revision !== requested.revision) {
+    throw new Error(
+      `stale delivery revision before settlement: expected ${requested.revision}, found ${current.revision}`,
+    );
+  }
+  if (current.stateDigest !== requested.stateDigest) {
+    throw new Error("stale delivery state digest before settlement");
+  }
+  if (!current.pendingEffect || current.pendingEffect.id !== effect.id) {
+    throw new Error("stale delivery effect id before settlement");
+  }
+}
+
+/** Read and integrity-check one delivery snapshot. */
+export function readDeliveryProductionState(statePath, deps = {}) {
+  const readFileSync = deps.readFileSync || fs.readFileSync;
+  return restoreDeliveryFlow(
+    JSON.parse(readFileSync(path.resolve(String(statePath)), "utf8")),
+  );
+}
+
+/**
+ * Durably and atomically replace a delivery snapshot with owner-only JSON
+ * bytes (file fsync before rename; parent-directory fsync on POSIX).
+ * The caller is responsible for holding the state lock.
+ */
+export function writeDeliveryProductionState(statePath, state, deps = {}) {
+  const verified = restoreDeliveryFlow(state);
+  const openSync = deps.openSync || fs.openSync;
+  const writeFileSync = deps.writeFileSync || fs.writeFileSync;
+  const fsyncSync = deps.fsyncSync || fs.fsyncSync;
+  const closeSync = deps.closeSync || fs.closeSync;
+  const renameSync = deps.renameSync || fs.renameSync;
+  const rmSync = deps.rmSync || fs.rmSync;
+  const uuid = deps.randomUUID || randomUUID;
+  const platform = deps.platform || process.platform;
+  const target = path.resolve(String(statePath));
+  const temporary = `${target}.${process.pid}.${uuid()}.tmp`;
+  let temporaryDescriptor = null;
+  let directoryDescriptor = null;
+  let renamed = false;
+  try {
+    temporaryDescriptor = openSync(temporary, "wx", 0o600);
+    writeFileSync(
+      temporaryDescriptor,
+      `${JSON.stringify(verified, null, 2)}\n`,
+      "utf8",
+    );
+    fsyncSync(temporaryDescriptor);
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = null;
+    renameSync(temporary, target);
+    renamed = true;
+    // POSIX rename durability requires syncing the containing directory too.
+    // Windows does not support opening a directory with fs.openSync("r").
+    if (platform !== "win32") {
+      directoryDescriptor = openSync(path.dirname(target), "r");
+      fsyncSync(directoryDescriptor);
+      closeSync(directoryDescriptor);
+      directoryDescriptor = null;
+    }
+  } catch (error) {
+    for (const descriptor of [temporaryDescriptor, directoryDescriptor]) {
+      if (descriptor == null) continue;
+      try {
+        closeSync(descriptor);
+      } catch {
+        // Preserve the authoritative write error.
+      }
+    }
+    try {
+      if (!renamed) rmSync(temporary, { force: true });
+    } catch {
+      // Preserve the authoritative write error.
+    }
+    throw error;
+  }
+  return verified;
+}
+
+function lockedTransaction(statePath, operation, deps) {
+  const lock = deps.withFileLock || withFileLock;
+  return lock(statePath, operation, {
+    ...(deps.lockOptions || {}),
+    failIfUnavailable: true,
+  });
+}
+
+/**
+ * Execute one available action through a production adapter.
+ *
+ * The adapter surface matches DeliveryCoordinator.execute(): each method gets
+ * `(payload, { effect, state })`, where `state` is the requested projection.
+ * Throws retain `pendingEffect` and `deliveryState` for explicit reconciliation.
+ */
+export async function runDeliveryProductionAction(options = {}, deps = {}) {
+  const statePath = path.resolve(String(options.statePath || ""));
+  if (!options.statePath) throw new Error("statePath is required");
+
+  const method = ACTION_TO_METHOD[options.action];
+  if (!method) {
+    throw new Error(`unsupported delivery action: ${options.action}`);
+  }
+  const provider = options.adapter?.[method];
+  if (typeof provider !== "function") {
+    throw new Error(`delivery adapter does not implement ${method}`);
+  }
+
+  const readState =
+    deps.readState || ((target) => readDeliveryProductionState(target, deps));
+  const writeState =
+    deps.writeState ||
+    ((target, state) => writeDeliveryProductionState(target, state, deps));
+
+  const requested = lockedTransaction(
+    statePath,
+    () => {
+      const current = readState(statePath);
+      assertCallerExpectation(current, options);
+      if (current.pendingEffect) {
+        throw new Error(
+          `delivery effect ${current.pendingEffect.id} is already pending; reconcile it before another provider call`,
+        );
+      }
+      const next = requestDeliveryAction(
+        current,
+        options.action,
+        options.payload || {},
+        { now: deps.now },
+      );
+      writeState(statePath, next);
+      return next;
+    },
+    deps,
+  );
+  const effect = requested.pendingEffect;
+
+  let result;
+  try {
+    result = await provider.call(options.adapter, effect.payload, {
+      effect,
+      state: projectDeliveryFlow(requested),
+    });
+  } catch (error) {
+    throw attachPendingEffect(error, requested, effect);
+  }
+
+  try {
+    return lockedTransaction(
+      statePath,
+      () => {
+        const current = readState(statePath);
+        assertSettlementBinding(current, requested, effect);
+        const settled = settleDeliveryAction(current, effect.id, result, {
+          now: deps.now,
+        });
+        writeState(statePath, settled);
+        return settled;
+      },
+      deps,
+    );
+  } catch (error) {
+    throw attachPendingEffect(error, requested, effect);
+  }
+}

package/src/lib/durable-security-store.js

@@ -58,11 +58,7 @@ export function writeSecurityStore(filePath, label, store) {
 
   try {
     descriptor = fs.openSync(temporaryPath, "wx", 0o600);
-    fs.writeFileSync(
-      descriptor,
-      `${JSON.stringify(store, null, 2)}\n`,
-      "utf8",
-    );
+    fs.writeFileSync(descriptor, `${JSON.stringify(store, null, 2)}\n`, "utf8");
     fs.fsyncSync(descriptor);
     fs.closeSync(descriptor);
     descriptor = null;
@@ -92,7 +88,12 @@ export function writeSecurityStore(filePath, label, store) {
         // Best-effort orphan cleanup.
       }
     }
-    throw storeError(label, "write", filePath, cause);
+    const error = storeError(label, "write", filePath, cause);
+    // Before rename the authoritative path is unchanged. After rename, a
+    // directory-fsync failure leaves crash durability unknown even though an
+    // immediate read may observe the new generation.
+    error.commitState = renamed ? "unknown" : "not-committed";
+    throw error;
   }
 }
 
@@ -110,15 +111,26 @@ export function mutateSecurityStore(
     throw storeError(label, "prepare", filePath, cause);
   }
 
-  return lock(
-    filePath,
-    () => {
-      const current = readSecurityStore(filePath, label);
-      const draft = structuredClone(current);
-      const result = mutator(draft);
-      writeSecurityStore(filePath, label, draft);
-      return result;
-    },
-    { timeoutMs, staleMs, failIfUnavailable: true },
-  );
+  let writeCommitted = false;
+  try {
+    return lock(
+      filePath,
+      () => {
+        const current = readSecurityStore(filePath, label);
+        const draft = structuredClone(current);
+        const result = mutator(draft);
+        writeSecurityStore(filePath, label, draft);
+        writeCommitted = true;
+        return result;
+      },
+      { timeoutMs, staleMs, failIfUnavailable: true },
+    );
+  } catch (cause) {
+    if (cause && !cause.commitState) {
+      // If the durable replace completed and only lock cleanup failed, the
+      // exact state is committed even though the caller lost its response.
+      cause.commitState = writeCommitted ? "committed" : "not-committed";
+    }
+    throw cause;
+  }
 }

package/src/lib/execution-trace/trace-context.cjs

@@ -0,0 +1,179 @@
+/**
+ * Shared W3C trace-context implementation for CommonJS and ESM consumers.
+ *
+ * Keep the implementation and singleton in this CommonJS module. The sibling
+ * trace-context.js file is an ESM wrapper around these exact exports so the
+ * ProcessExecutionBroker and observability code share one AsyncLocalStorage.
+ */
+
+const { AsyncLocalStorage } = require("node:async_hooks");
+const { randomBytes } = require("node:crypto");
+
+class TraceContext {
+  constructor() {
+    this._asyncLocalStorage = new AsyncLocalStorage();
+    this._spans = new Map();
+    this._listeners = new Set();
+  }
+
+  generateTraceId() {
+    return randomBytes(16).toString("hex");
+  }
+
+  generateSpanId() {
+    return randomBytes(8).toString("hex");
+  }
+
+  parseTraceparent(traceparent) {
+    if (!traceparent) return null;
+    const parts = traceparent.split("-");
+    if (parts.length !== 4) return null;
+    const [version, traceId, parentId, traceFlags] = parts;
+    if (
+      version.length !== 2 ||
+      traceId.length !== 32 ||
+      parentId.length !== 16 ||
+      traceFlags.length !== 2
+    ) {
+      return null;
+    }
+    return { version, traceId, parentId, traceFlags: parseInt(traceFlags, 16) };
+  }
+
+  formatTraceparent(traceId, spanId, traceFlags = 0x01) {
+    return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, "0")}`;
+  }
+
+  getCurrentContext() {
+    return this._asyncLocalStorage.getStore();
+  }
+
+  startRootSpan(name, attributes = {}) {
+    const traceId = this.generateTraceId();
+    const spanId = this.generateSpanId();
+    const context = {
+      traceId,
+      spanId,
+      parentSpanId: null,
+      name,
+      attributes,
+      startTime: Date.now(),
+      tracestate: "",
+      baggage: {},
+    };
+    this._spans.set(spanId, context);
+    this._emit("span:start", context);
+    return context;
+  }
+
+  startSpan(name, attributes = {}) {
+    const parent = this.getCurrentContext();
+    if (!parent) {
+      return this.startRootSpan(name, attributes);
+    }
+    const spanId = this.generateSpanId();
+    const context = {
+      traceId: parent.traceId,
+      spanId,
+      parentSpanId: parent.spanId,
+      name,
+      attributes: { ...attributes },
+      startTime: Date.now(),
+      tracestate: parent.tracestate || "",
+      baggage: { ...(parent.baggage || {}) },
+    };
+    this._spans.set(spanId, context);
+    this._emit("span:start", context);
+    return context;
+  }
+
+  endSpan(span, status = { code: "OK" }) {
+    if (!span || !this._spans.has(span.spanId)) return;
+    span.endTime = Date.now();
+    span.duration = span.endTime - span.startTime;
+    span.status = status;
+    this._emit("span:end", span);
+    this._spans.delete(span.spanId);
+  }
+
+  async runInContext(context, fn) {
+    return this._asyncLocalStorage.run(context, fn);
+  }
+
+  getPropagationEnv() {
+    const ctx = this.getCurrentContext();
+    if (!ctx) return {};
+    const env = {
+      TRACEPARENT: this.formatTraceparent(ctx.traceId, ctx.spanId),
+    };
+    if (ctx.tracestate) {
+      env.TRACESTATE = ctx.tracestate;
+    }
+    if (ctx.baggage && Object.keys(ctx.baggage).length > 0) {
+      env.BAGGAGE = Object.entries(ctx.baggage)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join(",");
+    }
+    return env;
+  }
+
+  extractFromEnv(env = process.env) {
+    const traceparent = env.TRACEPARENT || env.traceparent;
+    if (!traceparent) return null;
+    const parsed = this.parseTraceparent(traceparent);
+    if (!parsed) return null;
+    const context = {
+      traceId: parsed.traceId,
+      spanId: parsed.parentId,
+      parentSpanId: null,
+      name: "inherited",
+      attributes: {},
+      startTime: Date.now(),
+      tracestate: env.TRACESTATE || env.tracestate || "",
+      baggage: this._parseBaggage(env.BAGGAGE || env.baggage),
+    };
+    return context;
+  }
+
+  on(event, listener) {
+    this._listeners.add({ event, listener });
+  }
+
+  off(event, listener) {
+    for (const entry of this._listeners) {
+      if (entry.event === event && entry.listener === listener) {
+        this._listeners.delete(entry);
+        break;
+      }
+    }
+  }
+
+  _emit(event, data) {
+    for (const { event: ev, listener } of this._listeners) {
+      if (ev === event) {
+        try {
+          listener(data);
+        } catch {
+          // Listener failures must not break tracing or the caller.
+        }
+      }
+    }
+  }
+
+  _parseBaggage(baggage) {
+    if (!baggage) return {};
+    const result = {};
+    for (const pair of baggage.split(",")) {
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = decodeURIComponent(pair.slice(0, eqIdx).trim());
+      const value = decodeURIComponent(pair.slice(eqIdx + 1).trim());
+      result[key] = value;
+    }
+    return result;
+  }
+}
+
+const traceContext = new TraceContext();
+
+module.exports = { TraceContext, traceContext };

package/src/lib/execution-trace/trace-context.js

@@ -1,182 +1,15 @@
 /**
- * TraceContext - W3C Trace Context 兼容的分布式追踪上下文
+ * ESM facade for the shared CommonJS trace-context implementation.
  *
- * 支持：
- * - traceparent 头格式: {version}-{traceId}-{parentId}-{traceFlags}
- * - tracestate 头传播
- * - AsyncLocalStorage 上下文传播
- * - Span 创建与管理
- * - Baggage 透传
+ * ProcessExecutionBroker is also consumed through CommonJS on supported Node
+ * versions. Keeping the singleton in trace-context.cjs avoids require(ESM)
+ * warnings while preserving one AsyncLocalStorage across both module systems.
  */
 
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
 
-class TraceContext {
-  constructor() {
-    this._asyncLocalStorage = new AsyncLocalStorage();
-    this._spans = new Map();
-    this._listeners = new Set();
-  }
+const require = createRequire(import.meta.url);
+const traceContextModule = require("./trace-context.cjs");
 
-  generateTraceId() {
-    return randomBytes(16).toString("hex");
-  }
-
-  generateSpanId() {
-    return randomBytes(8).toString("hex");
-  }
-
-  parseTraceparent(traceparent) {
-    if (!traceparent) return null;
-    const parts = traceparent.split("-");
-    if (parts.length !== 4) return null;
-    const [version, traceId, parentId, traceFlags] = parts;
-    if (
-      version.length !== 2 ||
-      traceId.length !== 32 ||
-      parentId.length !== 16 ||
-      traceFlags.length !== 2
-    ) {
-      return null;
-    }
-    return { version, traceId, parentId, traceFlags: parseInt(traceFlags, 16) };
-  }
-
-  formatTraceparent(traceId, spanId, traceFlags = 0x01) {
-    return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, "0")}`;
-  }
-
-  getCurrentContext() {
-    return this._asyncLocalStorage.getStore();
-  }
-
-  startRootSpan(name, attributes = {}) {
-    const traceId = this.generateTraceId();
-    const spanId = this.generateSpanId();
-    const context = {
-      traceId,
-      spanId,
-      parentSpanId: null,
-      name,
-      attributes,
-      startTime: Date.now(),
-      tracestate: "",
-      baggage: {},
-    };
-    this._spans.set(spanId, context);
-    this._emit("span:start", context);
-    return context;
-  }
-
-  startSpan(name, attributes = {}) {
-    const parent = this.getCurrentContext();
-    if (!parent) {
-      return this.startRootSpan(name, attributes);
-    }
-    const spanId = this.generateSpanId();
-    const context = {
-      traceId: parent.traceId,
-      spanId,
-      parentSpanId: parent.spanId,
-      name,
-      attributes: { ...attributes },
-      startTime: Date.now(),
-      tracestate: parent.tracestate || "",
-      baggage: { ...(parent.baggage || {}) },
-    };
-    this._spans.set(spanId, context);
-    this._emit("span:start", context);
-    return context;
-  }
-
-  endSpan(span, status = { code: "OK" }) {
-    if (!span || !this._spans.has(span.spanId)) return;
-    span.endTime = Date.now();
-    span.duration = span.endTime - span.startTime;
-    span.status = status;
-    this._emit("span:end", span);
-    this._spans.delete(span.spanId);
-  }
-
-  async runInContext(context, fn) {
-    return this._asyncLocalStorage.run(context, fn);
-  }
-
-  getPropagationEnv() {
-    const ctx = this.getCurrentContext();
-    if (!ctx) return {};
-    const env = {
-      TRACEPARENT: this.formatTraceparent(ctx.traceId, ctx.spanId),
-    };
-    if (ctx.tracestate) {
-      env.TRACESTATE = ctx.tracestate;
-    }
-    if (ctx.baggage && Object.keys(ctx.baggage).length > 0) {
-      env.BAGGAGE = Object.entries(ctx.baggage)
-        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-        .join(",");
-    }
-    return env;
-  }
-
-  extractFromEnv(env = process.env) {
-    const traceparent = env.TRACEPARENT || env.traceparent;
-    if (!traceparent) return null;
-    const parsed = this.parseTraceparent(traceparent);
-    if (!parsed) return null;
-    const context = {
-      traceId: parsed.traceId,
-      spanId: parsed.parentId,
-      parentSpanId: null,
-      name: "inherited",
-      attributes: {},
-      startTime: Date.now(),
-      tracestate: env.TRACESTATE || env.tracestate || "",
-      baggage: this._parseBaggage(env.BAGGAGE || env.baggage),
-    };
-    return context;
-  }
-
-  on(event, listener) {
-    this._listeners.add({ event, listener });
-  }
-
-  off(event, listener) {
-    for (const entry of this._listeners) {
-      if (entry.event === event && entry.listener === listener) {
-        this._listeners.delete(entry);
-        break;
-      }
-    }
-  }
-
-  _emit(event, data) {
-    for (const { event: ev, listener } of this._listeners) {
-      if (ev === event) {
-        try {
-          listener(data);
-        } catch (e) {
-          // Silently ignore listener errors
-        }
-      }
-    }
-  }
-
-  _parseBaggage(baggage) {
-    if (!baggage) return {};
-    const result = {};
-    for (const pair of baggage.split(",")) {
-      const eqIdx = pair.indexOf("=");
-      if (eqIdx === -1) continue;
-      const key = decodeURIComponent(pair.slice(0, eqIdx).trim());
-      const value = decodeURIComponent(pair.slice(eqIdx + 1).trim());
-      result[key] = value;
-    }
-    return result;
-  }
-}
-
-export { TraceContext };
-export const traceContext = new TraceContext();
+export const { TraceContext, traceContext } = traceContextModule;
 export default traceContext;