api

Documentation

Overview

Package api implements the v1.3+ REST API. Routes mount under /api/v1. The API is JSON-only, returns a consistent error envelope {"error":"..."} on every non-2xx, supports pagination via ?page + ?per_page query params, and emits ETag headers for cacheable read endpoints so well-behaved clients (and the v1.4 studio UI) skip re-rendering identical responses.

Auth: every route is gated on either a session cookie (browser flows) or a Bearer token with the right scope (machine flows). The Mount() function wires both middlewares; downstream handlers resolve the actor via auth.TokenFromContext + auth.FromContext.

Index

• type API
  • func New(st *store.Store, users *auth.Users, tokens *auth.Tokens, ...) *API
  • func (a *API) Mount(r chi.Router)
  • func (a *API) WithCache(c *respcache.Cache) *API
  • func (a *API) WithEvents(p *events.Producer) *API
• type Cursor
  • func (c Cursor) Encode() string
  • func (c Cursor) IsZero() bool

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API is the surface the daemon mounts onto its chi router. Holds references to the persistence + auth dependencies the handlers need.

func New

func New(st *store.Store, users *auth.Users, tokens *auth.Tokens, sessions *auth.Sessions) *API

New constructs the API handle. The Mount() method wires every route on r under the /api/v1 prefix.

func (*API) Mount

func (a *API) Mount(r chi.Router)

Mount installs the v1 routes on r. Phase 6 ships the read surface; phase 7 layers the write endpoints on this same prefix. Phase 11 (UI shell) calls Mount before starting the server.

func (*API) WithCache

func (a *API) WithCache(c *respcache.Cache) *API

WithCache installs the v1.11 phase 6 LRU response cache. Returns the receiver for chaining. When set, hot list responses are served from cache (60s TTL, busted on SSE mutation events). Nil/unset means every request hits the DB — the v1.10 default.

func (*API) WithEvents

func (a *API) WithEvents(p *events.Producer) *API

WithEvents installs the v1.6 SSE Producer. Returns the receiver for chaining. When set, the /api/v1/events route is mounted; otherwise it 404s and the daemon's polling paths still work.

type Cursor

type Cursor struct {
	SortKey string `json:"k"` // RFC3339 timestamp or other monotonic key
	ID      string `json:"i"`
}

Cursor is the opaque pagination token. SortKey + ID together form the (last-row-of-previous-page) tuple; the next query selects rows strictly after this pair under the documented sort order.

func (Cursor) Encode

func (c Cursor) Encode() string

Encode returns the opaque base64 token. Empty cursor returns "".

func (Cursor) IsZero

func (c Cursor) IsZero() bool

IsZero reports whether the cursor is empty — first-page request.