@chidchanun/bcp 0.2.17 → 0.2.18

package/packages/client/src/deployment.mjs

@@ -0,0 +1,609 @@
+// packages/server/src/deployment.ts
+import {
+  randomUUID
+} from "node:crypto";
+
+// packages/server/src/production-hardening.ts
+var nextShutdownHookId = 1;
+var shutdownHooks = /* @__PURE__ */ new Map();
+function registerShutdownHook(hook, options = {}) {
+  if (typeof hook !== "function") {
+    throw new TypeError(
+      "BCP Framework: shutdown hook must be a function."
+    );
+  }
+  const id = nextShutdownHookId++;
+  const name = normalizeHookName(
+    options.name,
+    id
+  );
+  shutdownHooks.set(
+    id,
+    {
+      id,
+      name,
+      hook
+    }
+  );
+  return () => {
+    shutdownHooks.delete(
+      id
+    );
+  };
+}
+function normalizeHookName(value, id) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return `hook-${id}`;
+  }
+  if (normalized.length > 128 || /[\r\n]/.test(
+    normalized
+  )) {
+    throw new TypeError(
+      "BCP Framework: shutdown hook name must be at most 128 characters without line breaks."
+    );
+  }
+  return normalized;
+}
+
+// packages/server/src/deployment.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
+var DEFAULT_READINESS_TIMEOUT_MS = 5e3;
+var DEFAULT_SIGNALS = [
+  "SIGTERM",
+  "SIGINT"
+];
+function createDeploymentRuntime(options) {
+  const environment = options.environment ?? process.env;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const shutdownTimeoutMs = positiveInteger(
+    options.shutdownTimeoutMs ?? parseOptionalPositiveInteger(
+      environment.BCP_SHUTDOWN_TIMEOUT_MS
+    ) ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    "shutdownTimeoutMs"
+  );
+  const readinessTimeoutMs = positiveInteger(
+    options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS,
+    "readinessTimeoutMs"
+  );
+  const startedAtMs = now();
+  assertTimestamp(
+    startedAtMs,
+    "runtime start timestamp"
+  );
+  const metadata = {
+    serviceName: normalizeName(
+      options.serviceName,
+      "serviceName"
+    ),
+    ...normalizeOptionalText(
+      options.version
+    ) ? {
+      version: normalizeOptionalText(
+        options.version
+      )
+    } : {},
+    deploymentId: normalizeName(
+      options.deploymentId ?? environment.BCP_DEPLOYMENT_ID ?? idFactory(),
+      "deploymentId"
+    ),
+    ...normalizeOptionalText(
+      options.instanceId ?? environment.BCP_INSTANCE_ID
+    ) ? {
+      instanceId: normalizeOptionalText(
+        options.instanceId ?? environment.BCP_INSTANCE_ID
+      )
+    } : {},
+    ...normalizeOptionalText(
+      options.release ?? environment.BCP_RELEASE
+    ) ? {
+      release: normalizeOptionalText(
+        options.release ?? environment.BCP_RELEASE
+      )
+    } : {},
+    ...normalizeOptionalText(
+      options.environmentName ?? environment.NODE_ENV
+    ) ? {
+      environment: normalizeOptionalText(
+        options.environmentName ?? environment.NODE_ENV
+      )
+    } : {},
+    startedAt: new Date(startedAtMs).toISOString(),
+    pid: process.pid,
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch
+  };
+  const abortController = new AbortController();
+  const resourceEntries = [];
+  const names = /* @__PURE__ */ new Set();
+  let state = "idle";
+  let startPromise;
+  let shutdownPromise;
+  const runtime = {
+    metadata,
+    get state() {
+      return state;
+    },
+    addResource(resource) {
+      if (state !== "idle") {
+        throw new Error(
+          "BCP Deployment: resources can only be registered before runtime start."
+        );
+      }
+      const name = normalizeName(
+        resource.name,
+        "resource name"
+      );
+      if (names.has(name)) {
+        throw new Error(
+          `BCP Deployment: resource "${name}" is already registered.`
+        );
+      }
+      const normalized = {
+        ...resource,
+        name
+      };
+      const entry = {
+        resource: normalized,
+        status: {
+          name,
+          state: "registered"
+        }
+      };
+      names.add(name);
+      resourceEntries.push(entry);
+      return () => {
+        if (state !== "idle") {
+          return;
+        }
+        const index = resourceEntries.indexOf(
+          entry
+        );
+        if (index >= 0) {
+          resourceEntries.splice(
+            index,
+            1
+          );
+          names.delete(name);
+        }
+      };
+    },
+    resources() {
+      return resourceEntries.map(
+        (entry) => ({
+          ...entry.status
+        })
+      );
+    },
+    async start() {
+      if (state === "ready") {
+        return;
+      }
+      if (startPromise) {
+        return startPromise;
+      }
+      if (state === "draining" || state === "stopped") {
+        throw new Error(
+          "BCP Deployment: stopped runtime cannot be started again."
+        );
+      }
+      if (state === "failed") {
+        throw new Error(
+          "BCP Deployment: failed runtime cannot be started again."
+        );
+      }
+      startPromise = startResources();
+      return startPromise;
+    },
+    async readiness() {
+      const checkedAtMs = now();
+      assertTimestamp(
+        checkedAtMs,
+        "readiness timestamp"
+      );
+      const results = [];
+      for (const entry of resourceEntries) {
+        if (entry.status.state !== "started") {
+          results.push({
+            name: entry.resource.name,
+            ok: false,
+            durationMs: 0,
+            detail: `Resource state is ${entry.status.state}.`
+          });
+          continue;
+        }
+        if (!entry.resource.ready) {
+          results.push({
+            name: entry.resource.name,
+            ok: true,
+            durationMs: 0
+          });
+          continue;
+        }
+        const checkStarted = performance.now();
+        try {
+          const value = await withTimeout(
+            Promise.resolve(
+              entry.resource.ready(
+                createContext()
+              )
+            ),
+            readinessTimeoutMs,
+            `readiness check for ${entry.resource.name}`
+          );
+          const normalized = typeof value === "boolean" ? {
+            ok: value
+          } : value;
+          results.push({
+            name: entry.resource.name,
+            ok: normalized.ok === true,
+            durationMs: elapsedMilliseconds(
+              checkStarted
+            ),
+            ...normalized.detail ? {
+              detail: normalized.detail
+            } : {}
+          });
+        } catch (error) {
+          results.push({
+            name: entry.resource.name,
+            ok: false,
+            durationMs: elapsedMilliseconds(
+              checkStarted
+            ),
+            detail: errorMessage(error)
+          });
+        }
+      }
+      return {
+        ok: state === "ready" && results.every(
+          (item) => item.ok
+        ),
+        state,
+        checkedAt: new Date(
+          checkedAtMs
+        ).toISOString(),
+        resources: results
+      };
+    },
+    async diagnostics() {
+      const resources = [];
+      for (const entry of resourceEntries) {
+        let details;
+        let error;
+        if (entry.resource.diagnostics) {
+          try {
+            details = await entry.resource.diagnostics(
+              createContext()
+            );
+          } catch (diagnosticError) {
+            error = errorMessage(
+              diagnosticError
+            );
+          }
+        }
+        resources.push({
+          name: entry.resource.name,
+          lifecycle: {
+            ...entry.status
+          },
+          ...details ? {
+            details
+          } : {},
+          ...error ? {
+            error
+          } : {}
+        });
+      }
+      return {
+        metadata: {
+          ...metadata
+        },
+        state,
+        uptimeSeconds: Math.max(
+          0,
+          (now() - startedAtMs) / 1e3
+        ),
+        resources
+      };
+    },
+    async shutdown(_options = {}) {
+      if (shutdownPromise) {
+        return shutdownPromise;
+      }
+      if (state === "stopped") {
+        return;
+      }
+      shutdownPromise = stopResources();
+      return shutdownPromise;
+    },
+    installSignalHandlers(signalOptions = {}) {
+      const signals = normalizeSignals(
+        signalOptions.signals ?? DEFAULT_SIGNALS
+      );
+      const handlers = /* @__PURE__ */ new Map();
+      for (const signal of signals) {
+        const handler = () => {
+          void runtime.shutdown({
+            reason: signal
+          }).then(
+            () => {
+              if (signalOptions.setExitCode !== false) {
+                process.exitCode = 0;
+              }
+            },
+            () => {
+              process.exitCode = 1;
+            }
+          );
+        };
+        handlers.set(
+          signal,
+          handler
+        );
+        process.on(
+          signal,
+          handler
+        );
+      }
+      return () => {
+        for (const [
+          signal,
+          handler
+        ] of handlers) {
+          process.off(
+            signal,
+            handler
+          );
+        }
+        handlers.clear();
+      };
+    },
+    registerShutdownHook(name = `deployment:${metadata.serviceName}`) {
+      return registerShutdownHook(
+        () => runtime.shutdown({
+          reason: "framework-shutdown"
+        }),
+        {
+          name
+        }
+      );
+    }
+  };
+  for (const resource of options.resources ?? []) {
+    runtime.addResource(resource);
+  }
+  return runtime;
+  async function startResources() {
+    state = "starting";
+    try {
+      for (const entry of resourceEntries) {
+        entry.status = {
+          name: entry.resource.name,
+          state: "starting"
+        };
+        try {
+          await entry.resource.start?.(
+            createContext()
+          );
+          entry.status = {
+            name: entry.resource.name,
+            state: "started",
+            startedAt: new Date(
+              now()
+            ).toISOString()
+          };
+        } catch (error) {
+          entry.status = {
+            name: entry.resource.name,
+            state: "failed",
+            error: errorMessage(error)
+          };
+          throw new Error(
+            `BCP Deployment: resource "${entry.resource.name}" failed to start. ${errorMessage(error)}`
+          );
+        }
+      }
+      state = "ready";
+    } catch (error) {
+      state = "failed";
+      abortController.abort(error);
+      await stopStartedResources(
+        shutdownTimeoutMs
+      );
+      throw error;
+    }
+  }
+  async function stopResources() {
+    state = "draining";
+    if (!abortController.signal.aborted) {
+      abortController.abort(
+        new Error(
+          "BCP Deployment: runtime is shutting down."
+        )
+      );
+    }
+    const failures = await stopStartedResources(
+      shutdownTimeoutMs
+    );
+    state = failures.length > 0 ? "failed" : "stopped";
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        "BCP Deployment: one or more resources failed to stop."
+      );
+    }
+  }
+  async function stopStartedResources(timeoutMs) {
+    const failures = [];
+    const deadline = Date.now() + timeoutMs;
+    for (const entry of [...resourceEntries].reverse()) {
+      if (entry.status.state !== "started") {
+        continue;
+      }
+      entry.status = {
+        ...entry.status,
+        state: "stopping"
+      };
+      try {
+        const remaining = Math.max(
+          1,
+          deadline - Date.now()
+        );
+        await withTimeout(
+          Promise.resolve(
+            entry.resource.stop?.(
+              createContext()
+            )
+          ),
+          remaining,
+          `shutdown of ${entry.resource.name}`
+        );
+        entry.status = {
+          ...entry.status,
+          state: "stopped",
+          stoppedAt: new Date(
+            now()
+          ).toISOString()
+        };
+      } catch (error) {
+        const message = errorMessage(error);
+        entry.status = {
+          ...entry.status,
+          state: "failed",
+          error: message
+        };
+        failures.push(
+          new Error(
+            `BCP Deployment: resource "${entry.resource.name}" failed to stop. ${message}`
+          )
+        );
+      }
+    }
+    return failures;
+  }
+  function createContext() {
+    return {
+      metadata,
+      signal: abortController.signal
+    };
+  }
+}
+function createDeploymentReadinessResponse(runtime) {
+  return runtime.readiness().then(
+    (report) => Response.json(
+      report,
+      {
+        status: report.ok ? 200 : 503,
+        headers: {
+          "cache-control": "no-store"
+        }
+      }
+    )
+  );
+}
+async function createDeploymentDiagnosticsResponse(runtime) {
+  return Response.json(
+    await runtime.diagnostics(),
+    {
+      status: 200,
+      headers: {
+        "cache-control": "no-store"
+      }
+    }
+  );
+}
+function normalizeSignals(signals) {
+  return Array.from(
+    new Set(signals)
+  );
+}
+function normalizeName(value, field) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a non-empty string.`
+    );
+  }
+  if (normalized.length > 256 || /[\r\n]/.test(normalized)) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be at most 256 characters without line breaks.`
+    );
+  }
+  return normalized;
+}
+function normalizeOptionalText(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.trim();
+  return normalized || void 0;
+}
+function positiveInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a positive safe integer.`
+    );
+  }
+  return value;
+}
+function parseOptionalPositiveInteger(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = Number(value.trim());
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TypeError(
+      "BCP Deployment: BCP_SHUTDOWN_TIMEOUT_MS must be a positive safe integer."
+    );
+  }
+  return parsed;
+}
+function assertTimestamp(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Deployment: ${field} must be a finite number.`
+    );
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function elapsedMilliseconds(startedAt) {
+  return Math.max(
+    0,
+    performance.now() - startedAt
+  );
+}
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise(
+    (resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(
+          new Error(
+            `BCP Deployment: ${label} timed out after ${timeoutMs}ms.`
+          )
+        ),
+        timeoutMs
+      );
+      timer.unref?.();
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    }
+  );
+}
+export {
+  createDeploymentDiagnosticsResponse,
+  createDeploymentReadinessResponse,
+  createDeploymentRuntime
+};

package/packages/client/src/deployment.ts

@@ -0,0 +1,20 @@
+export {
+    createDeploymentDiagnosticsResponse,
+    createDeploymentReadinessResponse,
+    createDeploymentRuntime,
+
+    type DeploymentDiagnosticsReport,
+    type DeploymentDiagnosticsResource,
+    type DeploymentMetadata,
+    type DeploymentReadinessItem,
+    type DeploymentReadinessReport,
+    type DeploymentReadinessResult,
+    type DeploymentResource,
+    type DeploymentResourceContext,
+    type DeploymentResourceStatus,
+    type DeploymentRuntime,
+    type DeploymentRuntimeOptions,
+    type DeploymentRuntimeState,
+    type DeploymentShutdownOptions,
+    type DeploymentSignalOptions,
+} from "../../server/src/deployment.js";