spec

package
v3.0.0-dev.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

Documentation

Overview

Package spec is forgeapi's expectation table: what each operation does on each product, held once, each entry stating what a forge was measured or documented to do.

Three consumers read it and nothing else states these facts. The generator under internal/gen renders the per-forge block of every role method's godoc and the support matrix in SUPPORT.md; gen_test.go fails when either would change; and the conformance suite iterates one case per entry.

Index

Constants

This section is empty.

Variables

View Source
var Fields = map[string]int{
	"Identity.Whoami":                5,
	"Repos.ListRepos":                17,
	"PullRequests.ListPRs":           33,
	"PullRequests.ListMyPRs":         33,
	"PullRequests.ReadPR":            30,
	"PullRequests.CreatePR":          30,
	"PullRequests.ClosePR":           30,
	"PullRequests.ReopenPR":          30,
	"PullRequests.RerunFailedChecks": 2,
	"Merges.MergePR":                 4,
	"Merges.MergeStatus":             4,
	"Merges.CancelAutoMerge":         1,
	"Checks.CommitStatus":            10,
	"Checks.ListRuns":                15,
	"Checks.RerunFailedRun":          2,
	"Issues.ListIssues":              18,
	"Issues.ListMyIssues":            18,
	"Issues.ReadIssue":               15,
	"Issues.CreateIssue":             15,
	"Issues.CloseIssue":              15,
	"Issues.ReopenIssue":             15,
	"Capabilities.ConnectionCaps":    4,
	"Capabilities.GrantCaps":         2,
	"Capabilities.RepoAffordances":   6,
	"Governor.BudgetState":           5,
	"Releases.ListReleases":          10,
	"Releases.CreateRelease":         7,
	"Labels.ListLabels":              6,
	"Labels.AddLabels":               1,
	"Labels.RemoveLabels":            1,
}

Fields counts the output fields each operation publishes, which is one row of its measured table and the same count on all four products. A rendering reads it to tell a column that departs on every field from one that departs on most.

View Source
var FigureFields = [...]string{"Pool", "Remaining", "Reset", "Secondary"}

FigureFields is every figure a product's Figures row states, in rendering order.

View Source
var Figures = []Figure{
	{
		Product: GitHub, Field: "Pool", Header: "X-RateLimit-Resource", Value: "core",
		Says: "the pool the answer drew on, `core` for REST, `graphql` for documents and `search` for searches, named on a secondary limit too, which holds every pool " +
			"([rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#checking-the-status-of-your-rate-limit))",
	},
	{Product: GitHub, Field: "Remaining", Header: "X-RateLimit-Remaining", Value: "0", Says: "the units left in that pool's window: requests on REST, points on documents"},
	{Product: GitHub, Field: "Reset", Header: "X-RateLimit-Reset", Value: "4102444800", Says: "the instant that window renews, in epoch seconds"},
	{
		Product: GitHub, Field: "Secondary", Header: "Retry-After", Value: "60", Message: "secondary rate limit",
		Says: "a secondary limit, set on a 403 or 429 carrying either signal whatever X-RateLimit-Remaining reads, and on a document's errors-only answer at 200 carrying either, its message in the envelope's errors " +
			"([rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits))",
	},
	{
		Product: GitLab, Field: "Pool", Header: "RateLimit-Name", Value: "throttle_authenticated_api",
		Says: "the throttle the request counted against, the most restrictive one: on gitlab.com `throttle_authenticated_api` for most routes " +
			"([response headers](https://docs.gitlab.com/administration/settings/user_and_ip_rate_limits/#response-headers))",
	},
	{Product: GitLab, Field: "Remaining", Header: "RateLimit-Remaining", Value: "0", Says: "the requests left in that throttle's window"},
	{Product: GitLab, Field: "Reset", Header: "RateLimit-Reset", Value: "4102444800", Says: "the instant that window renews, in epoch seconds"},
	{Product: GitLab, Field: "Secondary", Says: "never set: every limit this product answers names its throttle"},
	{Product: Gitea, Field: "Pool", Says: "empty: the product sends no budget signal (measured on gitea.com)"},
	{Product: Gitea, Field: "Remaining", Says: "`BudgetRemainingUnknown`, since the product sends no budget signal"},
	{Product: Gitea, Field: "Reset", Says: "the zero time, since the product sends no budget signal"},
	{Product: Gitea, Field: "Secondary", Says: "never set: the product has no secondary limit"},
	{
		Product: Forgejo, Field: "Pool",
		Says: "empty: the header's one figure is the whole service's, reported under no name, though the header names its policy (`baseline` on codeberg.org, measured)",
	},
	{
		Product: Forgejo, Field: "Remaining", Header: "RateLimit", Param: "r", Value: `"baseline";r=0;t=600`,
		Says: "the requests left in the window " +
			"([RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/))",
	},
	{
		Product: Forgejo, Field: "Reset", Header: "RateLimit", Param: "t", Value: `"baseline";r=0;t=600`, Relative: true,
		Says: "the instant the window renews, counted in seconds after the answer, and the zero time where the header has no `t`",
	},
	{Product: Forgejo, Field: "Secondary", Says: "never set: the product has no secondary limit"},
}

