Documentation
¶
Overview ¶
Package httpapi is the HTTP projection of a toolbelt Engine: one REST route per Engine method, JSON in and out, no auth and no SSE. Consumers wrap the handler in their own stack and follow jobs through the Engine's Config callbacks or the jobs route.
Mutations return 202 with the enqueued job (null when none was needed). A refusal is 409 coded has_dependents, essential, disabled or not_configured. A GitHub API rate limit is 503 coded github_rate_limited with a rate_limit object; a job it failed carries error_code and rate_limit. A job the queue cannot take is 503 coded queue_full or shutting_down.
GET /search returns installable hits, and with &unavailable=1 the catalog entries nothing can install (see SearchResponse). Every response carries Cache-Control: no-store; a value already set is left as deliberate.
Index ¶
- func Handler(e *toolbelt.Engine, prefix string) http.Handler
- type Code
- type DependentsResponse
- type JobParams
- type JobResponse
- type JobsResponse
- type NameParams
- type OKResponse
- type RateLimitResponse
- type RemoveQuery
- type RemoveResponse
- type Route
- type SearchHit
- type SearchQuery
- type SearchResponse
- type UpdateRequest
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
Handler builds the projection's routes under prefix (e.g. "/api/tools"). Mount it at both the exact prefix and the subtree:
h := httpapi.Handler(engine, "/api/tools")
mux.Handle("/api/tools", h)
mux.Handle("/api/tools/", h)
Every response carries Cache-Control: no-store unless already set.
Types ¶
type Code ¶ added in v3.15.0
Code is one error code with the one status the package answers it with.
type DependentsResponse ¶ added in v3.15.0
type DependentsResponse struct {
Error string `json:"error"`
Code string `json:"code"`
Dependents []string `json:"dependents"`
}
DependentsResponse is the 409 envelope for refused remove/disable: the standard error envelope plus the blocking tool names.
type JobParams ¶ added in v3.15.0
type JobParams struct {
ID string `json:"id"`
}
JobParams is the cancel route's path.
type JobResponse ¶
JobResponse is the 202 body of every mutating route.
type JobsResponse ¶
type JobsResponse struct {
Active *toolbelt.Job `json:"active,omitempty"`
Recent []*toolbelt.Job `json:"recent"`
}
JobsResponse is the jobs route's body: the active job (with output tail) and recent history.
type NameParams ¶ added in v3.15.0
type NameParams struct {
Name string `json:"name"`
}
NameParams is the path of the routes under /{name}.
type OKResponse ¶ added in v3.15.0
type OKResponse struct {
OK bool `json:"ok"`
}
OKResponse is the cancel route's body.
type RateLimitResponse ¶ added in v3.15.0
type RateLimitResponse struct {
Error string `json:"error"`
Code string `json:"code"`
RateLimit toolbelt.GitHubRateLimit `json:"rate_limit"`
}
RateLimitResponse is the 503 envelope for a request GitHub's API rate limit refused: the standard error envelope plus the limit's detail.
type RemoveQuery ¶ added in v3.15.0
type RemoveQuery struct {
Force string `json:"force,omitempty"`
}
RemoveQuery is the delete route's query: Force 1 or true cascades.
type RemoveResponse ¶
type RemoveResponse struct {
Job *toolbelt.Job `json:"job"`
Dependents []string `json:"dependents,omitempty"`
}
RemoveResponse rides a 409-free DELETE alongside the job (dependents is populated on forced cascades so the client can report what else was removed).
type Route ¶ added in v3.15.0
type Route struct {
Params reflect.Type
Request reflect.Type
Query reflect.Type
Response reflect.Type
// Handler serves the route over e, with the package's cache policy.
// It reads path wildcards with PathValue, so the host's pattern must
// name them as Suffix does.
Handler func(e *toolbelt.Engine) http.Handler
Method string
// Suffix is appended to the mount prefix; "" is the prefix itself.
Suffix string
// Codes is every error code the route can answer, in a stable order.
Codes []Code
Status int
}
Route is one route of the projection, for a host that binds each route itself instead of mounting Handler. A nil type means none: no path wildcard, no body, no query key read.
type SearchHit ¶
type SearchHit struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Source string `json:"source"`
// Version is the catalog's default pinned version, set only for
// entries without an upstream version source (manual installs).
Version string `json:"version,omitempty"`
// Reason names the registry backend that defeated the compiler, and
// is set only alongside Unavailable.
Reason string `json:"reason,omitempty"`
// Match names which field the query hit — see [toolbelt.MatchKind].
// Empty for the featured set and for an unavailable hit. On the wire
// because a client cannot derive it: aliases are not projected here,
// so a hit on `rg` would look like a description match otherwise.
Match string `json:"match,omitempty"`
Featured bool `json:"featured,omitempty"`
Lsp bool `json:"lsp,omitempty"`
// install, with Reason naming the registry backend that defeated the
// compiler. Such a hit is informational: a client must not offer an
// install for it, and the engine refuses one anyway.
//
// Both fields are omitempty, so an installable hit serialises exactly
// as it did before this pair existed.
Unavailable bool `json:"unavailable,omitempty"`
// Apt marks a Debian package rather than a catalog entry. Version
// then carries the distro's candidate, which routinely differs from
// the catalog's version for the same tool, and the row's install lands
// in the container layer rather than on the persistent volume.
Apt bool `json:"apt,omitempty"`
}
SearchHit is one catalog search result. A projection of toolbelt.CatalogEntry without the embedded install definition (an implementation detail no client needs).
type SearchQuery ¶ added in v3.15.0
type SearchQuery struct {
Q string `json:"q,omitempty"`
// 1, true, yes or on.
Unavailable string `json:"unavailable,omitempty"`
}
SearchQuery is the search route's query.
type SearchResponse ¶
type SearchResponse struct {
// AptState names what the Debian corpus could say — see
// [toolbelt.AptState] for the three values. Absent from an engine
// predating the field, where AptAvailable is the whole answer.
AptState string `json:"apt_state,omitempty"`
Results []SearchHit `json:"results"`
// Matched is how many rows the query matched across the blocks
// Results holds, before each was cut to its cap. It is the
// denominator Truncated has no room for, so a client can say "25 of
// 61" instead of stating a cut it cannot size. Same population as
// Truncated: an unavailable block the caller did not ask for is not
// counted. Absent when the query matched nothing, and from an engine
// predating the field.
Matched int `json:"matched,omitempty"`
AptAvailable bool `json:"apt_available"`
// Truncated reports a CUT: some block in Results matched more rows than
// the reply carries, so a client showing "N results" is showing fewer than
// the query found. It is judged only over the blocks the reply holds, so
// an unavailable block the caller did not ask for never sets it, and a
// reply carrying every row the query matched is never flagged.
Truncated bool `json:"truncated"`
}
SearchResponse is the search route's body: installable hits merged into one relevance order via toolbelt.Match (catalog and Debian, not concatenated — a bare concatenation put every catalog hit ahead of every Debian one regardless of score), then the opt-in unavailable block, kept separate and unranked since ranking a dead end above a live option would be wrong.
AptAvailable distinguishes "no Debian package matched" from "the package list could not be consulted" — identical in an empty result, opposite in meaning. AptState says which of the two reasons the list could not be consulted, which is what lets a client report a pending condition instead of asserting an absence.
type UpdateRequest ¶ added in v3.15.0
type UpdateRequest struct {
Names []string `json:"names,omitempty"`
}
UpdateRequest is the optional body of the update route: the tools to update, every enabled tool when empty.