@boxxy/pepys 0.0.1 → 0.1.4

package/src/boxxy-source.ts

@@ -0,0 +1,25 @@
+import { defineFactFamily, defineSource, receiveFactBatch } from '@pepys/kit';
+import { wireFactSchemas } from './wire-fact-schemas.ts';
+
+// Every boxxy fact names its item as the entity, so the family's entity kind is `boxxy:item`.
+export const workFamily = defineFactFamily({
+  stream: 'facts.boxxy.work',
+  api: 'boxxy/1',
+  entityKind: 'boxxy:item',
+  types: wireFactSchemas,
+});
+
+// The path keeps the kit's limits, 100 facts and 1 MiB a batch, which hold the outbox's own
+// batch budget.
+export const boxxySource = defineSource({
+  name: 'boxxy',
+  families: [workFamily],
+  live: receiveFactBatch({
+    route: '/boxxy/facts',
+    check: {
+      kind: 'hmac-sha256',
+      header: 'x-boxxy-signature-256',
+      secretEnv: 'PEPYS_BOXXY_SIGNING_SECRET',
+    },
+  }),
+});

package/src/boxxy-work-plugin.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@pepys/kit';
+import { boxxySource } from './boxxy-source.ts';
+import { boxxyWorkConsumer } from './work/boxxy-work-consumer.ts';
+
+// The source and the consumer without the queries, which need the GitHub and telemetry consumers.
+// `pepys build` writes the consumer's glue from this plug-in.
+export const boxxyWorkPlugin = definePlugin({
+  name: 'boxxy',
+  sources: [boxxySource],
+  consumers: [boxxyWorkConsumer],
+});

package/src/build-boxxy-plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from '@pepys/kit';
+import { boxxySource } from './boxxy-source.ts';
+import { buildCostToLandQuery } from './queries/build-cost-to-land-query.ts';
+import { buildStageTimeQuery } from './queries/build-stage-time-query.ts';
+import type { ForeignReads } from './queries/types.ts';
+import { boxxyWorkConsumer } from './work/boxxy-work-consumer.ts';
+
+// The boxxy plug-in of a pepys deployment: its source, its consumer and its two queries. The
+// deployment passes the GitHub and telemetry consumers that the queries read, and deploys their
+// plug-ins beside this one.
+export function buildBoxxyPlugin(foreign: ForeignReads) {
+  return definePlugin({
+    name: 'boxxy',
+    sources: [boxxySource],
+    consumers: [boxxyWorkConsumer],
+    queries: [buildCostToLandQuery(foreign), buildStageTimeQuery(foreign.delivery)],
+  });
+}

package/src/consumers/apply-scope.ts

