Documentation
¶
Overview ¶
Package httpapi is the HTTP projection of a toolbelt Engine: a REST surface over the Engine's Go API, one route per method, JSON in and out. It is a pure function of the Engine — no auth, no SSE, and one piece of middleware only, the cache policy below; consumers wrap the returned handler in their own stack (an origin/CSP chain, a loopback-peer gate, logging) and stream job progress themselves via the Engine's Config callbacks or by polling the jobs route.
Mutations return 202 with the enqueued job (null when the operation needed none, e.g. adding a disabled template). Refusals map to conflict responses: has_dependents and disabled are 409 with the standard webhttp error envelope, has_dependents additionally naming the blocking tools.
Cache policy ¶
The handler owns its cache policy: every response it produces carries Cache-Control: no-store, so a consumer no longer needs to wrap it in a no-store middleware of its own. This is a mutable JSON control plane — it lists jobs and accepts installs — so a stored response is always wrong, on a success body, a decode rejection, an engine error, and the mux's own 404/405/redirect alike.
A Cache-Control header already set on the response when the handler runs is left exactly as it is, on the same rule webhttp.JSONHeaders applies to X-Content-Type-Options: a wrapping stack that states the policy stays that header's single writer. The package cannot tell a stricter value from a weaker one without parsing directives, so it treats any present value as deliberate — which makes an outer Cache-Control both the way to say "no-store, no-cache, must-revalidate" and the documented escape hatch for a consumer that genuinely wants this route cached.
Index ¶
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") and returns the handler. 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 the returned handler produces carries Cache-Control: no-store unless the header is already set — see the package doc's cache-policy section.
Types ¶
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 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 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"`
Featured bool `json:"featured,omitempty"`
Lsp bool `json:"lsp,omitempty"`
}
SearchHit is one catalog search result. A projection of toolbelt.CatalogEntry without the embedded install definition (an implementation detail no client needs).
type SearchResponse ¶
type SearchResponse struct {
Results []SearchHit `json:"results"`
}
SearchResponse is the search route's body.
Source Files