@inquir/compute 0.3.0 → 0.4.1

package/README.md

@@ -2,14 +2,19 @@
 
 Workspace-first SDK for defining, discovering, generating, and running Inquir Compute assets.
 
-## Install
-
-Requires Node.js 22 or newer. Version 0.3 groups only long-lived container applications in projects; functions and pipelines remain separate assets.
+## Install
+
+Requires Node.js 22 or newer. Version 0.3 groups only long-lived container applications in projects; functions and pipelines remain separate assets.
 
 ```bash
-npm install @inquir/compute zod@^3.23.8
+npm install @inquir/compute zod@^3.23.8
 ```
 
+> Release order: publish this SDK before the CLI that depends on it. CLI 0.4.0
+> needs SDK 0.4.0 (`isPromoteAccepted`, `getApplicationRollout`); the next CLI
+> needs SDK 0.4.1 (`listAppInstances`, `matchAppInstance`); see
+> `packages/cli/README.md`, "Publishing to npm".
+
 ## What It Includes
 
 - `defineFunction()` and `definePipeline()` for code-first assets.
@@ -17,8 +22,82 @@ npm install @inquir/compute zod@^3.23.8
 - `discoverAssets()` for workspace asset scanning.
 - `generateCodegenArtifacts()` / `generateAndWriteCodegenArtifacts()` for typed client + `registry.json`.
 - `runLocally()` for local function execution/debug harness.
-- HTTP transport helpers (`createClient`, `invokeRemote`, deploy/list helpers).
-- Application project helpers (`listProjects`, `createProject`, `getProject`, `addProjectResource`) group long-lived containers: web services, APIs, databases, and workers. Project members use `kind: 'application'`; serverless functions are managed separately. `createApplication` accepts `projectId` (ID or slug); omitting it creates a project named after the application.
+- HTTP transport helpers (`createClient`, `invokeRemote`, deploy/list helpers).
+- Application project helpers (`listProjects`, `createProject`, `getProject`, `addProjectResource`) group long-lived containers: web services, APIs, databases, and workers. Project members use `kind: 'application'`; serverless functions are managed separately. `createApplication` accepts `projectId` (ID or slug); omitting it creates a project named after the application. Archiving a project also archives all its applications, including an application shared with another project. Removing a membership leaves it running. Project lifecycle actions require `projects:write` and `apps:promote`.
+
+## Pending synchronous invocations
+
+When the server admits a finite cold invocation, `invokeRemote()` submits once
+and follows only the authenticated invocation's `/resume` endpoint. Hot
+invocations keep their existing path. Save each handle from `onPending` if the
+caller must survive a restart:
+
+```ts
+import { invokeRemote, resumeRemoteInvocation, cancelRemoteInvocation,
+  RemoteInvocationObservationEndedError } from '@inquir/compute';
+
+try {
+  const result = await invokeRemote(client, 'my-function', event, {
+    timeoutMs: 120_000, signal, onPending: saveHandle,
+  });
+} catch (error) {
+  if (error instanceof RemoteInvocationObservationEndedError) {
+    saveHandle(error.pending); // PENDING/RECOVERY_HELD is not FAILED.
+    // Later: await resumeRemoteInvocation(client, error.pending);
+    // Explicit intent: await cancelRemoteInvocation(client, error.pending);
+  } else throw error;
+}
+```
+
+Abort/timeout stops observation, not execution. A cancellation receipt records
+intent, not a terminal outcome. If the initial POST reply is lost before a handle
+arrives, this adapter cannot recover an unknown server ID and never repeats that
+POST. Server admission remains independently gated; this client does not enable
+gateway, pipeline, durable or streaming finite execution.
+
+## Durable source commands
+
+Source execution uses an explicit operation instead of synchronous writable
+`/exec`. Save a lowercase UUID v4 before preparing, and atomically retain every
+record supplied by the callback in private storage. Records contain command/env
+secrets; they contain a credential hash rather than the credential itself.
+
+```ts
+import { createClient, prepareSourceCommand, restoreSourceCommand } from '@inquir/compute';
+
+const client = createClient({ baseUrl: apiUrl, apiKey, workspaceId });
+const operation = await prepareSourceCommand(client, {
+  function: 'my-function', requestId: savedUuid,
+  input: { command: 'npm install', timeoutMs: 60_000 },
+  retain: savePrivateRecordAtomically,
+});
+await operation.submit();                 // no automatic POST retry
+const state = await operation.status();   // GET only
+const publication = await operation.reconcile(); // explicit source publication
+// await operation.cancel();              // explicit cancellation intent
+const restored = await restoreSourceCommand(client, savedRecord, {
+  retain: savePrivateRecordAtomically,
+});                                      // no HTTP or submission
+```
+
+The retained API, credential hash, original workspace selector and resolved
+workspace/function IDs must match on restore. Later actions stay pinned to those
+IDs even if the client changes. A lost response keeps the same operation UUID;
+inspect status or explicitly retry the same action. Poll timeout/abort stops
+observation and does not cancel or publish. `EXITED` and `CANCEL_REQUESTED` do not
+prove physical removal or capacity release. A GET with `publication: null` does
+not prove that an earlier explicit publication never happened.
+
+Acceptance identity is retained before an action returns and after each poll
+response. If storage fails, further HTTP is blocked until the pending record is
+saved; `operation.persist()` retries storage without HTTP. Keep the updated
+record returned by `record()` for reloads. The server must enable the source
+command API after its activation gates; a 503 never falls back to writable exec.
+
+`result.logFailure` and `sourcePublicationState(outcome) === 'CAPTURE_FAILED'`
+mark unavailable log capture, preserving the real termination and exit code.
+Blank Base64 fields then mean unavailable capture rather than successful empty
+logs; workspace output is absent and cannot be published.
 
 ## Concepts
 
