httpapi

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, no middleware; 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.

Index

• func Handler(e *toolbelt.Engine, prefix string) http.Handler
• type JobResponse
• type JobsResponse
• type RemoveResponse
• type SearchHit
• type SearchResponse

Functions

func Handler

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

Types

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 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.