Figures is every product's rate-limit figures, one row per product per field.

View Source
var Products = [...]Product{GitHub, GitLab, Gitea, Forgejo}

Products is the column order of every generated rendering.

View Source
var Revalidations = []Revalidation{
	{
		Product:    GitHub,
		Validators: "`ETag` on most REST routes, weak on the lists measured, and `Last-Modified` on many ([best practices](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api#use-conditional-requests-if-appropriate))",
		Documents:  "not revalidated: a document is a POST ([forming calls](https://docs.github.com/en/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)), and conditional requests for unsafe methods are unsupported (best practices)",
		Says: "a not-modified answer to a conditional request made with an `Authorization` header does not count against the primary rate limit " +
			"([best practices](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api#use-conditional-requests-if-appropriate)); " +
			"measured with an authorized request, the answer carries `ETag`, `Vary`, `Cache-Control` and the `x-ratelimit-*` headers but no `Link` and no `X-OAuth-Scopes`, and two answers with one body and different `Link` headers carried one `ETag`, which therefore covers the body alone: " +
			"a revalidated page of a list whose body states no total continues wherever it is full, and the identity read, whose scopes ride that header, is never revalidated",
		NotModifiedPrice: 0,
	},
	{
		Product:    GitLab,
		Validators: "a weak `ETag` on every REST read answered 200 with a body that sets no validator of its own, computed by Rack's ETag middleware over the body ([rack/etag.rb](https://github.com/rack/rack/blob/v2.2.23/lib/rack/etag.rb#L26-L63)), and no `Last-Modified` on the routes measured",
		Documents:  "not revalidated: a document is a POST; the ETag polling GitLab documents serves its own frontend routes ([polling](https://docs.gitlab.com/ee/development/polling.html))",
		Says: "a not-modified answer is billed like any request ([rate limits](https://docs.gitlab.com/administration/settings/user_and_ip_rate_limits/)); " +
			"measured with an authenticated request, `ratelimit-observed` rose across a 304 that carried `link`, `x-next-page`, `x-total` and `x-total-pages` as the 200 did, so revalidation saves the body's transfer, not the request",
		NotModifiedPrice: 1,
	},
	{
		Product:          Gitea,
		Validators:       "none on the JSON API: its writer sets only `Content-Type` ([services/context/base.go](https://github.com/go-gitea/gitea/blob/v28.1.0/services/context/base.go#L114-L120)); the raw, media and archive download routes send them ([routers/common/serve.go](https://github.com/go-gitea/gitea/blob/v28.1.0/routers/common/serve.go#L20-L21), [routers/api/v1/repo/file.go](https://github.com/go-gitea/gitea/blob/v28.1.0/routers/api/v1/repo/file.go#L141), [services/repository/archiver/archiver.go](https://github.com/go-gitea/gitea/blob/v28.1.0/services/repository/archiver/archiver.go#L355-L408)), and this library reads none of them; measured on gitea.com",
		Documents:        "no GraphQL API: the API is the REST surface its swagger describes ([API usage](https://docs.gitea.com/development/api-usage)), mounted at `/api/v1` with no GraphQL route beside it ([routers/init.go](https://github.com/go-gitea/gitea/blob/v28.1.0/routers/init.go#L183-L185))",
		Says:             "no validator rides a JSON answer, so no read is revalidated, no not-modified answer arises, and the cache stays inert; the price of 1 is this library's own for a product whose API documentation states no exemption ([API usage](https://docs.gitea.com/development/api-usage)), and the product sends no budget signal (measured)",
		NotModifiedPrice: 1,
	},
	{
		Product:          Forgejo,
		Validators:       "none on the JSON API: its writer sets only `Content-Type` ([services/context/base.go](https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/services/context/base.go#L137-L148)); the raw, media and archive download routes send them ([routers/common/serve.go](https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/routers/common/serve.go#L18-L19), [routers/api/v1/repo/file.go](https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/routers/api/v1/repo/file.go#L147) and [#L371-L374](https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/routers/api/v1/repo/file.go#L371-L374)), and this library reads none of them; measured on codeberg.org",
		Documents:        "no GraphQL API: the API is the REST surface its swagger describes ([API usage](https://forgejo.org/docs/latest/user/api-usage/)), mounted at `/api/v1` and `/api/forgejo/v1`, both REST ([routers/init.go](https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/routers/init.go#L180-L181))",
		Says:             "no validator rides a JSON answer, so no read is revalidated, no not-modified answer arises, and the cache stays inert; the price of 1 is this library's own for a product whose API documentation states no exemption ([API usage](https://forgejo.org/docs/latest/user/api-usage/)), and codeberg.org meters every request (`ratelimit: \"baseline\";r=1999;t=600`, measured)",
		NotModifiedPrice: 1,
	},
}

