api

package
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package api implements the HTTP API surface on Chi: REST CRUD handlers, RPC method dispatch, the Metadata API, and the middleware chain (CORS → Auth → RateLimit → Permission → Handler).

See TAD §3.2, §9.2 and PRD §14 for the full specification. Implemented in Phase 6.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewRouter 

func NewRouter(opts RouterOptions) *chi.Mux

NewRouter constructs a Chi HTTP router with the middleware chain in PRD §12.2 order: CORS → Auth → Rate Limit → Permission → Handler

func RegisterMethod 

func RegisterMethod(name string, h MethodHandler, opts MethodOpts)

RegisterMethod registers a custom RPC method in the global RPC registry per PRD §14.3 / TAD §9.2.

func RespondError 

func RespondError(w http.ResponseWriter, err error)

func RespondJSON 

func RespondJSON(w http.ResponseWriter, status int, data any, meta *MetaDetails)

Types

type AgentHandler 

type AgentHandler struct {
	// Base holds the runtime options shared across connections. Sink and
	// Approvals are per-connection and filled in by Stream.
	Base runtime.Options
	// AllowedOrigins is the browser-origin allowlist for the upgrade request,
	// sourced from the same CORSOrigins list that governs the HTTP API
	// (PRD §12.2). It backs the WebSocket origin check; "*" allows any origin.
	AllowedOrigins []string
	// ApprovalTimeout bounds one approval round trip on an idle connection
	// (0 = defaultApprovalTimeout).
	ApprovalTimeout time.Duration
}

AgentHandler serves the agent chat WebSocket endpoint (TAD §6.2): WS /api/v1/agent/stream. Client → server messages follow the §6.2 contract (message / approval_response); the runtime's streaming events are forwarded verbatim as server → client messages, including the extended §12.3 approval_required payload with policy_reason.

func (*AgentHandler) Stream 

func (h *AgentHandler) Stream(w http.ResponseWriter, r *http.Request)

Stream upgrades the connection and runs the §6.2 message loop.

type AuthHandler 

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

AuthHandler serves the built-in email/password login flow (PRD §15.1). Credential verification reads the User/Role tables directly through the DAL — deliberately bypassing the Document Engine, whose permission checks would deny an as-yet-unauthenticated caller (PRD §25.1 applies to already-known identities; login is the one path that must mint an identity from a secret).

func NewAuthHandler 

func NewAuthHandler(db dal.Database, reg schema.Registry, p auth.Provider) *AuthHandler

NewAuthHandler builds the login/refresh handler. enabled is false when the configured auth.Provider cannot issue tokens, in which case the routes are not mounted.

func (*AuthHandler) Login 

func (h *AuthHandler) Login(w http.ResponseWriter, r *http.Request)

Login handles POST /api/v1/auth/login.

func (*AuthHandler) Refresh 

func (h *AuthHandler) Refresh(w http.ResponseWriter, r *http.Request)

Refresh handles POST /api/v1/auth/refresh, rotating a refresh token.

type DocMetaResponse 

type DocMetaResponse struct {
	Name        string          `json:"name"`
	TitleField  string          `json:"title_field"`
	Searchable  bool            `json:"searchable"`
	Submittable bool            `json:"submittable"`
	Icon        string          `json:"icon,omitempty"`
	Description string          `json:"description,omitempty"`
	Fields      []FieldMeta     `json:"fields"`
	Permissions PermissionsMeta `json:"permissions"`
}

type ErrorDetail 

type ErrorDetail = render.ErrorDetail

type FieldMeta 

type FieldMeta struct {
	Name       string   `json:"name"`
	Column     string   `json:"db_column"`
	Type       string   `json:"type"`
	Label      string   `json:"label"`
	Required   bool     `json:"required"`
	Options    []string `json:"options,omitempty"`
	LinkTarget string   `json:"link,omitempty"`
	Hidden     bool     `json:"hidden"`
	ReadOnly   bool     `json:"read_only,omitempty"`
}

