@foss.global/codefeed 4.1.0 → 4.2.0

package/dist_ts/forgeinventory.transfer.d.ts

@@ -0,0 +1,75 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+/**
+ * Reads and drops at most 64 KiB of a response body that carries nothing the
+ * caller uses, so its connection can be reused; a longer or failing body is
+ * discarded with its connection.
+ */
+export declare const discardBody: (bodyArg: AsyncIterable<Uint8Array> | null) => Promise<void>;
+export interface ITransferBoundsOptions {
+    /** Wall-clock limit of the whole transfer. */
+    limitMs: number;
+    /** Longest gap between two chunks of a watched source. */
+    idleMs: number;
+    /** The code a passed wall-clock or idle limit fails with. */
+    timedOutCode: string;
+    /** The code a watched source that goes on after the transfer ended fails with. */
+    failedCode: string;
+}
+export interface ITransferBounds {
+    /** Aborts once the caller aborts, a limit passes or the transfer ends. */
+    signal: AbortSignal;
+    /** Ends the transfer: clears its timers and aborts `signal`. Idempotent. */
+    end: () => void;
+    /**
+     * The error the transfer fails with: the reason that ended it (`request-aborted`
+     * or the timeout code), else `errorArg` when it is a `ForgeInventoryError`,
+     * else `fallbackArg`.
+     */
+    failure: (errorArg: unknown, fallbackArg: string) => validation.ForgeInventoryError;
+    /** Runs one step of the transfer; it rejects as soon as the transfer ends, even if the step does not. */
+    run: <T>(stepArg: () => Promise<T>) => Promise<T>;
+    /** Re-arms the idle limit, before a step that waits on the network without a watched source. */
+    touch: () => void;
+    /** Passes chunks on and re-arms the idle limit on each one. */
+    watch: (sourceArg: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array, void, undefined>;
+}
+/**
+ * The bounds of one streamed transfer: the caller's signal, a wall-clock limit
+ * and an idle limit that `watch` re-arms on every chunk. Whichever ends it
+ * first decides the failure code. Every transfer must be ended with `end`.
+ */
+export declare const createTransferBounds: (signalArg: AbortSignal | undefined, optionsArg: ITransferBoundsOptions) => ITransferBounds;
+export interface IHeldBackCodes {
+    /** A chunk that is not a `Uint8Array`. */
+    invalidChunk: string;
+    /** More bytes than the declared size. */
+    overrun: string;
+    /** Fewer bytes than the declared size. */
+    short: string;
+}
+export interface IHeldBackChecks {
+    /** Sees every non-empty chunk in order, before it is passed on. */
+    inspect?: (chunkArg: Uint8Array) => void;
+    /** Runs once exactly `size` bytes have arrived, before the last chunk is passed on; a rejection keeps it back. */
+    complete?: () => void | Promise<void>;
+}
+/**
+ * Passes the bytes of `sourceArg` on while it counts them. The last chunk is
+ * held back until the source has ended with exactly `sizeArg` bytes and
+ * `checksArg.complete` has passed, so a consumer never receives a complete
+ * body that is wrong; otherwise it throws `codesArg.overrun` as soon as the
+ * size is exceeded, `codesArg.short` when the source ends early, or what
+ * `complete` threw.
+ */
+export declare function heldBackChunks(sourceArg: AsyncIterable<Uint8Array>, sizeArg: number, codesArg: IHeldBackCodes, checksArg?: IHeldBackChecks): AsyncGenerator<Uint8Array, void, undefined>;
+/**
+ * The readable stream of one transfer's bytes. It pulls `chunksArg` with
+ * backpressure and ends `boundsArg` and calls `onEndArg` as soon as it is
+ * destroyed, also while a pull is pending: ending the bounds aborts the
+ * request, which closes its connection, and the pending pull's result is
+ * dropped. (`Readable.from` waits for a pending pull before it finishes a
+ * destroy, so a stalled body would keep its connection until the idle limit.)
+ * The stream errors with what `chunksArg` throws.
+ */
+export declare const createTransferStream: (boundsArg: ITransferBounds, chunksArg: AsyncGenerator<Uint8Array, void, undefined>, onEndArg?: () => void) => InstanceType<typeof plugins.stream.Readable>;

package/dist_ts/forgeinventory.transfer.js

@@ -0,0 +1,174 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+/** Response bytes read from an unused answer before the rest is discarded. */
+const maxDiscardedResponseBytes = 64 * 1024;
+/**
+ * Reads and drops at most 64 KiB of a response body that carries nothing the
+ * caller uses, so its connection can be reused; a longer or failing body is
+ * discarded with its connection.
+ */
+export const discardBody = async (bodyArg) => {
+    if (!bodyArg)
+        return;
+    const chunks = bodyArg[Symbol.asyncIterator]();
+    let bytes = 0;
+    try {
+        while (bytes <= maxDiscardedResponseBytes) {
+            const result = await chunks.next();
+            if (result.done)
+                return;
+            bytes += result.value.byteLength;
+        }
+    }
+    catch {
+        // The status already decided the outcome.
+    }
+    finally {
+        try {
+            await chunks.return?.();
+        }
+        catch { /* The connection is discarded. */ }
+    }
+};
+/**
+ * The bounds of one streamed transfer: the caller's signal, a wall-clock limit
+ * and an idle limit that `watch` re-arms on every chunk. Whichever ends it
+ * first decides the failure code. Every transfer must be ended with `end`.
+ */
+export const createTransferBounds = (signalArg, optionsArg) => {
+    const controller = new AbortController();
+    let reason = null;
+    const stop = (reasonArg) => {
+        reason ??= reasonArg;
+        controller.abort();
+    };
+    const abort = () => stop('request-aborted');
+    if (signalArg?.aborted)
+        abort();
+    signalArg?.addEventListener('abort', abort, { once: true });
+    const deadline = setTimeout(() => stop(optionsArg.timedOutCode), optionsArg.limitMs);
+    let idle;
+    const rearm = () => {
+        clearTimeout(idle);
+        if (!controller.signal.aborted)
+            idle = setTimeout(() => stop(optionsArg.timedOutCode), optionsArg.idleMs);
+    };
+    rearm();
+    const end = () => {
+        clearTimeout(deadline);
+        clearTimeout(idle);
+        signalArg?.removeEventListener('abort', abort);
+        stop('transfer-ended');
+    };
+    const failure = (errorArg, fallbackArg) => {
+        if (reason !== null && reason !== 'transfer-ended')
+            return new validation.ForgeInventoryError(reason);
+        return errorArg instanceof validation.ForgeInventoryError ? errorArg : new validation.ForgeInventoryError(fallbackArg);
+    };
+    return {
+        signal: controller.signal,
+        end,
+        failure,
+        touch: rearm,
+        run: async (stepArg) => {
+            if (controller.signal.aborted)
+                throw failure(undefined, 'request-aborted');
+            let onAbort;
+            const aborted = new Promise((_resolve, reject) => {
+                onAbort = () => reject(failure(undefined, 'request-aborted'));
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+            });
+            try {
+                return await Promise.race([stepArg(), aborted]);
+            }
+            finally {
+                controller.signal.removeEventListener('abort', onAbort);
+            }
+        },
+        watch: async function* (sourceArg) {
+            for await (const chunk of sourceArg) {
+                if (controller.signal.aborted)
+                    throw failure(undefined, optionsArg.failedCode);
+                rearm();
+                yield chunk;
+            }
+        },
+    };
+};
+/**
+ * Passes the bytes of `sourceArg` on while it counts them. The last chunk is
+ * held back until the source has ended with exactly `sizeArg` bytes and
+ * `checksArg.complete` has passed, so a consumer never receives a complete
+ * body that is wrong; otherwise it throws `codesArg.overrun` as soon as the
+ * size is exceeded, `codesArg.short` when the source ends early, or what
+ * `complete` threw.
+ */
+export async function* heldBackChunks(sourceArg, sizeArg, codesArg, checksArg = {}) {
+    let bytes = 0;
+    let held = null;
+    for await (const chunk of sourceArg) {
+        if (!(chunk instanceof Uint8Array))
+            throw new validation.ForgeInventoryError(codesArg.invalidChunk);
+        if (chunk.byteLength === 0)
+            continue;
+        bytes += chunk.byteLength;
+        if (bytes > sizeArg)
+            throw new validation.ForgeInventoryError(codesArg.overrun);
+        checksArg.inspect?.(chunk);
+        if (held)
+            yield held;
+        held = chunk;
+    }
+    if (bytes !== sizeArg)
+        throw new validation.ForgeInventoryError(codesArg.short);
+    await checksArg.complete?.();
+    if (held)
+        yield held;
+}
+/**
+ * The readable stream of one transfer's bytes. It pulls `chunksArg` with
+ * backpressure and ends `boundsArg` and calls `onEndArg` as soon as it is
+ * destroyed, also while a pull is pending: ending the bounds aborts the
+ * request, which closes its connection, and the pending pull's result is
+ * dropped. (`Readable.from` waits for a pending pull before it finishes a
+ * destroy, so a stalled body would keep its connection until the idle limit.)
+ * The stream errors with what `chunksArg` throws.
+ */
+export const createTransferStream = (boundsArg, chunksArg, onEndArg) => {
+    let pulling = false;
+    const stream = new plugins.stream.Readable({
+        read() {
+            if (pulling)
+                return;
+            pulling = true;
+            void (async () => {
+                try {
+                    while (!stream.destroyed) {
+                        const result = await chunksArg.next();
+                        if (stream.destroyed)
+                            return;
+                        if (result.done)
+                            return void stream.push(null);
+                        if (!stream.push(result.value))
+                            return;
+                    }
+                }
+                catch (error) {
+                    stream.destroy(error);
+                }
+                finally {
+                    pulling = false;
+                }
+            })();
+        },
+        destroy(errorArg, callbackArg) {
+            boundsArg.end();
+            onEndArg?.();
+            // Runs the generator's cleanup once a pending pull has settled; nothing waits for it.
+            chunksArg.return(undefined).catch(() => undefined);
+            callbackArg(errorArg);
+        },
+    });
+    return stream;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9yZ2VpbnZlbnRvcnkudHJhbnNmZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9mb3JnZWludmVudG9yeS50cmFuc2Zlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssVUFBVSxNQUFNLGdDQUFnQyxDQUFDO0FBRTdELDhFQUE4RTtBQUM5RSxNQUFNLHlCQUF5QixHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUM7QUFFNUM7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLFdBQVcsR0FBRyxLQUFLLEVBQUUsT0FBeUMsRUFBaUIsRUFBRTtJQUM1RixJQUFJLENBQUMsT0FBTztRQUFFLE9BQU87SUFDckIsTUFBTSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsRUFBRSxDQUFDO0lBQy9DLElBQUksS0FBSyxHQUFHLENBQUMsQ0FBQztJQUNkLElBQUksQ0FBQztRQUNILE9BQU8sS0FBSyxJQUFJLHlCQUF5QixFQUFFLENBQUM7WUFDMUMsTUFBTSxNQUFNLEdBQUcsTUFBTSxNQUFNLENBQUMsSUFBSSxFQUFFLENBQUM7WUFDbkMsSUFBSSxNQUFNLENBQUMsSUFBSTtnQkFBRSxPQUFPO1lBQ3hCLEtBQUssSUFBSSxNQUFNLENBQUMsS0FBSyxDQUFDLFVBQVUsQ0FBQztRQUNuQyxDQUFDO0lBQ0gsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLDBDQUEwQztJQUM1QyxDQUFDO1lBQVMsQ0FBQztRQUNULElBQUksQ0FBQztZQUFDLE1BQU0sTUFBTSxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUM7UUFBQyxDQUFDO1FBQUMsTUFBTSxDQUFDLENBQUMsa0NBQWtDLENBQUMsQ0FBQztJQUMvRSxDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBZ0NGOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSxvQkFBb0IsR0FBRyxDQUFDLFNBQWtDLEVB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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/codefeed",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": false,
   "description": "The @foss.global/codefeed module generates commit/activity feeds from forge providers including Gitea and GitManager.",
   "exports": {
@@ -13,7 +13,7 @@
   "devDependencies": {
     "@foss.global/forgefixtures": "^0.3.1",
     "@git.zone/tsbuild": "^6.0.2",
-    "@git.zone/tsbundle": "^3.3.0",
+    "@git.zone/tsbundle": "^3.4.0",
     "@git.zone/tsrun": "^3.0.3",
     "@git.zone/tstest": "^8.0.0",
     "@push.rocks/qenv": "^8.2.1",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@foss.global/gitmanager": "^2.4.0",
-    "@foss.global/interfaces": "^2.6.0",
+    "@foss.global/interfaces": "^2.7.0",
     "@push.rocks/lik": "^6.4.4",
     "@push.rocks/smartnpm": "^2.1.3",
     "@push.rocks/smarttime": "^5.0.1"

package/readme.md

@@ -109,6 +109,8 @@ Discovery records each repository's Gitea `id` as a canonical decimal string, an
 
 What is measured: users with their account flags, two-factor and SSH/GPG keys; organizations, members, teams, team memberships and repository grants; repositories with their flags, Git refs split into branches, tags, pull request refs and other refs, Git objects and their uncompressed bytes, LFS objects referenced anywhere in history with the bytes Gitea holds and the number it lacks, issues, pull requests, comments, reviews, review comments, labels, milestones, reactions and attachments; releases including drafts, assets and asset bytes; wiki pages; collaborators, team grants, deploy keys, webhooks, branch and tag protections and push mirrors; packages per type with versions, files and bytes; system webhooks, Actions runners, workflows, runs, artifacts and the number of Actions secrets and variables; unadopted repositories.
 
+Beyond counts, each repository keeps records of what the migration recreates. `releaseRecords` lists every release, drafts and prereleases included, sorted by numeric id: tag name, target commitish, name, body, the draft and prerelease flags, created and published times as Gitea reports them (a draft reports its creation time as published, and its tag does not exist as a Git ref yet), an author snapshot (account id and login; Gitea's placeholder for a deleted account has id `-1`) and its assets sorted by numeric id with id, storage `uuid`, name, size, download count and creation time. Gitea exposes no content digest, so a record carries none; a replaced file carries another id and uuid, and the download count moves with every download, so it never decides whether a release changed. `protections` holds the branch protection rules sorted by rule name (code-unit order) with every restriction Gitea reads back, allowlists included, and the tag protection rules sorted by numeric id with their name pattern and allowlist. `releaseRecords` is null while a release count is not complete, and `protections` is null while either protection count is not; the counts then say why.
+
 Secrets are counted, never named: the report carries no tokens, Actions secret or variable values or names, webhook secrets or mirror remote URLs. Reasons are adapter codes or fixed text, never response bodies or URLs. Gitea has no read that lists user-scoped Actions secrets; that is listed in `limitations`, since they are reissued. User-scoped webhooks, variables and runners are read as that user through the `Sudo` header.
 
 Git-level measures come from a mirror clone of every ref Gitea advertises, `refs/pull/*` included, made with `@foss.global/gitmanager` in a fresh directory below `gitWorkDir` and removed afterwards. The reader's login and token form Basic credentials; the credential reaches Git only through GIT_CONFIG_* entries in the child process environment; it is never in the URL, the command line or any file. The private CA list applies to the clone as well. The mirror's HEAD becomes the repository's `head`: the ref it names as `target` and whether it `resolves`. In a repository that is not `empty`, a HEAD that does not resolve names a missing branch, such as a default branch deleted at the source, and a `target` other than `refs/heads/<defaultBranch>` means Gitea's setting and its Git HEAD disagree. `head` is null when the mirror or its refs could not be read. A detached source HEAD is one such case: GitManager's mirror import requires a symbolic HEAD, so the clone fails with `git-mirror-failed`, and this reader never reports a `target` of null. The mirror's distinct LFS pointers, from every reachable revision, are checked against Gitea in batches of 100: an object with a download action counts as held, one answered with error 404 as missing, and any other answer makes the LFS measures `partial`. A clone that fails or exceeds `gitTimeoutMs` makes every Git and LFS measure of that repository `partial`; only the API-reported size stays complete. A clone starts only once its scratch reservation, twice the reported size plus 64 MiB, fits the free space of the file system that holds `gitWorkDir`, counting the reservations of the clones already in flight from every reader in the process. A clone that does not fit waits for them, in arrival order; one that does not fit even alone makes every Git and LFS measure of its repository `partial` with `git-workdir-too-small`, so the inventory stays incomplete. Size `gitWorkDir` for the largest repositories measured at once.
@@ -120,7 +122,7 @@ Listings page until an empty page or the `x-total-count` total is reached. A tot
 
 ### Gitea source transfer
 
-`GiteaSourceTransfer` reads one repository's Git data and LFS objects for the one-time migration, with the same reader credentials as the inventory. It never writes to Gitea: Git is read only through `git-upload-pack`, LFS only through batch `download` requests and their download actions.
+`GiteaSourceTransfer` reads one repository's Git data, LFS objects and release assets for the one-time migration, with the same reader credentials as the inventory. It never writes to Gitea: Git is read only through `git-upload-pack`, LFS only through batch `download` requests and their download actions, release assets only through GETs of their attachment.
 
 ```ts
 import { GitManager } from '@foss.global/gitmanager';
@@ -130,7 +132,8 @@ const source = new GiteaSourceTransfer({
   baseUrl: 'https://gitea.example.com', // HTTPS only
   login: readerLogin,
   token: readerToken, // read it from a file; never pass it on a command line
-  // caCertificates: [privateCaPem], gitTimeoutMs: 30 * 60 * 1000, requestTimeoutMs: 60_000, maxResponseBytes: 16 * 1024 * 1024, lfsTransferTimeoutMs: 30 * 60 * 1000,
+  // caCertificates: [privateCaPem], gitTimeoutMs: 30 * 60 * 1000, requestTimeoutMs: 60_000, maxResponseBytes: 16 * 1024 * 1024,
+  // lfsTransferTimeoutMs: 30 * 60 * 1000, releaseAssetTimeoutMs: 30 * 60 * 1000,
 });
 
 // A started GitManager rooted in the caller's own scratch space; codefeed creates no scratch roots.
@@ -147,6 +150,10 @@ if (download.status === 'missing') {
 } else {
   await pipeline(download.stream, destination); // errors unless the bytes are exactly the object
 }
+
+// A release asset as the inventory recorded it: { id, uuid, name, size } from releaseRecords[].assets[].
+const asset = await source.downloadReleaseAsset({ owner: 'team', name: 'app', id: '11' }, release.id, recordedAsset, { signal });
+await pipeline(asset.stream, destination); // errors unless exactly `size` bytes of the recorded asset arrived
 ```
 
 A source repository is named by `owner`, `name` and its Gitea repository `id`, a canonical decimal string as the inventory records it; anything else rejects with `invalid-repository`. Git and the LFS API reach a repository only by name, and a name can move to another repository between two reads: Gitea answers a renamed repository's old path with a redirect, and a new repository can take the old name. Every source read is therefore bracketed by an identity read of `GET /api/v1/repositories/{id}`, which must still name `owner/name` (compared case-insensitively, as Gitea does). A repository that was renamed, or whose name now belongs to another repository, rejects with `repository-identity-changed`; a deleted one rejects with `http-404`. A transfer that fails is explained the same way when the identity read shows one of those two causes.
@@ -157,6 +164,8 @@ While the import runs, GitManager holds `target`: writes to it, such as `initBar
 
 `downloadLfsObject` sends one batch `download` request with the reader's Basic credentials, then a GET of the action's href with the action's headers only, and then reads the identity; when that read rejects, the stream is destroyed and the call rejects with its code. A missing object resolves as `{ status: 'missing' }`, so a caller can list the missing oids; any other object error rejects with `lfs-object-error-<code>`, such as `lfs-object-error-422` for a size Gitea disagrees with. The returned stream never holds the whole object: it counts and hashes the bytes as they pass and holds back the last chunk until the body ended with exactly `size` bytes whose SHA-256 is `oid`. Otherwise it errors with `lfs-size-overrun`, `lfs-short-body` or `lfs-digest-mismatch`; a `content-length` other than `size` rejects with `lfs-size-mismatch` before streaming. An abort errors it with `request-aborted`, a transfer longer than `lfsTransferTimeoutMs` or idle for `requestTimeoutMs` with `lfs-transfer-timed-out`. Destroying the stream ends the download.
 
+`downloadReleaseAsset(repository, releaseId, asset)` takes the release id and the asset's `id`, `uuid`, `name` and `size` as the inventory recorded them; anything else rejects with `release-asset-invalid` before any request. It reads the repository by id, then `GET /api/v1/repos/{owner}/{name}/releases/{releaseId}`, which must still carry an asset with the same id, uuid, name and size; otherwise it rejects with `release-asset-identity-changed` (a deleted release with `http-404`). The download count is not compared. It then GETs `{baseUrl}/attachments/{uuid}` with the reader's `token` authorization: no redirect is followed and no range is asked for, so any answer but 200 rejects, with `http-<status>` or, for a refused redirect, `release-asset-download-failed`, and a `content-length` other than `size` rejects with `release-asset-size-mismatch`. No digest is computed while the bytes stream: the stream counts them and holds back the last chunk until exactly `size` bytes have arrived and both identity reads have passed once more, so a consumer never receives a complete asset that is short, long or no longer the recorded one. Otherwise it errors with `release-asset-size-overrun`, `release-asset-short-body`, `repository-identity-changed` or `release-asset-identity-changed`. Content digests come from the content itself, such as a publisher's `SHA256SUMS` asset or the importer's own hash. An abort errors it with `request-aborted`, a download longer than `releaseAssetTimeoutMs` (default 30 minutes, at most six hours) or idle for `requestTimeoutMs` with `release-asset-transfer-timed-out`. A failed request is explained by the identity reads as for `downloadLfsObject`. Destroying the stream ends the download; the download's connections close with the stream. The stream fails internally with `release-asset-transfer-failed` when body bytes still arrive after the download has ended, which happens only once the stream is destroyed, so a reader of the stream does not see it.
+
 ### Git LFS batch client
 
 `LfsBatchClient` is a provider-neutral Git LFS batch API client with the `basic` transfer adapter, bound to one LFS endpoint and its credential. `GiteaSourceTransfer` downloads through it; the migration uploads to the native Git service through it.
@@ -347,7 +356,7 @@ The repo contains:
 - A mocked pagination test that does not require network.
 - A GitManager provider mapping test using a local test stub.
 - A default-deny GitManager public-client mapping test using a local test stub.
-- A mocked `GiteaSourceInventory` test, Git-level `GiteaSourceInventory` and `GiteaSourceTransfer` tests against a local HTTPS Git, LFS batch and REST server (needs `openssl` and `git http-backend`), and an opt-in one against a Docker Gitea from `@foss.global/forgefixtures`, run with `FORGEFIXTURES=gitea pnpm test` (Docker required).
+- A mocked `GiteaSourceInventory` test, Git-level `GiteaSourceInventory` and `GiteaSourceTransfer` tests and a release asset download test against a local HTTPS Git, LFS batch, REST and attachment server (needs `openssl` and `git http-backend`), and an opt-in one against a Docker Gitea from `@foss.global/forgefixtures`, run with `FORGEFIXTURES=gitea pnpm test` (Docker required).
 - An `LfsBatchClient` test against local loopback LFS servers over HTTP and over HTTPS with a private CA.
 
 Run tests:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/codefeed',
-  version: '4.1.0',
+  version: '4.2.0',
   description: 'The @foss.global/codefeed module generates commit/activity feeds from forge providers including Gitea and GitManager.'
 }

package/ts/classes.giteasourceinventory.ts

@@ -13,6 +13,9 @@ type IInstance = plugins.fossInterfaces.data.IForgeSourceInstanceInventory;
 type TOwner = plugins.fossInterfaces.data.TForgeSourceOwnerInventory;
 type IRepository = plugins.fossInterfaces.data.IForgeSourceRepositoryInventory;
 type IPackageTypeCounts = plugins.fossInterfaces.data.IForgeSourcePackageTypeCounts;
+type IRelease = plugins.fossInterfaces.data.IForgeSourceRelease;
+type IBranchProtection = plugins.fossInterfaces.data.IForgeSourceBranchProtection;
+type ITagProtection = plugins.fossInterfaces.data.IForgeSourceTagProtection;
 type IInventory = plugins.fossInterfaces.data.IForgeSourceInventory;
 
 export interface IGiteaSourceInventoryOptions {
@@ -119,6 +122,35 @@ const requiredString = (valueArg: unknown): string => {
   return value;
 };
 
+/** A string the forge may leave empty, such as a release body. */
+const text = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string') throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg;
+};
+
+/** A list of names; Gitea answers an empty one as `null`. */
+const texts = (valueArg: unknown): string[] => {
+  if (valueArg === null) return [];
+  if (!Array.isArray(valueArg)) throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg.map(text);
+};
+
+/** A signed account id; Gitea's placeholder for a deleted account is -1. */
+const accountId = (valueArg: unknown): string => {
+  if (typeof valueArg === 'number' && Number.isSafeInteger(valueArg)) return String(valueArg);
+  throw new validation.ForgeInventoryError('invalid-or-imprecise-integer');
+};
+
+/** An RFC 3339 time as the forge reports it. */
+const requiredTimestamp = (valueArg: unknown): string => {
+  const value = validation.timestamp(valueArg);
+  if (value === null) throw new validation.ForgeInventoryError('invalid-timestamp');
+  return value;
+};
+
+/** Orders canonical nonnegative decimal strings numerically. */
+const compareDecimal = (aArg: string, bArg: string): number => aArg.length - bArg.length || compareText(aArg, bArg);
+
 /** One provider path segment, as an owner or repository name. */
 const segment = (valueArg: unknown): string => {
   const segments = validation.segments(valueArg);
@@ -142,6 +174,83 @@ const assets = (valueArg: unknown): { count: bigint; bytes: bigint } => {
   }), { count: 0n, bytes: 0n });
 };
 
+/** A release as Gitea reads it, drafts included, with its assets by numeric id. */
+const releaseRecord = (itemArg: unknown): IRelease => {
+  const item = validation.record(itemArg);
+  const author = validation.record(item.author);
+  const itemAssets = item.assets ?? [];
+  if (!Array.isArray(itemAssets)) throw new validation.ForgeInventoryError('invalid-assets');
+  return {
+    id: validation.decimal(item.id),
+    tagName: requiredString(item.tag_name),
+    targetCommitish: text(item.target_commitish),
+    name: text(item.name),
+    body: text(item.body),
+    draft: requiredBoolean(item.draft),
+    prerelease: requiredBoolean(item.prerelease),
+    createdAt: requiredTimestamp(item.created_at),
+    publishedAt: requiredTimestamp(item.published_at),
+    author: { id: accountId(author.id), login: requiredString(author.login) },
+    assets: itemAssets.map((assetArg: unknown) => {
+      const asset = validation.record(assetArg);
+      return {
+        id: validation.decimal(asset.id),
+        uuid: requiredString(asset.uuid),
+        name: requiredString(asset.name),
+        size: validation.decimal(asset.size),
+        downloadCount: validation.decimal(asset.download_count),
+        createdAt: requiredTimestamp(asset.created_at),
+      };
+    }).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+  };
+};
+
+const allowlist = (usernamesArg: unknown, teamsArg: unknown) => ({ usernames: texts(usernamesArg), teams: texts(teamsArg) });
+
+/** A branch protection rule with every restriction Gitea reads back. */
+const branchProtection = (itemArg: unknown): IBranchProtection => {
+  const item = validation.record(itemArg);
+  return {
+    ruleName: requiredString(item.rule_name),
+    priority: validation.decimal(item.priority),
+    enablePush: requiredBoolean(item.enable_push),
+    enablePushAllowlist: requiredBoolean(item.enable_push_whitelist),
+    pushAllowlist: allowlist(item.push_whitelist_usernames, item.push_whitelist_teams),
+    pushAllowlistDeployKeys: requiredBoolean(item.push_whitelist_deploy_keys),
+    enableForcePush: requiredBoolean(item.enable_force_push),
+    enableForcePushAllowlist: requiredBoolean(item.enable_force_push_allowlist),
+    forcePushAllowlist: allowlist(item.force_push_allowlist_usernames, item.force_push_allowlist_teams),
+    forcePushAllowlistDeployKeys: requiredBoolean(item.force_push_allowlist_deploy_keys),
+    enableMergeAllowlist: requiredBoolean(item.enable_merge_whitelist),
+    mergeAllowlist: allowlist(item.merge_whitelist_usernames, item.merge_whitelist_teams),
+    enableBypassAllowlist: requiredBoolean(item.enable_bypass_allowlist),
+    bypassAllowlist: allowlist(item.bypass_allowlist_usernames, item.bypass_allowlist_teams),
+    enableStatusCheck: requiredBoolean(item.enable_status_check),
+    statusCheckContexts: texts(item.status_check_contexts),
+    requiredApprovals: validation.decimal(item.required_approvals),
+    enableApprovalsAllowlist: requiredBoolean(item.enable_approvals_whitelist),
+    approvalsAllowlist: allowlist(item.approvals_whitelist_username, item.approvals_whitelist_teams),
+    blockOnRejectedReviews: requiredBoolean(item.block_on_rejected_reviews),
+    blockOnOfficialReviewRequests: requiredBoolean(item.block_on_official_review_requests),
+    blockOnOutdatedBranch: requiredBoolean(item.block_on_outdated_branch),
+    dismissStaleApprovals: requiredBoolean(item.dismiss_stale_approvals),
+    ignoreStaleApprovals: requiredBoolean(item.ignore_stale_approvals),
+    blockAdminMergeOverride: requiredBoolean(item.block_admin_merge_override),
+    requireSignedCommits: requiredBoolean(item.require_signed_commits),
+    protectedFilePatterns: text(item.protected_file_patterns),
+    unprotectedFilePatterns: text(item.unprotected_file_patterns),
+  };
+};
+
+const tagProtection = (itemArg: unknown): ITagProtection => {
+  const item = validation.record(itemArg);
+  return {
+    id: validation.decimal(item.id),
+    namePattern: requiredString(item.name_pattern),
+    allowlist: allowlist(item.whitelist_usernames, item.whitelist_teams),
+  };
+};
+
 /** A `{ <rows>, total_count }` envelope whose rows must match its total. */
 const countedEnvelope = (bodyArg: unknown, rowsKeyArg: string): { rows: unknown[]; failure: string | null } => {
   const body = validation.record(bodyArg);
@@ -516,6 +625,8 @@ export class GiteaSourceInventory {
     const parent = item.parent === undefined || item.parent === null ? null : requiredString(validation.record(item.parent).full_name);
     if (fork !== (parent !== null)) throw new validation.ForgeInventoryError('inconsistent-fork-parent');
     const options = { signal: signalArg };
+    const branchRules = await this.#unpaged(`${path}/branch_protections`, options);
+    const tagRules = await this.#unpaged(`${path}/tag_protections`, options);
     return {
       owner: ownerArg,
       name: nameArg,
@@ -533,17 +644,21 @@ export class GiteaSourceInventory {
       ...await this.#git(ownerArg, nameArg, item, signalArg),
       collaboration: await this.#collaboration(path, features, signalArg),
       // Releases stay readable while their unit is disabled; a disabled wiki answers 404.
-      releases: await this.#releases(path, signalArg),
+      ...await this.#releases(path, signalArg),
       wikiPages: features.wiki ? await this.#count(`${path}/wiki/pages`, { ...options, missingIsEmpty: true }) : unitDisabled('wiki'),
       access: {
         collaborators: await this.#count(`${path}/collaborators`, options),
         teams: await this.#repositoryTeams(path, options),
         deployKeys: await this.#count(`${path}/keys`, options),
         webhooks: await this.#count(`${path}/hooks`, options),
-        branchProtections: await this.#unpagedCount(`${path}/branch_protections`, options),
-        tagProtections: await this.#unpagedCount(`${path}/tag_protections`, options),
+        branchProtections: branchRules.measure,
+        tagProtections: tagRules.measure,
         pushMirrors: await this.#count(`${path}/push_mirrors`, options),
       },
+      protections: branchRules.rows === null || tagRules.rows === null ? null : {
+        branches: branchRules.rows.map(branchProtection).sort((aArg, bArg) => compareText(aArg.ruleName, bArg.ruleName)),
+        tags: tagRules.rows.map(tagProtection).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+      },
       actions: await this.#actions(path, empty, signalArg),
     };
   }
@@ -655,7 +770,8 @@ export class GiteaSourceInventory {
     };
   }
 
-  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<IRepository['releases']> {
+  /** The release counts, and the release records once the listing is complete. */
+  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<Pick<IRepository, 'releases' | 'releaseRecords'>> {
     // An administrator's listing includes drafts.
     const releases = await this.#list(`${pathArg}/releases`, { signal: signalArg });
     let drafts = 0n;
@@ -667,10 +783,15 @@ export class GiteaSourceInventory {
       releaseAssets = { count: releaseAssets.count + itemAssets.count, bytes: releaseAssets.bytes + itemAssets.bytes };
     }
     return {
-      releases: listingMeasure(releases),
-      drafts: listingMeasure(releases, drafts),
-      assets: listingMeasure(releases, releaseAssets.count),
-      assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      releases: {
+        releases: listingMeasure(releases),
+        drafts: listingMeasure(releases, drafts),
+        assets: listingMeasure(releases, releaseAssets.count),
+        assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      },
+      releaseRecords: releases.failure === null
+        ? releases.items.map(releaseRecord).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id))
+        : null,
     };
   }
 
@@ -725,13 +846,18 @@ export class GiteaSourceInventory {
   }
 
   async #unpagedCount(pathArg: string, optionsArg: IListOptions): Promise<TMeasure> {
+    return (await this.#unpaged(pathArg, optionsArg)).measure;
+  }
+
+  /** A listing Gitea does not page: its count, and its rows when the read succeeded. */
+  async #unpaged(pathArg: string, optionsArg: IListOptions): Promise<{ measure: TMeasure; rows: unknown[] | null }> {
     try {
       const response = (await this.#get(pathArg, optionsArg)).body;
       const body = response === null && optionsArg.nullIsEmpty ? [] : response;
       if (!Array.isArray(body)) throw new validation.ForgeInventoryError('invalid-page');
-      return complete(body.length);
+      return { measure: complete(body.length), rows: body };
     } catch (error) {
-      return partial(0, reason(error));
+      return { measure: partial(0, reason(error)), rows: null };
     }
   }