@foss.global/codefeed 5.5.0 → 5.6.0

package/changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-11-15 - 5.6.0
+
+### Features
+
+- read a Gitea source's quiescence facts and send its HTTP freeze canaries for the migration's freeze proof (giteasourcefreeze)
+  - `GiteaQuiescenceReader.read()` returns an `IForgeSourceQuiescenceReport` (`@foss.global/interfaces` 3.5) with the connection's read-only site administrator token and GET requests only (S11 ruling D1): every runner of `GET /admin/actions/runners?disabled=false`, page after page at `limit=50` until the rows cover `total_count`, sorted by numeric id, with Gitea's `status` and `busy` as evidence; `total_count` of the `in_progress` jobs with `blindSpot: 'cancelling'`; every cron task with its schedule verbatim, sorted by name; and the runs Gitea lists as `queued` or `pending`, sorted by numeric id, or `overBound` with Gitea's count past `forgeSourceQuiescenceQueuedRunMaxRecords`. A part whose read does not finish is null with `<part>: <code>` in `incompleteReasons`, never an empty list; a listing whose filter Gitea ignored fails its part (`runner-filter-ignored`, `job-filter-ignored`, `run-filter-ignored`), as do a total that changes between pages, a row listed twice and rows that do not add up to the total. The reader decides nothing: the consumer calls the source quiescent.
+  - `GiteaFreezeProbe.run({ origins, canaries, signal })` sends the HTTP canaries with the canary credential only and returns one `IForgeSourceFreezeCanaryOutcome` per origin and canary (S11 ruling D2, G14; canary addendum 1): `receive-pack-discovery`, `archive-get`, `issue-post`, `release-post`, `generic-package-put`, `oci-blob-upload` (the registry token `GET`, then the upload `POST`), `lfs-put` (the batch request, then the object `PUT` on the same origin) and `lfs-off` (the batch `upload` request alone). Before any write it reads `/user`, `/user/orgs` and `/user/repos` through every origin and rejects an administrator, an unrestricted account or one that reaches more than the canary organization and repository with `canary-credential-overbroad` (S11 ruling D3), one that reaches neither with `canary-credential-mismatch`, and origins that show another account or canary repository id with `canary-origin-mismatch`. Every write carries a fresh nonce. An outcome reports the status of the canary's own request, its `X-Gitea-Freeze` header verbatim and what a 2xx created; redirects are reported and never followed, failures are codes without a status, and no outcome or error carries a body or a credential. The probe never judges the marker.
+  - An origin's `connectAddress` sends its connections to that IP address on `baseUrl`'s port, while the Host header, the TLS server name and the certificate check stay `baseUrl`'s host (`createNodeAgents` takes it as its third argument).
+  - Gitea 28.2.0 facts the reader relies on, from its source: a run's own `repository_id` reads 0, so the repository comes from the run's embedded record; `head_branch` is omitted for a run on a tag (`ref` reads `''`); the `pending` filter selects runs shown as `pending`, `requested` or `waiting`; `/user/orgs` and `/user/repos` carry `X-Total-Count`; an LFS upload action asks for `Transfer-Encoding: chunked`, which the probe replaces with the object's length.
+
 ## 2026-11-14 - 5.5.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/codefeed',
-    version: '5.5.0',
+    version: '5.6.0',
     description: 'The @foss.global/codefeed module generates commit/activity feeds from forge providers including Gitea and GitManager.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx1QkFBdUI7SUFDN0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVIQUF1SDtDQUNySSxDQUFBIn0=

package/dist_ts/classes.giteasourcefreeze.d.ts

