Documentation
¶
Overview ¶
Package api wires HTTP routes to the instance.Service.
Index ¶
- func NewRouter(svc *instance.Service, jobs store.JobStore, keys *auth.KeyStore, ...) http.Handler
- func WriteError(w http.ResponseWriter, err error)
- func WriteErrorWithDetails(w http.ResponseWriter, err error, details map[string]any)
- func WriteJSON(w http.ResponseWriter, status int, v any)
- type BackupView
- type BackupVolumeView
- type ErrorBody
- type HostFileRenamer
- type JobCanceller
- type RegistryPruner
- type RouterOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRouter ¶
func NewRouter(svc *instance.Service, jobs store.JobStore, keys *auth.KeyStore, audit func(http.Handler) http.Handler, metricsHandler http.Handler, canceller JobCanceller, version string, registryClient imgregistry.Client, opts ...RouterOption) http.Handler
NewRouter builds the full HTTP handler tree. audit is an optional middleware applied around auth-guarded handlers; pass nil for no-op. metricsHandler is an optional handler mounted at GET /metrics; pass nil to omit the endpoint. canceller is an optional JobCanceller for the POST /jobs/{id}/cancel route; pass nil when the job runner is not wired. version is the server's release string (e.g. "v1.0.16", "dev"); included in the /mcp discovery document. registryClient is an optional imgregistry.Client for the GET /registry/... routes; pass nil to disable registry browsing (routes return 404). opts carry the optional dependencies added after this signature settled; see RouterOption.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error)
WriteError translates an error into a JSON error response. Sentinel errors from the instance package map to known codes; anything else falls through to "internal".
func WriteErrorWithDetails ¶
func WriteErrorWithDetails(w http.ResponseWriter, err error, details map[string]any)
WriteErrorWithDetails is like WriteError but lets handlers attach structured detail (e.g. host/template/slug).
Types ¶
type BackupView ¶
type BackupView struct {
ID string `json:"id"`
Host string `json:"host"`
Template string `json:"template"`
Slug string `json:"slug"`
State string `json:"state"`
Image string `json:"image,omitempty"`
Volumes []BackupVolumeView `json:"volumes,omitempty"`
Created string `json:"created"`
Finished string `json:"finished,omitempty"`
}
BackupView is the JSON shape of one backup. Manifests are internal verification metadata and are not exposed; per-volume name+size are.
type BackupVolumeView ¶
BackupVolumeView is one exported volume's public metadata: name + tar size.
type ErrorBody ¶
type ErrorBody struct {
Code string `json:"code"`
Message string `json:"message"`
Details map[string]any `json:"details,omitempty"`
}
ErrorBody is the JSON shape of every error response.
type HostFileRenamer ¶ added in v1.0.38
type HostFileRenamer interface {
RenameHostFile(oldID, newID string) (path string, original []byte, err error)
}
HostFileRenamer rewrites a host's id in its hosts/*.yaml config file, returning the file's path and its original content (for revert-on-failure). Implemented by config.HostsDir.
type JobCanceller ¶
JobCanceller cancels an in-flight (running) job. Implemented by *jobs.Runner. Nil when the job runner is not wired (no -state-db), in which case the cancel endpoint is unreachable anyway (the jobs-disabled guard precedes it).
type RegistryPruner ¶ added in v1.0.35
RegistryPruner enqueues an on-demand registry prune run. Satisfied by *registryprune.Scheduler.
It is deliberately the SCHEDULER and not the job store: the scheduler's in-flight check is the only thing preventing two runs from classifying the same catalog while each mutates it, and a route that wrote to the store directly would walk straight past it. The route exposes the guard; it does not bypass it.
type RouterOption ¶ added in v1.0.35
type RouterOption func(*handlers)
RouterOption supplies an optional dependency to NewRouter. Options exist because NewRouter's positional signature already has eight parameters and is called from ~26 places; a new optional dependency should not touch every one of them.
func WithHostRenamer ¶ added in v1.0.38
func WithHostRenamer(r HostFileRenamer) RouterOption
WithHostRenamer enables POST /hosts/{host}/rename. Without it the route responds 501, the same "absent, not disabled" shape as the registry browse routes without a client.
func WithHostsReloader ¶ added in v1.0.38
func WithHostsReloader(reload func() error) RouterOption
WithHostsReloader supplies "re-read hosts/*.yaml and make it live everywhere", i.e. exactly what SIGHUP does. The rename handler calls it after a successful rename so the podman client's host map and the server's background-poller host list follow the new id, instead of working the old one until the next SIGHUP.
Unlike WithHostRenamer its absence is not a 501: the reload runs AFTER the rename has been committed to both the config file and the store, so a missing or failing reloader is logged, never a failed request.
func WithRegistryPruner ¶ added in v1.0.35
func WithRegistryPruner(p RegistryPruner) RouterOption
WithRegistryPruner enables POST /registry/prune. Without it the route 404s, exactly as the browse routes do without a registry client.
Source Files