gitea

package
v1.4.0-dev.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package gitea is the forgeapi client for Gitea and Forgejo, two products that share one API. Client is its one exported type, so no wire type of either product reaches a forgeapi signature.

Neither product has a GraphQL API, so every operation is REST and pays in requests for what a document carries on the other families. Client.CommitStatus states the largest such cost.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is one connection to a Gitea-family instance: where it is, what the credential is trusted with, and what the budget allows.

It is the concrete type New returns, so a consumer declares the narrowest role interface it actually uses against it rather than receiving an interface this package chose. What it holds is unexported, because the state behind an operation is nobody else's contract; the stable connection facts, which product of the two answered included, are published through Client.ConnectionCaps.

func New

func New(conn forgeapi.Connection, opts ...forgeapi.Option) (*Client, error)

New builds a client for one connection.

It performs no I/O. Which of the two products this instance runs, and every capability that version decides, is resolved by the accessor that needs it, so an instance that is down fails at the operation rather than at construction.

What it does refuse at entry is a client it cannot run honestly, and every refusal carries a code of its own, because a consumer names the remedy for the refusal it got rather than showing a generic warning: no credential source, which is forgeapi.CodeAnonymousRefused rather than a client that sends anonymous requests; no web base URL, a half-present certificate pair, a forgeapi.Connection.Proxy URL net/url refuses or carrying no scheme this library proxies over, or a malformed forgeapi.Header entry, which is forgeapi.CodeConnectionInvalid; an extra header whose name this library or the HTTP stack writes itself, which is forgeapi.CodeHeaderReserved naming it; a plaintext URL without forgeapi.WithPlaintextHTTP, which is forgeapi.CodePlaintextRefused; a private-range or single-label host without forgeapi.WithPrivateAddresses, which is forgeapi.CodePrivateAddressRefused; a negative value passed to any budget option, forgeapi.WithRetries and forgeapi.WithMutationReserve included, which is forgeapi.CodeBudgetInvalid; and a forgeapi.RotationCursor that is not well formed, which is forgeapi.CodeCursorInvalid.

func (*Client) BudgetState

func (c *Client) BudgetState() forgeapi.BudgetState

BudgetState implements forgeapi.Governor. It is the read-only view of this connection's governor, and which of its four fields carry a read value depends on the PRODUCT rather than the family. Forgejo sends a structured `ratelimit` header on every response, so Remaining is its `r` parameter and Reset its `t` seconds; Gitea sends no rate-limit header at all, so there Remaining is forgeapi.BudgetRemainingUnknown and Reset is the zero time. On both, LastCost is this library's own per-call price, one per request, with the folded status read as the expensive member, since neither product prices a call on the wire. The governor's reserve has a signal to hold against on Forgejo and is inert on Gitea; what bounds this family's folded-status work on either is the two per-interval caps forgeapi.Budget publishes, counted by this client over a rolling window of its own, and forgeapi.BudgetState.RotationCursor is where that rotation stands.

It performs no I/O and is safe to call concurrently with operations; it is never written from outside. See forgeapi.BudgetState.

func (*Client) Close

func (c *Client) Close()

Close implements forgeapi.Core: it releases this client's pool, the idle connections of the transport the library built for the connection, at once, which a caller that disconnects or re-addresses the connection wants; otherwise they close after that transport's idle timeout. A transport supplied through forgeapi.WithWireTransport stays its author's to release. A call in flight keeps its connection until it returns. Close adds no closed state: a call after it dials afresh, and a further Close releases that connection too.

func (*Client) CloseIssue

func (c *Client) CloseIssue(ctx context.Context, repo forgeapi.RepoRef, issue forgeapi.IssueRef) (forgeapi.Issue, error)

CloseIssue implements forgeapi.Issues.

func (*Client) ClosePR

ClosePR implements forgeapi.PullRequests.

func (*Client) CommitStatus

func (c *Client) CommitStatus(ctx context.Context, repo forgeapi.RepoRef, ref string) (forgeapi.CommitChecks, error)

