Documentation
¶
Overview ¶
Package api implements the REST management surface /api/v1 (a V1 compatibility contract — additive only, docs/architecture/api.md): token auth with scopes, one error envelope, cursor pagination, idempotency keys, rate limits, durable webhook management, and hand-authored OpenAPI kept accurate by a route-coverage test.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PruneIdempotency ¶
PruneIdempotencyKeys deletes idempotency rows whose replay window has passed (24 h TTL — the documented replay horizon). It is the scheduler- callable surface of the idempotency store; rows claimed while a request is in flight never pass the TTL before their release, so pruning is always safe in housekeeping.
Types ¶
type Deps ¶
type Deps struct {
DB *database.DB
Tokens *token.Service
Users *user.Service
Devices *device.Service
Plans *plan.Service
Ifaces *iface.Service
Settings *settings.Registry
Ring *secrets.KeyRing
Audit *audit.Service
Accounting *accounting.Service
Webhooks *webhook.Service
Metrics *metrics.Collector
Telemetry *telemetry.Sampler
Links *subscription.Service
Integration *integration.Service
Log *slog.Logger
// ClientConf renders client configs + QR (shared with the web panel).
ClientConf *clientconf.Renderer
// Reconciler runs after structural mutations so tunnel, peer, firewall,
// NAT and shaping state take effect together. Serve supplies the full
// boot.RuntimeReconciler behind one serialization lock. Nil = status-only
// (tests without a backend).
Reconciler accounting.Reconciler
NodeStatus func(context.Context, time.Time) nodestatus.Snapshot
// NodeID and ToolsVersion populate /node.
NodeID string
ToolsVersion string
}
Deps wires everything the REST surface needs. Nil-able collaborators (audit, metrics, accounting) degrade gracefully for tests.
type Envelope ¶
type Envelope struct {
Error ErrorBody `json:"error"`
}
Envelope is the single error shape of the API. Codes are the stable machine codes of internal/domain; messages are human-readable; request_id correlates with logs (never stack traces — security.md).
type Server ¶
type Server struct {
Deps
// contains filtered or unexported fields
}
Server is the REST API server. Handlers are registered once; the route table doubles as the OpenAPI coverage input.
func (*Server) Reload ¶
func (s *Server) Reload()
Reload re-reads runtime-tunable API settings (the per-token rate limit) from the registry and drops expired rate-limit windows. The serve housekeeping job calls it so a settings PATCH takes effect without a restart and the limiter map stays bounded by active tokens.
Source Files