Documentation
¶
Overview ¶
Package httpapi is the v0.2 production API for non-Go producers (ADR-0008): enqueue tasks, report production errors (ADR-0021), and read queue stats over HTTP with token auth. Unlike the read-only dashboard (`tq serve`), this surface WRITES, so the token is mandatory on every bind (no loopback exemption: API servers are meant to be exposed to other machines).
Viewpoint — Consumer: non-Go producers and remote dashboards; Concern: queue-metadata plus the error-report command (enqueue, error.observed facts, per-status counts, health); Non-goals: per-task reads — derived outcomes (agent results, review/status verdicts, session usage) remain dashboard surfaces (`tq serve` detail pages, `tq show`).
Cross-package map (lifecycle × concern): docs/architecture-understanding/2026-10-23_lifecycle-concern-grid.md
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the write API over one store.
func New ¶
New builds a Server. token must be non-empty: the API refuses to start without one (fail closed, unlike the dashboard's loopback exemption).
func (*Server) CloseReadModel ¶ added in v0.4.0
func (s *Server) CloseReadModel()
CloseReadModel releases the read-model surfaces UseReadModel armed, in the production close order (pump host, then DLQ sidecar, then the model itself). ListenAndServe owns this for the serve window; a caller that never serves (tests, embedded stats-only mounts) must call it or the projection home and sidecar handles leak (an open handle blocks t.TempDir cleanup on windows with an unlinkat refusal).
func (*Server) ListenAndServe ¶
ListenAndServe starts the API on addr (e.g. "127.0.0.1:8091") until ctx is cancelled. It owns the read model's lifetime when UseReadModel ran: the managed projection host tails the journal (platform restart budget and poison-fact DLQ) for the whole serve window, and the projection closes after the HTTP server has fully stopped.
func (*Server) UseErrorRecorder ¶ added in v0.3.4
UseErrorRecorder arms POST /api/v1/errors with the ReportError command handler (ADR-0021). Without it the route answers 503, so a producer learns the surface is disabled instead of silently dropping reports. The recorder appends error.observed facts only — reactions (fix-task minting) belong to the incident policy running in the pool.
func (*Server) UseReadModel ¶ added in v0.3.1
UseReadModel moves the stats read onto the ADR-0019 S3 metaengine read model beside the deployment's queue db (readmodel.PathFor derives the projection home): the projection folds the journal and GET /api/v1/stats reads its planned table. The enqueue side is untouched — the model is read-only over the store.
The pump is the MANAGED projection host (readmodel.NewProjectionHost) built from the same readmodel seams the composition root bundles for serve: ListenAndServe starts it and owns its lifetime, a poison fact dead-letters into the best-effort DLQ sidecar (OpenDeadLetters, warn-and-continue) and the fold keeps converging, and a retryable failure restarts under the platform budget instead of wedging the cursor at repeated error logs. The model itself stays self-opened — the sanctioned per-surface exception to the composition single-opener seam (no NewProjectionRuntime adoption, no composition import, no double-close; this surface never needed the never-started runtime host, only the pump protection). Decision record: docs/memos/2026-10-10_readmodel-open-seams.md ("Residual resolved").
Source Files