type MetaDetails 

type MetaDetails = render.MetaDetails

type MetaHandler 

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

func NewMetaHandler 

func NewMetaHandler(reg schema.Registry, permEngine perm.Engine) *MetaHandler

func (*MetaHandler) GetDocMeta 

func (h *MetaHandler) GetDocMeta(w http.ResponseWriter, r *http.Request)

GetDocMeta handles GET /api/v1/meta/{doctype} 

func (h *MetaHandler) GetLinks(w http.ResponseWriter, r *http.Request)

GetLinks handles GET /api/v1/meta/{doctype}/links

func (*MetaHandler) ListDocTypes 

func (h *MetaHandler) ListDocTypes(w http.ResponseWriter, r *http.Request)

ListDocTypes handles GET /api/v1/meta

type MethodHandler 

type MethodHandler = rpc.MethodHandler

type MethodOpts 

type MethodOpts = rpc.MethodOpts

type PagesHandler 

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

PagesHandler serves the registered ui.Pages as JSON for the Admin UI shell.

func NewPagesHandler 

func NewPagesHandler(reg ui.Registry) *PagesHandler

NewPagesHandler keeps a reference to the ui.Registry so late registrations (e.g. an Application registering pages after route assembly) are visible.

func (*PagesHandler) List 

func (h *PagesHandler) List(w http.ResponseWriter, r *http.Request)

List handles GET /api/v1/meta/pages.

type PermissionsMeta 

type PermissionsMeta struct {
	CanRead   bool `json:"can_read"`
	CanWrite  bool `json:"can_write"`
	CanCreate bool `json:"can_create"`
	CanDelete bool `json:"can_delete"`
}

type ResponseEnvelope 

type ResponseEnvelope = render.ResponseEnvelope

type RouterOptions 

type RouterOptions struct {
	CORSOrigins  []string
	AuthProvider auth.Provider
	RateLimit    int
	RateWindow   time.Duration
	Cache        cache.Store
	PermEngine   perm.Engine
	Registry     schema.Registry
	DocEngine    *document.Engine
	// Database is required to mount the built-in login/refresh routes
	// (PRD §15.1); when nil the routes are skipped.
	Database dal.Database
	// Pages carries ui.Page registrations surfaced by GET /api/v1/meta/pages
	// for the Admin UI sidebar (PRD §18.3). Nil skips the route.
	Pages ui.Registry
	// AgentRuntime carries the shared runtime options for the agent chat
	// WebSocket; when nil the /api/v1/agent/stream route is not mounted.
	// Sink and Approvals are per-connection and need not be set here.
	AgentRuntime *runtime.Options
}

RouterOptions holds dependencies required for mounting API routes.

Source Files

View all Source files

Directories

Path Synopsis
Package middleware contains the Chi middleware stack applied to every incoming HTTP request: CORS, Auth (JWT extraction), Rate Limit, and Permission (perm.Engine.CheckAction).
 Package middleware contains the Chi middleware stack applied to every incoming HTTP request: CORS, Auth (JWT extraction), Rate Limit, and Permission (perm.Engine.CheckAction).
Package render provides HTTP response serialization and standardized error formatting.
 Package render provides HTTP response serialization and standardized error formatting.
Package rest contains the REST handler implementations for the six standard Document operations (list, get, create, update, delete, submit).
 Package rest contains the REST handler implementations for the six standard Document operations (list, get, create, update, delete, submit).
Package rpc dispatches POST /api/v1/method/{app}.{module}.{method} requests to registered api.MethodHandler implementations, enforcing AllowedRoles through the shared perm.Engine path (TAD §9.2).
 Package rpc dispatches POST /api/v1/method/{app}.{module}.{method} requests to registered api.MethodHandler implementations, enforcing AllowedRoles through the shared perm.Engine path (TAD §9.2).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.