CommitStatus implements forgeapi.Checks.

This is the family whose folded status costs one request per pull request, plus one per additional status page, and the fold is computed HERE rather than taken from the endpoint's own verdict: that endpoint is paginated, and both its folded state and its total are computed over the page it returned, so a page of successes reports success for a commit that is failing and the truncation is not detectable from the body at all.

So a fold that stopped short reports the pagination cap in its partial marker and leaves the state unknown rather than publishing a verdict over part of the evidence. This read addresses one commit, so its fold is COMPLETE and bounded only by forgeapi.Budget.StatusPages.

It is also the read forgeapi.Budget.StatusReadsPerInterval counts, over a rolling window this client keeps for itself: the read past that cap is not issued and reports forgeapi.PartialBudget, and the next interval starts at the row after the last one served in that LIST rather than at the first, so no row starves. What survives a restart is the forgeapi.RotationCursor a consumer stored and handed to forgeapi.WithRotationCursor.

func (*Client) ConnectionCaps

func (c *Client) ConnectionCaps(ctx context.Context) (forgeapi.ConnectionCaps, error)

ConnectionCaps implements forgeapi.Capabilities.

func (*Client) CreateIssue

func (c *Client) CreateIssue(ctx context.Context, repo forgeapi.RepoRef, req forgeapi.NewIssue) (forgeapi.Issue, error)

CreateIssue implements forgeapi.Issues.

func (*Client) CreatePR

CreatePR implements forgeapi.PullRequests.

func (*Client) CreateRelease

func (c *Client) CreateRelease(ctx context.Context, repo forgeapi.RepoRef, req forgeapi.NewRelease) (forgeapi.Release, error)

CreateRelease implements forgeapi.Releases.

func (*Client) GrantCaps

func (c *Client) GrantCaps(ctx context.Context) (forgeapi.GrantCaps, error)

GrantCaps implements forgeapi.Capabilities.

It costs no request and carries no evidence object, and both follow from the same fact: this product has no grant endpoint, and the one grant-dependent value on this surface, the merge state, rides the pull-request record's own mergeable flag, which every read of a pull request already carries. So a credential that can read a pull request can read its merge state, and there is nothing separate to probe.

func (*Client) ListIssues

func (c *Client) ListIssues(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Issue], error)

ListIssues implements forgeapi.Issues.

This route's population on both products is issues AND pull requests, so the type filter both documents declare is part of the question rather than an option: without it the answer carries pull-request rows, which this operation would normalize as issues and a consumer would act on as issues.

func (*Client) ListLabels

func (c *Client) ListLabels(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Label], error)

ListLabels implements forgeapi.Labels.

func (*Client) ListMyIssues

func (c *Client) ListMyIssues(ctx context.Context, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Issue], error)

ListMyIssues implements forgeapi.Issues.

It is Client.ListMyPRs asking the same route for the other population: the type filter both products declare selects issues, and the scope, the price and the owner refusal are that call's own. Each row carries its own repository as the meta shape the search route answers, which is what the row is addressed by.

func (*Client) ListMyPRs

ListMyPRs implements forgeapi.PullRequests.

This family answers the cross-repository question through the ISSUE search route, filtered to pull requests and to the open state, so the rows span repositories and each carries its own forgeapi.PullRequest.Repo.

The filter that makes the rows the CREDENTIAL's is the boolean both products declare on this route, created, which the instance resolves against whoever the request authenticated as. Beside it one of the two declares a username filter, created_by, and the other declares none at all, so a call built on that spelling is contracted to scope the answer on one product of the family and not on the other. The shared boolean also prices the call at one request per page, because nothing has to be resolved before the question can be asked.

Under forgeapi.WithOwner the owner filter both products declare on the same route takes the boolean's place, so the call is still one request per page and the owner is resolved by the instance rather than by a read of its own. An owner the instance holds no user or organization for is answered 400 naming the user it could not find, which this family maps to forgeapi.CodeOwnerUnresolved: the route answers 400 for an owner or a team it cannot resolve, and this call sends no team.

