api

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: May 16, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package api implements the HTTP API server for Resin.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AuthMiddleware 

func AuthMiddleware(adminToken string, next http.Handler) http.Handler

AuthMiddleware returns an http.Handler that validates the Bearer token in the Authorization header against the expected admin token. If validation fails, it returns 401 Unauthorized with a JSON error body.

func DecodeBody 

func DecodeBody(r *http.Request, v interface{}) error

DecodeBody decodes the JSON request body into v, rejecting unknown fields.

func HandleCleanupSubscriptionCircuitOpenNodes 

func HandleCleanupSubscriptionCircuitOpenNodes(cp *service.ControlPlaneService) http.HandlerFunc

HandleCleanupSubscriptionCircuitOpenNodes returns a handler for POST /api/v1/subscriptions/{id}/actions/cleanup-circuit-open-nodes.

func HandleCreatePlatform 

func HandleCreatePlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleCreatePlatform returns a handler for POST /api/v1/platforms.

func HandleCreateSubscription 

func HandleCreateSubscription(cp *service.ControlPlaneService) http.HandlerFunc

HandleCreateSubscription returns a handler for POST /api/v1/subscriptions.

func HandleDeleteAllLeases 

func HandleDeleteAllLeases(cp *service.ControlPlaneService) http.HandlerFunc

HandleDeleteAllLeases returns a handler for DELETE /api/v1/platforms/{id}/leases.

func HandleDeleteLease 

func HandleDeleteLease(cp *service.ControlPlaneService) http.HandlerFunc

HandleDeleteLease returns a handler for DELETE /api/v1/platforms/{id}/leases/{account}.

func HandleDeletePlatform 

func HandleDeletePlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleDeletePlatform returns a handler for DELETE /api/v1/platforms/{id}.

func HandleDeleteRule 

func HandleDeleteRule(cp *service.ControlPlaneService) http.HandlerFunc

HandleDeleteRule returns a handler for DELETE /api/v1/account-header-rules/{prefix}.

func HandleDeleteSubscription 

func HandleDeleteSubscription(cp *service.ControlPlaneService) http.HandlerFunc

HandleDeleteSubscription returns a handler for DELETE /api/v1/subscriptions/{id}.

func HandleGeoIPLookup 

func HandleGeoIPLookup(cp *service.ControlPlaneService) http.HandlerFunc

HandleGeoIPLookup returns a handler for GET /api/v1/geoip/lookup.

func HandleGeoIPLookupPost 

func HandleGeoIPLookupPost(cp *service.ControlPlaneService) http.HandlerFunc

HandleGeoIPLookupPost returns a handler for POST /api/v1/geoip/lookup (batch).

func HandleGeoIPStatus 

func HandleGeoIPStatus(cp *service.ControlPlaneService) http.HandlerFunc

HandleGeoIPStatus returns a handler for GET /api/v1/geoip/status.

func HandleGeoIPUpdate 

func HandleGeoIPUpdate(cp *service.ControlPlaneService) http.HandlerFunc

HandleGeoIPUpdate returns a handler for POST /api/v1/geoip/actions/update-now.

func HandleGetLease 

func HandleGetLease(cp *service.ControlPlaneService) http.HandlerFunc

HandleGetLease returns a handler for GET /api/v1/platforms/{id}/leases/{account}.

func HandleGetNode 

func HandleGetNode(cp *service.ControlPlaneService) http.HandlerFunc

HandleGetNode returns a handler for GET /api/v1/nodes/{hash}.

func HandleGetPlatform 

func HandleGetPlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleGetPlatform returns a handler for GET /api/v1/platforms/{id}.

func HandleGetRequestLog 

func HandleGetRequestLog(repo *requestlog.Repo) http.Handler

HandleGetRequestLog handles GET /api/v1/request-logs/{log_id}.

func HandleGetRequestLogPayloads 

func HandleGetRequestLogPayloads(repo *requestlog.Repo) http.Handler