@@ -0,0 +1,125 @@
+import {
+  initBoxxyWorkModel,
+  linkAttemptOf,
+  linkProduced,
+  linkRanIn,
+  parseBoxxyItemID,
+  readScopeFacts,
+  toBoxxyAttemptID,
+  toGithubPullRequestID,
+  toTelemetrySessionID,
+  updateBoxxyWorkModel,
+} from '../generated/boxxy-work-boundary.ts';
+import type {
+  BoxxyItemID,
+  BoxxyWorkMessage,
+  BoxxyWorkModel,
+  BoxxyWorkOperation,
+} from '../generated/boxxy-work-boundary.ts';
+import { foldWorkFacts } from '../work/fold-work-facts.ts';
+import type { AttemptFold, WorkFold } from '../work/types.ts';
+
+export type { BoxxyWorkMessage, BoxxyWorkModel } from '../generated/boxxy-work-boundary.ts';
+
+// scriptc takes the model and message types through a re-export, but not the two functions
+export function init(): BoxxyWorkModel {
+  return initBoxxyWorkModel();
+}
+
+export function update(model: BoxxyWorkModel, message: BoxxyWorkMessage): BoxxyWorkModel {
+  return updateBoxxyWorkModel(model, message);
+}
+
+// Every row and link of one item, from every fact of the item.
+export function applyScope(scope: string): string {
+  const item = parseBoxxyItemID(scope);
+
+  if (item === undefined) {
+    return JSON.stringify([]);
+  }
+
+  const fold = foldWorkFacts(readScopeFacts(item));
+
+  return JSON.stringify(buildItemOperations(item, fold));
+}
+
+function buildItemOperations(item: BoxxyItemID, fold: WorkFold): BoxxyWorkOperation[] {
+  const operations: BoxxyWorkOperation[] = [];
+
+  if (fold.item !== null) {
+    operations.push({ upsert: { boxxy_item: { ...fold.item, id: item } } });
+  }
+
+  for (const attempt of fold.attempts) {
+    operations.push(...buildAttemptOperations(item, attempt));
+  }
+
+  return operations;
+}
+
+function buildAttemptOperations(item: BoxxyItemID, attempt: AttemptFold): BoxxyWorkOperation[] {
+  const id = toBoxxyAttemptID(attempt.id);
+
+  const operations: BoxxyWorkOperation[] = [
+    {
+      upsert: {
+        boxxy_attempt: {
+          id,
+          item_id: item,
+          phase: attempt.phase,
+          number: attempt.number,
+          round: attempt.round,
+          mode: attempt.mode,
+          pool: attempt.pool,
+          recipe_hash: attempt.recipe_hash,
+          rules_version: attempt.rules_version,
+          atc_session: attempt.atc_session,
+          state: attempt.state,
+          outcome: attempt.outcome,
+          failure: attempt.failure,
+          claimed_at: attempt.claimed_at,
+          started_at: attempt.started_at,
+          closed_out_at: attempt.closed_out_at,
+          ended_at: attempt.ended_at,
+          sleeps: attempt.sleeps,
+          updated_at: attempt.updated_at,
+        },
+      },
+    },
+    linkAttemptOf({ from: id, to: item, confidence: 1, evidence: attempt.claimedFact }),
+  ];
+
+  for (const bound of attempt.sessions) {
+    const session = toTelemetrySessionID(bound.session);
+
+    operations.push(
+      {
+        upsert: {
+          boxxy_attempt_session: {
+            attempt_id: id,
+            session_id: session,
+            key: bound.key,
+            product: bound.product,
+            caller_issuer: bound.caller_issuer,
+            caller_subject: bound.caller_subject,
+            bound_at: bound.bound_at,
+          },
+        },
+      },
+      linkRanIn({ from: id, to: session, confidence: 1, evidence: bound.evidence }),
+    );
+  }
+
+  for (const pullRequest of attempt.pullRequests) {
+    operations.push(
+      linkProduced({
+        from: id,
+        to: toGithubPullRequestID(pullRequest.id),
+        confidence: 1,
+        evidence: pullRequest.evidence,
+      }),
+    );
+  }
+
+  return operations;
+}

package/src/create-pepys-fact-sink.ts

@@ -0,0 +1,64 @@
+import type { FactSink } from '@boxxy/model';
+import { createFactBatchSender } from '@pepys/kit/send';
+import { boxxySource } from './boxxy-source.ts';
+import { isOutgoingFact } from './sink/is-outgoing-fact.ts';
+import { pickSinkAnswer } from './sink/pick-sink-answer.ts';
+import { toWireFact } from './sink/to-wire-fact.ts';
+
+interface PepysFactSinkOptions {
+  // the URL of the source's receive route on pepys ingest
+  readonly url: string;
+
+  // the value of `PEPYS_BOXXY_SIGNING_SECRET` in the pepys deployment
+  readonly secret: string;
+  readonly timeoutMs: number;
+
+  // the global `fetch` when left out; a test passes ingest's route
+  readonly fetch?: (request: Request) => Promise<Response>;
+}
+
+// The sink holds no HTTP code: the kit's sender builds the body, signs it and posts it. The sender
+// takes no abort signal of the caller's, so the sink races it with a timer; a late answer is
+// dropped, and the rows stay unsent. The kit's sender throws on an empty secret.
+export function createPepysFactSink(options: PepysFactSinkOptions): FactSink {
+  const send = createFactBatchSender({
+    source: boxxySource,
+    url: options.url,
+    secret: options.secret,
+    fetch: options.fetch,
+  });
+
+  return {
+    send: async (facts) => {
+      const wire = facts.map((fact) => toWireFact(fact));
+      const outgoing = wire.filter((fact) => isOutgoingFact(fact));
+
+      // ingest would refuse the batch whole with 422 for the same fact
+      if (outgoing.length < wire.length) {
+        return {
+          kind: 'refused-batch',
+          status: 422,
+          reason: 'a fact does not fit its type in the boxxy fact family',
+        };
+      }
+
+      const sent = await withTimeout(send(outgoing), options.timeoutMs);
+
+      return pickSinkAnswer(sent, options.timeoutMs);
+    },
+  };
+}
+
+async function withTimeout<Value>(sending: Promise<Value>, timeoutMs: number) {
+  const timer = Promise.withResolvers<'timeout'>();
+
+  const handle = setTimeout(() => {
+    timer.resolve('timeout');
+  }, timeoutMs);
+
+  try {
+    return await Promise.race([sending, timer.promise]);
+  } finally {
+    clearTimeout(handle);
+  }
+}