Revalidations is every product's conditional-read facts, which the read cache and the published prices follow.

View Source
var Table = []Entry{}/* 120 elements not displayed */

Table is the expectation table: one entry per operation per product, in the operation order the roles declare and the product order every rendering uses.

View Source
var Throttles = []Throttle{
	{
		Product: GitHub, Status: 403, Header: "X-RateLimit-Remaining", Value: "0",
		Says: "the primary or a secondary limit spent, with no budget left in the window",
	},
	{
		Product: GitHub, Status: 403, Header: "Retry-After",
		Says: "a secondary limit, whatever X-RateLimit-Remaining reads, " +
			"as [GitHub documents it](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)",
	},
	{
		Product: GitHub, Status: 403, Message: "secondary rate limit",
		Says: "a secondary limit, whatever X-RateLimit-Remaining reads, where the answer carries no Retry-After",
	},
	{Product: GitHub, Status: 429, Says: "a primary or a secondary limit"},
	{
		Product: GitHub, Status: 200, Document: true, Header: "X-RateLimit-Remaining", Value: "0",
		Says: "a document's primary or secondary limit spent, with no budget left in the window " +
			"([GraphQL rate limits](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api#exceeding-the-rate-limit))",
	},
	{
		Product: GitHub, Status: 200, Document: true, Header: "Retry-After",
		Says: "a document's secondary limit, whatever X-RateLimit-Remaining reads",
	},
	{
		Product: GitHub, Status: 200, Document: true, Message: "secondary rate limit",
		Says: "a document's secondary limit, whatever X-RateLimit-Remaining reads",
	},
	{
		Product: GitHub, Status: 403, Document: true, Message: "secondary rate limit",
		Says: "a document's secondary limit, its message in the envelope's errors",
	},
	{
		Product: GitHub, Status: 403, Document: true, Header: "X-RateLimit-Remaining", Value: "0", Message: "secondary rate limit",
		Says: "a document's secondary limit with no budget left in the window, its message in the envelope's errors",
	},
	{
		Product: GitHub, Status: 429, Document: true, Header: "X-RateLimit-Remaining", Value: "0", Message: "secondary rate limit",
		Says: "a document's secondary limit with no budget left in the window, its message in the envelope's errors",
	},
	{Product: GitLab, Status: 429, Says: "a rate limit"},
	{
		Product: Gitea, Status: 403, Header: "RateLimit", Value: "r=0",
		Says: "a rate limit with no budget left in the window, the structured header's r parameter at 0",
	},
	{Product: Gitea, Status: 429, Says: "a rate limit"},
	{
		Product: Forgejo, Status: 403, Header: "RateLimit", Value: "r=0",
		Says: "a rate limit with no budget left in the window, the structured header's r parameter at 0",
	},
	{Product: Forgejo, Status: 429, Says: "a rate limit"},
}