HandleGetRequestLogPayloads handles GET /api/v1/request-logs/{log_id}/payloads. Returns base64-encoded payloads with truncation metadata.

func HandleGetSubscription 

func HandleGetSubscription(cp *service.ControlPlaneService) http.HandlerFunc

HandleGetSubscription returns a handler for GET /api/v1/subscriptions/{id}.

func HandleHealthz 

func HandleHealthz() http.HandlerFunc

HandleHealthz returns a handler for GET /healthz. No authentication is required.

func HandleHistoryAccessLatency 

func HandleHistoryAccessLatency(mgr *metrics.Manager) http.Handler

HandleHistoryAccessLatency handles GET /api/v1/metrics/history/access-latency.

func HandleHistoryLeaseLifetime 

func HandleHistoryLeaseLifetime(mgr *metrics.Manager) http.Handler

HandleHistoryLeaseLifetime handles GET /api/v1/metrics/history/lease-lifetime.

func HandleHistoryNodePool 

func HandleHistoryNodePool(mgr *metrics.Manager) http.Handler

HandleHistoryNodePool handles GET /api/v1/metrics/history/node-pool.

func HandleHistoryProbes 

func HandleHistoryProbes(mgr *metrics.Manager) http.Handler

HandleHistoryProbes handles GET /api/v1/metrics/history/probes.

func HandleHistoryRequests 

func HandleHistoryRequests(mgr *metrics.Manager) http.Handler

HandleHistoryRequests handles GET /api/v1/metrics/history/requests.

func HandleHistoryTraffic 

func HandleHistoryTraffic(mgr *metrics.Manager) http.Handler

HandleHistoryTraffic handles GET /api/v1/metrics/history/traffic.

func HandleIPLoad 

func HandleIPLoad(cp *service.ControlPlaneService) http.HandlerFunc

HandleIPLoad returns a handler for GET /api/v1/platforms/{id}/ip-load.

func HandleListLeases 

func HandleListLeases(cp *service.ControlPlaneService) http.HandlerFunc

HandleListLeases returns a handler for GET /api/v1/platforms/{id}/leases.

func HandleListNodes 

func HandleListNodes(cp *service.ControlPlaneService) http.HandlerFunc

HandleListNodes returns a handler for GET /api/v1/nodes.

func HandleListPlatforms 

func HandleListPlatforms(cp *service.ControlPlaneService) http.HandlerFunc

HandleListPlatforms returns a handler for GET /api/v1/platforms.

func HandleListRequestLogs 

func HandleListRequestLogs(repo *requestlog.Repo) http.Handler

HandleListRequestLogs handles GET /api/v1/request-logs. Query params: from, to (RFC3339Nano), limit, cursor, platform_id, platform_name, account, target_host, egress_ip, proxy_type, net_ok, http_status, fuzzy.

func HandleListRules 

func HandleListRules(cp *service.ControlPlaneService) http.HandlerFunc

HandleListRules returns a handler for GET /api/v1/account-header-rules.

func HandleListSubscriptions 

func HandleListSubscriptions(cp *service.ControlPlaneService) http.HandlerFunc

HandleListSubscriptions returns a handler for GET /api/v1/subscriptions.

func HandlePatchSystemConfig 

func HandlePatchSystemConfig(cp *service.ControlPlaneService) http.HandlerFunc

HandlePatchSystemConfig returns a handler for PATCH /api/v1/system/config.

func HandlePreviewFilter 

func HandlePreviewFilter(cp *service.ControlPlaneService) http.HandlerFunc

HandlePreviewFilter returns a handler for POST /api/v1/platforms/preview-filter.

func HandleProbeEgress 

func HandleProbeEgress(cp *service.ControlPlaneService) http.HandlerFunc

HandleProbeEgress returns a handler for POST /api/v1/nodes/{hash}/actions/probe-egress.

func HandleProbeLatency 

func HandleProbeLatency(cp *service.ControlPlaneService) http.HandlerFunc

