Documentation
¶
Overview ¶
Package api exposes the HTTP handlers shared by the server mux (internal/platform/server) and the local serve mux (internal/http). It depends only on internal/domain and the standard library, so both muxes can import it without crossing the server-track architecture boundary (REQ-SH-010).
Index ¶
- Variables
- type Handlers
- func (h *Handlers) AgentProjects(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) Me(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) ProjectGraph(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) Projects(w http.ResponseWriter, r *http.Request)
- func (h *Handlers) Stats(w http.ResponseWriter, r *http.Request)
- type Port
- type Principal
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnauthenticated selects the 401 unauthorized envelope. ErrUnauthenticated = errors.New("api: unauthenticated") // ErrForbidden selects the 403 forbidden envelope. ErrForbidden = errors.New("api: forbidden") )
Sentinel errors a Port implementation returns to select a response contract. Adapters translate their own error vocabulary (missing credentials, authorization denials, store failures) into these so the emitted envelope stays identical on both muxes without this package importing their types.
Functions ¶
This section is empty.
Types ¶
type Handlers ¶
type Handlers struct {
// contains filtered or unexported fields
}
Handlers serves the parity endpoints over a single Port.
func (*Handlers) AgentProjects ¶
func (h *Handlers) AgentProjects(w http.ResponseWriter, r *http.Request)
AgentProjects serves GET /api/agent/projects. It reproduces the server handler (internal/platform/server/agent_http.go:34-52): no-store headers, the project map flattened to {id,label} entries sorted by label then id, all wrapped under a single "projects" key.
func (*Handlers) Me ¶
func (h *Handlers) Me(w http.ResponseWriter, r *http.Request)
Me serves GET /api/me. The envelope reproduces the pre-extraction server response: the principalResponse fields (internal/platform/server/http.go:1526) plus the optional workspace_id, display_name and email keys the server me handler added (internal/platform/server/http.go:437-458).
func (*Handlers) ProjectGraph ¶
func (h *Handlers) ProjectGraph(w http.ResponseWriter, r *http.Request)
ProjectGraph serves GET /api/graph/project-graph. It parses the project selector plus the depth/max_nodes bounds, delegates the traversal to the Port (store-backed in server mode, BFS in local mode) and serializes the returned domain.GraphSubgraph unchanged.
A nil subgraph with no error means "no graph for this project" (an unknown project, or a traversal whose per-node lookups all failed). The server handler tolerated those and still answered with the root-labelled empty envelope, so the same 200 shape is emitted here rather than a null body.
func (*Handlers) Projects ¶
func (h *Handlers) Projects(w http.ResponseWriter, r *http.Request)
Projects serves GET /api/projects. The pre-extraction server handler (internal/platform/server/http.go:657-664) wrote the ListProjects []string verbatim, so a nil list must still serialize as null.
func (*Handlers) Stats ¶
func (h *Handlers) Stats(w http.ResponseWriter, r *http.Request)
Stats serves GET /api/stats. The pre-extraction server handler (internal/platform/server/http.go:621-628) wrote the Operations result verbatim and ignored the query string, so the neutral handler serializes domain.ServerStats untouched and reads no parameters.
type Port ¶
type Port interface {
CurrentPrincipal(ctx context.Context) (Principal, error)
ServerStats(ctx context.Context) (*domain.ServerStats, error)
Projects(ctx context.Context) ([]string, error)
AgentProjects(ctx context.Context) (map[string]string, error)
ProjectGraph(ctx context.Context, projectID string, depth, maxNodes int) (*domain.GraphSubgraph, error)
}
Port is the complete surface these handlers need from their host mux. Server mode backs it with the request-scoped Operations; local mode derives it from the SQLite bundle.
type Principal ¶
type Principal struct {
Identity domain.Principal
WorkspaceID string
DisplayName string
Email string
}
Principal is the neutral projection of the authenticated identity plus the optional enrichment the /api/me envelope may carry. Identity reuses domain.Principal so the base field serialization is byte-identical to the pre-extraction server response; WorkspaceID, DisplayName and Email stay empty when the backing mux has nothing to enrich.
Source Files