@kici-dev/orchestrator 0.14.1 → 0.15.0

package/dist/routes/admin.d.ts

@@ -30,6 +30,7 @@ import type { BackendSyncManager, OrchestratorMode } from '@kici-dev/engine';
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
 import type { AccessLogWriter } from '../audit/access-log.js';
+import type { WebhookUrlResolution } from '../sources/webhook-url-resolvers.js';
 /**
  * Dependencies for admin API routes.
  */
@@ -42,10 +43,8 @@ export interface AdminRouteDeps {
      */
     databaseUrl?: string;
     /**
-     * Orchestrator operating mode. Gates mode-specific admin behavior — today the
-     * `observed`-mode refusal of GitHub-App source creation (those sources are
-     * Platform-relayed by nature, and an observed orchestrator never accepts a
-     * relay). Optional so WS-only / test admins can omit it.
+     * Orchestrator operating mode. Gates mode-specific admin behavior. Optional so
+     * WS-only / test admins can omit it.
      */
     mode?: OrchestratorMode;
     /**
@@ -104,26 +103,24 @@ export interface AdminRouteDeps {
     sourceStore?: SourceStore;
     /**
      * Optional -- resolves the public webhook URL for a newly added source so
-     * `kici-admin source add` can print it. Wired in platform/hybrid mode to
-     * register-and-await the Platform ack; independent mode returns a null URL
-     * with a note.
+     * `kici-admin source add` can print it. The rules per mode live in
+     * `sources/webhook-url-resolvers.ts`.
      */
     resolveSourceWebhookUrl?: (params: {
         routingKey: string;
         provider: string;
         sourceId: string;
-    }) => Promise<{
-        webhookUrl: string | null;
-        webhookNote?: string;
-    }>;
+    }) => Promise<WebhookUrlResolution>;
     /**
      * Optional -- resolves the org-scoped GitHub webhook URL for the manifest
-     * setup pre-flight (before any App exists). Wired in platform/hybrid mode.
-     */
-    resolveGithubWebhookUrl?: () => Promise<{
-        webhookUrl: string | null;
-        webhookNote?: string;
-    }>;
+     * setup pre-flight (before any App exists), by mode.
+     */
+    resolveGithubWebhookUrl?: () => Promise<WebhookUrlResolution>;
+    /** Optional — builds the direct-ingress URL `source list` prints per GitHub source. */
+    resolveSourceIngressUrl?: (row: {
+        id: string;
+        customerId: string | null;
+    }) => string | null;
     /** Optional -- for DB migration endpoints. */
     db?: Kysely<any>;
     /** Optional -- for DB migration endpoints. */

package/dist/routes/cluster-join.d.ts

@@ -0,0 +1,13 @@
+/**
+ * POST /api/v1/cluster/join: the direct transport of `kici-admin join --peer`.
+ *
+ * The body is the same join.request the Platform relays. Unauthenticated by design:
+ * the joiner proves it holds a join token inside the request. A version-1 body (one
+ * that carries the token) is refused with 426 and `Upgrade: kici-join-v2`.
+ */
+import { Hono } from 'hono';
+import { type JoinResponse } from '@kici-dev/engine';
+/** HTTP status for a join answer: a refusal without an error code is an internal failure. */
+export declare function joinResponseHttpStatus(response: JoinResponse): 200 | 400 | 401 | 426 | 500;
+export declare function createClusterJoinRoutes(onJoinRequest: (raw: unknown) => Promise<JoinResponse>): Hono;
+//# sourceMappingURL=cluster-join.d.ts.map

package/dist/routes/github-webhook.d.ts

