Documentation
¶
Overview ¶
Package cli implements the `stackr` command-line client.
Index ¶
- Variables
- func Clear() error
- func DotenvQuote(v string) string
- func LoginBrowser(ctx context.Context, rawURL string) error
- func LoginWithKey(ctx context.Context, rawURL, key string) error
- func RemoveLink() error
- func Save(c Config) error
- func SaveLink(dir string, l Link) error
- type APIError
- type App
- type AppCreate
- type Backup
- type BackupRun
- type Client
- func (c *Client) AddDestination(ctx context.Context, in DestinationCreate) (Destination, error)
- func (c *Client) AddDomain(ctx context.Context, appID, host string, port int, https bool) (Domain, error)
- func (c *Client) AddDomainResource(ctx context.Context, host, level, owner string, includeEnvOnDefault bool) (DomainResource, error)
- func (c *Client) AddInvite(ctx context.Context, org, email, role string, days int) (Invite, error)
- func (c *Client) AddMember(ctx context.Context, org, email, role string, days int) (Invite, error)
- func (c *Client) AddRegistry(ctx context.Context, in Registry, password string) (Registry, error)
- func (c *Client) AddRegistryCredential(ctx context.Context, org, name string) (RegistryCredential, error)
- func (c *Client) AddVolume(ctx context.Context, appID, name, mountPath string) (Volume, error)
- func (c *Client) AddVolumeWith(ctx context.Context, appID string, in VolumeCreate) (Volume, error)
- func (c *Client) ApproveOrgPlan(ctx context.Context, planID string) (Plan, error)
- func (c *Client) ApprovePlan(ctx context.Context, planID string) (Plan, error)
- func (c *Client) Apps(ctx context.Context, stack, env string) ([]App, error)
- func (c *Client) AttachProvision(ctx context.Context, appID, provisionID, envVar string) (Provision, error)
- func (c *Client) AutoDomain(ctx context.Context, appID string) (Domain, error)
- func (c *Client) BackupRuns(ctx context.Context, id string) ([]BackupRun, error)
- func (c *Client) Backups(ctx context.Context, tileID string) ([]Backup, error)
- func (c *Client) CancelDeployment(ctx context.Context, id string) (Deployment, error)
- func (c *Client) CopyEnv(ctx context.Context, envID, name string, ephemeral bool) (Env, error)
- func (c *Client) CreateApp(ctx context.Context, stackID string, in AppCreate) (App, error)
- func (c *Client) CreateBackup(ctx context.Context, tileID string, fields map[string]any) (Backup, error)
- func (c *Client) CreateDB(ctx context.Context, stackID, name, engine, envSlug, scope string) (DB, error)
- func (c *Client) CreateEnv(ctx context.Context, stackID, name string) (Env, error)
- func (c *Client) CreateStack(ctx context.Context, name, desc, orgID string) (Stack, error)
- func (c *Client) CreateStorage(ctx context.Context, in StorageCreate) (StorageEntry, error)
- func (c *Client) CreateStoragePath(ctx context.Context, storageID string, in StoragePathCreate) (StoragePath, error)
- func (c *Client) DBs(ctx context.Context) ([]DB, error)
- func (c *Client) DeleteApp(ctx context.Context, appID string) error
- func (c *Client) DeleteBackup(ctx context.Context, id string) error
- func (c *Client) DeleteDB(ctx context.Context, dbID string, force bool) error
- func (c *Client) DeleteDestination(ctx context.Context, id string) error
- func (c *Client) DeleteDomain(ctx context.Context, domainID string) error
- func (c *Client) DeleteDomainResource(ctx context.Context, id string) error
- func (c *Client) DeleteEnv(ctx context.Context, envID string, force bool) error
- func (c *Client) DeleteInvite(ctx context.Context, org, id string) error
- func (c *Client) DeleteProxyEntry(ctx context.Context, name string) error
- func (c *Client) DeleteRegistry(ctx context.Context, id string) error
- func (c *Client) DeleteRegistryCredential(ctx context.Context, org, id string) error
- func (c *Client) DeleteRegistryTag(ctx context.Context, org, name, tag string) error
- func (c *Client) DeleteSlice(ctx context.Context, provisionID string) error
- func (c *Client) DeleteStack(ctx context.Context, stackID string) error
- func (c *Client) DeleteStorage(ctx context.Context, id string) error
- func (c *Client) DeleteStoragePath(ctx context.Context, id string) error
- func (c *Client) DeleteVolume(ctx context.Context, volumeID string) error
- func (c *Client) Deploy(ctx context.Context, appID string) (string, error)
- func (c *Client) DeploymentLogs(ctx context.Context, id string) (string, error)
- func (c *Client) Deployments(ctx context.Context, appID string) ([]Deployment, error)
- func (c *Client) Destinations(ctx context.Context) ([]Destination, error)
- func (c *Client) DetachProvision(ctx context.Context, appID, provisionID string) error
- func (c *Client) DomainResources(ctx context.Context) ([]DomainResource, error)
- func (c *Client) Domains(ctx context.Context, appID string) ([]Domain, error)
- func (c *Client) Envs(ctx context.Context, stackID string) ([]Env, error)
- func (c *Client) ExportOrgConfig(ctx context.Context, org string) ([]byte, error)
- func (c *Client) ExportStackConfig(ctx context.Context, stackID string) ([]byte, error)
- func (c *Client) FollowLogs(ctx context.Context, appID string, tail int, fn func(LogEvent) error) error
- func (c *Client) ForkSlice(ctx context.Context, provisionID, name string) (Slice, error)
- func (c *Client) Forward(ctx context.Context, tileID string, port int) (net.Conn, int, error)
- func (c *Client) ForwardPresence(ctx context.Context, tileID string, port int) (net.Conn, int, error)
- func (c *Client) GetApp(ctx context.Context, appID string) (App, error)
- func (c *Client) GetDB(ctx context.Context, dbID string) (DB, error)
- func (c *Client) GetDeployment(ctx context.Context, id string) (Deployment, error)
- func (c *Client) GetPREnv(ctx context.Context, stackID string) (PREnv, error)
- func (c *Client) InstanceSlices(ctx context.Context, dbID string) ([]Slice, error)
- func (c *Client) Invites(ctx context.Context, org string) ([]Invite, error)
- func (c *Client) ListProvisions(ctx context.Context, appID string) ([]Provision, error)
- func (c *Client) ListStorage(ctx context.Context) ([]StorageEntry, error)
- func (c *Client) Logs(ctx context.Context, appID string, tail int) (string, error)
- func (c *Client) Members(ctx context.Context, org string) ([]Member, error)
- func (c *Client) Metrics(ctx context.Context, appID, window string) ([]Metric, error)
- func (c *Client) OrgPlanNow(ctx context.Context, orgID string) (Plan, error)
- func (c *Client) OrgPlanPreview(ctx context.Context, orgID, main string) (Plan, error)
- func (c *Client) OrgPlans(ctx context.Context, orgID string) ([]Plan, error)
- func (c *Client) Orgs(ctx context.Context) ([]Org, error)
- func (c *Client) PatchApp(ctx context.Context, appID string, fields map[string]any) (App, error)
- func (c *Client) PatchBackup(ctx context.Context, id string, fields map[string]any) (Backup, error)
- func (c *Client) PatchDB(ctx context.Context, dbID string, s DBSettings) (DB, error)
- func (c *Client) PatchDomain(ctx context.Context, domainID string, fields map[string]any) (Domain, error)
- func (c *Client) PatchEnv(ctx context.Context, envID string, fields map[string]any) (Env, error)
- func (c *Client) PatchRegistry(ctx context.Context, id string, fields map[string]any) (Registry, error)
- func (c *Client) PatchStack(ctx context.Context, stackID string, fields map[string]any) (Stack, error)
- func (c *Client) Plan(ctx context.Context, planID string) (Plan, error)
- func (c *Client) PlanNow(ctx context.Context, stackID string) ([]Plan, error)
- func (c *Client) PlanPreview(ctx context.Context, stackID, main string, files map[string]string, env string) (Plan, error)
- func (c *Client) Plans(ctx context.Context, stackID string, limit int) ([]Plan, error)
- func (c *Client) ProbeStorage(ctx context.Context, id string) (StorageEntry, error)
- func (c *Client) Promote(ctx context.Context, stackID, envSlug, commit, plan string, force bool) (PromoteResult, error)
- func (c *Client) ProvisionSlice(ctx context.Context, dbID, name, envID string, public bool) (Slice, error)
- func (c *Client) ProxyConfig(ctx context.Context) (ProxyConfig, error)
- func (c *Client) PutProxyEntry(ctx context.Context, name, yamlBody string) (ProxyConfig, error)
- func (c *Client) PutProxyOverride(ctx context.Context, yamlBody string) (ProxyConfig, error)
- func (c *Client) ReferenceCatalogue(ctx context.Context, appID string) ([]RefSource, error)
- func (c *Client) Registries(ctx context.Context) ([]Registry, error)
- func (c *Client) RegistryCredentials(ctx context.Context, org string) ([]RegistryCredential, error)
- func (c *Client) RegistryImages(ctx context.Context, org string) ([]RegistryImage, error)
- func (c *Client) RegistryTags(ctx context.Context, org, name string) ([]RegistryTag, error)
- func (c *Client) RejectOrgPlan(ctx context.Context, planID string) (Plan, error)
- func (c *Client) RejectPlan(ctx context.Context, planID string) (Plan, error)
- func (c *Client) Releases(ctx context.Context, stackID string) ([]Release, error)
- func (c *Client) RemoveMember(ctx context.Context, org, userID string) error
- func (c *Client) ResetEnv(ctx context.Context, envID string, force bool) error
- func (c *Client) Resolve(ctx context.Context, path, envID string) (Target, error)
- func (c *Client) ResolvedVars(ctx context.Context, appID string) ([]Var, error)
- func (c *Client) Resources(ctx context.Context, appID string) ([]Resource, error)
- func (c *Client) RestartApp(ctx context.Context, appID string) (App, error)
- func (c *Client) Restore(ctx context.Context, backupID, runID string) error
- func (c *Client) Rollback(ctx context.Context, appID, imageTag string) (string, error)
- func (c *Client) RunApp(ctx context.Context, appID string) error
- func (c *Client) RunBackup(ctx context.Context, id string) (BackupRun, error)
- func (c *Client) SetDestinationShared(ctx context.Context, id string, shared bool) (Destination, error)
- func (c *Client) SetMemberRole(ctx context.Context, org, userID, role string) (Member, error)
- func (c *Client) SetPREnv(ctx context.Context, stackID string, fields map[string]any) (PREnv, error)
- func (c *Client) SetSettings(ctx context.Context, kind, id string, fields map[string]*string) (SettingsLevel, error)
- func (c *Client) SetSlicePublic(ctx context.Context, provisionID string, public bool) (Slice, error)
- func (c *Client) SetVarsAt(ctx context.Context, scope VarScope, vars []Var) ([]Var, error)
- func (c *Client) Settings(ctx context.Context, kind, id string) (SettingsLevel, error)
- func (c *Client) Stacks(ctx context.Context) ([]Stack, error)
- func (c *Client) StopApp(ctx context.Context, appID string) (App, error)
- func (c *Client) StopRun(ctx context.Context, appID, runID string) error
- func (c *Client) ToggleCron(ctx context.Context, appID string) (App, error)
- func (c *Client) UnresolvedVars(ctx context.Context, appID string) ([]Var, error)
- func (c *Client) VarsAt(ctx context.Context, scope VarScope) ([]Var, error)
- func (c *Client) Volumes(ctx context.Context, appID string) ([]Volume, error)
- type Config
- type DB
- type DBSettings
- type Deployment
- type Destination
- type DestinationCreate
- type Domain
- type DomainResource
- type Env
- type Invite
- type Link
- type LogEvent
- type Member
- type Metric
- type Org
- type PREnv
- type Plan
- type PlanChange
- type PromoteResult
- type Provision
- type ProxyConfig
- type RefOutput
- type RefSource
- type Registry
- type RegistryCredential
- type RegistryImage
- type RegistryTag
- type Release
- type Resource
- type SettingKnob
- type SettingsLevel
- type Slice
- type Stack
- type StorageCreate
- type StorageEntry
- type StoragePath
- type StoragePathCreate
- type Target
- type Var
- type VarScope
- type Volume
- type VolumeCreate
Constants ¶
This section is empty.
Variables ¶
var ErrNotLoggedIn = errors.New("not logged in; run `stackr login <url>`")
ErrNotLoggedIn is returned by Load when no config file exists yet.
Functions ¶
func DotenvQuote ¶
DotenvQuote quotes a value when bare text would not survive a round trip: anything with whitespace, quotes, newlines, or shell-significant characters.
func LoginBrowser ¶
LoginBrowser runs the gh-style loopback flow: spin up a localhost listener, open the browser at /cli/authorize, receive a one-time code on the callback, exchange it for a key, verify, and save.
func LoginWithKey ¶
LoginWithKey saves an explicitly-provided key after verifying it works.
func RemoveLink ¶
func RemoveLink() error
RemoveLink deletes the nearest link file. os.ErrNotExist if none is linked.
Types ¶
type APIError ¶
APIError is a non-2xx API response: the human message plus the HTTP status and machine code, kept so `--json` can emit a structured error object.
func (*APIError) HTTPStatus ¶
type App ¶
type App struct {
ID string `json:"id"`
Name string `json:"name"`
EnvID string `json:"env_id"`
Status string `json:"status"`
}
App is a deployable service within a stack/environment.
type AppCreate ¶
type AppCreate struct {
Name string `json:"name"`
EnvSlug string `json:"env_slug,omitempty"`
Kind string `json:"kind,omitempty"`
SourceType string `json:"source_type,omitempty"`
Image string `json:"image,omitempty"`
GitURL string `json:"git_url,omitempty"`
GitBranch string `json:"git_branch,omitempty"`
DockerfilePath string `json:"dockerfile_path,omitempty"`
BuildContext string `json:"build_context,omitempty"`
Port int `json:"port,omitempty"`
Env map[string]string `json:"env,omitempty"`
Schedule string `json:"schedule,omitempty"`
Command string `json:"command,omitempty"`
TimeoutMinutes int `json:"timeout_minutes,omitempty"`
Connector string `json:"connector_id,omitempty"`
}
AppCreate is the payload for creating a service or cron app.
type Backup ¶
type Backup struct {
ID string `json:"id"`
TileID string `json:"tile_id"`
DestinationID string `json:"destination_id"`
Kind string `json:"kind"`
ContainerMode string `json:"container_mode"`
Cron string `json:"cron"`
Timezone string `json:"timezone"`
KeepLatest int `json:"keep_latest"`
Enabled bool `json:"enabled"`
}
Backup is a schedule: what to dump, where to, how often, how much to keep.
type BackupRun ¶
type BackupRun struct {
ID string `json:"id"`
BackupID string `json:"backup_id"`
Trigger string `json:"trigger"`
Status string `json:"status"`
ObjectKey string `json:"object_key"`
SizeBytes int64 `json:"size_bytes"`
Error string `json:"error"`
CreatedAt string `json:"created_at"`
FinishedAt string `json:"finished_at"`
}
BackupRun is one execution of a schedule, and the unit a restore names.
type Client ¶
Client is a thin HTTP client over the stackr /api/v1 surface. It stays deliberately small: enough to prove auth end-to-end. A generated SDK over the committed doc/openapi.json can replace the per-endpoint methods later.
func (*Client) AddDestination ¶
func (c *Client) AddDestination(ctx context.Context, in DestinationCreate) (Destination, error)
AddDestination creates a destination. The server dials the bucket before storing it, so bad credentials fail here rather than at the first run.
func (*Client) AddDomain ¶
func (c *Client) AddDomain(ctx context.Context, appID, host string, port int, https bool) (Domain, error)
AddDomain attaches a host to an app and updates the proxy. port 0 = the app's own port; https terminates TLS.
func (*Client) AddDomainResource ¶
func (c *Client) AddDomainResource(ctx context.Context, host, level, owner string, includeEnvOnDefault bool) (DomainResource, error)
AddDomainResource creates a resource at level (owner: org/stack id, ignored for instance level).
func (*Client) AddMember ¶
AddMember invites rather than inserting a membership: a user row comes from accepting an invite.
func (*Client) AddRegistry ¶
func (*Client) AddRegistryCredential ¶
func (*Client) AddVolume ¶
AddVolume creates a volume mounted into an app at mountPath and redeploys it.
func (*Client) AddVolumeWith ¶
AddVolumeWith mounts a volume with every field set.
func (*Client) ApproveOrgPlan ¶
func (*Client) ApprovePlan ¶
ApprovePlan applies a pending plan.
func (*Client) AttachProvision ¶
func (c *Client) AttachProvision(ctx context.Context, appID, provisionID, envVar string) (Provision, error)
AttachProvision points an app at an existing logical database (same env).
func (*Client) AutoDomain ¶
AutoDomain generates the tile's hostname under whichever domain resource its environment nests below.
func (*Client) BackupRuns ¶
BackupRuns lists a schedule's run history, which is also where a restore's run id comes from.
func (*Client) Backups ¶
Backups lists a tile's schedules. There is no list-all route, a backup is only ever addressed through the tile it protects.
func (*Client) CancelDeployment ¶
CancelDeployment stops a build or roll-out in flight.
func (*Client) CopyEnv ¶
CopyEnv creates a new environment from an existing one: same tiles, nothing deployed.
func (*Client) CreateBackup ¶
func (c *Client) CreateBackup(ctx context.Context, tileID string, fields map[string]any) (Backup, error)
CreateBackup adds a schedule to a tile. The body is a map for the same reason PatchApp's is: keep_latest 0 and enabled false are meaningful values.
func (*Client) CreateDB ¶
func (c *Client) CreateDB(ctx context.Context, stackID, name, engine, envSlug, scope string) (DB, error)
CreateDB provisions a database in a stack. scope ("", env, stack, org) sets how widely a shared instance can be provisioned from.
func (*Client) CreateStack ¶
CreateStack creates a stack. orgID may be empty unless you belong to many.
func (*Client) CreateStorage ¶
func (c *Client) CreateStorage(ctx context.Context, in StorageCreate) (StorageEntry, error)
func (*Client) CreateStoragePath ¶
func (c *Client) CreateStoragePath(ctx context.Context, storageID string, in StoragePathCreate) (StoragePath, error)
func (*Client) DBs ¶
DBs lists databases visible to the key. Separate from Apps because the API splits the two, though both are tiles and both are forwardable.
func (*Client) DeleteBackup ¶
DeleteBackup removes a schedule. Archives already written are not touched.
func (*Client) DeleteDB ¶
DeleteDB drops a shared instance. force is required once consumers hold slices on it, without it the server refuses rather than destroying their data.
func (*Client) DeleteDestination ¶
DeleteDestination removes a destination. Archives already in the bucket stay.
func (*Client) DeleteDomain ¶
DeleteDomain removes a host by id and re-syncs the proxy.
func (*Client) DeleteDomainResource ¶
DeleteDomainResource removes a resource by id.
func (*Client) DeleteEnv ¶
DeleteEnv tears an environment down. force is required once tiles are running there.
func (*Client) DeleteInvite ¶
func (*Client) DeleteProxyEntry ¶
func (*Client) DeleteRegistry ¶
func (*Client) DeleteRegistryCredential ¶
func (*Client) DeleteRegistryTag ¶
func (*Client) DeleteSlice ¶
DeleteSlice destroys one logical database or bucket, and with it every consumer's link to it.
func (*Client) DeleteStack ¶
DeleteStack removes a stack and everything in it.
func (*Client) DeleteStoragePath ¶
func (*Client) DeleteVolume ¶
DeleteVolume removes a volume by id (its data is preserved) and redeploys.
func (*Client) DeploymentLogs ¶
DeploymentLogs returns one deployment's build output.
func (*Client) Deployments ¶
Deployments lists a tile's recent deployments, newest first.
func (*Client) Destinations ¶
func (c *Client) Destinations(ctx context.Context) ([]Destination, error)
Destinations lists the targets the key can use: its own orgs', plus the server-wide ones an admin has shared.
func (*Client) DetachProvision ¶
DetachProvision unhooks one consumer from a slice and keeps the data.
func (*Client) DomainResources ¶
func (c *Client) DomainResources(ctx context.Context) ([]DomainResource, error)
DomainResources lists the resources visible to the key's user.
func (*Client) ExportOrgConfig ¶
ExportOrgConfig does the same for an organization.
func (*Client) ExportStackConfig ¶
ExportStackConfig renders a stack's live state as the file that would produce it: the way out of panel-first and into config-as-code.
func (*Client) FollowLogs ¶
func (c *Client) FollowLogs(ctx context.Context, appID string, tail int, fn func(LogEvent) error) error
FollowLogs streams live logs (SSE), calling fn per line until the context is cancelled or the stream closes. A 204 means the app isn't running (nothing to follow). Structured events let the caller choose text or NDJSON.
func (*Client) ForkSlice ¶
ForkSlice copies a slice into a new one on the same instance. The copy runs server-side and can take a while on a large database, so this call is the one place the CLI's 15s timeout is deliberately not enough, see the longer client it builds.
func (*Client) Forward ¶
Forward opens one tunnel to a container port on a tile and returns it as a net.Conn, one call per local connection the forward command accepts. The second return is the container port actually used, which matters when port is 0 and the server picked the tile's own.
The shared HTTP client is deliberately not used: its 15s timeout would cut the tunnel off mid-session.
func (*Client) ForwardPresence ¶
func (c *Client) ForwardPresence(ctx context.Context, tileID string, port int) (net.Conn, int, error)
ForwardPresence opens the session websocket `stackr forward` holds for its whole lifetime: it registers who has a forward open (the canvas card), and doubles as the startup probe, a missing scope, stopped tile or bad port fails here. Reading from it blocks until the server drops the session; the forward command uses that to re-register after a server restart.
func (*Client) GetDeployment ¶
GetDeployment reads one deployment's current state.
func (*Client) InstanceSlices ¶
InstanceSlices lists the slices cut from one shared instance.
func (*Client) ListProvisions ¶
ListProvisions lists the logical databases an app holds.
func (*Client) ListStorage ¶
func (c *Client) ListStorage(ctx context.Context) ([]StorageEntry, error)
func (*Client) Metrics ¶
Metrics reads a tile's sampled resource use. window is "1h", "6h" or "24h".
func (*Client) OrgPlanNow ¶
func (*Client) OrgPlanPreview ¶
OrgPlanPreview posts the org config file and returns the throwaway plan, the org twin of PlanPreview. Org files have no include:, so no bundle map.
func (*Client) OrgPlans ¶
Plans lists a stack's recent config plans, newest first. Org config-as-code plans (org id in place of stack id, same wire shape).
func (*Client) PatchApp ¶
PatchApp updates tile settings. The body is a map rather than a struct because the API distinguishes absent from cleared by which keys arrive, a struct with omitempty could never send a deliberate zero.
func (*Client) PatchBackup ¶
PatchBackup changes a schedule's destination, cron, retention or enabled flag.
func (*Client) PatchDomain ¶
func (c *Client) PatchDomain(ctx context.Context, domainID string, fields map[string]any) (Domain, error)
PatchDomain changes one domain's TLS: HTTPS on or off, a custom certificate installed or cleared. Only the fields present are touched.
func (*Client) PatchRegistry ¶
func (*Client) PatchStack ¶
func (c *Client) PatchStack(ctx context.Context, stackID string, fields map[string]any) (Stack, error)
PatchStack renames or re-describes a stack. The slug moves with the name.
func (*Client) PlanNow ¶
PlanNow re-plans a stack against its bound config repo. It returns every plan the sweep produced, the stack-scoped one first, then one per environment pinned to its own config branch.
func (*Client) PlanPreview ¶
func (c *Client) PlanPreview(ctx context.Context, stackID, main string, files map[string]string, env string) (Plan, error)
PlanPreview posts a local config bundle and returns the throwaway plan the server computed against live state. Nothing is stored server-side, the returned plan has no ID and cannot be approved.
func (*Client) ProbeStorage ¶
ProbeStorage mounts the share on the node that will mount it at deploy time and records the outcome on the storage row.
func (*Client) Promote ¶
func (c *Client) Promote(ctx context.Context, stackID, envSlug, commit, plan string, force bool) (PromoteResult, error)
Promote moves a built commit onto a rung. plan applies a waiting config plan first, in the same job.
func (*Client) ProvisionSlice ¶
func (c *Client) ProvisionSlice(ctx context.Context, dbID, name, envID string, public bool) (Slice, error)
ProvisionSlice cuts a slice out of an instance with no consumer attached.
envID says which environment the slice belongs to, which decides what can ever consume it, a stack- or org-scoped instance serves several, and a slice cut into the wrong one can never be attached.
func (*Client) ProxyConfig ¶
func (c *Client) ProxyConfig(ctx context.Context) (ProxyConfig, error)
func (*Client) PutProxyEntry ¶
func (*Client) PutProxyOverride ¶
func (*Client) ReferenceCatalogue ¶
ReferenceCatalogue lists what a tile may reference.
func (*Client) RegistryCredentials ¶
func (*Client) RegistryImages ¶
func (*Client) RegistryTags ¶
func (*Client) RejectOrgPlan ¶
func (*Client) RejectPlan ¶
RejectPlan closes a pending plan without applying it.
func (*Client) RemoveMember ¶
func (*Client) ResetEnv ¶
ResetEnv tears a config-managed environment down so the next apply rebuilds it from the file.
func (*Client) Resolve ¶
Resolve turns an infra path into what it names. envID is the linked environment, which is what lets the path be relative ("app-db" rather than org:stack:env:app-db); the server completes it, so nothing about the hierarchy is cached on this side.
func (*Client) ResolvedVars ¶
ResolvedVars returns the environment a deploy would produce, references expanded. Fails rather than omitting when the key can't read a secret.
func (*Client) RestartApp ¶
RestartApp bounces a tile in place: no rebuild, no new image.
func (*Client) Restore ¶
Restore writes an archive back over the live database or volume. Needs the backups:restore scope, which is granted separately from backups:write.
func (*Client) RunBackup ¶
RunBackup triggers a schedule immediately and returns the run it started.
func (*Client) SetDestinationShared ¶
func (c *Client) SetDestinationShared(ctx context.Context, id string, shared bool) (Destination, error)
SetDestinationShared offers a server-wide destination to every organization, or takes it back. Taking it back is refused while an org still schedules against it, and the error names the tiles.
func (*Client) SetMemberRole ¶
func (*Client) SetPREnv ¶
func (c *Client) SetPREnv(ctx context.Context, stackID string, fields map[string]any) (PREnv, error)
SetPREnv writes them.
func (*Client) SetSettings ¶
func (c *Client) SetSettings(ctx context.Context, kind, id string, fields map[string]*string) (SettingsLevel, error)
SetSettings writes this level's own overrides. A nil value clears one back to inherit.
func (*Client) SetSlicePublic ¶
func (c *Client) SetSlicePublic(ctx context.Context, provisionID string, public bool) (Slice, error)
SetSlicePublic exposes or hides a slice outside its own network. Every consumer of the same bucket moves with it.
func (*Client) SetVarsAt ¶
SetVarsAt is SetVars against any scope, an app, a stack, or an org. The read-modify-write is the same at every level, because every one of those endpoints replaces the whole set.
func (*Client) Stacks ¶
Stacks lists stacks visible to the key. It doubles as the auth check: a 401/403 surfaces as an error.
func (*Client) StopApp ¶
StopApp scales a tile to zero. The row, its volumes and its replica count stay, so RestartApp brings it back as it was.
func (*Client) ToggleCron ¶
ToggleCron pauses a running schedule or resumes a paused one. The answer carries the state it landed in.
func (*Client) UnresolvedVars ¶
UnresolvedVars lists a tile's variables exactly as stored, references unexpanded. This is what you edit against; ResolvedVars is what the container will see.
type DB ¶
type DB struct {
ID string `json:"id"`
StackID string `json:"stack_id"`
Name string `json:"name"`
Engine string `json:"engine"`
Status string `json:"status"`
ExternalPort int `json:"external_port"`
Scope string `json:"scope"`
CPULimit float64 `json:"cpu_limit"`
MemLimitMB int `json:"mem_limit_mb"`
Image string `json:"image"`
ShmSizeMB int `json:"shm_size_mb"`
Path string `json:"path"` // colon-path address, set on create
}
DB is a provisioned database (shared instance).
type DBSettings ¶
type DBSettings struct {
ExternalPort *int `json:"external_port,omitempty"`
Scope *string `json:"scope,omitempty"`
CPULimit *float64 `json:"cpu_limit,omitempty"`
MemLimitMB *int `json:"mem_limit_mb,omitempty"`
Image *string `json:"image,omitempty"`
ShmSizeMB *int `json:"shm_size_mb,omitempty"`
}
DBSettings are the instance knobs a PATCH can change. Pointers so "not mentioned" stays distinct from "set to zero", 0 is a meaningful value for every one of them.
type Deployment ¶
type Deployment struct {
ID string `json:"id"`
AppID string `json:"app_id"`
Status string `json:"status"` // waiting_ci queued running done error cancelled
Trigger string `json:"trigger"`
CommitSHA string `json:"commit_sha"`
ImageTag string `json:"image_tag"`
Error string `json:"error,omitempty"`
}
Deployment is one deployment's state, polled by `deploy` while waiting.
type Destination ¶
type Destination struct {
ID string `json:"id"`
Name string `json:"name"`
Endpoint string `json:"endpoint"`
Bucket string `json:"bucket"`
Region string `json:"region"`
OrgID string `json:"org_id"`
Global bool `json:"global"`
}
Destination is an S3 target backups are written to. Secrets are write-only, the server never renders them back, so they are absent here on purpose.
type DestinationCreate ¶
type DestinationCreate struct {
Name string `json:"name"`
Endpoint string `json:"endpoint"`
Bucket string `json:"bucket"`
Region string `json:"region,omitempty"`
AccessKey string `json:"access_key"`
SecretKey string `json:"secret_key"`
OrgID string `json:"org_id,omitempty"`
// bucket credentials go with it, so it is off unless asked for.
Shared bool `json:"shared,omitempty"`
}
DestinationCreate is the create body. OrgID empty makes the destination server-wide, which the API allows for admins only.
type Domain ¶
type Domain struct {
ID string `json:"id"`
Host string `json:"host"`
Path string `json:"path"`
ContainerPort int `json:"container_port"`
HTTPS bool `json:"https"`
}
Domain is a host attached to an app.
type DomainResource ¶
type DomainResource struct {
ID string `json:"id"`
Level string `json:"level"`
OwnerID string `json:"owner_id"`
Host string `json:"host"`
IncludeEnvOnDefault bool `json:"include_env_on_default"`
}
DomainResource is a host owned at a level (instance/org/stack) that tiles generate per-environment hostnames under.
type Invite ¶
type Invite struct {
ID string `json:"id"`
Email string `json:"email,omitempty"`
Role string `json:"role"`
ExpiresAt time.Time `json:"expires_at"`
Used bool `json:"used"`
URL string `json:"url"`
}
Invite is an open invitation. The URL is a credential: anyone holding it can join as the role it carries.
type Link ¶
type Link struct {
Stack string `json:"stack"` // stack id
StackName string `json:"stack_name"` // cached for display
Env string `json:"env"` // environment id
EnvName string `json:"env_name"` // cached for display
App string `json:"app"` // default app id
AppName string `json:"app_name"` // cached for display
}
Link binds the current repo directory to a stack and environment, so verbs resolve their target from cwd instead of flags.
type Member ¶
type Member struct {
UserID string `json:"user_id"`
Email string `json:"email"`
Name string `json:"name,omitempty"`
Role string `json:"role"`
}
Member is one person in an organization.
type Metric ¶
type Metric struct {
At time.Time `json:"at"`
CPUPercent float64 `json:"cpu_percent"`
MemBytes int64 `json:"mem_bytes"`
RxBps float64 `json:"rx_bps"`
TxBps float64 `json:"tx_bps"`
}
Metric is one sample of a tile's resource use.
type Org ¶
type Org struct {
ID string `json:"id"`
Slug string `json:"slug"`
Name string `json:"name"`
Role string `json:"role"`
}
Org is one organization the key's user belongs to. Slug is what every slug path starts with, which is the whole reason this listing exists.
type PREnv ¶
type PREnv struct {
Enabled bool `json:"enabled"`
Comment bool `json:"comment"`
Status bool `json:"status"`
SecretSet bool `json:"secret_set"`
}
PREnv is a stack's pull-request environment settings. The webhook secret is never returned, only whether one is set.
type Plan ¶
type Plan struct {
ID string `json:"id"`
StackID string `json:"stack_id"`
EnvSlug string `json:"env_slug,omitempty"`
CommitSHA string `json:"commit_sha,omitempty"`
Status string `json:"status"`
Summary string `json:"summary"`
Error string `json:"error,omitempty"`
CreatedAt string `json:"created_at"`
DecidedAt string `json:"decided_at,omitempty"`
Changes []PlanChange `json:"changes,omitempty"`
Errors []string `json:"errors,omitempty"`
Warnings []string `json:"warnings,omitempty"`
// GenSecrets: secrets an apply would mint, real work, so a preview with
// only these is not "empty" for --detailed-exitcode.
GenSecrets []string `json:"gen_secrets,omitempty"`
Destructive bool `json:"destructive"`
}
Plan is a config-as-code plan. Changes/Destructive are populated on the single-plan routes; a listing returns headers only.
type PlanChange ¶
type PlanChange struct {
Kind string `json:"kind"`
Env string `json:"env"`
// Scope is set instead of Env on a row for a value the config declares
// (stack | org): the value lives at the scope, not in an environment.
Scope string `json:"scope,omitempty"`
Tile string `json:"tile,omitempty"`
Field string `json:"field,omitempty"`
Old string `json:"old,omitempty"`
New string `json:"new,omitempty"`
Note string `json:"note,omitempty"`
Destroys bool `json:"destroys,omitempty"`
}
PlanChange is one line of a config plan's diff.
type PromoteResult ¶
type PromoteResult struct {
Env string `json:"env"`
Commit string `json:"commit"`
Plan string `json:"plan,omitempty"`
Job string `json:"job,omitempty"`
}
PromoteResult says what the promote started.
type Provision ¶
type Provision struct {
ID string `json:"id"`
InstanceID string `json:"instance_id"`
ConsumerID string `json:"consumer_id"`
DBName string `json:"db_name"`
Secret string `json:"secret"`
Status string `json:"status"`
}
Provision is one logical database an app holds inside a shared instance.
type ProxyConfig ¶
type ProxyConfig struct {
StaticOverride string `json:"static_override"`
OverrideActive bool `json:"override_active"`
CurrentStatic string `json:"current_static"`
Entries map[string]string `json:"entries"`
}
ProxyConfig is the traefik escape-hatch state.
type RefOutput ¶
type RefOutput struct {
Name string `json:"name"`
Kind string `json:"kind"`
Secret bool `json:"secret,omitempty"`
}
RefOutput is one name a source publishes.
type RefSource ¶
type RefSource struct {
Scope string `json:"scope"`
Slug string `json:"slug,omitempty"`
Kind string `json:"kind"`
Outputs []RefOutput `json:"outputs"`
}
RefSource is one thing a tile may reference. Carries no values: the catalogue has to be safe to show a caller without secrets:read.
type Registry ¶
type Registry struct {
ID string `json:"id"`
Name string `json:"name"`
URL string `json:"url"`
Domain string `json:"domain,omitempty"`
Username string `json:"username,omitempty"`
Managed bool `json:"managed"`
}
Registry is one registry stackr knows about: the managed one, or an external one a tile pulls from. The password is never returned.
type RegistryCredential ¶
type RegistryCredential struct {
ID string `json:"id"`
Name string `json:"name"`
Prefix string `json:"prefix"`
System bool `json:"system"`
CreatedAt time.Time `json:"created_at"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
Secret string `json:"secret,omitempty"`
}
RegistryCredential is one push credential for an org's registry namespace. Secret is filled exactly once, by the create that minted it.
type RegistryImage ¶
RegistryImage is one repository in an org's namespace.
type RegistryTag ¶
type RegistryTag struct {
Tag string `json:"tag"`
Digest string `json:"digest,omitempty"`
Size int64 `json:"size,omitempty"`
}
RegistryTag is one tag of one image.
type Release ¶
type Release struct {
Commit string `json:"commit"`
Built bool `json:"built"`
Building bool `json:"building"`
RunningOn []string `json:"running_on"`
PendingPlan string `json:"pending_plan,omitempty"`
}
Release is one commit this stack has built, and where it stands.
type Resource ¶
type Resource struct {
ID string `json:"id"`
Slug string `json:"slug"`
Kind string `json:"kind"`
Status string `json:"status"`
Bound bool `json:"bound"`
Outputs []RefOutput `json:"outputs,omitempty"`
}
Resource is one managed resource (a logical database or bucket) in a tile's environment, with the output names it publishes.
type SettingKnob ¶
type SettingKnob struct {
Key string `json:"key"`
Value string `json:"value"`
Source string `json:"source"`
Own *string `json:"own,omitempty"`
}
SettingKnob is one default: what applies at this level, which level decided it, and this level's own override when it has one.
type SettingsLevel ¶
type SettingsLevel struct {
Level string `json:"level"`
Values []SettingKnob `json:"values"`
}
type Slice ¶
type Slice struct {
ID string `json:"id"`
InstanceID string `json:"instance_id"`
Name string `json:"name"`
Slug string `json:"slug"`
Status string `json:"status"`
Public bool `json:"public"`
Consumers []string `json:"consumers"`
}
Slice is one logical database or bucket cut from a shared instance.
type StorageCreate ¶
type StorageCreate struct {
Name string `json:"name"`
Backend string `json:"backend"`
Address string `json:"address,omitempty"`
Export string `json:"export,omitempty"`
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
Opts string `json:"opts,omitempty"`
Org string `json:"org,omitempty"`
}
type StorageEntry ¶
type StorageEntry struct {
ID string `json:"id"`
Name string `json:"name"`
Slug string `json:"slug"`
Backend string `json:"backend"`
Status string `json:"status"`
StatusMsg string `json:"status_msg"`
Org string `json:"org,omitempty"`
Paths []StoragePath `json:"paths"`
}
Storage is a server-scoped share/pool with its declared sub-paths.
type StoragePath ¶
type StoragePathCreate ¶
type Target ¶
type Target struct {
Kind string `json:"kind"` // "instance" | "slice"
ID string `json:"id"`
InstanceID string `json:"instance_id"`
Name string `json:"name"`
Path string `json:"path"` // fully-qualified, for confirmation prompts
}
Target is what an infra path names: a shared instance or one slice of one.
type Var ¶
type Var struct {
Name string `json:"name"`
Value string `json:"value"`
Secret bool `json:"secret,omitempty"`
// Generate mints the value on the server, with the same generator the
// config file's `default: generated` uses. A name that already has a value
// is left alone: generating over a live secret would break everything
// reading it.
Generate bool `json:"generate,omitempty"`
Length int `json:"length,omitempty"`
}
Var is one app variable. Value may hold a ${{ ... }} reference; Secret marks it as masked on read without the secrets:read scope.
type VarScope ¶
VarScope names which variable set to act on. Exactly one field is set: an app's own variables, an environment's own values, or the stack/org set those cascade down from.
type Volume ¶
type Volume struct {
ID string `json:"id"`
Name string `json:"name"`
MountPath string `json:"mount_path"`
VolumeName string `json:"volume_name"`
Status string `json:"status"`
}
Volume is a persistent volume mounted into an app.
type VolumeCreate ¶
type VolumeCreate struct {
Name string `json:"name"`
MountPath string `json:"mount_path"`
VolumeName string `json:"volume_name,omitempty"`
MaxSizeMB int `json:"max_size_mb,omitempty"`
}
VolumeCreate is a volume's full shape. VolumeName adopts an existing docker volume instead of creating one named after the tile, which is how data from a pre-stackr deployment is kept rather than started over.