@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/plugins/join-request-jobs.service.d.ts

@@ -0,0 +1,250 @@
+import { type AuthUser, type ChangeRequestState, type IWorkflowService } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { JoinRequestRecord, JoinRequestStore } from './join-request-records.store.js';
+/**
+ * How long a claim outlives its last heartbeat before another process may
+ * take the record over.
+ *
+ * Three missed beats. It does NOT have to cover the longest honest attempt —
+ * that was the mistake this replaced. Sizing the window to a first-ever
+ * request's full clone made a crash-restart wait out the whole clone window
+ * before anything would retry, and a boot is far quicker than that, so the
+ * boot sweep was refused every row it had come to rescue and gave up. A
+ * heartbeat decouples the two: a live process holds its claim for as long as
+ * the work genuinely takes, however long that is, and a dead one lets go
+ * within a minute and a half.
+ */
+export declare const CLAIM_STALE_AFTER_MS: number;
+/**
+ * A failure that says nothing about the REQUEST — the platform simply could
+ * not do the work just now. Thrown instead of returning a refusal when the
+ * knowledge base is not readable yet, which is a boot that has not finished
+ * cloning or a remote that blipped, and is indistinguishable from "the plugin
+ * was deleted" if you only look at an empty catalog.
+ *
+ * The difference matters to the person who clicked: a refusal is shown to
+ * them and takes their request off the page, while this leaves the row
+ * `pending` — still "Requested", still owed — for the next sweep to retry.
+ */
+export declare class JoinRequestNotReadyError extends Error {
+    constructor(message: string);
+}
+/** What a recorded plugin key still names, resolved when the job runs. */
+export interface JoinRequestTarget {
+    /** The plugin's primary folder, workspace-relative (`Plugins/Finance`). */
+    folder: string;
+    /** What people call it — the change request's title and body carry this. */
+    displayName: string;
+}
+export interface JoinRequestJobsDeps {
+    workflow: Pick<IWorkflowService, 'createBranch' | 'listBranches' | 'commitChanges' | 'openChangeRequest' | 'listChangeRequestsAuthoredBy'>;
+    workspaceService: Pick<WorkspaceService, 'getOrCreateForBranch' | 'readFile' | 'writeFile'>;
+    kbDirName: string;
+    /**
+     * The plugin a recorded key still names, or null when nothing does — it was
+     * deleted, or its folder moved out from under the record.
+     */
+    target(pluginKey: string): Promise<JoinRequestTarget | null>;
+    /**
+     * The requester as an author. Resolved per run rather than carried on the
+     * record because the boot sweep has no request to read an identity from,
+     * and the commit and change request are the requester's, not the platform's.
+     */
+    requester(email: string): Promise<AuthUser | null>;
+}
+/**
+ * The git half of a join request, after the answer.
+ *
+ * The endpoint used to do all of this before it replied: create the branch on
+ * the remote, clone the plugins repository for it (many seconds the first
+ * time a person asks for anything), splice the grant into `access.md`, commit,
+ * push, open the change request. The click looked like a freeze for as long as
+ * that took. So the route now records the ask and answers, and this runs the
+ * same steps afterwards, against the recorded row — nothing about what lands
+ * on the git host changed, including the change request's title, body and
+ * diff, so the plugin's managers see exactly what they saw before.
+ *
+ * SINGLE FLIGHT PER RECORD, and the record's id is the key: a second click, a
+ * second tab, or a sweep that overlaps a live run all join the run already
+ * under way instead of starting a second one. Since the row is unique on
+ * `(requester, plugin)`, that is also what makes two clicks one change
+ * request.
+ *
+ * AND IDEMPOTENT ANYWAY, because single-flight is an in-process promise and a
+ * restart is not: every step tolerates having run before. An existing open
+ * join change request is adopted rather than duplicated, a leftover branch is
+ * reused, and the splice no-ops when the grant is already on the branch. That
+ * is what lets the boot sweep re-run every `pending` row without asking which
+ * of them got how far.
+ *
+ * AND ACROSS PROCESSES, by claiming the row. Single-flight is an in-process
+ * map, and a redeploy runs two processes for as long as the changeover takes
+ * — both sweeping, neither able to see the other's map. The sweep cannot go
+ * under the commit-worker lease to fix that: it is sequenced after the
+ * knowledge-base startup phase instead, in `createCoreServer`, because it
+ * needs the default-branch clone that phase maintains and the plugin catalog
+ * read from it, and a sweep that ran first would mark every row failed for a
+ * knowledge base that was merely not ready yet. So exclusion is taken where
+ * the row lives: `run` claims it with one conditional UPDATE, and a process
+ * that does not get the claim does nothing. Two servers cloning, committing
+ * and pushing the same branch into the same shared workspace is what that
+ * prevents; the adoption check below, on a FRESH listing, is the second line
+ * for the change request itself.
+ *
+ * THE CLAIM IS A HEARTBEAT, and that is the part worth being careful about. A
+ * bare `claimed_at` cannot distinguish a process still working from one that
+ * died holding the row, so whatever window you pick is wrong in one
+ * direction: long enough to cover a first-ever request's clone, and a crash
+ * leaves the request owed for that whole window — which is how the boot
+ * sweep, the very thing meant to rescue it, came to be refused every row it
+ * asked for and to give up silently. So a running job pushes its claim
+ * forward every {@link CLAIM_HEARTBEAT_MS}, and the window is three missed
+ * beats. A live process holds a row for as long as the work honestly takes; a
+ * dead one lets go in ninety seconds.
+ *
+ * AND THE CLAIM IS FENCED, because a heartbeat still cannot make missing the
+ * window impossible — a long GC pause, a frozen host, a partition that
+ * outlives three beats. A worker that comes back from one believes it still
+ * holds a row another worker has since taken, and if the writes that decide
+ * the row were addressed by id alone it would settle its replacement's
+ * attempt: the replacement's fresh run stamped `opened` by the straggler's
+ * stale number, or a run that is going fine stamped `failed` under it. So a
+ * claim mints a token, and every write that holds or decides the row names
+ * the token it believes it holds. A superseded worker writes nothing.
+ *
+ * The same mechanism is what makes the row's DELETION visible. Account
+ * erasure removes a requester's rows outright, in a transaction this has no
+ * part in; a beat against a row that is gone matches nothing, exactly as a
+ * beat against a stolen one does. Both read as "not ours any more".
+ *
+ * So {@link attempt} beats the claim in front of each step that touches the
+ * world — before the branch, after the clone and immediately before the file
+ * write and push, and again immediately before the change request — rather
+ * than once at the end. The clone between the first two is the long step, and
+ * a check taken before it says nothing about who owns the row by the time it
+ * returns. Anything short of a confirmed `held` stops the work, including a
+ * beat that could not reach the database at all: in front of something
+ * irreversible, not knowing is treated as not owning.
+ *
+ * None of that makes a gate and the step behind it atomic, and it is not
+ * meant to. It narrows the exposure from the whole of a clone to a single
+ * statement, and what carries the rest is that every step here is idempotent
+ * and the deciding writes are fenced — so even two workers racing through the
+ * git leave exactly one change request. A lease that could not expire across
+ * these steps would close the window instead, and is the one option not open:
+ * that is precisely what the heartbeat replaced, and it left the request of
+ * any process that died owed forever.
+ *
+ * AND SOMETHING ALWAYS LOOKS AGAIN. {@link startSweeping} re-reads the owed
+ * rows on a timer, not only at boot, because the one case boot cannot cover
+ * is the redeploy: the incoming process skips a row the outgoing one holds,
+ * and the outgoing process then exits mid-work. A requester cannot rescue
+ * that themselves — a pending record shows them the "Requested" card, not a
+ * button — so nothing but this tick would ever pick the row up.
+ */
+export declare class PluginJoinRequestJobs {
+    private readonly store;
+    private readonly deps;
+    private readonly inFlight;
+    private sweepTimer;
+    /**
+     * Set by `stopSweeping`: the process is shutting down. A start that arrives
+     * after it — a request handler still finishing while the pool is being
+     * drained — runs nothing; the row stays `pending` and the next boot's sweep
+     * does the work, exactly as for a row written just before a crash.
+     */
+    private stopping;
+    constructor(store: JoinRequestStore, deps: JoinRequestJobsDeps);
+    /**
+     * Record the ask — the whole of what the endpoint does before answering.
+     * One statement against one row, so it costs a database round-trip and no
+     * git at all.
+     */
+    record(user: AuthUser, pluginKey: string): Promise<JoinRequestRecord>;
+    /**
+     * An `opened` record whose change request is no longer open is an ask that
+     * was ANSWERED — declined by a manager, withdrawn, or settled and the
+     * access since taken back — and the click that finds it is a new ask. Put
+     * the row back to `pending` so the caller can carry it; hand back every
+     * other record unchanged.
+     *
+     * The request's state is read from its own row, not from a listing: every
+     * listing is open-only and cached, so a closed request is simply absent
+     * from it, and absence proves nothing. The row says `closed`. A number with
+     * no row at all is over too — nothing is standing under it.
+     */
+    reviveIfAnswered(record: JoinRequestRecord): Promise<JoinRequestRecord>;
+    /** The state of each named change request, by its row — see the store. */
+    changeRequestStates(numbers: readonly number[]): Promise<Map<number, ChangeRequestState>>;
+    /** Every request this person has recorded — what the plugin listing reads. */
+    recordsFor(email: string): Promise<JoinRequestRecord[]>;
+    /**
+     * Run the git work for `record`, or join the run already under way for it.
+     * Returns the flight so a test (or the sweep) can await it; callers on the
+     * request path deliberately do not. Never rejects — a failure is recorded
+     * on the row, which is where the requester reads it.
+     */
+    start(record: JoinRequestRecord): Promise<void>;
+    /**
+     * Re-run every record still `pending` — what makes a recorded request
+     * survive: a row written before a process died is completed or marked
+     * failed afterwards, never left owed.
+     *
+     * A record another LIVE process is working is skipped by the claim, not by
+     * this: the sweep asks for everything pending and lets each attempt decide.
+     */
+    sweep(): Promise<void>;
+    /**
+     * Sweep now, and keep sweeping.
+     *
+     * Boot alone left a hole with no second door: a redeploy's incoming process
+     * sweeps while the outgoing one still holds a record, skips it correctly,
+     * and then the outgoing process exits mid-work — after which nothing looked
+     * at that row again until the next boot. Nothing else retries, because the
+     * only other way a record is picked up is its requester clicking again, and
+     * a pending record shows them the "Requested" card rather than a button.
+     *
+     * Idempotent, and safe to call when a sweep is already scheduled.
+     */
+    startSweeping(intervalMs?: number): void;
+    /**
+     * Stop the periodic sweep, and refuse to start any further job. Part of
+     * shutting down cleanly: what is in flight is awaited by `drain`; nothing
+     * new begins against a pool that is about to end.
+     */
+    stopSweeping(): void;
+    /**
+     * Every job now in flight, as one promise. The test seam, and the honest
+     * answer to "is the background work done" for anything that has to know.
+     */
+    drain(): Promise<void>;
+    private run;
+    /**
+     * The work itself. The caller has already claimed `record` and passes the
+     * claim it holds, plus `stillOurs` — which beats the claim and throws
+     * {@link ClaimLostError} if the row has moved on. That is called before each
+     * step that touches the world, so a claim lost mid-clone costs a clone
+     * rather than a duplicate change request.
+     */
+    private attempt;
+    /**
+     * Have the join branch, whether this call made it or an earlier one did.
+     *
+     * `createBranch` failing is ambiguous — the branch already exists (the
+     * ordinary case: a rejected request left it, or a retry is re-running), or
+     * the git host refused for a reason that leaves nothing to work against.
+     * Swallowing both was the bug: every later step then ran against a branch
+     * that was never created, and the requester read whatever confused error
+     * fell out downstream instead of the one that actually happened.
+     *
+     * So a failure is only forgiven when a FRESH listing proves the branch is
+     * there. `strictFetch` is what makes that a proof rather than a guess: a
+     * stale list from a clone that could not reach origin would report a branch
+     * created seconds ago as missing, and — worse — would let a genuine refusal
+     * pass as "already exists". Anything the listing does not vouch for is
+     * rethrown, which marks the row failed with the git host's own words and
+     * leaves the next click free to retry the same row.
+     */
+    private ensureBranch;
+}
+//# sourceMappingURL=join-request-jobs.service.d.ts.map

package/dist/modules/plugins/join-request-jobs.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-request-jobs.service.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/join-request-jobs.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAEV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,iCAAiC,CAAC;AAgBzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,QAAY,CAAC;AAe9C;;;;;;;;;;GAUG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAuDD,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,IAAI,CACZ,gBAAgB,EACd,cAAc,GACd,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,8BAA8B,CACjC,CAAC;IACF,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC7D;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,qBAAa,qBAAqB;IAY9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,UAAU,CAA+C;IACjE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAS;gBAGN,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,mBAAmB;IAG5C;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAQ3E;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAO7E,0EAA0E;IACpE,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAI/F,8EAA8E;IACxE,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAI7D;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,UAAU,GAAE,MAA0B,GAAG,IAAI;IAe3D;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAOpB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,GAAG;IAyGjB;;;;;;OAMG;YACW,OAAO;IAmHrB;;;;;;;;;;;;;;;;;OAiBG;YACW,YAAY;CAc3B"}