@olivervea/pipelines 2.0.0-beta.26 → 2.0.0-beta.28

package/src/describe/triggers.ts

@@ -0,0 +1,72 @@
+import { STEP_NAME } from '../core/steps.ts';
+import type { TriggerNode } from '../builder/pipeline.ts';
+import type { TriggerT } from './manifest-schema.ts';
+import type { DescribeContext } from './context.ts';
+
+export function describeTriggers(
+  ctx: DescribeContext,
+  triggers: readonly TriggerNode[],
+): TriggerT[] {
+  const names = new Set<string>();
+  return triggers.map((t) => {
+    if (names.has(t.name))
+      ctx.problems.push(
+        `duplicate trigger '${t.name}'${t.kind === 'push' ? ' (onPush may be used once)' : ' (give each onPoll and onWebhook a distinct name)'}`,
+      );
+    names.add(t.name);
+    if (t.kind === 'push') return { kind: 'push', name: 'push' };
+    if (t.kind === 'webhook') return describeWebhook(ctx, t);
+    return describePoll(ctx, t);
+  });
+}
+
+function describeWebhook(
+  ctx: DescribeContext,
+  t: Extract<TriggerNode, { kind: 'webhook' }>,
+): TriggerT {
+  if (!STEP_NAME.test(t.name))
+    ctx.problems.push(`webhook trigger name '${t.name}' must be lower-case kebab`);
+  const secret = ctx.useSecret(t.verify.secret, `webhook '${t.name}'`);
+  if (t.verify.scheme === 'bearer')
+    return { kind: 'webhook', name: t.name, verify: { scheme: 'bearer', secret } };
+  if (!t.verify.header)
+    ctx.problems.push(`webhook '${t.name}': the signature header must not be empty`);
+  return {
+    kind: 'webhook',
+    name: t.name,
+    verify: {
+      scheme: 'hmac-sha256',
+      secret,
+      header: t.verify.header,
+      prefix: t.verify.prefix,
+    },
+  };
+}
+
+function describePoll(
+  ctx: DescribeContext,
+  t: Extract<TriggerNode, { kind: 'poll' }>,
+): TriggerT {
+  const problems = ctx.problems;
+  if (!STEP_NAME.test(t.name))
+    problems.push(`poll trigger name '${t.name}' must be lower-case kebab`);
+  if (!(Number.isInteger(t.intervalSeconds) && t.intervalSeconds > 0))
+    problems.push(`poll '${t.name}': intervalSeconds must be a positive integer`);
+  const declared = new Set(t.secrets.map((s) => ctx.useSecret(s, `poll '${t.name}'`)));
+  for (const [h, v] of Object.entries(t.headers)) {
+    for (const m of v.matchAll(/\$SECRET:([A-Za-z0-9_]+)/g))
+      if (!declared.has(m[1]!))
+        problems.push(
+          `poll '${t.name}': header '${h}' references secret '${m[1]}', which is not in the poll's secrets`,
+        );
+  }
+  return {
+    kind: 'poll',
+    name: t.name,
+    url: t.url,
+    headers: { ...t.headers },
+    secrets: [...declared].sort(),
+    valuePath: t.valuePath,
+    intervalSeconds: t.intervalSeconds,
+  };
+}

package/src/harness/execute.ts

@@ -6,15 +6,17 @@ import { isSkipped } from '../core/handlers.ts';
 import type { AnyStep } from '../core/steps.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
 import { objectPath } from '../ctx/files.ts';
+import { createLinks, type StepLink } from '../ctx/links.ts';
 import { sha256File } from '../util/hash.ts';
 import { EXIT } from './exit.ts';
 import { validateConfig, validateInput, validateOutput } from './validate.ts';
 
 export type FailureKind = 'handler' | 'input' | 'output';