HandleProbeLatency returns a handler for POST /api/v1/nodes/{hash}/actions/probe-latency.

func HandleRealtimeConnections 

func HandleRealtimeConnections(mgr *metrics.Manager) http.Handler

HandleRealtimeConnections handles GET /api/v1/metrics/realtime/connections.

func HandleRealtimeLeases 

func HandleRealtimeLeases(mgr *metrics.Manager) http.Handler

HandleRealtimeLeases handles GET /api/v1/metrics/realtime/leases.

func HandleRealtimeThroughput 

func HandleRealtimeThroughput(mgr *metrics.Manager) http.Handler

HandleRealtimeThroughput handles GET /api/v1/metrics/realtime/throughput.

func HandleRebuildPlatform 

func HandleRebuildPlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleRebuildPlatform returns a handler for POST /api/v1/platforms/{id}/actions/rebuild-routable-view.

func HandleRefreshSubscription 

func HandleRefreshSubscription(cp *service.ControlPlaneService) http.HandlerFunc

HandleRefreshSubscription returns a handler for POST /api/v1/subscriptions/{id}/actions/refresh.

func HandleResetPlatform 

func HandleResetPlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleResetPlatform returns a handler for POST /api/v1/platforms/{id}/actions/reset-to-default.

func HandleResolveRule 

func HandleResolveRule(cp *service.ControlPlaneService) http.HandlerFunc

HandleResolveRule returns a handler for POST /api/v1/account-header-rules:resolve.

func HandleSnapshotNodeLatencyDistribution 

func HandleSnapshotNodeLatencyDistribution(mgr *metrics.Manager) http.Handler

HandleSnapshotNodeLatencyDistribution handles GET /api/v1/metrics/snapshots/node-latency-distribution. This returns a histogram of per-node authority-domain EWMA latencies, NOT the per-request access latency stored in the Collector.

func HandleSnapshotNodePool 

func HandleSnapshotNodePool(mgr *metrics.Manager) http.Handler

HandleSnapshotNodePool handles GET /api/v1/metrics/snapshots/node-pool.

func HandleSnapshotPlatformNodePool 

func HandleSnapshotPlatformNodePool(mgr *metrics.Manager) http.Handler

HandleSnapshotPlatformNodePool handles GET /api/v1/metrics/snapshots/platform-node-pool.

func HandleSystemConfig 

func HandleSystemConfig(runtimeCfg *atomic.Pointer[config.RuntimeConfig]) http.HandlerFunc

HandleSystemConfig returns a handler for GET /api/v1/system/config.

func HandleSystemDefaultConfig 

func HandleSystemDefaultConfig() http.HandlerFunc

HandleSystemDefaultConfig returns a handler for GET /api/v1/system/config/default.

func HandleSystemEnvConfig 

func HandleSystemEnvConfig(envCfg *config.EnvConfig) http.HandlerFunc

HandleSystemEnvConfig returns a handler for GET /api/v1/system/config/env.

func HandleSystemInfo 

func HandleSystemInfo(info service.SystemInfo) http.HandlerFunc

HandleSystemInfo returns a handler for GET /api/v1/system/info.

func HandleUpdatePlatform 

func HandleUpdatePlatform(cp *service.ControlPlaneService) http.HandlerFunc

HandleUpdatePlatform returns a handler for PATCH /api/v1/platforms/{id}.

func HandleUpdateSubscription 

func HandleUpdateSubscription(cp *service.ControlPlaneService) http.HandlerFunc

HandleUpdateSubscription returns a handler for PATCH /api/v1/subscriptions/{id}.

func HandleUpsertRule 

func HandleUpsertRule(cp *service.ControlPlaneService) http.HandlerFunc

HandleUpsertRule returns a handler for:

  • PUT /api/v1/account-header-rules/{prefix...}

func NewTokenActionHandler 

func NewTokenActionHandler(proxyToken string, cp *service.ControlPlaneService, apiMaxBodyBytes int64) http.Handler

NewTokenActionHandler returns the handler for token-path actions.

