@foss.global/interfaces
Shared TypeScript DTOs and TypedRequest contracts for the foss.global Git platform ecosystem.
This package intentionally contains contracts only. Runtime forge adapters belong in @foss.global/codefeed, and the Git storage/protocol engine belongs in @foss.global/gitmanager.
Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.
Install
pnpm add @foss.global/interfaces
Usage
import type { data, requests } from '@foss.global/interfaces';
const repo: data.IPublicRepo = {
id: 1,
org: 'foss.global',
name: 'interfaces',
slug: 'foss.global/interfaces',
orgAvatarUrl: '',
description: 'Shared contracts',
language: 'TypeScript',
htmlUrl: 'https://code.foss.global/foss.global/interfaces',
cloneUrl: 'https://code.foss.global/foss.global/interfaces.git',
sshUrl: 'ssh://git@code.foss.global:29419/foss.global/interfaces.git',
starsCount: 0,
forksCount: 0,
watchersCount: 0,
openIssuesCount: 0,
openPrCount: 0,
releaseCount: 0,
size: 0,
defaultBranch: 'main',
updatedAt: new Date().toISOString(),
createdAt: new Date().toISOString(),
archived: false,
topics: [],
};
type PublicOverviewRequest = requests.IReq_PublicOverview;
Archived pull request contracts
IPublicArchivedPullRequest is a pull request archived from the source forge,
read-only, with its whole conversation embedded: comments, and reviews
each with its own comments on the diff (diffHunk as recorded; an archive
computes no diff). Every field is as the source recorded it: state with
merged, the merge fields, base, head (with the head repository),
mergeBase, draft, locked, pinOrder, dueDate, and labels and
milestone as snapshots. Each person is an IPublicArchivedPullRequestAccount:
the source account's id and login, never an email, and user, the native
user it resolves to or null. A review's state is the source's value
(APPROVED, COMMENT, REQUEST_CHANGES, REQUEST_REVIEW); a pending review
is never archived. It extends IPublicArchivedPullRequestSummary, the same
fields without the conversation and with commentCount and reviewCount.
IReq_PublicRepo's response carries the optional archivedPullRequests
(summaries, like every list of that response) and
selectedArchivedPullRequest (the archived pull request pullRequestNumber
names when no native one holds it, with its conversation); both are absent
from servers that predate the archive. IPublicPullRequest stays the
native pull request alone.
Repository release API contracts
The code host's native release API, /api/v1/repositories/:org/:repo/releases,
as JSON on the wire. IRepositoryReleaseCreateRequest (POST, answered 201)
names the tag and optionally name (the tag name by default), body,
prerelease and draft; the code host resolves the tag's target object.
IRepositoryReleaseUpdateRequest (PUT …/releases/:tag, answered 200) changes
any of the four and leaves an omitted one as it is; draft: false publishes.
Both bodies are closed and no field is nullable. Answers are envelopes:
IRepositoryReleaseListResponse ({ releases }, drafts included),
IRepositoryReleaseResponse ({ release }) and
IRepositoryReleaseAssetResponse ({ asset }, for
POST …/releases/:tag/assets/:name). An IRepositoryRelease carries its
releaseId, targetObjectId, author (an IPublicUser), ready assets and
ISO 8601 times; publishedAt is null until the first publication and stays set
when a release turns back into a draft. An IRepositoryReleaseAsset always
carries its verified sha256 and sizeBytes. IPublicRelease stays the
public website's read model.
Runner and CI contracts
Runner protocol v1 is exposed through runnerProtocolVersion. The package root and the data namespace both export the complete runner and CI DTO set:
import {
runnerProtocolVersion,
type IClaimJobResponse,
type ICiEnqueueJobRequest,
type IRegisterRunnerRequest,
} from '@foss.global/interfaces';
const registration: IRegisterRunnerRequest = {
registrationRequestId: 'registration-1',
protocolVersion: runnerProtocolVersion,
runnerVersion: '0.1.0',
name: 'linux-amd64-1',
labels: ['linux', 'amd64'],
capabilities: {
executor: 'oci',
runtime: 'docker',
networks: ['none', 'bridge'],
sourceArchives: ['tar.gz'],
artifacts: false,
caches: false,
serviceContainers: false,
},
};
const enqueue: ICiEnqueueJobRequest = {
idempotencyKey: 'build-main-1',
tenantId: 'foss.global',
repositoryId: 'foss.global/interfaces',
requiredLabels: ['linux', 'amd64'],
job: {
image: 'node:24',
command: ['pnpm', 'test'],
network: 'none',
},
};
type ClaimedJob = IClaimJobResponse;
The runner lifecycle contracts cover registration, sessions, runner and job heartbeats, claim/lease identity, fencing tokens, ordered log chunks, completion, abandonment, and recovery. The CI control-plane contracts cover job enqueue and summaries, log pages, cancellation, and runner drain state.
Protocol v1 describes OCI execution with Docker or Podman and tar.gz source archives. Artifacts, caches, and service containers are explicitly unsupported in the v1 capability shape. Supported job network modes are none and bridge; the execution service remains responsible for enforcing the advertised capability.
GitManager ref inventory contracts
IGitManagerRefRequest, IGitManagerRef, and TGitManagerRefInventoryResult
describe a complete, paginated ref inventory. Without prefixes, every ref
under refs/ is listed, including notes, pull, keep-around, and
provider-internal namespaces. HEAD is reported separately in head. Annotated
tags carry their fully peeled object. Symbolic refs carry their target ref
name; a symbolic ref whose target does not resolve is still listed, with a null
objectId and objectType.
import type {
IGitManagerRef,
IGitManagerRefRequest,
TGitManagerRefInventoryResult,
} from '@foss.global/interfaces';
declare function listRefs(
request: IGitManagerRefRequest,
): Promise<TGitManagerRefInventoryResult>;
const collectRefs = async (): Promise<IGitManagerRef[]> => {
const refs: IGitManagerRef[] = [];
let cursor: string | undefined;
while (true) {
const result = await listRefs({ org: 'foss.global', repo: 'interfaces', cursor });
if (result.status === 'stale') {
refs.length = 0;
cursor = undefined;
continue;
}
refs.push(...result.refs);
if (result.pagination.status === 'exhausted') {
return refs;
}
cursor = result.pagination.cursor;
}
};
// A complete ref name as the only prefix is an exact lookup.
const main = await listRefs({
org: 'foss.global',
repo: 'interfaces',
prefixes: ['refs/heads/main'],
});
Prefixes match whole path components, so refs/heads/ma does not select
refs/heads/main. Overlapping prefixes select their de-duplicated union, and
an empty prefixes array is rejected as invalid. Pages are sorted by ref name
in byte order and each carries inventoryDigest, the SHA-256 of the complete
selection defined on IGitManagerRefInventoryPage. A cursor is opaque and
bound to the repository, the prefix set, and that digest. When the selected
refs or HEAD change between pages, the next call returns status: 'stale'
instead of a page that would mix two states; the caller restarts without a
cursor. A cursor is a transport continuation, not a durable replication
checkpoint.
GitManager remote transfer and size contracts
IGitManagerImportMirrorRequest and IGitManagerRefreshMirrorRequest take
IGitManagerRemoteTransferOptions: an optional credential
(TGitManagerRemoteCredential, HTTP Basic), optional caCertificates (PEM,
used as Git's CA bundle for that transfer) and an optional timeoutMs
(default 120000, at most 21600000). A credential reaches Git only through the
Git process environment as an Authorization header, so it never appears in
the remote URL, on a command line, in the repository's Git config, or in an
error. It requires an https remote without user information, and Git does
not follow redirects while it carries one. A refresh reuses the mirror's stored
remote URL. Import and refresh never take an SSH key: it belongs to the push
alone (TGitManagerAtomicPushCredential).
IGitManagerRepositorySize measures a repository's object database:
objectCount distinct objects, objectBytes (their uncompressed sizes, which
do not depend on packing) and storageBytes (every file of the object
database, which does).
GitManager atomic push and default branch contracts
IGitManagerAtomicPushRequest pushes IGitManagerAtomicPushRefUpdates from a
managed repository to remoteUrl as one transaction: the remote applies every
update or none, and a remote that does not advertise the atomic capability is
refused rather than pushed to ref by ref. Every update is leased:
expectedOldObjectId is the object the remote ref must point at now (null to
create a ref that must not exist), and newObjectId is the object to set (null
to delete). The URL is used for that push only; it must be https, or http to
a loopback host. The transfer options are those of importMirror, except that
a push credential is also accepted for loopback http.
A push also goes over SSH: its credential is a
TGitManagerAtomicPushCredential, the transfer credentials plus
IGitManagerRemoteSshKeyCredential (kind: 'sshKey', an unencrypted
privateKey and the remote's hostKey). The host key is required and pinned:
one OpenSSH key line, <type> <base64>, with no host name or comment, and every
other host key is refused. An SSH key goes with an
ssh://<user>@<host>[:<port>]/<path> URL and only with one; a path outside
[A-Za-z0-9._/-] is refused, never escaped. caCertificates with an sshKey
credential are refused.
TGitManagerRemoteCredential, which import and refresh share, has no SSH
member.
import type { IGitManagerAtomicPushRequest } from '@foss.global/interfaces';
const push: IGitManagerAtomicPushRequest = {
org: 'freeze',
repo: 'canary',
remoteUrl: 'ssh://git@code.foss.global:29419/freeze-canary/probe.git',
credential: { kind: 'sshKey', privateKey, hostKey: 'ssh-ed25519 AAAAC3Nz...' },
updates: [{ ref: 'refs/heads/canary', expectedOldObjectId: null, newObjectId }],
};
An https push may set connectAddress, an IP literal (IPv6 without
brackets) that the push connects to directly, never through a proxy, instead
of the address DNS gives for the URL's host, on the URL's port. The Host header
and the TLS server name stay the URL's host, and the certificate is verified
against that name, so one name can be pushed to through a second network path.
It is refused with an sshKey credential, a URL that is not https, a URL
whose host is an IP literal, and an address that is not an IP literal. Only the
push takes it: IGitManagerRemoteTransferOptions, which import and refresh
share, has no connectAddress.
const directPush: IGitManagerAtomicPushRequest = {
org: 'freeze',
repo: 'canary',
remoteUrl: 'https://code.foss.global/freeze-canary/probe.git',
connectAddress: '192.0.2.10',
credential: { kind: 'basic', username: 'freeze-canary-probe', password },
updates: [{ ref: 'refs/heads/canary', expectedOldObjectId: null, newObjectId }],
};
IGitManagerAtomicPushResult is applied when every ref is ok and
rejected when no ref changed. Each IGitManagerAtomicPushRefResult is ok,
stale (the lease failed) or rejected (a hook, ref protection, or another
ref of the same push failed), with the remote's reason as message. Every ref
that is not ok also carries a classified TGitManagerAtomicPushRefReason:
stale-lease, atomic-collateral (refused only because another ref failed),
transaction-failed (the remote could not commit, typically a concurrent
change; read the remote back), hook-declined, non-fast-forward,
local-rejected or remote-rejected for any other refusal.
Every result carries remoteMessages, the remote's remote: lines in order
(a hook's output, for example) without the prefix and trailing padding, for
https and ssh alike, and empty when the remote sent none. The engine bounds
the list in count and bytes and says so in its last element when it cut it;
credentials are redacted as in message. It is free text: a consumer may look
for a value it chose, such as a freeze nonce, and never branches on anything
else.
IGitManagerSetDefaultBranchRequest points a repository's HEAD at an existing
branch, named as in IGitManagerRepositoryInfo.defaultBranch. With
allowUnborn: true the branch may not exist yet: HEAD then names it unborn
until a push creates it, so that one atomic push can create the new default
branch and delete the old one, which Git refuses while HEAD names the old one.
An IGitManagerProtectedRefViolation names a ref update that the protected ref
rules or a held tag refuse and the TGitManagerProtectedRefViolationRule it
breaks: create, delete, force-push (the old object is not an ancestor of
the new one), not-a-commit or held-tag (a release holds the tag at its
stored object, and the update's new object is not that object: moving the tag,
deleting it, or creating a missing held tag at another object; pointing it at
exactly the held object is allowed, whatever the old object was). GitManager
decides it with the same check its pre-receive hook enforces.
Origin contracts
TOriginState records where a native entity came from: native, imported
with an IOriginRef, or unknown, which never means native. An IOriginRef
names the source by the operator-minted forge connection instanceId, the
entityKind (repository), the source entityId (a Gitea repository's
decimal ID) and parentId (null for repositories, whose Gitea IDs are unique
per instance). It carries no URLs, paths, configuration or run IDs, digests, or
authority.
Forge inventory contracts
IForgeInventoryReport, IForgeInventoryPage<TItem>, IForgeInventoryNamespace,
IForgeInventoryRepository and IForgeInventoryIssue describe operator inventory observations. They
are exported from both the package root and data. This package supplies types;
it does not scan a forge or validate network responses.
Stable provider identifiers are opaque strings qualified by instance and ID namespace. Mutable paths remain separate segment arrays, preserving GitLab subgroups and literal hyphens. A source without a stable identifier reports an unresolved identity. URLs must be credential-free, and inventory responses need operator authorization rather than anonymous public exposure.
Issue observations separate the provider row ID from its repository-local
number (GitLab iid) and retain the repository identity. They preserve empty
body text, unknown metadata, open/closed state, provider issue classification,
confidentiality, reported author identity and provider content timestamps.
The reported author does not prove original attribution for previously imported
issues. Comments, labels, milestones, assignees, attachments and history require
their own inventory and preservation work; this metadata DTO does not claim
that those collections or external writes are implemented.
Every canonical entity class has an explicit capability and collection result,
including classes not inspected or unavailable. Additional provider features
have their own entries. enumerated means the selected collection was exhausted
for its recorded visibility scope; a public or caller-visible live scan does
not establish a complete frozen migration inventory. Page continuation,
exhaustion, and interrupted enumeration have distinct discriminated shapes.
Counts and byte quantities use nonnegative decimal strings to avoid JSON integer precision loss. Unknown size differs from zero, and estimated repository storage size is not the size of a future Git push. Runtime adapters must validate values, scope consistency, capability/result agreement, cursor binding, diagnostics, and authorization. These DTOs do not establish replication authority, historical import fidelity, checksummed manifests, or durable recovery checkpoints.
Forge source inventory contracts
IForgeSourceInventoryReport is the authenticated, read-only measurement of a
source forge before its one-time migration, read with a site administrator's
token. It counts users, organizations, teams, memberships, keys, packages by
type (and, when a run selects them, records each package and each repository's issues and pull requests), and per repository the Git refs and objects, LFS objects, issues, pull requests,
comments, reviews, reactions, attachments, releases (drafts included) with
asset bytes, wiki pages, access settings, webhooks, push mirrors, Actions
settings, and the Actions runs and artifacts that are archived rather than
migrated.
Every count is a TForgeSourceMeasure: complete with a decimal-string value,
partial with the value observed before a retryable failure, or notMeasured
when no read was attempted. inventoryComplete is true only when discovery
finished and no measure is partial or not measured; incompleteReasons lists
why not. limitations names source data the provider exposes to no
administrator read and that is reissued rather than migrated, such as Gitea's
user-scoped Actions secrets; everything readable is a measure instead.
Reasons are sanitized text, never raw response bodies or URLs.
Git counts other than the forge-reported size, and LFS counts, are read at the
Git level from a mirror clone of every advertised ref: refs by namespace,
distinct objects and their uncompressed bytes, and the LFS objects that
pointers in any reachable revision reference. LFS objects are checked through
the forge's LFS batch API and split into held objects with their bytes and
missingObjects, which cannot be migrated.
The same mirror records the repository's head, an IForgeSourceRepositoryHead:
the ref HEAD names as target (null when HEAD is detached or not symbolic) and
whether it resolves. An empty repository's HEAD is unborn and does not
resolve; in any other repository a HEAD that does not resolve names a missing
branch, such as a default branch deleted at the source, and an import's HEAD
diverges from the source at apply time until the source names an existing
branch. A target that differs from the API's defaultBranch shows that the
forge's setting and its Git HEAD disagree. head is null when the mirror was
not measured and absent in reports from generators that predate it.
The same mirror records refDigests, an IForgeSourceRefDigests with one
IForgeSourceRefNamespaceDigest each for refs/heads/, refs/tags/ and
refs/notes/: GitManager's inventoryDigest over HEAD and the refs under
that prefix, as an IGitManagerRefInventoryPage defines it, and the
refCount of that selection. The digest does not cover the repository's name,
so a consumer compares it with the digest of the same prefix in any other
GitManager repository to prove both hold the same refs. Pull request refs have
no digest. git.otherRefs includes the notes refs, so
git.otherRefs - notes.refCount refs belong to no digested namespace.
refDigests is null when the mirror was not measured or any digest could not
be read, never partial, and absent in reports from generators that predate it.
A repository records its description verbatim as the forge's API reports
it, without trimming or normalising; '' means the source repository has no
description. It is never null. It is absent in reports from generators that
predate it, and a consumer treats an absent description as unread, never as
''.
Beside its counts, a repository records each release as a
TForgeSourceRelease in releaseRecords, drafts included: the source ids,
tag, target, name, body, flags, the forge's creation and publication times, an
IForgeSourceReleaseAuthor snapshot (the source account's id and login, never
a native user) and its IForgeSourceReleaseAssets with their storage uuid,
name as stored, size and download count. The forge exposes no asset digest, so
none is recorded; a consumer verifies content itself. The download count moves
with every download and never decides whether a release changed.
A release is an IForgeSourcePublishedRelease (draft: false), whose
publishedAt is always a time, or an IForgeSourceDraftRelease
(draft: true), whose publishedAt is null when the forge reports none, as
Gitea 28 does for every draft. Both times are the forge's values verbatim:
Gitea 28 reports the date of the commit a release points at as createdAt.
protections records, as read, the branch and tag protection rules that
access counts: an IForgeSourceBranchProtection keeps the rule name (an exact
name or a glob), whether anyone may push or force-push, every allowlist with
its switch, and the review, status check, signing and file pattern
restrictions; an IForgeSourceTagProtection keeps its name pattern and
allowlist. Whether a rule can be enforced natively is the consumer's verdict.
Releases, assets and tag rules sort by numeric id, branch rules by name in
code-unit order. Both are null when their counts are not complete and absent
in reports from generators that predate them.
Owners are a TForgeSourceOwnerInventory union: an organization carries its
members, teams, team memberships and repository grants, labels and Actions
secret count; a user carries its account flags and SSH and GPG key counts.
Both carry repositories, webhooks, Actions variables, runners and packages by
type. totals.owners sums the owner-level counts; the repository-shaped totals
sum repositories only.
Beside their counts, owners and repositories record who may access what, as the forge reports it and without a verdict:
- A user's
userRecordis anIForgeSourceUserRecord: id, login, the active, administrator, restricted and sign-in-prohibited flags, profile visibility, and every SSH key as anIForgeSourceUserSshKey(id, title, fingerprint, OpenSSH key type and public key), andfullName, the forge's full name verbatim (''when unset). It is null whensshKeysis not complete;fullNameis absent in reports from generators that predate it. - An organization's
teamRecordsareIForgeSourceTeamRecords: id, name,permission,unitsMap(null when the forge reports none), whether the team includes all repositories and may create them, its visibility, its members by id and login, and the ids of its repositories. Gitea 28 reports a granular team aspermissionnonewith a units map, and theOwnersteam asownerwith a units map, so a consumer recognisesOwnersbypermissionalone. They are null whenteams,teamMembershipsorteamRepositoryGrantsis not complete. - An organization's
profileis anIForgeSourceOrganizationProfile: itsfullName,description,websiteandlocation, each verbatim and''when unset.websiteis not validated, because a value a forge's web form stored may not be a valid URL. The organization's email (personal data), its avatar URL (hosted by the forge, so it dies with it; a consumer acknowledges the avatar as not migrated), Gitea'srepo_admin_change_team_access(the native forge has no teams) and its visibility (already on the owner) are deliberately not recorded. It is absent in reports from generators that predate it. - A repository's
accessRecordsis anIForgeSourceRepositoryAccess: its collaborators with theeffectivePermissionthe forge reports for each, its SSH deploy keys (binding id, shared key row id, title, fingerprint, public key and mode) and its deploy tokens (id, title and mode only). The effective permission is the strongest of the collaboration, teams, ownership, site administration and public access, never the collaboration's own mode, which no REST endpoint reports. A deploy token is a credential that is reissued, so neither the token nor the masked form the forge reports in its place is recorded. It is null whenaccess.collaborators,access.deployKeysoraccess.deployTokensis not complete; a producer reportsaccess.collaboratorscomplete only when it also read every collaborator's effective permission.
Records sort by numeric id (collaborators by user id) and access modes are a
TForgeSourceAccessMode. All three are absent in reports from generators that
predate them. access.deployTokens counts deploy tokens; when it is present,
access.deployKeys counts SSH deploy keys only, while a generator that
predates it counted the forge's whole deploy key list, which on Gitea 28
includes deploy tokens.
A repository's collaboration.byKind, an
IForgeSourceCollaborationKindCounts, splits issues from pull requests:
issueComments, issueReactions, issueAttachments and
issueAttachmentBytes beside their pull request twins, and pull requests by
state (openPullRequests, closedPullRequests for those closed without a
merge, mergedPullRequests, which sum to pullRequests). Each mixed measure
is the sum of its two kinds, so a disabled pull request unit leaves every
issue measure measured. Every member of byKind is required, so the split is
whole or absent; it is absent in reports from generators that predate it.
collaboration.projects counts the repository's project boards and an
owner's projects its own boards, both absent in reports from generators that
predate them.
Issues and pull requests are recorded one collaboration unit per repository when a run selects the collaboration class, so their bodies never compete with the repository unit for the unit bound:
- Discovery's
collaboration: trueselects the class; every discovered repository then has a{ kind: 'collaboration', owner, name, id }unit, keyed by the repository's discovered id. A consumer refuses such a discovery while any repository lacksid, and never keys by name. - An
IForgeSourceCollaborationInventorycarrieshighestNumber, the highest number the forge lists among the repository's issues and pull requests, which share one sequence (0when it lists none; a deleted number, or one a disabled unit hides, is invisible to every read), and the record listslabels,milestones,issuesandpullRequests.pullRequestsis absent in results from generators that predate it, and then unread. - Each list is a
TForgeSourceCollaborationRecords:completewith every record, ornotMeasuredwith a reason when no read was attempted, as for the issues of a repository whose issue unit is disabled. A read that fails fails the unit, so records are never partial, and unread is never empty. A list sharesstatuswithTForgeSourceMeasure, so a tool that finds measures bystatusreports anotMeasuredlist as a gap by its path (for examplecollaboration.issues); it never readsvaluefrom acompletelist. - An
IForgeSourceIssueis an issue, never a pull request: source id, number as a decimal string, title and body verbatim (never trimmed), state, the forge's creation, update and closing times, the poster as anIForgeSourceAccountRef(id and verbatim login, never a native user; a deleted account reads as the forge's placeholder), theIForgeSourceOriginalAuthorGitea records for content it imported from another service (null when none), assignees, label ids, milestone id,locked,pinOrder(0when not pinned),dueDate,ref(the branch or tag a user set,''when none),projectIds(the project boards it is on,[]when none),timeEstimate(seconds,0when none), the countstrackedTimes(tracked time entries) anddependencies(issues it depends on), and the attachment and reaction counts of the issue itself. Gitea'scontent_versionis not recorded: it counts concurrent edits and is not content. ItsIForgeSourceIssueComments carry id, verbatim body, times, poster, original author and their own attachment and reaction counts. - An
IForgeSourcePullRequestis recorded for an archive, never as a native pull request's state: source id, number as a decimal string, title and body verbatim,state(openorclosed; a merged pull request isclosed) withmerged,mergedAt,mergeCommitShaandmergedByas the source recorded them (null when it reports none; the forge reports no merge style),base(label,ref,sha,''when the forge reports none) andhead(the same plus the head repository'srepositoryId,-1when Gitea no longer has it, andrepositoryFullName, null then),mergeBase(''when the forge reports none),draft, the creation, update and closing times, the poster and original author,assignees,requestedReviewers(source accounts) andrequestedReviewerTeams(IForgeSourceTeamRef: id and name),labelsandmilestoneas snapshots of what the forge reports on the pull request (never ids to resolve),locked,pinOrder,dueDate,allowMaintainerEdit(recorded, never enforced),ref,projectIds,timeEstimate,trackedTimesanddependencieswith the same sentinels as on an issue, its own attachment and reaction counts, its conversation comments asIForgeSourceIssueComments, itsreviewsandpendingReviews. A person is anIForgeSourceAccountRef(id and login), never an email or a native user. - An
IForgeSourcePullRequestReviewis a submitted review or a review request: id,reviewer(null when the forge names none, as for a review requested from a team),team,state(APPROVED,COMMENT,REQUEST_CHANGESorREQUEST_REVIEW, the forge's values verbatim), body,commitId,stale,official,dismissed, the submission and update times,attachmentsandreactions(decimal string counts for the review's own comment, the one that holds its body;0for aREQUEST_REVIEW, which has none), and itsIForgeSourcePullRequestReviewComments (id, body, times, poster,resolver,path,commitId,originalCommitId,diffHunk,positionandoriginalPositionas decimal strings, and their ownattachmentsandreactionscounts). Files and reactions on reviews and review comments are counted on these records only, never in the mixedattachmentsandreactionsmeasures of the counts unit. A pending (draft) review, which only its author and administrators can see, is never a record: its pull request'spendingReviewscounts it, without body or comments. labelsareIForgeSourceLabels (id, verbatim name, colour, description,exclusive,archived): every repository label, used or not, and never an organization label. An issue'slabelIdsmay also name an organization label, which resolves against the owning organization'slabelRecords(repository and organization labels share one id space). A consumer refuses a run where an issue names a label id found in neither list, or an organization label while that organization'slabelRecordsis null.milestonesare every repository milestone, used or not, asIForgeSourceMilestones (id, title, description, state, creation, update and closing times,dueOn).- An organization's
labelRecordsare all its labels, the only place they are stored, so a consumer can name the ones no issue carries; null whenlabelsis not complete. - Labels, milestones, comments, reviews, review comments, assignees,
requested reviewers and teams sort by numeric id, issues and pull requests
by numeric number, label ids numerically. The inventory's
collaborationand each organization'slabelRecordsare present exactly when discovery'scollaborationis present; absent means unread, never none. A collaboration unit over the unit bound fails withunit-over-bound.
Packages are recorded one per unit when a run selects the package class:
- Discovery's
packageslists each package as anIForgeSourcePackageRef(owner, type, name). The forge keeps one package per owner, type and lowercased name and exposes no other package id (Gitea's v1 package API reports the version id asid), so anIForgeSourcePackageInventoryis identified byownerId,typeand its lowercasedname. - A package record lists every
IForgeSourcePackageVersion(id, version as stored, the forge's creation time, informational only) and, inblobs, each distinct content once as anIForgeSourcePackageBlob: the SHA-256 and size the forge reports and everyIForgeSourcePackageFile(version id, file id, name as stored) holding it. Versions sort by numeric id, blobs by SHA-256, files by version id and file id.repositoryIdis the linked repository's id or null. - A container version is a tag, lowercased, or a manifest digest
sha256:<hex>, so a version is tagged exactly when it does not start withsha256:. Its manifest digest is the SHA-256 of the blob holding itsmanifest.json. An index version carriesreferences, the sorted digests of the manifests it references; no other version carries the field. - Only state the forge can change without replacing a version is recorded
beside the files: npm
distTags(every dist-tag the forge serves, a derivedlatestincluded, since no read tells it from a stored one) and each version'sdeprecatedmessage, and each Cargo version'syankedflag. Metadata fixed at publication (an npm version document, a Cargo index entry, Swift release metadata) is read when the version is transferred, except a Swift version'smanifests(below). Download counts are never recorded. - A Swift version carries
manifests, theIForgeSourceSwiftManifests (key, size, SHA-256 of the bytes the forge served) sorted by key in code-unit order, so a consumer that stores manifests beside the archive can size the version. The key is the trimmed Swift version the forge keys a manifest by (5.7,5.7.1),''forPackage.swift. The producer takes the candidate keys from the manifest file names in the version's archive, after checking the archive against its recorded blob, and asks the forge for each. The field has three states, and neither unread state is ever read as no manifests or zero bytes:- absent: the inventory was recorded by a generator that predates it;
null: the archive was larger than the producer's read bound and was not read;- a list: exactly the manifests the forge answered 200 for,
Package.swiftalways among them.
totals.packageContentis anIForgeSourcePackageContentTotals, a pure function of the package records: distinct digests and their bytes for every owner together and per owner, each by type, over all versions and over the tagged versions plus the manifests their indexes reference. It sizes stores that keep each digest once (Gitea globally, the native container registry per owner); a store that keeps every file needs the per-version file sums of the owners' package counts.packagesandtotals.packageContentare present exactly when discovery'spackagesis present, an empty list included: a source without packages readspackages: []and complete zeros. Absent means the package class is unread, never that the source holds no packages.- A unit result must fit
forgeSourceInventoryUnitMaxBytes(4 MiB of UTF-8 JSON). A package or collaboration unit over it fails with the reasonunit-over-bound; its record is never truncated.
A run first reads IForgeSourceInventoryDiscovery, then measures independent
TForgeSourceInventoryUnits (the instance, each owner, each repository and,
when discovery lists them, each package and, when discovery selects
collaboration, each repository's collaboration). A consumer handles every
unit kind and refuses one it does not know, since package and collaboration
units carry owner and name like a repository unit. A failed unit, or one holding a partial measure,
is measured again on resume.
Discovery records each repository's id as a decimal string and its unit
carries it, so a unit whose name now answers with another id fails instead of
measuring the repository that took the name. id is absent in discoveries
from generators that predate it; a consumer that keys on ids refuses those.
IForgeSourceInventory is deterministic: it carries no run timestamps (the
source's own times, such as release creation, are source state), owners sort
by kind and name, repositories and collaborations by owner and name, packages
by owner, type and name. The report adds
collisionCheck, the source owner and repository names that already exist
natively, exactly or case-insensitively, sorted by subject, source and native
name. A report is a complete planning basis only when inventoryComplete is
true and the collision check ran.
A report never contains secret values, credentials, tokens or the masked forms a forge reports in their place, private keys, Actions secret or variable values, webhook secrets, or mirror remote URLs.
forgeSourceReadStampFields lists the read stamps: fields the source changes
when it is only read, so two inventories of a source nobody wrote to differ in
them and in nothing else. Today that is a release asset's downloadCount. Each
entry is the path from the root of an IForgeSourceInventory to the field, an
object member by name and '*' for every list element; a null or absent member
on the way holds no field. A consumer that compares inventories across a source
freeze removes exactly these fields before it digests them.
Forge source freeze contracts
A freeze proof reads facts from the source and sends canaries to it; the producer reports facts only, and the consumer decides. Neither type carries a token, key, credential or response body.
IForgeSourceQuiescenceReport is read with GET requests only and the
connection's read-only administrator token: the generator, the source
identity with the forge's version verbatim, enabledRunners (every enabled
runner in any scope, every page read, sorted by numeric id; each runner's
status and busy are evidence only, because a frozen source stops runners
from updating them), jobsInProgress (the forge's
in_progress count as a decimal string, always with blindSpot: 'cancelling':
the forge selects cancelling jobs under no filter, so the count never proves
none is cancelling), every cron task with its schedule verbatim, and the
queuedRuns (every queued or pending run with its repository, number, event,
ref and commit, sorted by numeric id). Past forgeSourceQuiescenceQueuedRunMaxRecords (1000) the
queue is overBound with the forge's count and no records, never a truncated
list. A part whose read did not finish is null, and incompleteReasons says
why. A consumer calls the source quiescent only when the version is the one it
qualified, enabledRunners is empty, the job count is '0', every schedule is -,
the queue is complete and incompleteReasons is empty.
IForgeSourceFreezeCanaryOutcome is what one HTTP canary
(TForgeSourceFreezeHttpCanary: receive-pack-discovery, archive-get,
issue-post, release-post, generic-package-put, oci-blob-upload,
lfs-put, lfs-off) got from one IForgeSourceFreezeOrigin: the
httpStatus of its own request (for oci-blob-upload the upload POST, for
lfs-put the object PUT, for lfs-off the batch request; null without a
response), the
X-Gitea-Freeze header as freezeMarker (null when absent), wrote, the
identity of what a 2xx created (null otherwise, and always for
receive-pack-discovery and lfs-off, which create nothing), and a sanitized
errorCode when the canary did not complete as sent. An origin is a baseUrl
with an optional connectAddress: the IP address the connection goes to
instead of DNS, while Host, TLS server name and certificate check stay
baseUrl's host, so one name reached through the edge and directly at the
host are two origins. The SSH canary is an atomic push through GitManager, whose
result carries remoteMessages.
Exports
data: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, pull requests (native and archived), activity, news, stats, codefeed commit results, GitManager repository/read/push API results, origin references, forge and forge source inventories, forge source freeze facts, the native repository release API, and runner/CI contracts.requests: TypedRequest contracts forcodefeed,publicOverview,publicOrg,publicRepo,publicFile, andpublicCommits.- Barrel exports: all public data and request interfaces are also exported from the package root.
Testing
pnpm test
pnpm run build
License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.