-export type Envelope =
+export type Envelope = (
   | { status: 'succeeded'; output: unknown }
   | { status: 'skipped'; reason: string }
-  | { status: 'failed'; error: { kind: FailureKind; message: string } };
+  | { status: 'failed'; error: { kind: FailureKind; message: string } }
+) & { links?: StepLink[] };
 
 export interface Execution {
   envelope: Envelope;
@@ -85,7 +87,14 @@ export async function executeStep(args: {
       exitCode: EXIT.inputInvalid,
     };
   }
-  const ctx: Ctx = { ...args.ctx, config: Object.freeze(config.value) as Ctx['config'] };
+  const collected = createLinks();
+  const ctx: Ctx = {
+    ...args.ctx,
+    config: Object.freeze(config.value) as Ctx['config'],
+    link: collected.link,
+  };
+  const withLinks = (e: Envelope): Envelope =>
+    collected.links.length ? { ...e, links: [...collected.links] } : e;
 
   let value: unknown;
   try {
@@ -98,14 +107,17 @@ export async function executeStep(args: {
     log(message);
     if (e instanceof Error && e.stack && !cancelled) log(e.stack);
     return {
-      envelope: { status: 'failed', error: { kind: 'handler', message } },
+      envelope: withLinks({ status: 'failed', error: { kind: 'handler', message } }),
       exitCode: cancelled ?? EXIT.handlerFailed,
     };
   }
 
   if (isSkipped(value)) {
     log(`step '${step.name}' skipped: ${value.reason}`);
-    return { envelope: { status: 'skipped', reason: value.reason }, exitCode: EXIT.ok };
+    return {
+      envelope: withLinks({ status: 'skipped', reason: value.reason }),
+      exitCode: EXIT.ok,
+    };
   }
   const out = validateOutput(step, value);
   const problems = out.ok
@@ -115,9 +127,12 @@ export async function executeStep(args: {
     const message = `step '${step.name}': returned value does not match ${step.output?.name ?? 'its (absent) output model'}:\n  ${problems.join('\n  ')}`;
     log(message);
     return {
-      envelope: { status: 'failed', error: { kind: 'output', message } },
+      envelope: withLinks({ status: 'failed', error: { kind: 'output', message } }),
       exitCode: EXIT.outputInvalid,
     };
   }
-  return { envelope: { status: 'succeeded', output: out.value }, exitCode: EXIT.ok };
+  return {
+    envelope: withLinks({ status: 'succeeded', output: out.value }),
+    exitCode: EXIT.ok,
+  };
 }

package/src/index.ts

@@ -77,6 +77,7 @@ export type {
   RetryOptions,
   OutputFileOptions,
 } from './ctx/types.ts';
+export type { StepLink } from './ctx/links.ts';
 export type { Ref, Mappable, MapperResult } from './builder/refs.ts';
 export {
   pipeline,

package/src/library/compose-deploy.ts

@@ -20,6 +20,7 @@ export interface ComposeTargetValue {
   service: string;
   token: { secret: string };
   healthUrl?: string | undefined;
+  link?: string | undefined;
 }
 
 /** What the deployer answers to `POST /v1/deploy`. */
@@ -103,6 +104,7 @@ export function composeDeploy<const N extends string, const K extends string>(
       );
     if (target.healthUrl)
       await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+    if (target.link) ctx.link(target.link);
     ctx.log('deployed', {
       service: target.service,
       image: ref,

package/src/library/helm-deploy-ssh.ts

@@ -113,6 +113,8 @@ export interface HelmDeployOverSshDef<
   helmWait?: boolean;
   /** `helm upgrade --atomic`: wait like `helmWait`, and roll back when the upgrade fails. Default false. */
   atomic?: boolean;
+  /** Public URL of what the release serves; the step links to it after a successful deploy. */
+  link?: Configurable<string>;
   /** After the rollouts, GET this URL until it returns 2xx (`httpHealthCheck`: 5 × 5 s unless given), or fail the step. */
   healthUrl?:
     | Configurable<string>
@@ -407,6 +409,7 @@ function helmDeployOverSshLiteral(
     values: def.values ?? [],
     set: def.set ?? {},
     healthUrl: def.healthUrl,
+    link: def.link,
   };
 
   const contract = step({
@@ -436,6 +439,7 @@ function helmDeployOverSshLiteral(
       ...(def.dependencies ? { dependencies: true } : {}),
       ...(def.atomic ? { atomic: true } : def.helmWait ? { helmWait: true } : {}),
       ...(def.healthUrl !== undefined ? { healthUrl: def.healthUrl } : {}),
+      ...(def.link !== undefined ? { link: def.link } : {}),
     },
   });
   return implement(contract, async (stepInput, ctx: Ctx) => {
@@ -449,6 +453,7 @@ function helmDeployOverSshLiteral(
       namespace: string;
       values: string[];
       set: Record<string, string>;
+      link?: string;
       healthUrl?:
         | string
         | ({ url: string } & Pick<HttpHealthCheckOptions, 'attempts' | 'delaySeconds'>);
@@ -495,6 +500,7 @@ function helmDeployOverSshLiteral(
         attempts: health.attempts,
         delaySeconds: health.delaySeconds,
       });
+    if (d.link) ctx.link(d.link);
     return {
       release: d.release,
       namespace: d.namespace,

package/src/library/helm-deploy.ts

@@ -53,6 +53,12 @@ function targetVariants<const E extends z.ZodRawShape, const K extends string>(
       .describe(
         'Base URL step pods reach the release at (health checks, smoke tests); default http://<release>.<namespace>.svc.cluster.local.',
       ),
+    link: z
+      .string()
+      .optional()
+      .describe(
+        'Public URL of what the target serves (a site, an API); the deploy step links to it.',
+      ),
     ...(o.extend ?? ({} as E)),
   };
   const inCluster = z.object({
@@ -86,6 +92,12 @@ function targetVariants<const E extends z.ZodRawShape, const K extends string>(
       .describe(
         "Checked by the step after the deployer's own health check, when the step can reach it.",
       ),
+    link: z
+      .string()
+      .optional()
+      .describe(
+        'Public URL of what the target serves (a site, an API); the deploy step links to it.',
+      ),
     ...(o.extend ?? ({} as E)),
   });
   const none = z.object({
@@ -156,6 +168,7 @@ interface TargetCommon {
   values: readonly string[];
   set: Readonly<Record<string, string>>;
   url?: string | undefined;
+  link?: string | undefined;
 }
 /** A resolved `kind: inCluster` target. */
 export type InClusterTargetValue = TargetCommon & { kind: 'inCluster' };
@@ -472,6 +485,7 @@ function targetDeploy(
         attempts: 12,
         delaySeconds: 5,
       });
+    if (target.link) ctx.link(target.link);
     const main = flags[0];
     return {
       release,

package/src/library/models.ts

@@ -54,7 +54,7 @@ export const HelmRelease = model(
 export const FailedStep = z.object({
   step: z.string(),
   attempt: z.number().int(),
-  /** `<pipeline id>#<run>/<step>@<attempt>` (spec §5.5). */
+  /** `<pipeline id>#<run>/<step>@<attempt>`. */
   address: z.string(),
   /** The attempt's failure reason (handler error, exit code, timeout, …). */
   reason: z.string(),
@@ -74,7 +74,7 @@ export const FailureContext = model(
     run: z.object({
       id: z.string(),
       number: z.number().int(),
-      /** `<pipeline id>#<run>` (spec §5.5). */
+      /** `<pipeline id>#<run>`. */
       address: z.string(),
       /** The run's derived version, `yyyy.MM.dd.<run>`. */
       versionStamp: z.string(),

package/src/testing/index.ts

@@ -14,6 +14,7 @@ import type {
 } from '../core/steps.ts';
 import { createCtx } from '../ctx/index.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
+import type { StepLink } from '../ctx/links.ts';
 import { executeStep, type FailureKind, type StepFunction } from '../harness/execute.ts';
 import { sha256Hex } from '../util/hash.ts';
 
@@ -39,6 +40,8 @@ export type TestResult<S extends AnyStep> = {
   filesDir: string;
   logs: string[];
   exitCode: number;
+  /** What the handler passed to `ctx.link`; absent when nothing. */
+  links?: StepLink[];
 } & (
   | { status: 'succeeded'; output: OutputValue<S> }
   | { status: 'skipped'; reason: string }