No row of this route carries a folded verdict, and the reason is the route's own shape rather than a choice: an issue-search row carries neither a check state nor a HEAD COMMIT, measured on both products and declared by both documents, and a folded status is addressed BY the head. So every row answers forgeapi.CheckUnknown with a zero total, uniformly, which is what the expectation table states field by field for this operation on this family. The verdict for a row a consumer opens is Client.ReadPR or Client.CommitStatus, one call on one pull request; recovering the head here would cost a second read per row, which is the per-item fan-out the budget refuses on a poller's hot path.

func (*Client) ListPRs

ListPRs implements forgeapi.PullRequests.

There is no document to fold the merge state into this call, so what the list carries is what the REST list carries, and a state it cannot read is reported unknown rather than guessed. The folded check verdict for each row is a separate read with a separate cap; see Client.CommitStatus.

That read is BOUNDED on this path, which is the same rule every family's list follows arriving in another transport: one page of the status endpoint per row, and a row whose status had a further page answers forgeapi.CheckUnknown with forgeapi.PartialPaginationCap on forgeapi.PullRequest.Partial. A row the client's per-interval cap left unread carries forgeapi.PartialBudget instead, which is a different fact: the fold was not issued rather than truncated.

Which rows those are is decided per LIST. The rotation this call resumes from is this repository's own, so no row of it starves across intervals, and nothing here schedules across repositories: a caller sweeping several through this call on one connection gives the first lists the folds and the later ones none inside one interval, in the order it chose. Client.ListMyPRs is the call whose rows span repositories, and it issues no fold and spends no part of the per-interval cap, because an issue-search row carries no head to address one by; the verdict for a row a consumer opens is Client.ReadPR or Client.CommitStatus.

func (*Client) ListReleases

func (c *Client) ListReleases(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Release], error)

ListReleases implements forgeapi.Releases.

func (*Client) ListRepos

func (c *Client) ListRepos(ctx context.Context, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Repository], error)

ListRepos implements forgeapi.Repos.

Under an owner it reads the owner's own route, which both products resolve for a user and an organization alike and which pages in SQL before dropping the rows the caller has no unit access to, so its walk continues from the stated total. Its 404 is an owner the instance does not hold (services/context/user.go), so it carries forgeapi.CodeOwnerUnresolved.

func (*Client) ListRuns

func (c *Client) ListRuns(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Run], error)

ListRuns implements forgeapi.Checks. The row type reads both products' status fields, and forgeapi.Run.Name is the workflow file's name without its YAML extension, since neither product names the workflow. It is not gated on forgeapi.CapRerunChecks, since both carry the route whether or not they can re-run. The envelope's total_count decides the continuation (see runWalk.next), so one missing or below zero is refused, a page with no row while the total states more ends the walk with forgeapi.PartialResultWindow, and under forgeapi.WithSince a page runsSince reports passed ends it complete.

func (*Client) MergePR

MergePR implements forgeapi.Merges.

The merge is synchronous here and this family has neither a merge queue nor a merge train, so a merge not asked to wait is merged or refused. A merge asked to wait sends the merge form first, which merges a pull request whose requirements are met, and only on that form's 405 sends it again with merge_when_checks_succeed, this family's own field for it, whose 201 is the scheduled merge, forgeapi.MergeOutcomeEnqueued: measured, every product of the family schedules a flagged merge whatever the checks, and Forgejo then waits for the next commit status on its head, so the flag goes only where the merge cannot complete now. Such a merge costs one or two requests. Two of its refusals are this family's own: a conflict is forgeapi.CodeNotMergeable, because the route answers it for a head that moved, for a merge that conflicts and for a merge asked to wait while one is already scheduled, which stands, and names the cause in human text alone, and an archived repository is forgeapi.CodeRepoArchived. That is a permanent refusal whose remedy is an operator unarchiving the repository, never retried and never reported as a conflict, because no rebase and no re-read reaches that state. A strategy outside the family's own set is forgeapi.CodeStrategyNotAllowed before any request; the route's own 405 is forgeapi.CodeNotMergeable, because this product answers it for a disallowed merge style and for a pull request not yet mergeable alike.