Throttles is every rate-limit answer the families map.

Functions

This section is empty.

Types

type Departure

type Departure struct {
	Field    string
	Kind     Kind
	Says     string
	Evidence string
}

Departure is one field a product does not deliver as the contract states.

Says is the measurement's own words about that cell, kept verbatim so the generated documentation states what was read rather than a paraphrase. Evidence is empty on a measured departure and names the instrument on one that is not measured: CREDENTIAL and HOST for a read nobody has taken, the SANDBOX forms for an answer only a write could give, and a PARTLY prefix where one half of the cell was read and the other was not.

type Entry

type Entry struct {
	Method     string
	Product    Product
	Exercises  string
	Needs      string
	Support    Support
	Departures []Departure
	Sends      []Sent
	Requests   Requests
}

Entry is one operation on one product.

Exercises names the endpoint or the GraphQL document the call reaches. It is EMPTY in two cases the Support status tells apart, because an unrouted call is not one thing: on a Pending entry no route is settled YET, which the generator renders as unsettled and which is the family implementer's to decide; on an Unsupported entry the product carries no such verb, which the generator renders as the refusal it is and which a departure row of that entry states. Needs is the capability a detection can refuse the call on, empty where none gates it. Departures holds only the fields that depart: a field arriving exactly as the contract states has no row here, which is what keeps the generated blocks short. Sends holds the request facts a consumer relies on, and it is empty on the operations whose request carries no decision and on a column whose family nobody has implemented, where a claim about what the code sends would be a claim about code that does not run.

type Figure

type Figure struct {
	Product Product
	// Field is the figure as Error names it, one of FigureFields.
	Field string
	// Header is the response header carrying the figure, empty where the
	// product's answers carry none, and Value a value it arrives with.
	Header string
	Value  string
	// Param is the parameter of Header's structured value carrying the figure,
	// empty where the whole value does.
	Param string
	// Message is a phrase of a refusal's message member that sets Secondary,
	// matched in any case, empty where none does.
	Message string
	Says    string
	// Relative reports a Reset counting seconds after the answer rather than
	// epoch seconds.
	Relative bool
}

Figure is where one product's answers carry one rate-limit figure, which a failed answer's Error reports and which BudgetState's Pools and PoolOf read from every answer. Says carries the reading and its citation.

type Holds

type Holds string

Holds is what decides the value one Sent names, which is what lets the table state a request fact without holding a fixture's own values: a literal is spelled here, and everything else is the value the CALLER supplied, resolved by whoever drives the call.

const (
	HoldsLiteral    Holds = "literal"
	HoldsHeadSHA    Holds = "head SHA"
	HoldsLabelNames Holds = "label names"
	HoldsLabelIDs   Holds = "label ids"
	HoldsSinceBound Holds = "since bound"
	HoldsNothing    Holds = "nothing"
)

What a sent field can hold. HoldsNothing is the absence of the field itself, which is a decision as much as a value is: a request that omits a flag gets the product's default for it, and a default that arms something is the defect this column exists to catch.

type Kind

type Kind string

Kind is why a product's field departs from the normalized contract.

const (
	CannotSupply      Kind = "cannot supply"
	DiffersInShape    Kind = "differs in shape"
	DiffersInSpelling Kind = "differs in spelling"
	NotMeasured       Kind = "not measured"
)