package/src/create-pepys-reader.ts

@@ -0,0 +1,79 @@
+import { costToLandSchema, stageTimeSchema } from '@boxxy/model';
+import type { ItemId, PepysAnswer, PepysReader } from '@boxxy/model';
+import type { z } from 'zod';
+import type { UncheckedQueryClient } from './types.ts';
+
+interface PepysReaderOptions {
+  readonly client: UncheckedQueryClient;
+
+  // the environment whose deploy counts in the stage times, such as `production`
+  readonly environment: string;
+  readonly timeoutMs: number;
+}
+
+// The port takes boxxy's bare item ID; the queries take the item's entity ID. The reader never
+// throws and never retries: a report is a read that the owner can ask again.
+export function createPepysReader(options: PepysReaderOptions): PepysReader {
+  const ask = makeAsk(options.timeoutMs);
+
+  return {
+    readCostToLand: (item) =>
+      ask(costToLandSchema, () => options.client.boxxy_cost_to_land({ item: toItemEntity(item) })),
+    readStageTime: (item) =>
+      ask(stageTimeSchema, () =>
+        options.client.boxxy_stage_time({
+          item: toItemEntity(item),
+          environment: options.environment,
+        }),
+      ),
+  };
+}
+
+// An answer that parses is the value. An error, a timeout, no connection, or an answer that the
+// schema refuses is `unavailable` with a reason. A refused answer means that the pepys deployment
+// runs another version of this package than the boxxy server.
+function makeAsk(timeoutMs: number) {
+  return async <Value>(
+    schema: z.ZodType<Value>,
+    call: () => Promise<unknown>,
+  ): Promise<PepysAnswer<Value>> => {
+    const answer = await withTimeout(call, timeoutMs);
+
+    if (answer.kind === 'unavailable') {
+      return answer;
+    }
+
+    const parsed = schema.safeParse(answer.value);
+
+    return parsed.success
+      ? { kind: 'value', value: parsed.data }
+      : { kind: 'unavailable', reason: 'pepys answered a shape this boxxy does not know' };
+  };
+}
+
+async function withTimeout(
+  call: () => Promise<unknown>,
+  timeoutMs: number,
+): Promise<PepysAnswer<unknown>> {
+  const timer = Promise.withResolvers<PepysAnswer<unknown>>();
+
+  const handle = setTimeout(() => {
+    timer.resolve({ kind: 'unavailable', reason: `no answer in ${timeoutMs} ms` });
+  }, timeoutMs);
+
+  try {
+    return await Promise.race([
+      call().then(
+        (value): PepysAnswer<unknown> => ({ kind: 'value', value }),
+        (error: unknown): PepysAnswer<unknown> => ({ kind: 'unavailable', reason: String(error) }),
+      ),
+      timer.promise,
+    ]);
+  } finally {
+    clearTimeout(handle);
+  }
+}
+
+function toItemEntity(item: ItemId): string {
+  return `boxxy:item:${item}`;
+}