httpapi

package
v3.15.1 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: 7 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler

func Handler(e *toolbelt.Engine, prefix string) http.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

type Code struct {
	Code   string
	Status int
}

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

type JobResponse struct {
	Job *toolbelt.Job `json:"job"`
}

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.

func Routes added in v3.15.0

func Routes() []Route

Routes returns the projection's routes in table order: the routes Handler serves.

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"`
	// Unavailable marks a hit the catalog knows about and cannot
	// 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"`
	// Unavailable opts into the uninstallable block: present and empty,
	// 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.

Jump to

Keyboard shortcuts

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