@@ -25,19 +25,21 @@ export interface GithubWebhookRoutesDeps {
  */
 export declare function shouldServeGithubIngress(mode: OrchestratorMode): boolean;
 /**
- * Direct GitHub-App webhook ingress: `POST /webhook/:orgId/github/:sourceId`.
+ * Direct GitHub webhook ingress, bypassing the Platform relay:
  *
- * Bypasses the Platform relay. Handles both operator topologies on one route:
- *  - App-level repoint: the App's single webhook URL points here, so GitHub
- *    sends `X-GitHub-Hook-Installation-Target-Type: integration` +
- *    `-Target-ID: <appId>` — validated against the source's routing key.
- *  - Classic per-repo webhook: a repo-level hook points here with no App
- *    target headers — `:sourceId` already identifies the source, so the
- *    App-header check is skipped.
+ *  - `POST /webhook/:orgId/github/:sourceId` (per-source) serves an App-level
+ *    repoint (GitHub sends `X-GitHub-Hook-Installation-Target-Type:
+ *    integration` + `-Target-ID: <appId>`, validated against the source's
+ *    routing key) and a classic repository hook (no App target headers;
+ *    `:sourceId` identifies the source).
+ *  - `POST /webhook/:orgId/github` (org-scoped) serves an App-level webhook:
+ *    the App's target id names the source. It is the URL the manifest flow
+ *    bakes into a new App in observed and independent mode.
  *
- * Verification is the existing local `verify-inbound.ts` GitHub path (secret
- * read from the orchestrator secret store; rotation-aware). Dedup + dispatch
- * are the universal `processWebhook` pipeline via `onWebhook`.
+ * Both routes share verification (the local `verify-inbound.ts` GitHub path,
+ * secret read from the orchestrator secret store, rotation-aware), dedup on the
+ * raw `X-GitHub-Delivery`, and ingest through the `processWebhook` pipeline via
+ * `onWebhook`.
  */
 export declare function createGithubWebhookRoutes(deps: GithubWebhookRoutesDeps): Hono;
 //# sourceMappingURL=github-webhook.d.ts.map

package/dist/scaler/bare-metal-backend.d.ts

@@ -49,6 +49,18 @@ export interface BareMetalScalerBackendOptions {
      * (`systemd-run` does not exist), with a one-time startup warning.
      */
     enforceCgroups?: boolean;
+    /**
+     * Run the `nft` calls of job-image mode (the scaler-level `requireSudo`)
+     * through `sudo -n`, for an orchestrator that runs as a non-root user with a
+     * NOPASSWD sudoers rule for nft. Process mode runs no nft. Default false.
+     */
+    requireSudo?: boolean;
+    /**
+     * Extra `host:address` mappings (the scaler-level `extraHosts`) for the agent
+     * containers of job-image mode, passed to the runtime as `ExtraHosts`.
+     * Process mode ignores them.
+     */
+    extraHosts?: string[];
 }
 export declare class BareMetalScalerBackend implements ScalerBackend {
     readonly type: "bare-metal";
@@ -71,7 +83,36 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     private readonly logCaptures;
     /** Container-mode agents' IPs on the isolated network, for nftables cleanup. */
     private readonly containerIps;
-    constructor(options: BareMetalScalerBackendOptions);
+    /** Whether job-image mode's nft calls run through `sudo -n`. */
+    private readonly requireSudo;
+    private readonly extraHosts?;
+    /**
+     * Why this host cannot run nft the way {@link requireSudo} asks, as `create`
+     * probed it; `null` when it can. `reload` is synchronous and reads it to
+     * refuse job-image label sets a reload adds.
+     */
+    private readonly nftFailure;
+    /**
+     * Build a backend and check, once, that this host can run nft the way the
+     * scaler asks. A scaler with a job-image label set is refused here when it
+     * cannot, so the orchestrator stops at startup (and a reload that adds the
+     * scaler fails) instead of failing every spawn. A process-only scaler is
+     * never refused: process mode runs no nft.
+     */
+    static create(options: BareMetalScalerBackendOptions): Promise<BareMetalScalerBackend>;
+    /**
+     * @param nftFailure - The `create` probe's answer. A backend built directly
+     * was not probed, and is treated as able to run nft.
+     */
+    constructor(options: BareMetalScalerBackendOptions, nftFailure?: string | null);
+    /**
+     * Why a reload's job-image label sets cannot run here. `reload` is
+     * synchronous and cannot probe nft, so it reads what `create` probed — which
+     * holds only for the `requireSudo` the backend was built with.
+     */
+    private jobImageReloadErrors;
+    /** How every nft call of job-image mode runs: through `sudo -n` or not. */
+    private nftOpts;
     /**
      * Warn about label sets whose `networkPolicy` this backend cannot enforce.
      *

package/dist/scaler/types.d.ts

@@ -497,7 +497,8 @@ export interface ScalerEntry {
     orchestratorUrl?: string;
     /**
      * Extra host:IP mappings for spawned agents (e.g. ["registry.local:host-gateway"]): the
-     * container runtime's ExtraHosts, or each Firecracker guest's /etc/hosts.
+     * container runtime's ExtraHosts (container scaler, bare-metal job-image agents), or
+     * each Firecracker guest's /etc/hosts.
      */
     extraHosts?: string[];
     /** Disable nftables-based network isolation for container backend (default: true). Set to false when nft is unavailable. */
@@ -564,10 +565,11 @@ export interface ScalerEntry {
     /** Default memory in MiB for VMs @default 512 */
     memSizeMib?: number;
     /**
-     * Wrap privileged commands (`ip`, `chown`) with `sudo -n` when the
-     * orchestrator runs as a non-root user (e.g. user-mode systemd on edge
-     * worker nodes). Operators must have NOPASSWD sudoers entries for those
-     * binaries. Default false.
+     * Wrap privileged commands with `sudo -n` when the orchestrator runs as a
+     * non-root user (e.g. user-mode systemd on edge worker nodes): the Firecracker
+     * backend's `ip`, `chown`, `chmod`, `kill` and `nft`, and the `nft` of a
+     * bare-metal scaler's job-image label sets. Operators must have NOPASSWD
+     * sudoers entries for those binaries. Default false.
      */
     requireSudo?: boolean;
     /**