Documentation
¶
Overview ¶
Package api provides the HTTP API server for the lunar platform.
The API implements the OpenAPI specification defined in docs/openapi.yaml and provides endpoints for managing functions, versions, executions, and runtime execution.
Main endpoint groups:
- /api/functions - Function management (CRUD)
- /api/functions/{id}/versions - Version management
- /api/executions - Execution history and logs
- /fn/{function_id} - Runtime function execution
Index ¶
- Constants
- Variables
- func ActivateVersionHandler(database store.DB) http.HandlerFunc
- func AuthMiddleware(apiKey string, db store.DB) func(http.Handler) http.Handler
- func CORSMiddleware(next http.Handler) http.Handler
- func Chain(h http.Handler, middlewares ...Middleware) http.Handler
- func CreateFunctionHandler(database store.DB) http.HandlerFunc
- func DeleteFunctionHandler(database store.DB) http.HandlerFunc
- func DeleteVersionHandler(database store.DB) http.HandlerFunc
- func ExecuteFunctionHandler(deps ExecuteFunctionDeps) http.HandlerFunc
- func GetExecutionAIRequestsHandler(database store.DB, aiTracker ai.Tracker) http.HandlerFunc
- func GetExecutionEmailRequestsHandler(database store.DB, emailTracker email.Tracker) http.HandlerFunc
- func GetExecutionHandler(database store.DB) http.HandlerFunc
- func GetExecutionLogsHandler(database store.DB, appLogger logger.Logger) http.HandlerFunc
- func GetFunctionHandler(database store.DB, envStore env.Store, kvStore kv.Store) http.HandlerFunc
- func GetNextRunHandler(database store.DB) http.HandlerFunc
- func GetVersionDiffHandler(database store.DB) http.HandlerFunc
- func GetVersionHandler(database store.DB) http.HandlerFunc
- func HandleDeviceApprove(deviceStore *DeviceAuthStore, db store.DB) http.HandlerFunc
- func HandleDeviceApproveStatus(deviceStore *DeviceAuthStore) http.HandlerFunc
- func HandleDeviceRequest(deviceStore *DeviceAuthStore, baseURL string) http.HandlerFunc
- func HandleDeviceToken(deviceStore *DeviceAuthStore) http.HandlerFunc
- func HandleListAPITokens(db store.DB) http.HandlerFunc
- func HandleLogin(apiKey string) http.HandlerFunc
- func HandleLogout() http.HandlerFunc
- func HandleRevokeAPIToken(db store.DB) http.HandlerFunc
- func ListExecutionsHandler(database store.DB) http.HandlerFunc
- func ListFunctionsHandler(database store.DB) http.HandlerFunc
- func ListVersionsHandler(database store.DB) http.HandlerFunc
- func LoggingMiddleware(next http.Handler) http.Handler
- func RecoveryMiddleware(next http.Handler) http.Handler
- func UpdateEnvVarsHandler(database store.DB, envStore env.Store) http.HandlerFunc
- func UpdateFunctionHandler(database store.DB, scheduler *internalcron.FunctionScheduler) http.HandlerFunc
- func UpdateKvStoreHandler(database store.DB, kvStore kv.Store) http.HandlerFunc
- func ValidateCreateFunctionRequest(req *CreateFunctionRequest) error
- func ValidateUpdateEnvVarsRequest(req *UpdateEnvVarsRequest) error
- func ValidateUpdateFunctionRequest(req *store.UpdateFunctionRequest) error
- func ValidateUpdateKvStoreRequest(req *UpdateKvStoreRequest) error
- type CreateFunctionRequest
- type DeviceApproveRequest
- type DeviceApproveStatusResponse
- type DeviceAuthStore
- type DeviceRequestResponse
- type DeviceTokenResponse
- type DiffLine
- type DiffLineType
- type ErrorResponse
- type ExecuteFunctionDeps
- type ExecutionWithLogs
- type ListExecutionsResponse
- type ListFunctionsResponse
- type ListVersionsResponse
- type LogEntry
- type LogLevel
- type LoginRequest
- type LoginResponse
- type Middleware
- type NextRunResponse
- type PaginatedAIRequestsResponse
- type PaginatedEmailRequestsResponse
- type PaginatedExecutionWithLogs
- type PaginatedExecutionsResponse
- type PaginatedFunctionsResponse
- type PaginatedLogsResponse
- type PaginatedVersionsResponse
- type PendingAuth
- type PendingAuthStatus
- type Server
- type ServerConfig
- type UpdateEnvVarsRequest
- type UpdateKvStoreRequest
- type ValidationError
- type VersionDiffResponse
Constants ¶
const ( // MaxPageSize is the maximum allowed page size for pagination MaxPageSize = 100 // MaxFunctionNameLength is the maximum length for function names MaxFunctionNameLength = 100 // MaxDescriptionLength is the maximum length for function descriptions MaxDescriptionLength = 500 // MaxCodeLength is the maximum length for function code MaxCodeLength = 1024 * 1024 // 1MB // MaxEnvVarKeyLength is the maximum length for environment variable keys MaxEnvVarKeyLength = 100 // MaxEnvVarValueLength is the maximum length for environment variable values MaxEnvVarValueLength = 10000 // MaxEnvVars is the maximum number of environment variables per function MaxEnvVars = 100 // MaxStoreKeyLength is the maximum length for store keys MaxStoreKeyLength = 100 // MaxStoreValueLength is the maximum length for store values MaxStoreValueLength = 10000 )
Variables ¶
var AllowedCronStatuses = []string{string(store.CronStatusActive), string(store.CronStatusPaused)}
var AllowedRetentionDays = []int{7, 15, 30, 365}
Functions ¶
func ActivateVersionHandler ¶
func ActivateVersionHandler(database store.DB) http.HandlerFunc
ActivateVersionHandler returns a handler for activating a version
func AuthMiddleware ¶
AuthMiddleware validates authentication via cookie or Bearer token. It checks the admin API key first, then falls back to API tokens in the database.
func CORSMiddleware ¶
CORSMiddleware adds CORS headers
func Chain ¶
func Chain(h http.Handler, middlewares ...Middleware) http.Handler
Chain applies middlewares in order
func CreateFunctionHandler ¶
func CreateFunctionHandler(database store.DB) http.HandlerFunc
CreateFunctionHandler returns a handler for creating functions
func DeleteFunctionHandler ¶
func DeleteFunctionHandler(database store.DB) http.HandlerFunc
DeleteFunctionHandler returns a handler for deleting functions
func DeleteVersionHandler ¶
func DeleteVersionHandler(database store.DB) http.HandlerFunc
DeleteVersionHandler returns a handler for deleting a version
func ExecuteFunctionHandler ¶
func ExecuteFunctionHandler(deps ExecuteFunctionDeps) http.HandlerFunc
ExecuteFunctionHandler returns a handler for executing functions
func GetExecutionAIRequestsHandler ¶
GetExecutionAIRequestsHandler returns a handler for getting AI requests for an execution
func GetExecutionEmailRequestsHandler ¶
func GetExecutionEmailRequestsHandler(database store.DB, emailTracker email.Tracker) http.HandlerFunc
GetExecutionEmailRequestsHandler returns a handler for getting email requests for an execution
func GetExecutionHandler ¶
func GetExecutionHandler(database store.DB) http.HandlerFunc
GetExecutionHandler returns a handler for getting a specific execution
func GetExecutionLogsHandler ¶
GetExecutionLogsHandler returns a handler for getting execution logs
func GetFunctionHandler ¶
GetFunctionHandler returns a handler for getting a specific function
func GetNextRunHandler ¶
func GetNextRunHandler(database store.DB) http.HandlerFunc
GetNextRunHandler returns a handler for getting the next scheduled run time
func GetVersionDiffHandler ¶
func GetVersionDiffHandler(database store.DB) http.HandlerFunc
GetVersionDiffHandler returns a handler for getting diff between versions
func GetVersionHandler ¶
func GetVersionHandler(database store.DB) http.HandlerFunc
GetVersionHandler returns a handler for getting a specific version
func HandleDeviceApprove ¶
func HandleDeviceApprove(deviceStore *DeviceAuthStore, db store.DB) http.HandlerFunc
HandleDeviceApprove handles POST /api/auth/device-approve Auth required - user approves or denies the request
func HandleDeviceApproveStatus ¶
func HandleDeviceApproveStatus(deviceStore *DeviceAuthStore) http.HandlerFunc
HandleDeviceApproveStatus handles GET /api/auth/device-approve?code=<device_code> Auth required - returns pending request info for the SPA to render
func HandleDeviceRequest ¶
func HandleDeviceRequest(deviceStore *DeviceAuthStore, baseURL string) http.HandlerFunc
HandleDeviceRequest handles POST /api/auth/device-request No auth required - the CLI is not yet authenticated
func HandleDeviceToken ¶
func HandleDeviceToken(deviceStore *DeviceAuthStore) http.HandlerFunc
HandleDeviceToken handles GET /api/auth/device-token?code=<device_code> No auth required - polled by CLI
func HandleListAPITokens ¶
func HandleListAPITokens(db store.DB) http.HandlerFunc
HandleListAPITokens handles GET /api/tokens
func HandleLogin ¶
func HandleLogin(apiKey string) http.HandlerFunc
HandleLogin validates the API key and sets an HttpOnly cookie
func HandleLogout ¶
func HandleLogout() http.HandlerFunc
HandleLogout clears the authentication cookie
func HandleRevokeAPIToken ¶
func HandleRevokeAPIToken(db store.DB) http.HandlerFunc
HandleRevokeAPIToken handles POST /api/tokens/{id}/revoke
func ListExecutionsHandler ¶
func ListExecutionsHandler(database store.DB) http.HandlerFunc
ListExecutionsHandler returns a handler for listing executions
func ListFunctionsHandler ¶
func ListFunctionsHandler(database store.DB) http.HandlerFunc
ListFunctionsHandler returns a handler for listing functions
func ListVersionsHandler ¶
func ListVersionsHandler(database store.DB) http.HandlerFunc
ListVersionsHandler returns a handler for listing function versions
func LoggingMiddleware ¶
LoggingMiddleware logs HTTP requests
func RecoveryMiddleware ¶
RecoveryMiddleware recovers from panics and returns 500
func UpdateEnvVarsHandler ¶
UpdateEnvVarsHandler returns a handler for updating environment variables
func UpdateFunctionHandler ¶
func UpdateFunctionHandler(database store.DB, scheduler *internalcron.FunctionScheduler) http.HandlerFunc
UpdateFunctionHandler returns a handler for updating functions
func UpdateKvStoreHandler ¶
UpdateKvStoreHandler returns a handler for updating key-value store entries
func ValidateCreateFunctionRequest ¶
func ValidateCreateFunctionRequest(req *CreateFunctionRequest) error
ValidateCreateFunctionRequest validates a CreateFunctionRequest
func ValidateUpdateEnvVarsRequest ¶
func ValidateUpdateEnvVarsRequest(req *UpdateEnvVarsRequest) error
ValidateUpdateEnvVarsRequest validates an UpdateEnvVarsRequest
func ValidateUpdateFunctionRequest ¶
func ValidateUpdateFunctionRequest(req *store.UpdateFunctionRequest) error
ValidateUpdateFunctionRequest validates an UpdateFunctionRequest
func ValidateUpdateKvStoreRequest ¶
func ValidateUpdateKvStoreRequest(req *UpdateKvStoreRequest) error
ValidateUpdateKvStoreRequest validates an UpdateKvStoreRequest
Types ¶
type CreateFunctionRequest ¶
type CreateFunctionRequest struct {
Name string `json:"name"`
Description *string `json:"description,omitempty"`
Code string `json:"code"`
}
CreateFunctionRequest is the request body for creating a function
type DeviceApproveRequest ¶
type DeviceApproveRequest struct {
DeviceCode string `json:"device_code"`
Action string `json:"action"`
}
DeviceApproveRequest is the request body for POST /api/auth/device-approve
type DeviceApproveStatusResponse ¶
type DeviceApproveStatusResponse struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
Status string `json:"status"`
ExpiresAt int64 `json:"expires_at"`
}
DeviceApproveStatusResponse is the response for GET /api/auth/device-approve
type DeviceAuthStore ¶
type DeviceAuthStore struct {
// contains filtered or unexported fields
}
DeviceAuthStore is a thread-safe in-memory store for pending device auth requests. Pending auths are stored in memory rather than the database because they are short-lived (5 minute TTL) and do not need to survive server restarts.
func NewDeviceAuthStore ¶
func NewDeviceAuthStore() *DeviceAuthStore
NewDeviceAuthStore creates a new DeviceAuthStore
func (*DeviceAuthStore) Approve ¶
func (s *DeviceAuthStore) Approve(deviceCode string, token string) bool
Approve marks a pending auth as approved with the given token
func (*DeviceAuthStore) Create ¶
func (s *DeviceAuthStore) Create() *PendingAuth
Create generates a new pending auth request and returns it
func (*DeviceAuthStore) Deny ¶
func (s *DeviceAuthStore) Deny(deviceCode string) bool
Deny marks a pending auth as denied
func (*DeviceAuthStore) Get ¶
func (s *DeviceAuthStore) Get(deviceCode string) *PendingAuth
Get returns a pending auth by device code, or nil if not found/expired
type DeviceRequestResponse ¶
type DeviceRequestResponse struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
ApprovalURL string `json:"approval_url"`
ExpiresIn int `json:"expires_in"`
Interval int `json:"interval"`
}
DeviceRequestResponse is the response for POST /api/auth/device-request
type DeviceTokenResponse ¶
type DeviceTokenResponse struct {
Status string `json:"status"`
Token string `json:"token,omitempty"`
}
DeviceTokenResponse is the response for GET /api/auth/device-token
type DiffLine ¶
type DiffLine struct {
LineType DiffLineType `json:"line_type"`
OldLine *int `json:"old_line,omitempty"`
NewLine *int `json:"new_line,omitempty"`
Content string `json:"content"`
}
DiffLine represents a line in a version diff
type DiffLineType ¶
type DiffLineType string
DiffLineType represents the type of change in a diff line
const ( DiffLineUnchanged DiffLineType = "unchanged" DiffLineAdded DiffLineType = "added" DiffLineRemoved DiffLineType = "removed" )
type ErrorResponse ¶
type ErrorResponse struct {
Error string `json:"error"`
}
ErrorResponse is the standard error response
type ExecuteFunctionDeps ¶
ExecuteFunctionDeps holds dependencies for executing functions
type ExecutionWithLogs ¶
ExecutionWithLogs includes execution details and logs
type ListExecutionsResponse ¶
ListExecutionsResponse is the response for listing executions
type ListFunctionsResponse ¶
type ListFunctionsResponse struct {
Functions []store.FunctionWithActiveVersion `json:"functions"`
}
ListFunctionsResponse is the response for listing functions
type ListVersionsResponse ¶
type ListVersionsResponse struct {
Versions []store.FunctionVersion `json:"versions"`
}
ListVersionsResponse is the response for listing versions
type LogEntry ¶
type LogEntry struct {
Level LogLevel `json:"level"`
Message string `json:"message"`
CreatedAt int64 `json:"created_at"`
}
LogEntry represents a log entry from function execution
type LoginRequest ¶
type LoginRequest struct {
APIKey string `json:"apiKey"`
}
type LoginResponse ¶
type NextRunResponse ¶
type NextRunResponse struct {
HasSchedule bool `json:"has_schedule"`
CronSchedule *string `json:"cron_schedule,omitempty"`
CronStatus *string `json:"cron_status,omitempty"`
IsPaused bool `json:"is_paused,omitempty"`
NextRun *int64 `json:"next_run,omitempty"`
NextRunHuman *string `json:"next_run_human,omitempty"`
}
NextRunResponse is the response for getting the next scheduled run time
type PaginatedAIRequestsResponse ¶
type PaginatedAIRequestsResponse struct {
AIRequests []store.AIRequest `json:"ai_requests"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedAIRequestsResponse is the paginated response for AI requests
type PaginatedEmailRequestsResponse ¶
type PaginatedEmailRequestsResponse struct {
EmailRequests []store.EmailRequest `json:"email_requests"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedEmailRequestsResponse is the paginated response for email requests
type PaginatedExecutionWithLogs ¶
type PaginatedExecutionWithLogs struct {
store.Execution
Logs []LogEntry `json:"logs"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedExecutionWithLogs includes execution details with paginated logs
type PaginatedExecutionsResponse ¶
type PaginatedExecutionsResponse struct {
Executions []store.Execution `json:"executions"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedExecutionsResponse is the paginated response for listing executions
type PaginatedFunctionsResponse ¶
type PaginatedFunctionsResponse struct {
Functions []store.FunctionWithActiveVersion `json:"functions"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedFunctionsResponse is the paginated response for listing functions
type PaginatedLogsResponse ¶
type PaginatedLogsResponse struct {
Logs []LogEntry `json:"logs"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedLogsResponse is the paginated response for listing logs
type PaginatedVersionsResponse ¶
type PaginatedVersionsResponse struct {
Versions []store.FunctionVersion `json:"versions"`
Pagination store.PaginationInfo `json:"pagination"`
}
PaginatedVersionsResponse is the paginated response for listing versions
type PendingAuth ¶
type PendingAuth struct {
DeviceCode string
UserCode string
CreatedAt time.Time
ExpiresAt time.Time
Status PendingAuthStatus
Token string // raw token, set on approval
}
PendingAuth represents a pending device authorization request
type PendingAuthStatus ¶
type PendingAuthStatus string
PendingAuthStatus represents the status of a pending device auth request
const ( PendingAuthStatusPending PendingAuthStatus = "pending" PendingAuthStatusApproved PendingAuthStatus = "approved" PendingAuthStatusDenied PendingAuthStatus = "denied" )
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents the API server
func NewServer ¶
func NewServer(config ServerConfig) *Server
NewServer creates a new API server with full configuration
func (*Server) ListenAndServe ¶
ListenAndServe starts the HTTP server on the specified address
type ServerConfig ¶
type ServerConfig struct {
DB store.DB
Logger logger.Logger
KVStore kv.Store
EnvStore env.Store
HTTPClient internalhttp.Client
AITracker ai.Tracker
EmailTracker email.Tracker
Scheduler *internalcron.FunctionScheduler
ExecutionTimeout time.Duration
FrontendHandler http.Handler
APIKey string
BaseURL string
}
ServerConfig holds configuration for creating a Server
type UpdateEnvVarsRequest ¶
UpdateEnvVarsRequest is the request body for updating environment variables
type UpdateKvStoreRequest ¶
UpdateKvStoreRequest is the request body for updating the KV store
type ValidationError ¶
ValidationError represents a validation error
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
type VersionDiffResponse ¶
type VersionDiffResponse struct {
OldVersion int `json:"old_version"`
NewVersion int `json:"new_version"`
Diff []DiffLine `json:"diff"`
}
VersionDiffResponse is the response for version diff