v1

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 46 Imported by: 0

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

View Source
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().

View Source
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.

View Source
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

ScopeGroups is the order the UI renders headings in. A group with no scopes simply doesn't appear.

View Source
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 HashKey

func HashKey(raw string) string

HashKey returns the stored hash for a raw API token.

func ValidScope

func ValidScope(s string) bool

ValidScope reports whether s is a known capability.

func WriteScope

func WriteScope(s string) bool

WriteScope reports whether granting s requires content-write access.

Types

type API

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

func New

func New(store repo.Store, engine *deploy.Engine, rt *runtime.Runtime, clus *cluster.Cluster, px *proxy.Proxy, js *jobs.Service, bk *backup.Service, fwd *forward.Registry, n *notify.Notifier, ap stackconf.Applier) *API

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

func (a *API) Register(g *echo.Group)

Register wires all v1 routes onto the group (which must carry KeyAuth). Each op declares the capability scope it requires.

func (*API) SpecHandler

func (a *API) SpecHandler(c echo.Context) error

SpecHandler serves the generated OpenAPI document.

func (*API) SpecJSON

func (a *API) SpecJSON() ([]byte, error)

SpecJSON returns the generated OpenAPI document as JSON bytes (used by the live endpoint and the `make openapi` generator).

func (*API) WithRegistrySigner

func (a *API) WithRegistrySigner(s *registry.Signer) *API

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.

func (*API) WithWork

func (a *API) WithWork(q *workqueue.Queue) *API

WithWork gives the API the durable job runner. An approve enqueues an apply and answers 202: a CI job holding the connection open is not what keeps an apply alive, the queue is.

type ScopeInfo

type ScopeInfo struct {
	Name  string
	Desc  string
	Write bool // requires content-write access to grant
	Group string
}

ScopeInfo describes a capability for the key-creation UI.

func ScopesIn

func ScopesIn(group string) []ScopeInfo

ScopesIn returns the catalog entries in one group, preserving Scopes' order.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL