From 7ae223d4ff8ab2def86c8f5274fdd04591f5c39b Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 22 Nov 2026 14:14:09 +0100 Subject: [PATCH] gitea: merge-pull merges plainly only from a watched-branches view read since the last change An unread or stale view held no entry for a watched repository, so every member would have merged plainly with the note no delivery: a merge that reports success and delivers nothing. The registrations holder now keeps the time of its last read and of the last registration-changed heard; the merge call refuses every member ("the watched branches are not read yet") while the view is not read since that change, and a read that fails is said and asked again with the module's growing wait until it answers. Builds: design 47 H2 H-A-471 (second addendum); review finding H-A-471 addendum (2) --- modules/gitea/index.ts | 2 +- modules/gitea/mergecall.ts | 20 +++++--- modules/gitea/registrations.ts | 74 +++++++++++++++++++++------ modules/gitea/seat.ts | 5 +- modules/gitea/test/guard.test.ts | 5 +- modules/gitea/test/merge-call.test.ts | 48 +++++++++++++++++ 6 files changed, 129 insertions(+), 25 deletions(-) diff --git a/modules/gitea/index.ts b/modules/gitea/index.ts index 4e31b6d4b..6bd700ba7 100644 --- a/modules/gitea/index.ts +++ b/modules/gitea/index.ts @@ -304,7 +304,7 @@ void failedSteps.expireSeen().catch((err) => console.log(`[gitea] the seen keys registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll), ...writeTools(writes), ...statusTools("gitea", "gitea_first_views", "gitea_first_view_again", followers, firstViews, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }), ...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, registered: () => registrations.written, judge: (head) => failedSteps.judge(head), - watched: () => registrations.watched, calls, say: seatPublish, partials, once }) : []), + watched: () => (registrations.current ? registrations.watched : null), calls, say: seatPublish, partials, once }) : []), ...callTools(calls, partials, seatPublish, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }), ...(gitea ? [mergedTool(gitea, calls)] : []), tokenLeaseTool(processVaultAndLease().vault, processVaultAndLease().lease, diff --git a/modules/gitea/mergecall.ts b/modules/gitea/mergecall.ts index 051dc2328..22326da15 100644 --- a/modules/gitea/mergecall.ts +++ b/modules/gitea/mergecall.ts @@ -9,7 +9,9 @@ // (no entry, or an empty set, in the registrations' watched branches) is the forge's business alone (H2 H-A-471 and its // addendum): judged against nothing of the module graph, merged plainly in the order named, answered and kept merged with // the note no delivery, and left out of merge-called, so it starts no delivery. A watched repository whose base is no -// watched branch stays refused. +// watched branch stays refused. A member is merged plainly only from a view of the watched branches read since the last +// registration-changed heard (the second addendum): while the view is unread or stale, every member is refused, never +// merged with the note. import { randomBytes } from "node:crypto"; import { UNPROVEN, callerOf } from "@novox/mesh-sdk/callers"; @@ -24,8 +26,9 @@ import type { Partials } from "./partials.js"; export interface CallDeps { /** Whether the first registrations were written: until then no merge is made (design 47 §95). */ registered: () => boolean; - /** The watched branches the registrations name, by their origin repository `/`. */ - watched: () => ReadonlyMap>; + /** The watched branches the registrations name, by their origin repository `/`; null while they are not + * read since the last registration-changed heard (H-A-471, second addendum). */ + watched: () => ReadonlyMap> | null; /** The failed `required` step that refuses a head, or null (failedsteps.ts). */ judge: (head: string) => Promise; /** A new call's id: 16 lowercase hex characters (H-A-24). */ @@ -63,6 +66,9 @@ export interface Member { /** The note of a member merged plainly: it starts no delivery (H-A-471). */ export const NO_DELIVERY = "no delivery: the repository has no watched branch"; +/** Why every member is refused while the watched branches are unread or stale (H-A-471, second addendum). */ +export const NOT_READ = "the watched branches are not read yet"; + const SHA = /^[0-9a-f]{40}$/; export const CALL = /^[0-9a-f]{16}$/; @@ -89,7 +95,7 @@ export function membersOf(raw: unknown): Member[] { } /** Why a member is refused at judging, or "" when it is judged. */ -async function judgeMember(forge: CallForge, deps: CallDeps, m: Member): Promise { +async function judgeMember(forge: CallForge, deps: CallDeps, watched: ReadonlyMap>, m: Member): Promise { const pull = await forge.getPullRequest(m.owner, m.repo, m.number); m.branch = String(pull.base ?? ""); if (pull.merged) { @@ -100,7 +106,7 @@ async function judgeMember(forge: CallForge, deps: CallDeps, m: Member): Promise if (pull.head_sha !== m.head) { return `head-moved: its head is ${String(pull.head_sha).slice(0, 12)}, not the ${m.head.slice(0, 12)} the caller names`; } - const branches = deps.watched().get(m.repository); + const branches = watched.get(m.repository); // A repository of no module: no build-input fingerprint and no required step judge it (H-A-471). if (!branches || branches.size === 0) { m.plain = true; @@ -147,10 +153,12 @@ export async function mergeCall(forge: CallForge, args: Record, if (!deps.registered()) throw new Refused("no module is registered yet: the catalog has said no registration-changed, so no merge is made until the first registrations are written"); const call = (deps.newCall ?? newCallId)(); if (!CALL.test(call)) throw new Error(`the call's id ${JSON.stringify(call)} is not 16 lowercase hex characters`); + // One view judges the whole call; unread or stale, it judges no member (H-A-471, second addendum). + const watched = deps.watched(); // Every member is judged before any is merged (§735). let refused = false; for (const m of members) { - const why = await judgeMember(forge, deps, m); + const why = watched ? await judgeMember(forge, deps, watched, m) : NOT_READ; if (why) { m.state = "refused"; m.why = why; diff --git a/modules/gitea/registrations.ts b/modules/gitea/registrations.ts index 3d8f5828d..f3eb77346 100644 --- a/modules/gitea/registrations.ts +++ b/modules/gitea/registrations.ts @@ -4,11 +4,17 @@ // two ways, both through the seat `mesh-catalog`: its verb `registrations` asked at the start (a restart after the first // registrations were written), and its event `registration-changed` (the first being written, or heard again from the // seat's kept stream). Neither is the holder's state or a module named. +// +// **A plain merge needs a view read since the last change heard** (design 47 H2 H-A-471, second addendum): the holder keeps +// the time of its last read of the watched branches and of the last registration-changed it heard; the view is current only +// when a read asked after that change has answered. A read that fails is said and asked again with a growing wait until it +// answers, so an unread view is never taken as "no watched branch". import { seat as CATALOG, verbs as CATALOG_VERBS, events as CATALOG_EVENTS, type RegistrationChangedEvent, type RegistrationsAnswer, type RegistrationsInput, } from "@novox/mesh-delivery-contracts-mesh-catalog"; +import { bindWait } from "./bind.js"; /** The seat verb asked, as the manifest's `invokes` names it. */ export const REGISTRATIONS_VERB = `seat:${CATALOG}.${CATALOG_VERBS.registrations}`; @@ -18,8 +24,18 @@ export const REGISTRATION_CHANGED_EVENT = `${CATALOG}.${CATALOG_EVENTS.registrat export class Registrations { private first = false; private byRepository = new Map>(); + /** The registration-changed events heard; the count a read was asked at, once it answered (-1: never read). */ + private changes = 0; + private readAtChange = -1; + /** The reads asked, and the latest whose answer is the view (an older answer landing later is not taken). */ + private asked = 0; + private applied = 0; + private lastRead?: Date; + private lastChange?: Date; constructor(private readonly ask: (verb: string, input: RegistrationsInput) => Promise, - private readonly log: (line: string) => void = () => {}) {} + private readonly log: (line: string) => void = () => {}, + private readonly sleep: (ms: number) => Promise = (ms) => new Promise((r) => setTimeout(r, ms)), + private readonly now: () => Date = () => new Date()) {} /** Whether the first registrations are written: the one fact the merge switches on. */ get written(): boolean { @@ -31,6 +47,19 @@ export class Registrations { return this.byRepository; } + /** Whether the watched branches were read since the last registration-changed heard (H-A-471, second addendum). */ + get current(): boolean { + return this.readAtChange === this.changes; + } + + /** The time the last read that answered was asked, and of the last registration-changed heard. */ + get readAt(): Date | undefined { + return this.lastRead; + } + get changedAt(): Date | undefined { + return this.lastChange; + } + /** One `registration-changed`: the first registration written, however many were before this module started. */ hear(ev: RegistrationChangedEvent | undefined): void { if (!ev || typeof ev.module !== "string" || ev.module === "") { @@ -38,25 +67,40 @@ export class Registrations { } if (!this.first) this.log(`the first registration is written (${ev.module}); merge-pull merges from here`); this.first = true; + this.changes++; + this.lastChange = this.now(); } /** The start's first view, asked again after each `registration-changed`: any registration held is the first written, and its - * watched branches are read. A failed ask is said and left to the event. */ + * watched branches are read. A failed ask is said and asked again with a growing wait until it answers (H-A-471, second + * addendum); until then no member is merged plainly. */ async start(): Promise { - try { - let a: unknown = await this.ask(REGISTRATIONS_VERB, {}); - if (typeof a === "string") a = JSON.parse(a); - const r = (a as RegistrationsAnswer | undefined)?.registrations; - if (!Array.isArray(r)) throw new Error(`${REGISTRATIONS_VERB} answered no registrations: ${JSON.stringify(a ?? null).slice(0, 200)}`); - const by = new Map>(); - for (const x of r) for (const b of x.branches ?? []) (by.get(x.origin) ?? by.set(x.origin, new Set()).get(x.origin)!).add(b); - this.byRepository = by; - if (r.length > 0) { - this.first = true; - this.log(`${r.length} registrations are held; merge-pull merges`); + for (let attempt = 1; ; attempt++) { + const at = this.changes, seq = ++this.asked, askedAt = this.now(); + try { + let a: unknown = await this.ask(REGISTRATIONS_VERB, {}); + if (typeof a === "string") a = JSON.parse(a); + const r = (a as RegistrationsAnswer | undefined)?.registrations; + if (!Array.isArray(r)) throw new Error(`${REGISTRATIONS_VERB} answered no registrations: ${JSON.stringify(a ?? null).slice(0, 200)}`); + if (seq < this.applied) return; + const by = new Map>(); + for (const x of r) for (const b of x.branches ?? []) (by.get(x.origin) ?? by.set(x.origin, new Set()).get(x.origin)!).add(b); + this.byRepository = by; + this.applied = seq; + this.readAtChange = at; + this.lastRead = askedAt; + if (attempt > 1) this.log(`the registrations are read after ${attempt} attempts`); + if (r.length > 0) { + this.first = true; + this.log(`${r.length} registrations are held; merge-pull merges`); + } + return; + } catch (err) { + const wait = bindWait(attempt); + this.log(`the registrations could not be read: ${err instanceof Error ? err.message : String(err)}; ` + + `no member is merged plainly until they are, asked again in ${wait / 1000}s`); + await this.sleep(wait); } - } catch (err) { - this.log(`the registrations could not be read: ${err instanceof Error ? err.message : String(err)}; merge-pull waits for registration-changed`); } } } diff --git a/modules/gitea/seat.ts b/modules/gitea/seat.ts index 48f1dd39d..5eef8308b 100644 --- a/modules/gitea/seat.ts +++ b/modules/gitea/seat.ts @@ -54,8 +54,9 @@ export interface SeatDeps { registered: () => boolean; /** The failed `required` step that refuses a head, judged from the module's own state `failed-steps` (failedsteps.ts), or null. */ judge: (head: string) => Promise; - /** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one. */ - watched: () => ReadonlyMap>; + /** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one; + * null while they are not read since the last registration-changed heard (H-A-471, second addendum). */ + watched: () => ReadonlyMap> | null; /** The state calls (calls.ts): each merge call written before its first merge (design 47 H §766). */ calls?: Calls; /** Says merge-called on the seat (mesh-sdk runtime.seatPublish; design 47 H §736). */ diff --git a/modules/gitea/test/guard.test.ts b/modules/gitea/test/guard.test.ts index ec6fa230a..e544a1ef8 100644 --- a/modules/gitea/test/guard.test.ts +++ b/modules/gitea/test/guard.test.ts @@ -570,7 +570,10 @@ test("the first registrations are learned from the seat mesh-catalog's verb at t const held = reg(JSON.stringify({ registrations: [{ module: "mesh-sdk" }] })); await held.start(); assert.equal(held.written, true, "a registration held at the start"); - const down = reg(new Error("no responders")); + // A failed first view is said and asked again (H-A-471, second addendum): the test's wait answers it with none. + let downAnswer: unknown = new Error("no responders"); + const down = new Registrations(async () => { if (downAnswer instanceof Error) throw downAnswer; return downAnswer; }, (l) => said.push(l), + async () => { downAnswer = { registrations: [] }; }); await down.start(); assert.equal(down.written, false); assert.match(said.join("\n"), /could not be read: no responders/, "a failed first view is said, never taken as none silently"); diff --git a/modules/gitea/test/merge-call.test.ts b/modules/gitea/test/merge-call.test.ts index 3c5a065ac..e44d0c27f 100644 --- a/modules/gitea/test/merge-call.test.ts +++ b/modules/gitea/test/merge-call.test.ts @@ -125,6 +125,54 @@ test("a member of a repository with no watched branch is merged plainly, noted n } }); +// **A plain merge needs a view read since the last change heard** (design 47 H2 H-A-471, second addendum): while the +// watched branches are unread, or were read before a later registration-changed, every member is refused ("the watched +// branches are not read yet"), never merged with the note; a view read after the change merges the unwatched member +// plainly. A read that fails is said and asked again until it answers. +test("a member is merged plainly only from a watched-branches view read since the last registration-changed", async () => { + const { Registrations } = await import("../dist/registrations.js"); + const NOT_READ = "the watched branches are not read yet"; + const said: string[] = []; + const waits: number[] = []; + let answer: unknown = new Error("no responders"); + const reg = new Registrations(async () => { if (answer instanceof Error) throw answer; return answer; }, (l) => said.push(l), + async (ms) => { waits.push(ms); answer = { registrations: [{ module: "app", origin: "novox/app", branches: ["main"] }] }; }); + const hq = { by: "lead@shanks", pulls: [{ repository: "novox/hq", number: 799, head: B }, two.pulls[0]] }; + const pulls = () => Object.assign(open(), { "novox/hq#799": { base: "main", head: B, state: "open", merged: false } }); + const view = () => (reg.current ? reg.watched : null); + reg.hear({ module: "app", moved: ["watch"], version: 1, warrant: "q-1" }); + // Unread: every member refused, nothing merged. + const f1 = forge(pulls()); + const unread = await call(f1, hq, { watched: view }); + assert.deepEqual([f1.merges, unread.members.map((m: any) => [m.state, m.why, m.note])], + [[], [["refused", NOT_READ, undefined], ["refused", NOT_READ, undefined]]], "an unread view refuses every member"); + // A failed read is said and asked again until it answers; read, the view is current. + await reg.start(); + assert.deepEqual([waits, reg.current], [[2_000], true]); + assert.match(said.join("\n"), /could not be read: no responders; no member is merged plainly until they are, asked again in 2s/); + assert.ok(reg.readAt && reg.changedAt && reg.readAt >= reg.changedAt, "the times of the last read and the last change are kept"); + // A registration-changed heard after the read: stale, every member refused again. + reg.hear({ module: "app", moved: ["watch"], version: 2, warrant: "q-2" }); + const f2 = forge(pulls()); + const stale = await call(f2, hq, { watched: view }); + assert.deepEqual([f2.merges, stale.members.map((m: any) => m.why)], [[], [NOT_READ, NOT_READ]], "a view read before a later change refuses"); + // A change heard while a read is asked leaves the view stale. + let release!: () => void; + answer = { registrations: [{ module: "app", origin: "novox/app", branches: ["main"] }] }; + const slow = new Registrations(() => new Promise((r) => { release = () => r(answer); })); + const asking = slow.start(); + slow.hear({ module: "app", moved: ["watch"], version: 3, warrant: "q-3" }); + release(); + await asking; + assert.equal(slow.current, false, "a read asked before the change heard is not since it"); + // Read again after the change: the unwatched member merges plainly with the note, the watched one as any call's. + await reg.start(); + const f3 = forge(pulls()); + const landed = await call(f3, hq, { watched: view }); + assert.deepEqual([f3.merges, landed.members.map((m: any) => [m.state, m.note])], + [["novox/hq#799", "novox/app#5"], [["merged", "no delivery: the repository has no watched branch"], ["merged", undefined]]]); +}); + test("a call is refused whole with no proved caller, no by, no registration or no pull request", async () => { const f = forge(open()); await assert.rejects(call(f, two, {}, ""), /proved no caller account/);