func (*Client) MergeStatus

func (c *Client) MergeStatus(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef) (forgeapi.MergeStatus, error)

MergeStatus implements forgeapi.Merges.

It is one REST call, the same pull-request read Client.ReadPR makes without the folded status that read adds, and the record carries the merged state and the pull request's own page. That folded status is what Client.ReadPR is for, and it is the call a caller wanting the check verdict makes on the same pull request; this read returns no checks and pays for none. Queue is forgeapi.QueueNone always: this family has no queue and no train, so the neutral member is the answer rather than a field omitted, which is what lets a caller written against another family read this one unchanged.

func (*Client) ReadPR

ReadPR implements forgeapi.PullRequests.

It is two to four REST calls on this family, which is the cost this operation publishes: the pull-request read, plus the folded commit status forgeapi.ActionState.Checks comes from, since there is no document to fold it into the first. The second request is always issued, and the fold is COMPLETE, so it follows that status's pages until it is total: the low end of the range is a single-page fold and the high end is forgeapi.Budget.StatusPages. None of it is counted against the folded-status cap the client keeps per rolling interval, because this read is priced per call. A fold that reaches that page bound reports forgeapi.PartialPaginationCap in forgeapi.PullRequest.Partial with the verdict at forgeapi.CheckUnknown rather than a verdict over part of the evidence.

Its absence answer is the union, forgeapi.CodeRepoOrPRNotVisible, always. One REST status carries no evidence separating a pull request that does not exist from a repository the credential cannot see; the body carries a message and no machine-readable cause, mapping on message text is the guess this library refuses, and a third read to prove the repository exists would break that published cost.

A forgeapi.PullRequest carries no successor, so a repository that moved answers forgeapi.CodeRepoRefStale carrying it, at the first read and its hop.

func (*Client) ReopenPR

func (c *Client) ReopenPR(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef) (forgeapi.PullRequest, error)

ReopenPR implements forgeapi.PullRequests.

func (*Client) RepoAffordances

func (c *Client) RepoAffordances(ctx context.Context, repo forgeapi.RepoRef) (forgeapi.RepoAffordances, error)

RepoAffordances implements forgeapi.Capabilities. forgeapi.RepoAffordances.MergeTrain is forgeapi.SupportNo on every repository of this family, which has neither a merge queue nor a merge train, and its evidence source is forgeapi.EvidenceVersion rather than the response body the other values come from: no field of the repository record answers it, and what does is the product the version body identified.

A forgeapi.RepoAffordances carries no successor, so a repository that moved answers forgeapi.CodeRepoRefStale carrying it.

func (*Client) RerunFailedChecks

func (c *Client) RerunFailedChecks(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef, headSHA string) error

RerunFailedChecks implements forgeapi.PullRequests.

This is the operation the two products of this family differ on, and it is why a missing verb is a CAPABILITY here rather than an unimplemented role: one package serves both, so failing to satisfy the role would withdraw the operation from the product that does serve it. An instance without it reports forgeapi.CapRerunChecks as no or unknown with its evidence, and the refusal arrives from the capability rather than from a call that cannot work: forgeapi.CodeCapabilityUnsupported, with that evidence on it and no request sent.

The head pin binds here and costs no request of its own: the route is addressed by a server-allocated run id, so the read that resolves it is filtered BY the caller's SHA, and a SHA no run carries means the pull request has moved since the caller's row was rendered. That is refused rather than re-run, because a re-run can carry deployment side effects and a row displaying one commit's red status must not act on another's. An empty SHA means the forge reported no head, and the re-run then proceeds against the FIRST run the instance returns, which is the one case where the pin is unavailable rather than waived, and which is the instance's own ordering rather than a newest this route's document states.

func (*Client) Whoami

func (c *Client) Whoami(ctx context.Context) (forgeapi.Account, error)

Whoami implements forgeapi.Identity.

Jump to

Keyboard shortcuts

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