The four departure kinds. The first three are a field the product cannot supply, one that arrives in another structure, and one that arrives in another form. The fourth is a cell no measurement lane could read, which is a departure from a CONFIRMED contract rather than from the contract itself, and its Evidence names the instrument that closes it.

type Product

type Product string

Product is one of the four forge products, spelled as every rendering spells it.

const (
	GitHub  Product = "GitHub"
	GitLab  Product = "GitLab"
	Gitea   Product = "Gitea"
	Forgejo Product = "Forgejo"
)

The four products. Products fixes the column order: GitHub first because it is the measured column, then GitLab, then the two the Gitea family serves.

type Requests

type Requests struct {
	Min int
	Max int
	// PerItem counts the further requests each row costs: the Gitea family's
	// folded status, one read per row.
	PerItem int
	// PerItemCeiling counts the further requests a row may cost beyond PerItem:
	// GitLab's fork lookup on its cross-repository list, one per distinct fork.
	PerItemCeiling int
	// PerName counts the further requests each label name the call names costs:
	// one removal per name where the product removes one label per request.
	PerName int
	// PerNameCeiling counts the further requests a name may cost beyond PerName:
	// a removal sent only for a name the item carries.
	PerNameCeiling int
	// Paged says the figure is per page of a continued list, capped by
	// Budget.ListPages.
	Paged bool
}

Requests is one call's price in requests the instance bills: every request sent, failed attempts included, less a not-modified answer a product prices at zero in Revalidations. Min and Max are equal for one figure and differ for a range, whose arms are a degradation path or a fold's pages rather than an estimate.

type Revalidation

type Revalidation struct {
	Product          Product
	Validators       string
	Documents        string
	Says             string
	NotModifiedPrice int
}

Revalidation is what one product does with a conditional read of a REST route: the validators it sends, what a not-modified answer bills, and whether a document read can be revalidated. NotModifiedPrice is in the product's own units. Says carries the citation.

type Sent

type Sent struct {
	Field string
	Where Where
	Holds Holds
	Value string
	Says  string
}

Sent is one fact about what a call PUTS ON THE WIRE: a request field a consumer relies on, where a wrong default would change the request silently and no output assertion would notice.

Field is the product's own wire spelling. Value is the JSON the field carries and is read only where Holds is HoldsLiteral. Says states the decision the field carries, and it is what the generated documentation publishes, so the library says what it sends as well as what it answers.

type Support

type Support string

Support is how much of an operation a product serves.

const (
	Supported   Support = "supported"
	Unsupported Support = "unsupported"
	Pending     Support = "pending"
)

The support statuses a matrix cell can carry. Pending claims no support on that product yet: either no family implements the operation there, or the instance measured answered it in a way the normalized contract does not cover, so a claim of support would be a claim the measurement does not make. Unsupported is the one status an implementation cannot change, because it says the PRODUCT carries no such operation, so detection refuses the call on every instance of it.

There is no partly-supported status. A departure is per FIELD and rides the generated godoc beside the field it qualifies, so a cell standing for "supported with a note" would state the same fact at a grain that cannot name which field it is about.

type Throttle

type Throttle struct {
	Product Product
	Header  string
	Value   string
	// Message is the phrase the refusal's message member carries that makes the
	// status a throttle, or beside a Header a secondary one, matched in any
	// case, empty where no message does.
	Message string
	Says    string
	Status  int
	// Document reports an answer to a GraphQL document carrying errors and no
	// data, whose Message rides an envelope error's message.
	Document bool
}

Throttle is one answer a product sends for its rate limit, which every operation on that product reports as KindRateLimited, with RetryAfter from the Retry-After header where the answer carries one.

Header is the response header that makes the status a throttle, empty where the status alone does, and Value the value it carries, empty where any does.

type Where

type Where string

Where is the part of one request a Sent names.

const (
	InBody  Where = "body"
	InQuery Where = "query"
)

The two parts of a request a decision can ride. A product that takes a filter as a query parameter and one that takes the same fact in a body are stating the same decision in two places, which is why the part is per product rather than per operation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL