@boxxy/dispatch 0.1.0 → 0.1.3

package/src/closeouts/settle-attempt.ts

@@ -0,0 +1,161 @@
+import type {
+  AttemptRow,
+  EngineOutcome,
+  Instant,
+  ItemView,
+  LoadedRules,
+  OutcomeName,
+  StoreChange,
+  StoreTx,
+} from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { buildAttemptChange } from '../attempts/build-attempt-change.ts';
+import { isSameGuard } from '../attempts/is-same-guard.ts';
+import type { MoveResult } from '../attempts/types.ts';
+import { buildKeepWrites } from '../sessions/build-keep-writes.ts';
+import { buildSettlePlans } from './build-settle-plans.ts';
+import { pickSettlement } from './pick-settlement.ts';
+import type { SettleAttemptInput } from './types.ts';
+
+// Settles one attempt, with the writes of its effects, in one change and one lock. No step
+// throws on stored data, so only a store error leaves it. When the item holds after the settle,
+// the same lock writes the notice row. A settle decided on an older row refuses, with no write.
+export function settleAttempt(input: SettleAttemptInput): Promise<MoveResult> {
+  return input.store.exclusive(async (tx) => {
+    const attempt = await tx.readAttempt(input.attempt);
+
+    invariant(attempt !== null, `the settle names a stored attempt: ${input.attempt}`);
+
+    if (input.seen !== undefined && !isSameGuard(input.seen, attempt)) {
+      return { kind: 'refused', reason: 'guard-mismatch' };
+    }
+
+    const detail = await tx.readItemDetail(attempt.item, input.now, input.rules);
+
+    invariant(detail !== null, `an attempt's item is stored: ${attempt.item}`);
+
+    const item = detail.item;
+
+    const settlement = pickSettlement({
+      attempt,
+      item,
+      rules: input.rules,
+      forced: input.forced,
+      now: input.now,
+    });
+
+    const hasFileItem = settlement.effects.some((effect) => effect.kind === 'file-item');
+
+    const settled = buildSettlePlans({
+      effects: settlement.effects,
+      ctx: {
+        attempt,
+        item,
+        rules: input.rules,
+        relations: detail.relations.filter((relation) => relation.source === item.id),
+        actor: input.actor,
+        now: input.now,
+        newId: input.newId,
+      },
+      openIssues: hasFileItem ? await tx.listOpenIssues(item.repo, input.now, input.rules) : [],
+      held: isHoldEdge(input.rules, item, attempt, settlement.outcome),
+    });
+
+    const built = buildAttemptChange({
+      attempt,
+      event: {
+        kind: 'settled',
+        state: settlement.state,
+        failure: settlement.failure,
+        outcome: settlement.outcome,
+        returnedOutcome: settlement.returnedOutcome,
+        sessionStopped: input.sessionStopped,
+        frictionDropped: settlement.frictionDropped,
+        criteria: settled.criteria,
+        matched: settled.matched,
+        skippedEffects: settled.skippedEffects,
+      },
+      actor: input.actor,
+      now: input.now,
+      newId: input.newId,
+    });
+
+    if (built.kind === 'not-allowed') {
+      return { kind: 'not-allowed' };
+    }
+
+    const change: StoreChange = {
+      ...built.change,
+      writes: [
+        ...built.change.writes,
+        ...(settlement.state === 'succeeded' && input.sessionStopped
+          ? buildKeepWrites({ attempt, item, rules: input.rules, now: input.now })
+          : []),
+        ...settled.plans.flatMap((plan) => (plan.kind === 'apply' ? plan.writes : [])),
+      ],
+      facts: [
+        ...built.change.facts,
+        ...settled.plans.flatMap((plan) => (plan.kind === 'apply' ? plan.facts : [])),
+      ],
+    };
+
+    const result = await tx.applyChange(change);
+
+    if (result.kind !== 'applied') {
+      return { kind: 'refused', reason: result.kind };
+    }
+
+    await writeHoldNotice(tx, attempt, input.rules, input.now);
+
+    return result;
+  });
+}
+
+// The one place where settle reads an edge; it stores no position.
+function isHoldEdge(
+  rules: LoadedRules,
+  item: ItemView,
+  attempt: AttemptRow,
+  outcome: OutcomeName | EngineOutcome,
+): boolean {
+  const step = rules.kinds
+    .get(item.kind)
+    ?.pipeline.steps.find((candidate) => candidate.phase === attempt.phase);
+
+  const edge = step?.on[outcome];
+
+  return typeof edge === 'object' && 'hold' in edge;
+}
+
+async function writeHoldNotice(
+  tx: StoreTx,
+  attempt: AttemptRow,
+  rules: LoadedRules,
+  now: Instant,
+): Promise<void> {
+  const after = await tx.readItem(attempt.item, now, rules);
+
+  if (after?.position.kind !== 'hold') {
+    return;
+  }
+
+  // the store numbers each notice, so the ID here is replaced
+  await tx.applyChange({
+    at: now,
+    writes: [
+      {
+        op: 'insert',
+        table: 'notices',
+        row: {
+          id: 1,
+          item: attempt.item,
+          reason: after.position.reason,
+          at: now,
+          tries: 0,
+          sentAt: null,
+        },
+      },
+    ],
+    facts: [],
+  });
+}