@@ -98,3 +177,80 @@ const client = createClient({ baseUrl: 'http://localhost:3000', apiKey: process.
 const response = await invokeRemote(client, 'hello', { name: 'World' });
 ```
 
+## Readonly published-release commands (scoped rollout)
+
+`prepareReleaseCommand` retains the caller's original UUID, workspace and command
+before the first HTTP submission. It uses the dedicated readonly release API;
+it does not invoke the writable source-command API or a function handler.
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { prepareReleaseCommand, restoreReleaseCommand } from '@inquir/compute';
+
+const operation = await prepareReleaseCommand(client, {
+  functionId,
+  requestId: randomUUID(),
+  input: { command: 'cat package.json', timeoutMs: 60_000 },
+  retain: async record => saveCommandRecord(record), // Durable caller storage.
+});
+const first = await operation.submit(); // Submit once. Keep the retained record on a lost reply.
+const outcome = first.state === 'PENDING' || first.state === 'RECOVERY_HELD'
+  ? await restoreReleaseCommand(client, operation.record()).observe()
+  : first;
+```
+
+Observation resumes the same ID and never repeats the initial POST. An expired
+or aborted observer keeps that handle; `operation.cancel()` separately requests
+durable cancellation. Cancellation acknowledgement is an intent, while `REMOVED`
+is a validated terminal result after physical task/container cleanup. Scope or
+artifact uncertainty remains held rather than becoming a fabricated failure.
+`CANCELLED_WITHOUT_CONTAINER` separately proves an admitted reservation was
+cancelled and physically retired before CREATE; its `result` is `null` because
+no shell ran. `CANCELLED_BEFORE_ADMISSION` has no reservation to retire.
+
+This path is disabled by default. Each exact runtime image, readonly process,
+source/input mount, resource and network profile must receive native
+qualification before its scoped operator approval and rollout switches enable
+admission. The initial source tests do not constitute that qualification.
+
+## Application observability
+
+The SDK exposes resource and HTTP history, persisted runtime/HTTP logs and configurable app alerts. Every helper uses the client's credentials and workspace selector:
+
+```ts
+import {
+  createClient, getAppMetrics, getAppHttpMetrics, getAppLogHistory,
+  createAppAlertRule, updateAppAlertRule, listAppAlertIncidents,
+} from '@inquir/compute';
+
+const client = createClient({
+  baseUrl: 'https://inquir.org/api',
+  apiKey: process.env.INQUIR_TOKEN,
+  workspaceId: process.env.INQUIR_WORKSPACE,
+});
+const to = new Date().toISOString();
+const from = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+const resources = await getAppMetrics(client, appId, { from, to });
+const http = await getAppHttpMetrics(client, appId, { from, to });
+const logs = await getAppLogHistory(client, appId, {
+  from, to, releaseId, allocationId, allocationFence: 4, level: 'error', limit: 100,
+});
+if (logs.nextCursor) {
+  const older = await getAppLogHistory(client, appId, {
+    from: logs.from, to: logs.to, releaseId, allocationId, allocationFence: 4,
+    level: 'error', limit: 100, cursor: logs.nextCursor,
+  });
+}
+
+const { rule } = await createAppAlertRule(client, appId, {
+  name: 'High RAM', enabled: true, metric: 'memory_percent',
+  threshold: 85, forSeconds: 120, recoveryThreshold: 65,
+  recoveryForSeconds: 60, noDataSeconds: 180, noData: 'alert', channels: [],
+});
+await updateAppAlertRule(client, appId, rule.id, { threshold: 90 });
+const { incidents } = await listAppAlertIncidents(client, appId, { limit: 25 });
+```
+
+`getAppHttpLogHistory`, `listAppAlertRules` and `deleteAppAlertRule` complete the API. Deletion disables the rule and resolves its active incidents; retained history is still available. Omit `channels` in a patch to preserve existing destinations, or pass an empty array to remove them. `webhook`/`slack` channel URLs are write-only; response types expose only channel id, type and configured status. Never log alert request inputs containing a secret URL.
+
+Resource and HTTP retention is 30 days; runtime logs are retained for 7 days. Runtime history is attributed to the exact release, allocation/fence, runner/epoch and container, including replaced containers. Paging is newest-first and requires an unchanged date window and filters. Resource history retains unavailable values as `null`; use `status`, `latestSampleAt` and `truncated` to detect stale or incomplete results. Network and block I/O rates are measured separately; block I/O is not volume space usage. CPU/RAM alert percentages are relative to enforced limits, and the continuous maximum across current production replicas determines threshold firing.

package/dist/app-observability.d.ts

@@ -0,0 +1,117 @@
+import { type TransportClient } from './transport.js';
+import type { AppMetricsHistoryResponse, AppHttpMetricsResponse, AppLogHistoryResponse, AppRuntimeLogEntry, AppHttpLogEntry, AppAlertRuleInput, AppAlertRuleDto, AppAlertIncidentDto, AppResourceRecommendationResponse, AppDescribeResponse } from './app-observability.types.js';
+export * from './app-observability.types.js';
+/** ISO 8601 timestamps. Preserve the same window when following a log cursor. */
+export interface AppObservationRange {
+    from?: string;
+    to?: string;
+}
+export interface AppRuntimeLogQuery extends AppObservationRange {
+    limit?: number;
+    cursor?: string;
+    releaseId?: string;
+    allocationId?: string;
+    allocationFence?: number;
+    runnerId?: string;
+    runnerEpoch?: number;
+    containerId?: string;
+    stream?: AppRuntimeLogEntry['stream'];
+    level?: Exclude<AppRuntimeLogEntry['level'], null>;
+    search?: string;
+}
+export interface AppHttpLogQuery extends AppObservationRange {
+    limit?: number;
+    cursor?: string;
+    releaseId?: string;
+    statusCode?: number;
+    query?: string;
+}
+/** Actual resource history, up to 30 days; CPU/RAM percentages use enforced limits. */
+export declare function getAppMetrics(client: TransportClient, appId: string, range?: AppObservationRange): Promise<AppMetricsHistoryResponse>;
+/**
+ * Read-only CPU/RAM right-sizing advice from observed usage over the last
+ * `days` days (1 to 7, default 7). Nothing changes until the figures are
+ * applied with an application update and a redeploy.
+ */
+export declare function getAppResourceRecommendation(client: TransportClient, appId: string, options?: {
+    days?: number;
+}): Promise<AppResourceRecommendationResponse>;
+/**
+ * Why the application is (not) running: conditions of the application, its
+ * releases, replica attempts and runners, the plan capacity and recent events.
+ * Read-only.
+ */
+export declare function describeApp(client: TransportClient, appId: string): Promise<AppDescribeResponse>;
+/** One replica of an application, the pod analog (docs/design/REPLICA_SELECTION.md). */
+export interface AppInstance {
+    /** `<app>-<replicaIndex>-<allocationId[0..8]>`: stable for one attempt, new for a replacement. */
+    name: string;
+    /** Null only for a legacy (pre-allocation) single container. */
+    allocationId: string | null;
+    releaseId: string;
+    production: boolean;
+    replicaIndex: number;
+    incarnation: number;
+    /** Earlier attempts of this slot in this release. */
+    restarts: number;
+    state: string;
+    /** Serving production traffic right now. */
+    ready: boolean;
+    console: 'available' | 'remote_unsupported' | 'unavailable';
+    runner: {
+        id: string;
+        provider: string;
+        region: string | null;
+    } | null;
+    createdAt: string;
+    startedAt: string | null;
+    readyAt: string | null;
+    failure: string | null;
+    usage: {
+        cpuUsedCores: number | null;
+        cpuPercent: number | null;
+        memoryWorkingSetBytes: number | null;
+        memoryPercent: number | null;
+        sampledAt: string;
+    } | null;
+    conditions: AppDescribeResponse['application']['conditions'];
+}
+export interface AppInstancesResponse {
+    applicationId: string;
+    productionReleaseId: string | null;
+    generatedAt: string;
+    instances: AppInstance[];
+}
+/** The application's replicas: name, state, runner, readiness, restarts, CPU/memory now. */
+export declare function listAppInstances(client: TransportClient, appId: string): Promise<AppInstancesResponse>;
+/**
+ * Resolve a replica selector the way the server does: exact allocation id,
+ * instance name (`...-<index>-<id8>`), bare replica index (the ready one
+ * first), or a unique allocation-id prefix of at least 8 characters.
+ */
+export declare function matchAppInstance(selector: string, instances: readonly AppInstance[]): AppInstance | null;
+/** HTTP gateway observations; private TCP traffic is not HTTP request telemetry. */
+export declare function getAppHttpMetrics(client: TransportClient, appId: string, range?: AppObservationRange): Promise<AppHttpMetricsResponse>;
+/** One descending timestamp/id page of persisted runtime logs (7-day retention). */
+export declare function getAppLogHistory(client: TransportClient, appId: string, query?: AppRuntimeLogQuery): Promise<AppLogHistoryResponse<AppRuntimeLogEntry>>;
+/** One descending timestamp/id page of HTTP access logs (30-day retention). */
+export declare function getAppHttpLogHistory(client: TransportClient, appId: string, query?: AppHttpLogQuery): Promise<AppLogHistoryResponse<AppHttpLogEntry>>;
+export declare function listAppAlertRules(client: TransportClient, appId: string): Promise<{
+    rules: AppAlertRuleDto[];
+}>;
+/** URLs are write-only secrets. Returned channels contain only id/type/configured. */
+export declare function createAppAlertRule(client: TransportClient, appId: string, input: AppAlertRuleInput): Promise<{
+    rule: AppAlertRuleDto;
+}>;
+/** Omit channels to keep configured destinations; [] removes them. */
+export declare function updateAppAlertRule(client: TransportClient, appId: string, ruleId: string, input: Partial<AppAlertRuleInput>): Promise<{
+    rule: AppAlertRuleDto;
+}>;
+/** Disables the rule and resolves its incidents; history is retained. No response body. */
+export declare function deleteAppAlertRule(client: TransportClient, appId: string, ruleId: string): Promise<void>;
+export declare function listAppAlertIncidents(client: TransportClient, appId: string, options?: {
+    limit?: number;
+}): Promise<{
+    incidents: AppAlertIncidentDto[];
+}>;
+//# sourceMappingURL=app-observability.d.ts.map

package/dist/app-observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.d.ts","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"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"}

package/dist/app-observability.js

@@ -0,0 +1,100 @@
+import { rawRequest } from './transport.js';
+export * from './app-observability.types.js';
+function appPath(id, suffix) {
+    return `/v1/apps/${encodeURIComponent(id)}/${suffix}`;
+}
+function queryString(options) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options)) {
+        // Zero is significant (notably runner epoch); unknown observations remain null in responses.
+        if (value !== undefined)
+            query.set(key, String(value));
+    }
+    return query.size ? `?${query}` : '';
+}
+/** Actual resource history, up to 30 days; CPU/RAM percentages use enforced limits. */
+export function getAppMetrics(client, appId, range = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'metrics') + queryString(range));
+}
+/**
+ * Read-only CPU/RAM right-sizing advice from observed usage over the last
+ * `days` days (1 to 7, default 7). Nothing changes until the figures are
+ * applied with an application update and a redeploy.
+ */
+export function getAppResourceRecommendation(client, appId, options = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'resources/recommendation') + queryString(options));
+}
+/**
+ * Why the application is (not) running: conditions of the application, its
+ * releases, replica attempts and runners, the plan capacity and recent events.
+ * Read-only.
+ */
+export function describeApp(client, appId) {
+    return rawRequest(client, 'GET', appPath(appId, 'describe'));
+}
+/** The application's replicas: name, state, runner, readiness, restarts, CPU/memory now. */
+export function listAppInstances(client, appId) {
+    return rawRequest(client, 'GET', appPath(appId, 'instances'));
+}
+/**
+ * Resolve a replica selector the way the server does: exact allocation id,
+ * instance name (`...-<index>-<id8>`), bare replica index (the ready one
+ * first), or a unique allocation-id prefix of at least 8 characters.
+ */
+export function matchAppInstance(selector, instances) {
+    const value = selector.trim();
+    const candidates = instances.filter((instance) => instance.allocationId !== null);
+    if (!value)
+        return null;
+    const unique = (matches) => (matches.length === 1 ? matches[0] : null);
+    const exact = candidates.filter((instance) => instance.allocationId === value || instance.name === value);
+    if (exact.length)
+        return unique(exact);
+    const named = /-(\d{1,4})-([A-Za-z0-9]{8})$/u.exec(value);
+    if (named) {
+        const matches = candidates.filter((instance) => instance.replicaIndex === Number(named[1]) &&
+            instance.allocationId.toLowerCase().startsWith(named[2].toLowerCase()));
+        if (matches.length)
+            return unique(matches);
+    }
+    if (/^\d{1,4}$/u.test(value)) {
+        const slot = candidates.filter((instance) => instance.replicaIndex === Number(value));
+        // A slot can hold a ready attempt and its replacement or a failed one: prefer the production ready one.
+        return unique(slot.filter((instance) => instance.production && instance.ready)) ?? unique(slot.filter((instance) => instance.production)) ?? unique(slot);
+    }
+    if (value.length >= 8 && /^[A-Za-z0-9-]+$/u.test(value)) {
+        return unique(candidates.filter((instance) => instance.allocationId.toLowerCase().startsWith(value.toLowerCase())));
+    }
+    return null;
+}
+/** HTTP gateway observations; private TCP traffic is not HTTP request telemetry. */
+export function getAppHttpMetrics(client, appId, range = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'http-metrics') + queryString(range));
+}
+/** One descending timestamp/id page of persisted runtime logs (7-day retention). */
+export function getAppLogHistory(client, appId, query = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'logs/runtime') + queryString(query));
+}
+/** One descending timestamp/id page of HTTP access logs (30-day retention). */
+export function getAppHttpLogHistory(client, appId, query = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'http-logs') + queryString(query));
+}
+export function listAppAlertRules(client, appId) {
+    return rawRequest(client, 'GET', appPath(appId, 'alert-rules'));
+}
+/** URLs are write-only secrets. Returned channels contain only id/type/configured. */
+export function createAppAlertRule(client, appId, input) {
+    return rawRequest(client, 'POST', appPath(appId, 'alert-rules'), input);
+}
+/** Omit channels to keep configured destinations; [] removes them. */
+export function updateAppAlertRule(client, appId, ruleId, input) {
+    return rawRequest(client, 'PATCH', appPath(appId, `alert-rules/${encodeURIComponent(ruleId)}`), input);
+}
+/** Disables the rule and resolves its incidents; history is retained. No response body. */
+export async function deleteAppAlertRule(client, appId, ruleId) {
+    await rawRequest(client, 'DELETE', appPath(appId, `alert-rules/${encodeURIComponent(ruleId)}`));
+}
+export function listAppAlertIncidents(client, appId, options = {}) {
+    return rawRequest(client, 'GET', appPath(appId, 'alert-incidents') + queryString(options));
+}
+//# sourceMappingURL=app-observability.js.map

package/dist/app-observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.js","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"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"}