@casecore/release-agent 0.1.3 → 0.1.6

package/dist/producer-state.mjs

@@ -3,16 +3,18 @@ import { blocker, smokeScenarios, safeStatus } from './producer-support.mjs';
 import path from 'node:path';
 import { createProtectedJsonStore } from './journal.mjs';
 import { validProducerState } from './producer-journal.mjs';
-import { installOperationBarrier, markOperationStateLoaded, reserveExclusiveOperation } from './exclusive-operation.mjs';
+import {
+  installOperationBarrier,
+  markOperationStateLoaded,
+  reserveExclusiveOperation,
+} from './exclusive-operation.mjs';
 
 export class ProducerState {
-  constructor({
-    installationKey,
-    journalFile,
-    provider,
-    now = () => new Date(),
-    sourcePolicy,
-  }) {
+  #engineInstance;
+  static isEngineInstance(value) {
+    return value !== null && typeof value === 'object' && #engineInstance in value;
+  }
+  constructor({ installationKey, journalFile, provider, now = () => new Date(), sourcePolicy }) {
     assert.match(installationKey, /^[\w.-]{1,200}$/);
     assert.ok(path.isAbsolute(journalFile));
     Object.assign(this, { installationKey, journalFile, provider, now, sourcePolicy });
@@ -26,7 +28,7 @@ export class ProducerState {
         (Number.isSafeInteger(provider.snapshotTimeoutMs) &&
           provider.snapshotTimeoutMs > 0 &&
           provider.snapshotTimeoutMs <= 30000),
-      'Invalid fixed provider snapshot budget',
+      'Invalid fixed provider snapshot budget'
     );
     this.state = {
       schema: 1,
@@ -47,9 +49,7 @@ export class ProducerState {
   async initialize() {
     this.state = this.journal.read();
     // A restarted process must reconcile a previously admitted mutation first.
-    for (const run of this.state.runs.filter((r) =>
-      ['running', 'queued'].includes(r.status),
-    )) {
+    for (const run of this.state.runs.filter((r) => ['running', 'queued'].includes(r.status))) {
       if (
         run.status === 'queued' &&
         run.lane === 'scheduled' &&
@@ -62,7 +62,7 @@ export class ProducerState {
         blocker(
           'RECONCILIATION_REQUIRED',
           'Предыдущее выполнение требует проверки фактического состояния',
-          true,
+          true
         ),
       ];
     }
@@ -108,15 +108,9 @@ export class ProducerState {
       occurredAt: this.now().toISOString(),
       code,
       frames,
-      ...(smokeScenarios.has(error?.scenario)
-        ? { scenario: error.scenario }
-        : {}),
-      ...(safeStatus(error?.expectedStatus)
-        ? { expectedStatus: error.expectedStatus }
-        : {}),
-      ...(safeStatus(error?.actualStatus)
-        ? { actualStatus: error.actualStatus }
-        : {}),
+      ...(smokeScenarios.has(error?.scenario) ? { scenario: error.scenario } : {}),
+      ...(safeStatus(error?.expectedStatus) ? { expectedStatus: error.expectedStatus } : {}),
+      ...(safeStatus(error?.actualStatus) ? { actualStatus: error.actualStatus } : {}),
       ...([
         'ENOTFOUND',
         'EAI_AGAIN',
@@ -131,9 +125,7 @@ export class ProducerState {
         ? { transportCode: error.transportCode }
         : {}),
     };
-    this.state.diagnostics = [...(this.state.diagnostics ?? []), item].slice(
-      -200,
-    );
+    this.state.diagnostics = [...(this.state.diagnostics ?? []), item].slice(-200);
     return code;
   }
   async snapshot(after = '0', { deadlineAt } = {}) {
@@ -144,8 +136,8 @@ export class ProducerState {
         this.provider.snapshotTimeoutMs ?? 10000,
         deadlineAt
           ? Date.parse(deadlineAt) - this.now().getTime()
-          : (this.provider.snapshotTimeoutMs ?? 10000),
-      ),
+          : (this.provider.snapshotTimeoutMs ?? 10000)
+      )
     );
     const controller = new AbortController();
     let timer;
@@ -155,22 +147,17 @@ export class ProducerState {
         reject(
           Object.assign(Error('Producer status read timed out'), {
             code: 'PRODUCER_STATUS_TIMEOUT',
-          }),
+          })
         );
       }, limit);
     });
     let data;
     try {
-      data = await Promise.race([
-        this.provider.snapshot({ signal: controller.signal }),
-        timeout,
-      ]);
+      data = await Promise.race([this.provider.snapshot({ signal: controller.signal }), timeout]);
     } finally {
       clearTimeout(timer);
     }
-    const candidates = new Map(
-      data.candidates.map((candidate) => [candidate.id, candidate]),
-    );
+    const candidates = new Map(data.candidates.map((candidate) => [candidate.id, candidate]));
     for (const item of Object.values(this.state.commands)) {
       if (
         item.command.action !== 'publish' ||

package/dist/producer.d.ts

@@ -13,6 +13,56 @@ export * from './protocol.js';
 export interface ProviderContext {
   signal: AbortSignal;
 }
+declare const publicationTerminalBrand: unique symbol;
+export interface PublicationTerminalAuthority {
+  readonly [publicationTerminalBrand]: true;
+}
+export interface PublicationTerminalBindings {
+  action: 'publish' | 'deploy';
+  commandId: string;
+  runId: string;
+  installationKey: string;
+  repository: string;
+  ref: string;
+  provider: RunnerCommand['executionProvider'];
+  candidateId: string;
+  delivery: OriginalDelivery;
+}
+export interface PublicationTerminalProof {
+  schema: 1;
+  bindings: PublicationTerminalBindings;
+  status: 'deployed' | 'failed';
+  completedAt: string;
+  artifactIdentity: ArtifactIdentity | null;
+  readback: ProductionReadback;
+  failure: PublicationFailureFact | null;
+}
+export function readPublicationTerminalAuthority(
+  authority: PublicationTerminalAuthority,
+  bindings: PublicationTerminalBindings
+): PublicationTerminalProof;
+export interface PublicationTerminalReceipt {
+  schema: 1;
+  kind: 'publication_terminal';
+  issuedAt: string;
+  proof: PublicationTerminalProof;
+  mac: string;
+}
+export function sealPublicationTerminalReceipt(
+  authority: PublicationTerminalAuthority,
+  bindings: PublicationTerminalBindings,
+  token: string
+): Promise<PublicationTerminalReceipt>;
+/** Authenticated data, never an execution capability. */
+export function verifyPublicationTerminalReceipt(
+  receipt: PublicationTerminalReceipt,
+  token: string
+): PublicationTerminalReceipt;
+export interface TerminalVerificationContext extends ProviderContext {
+  completedAt: string;
+  status: 'deployed' | 'failed';
+  artifactIdentity?: ArtifactIdentity;
+}
 export interface ExecutionContext {
   stage<T>(
     id: StageId,
@@ -39,6 +89,13 @@ export interface ReleaseProvider {
   actions: RunnerCommand['action'][];
   snapshotTimeoutMs?: number;
   remotePublication?: boolean;
+  publicationTerminal?(
+    command: RunnerCommand,
+    context: ProviderContext & {
+      authority: PublicationTerminalAuthority;
+      bindings: PublicationTerminalBindings;
+    }
+  ): Promise<void>;
   snapshot(context: ProviderContext): Promise<{
     connection: ProducerSnapshot['connection'];
     installed?: ProductionReadback | null;
@@ -56,9 +113,21 @@ export interface ReleaseProvider {
   verifyPublicationArtifact?(
     command: RunnerCommand,
     identity: ArtifactIdentity,
-    delivery: OriginalDelivery
+    delivery: OriginalDelivery,
+    context?: TerminalVerificationContext
+  ): Promise<boolean>;
+  verifyPublicationDelivery?(
+    command: RunnerCommand,
+    delivery: OriginalDelivery,
+    context?: TerminalVerificationContext
+  ): Promise<boolean>;
+  verifyArtifactDelivery?(
+    command: RunnerCommand,
+    identity: ArtifactIdentity,
+    delivery: OriginalDelivery,
+    source: { repository: string; ref: string; sourceCommit: string },
+    context: TerminalVerificationContext
   ): Promise<boolean>;
-  verifyPublicationDelivery?(command: RunnerCommand, delivery: OriginalDelivery): Promise<boolean>;
   reconcilePublicationFailure?(
     command: RunnerCommand,
     context: ProviderContext & { delivery: OriginalDelivery | null; recoveryDeadlineAt: number }
@@ -152,6 +221,7 @@ export function producerServer(
     workflowRunHeader?: string;
     claimPublication?(commandId: string, workflowRunId: number): Promise<unknown>;
     reportPublication?(commandId: string, report: unknown): Promise<unknown>;
+    readTerminalReceipt?(commandId: string): Promise<PublicationTerminalReceipt | null | undefined>;
     configure?(request: ConfigurationRequest): Promise<ConfigurationAcknowledgement | undefined>;
     reconcileConfiguration?(
       configurationId: string

package/dist/producer.mjs

@@ -3,6 +3,12 @@ import { sameIdentity, acceptedProduction } from './protocol.mjs';
 import { blocker, failureMessage, failedProduction } from './producer-support.mjs';
 import { ProducerExecution } from './producer-execution.mjs';
 import { reconcilePublicationFailure } from './producer-publication-failure.mjs';
+import { notifyPublicationTerminal } from './publication-terminal.mjs';
+export {
+  readPublicationTerminalAuthority,
+  sealPublicationTerminalReceipt,
+  verifyPublicationTerminalReceipt,
+} from './publication-terminal.mjs';
 export { publicationFailureProofDigest } from './producer-publication-failure.mjs';
 export {
   sameIdentity,
@@ -18,6 +24,43 @@ export class ReleaseControlProducer extends ProducerExecution {
     const item = this.state.commands[commandId];
     assert.ok(item, 'Unknown command');
     const run = this.state.runs.find((r) => r.commandId === commandId);
+    if (
+      ['publish', 'deploy'].includes(item.command.action) &&
+      typeof this.provider.publicationTerminal === 'function'
+    ) {
+      if (run?.status === 'failed' && item.publicationFailureReconciliation?.state === 'settled') {
+        await reconcilePublicationFailure(this, item, run, { terminalRetry: true });
+        return this.acknowledgement(commandId);
+      }
+      if (run?.status === 'deployed') {
+        const controller = new AbortController();
+        let timer;
+        try {
+          const fact = await Promise.race([
+            this.provider.readProduction(this.resolvedCommand(item.command), {
+              signal: controller.signal,
+            }),
+            new Promise((_, reject) => {
+              timer = setTimeout(() => {
+                controller.abort();
+                reject(Error('PUBLICATION_TERMINAL_READBACK_TIMEOUT'));
+              }, 30000);
+            }),
+          ]);
+          assert.ok(
+            acceptedProduction(fact, this.resolvedCommand(item.command), this.now()),
+            'PUBLICATION_TERMINAL_READBACK_REQUIRED'
+          );
+          run.readback = structuredClone(fact);
+          await this.save();
+          await notifyPublicationTerminal(this, item, run);
+        } finally {
+          controller.abort();
+          clearTimeout(timer);
+        }
+        return this.acknowledgement(commandId);
+      }
+    }
     if (
       item.command.action === 'publish' &&
       run?.status === 'blocked' &&
@@ -140,6 +183,7 @@ export class ReleaseControlProducer extends ProducerExecution {
         await this.save();
       }
     }
+    await notifyPublicationTerminal(this, item, run);
     return this.acknowledgement(commandId);
   }
 }

package/dist/provenance.json

@@ -1,40 +1,42 @@
 {
   "schema": 1,
   "package": "@casecore/release-agent",
-  "version": "0.1.3",
-  "sourceCommit": "a9736762537078698065c74bbb0febb675b980c7",
+  "version": "0.1.6",
+  "sourceCommit": "70442860e0f89db88c78142c6f6a7e8073414af5",
   "sourceVerified": true,
   "sourceDirty": false,
   "buildKind": "release",
-  "contentDigest": "sha256:21d9013bdd65fefe213eee463eaa9dc13bb2ee1647f392e2c6c90ca5953d2886",
+  "contentDigest": "sha256:a41148b8adf594a5da507b1f8495b5b8c63e32b514d815c7bbce2634b0e6fb89",
   "files": {
     "src/configuration-hook.mjs": "sha256:1171bf982cbf7cb0092f63b633ef0b0a0947d8ed1106f88c9175c8add33d81b1",
-    "src/exclusive-operation.mjs": "sha256:5a1d0b7d3aa41b901132e239586d66d6c7aa2c16682a7db033a7aab91b1d781a",
+    "src/exclusive-operation.mjs": "sha256:d5c2718a2a4228d09559e914360329383ae276f034bb468c52642a4bd6aa0d99",
     "src/identity.mjs": "sha256:253021058fc79232d83f3ecba6f1023fd046f27aabdf9c129a103d3c9ccb07f5",
     "src/index.mjs": "sha256:76bda5e1dc376bb7033d8fdbddb0afa85c7c68bbe028aea078ffceaaa35ec75e",
     "src/journal.mjs": "sha256:35a2620d56084ec1aa164e09d77b8e77096413d9572f7b601da8ef7149b996bd",
     "src/pipeline.mjs": "sha256:7a2d39d235ce7160441d177200389c5f3eae1cc494ec36082a23e8d64a0abe3f",
-    "src/producer-admission.mjs": "sha256:975c7dac25d4c8f94423e5a4db2bd99c556afd6492b26fbda58e841f1df8fc3c",
-    "src/producer-delivery.mjs": "sha256:b20d9ae20dee90bbbe739245a84c9f4b91b1ab958b5e2995ff8705da24ba3988",
-    "src/producer-execution.mjs": "sha256:6d9fbca493e4386c92c4d853a66ece3677ec7ab644d6da15b68dd744f30186ef",
-    "src/producer-journal.mjs": "sha256:0934057702fb611b9a8d9dde58cb2c2024f436a49a4e5f6ab02f8884a320cea7",
-    "src/producer-publication-failure.mjs": "sha256:726b2b85880143b70219473896b894f64b25b1c495f77488f1e73ce950b839f6",
+    "src/producer-admission.mjs": "sha256:03d868141daf92351b3e1a4e70997c87fc39044624644536a374aa86d108d12d",
+    "src/producer-delivery.mjs": "sha256:04439a95afcb52d879cc83b99fa1d7716f4dff84bb7c07f88d31f534799e76a8",
+    "src/producer-execution.mjs": "sha256:e78724fa2f2fd4946ae8103bb5165b363eb968fab42add4fed572155f51871d9",
+    "src/producer-journal.mjs": "sha256:9ec7c5e4ae6add8c0b64644673c3243946175fb5cc2dafcd5f1fdee2c6485ffd",
+    "src/producer-publication-failure.mjs": "sha256:9db4effbeae8287070e3c27133abecf2bf435a8c6917c3162f0efd3189ea9445",
     "src/producer-publication.mjs": "sha256:c09fa07b37507093b71bbaff3af9df8ec2331c0cba24a4b936d247e9b35257f7",
-    "src/producer-server.mjs": "sha256:def28e10a17eb80fb04ba69b09050731bb005949f949a7f1fb46dae267323434",
-    "src/producer-state.mjs": "sha256:c3fcdace4c6579be092d39803cfb308e4bf88060b3f75bb7fc8b91284609b4ce",
+    "src/producer-server.mjs": "sha256:fc67ceced78239a1d159ff1af82b0061a407891523ad2a1a9139a3d4d158619c",
+    "src/producer-state.mjs": "sha256:61d6a914c268f94790c459562436bfe95efd07865ca1052b0b58760d9087d535",
     "src/producer-support.mjs": "sha256:0a10f6fa50cd8e729ba432640d0845004488ead2bcc1c9383f02548037f83d66",
-    "src/producer.mjs": "sha256:6d0b875a9901a14edf5b93c771356f5352e924ff7977c13b027343c9bdca42f4",
+    "src/producer.mjs": "sha256:d5a9fca0bcb14f8c757d7219fcb8f2d39a2bf7af05c9cce3b8f654fa3060552c",
     "src/protocol-internals.mjs": "sha256:d08a0c72079d091792c5327adafac5ffc38ea20138a6c44b88879e7157a890b3",
     "src/protocol.mjs": "sha256:1fe135a2e60922b517886a392c2b0c2250b773abda8b1a1fcd9af86df2be6dae",
+    "src/publication-terminal-receipt.mjs": "sha256:b4ecc620f7e4325ec9d42652b8f1620f609fad65b1400cd2810a0a2f7e7b6794",
+    "src/publication-terminal.mjs": "sha256:643663218b31526a47c88f6ea2475428d94e2450b49225c253f39d54de30fed2",
     "src/snapshot-validator.mjs": "sha256:1279aa19e0932776bc1998935f70ca6fae65391f96b60e2d65bcab3b2cb46036",
     "src/source-admission.mjs": "sha256:25e0e3cc163895c3f6b5057162538c4c313bd37e67956c63b2624df52517b437",
-    "src/source-non-admission.mjs": "sha256:a2308518c8337b662946c5778fe30a5a35a6e7f0b8ed6130eeca93d8ea959ded",
+    "src/source-non-admission.mjs": "sha256:fd513148f9cd8beb1faddf9ad30189913d387a3cd6bc67f3308e7b0cbee46396",
     "src/source-store.mjs": "sha256:b58a833518086a3d64fe163c323c90b6d6f4cd0793982891146c0a5f9d7241b9",
     "src/stage-journal.mjs": "sha256:96321418e4f8b48aba3dd0a4269a8f345d6763acb81f3b1e330ba3baf06a213e",
     "types/index.d.ts": "sha256:92ef7b5600f05d52dcb646fc3e4d2b4944ead52ff1c9ee23bb9f4659bebf05a6",
     "types/journal.d.ts": "sha256:79beb61af50b00400588a87426a7f5b38bf38d4b8224284dc6e0631378aa244e",
     "types/pipeline.d.ts": "sha256:c9135e25fb852377c32a16ce781405393c5857886e3f77754b715747202c70a9",
-    "types/producer.d.ts": "sha256:980aad137365f6c131b6bfabfab411a73c4a2b2fb35a167152ef8ed446ec1ade",
+    "types/producer.d.ts": "sha256:f64ae58d8e5984caea148a97e2cdf7d52a77bc472fb17ec75b5af1350f763fcc",
     "types/protocol.d.ts": "sha256:02c06986c81bfc4214169f62da8e0566704b71a5add58434dfca92c673fad4ce",
     "types/source-store.d.ts": "sha256:ce2086dd682e8f57bc5e1581b411ec9fe1cf1cfba8dccafe38c22d102c2b9904",
     "types/types.d.ts": "sha256:cdc6664854bffc371a3da45f29bf1b31f14fd61b66e8f8bae8309dd836f6de6e"

package/dist/publication-terminal-receipt.mjs

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { completeIdentity, keys, timestamp, uuid } from './protocol-internals.mjs';
+import { validateOriginalDelivery } from './producer-support.mjs';
+
+const domain = 'casecore.release-agent/publication-terminal/v1\0';
+const sorted = (value) => {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value && typeof value === 'object')
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, sorted(value[key])])
+    );
+  assert.ok(value === null || ['string', 'boolean', 'number'].includes(typeof value));
+  assert.ok(typeof value !== 'number' || Number.isFinite(value));
+  return value;
+};
+const body = (receipt) =>
+  JSON.stringify(
+    sorted({
+      schema: receipt.schema,
+      kind: receipt.kind,
+      issuedAt: receipt.issuedAt,
+      proof: receipt.proof,
+    })
+  );
+function secret(token) {
+  assert.ok(
+    typeof token === 'string' && token.length >= 43 && token.length <= 4096 && !/\s/.test(token),
+    'PUBLICATION_TERMINAL_TOKEN_REQUIRED'
+  );
+  return token;
+}
+export function validatePublicationTerminalReceipt(receipt) {
+  keys(receipt, ['schema', 'kind', 'issuedAt', 'proof', 'mac']);
+  assert.equal(receipt.schema, 1);
+  assert.equal(receipt.kind, 'publication_terminal');
+  timestamp(receipt.issuedAt);
+  assert.match(receipt.mac, /^[a-f0-9]{64}$/);
+  const proof = receipt.proof;
+  keys(proof, [
+    'schema',
+    'bindings',
+    'status',
+    'completedAt',
+    'artifactIdentity',
+    'readback',
+    'failure',
+  ]);
+  assert.equal(proof.schema, 1);
+  assert.ok(['deployed', 'failed'].includes(proof.status));
+  timestamp(proof.completedAt);
+  const bindings = proof.bindings;
+  keys(bindings, [
+    'action',
+    'commandId',
+    'runId',
+    'installationKey',
+    'repository',
+    'ref',
+    'provider',
+    'candidateId',
+    'delivery',
+  ]);
+  assert.ok(['publish', 'deploy'].includes(bindings.action));
+  assert.match(bindings.commandId, uuid);
+  assert.match(bindings.runId, uuid);
+  assert.match(bindings.installationKey, /^[\w.-]{1,200}$/);
+  assert.match(bindings.repository, /^[\w.-]+\/[\w.-]+$/);
+  assert.ok(
+    typeof bindings.ref === 'string' && bindings.ref.length > 0 && bindings.ref.length <= 200
+  );
+  assert.ok(['github', 'local'].includes(bindings.provider));
+  assert.ok(
+    typeof bindings.candidateId === 'string' &&
+      bindings.candidateId.length > 0 &&
+      bindings.candidateId.length <= 200
+  );
+  validateOriginalDelivery(bindings.delivery);
+  assert.ok(Date.parse(proof.completedAt) >= Date.parse(bindings.delivery.requestedAt));
+  if (proof.status === 'deployed') {
+    assert.ok(Date.parse(proof.completedAt) <= Date.parse(bindings.delivery.deadlineAt));
+    assert.ok(completeIdentity(proof.artifactIdentity));
+  } else assert.ok(proof.artifactIdentity === null || completeIdentity(proof.artifactIdentity));
+  assert.ok(proof.readback && typeof proof.readback === 'object');
+  assert.ok(proof.failure === null || (proof.failure && typeof proof.failure === 'object'));
+  assert.ok(Buffer.byteLength(body(receipt)) <= 262144, 'PUBLICATION_TERMINAL_RECEIPT_TOO_LARGE');
+  return receipt;
+}
+// Internal data constructor. Public sealing additionally requires the genuine
+// active engine capability and durably writes the existing command journal.
+export function createPublicationTerminalReceipt(proof, token) {
+  const receipt = {
+    schema: 1,
+    kind: 'publication_terminal',
+    issuedAt: new Date().toISOString(),
+    proof: structuredClone(proof),
+    mac: '',
+  };
+  receipt.mac = createHmac('sha256', secret(token))
+    .update(domain)
+    .update(body(receipt))
+    .digest('hex');
+  return validatePublicationTerminalReceipt(receipt);
+}
+/** Authenticated data only: this never creates or revives a WeakMap capability. */
+export function verifyPublicationTerminalReceipt(receipt, token) {
+  validatePublicationTerminalReceipt(receipt);
+  const expected = createHmac('sha256', secret(token))
+    .update(domain)
+    .update(body(receipt))
+    .digest();
+  assert.ok(
+    timingSafeEqual(expected, Buffer.from(receipt.mac, 'hex')),
+    'PUBLICATION_TERMINAL_RECEIPT_AUTHENTICATION_REQUIRED'
+  );
+  return structuredClone(receipt);
+}