@kindgi/handler-runtime 0.0.0-bootstrap.0 → 0.1.0

package/src/pack-env.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The process environment a pack's code reads: names its handlers and the
+ * libraries they import take from `process.env` (a database URL a client
+ * reads at import, a bucket name). Declared once per pack, in
+ * `kindgi.config` (`env: { required, optional }`; Python:
+ * `[tool.kindgi.env]`), and carried in `index.json`, so the pack service
+ * in an image knows what it needs.
+ *
+ * A deployment injects exactly these names: `required` must be there for
+ * the pack service to be ready, `optional` is injected when the target
+ * has a value. Nothing else from an env file reaches the process.
+ *
+ * Distinct from `needsSpec.env` / `ctx.env`, the per-call values the
+ * runtime resolves for a call's tenant, and from `needsSpec.secrets` /
+ * `ctx.secrets`.
+ */
+
+/** A pack's declared process environment, as `index.json` carries it. */
+export interface PackEnvDeclaration {
+  /** Names the pack service needs, set and non-empty, to be ready. Sorted. */
+  readonly required: readonly string[];
+  /** Names the pack reads when present. Sorted. */
+  readonly optional: readonly string[];
+}
+
+/** `env` in `kindgi.config`, as the author writes it. */
+export interface PackEnvConfig {
+  readonly required?: readonly string[];
+  readonly optional?: readonly string[];
+}
+
+/** A process environment variable name. */
+export const PACK_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The prefix of the names that configure Kindgi itself; never a pack's. */
+export const RESERVED_ENV_PREFIX = 'KINDGI_';
+
+export type PackEnvResult =
+  | { readonly kind: 'ok'; readonly value: PackEnvDeclaration | undefined }
+  | { readonly kind: 'err'; readonly message: string };
+
+/**
+ * Validate a config's `env` and normalize it to what the index carries:
+ * both lists, each sorted (code-unit order). `undefined` when nothing is
+ * declared, so an index without `env` stays byte-identical.
+ *
+ * Refused: a name that isn't an environment variable name, a `KINDGI_*`
+ * name, a name listed twice, and a name in both lists.
+ */
+export function resolvePackEnv(env: unknown): PackEnvResult {
+  if (env === undefined) return { kind: 'ok', value: undefined };
+  if (env === null || typeof env !== 'object' || Array.isArray(env)) {
+    return {
+      kind: 'err',
+      message: '`env` must be an object: { required?: string[], optional?: string[] }',
+    };
+  }
+  const unknownKeys = Object.keys(env).filter((k) => k !== 'required' && k !== 'optional');
+  if (unknownKeys.length > 0) {
+    return {
+      kind: 'err',
+      message: `\`env\` takes only \`required\` and \`optional\`, not ${unknownKeys.map((k) => `\`${k}\``).join(', ')}`,
+    };
+  }
+  const { required, optional } = env as {
+    readonly required?: unknown;
+    readonly optional?: unknown;
+  };
+  const lists = { required, optional };
+  const problems: string[] = [];
+  const seen = new Map<string, string>();
+  for (const [list, names] of Object.entries(lists)) {
+    if (names === undefined) continue;
+    if (!Array.isArray(names) || names.some((n) => typeof n !== 'string')) {
+      problems.push(`\`env.${list}\` must be a list of names`);
+      continue;
+    }
+    for (const name of names as string[]) {
+      if (!PACK_ENV_NAME.test(name)) {
+        problems.push(`"${name}" in \`env.${list}\` isn't an environment variable name`);
+      } else if (name.startsWith(RESERVED_ENV_PREFIX)) {
+        problems.push(
+          `"${name}" in \`env.${list}\`: \`${RESERVED_ENV_PREFIX}*\` names configure Kindgi, not the pack`,
+        );
+      } else if (seen.has(name)) {
+        const first = seen.get(name);
+        problems.push(
+          first === list
+            ? `"${name}" is listed twice in \`env.${list}\``
+            : `"${name}" is in both \`env.required\` and \`env.optional\``,
+        );
+      } else {
+        seen.set(name, list);
+      }
+    }
+  }
+  if (problems.length > 0) return { kind: 'err', message: problems.join('; ') };
+
+  const sorted = (names: unknown): string[] =>
+    Array.isArray(names) ? [...(names as string[])].sort(byCodeUnit) : [];
+  const declaration = { optional: sorted(optional), required: sorted(required) };
+  if (declaration.required.length === 0 && declaration.optional.length === 0) {
+    return { kind: 'ok', value: undefined };
+  }
+  return { kind: 'ok', value: declaration };
+}
+
+/**
+ * The required names `environment` doesn't provide: not set, or set to
+ * the empty string. Sorted, like the declaration.
+ */
+export function missingPackEnv(
+  declaration: PackEnvDeclaration | undefined,
+  environment: Readonly<Record<string, string | undefined>>,
+): readonly string[] {
+  if (declaration === undefined) return [];
+  return declaration.required.filter((name) => {
+    const value = environment[name];
+    return value === undefined || value === '';
+  });
+}
+
+/** How the pack service treats missing required names (`KINDGI_PACK_ENV_CHECK`). */
+export type PackEnvCheck = 'strict' | 'warn';
+
+/** The variable that sets {@link PackEnvCheck}. */
+export const PACK_ENV_CHECK_VAR = 'KINDGI_PACK_ENV_CHECK';
+
+/** `KINDGI_PACK_ENV_CHECK`'s value; unset or empty is `strict`. */
+export function parsePackEnvCheck(
+  raw: string | undefined,
+):
+  | { readonly kind: 'ok'; readonly value: PackEnvCheck }
+  | { readonly kind: 'err'; readonly message: string } {
+  if (raw === undefined || raw === '' || raw === 'strict') return { kind: 'ok', value: 'strict' };
+  if (raw === 'warn') return { kind: 'ok', value: 'warn' };
+  return {
+    kind: 'err',
+    message: `${PACK_ENV_CHECK_VAR} must be \`strict\` or \`warn\`, not "${raw}"`,
+  };
+}
+
+function byCodeUnit(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/pack-service/index.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { createPackService } from './service.js';
+export type { PackService, PackServiceLogEvent, PackServiceOptions } from './service.js';
+export { PACK_SERVICE_DRAIN_MS, main, readPackServiceConfig, startPackService } from './main.js';
+export type { PackServiceConfig, RunningPackService } from './main.js';
+export { createPackServiceSupervisor } from './supervisor.js';
+export type {
+  BootFailure,
+  PackRelay,
+  PackRelayCall,
+  PackRelayOutcome,
+  PackServiceSupervisor,
+  PackServiceSupervisorEvent,
+  PackServiceSupervisorOptions,
+} from './supervisor.js';

package/src/pack-service/main.ts

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The pack service process: `node dist/pack-service/main.js
+ * [--index <path>] [--module-root <dir>] [--bundle-map <path>]
+ * [--host <address>]` (package export
+ * `@kindgi/handler-runtime/pack-service-main`).
+ *
+ * Configuration (arguments win over environment):
+ *   - index:        `--index`, else `KINDGI_PACK_INDEX`, else `/app/index.json`
+ *   - module root:  `--module-root`, else the index's directory — where
+ *                   the index's module paths resolve
+ *   - bundle map:   `--bundle-map` (optional) — a build's map of each
+ *                   source path the index names to its bundle, relative
+ *                   to the module root (`kindgi build` writes
+ *                   `dist/bundle-map.json`): modules load from the bundles
+ *   - token:        `KINDGI_PACK_SERVICE_TOKEN` (required)
+ *   - concurrency:  `KINDGI_PACK_SERVICE_MAX_CONCURRENCY` (default 32)
+ *   - env check:    `KINDGI_PACK_ENV_CHECK`, `strict` (default) | `warn`:
+ *                   whether a required env name the index declares and the
+ *                   process lacks keeps the service from being ready
+ *   - port:         `PORT` (platform convention; default 8080; `0` picks one)
+ *   - host:         `--host`, else every interface (a container platform
+ *                   such as Cloud Run needs that); a local supervisor
+ *                   passes `127.0.0.1`
+ *
+ * Boot fails (exit 1, listing every problem) when the index can't be
+ * read, a module it names is missing, or a module fails to import — so a
+ * broken build never becomes ready. SIGTERM drains in-flight calls
+ * (readyz answers 503 meanwhile) and exits 0.
+ *
+ * Logs are JSON lines on stderr. The `listening` line carries the bound
+ * port, for callers that start it with `PORT=0`.
+ */
+
+import { access, readFile } from 'node:fs/promises';
+import { type Server, createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { isProcessEntrypoint } from '../entrypoint.js';
+import type { Index } from '../kindgi-index.js';
+import { INDEX_ENVELOPE_VERSION, readBundleMap } from '../kindgi-index.js';
+import { PACK_ENV_CHECK_VAR, type PackEnvCheck, parsePackEnvCheck } from '../pack-env.js';
+import { type PackService, type PackServiceLogEvent, createPackService } from './service.js';
+
+export interface PackServiceConfig {
+  readonly indexPath: string;
+  readonly moduleRoot: string;
+  /** A build's bundle map (source path → bundle path under `moduleRoot`). */
+  readonly bundleMapPath?: string;
+  readonly token: string;
+  readonly port: number;
+  /** The listen address. Absent: every interface. */
+  readonly host?: string;
+  readonly maxConcurrency?: number;
+  /** Default `strict`. */
+  readonly envCheck?: PackEnvCheck;
+}
+
+type ConfigOutcome =
+  | { readonly kind: 'ok'; readonly value: PackServiceConfig }
+  | { readonly kind: 'err'; readonly problems: readonly string[] };
+
+/** Read the process configuration from arguments and environment. */
+export function readPackServiceConfig(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+): ConfigOutcome {
+  const arg = (name: string): string | undefined => {
+    const at = argv.indexOf(name);
+    return at >= 0 ? argv[at + 1] : undefined;
+  };
+  const problems: string[] = [];
+  const indexPath = resolve(arg('--index') ?? env.KINDGI_PACK_INDEX ?? '/app/index.json');
+  const moduleRoot = resolve(arg('--module-root') ?? dirname(indexPath));
+  const bundleMap = arg('--bundle-map');
+  if (bundleMap === '') problems.push('--bundle-map needs a path');
+  const host = arg('--host');
+  if (host === '') problems.push('--host needs an address');
+  const token = env.KINDGI_PACK_SERVICE_TOKEN ?? '';
+  if (token.length === 0) problems.push('KINDGI_PACK_SERVICE_TOKEN is required');
+  const port = Number(env.PORT ?? '8080');
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    problems.push(`PORT must be a port number, got ${JSON.stringify(env.PORT)}`);
+  }
+  const rawConcurrency = env.KINDGI_PACK_SERVICE_MAX_CONCURRENCY;
+  const maxConcurrency = rawConcurrency === undefined ? undefined : Number(rawConcurrency);
+  if (maxConcurrency !== undefined && (!Number.isInteger(maxConcurrency) || maxConcurrency < 1)) {
+    problems.push('KINDGI_PACK_SERVICE_MAX_CONCURRENCY must be a positive integer');
+  }
+  const envCheck = parsePackEnvCheck(env[PACK_ENV_CHECK_VAR]);
+  if (envCheck.kind === 'err') problems.push(envCheck.message);
+  if (problems.length > 0 || envCheck.kind === 'err') return { kind: 'err', problems };
+  return {
+    kind: 'ok',
+    value: {
+      indexPath,
+      moduleRoot,
+      ...(bundleMap && { bundleMapPath: resolve(bundleMap) }),
+      token,
+      port,
+      ...(host && { host }),
+      ...(maxConcurrency !== undefined && { maxConcurrency }),
+      envCheck: envCheck.value,
+    },
+  };
+}
+
+/** How long SIGTERM lets in-flight calls finish (sized for Cloud Run's 10 s SIGTERM→SIGKILL window). */
+export const PACK_SERVICE_DRAIN_MS = 8_000;
+
+export interface RunningPackService {
+  readonly service: PackService;
+  readonly server: Server;
+  readonly port: number;
+  /** Drain in-flight calls (up to `graceMs`), then stop listening. */
+  stop(graceMs?: number): Promise<void>;
+}
+
+type StartOutcome =
+  | { readonly kind: 'ok'; readonly value: RunningPackService }
+  | { readonly kind: 'err'; readonly problems: readonly string[] };
+
+/** Load the index, check and prewarm every module, then listen. */
+export async function startPackService(
+  config: PackServiceConfig,
+  logger: (event: PackServiceLogEvent | Record<string, unknown>) => void = logJson,
+): Promise<StartOutcome> {
+  let index: Index;
+  try {
+    index = JSON.parse(await readFile(config.indexPath, 'utf8')) as Index;
+  } catch (cause) {
+    return { kind: 'err', problems: [`Cannot read the pack index: ${describe(cause)}`] };
+  }
+  if (index.v !== INDEX_ENVELOPE_VERSION) {
+    return {
+      kind: 'err',
+      problems: [`Index envelope v${String(index.v)} is not v${INDEX_ENVELOPE_VERSION}`],
+    };
+  }
+  let bundles: Readonly<Record<string, string>> = {};
+  if (config.bundleMapPath !== undefined) {
+    const read = await readBundleMap(config.bundleMapPath);
+    if (read.kind === 'err') return { kind: 'err', problems: [read.message] };
+    bundles = read.value;
+  }
+  // A module the index names loads from its bundle when the build mapped it.
+  const resolveModule = (modulePath: string): string => {
+    const target = bundles[modulePath] ?? modulePath;
+    return isAbsolute(target) ? target : resolve(config.moduleRoot, target);
+  };
+
+  const missing: string[] = [];
+  const paths = [
+    ...index.tools.map((t) => t.modulePath),
+    ...index.guardrails.map((g) => g.checkModulePath),
+  ];
+  for (const p of paths) {
+    await access(resolveModule(p)).catch(() => missing.push(`Missing module: ${p}`));
+  }
+  if (missing.length > 0) return { kind: 'err', problems: missing };
+
+  const service = createPackService({
+    index,
+    resolveModule,
+    token: config.token,
+    ...(config.maxConcurrency !== undefined && { maxConcurrency: config.maxConcurrency }),
+    ...(config.envCheck !== undefined && { envCheck: config.envCheck }),
+    logger,
+  });
+  const failures = await service.prewarm();
+  if (failures.length > 0) return { kind: 'err', problems: failures.map((f) => f.message) };
+
+  const server = createServer(service.handle);
+  await new Promise<void>((ready) =>
+    config.host === undefined
+      ? server.listen(config.port, ready)
+      : server.listen(config.port, config.host, ready),
+  );
+  const port = (server.address() as AddressInfo).port;
+  logger({
+    kind: 'listening',
+    port,
+    packId: index.packId,
+    artifactVersion: index.artifactVersion,
+  });
+  return {
+    kind: 'ok',
+    value: {
+      service,
+      server,
+      port,
+      async stop(graceMs = PACK_SERVICE_DRAIN_MS) {
+        await service.drain(graceMs);
+        // Calls have finished (or the grace ran out). What is left is an idle
+        // keep-alive or a caller that went away mid-call, whose half-open
+        // connection would otherwise hold `close` for seconds.
+        const closed = new Promise<void>((done) => server.close(() => done()));
+        server.closeAllConnections();
+        await closed;
+      },
+    },
+  };
+}
+
+/** Process entry. Resolves with the exit code. */
+export async function main(
+  argv: readonly string[] = process.argv.slice(2),
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Promise<number> {
+  const config = readPackServiceConfig(argv, env);
+  if (config.kind === 'err') {
+    logJson({ kind: 'config-invalid', problems: config.problems });
+    return 1;
+  }
+  // The token is for the service's callers. The pack's code, loaded
+  // next, runs in this process and has no use for it — and a dependency
+  // that read it could call the pack's tools around the runtime.
+  Reflect.deleteProperty(process.env, 'KINDGI_PACK_SERVICE_TOKEN');
+  const started = await startPackService(config.value);
+  if (started.kind === 'err') {
+    logJson({ kind: 'boot-failed', problems: started.problems });
+    return 1;
+  }
+  await new Promise<void>((stopped) => {
+    process.once('SIGTERM', () => {
+      logJson({ kind: 'draining' });
+      void started.value.stop().then(stopped);
+    });
+  });
+  logJson({ kind: 'stopped' });
+  return 0;
+}
+
+function logJson(event: PackServiceLogEvent | Record<string, unknown>): void {
+  process.stderr.write(`${JSON.stringify(event)}\n`);
+}
+
+function describe(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+if (isProcessEntrypoint(import.meta.url)) {
+  void main().then((code) => process.exit(code));
+}