func PaginateSlice 

func PaginateSlice[T any](items []T, p Pagination) []T

PaginateSlice applies limit/offset to a slice and returns the page.

func ParseBoolQuery 

func ParseBoolQuery(r *http.Request, key string) (*bool, error)

ParseBoolQuery parses an optional boolean query parameter. Returns nil when the parameter is not present.

func PathParam 

func PathParam(r *http.Request, name string) string

PathParam extracts a named path parameter from the request URL. Works with Go 1.22+ ServeMux pattern matching (e.g. /platforms/{id}).

func RequestBodyLimitMiddleware 

func RequestBodyLimitMiddleware(maxBytes int64, next http.Handler) http.Handler

RequestBodyLimitMiddleware enforces a max request body size for downstream handlers.

func SortSlice 

func SortSlice[T any](items []T, sort Sorting, keyFn func(T) string)

SortSlice sorts items in place by the given key extractor and sort order. keyFn must return a comparable string value for sorting.

func ValidateUUID 

func ValidateUUID(s string) bool

ValidateUUID checks that s is a valid lowercase canonical UUID string.

func WriteError 

func WriteError(w http.ResponseWriter, status int, code, message string)

WriteError writes a standard error response.

func WriteJSON 

func WriteJSON(w http.ResponseWriter, status int, data any)

WriteJSON writes a JSON response with the given status code.

func WritePage 

func WritePage[T any](w http.ResponseWriter, status int, allItems []T, p Pagination)

WritePage writes a paginated list response.

Types

type ErrorDetail 

type ErrorDetail struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorDetail contains the error code and human-readable message.

type ErrorResponse 

type ErrorResponse struct {
	Error ErrorDetail `json:"error"`
}

ErrorResponse is the standard error envelope.

type PageResponse 

type PageResponse[T any] struct {
	Items  []T `json:"items"`
	Total  int `json:"total"`
	Limit  int `json:"limit"`
	Offset int `json:"offset"`
}

PageResponse is the standard list envelope for paginated endpoints.

type Pagination 

type Pagination struct {
	Limit  int
	Offset int
}

Pagination holds parsed limit/offset values.

func ParsePagination 

func ParsePagination(r *http.Request) (Pagination, error)

ParsePagination reads limit and offset from query parameters.

type Server 

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

Server wraps the HTTP server and mux for the Resin API.

func NewServer 

func NewServer(
	port int,
	adminToken string,
	systemInfo service.SystemInfo,
	runtimeCfg *atomic.Pointer[config.RuntimeConfig],
	envCfg *config.EnvConfig,
	cp *service.ControlPlaneService,
	apiMaxBodyBytes int64,
	requestlogRepo *requestlog.Repo,
	metricsManager *metrics.Manager,
) *Server

NewServer creates a new API server wired with all routes. cp may be nil if the control plane is not yet initialized.

func NewServerWithAddress 

func NewServerWithAddress(
	listenAddress string,
	port int,
	adminToken string,
	systemInfo service.SystemInfo,
	runtimeCfg *atomic.Pointer[config.RuntimeConfig],
	envCfg *config.EnvConfig,
	cp *service.ControlPlaneService,
	apiMaxBodyBytes int64,
	requestlogRepo *requestlog.Repo,
	metricsManager *metrics.Manager,
) *Server

NewServerWithAddress creates a new API server with an explicit listen address.

func (*Server) Handler 

func (s *Server) Handler() http.Handler

Handler returns the underlying http.Handler for testing.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe() error

ListenAndServe starts the HTTP server. It blocks until the server stops.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server.

type Sorting 

type Sorting struct {
	SortBy    string
	SortOrder string // "asc" or "desc"
}

Sorting holds parsed sort_by and sort_order values.

func ParseSorting 

func ParseSorting(r *http.Request, allowed []string, defaultField, defaultOrder string) (Sorting, error)

ParseSorting reads sort_by and sort_order from query parameters.

Source Files

View all Source files

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.