package/src/closeouts/types.ts

@@ -0,0 +1,87 @@
+import type {
+  ActorRef,
+  AnyNewFact,
+  AtcSessionId,
+  AttemptId,
+  AttemptRow,
+  CallerIdentity,
+  ClaimStore,
+  Effect,
+  ForcedFailure,
+  Instant,
+  ItemView,
+  LoadedRules,
+  NewId,
+  RelationRow,
+  RowWrite,
+} from '@boxxy/model';
+import type { AttemptGuard } from '../attempts/is-same-guard.ts';
+
+// What one effect of a settle writes, or why it writes nothing.
+export type EffectPlan =
+  | {
+      readonly kind: 'apply';
+      readonly effect: Effect;
+      readonly writes: readonly RowWrite[];
+      readonly facts: readonly AnyNewFact[];
+    }
+  | { readonly kind: 'skip'; readonly effect: Effect; readonly reason: string };
+
+// What an effect handler reads. A handler does no I/O: settle reads these first.
+export interface EffectContext {
+  readonly attempt: AttemptRow;
+
+  // the attempt's item, open or closed
+  readonly item: ItemView;
+  readonly rules: LoadedRules;
+
+  // the live relations of the attempt's item
+  readonly relations: readonly RelationRow[];
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+// One handler for each kind of effect.
+export type EffectHandlers = {
+  readonly [Kind in Effect['kind']]: (
+    effect: Extract<Effect, { kind: Kind }>,
+    ctx: EffectContext,
+  ) => EffectPlan;
+};
+
+export interface SettleAttemptInput {
+  readonly store: ClaimStore;
+  readonly attempt: AttemptId;
+
+  // the cause that ends the attempt with the outcome `lost`; null settles by the close-out
+  readonly forced: ForcedFailure | null;
+
+  // false: settled by the give-up rule while the session still ran
+  readonly sessionStopped: boolean;
+
+  // the guard columns of the row the caller decided on, when it read the row before the lock
+  readonly seen?: Partial<AttemptGuard>;
+  readonly rules: LoadedRules;
+  readonly actor: ActorRef;
+  readonly now: Instant;
+  readonly newId: NewId;
+}
+
+// What every call from inside a session gives the core. `attempt` comes from the request: the ID
+// the session read with `attempt.current`. `session` and `caller` come from the edge, which
+// proved the caller and found its session.
+export interface CallRef {
+  readonly attempt: AttemptId;
+  readonly session: AtcSessionId;
+  readonly caller: CallerIdentity;
+}
+
+export interface CloseOutInput {
+  readonly store: ClaimStore;
+  readonly call: CallRef;
+  readonly body: unknown;
+  readonly rules: LoadedRules;
+  readonly now: Instant;
+  readonly newId: NewId;
+}

package/src/index.ts

@@ -1 +1,62 @@
+export { bindAttemptSession } from './attempts/bind-attempt-session.ts';
+export type { BindAnswer, BindAttemptSessionInput } from './attempts/bind-attempt-session.ts';
+export { endItemAttempts } from './attempts/end-item-attempts.ts';
+export type { EndedAttempts } from './attempts/end-item-attempts.ts';
+export { pickCallAttempt } from './attempts/pick-call-attempt.ts';
+export type { CallAttempt } from './attempts/pick-call-attempt.ts';
+export { stopStraySession } from './attempts/stop-stray-session.ts';
+export type { StopStraySessionInput } from './attempts/stop-stray-session.ts';
+export type { MoveResult } from './attempts/types.ts';
+export { ClaimRaceError, claimNext } from './claims/claim-next.ts';
+export { requestWake } from './claims/request-wake.ts';
+export { resumeClaim } from './claims/resume-claim.ts';
+export { startClaim } from './claims/start-claim.ts';
+
+export type {
+  ClaimInput,
+  RequestWakeInput,
+  ResumeClaimInput,
+  SpawnSettings,
+  StartClaimInput,
+} from './claims/types.ts';
+
+export { closeOutAttempt } from './closeouts/close-out-attempt.ts';
+export { settleAttempt } from './closeouts/settle-attempt.ts';
+export type { CallRef, CloseOutInput, EffectPlan, SettleAttemptInput } from './closeouts/types.ts';
+export { noticeLimits } from './notices/constants.ts';
+export { createNullNotifier } from './notices/create-null-notifier.ts';
+export { sendNotices } from './notices/send-notices.ts';
+export type { NoticeReport, SendNoticesInput } from './notices/types.ts';
 export { packageName } from './package-name.ts';
+export { buildInitialSenderState } from './outbox/build-initial-sender-state.ts';
+export { buildOutboxStatus } from './outbox/build-outbox-status.ts';
+export { outboxLimits } from './outbox/constants.ts';
+export { runSenderOnce } from './outbox/run-sender-once.ts';
+
+export type {
+  OutboxLimits,
+  SenderDeps,
+  SenderState,
+  SenderStep,
+  SenderTurn,
+} from './outbox/types.ts';
+
+export { actOnReading } from './readings/act-on-reading.ts';
+export { findWaitingSince } from './readings/find-waiting-since.ts';
+export { pickReadingAction } from './readings/pick-reading-action.ts';
+export type { ActOnReadingInput, ReadingAction, ReadingInput } from './readings/types.ts';
+export { forgetSessions } from './sessions/forget-sessions.ts';
+export type { ForgetReport, ForgetSessionsInput } from './sessions/types.ts';
+export { timeouts } from './timeouts.ts';
+export type { DispatchTimeouts } from './types.ts';
+export { linkPullRequest } from './pull-requests/link-pull-request.ts';
+export { parsePullRequestUrl } from './pull-requests/parse-pull-request-url.ts';
+
+export type {
+  LinkPullRequestInput,
+  LinkPullRequestResult,
+  WatchPullRequestsInput,
+  WatchReport,
+} from './pull-requests/types.ts';
+
+export { watchPullRequests } from './pull-requests/watch-pull-requests.ts';

package/src/notices/constants.ts

@@ -0,0 +1,7 @@
+export const noticeLimits = {
+  // a row with this many tries is no longer sent, and stays listed in `runner.status`
+  maxTries: 5,
+
+  // the unsent rows one tick reads, tried or not
+  readRows: 200,
+} as const;

package/src/notices/create-null-notifier.ts

@@ -0,0 +1,6 @@
+import type { Notifier } from '@boxxy/model';
+
+// For a configuration that names no notice session: every notice counts as sent.
+export function createNullNotifier(): Notifier {
+  return { tellHold: () => Promise.resolve({ kind: 'sent' }) };
+}

package/src/notices/send-notices.ts

@@ -0,0 +1,41 @@
+import type { NoticeOutcome, NoticeRow } from '@boxxy/model';
+import { noticeLimits } from './constants.ts';
+import type { NoticeReport, SendNoticesInput } from './types.ts';
+
+// Sends each unsent hold notice through the notifier and counts the try on its row. A failed
+// notice stays unsent until it has used `maxTries`. A notifier that throws counts as a failed
+// one, and no notice changes an attempt or an item.
+export async function sendNotices(input: SendNoticesInput): Promise<NoticeReport> {
+  const rows = await input.store.read((tx) => tx.listUnsentNotices(noticeLimits.readRows));
+
+  let sent = 0;
+  let failed = 0;
+
+  for (const row of rows.filter((candidate) => candidate.tries < noticeLimits.maxTries)) {
+    const outcome = await tellHold(input, row);
+
+    const isSent = outcome.kind === 'sent';
+
+    await input.store.exclusive((tx) => tx.markNoticeTried(row.id, input.now, isSent));
+
+    if (isSent) {
+      sent += 1;
+    } else {
+      failed += 1;
+    }
+  }
+
+  return {
+    sent,
+    failed,
+    stuck: rows.filter((candidate) => candidate.tries >= noticeLimits.maxTries).length,
+  };
+}
+
+async function tellHold(input: SendNoticesInput, row: NoticeRow): Promise<NoticeOutcome> {
+  try {
+    return await input.notifier.tellHold({ item: row.item, reason: row.reason, at: row.at });
+  } catch (error) {
+    return { kind: 'failed', reason: error instanceof Error ? error.message : 'notifier threw' };
+  }
+}

package/src/notices/types.ts

@@ -0,0 +1,14 @@
+import type { ClaimStore, Instant, Notifier } from '@boxxy/model';
+
+export interface SendNoticesInput {
+  readonly store: ClaimStore;
+  readonly notifier: Notifier;
+  readonly now: Instant;
+}
+
+// What one tick did with the unsent rows. `stuck` rows have used all their tries.
+export interface NoticeReport {
+  readonly sent: number;
+  readonly failed: number;
+  readonly stuck: number;
+}

package/src/outbox/build-backoff-ms.ts

@@ -0,0 +1,14 @@
+import type { OutboxLimits } from './types.ts';
+
+// The wait before the next try, after this many `retry` answers in a row: the first wait, doubled
+// each time up to the longest wait, then moved by the jitter. `random` is in [0, 1).
+export function buildBackoffMs(retries: number, limits: OutboxLimits, random: number): number {
+  const backoff = limits.backoff;
+
+  const base = Math.min(
+    backoff.firstMs * backoff.factor ** Math.max(retries - 1, 0),
+    backoff.maxMs,
+  );
+
+  return Math.round(base * (1 + backoff.jitter * (2 * random - 1)));
+}

package/src/outbox/build-initial-sender-state.ts

@@ -0,0 +1,14 @@
+import type { SenderState } from './types.ts';
+
+export function buildInitialSenderState(): SenderState {
+  return {
+    queue: [],
+    retries: 0,
+    parkRun: 0,
+    phase: 'idle',
+    failingSince: null,
+    nextTryAt: null,
+    lastError: null,
+    lastStoredAt: null,
+  };
+}

package/src/outbox/build-outbox-status.ts

@@ -0,0 +1,43 @@
+import type { Instant, OutboxStatus } from '@boxxy/model';
+import type { SenderState } from './types.ts';
+
+const msPerMinute = 60_000;
+
+interface OutboxStatusInput {
+  readonly sink: 'pepys' | 'none';
+  readonly state: SenderState;
+  readonly counts: {
+    readonly unsent: number;
+    readonly parked: number;
+    readonly oldestUnsentAt: Instant | null;
+  };
+  readonly now: Instant;
+
+  // a batch is in flight
+  readonly isSending: boolean;
+}
+
+export function buildOutboxStatus(input: OutboxStatusInput): OutboxStatus {
+  return {
+    sink: input.sink,
+    state: pickState(input),
+    unsent: input.counts.unsent,
+    parked: input.counts.parked,
+    lag:
+      input.counts.oldestUnsentAt === null
+        ? null
+        : Math.max(0, Math.floor((input.now - input.counts.oldestUnsentAt) / msPerMinute)),
+    failingSince: input.state.failingSince,
+    nextTryAt: input.state.nextTryAt,
+    lastError: input.state.lastError,
+    lastStoredAt: input.state.lastStoredAt,
+  };
+}
+
+function pickState(input: OutboxStatusInput): OutboxStatus['state'] {
+  if (input.sink === 'none') {
+    return 'off';
+  }
+
+  return input.isSending ? 'sending' : input.state.phase;
+}

package/src/outbox/constants.ts

@@ -0,0 +1,15 @@
+import type { OutboxLimits } from './types.ts';
+
+export const outboxLimits: OutboxLimits = {
+  batchFacts: 100,
+  factBytes: 262_144,
+
+  // One batch is one S2 append, which holds 1,048,576 metered bytes. The rest is margin for S2's
+  // JSON request of about 2 MiB, which a body made mostly of quotes reaches at 1 MiB.
+  batchBytes: 900_000,
+  envelopeBytes: 512,
+  requestTimeoutMs: 10_000,
+  backoff: { firstMs: 1000, factor: 2, maxMs: 300_000, jitter: 0.2 },
+  blockedRetryMs: 300_000,
+  parkRun: 25,
+};

package/src/outbox/measure-wire-bytes.ts

@@ -0,0 +1,31 @@
+import type { OutboxFact } from '@boxxy/model';
+
+const encoder = new TextEncoder();
+
+// An ISO 8601 time of a UTC instant has this one length, so the size needs no date function.
+const isoTimePlaceholder = '2026-01-01T00:00:00.000Z';
+const nullBytes = 4;
+const storeVersionKey = '"storeVersion":';
+
+// The UTF-8 bytes of the fact as the sink sends it: the row's fields, the time as ISO 8601, and
+// the store version added to the payload. The payload is encoded once, and the added field is
+// counted by its length.
+export function measureWireBytes(fact: OutboxFact): number {
+  const envelope = JSON.stringify({
+    type: fact.type,
+    event: fact.factId,
+    entity: fact.entity,
+    actor: fact.actor,
+    at: isoTimePlaceholder,
+    payload: null,
+  });
+
+  const payload = JSON.stringify(fact.payload);
+  const separatorBytes = payload === '{}' ? 0 : 1;
+
+  const addedBytes = payload.startsWith('{')
+    ? separatorBytes + storeVersionKey.length + String(fact.seq).length
+    : 0;
+
+  return encoder.encode(envelope).length - nullBytes + encoder.encode(payload).length + addedBytes;
+}

package/src/outbox/pick-sender-move.ts

@@ -0,0 +1,37 @@
+import type { SinkAnswer } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import type { OutboxLimits, SenderMove } from './types.ts';
+
+interface SenderMoveInput {
+  readonly answer: SinkAnswer;
+  readonly batchSize: number;
+
+  // rows parked since the last `stored`
+  readonly parkRun: number;
+  readonly limits: OutboxLimits;
+}
+
+const versionSkewReason = 'pepys refuses every fact';
+
+// What the sender does with each answer of the sink.
+export function pickSenderMove(input: SenderMoveInput): SenderMove {
+  return match(input.answer)
+    .with({ kind: 'stored' }, (): SenderMove => ({ kind: 'mark-sent' }))
+    .with({ kind: 'retry' }, (): SenderMove => ({ kind: 'retry-same' }))
+    .with({ kind: 'refused-sink' }, (refused): SenderMove => ({
+      kind: 'block',
+      reason: refused.reason,
+    }))
+    .with({ kind: 'refused-batch' }, (refused): SenderMove => {
+      if (input.batchSize > 1) {
+        return { kind: 'split' };
+      }
+
+      if (input.parkRun >= input.limits.parkRun) {
+        return { kind: 'block', reason: versionSkewReason };
+      }
+
+      return { kind: 'park', reason: refused.status === 413 ? 'too-large' : refused.reason };
+    })
+    .exhaustive();
+}