Documentation
¶
Overview ¶
Package v1 is the REST API. Every operation is declared through op(), which registers the Echo route AND its OpenAPI entry from the same Go types, the spec at /api/openapi.json cannot drift from the handlers.
The package is split by resource: stacks.go, apps.go, logs.go, databases.go hold the handlers; types.go the request/response shapes; helpers.go the shared plumbing; auth.go/errors.go the middleware. This file is just the machinery, the API struct, op(), the route table, and the spec.
Index ¶
- Constants
- Variables
- func HashKey(raw string) string
- func ValidScope(s string) bool
- func WriteScope(s string) bool
- type API
- func (a *API) JSONErrors(next echo.HandlerFunc) echo.HandlerFunc
- func (a *API) KeyAuth(next echo.HandlerFunc) echo.HandlerFunc
- func (a *API) Register(g *echo.Group)
- func (a *API) SpecHandler(c echo.Context) error
- func (a *API) SpecJSON() ([]byte, error)
- func (a *API) WithRegistrySigner(s *registry.Signer) *API
- func (a *API) WithWork(q *workqueue.Queue) *API
- type ScopeInfo
Constants ¶
const ( ScopeStacksRead = "stacks:read" ScopeStacksWrite = "stacks:write" ScopeAppsRead = "apps:read" ScopeAppsWrite = "apps:write" ScopeAppsDeploy = "apps:deploy" ScopeVarsRead = "vars:read" ScopeVarsWrite = "vars:write" ScopeSecretsRead = "secrets:read" ScopeLogsRead = "logs:read" ScopeDBsRead = "dbs:read" ScopeDBsWrite = "dbs:write" ScopeDBsFork = "dbs:fork" ScopeDomainsWrite = "domains:write" ScopeEnvsWrite = "envs:write" ScopeConfigRead = "config:read" ScopeConfigApply = "config:apply" ScopeTilesForward = "tiles:forward" ScopeBackupsRead = "backups:read" ScopeBackupsWrite = "backups:write" ScopeBackupsRestore = "backups:restore" ScopeStorageRead = "storage:read" ScopeStorageWrite = "storage:write" )
Capability scopes. A key is granted a subset of these at creation (bounded by the creator's own access); each route declares the one it requires via op().
const ( GroupStructure = "Stacks & environments" GroupApps = "Apps & deployments" GroupConfig = "Configuration" GroupData = "Data" GroupAccess = "Access" )
Scope groups, in display order. A group is only a UI heading, nothing is enforced at group level, and keys still store the explicit scope list.
const ForwardPortHeader = "X-Stackr-Port"
ForwardPortHeader carries the resolved container port back on the upgrade response, so a client that asked for the default learns what it got.
Variables ¶
var ScopeGroups = []string{GroupStructure, GroupApps, GroupConfig, GroupData, GroupAccess}
ScopeGroups is the order the UI renders headings in. A group with no scopes simply doesn't appear.
var Scopes = []ScopeInfo{ {ScopeStacksRead, "List and read stacks", false, GroupStructure}, {ScopeStacksWrite, "Create and delete stacks", true, GroupStructure}, {ScopeEnvsWrite, "Create environments", true, GroupStructure}, {ScopeAppsRead, "List and read apps", false, GroupApps}, {ScopeAppsWrite, "Create, update, and delete apps", true, GroupApps}, {ScopeAppsDeploy, "Trigger deployments", true, GroupApps}, {ScopeLogsRead, "Read logs", false, GroupApps}, {ScopeVarsRead, "Read environment variables", false, GroupConfig}, {ScopeVarsWrite, "Replace environment variables", true, GroupConfig}, {ScopeSecretsRead, "Reveal secret values and resolve references", true, GroupConfig}, {ScopeDomainsWrite, "Add and remove domains", true, GroupConfig}, {ScopeConfigRead, "Read config-as-code plans", false, GroupConfig}, {ScopeConfigApply, "Re-plan, approve, and reject config-as-code plans", true, GroupConfig}, {ScopeDBsRead, "List and read databases", false, GroupData}, {ScopeDBsWrite, "Create and delete databases", true, GroupData}, {ScopeDBsFork, "Fork a database slice, copying its data", true, GroupData}, {ScopeBackupsRead, "List backup schedules and run history", false, GroupData}, {ScopeBackupsWrite, "Configure backups and trigger runs", true, GroupData}, {ScopeBackupsRestore, "Restore data from a backup (destructive)", true, GroupData}, {ScopeStorageRead, "List storage shares/pools and their sub-paths", false, GroupData}, {ScopeStorageWrite, "Create and delete storage shares/pools and sub-paths", true, GroupData}, {ScopeTilesForward, "Port-forward a tile to a local machine", true, GroupAccess}, }
Scopes is the full capability catalog, in display order.
Functions ¶
func ValidScope ¶
ValidScope reports whether s is a known capability.
func WriteScope ¶
WriteScope reports whether granting s requires content-write access.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
func (*API) JSONErrors ¶
func (a *API) JSONErrors(next echo.HandlerFunc) echo.HandlerFunc
JSONErrors is the outermost v1 middleware: it renders any handler error as the uniform JSON shape instead of echo's default HTML/text, so every failure looks the same to a CLI. Internal errors are collapsed to a generic message (status + text) so raw error strings don't leak.
func (*API) KeyAuth ¶
func (a *API) KeyAuth(next echo.HandlerFunc) echo.HandlerFunc
KeyAuth authenticates via x-api-key and loads the key's user + org access into the request context, so scope checks and org tenancy both apply.
func (*API) Register ¶
Register wires all v1 routes onto the group (which must carry KeyAuth). Each op declares the capability scope it requires.
func (*API) SpecHandler ¶
SpecHandler serves the generated OpenAPI document.
func (*API) SpecJSON ¶
SpecJSON returns the generated OpenAPI document as JSON bytes (used by the live endpoint and the `make openapi` generator).
func (*API) WithRegistrySigner ¶
WithRegistrySigner gives the API the managed registry's token signer. Nil when the keypair would not load, which the registry routes report rather than failing at the registry with a bare 401.