@@ -0,0 +1,99 @@
+import * as plugins from './plugins.js';
+type IQuiescenceReport = plugins.fossInterfaces.data.IForgeSourceQuiescenceReport;
+type IFreezeOrigin = plugins.fossInterfaces.data.IForgeSourceFreezeOrigin;
+type TFreezeCanary = plugins.fossInterfaces.data.TForgeSourceFreezeHttpCanary;
+type ICanaryOutcome = plugins.fossInterfaces.data.IForgeSourceFreezeCanaryOutcome;
+export interface IGiteaQuiescenceReaderOptions {
+    /** Operator-assigned identity of the source instance. */
+    instanceId: string;
+    /** Instance root, including an optional deployment subpath. HTTPS is required. */
+    baseUrl: string;
+    /**
+     * A site administrator's token, the connection's read-only one, retained
+     * only in this reader's memory. It is sent only to `baseUrl`, only in GET
+     * requests, and never appears in reports, reasons or errors.
+     */
+    token: string;
+    /** PEM certificates that replace the default trust store for this reader's connections. */
+    caCertificates?: string[];
+    /** Deadline of one request; defaults to 60 s, at most 300 s. */
+    requestTimeoutMs?: number;
+}
+/**
+ * Reads the writers of a Gitea source for a freeze proof, with GET requests
+ * and a site administrator's token only: every enabled Actions runner, the
+ * jobs in progress, the cron tasks and the runs waiting to start. It reports
+ * facts only; whether the source is quiescent is the consumer's decision.
+ */
+export declare class GiteaQuiescenceReader {
+    #private;
+    constructor(optionsArg: IGiteaQuiescenceReaderOptions);
+    /** Validated, normalized instance root; contains no credentials or API suffix. */
+    get baseUrl(): string;
+    /**
+     * Reads the report. Rejects unless the token belongs to a site
+     * administrator (`reader-not-site-admin`) and the forge reports a version;
+     * a part whose read does not finish is null, with `<part>: <code>` in
+     * `incompleteReasons`. Queued runs past
+     * `forgeSourceQuiescenceQueuedRunMaxRecords` are `overBound` with the
+     * forge's count and are not read further. An abort rejects with
+     * `request-aborted`.
+     */
+    read(signalArg?: AbortSignal): Promise<IQuiescenceReport>;
+}
+export interface IGiteaFreezeProbeOptions {
+    /**
+     * The canary credential's token, never the connection's administrator
+     * token, retained only in this probe's memory: a restricted,
+     * non-administrator account whose only organization is the canary
+     * repository's owner and whose only repository is the canary repository.
+     * It is sent only to the origins of a run and never appears in outcomes or
+     * errors.
+     */
+    token: string;
+    /** The canary repository; its owner is the canary organization, and its generic and container packages carry its name. */
+    repository: {
+        owner: string;
+        name: string;
+    };
+    /** PEM certificates that replace the default trust store for the probe's connections. */
+    caCertificates?: string[];
+    /** Deadline of one request, its response body included; defaults to 60 s, at most 300 s. */
+    requestTimeoutMs?: number;
+}
+export interface IGiteaFreezeProbeRunOptions {
+    /** The network paths to send the canaries through, each at most once; all must reach the same instance. */
+    origins: IFreezeOrigin[];
+    /** The canaries each origin gets, in order, each at most once: the consumer's canary configuration. */
+    canaries: TFreezeCanary[];
+    signal?: AbortSignal;
+}
+/**
+ * Sends a Gitea source's HTTP freeze canaries for a freeze proof, with the
+ * canary credential only. Before any write it reads `/user`, `/user/orgs` and
+ * `/user/repos` through every origin of the run and refuses a credential that
+ * reaches more than the canary repository (`canary-credential-overbroad`).
+ * Each canary targets the canary repository or its packages, and every write
+ * carries a fresh nonce. It reports what each canary's own request answered:
+ * the status, the `X-Gitea-Freeze` header verbatim and what a 2xx created. It
+ * never returns a response body or a credential, never follows a redirect and
+ * never judges the marker.
+ */
+export declare class GiteaFreezeProbe {
+    #private;
+    constructor(optionsArg: IGiteaFreezeProbeOptions);
+    /**
+     * Runs the preflight through every origin, then sends each canary through
+     * each origin, origins and canaries in the order given, and returns one
+     * outcome per pair. A preflight that does not pass rejects before any
+     * canary is sent: `canary-credential-overbroad` when the account is an
+     * administrator, is not restricted, or reaches another organization or
+     * repository; `canary-credential-mismatch` when it reaches no organization
+     * or repository at all; `canary-origin-mismatch` when two origins name a
+     * different account or canary repository id; a failed read with its code.
+     * An abort rejects with `request-aborted`; every other failure is an
+     * outcome's `errorCode`.
+     */
+    run(optionsArg: IGiteaFreezeProbeRunOptions): Promise<ICanaryOutcome[]>;
+}
+export {};