cli

package
v0.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package cli implements the `stackr` command-line client.

Index

Constants

This section is empty.

Variables

View Source
var ErrNotLoggedIn = errors.New("not logged in; run `stackr login <url>`")

ErrNotLoggedIn is returned by Load when no config file exists yet.

Functions

func Clear

func Clear() error

Clear removes the saved credential. Absent file is not an error.

func DotenvQuote

func DotenvQuote(v string) string

DotenvQuote quotes a value when bare text would not survive a round trip: anything with whitespace, quotes, newlines, or shell-significant characters.

func LoginBrowser

func LoginBrowser(ctx context.Context, rawURL string) error

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

func LoginWithKey(ctx context.Context, rawURL, key string) error

LoginWithKey saves an explicitly-provided key after verifying it works.

func RemoveLink() error

RemoveLink deletes the nearest link file. os.ErrNotExist if none is linked.

func Save

func Save(c Config) error

Save writes the credential with owner-only permissions (0600 file, 0700 dir).

func SaveLink(dir string, l Link) error

SaveLink writes the link into ./.stackr/link.json in the given directory.

Types

type APIError

type APIError struct {
	StatusCode int
	Code       string
	Message    string
}

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) APICode

func (e *APIError) APICode() string

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) HTTPStatus

func (e *APIError) HTTPStatus() int

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

type Client struct {
	BaseURL string
	Key     string
	HTTP    *http.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 NewClient

func NewClient(c Config) *Client

NewClient builds a client from a saved config.

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) AddInvite

func (c *Client) AddInvite(ctx context.Context, org, email, role string, days int) (Invite, error)

func (*Client) AddMember

func (c *Client) AddMember(ctx context.Context, org, email, role string, days int) (Invite, error)

AddMember invites rather than inserting a membership: a user row comes from accepting an invite.

func (*Client) AddRegistry

func (c *Client) AddRegistry(ctx context.Context, in Registry, password string) (Registry, error)

func (*Client) AddRegistryCredential

func (c *Client) AddRegistryCredential(ctx context.Context, org, name string) (RegistryCredential, error)

func (*Client) AddVolume

func (c *Client) AddVolume(ctx context.Context, appID, name, mountPath string) (Volume, error)

AddVolume creates a volume mounted into an app at mountPath and redeploys it.

func (*Client) AddVolumeWith

func (c *Client) AddVolumeWith(ctx context.Context, appID string, in VolumeCreate) (Volume, error)

AddVolumeWith mounts a volume with every field set.

func (*Client) ApproveOrgPlan

func (c *Client) ApproveOrgPlan(ctx context.Context, planID string) (Plan, error)

func (*Client) ApprovePlan

func (c *Client) ApprovePlan(ctx context.Context, planID string) (Plan, error)

ApprovePlan applies a pending plan.

func (*Client) Apps

func (c *Client) Apps(ctx context.Context, stack, env string) ([]App, error)

Apps lists apps, optionally scoped to a stack and/or environment.

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

func (c *Client) AutoDomain(ctx context.Context, appID string) (Domain, error)

AutoDomain generates the tile's hostname under whichever domain resource its environment nests below.

func (*Client) BackupRuns

func (c *Client) BackupRuns(ctx context.Context, id string) ([]BackupRun, error)

BackupRuns lists a schedule's run history, which is also where a restore's run id comes from.

func (*Client) Backups

func (c *Client) Backups(ctx context.Context, tileID string) ([]Backup, error)

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

func (c *Client) CancelDeployment(ctx context.Context, id string) (Deployment, error)

CancelDeployment stops a build or roll-out in flight.

func (*Client) CopyEnv

func (c *Client) CopyEnv(ctx context.Context, envID, name string, ephemeral bool) (Env, error)

CopyEnv creates a new environment from an existing one: same tiles, nothing deployed.

func (*Client) CreateApp

func (c *Client) CreateApp(ctx context.Context, stackID string, in AppCreate) (App, error)

CreateApp creates a service or cron app in a stack.

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) CreateEnv

func (c *Client) CreateEnv(ctx context.Context, stackID, name string) (Env, error)

CreateEnv creates an environment in a stack.

func (*Client) CreateStack

func (c *Client) CreateStack(ctx context.Context, name, desc, orgID string) (Stack, error)

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

func (c *Client) DBs(ctx context.Context) ([]DB, error)

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) DeleteApp

func (c *Client) DeleteApp(ctx context.Context, appID string) error

DeleteApp removes a tile: its containers, its proxy route and its row.

func (*Client) DeleteBackup

func (c *Client) DeleteBackup(ctx context.Context, id string) error

DeleteBackup removes a schedule. Archives already written are not touched.

func (*Client) DeleteDB

func (c *Client) DeleteDB(ctx context.Context, dbID string, force bool) error

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

func (c *Client) DeleteDestination(ctx context.Context, id string) error

DeleteDestination removes a destination. Archives already in the bucket stay.

func (*Client) DeleteDomain

func (c *Client) DeleteDomain(ctx context.Context, domainID string) error

DeleteDomain removes a host by id and re-syncs the proxy.

func (*Client) DeleteDomainResource

func (c *Client) DeleteDomainResource(ctx context.Context, id string) error

DeleteDomainResource removes a resource by id.

func (*Client) DeleteEnv

func (c *Client) DeleteEnv(ctx context.Context, envID string, force bool) error

DeleteEnv tears an environment down. force is required once tiles are running there.

func (*Client) DeleteInvite

func (c *Client) DeleteInvite(ctx context.Context, org, id string) error

func (*Client) DeleteProxyEntry

func (c *Client) DeleteProxyEntry(ctx context.Context, name string) error

func (*Client) DeleteRegistry

func (c *Client) DeleteRegistry(ctx context.Context, id string) error

func (*Client) DeleteRegistryCredential

func (c *Client) DeleteRegistryCredential(ctx context.Context, org, id string) error

func (*Client) DeleteRegistryTag

func (c *Client) DeleteRegistryTag(ctx context.Context, org, name, tag string) error

func (*Client) DeleteSlice

func (c *Client) DeleteSlice(ctx context.Context, provisionID string) error

DeleteSlice destroys one logical database or bucket, and with it every consumer's link to it.

func (*Client) DeleteStack

func (c *Client) DeleteStack(ctx context.Context, stackID string) error

DeleteStack removes a stack and everything in it.

func (*Client) DeleteStorage

func (c *Client) DeleteStorage(ctx context.Context, id string) error

func (*Client) DeleteStoragePath

func (c *Client) DeleteStoragePath(ctx context.Context, id string) error

func (*Client) DeleteVolume

func (c *Client) DeleteVolume(ctx context.Context, volumeID string) error

DeleteVolume removes a volume by id (its data is preserved) and redeploys.

func (*Client) Deploy

func (c *Client) Deploy(ctx context.Context, appID string) (string, error)

Deploy triggers a deployment and returns the new deployment id.

func (*Client) DeploymentLogs

func (c *Client) DeploymentLogs(ctx context.Context, id string) (string, error)

DeploymentLogs returns one deployment's build output.

func (*Client) Deployments

func (c *Client) Deployments(ctx context.Context, appID string) ([]Deployment, error)

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

func (c *Client) DetachProvision(ctx context.Context, appID, provisionID string) error

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) Domains

func (c *Client) Domains(ctx context.Context, appID string) ([]Domain, error)

Domains lists an app's hosts.

func (*Client) Envs

func (c *Client) Envs(ctx context.Context, stackID string) ([]Env, error)

Envs lists the environments of a stack.

func (*Client) ExportOrgConfig

func (c *Client) ExportOrgConfig(ctx context.Context, org string) ([]byte, error)

ExportOrgConfig does the same for an organization.

func (*Client) ExportStackConfig

func (c *Client) ExportStackConfig(ctx context.Context, stackID string) ([]byte, error)

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

func (c *Client) ForkSlice(ctx context.Context, provisionID, name string) (Slice, error)

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

func (c *Client) Forward(ctx context.Context, tileID string, port int) (net.Conn, int, error)

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) GetApp

func (c *Client) GetApp(ctx context.Context, appID string) (App, error)

GetApp reads one tile.

func (*Client) GetDB

func (c *Client) GetDB(ctx context.Context, dbID string) (DB, error)

GetDB reads one shared instance.

func (*Client) GetDeployment

func (c *Client) GetDeployment(ctx context.Context, id string) (Deployment, error)

GetDeployment reads one deployment's current state.

func (*Client) GetPREnv

func (c *Client) GetPREnv(ctx context.Context, stackID string) (PREnv, error)

GetPREnv reads a stack's PR environment settings.

func (*Client) InstanceSlices

func (c *Client) InstanceSlices(ctx context.Context, dbID string) ([]Slice, error)

InstanceSlices lists the slices cut from one shared instance.

func (*Client) Invites

func (c *Client) Invites(ctx context.Context, org string) ([]Invite, error)

func (*Client) LatestRestore added in v0.4.0

func (c *Client) LatestRestore(ctx context.Context, backupID string) (RestoreStatus, error)

LatestRestore reads the newest restore of a backup.

func (*Client) ListProvisions

func (c *Client) ListProvisions(ctx context.Context, appID string) ([]Provision, error)

ListProvisions lists the logical databases an app holds.

func (*Client) ListStorage

func (c *Client) ListStorage(ctx context.Context) ([]StorageEntry, error)

func (*Client) Logs

func (c *Client) Logs(ctx context.Context, appID string, tail int) (string, error)

Logs returns the last `tail` log lines as a single string.

func (*Client) Members

func (c *Client) Members(ctx context.Context, org string) ([]Member, error)

func (*Client) Metrics

func (c *Client) Metrics(ctx context.Context, appID, window string) ([]Metric, error)

Metrics reads a tile's sampled resource use. window is "1h", "6h" or "24h".

func (*Client) OrgPlanNow

func (c *Client) OrgPlanNow(ctx context.Context, orgID string) (Plan, error)

func (*Client) OrgPlanPreview

func (c *Client) OrgPlanPreview(ctx context.Context, orgID, main string) (Plan, error)

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

func (c *Client) OrgPlans(ctx context.Context, orgID string) ([]Plan, error)

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) Orgs

func (c *Client) Orgs(ctx context.Context) ([]Org, error)

Orgs lists the organizations the key can see.

func (*Client) PatchApp

func (c *Client) PatchApp(ctx context.Context, appID string, fields map[string]any) (App, error)

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

func (c *Client) PatchBackup(ctx context.Context, id string, fields map[string]any) (Backup, error)

PatchBackup changes a schedule's destination, cron, retention or enabled flag.

func (*Client) PatchDB

func (c *Client) PatchDB(ctx context.Context, dbID string, s DBSettings) (DB, error)

PatchDB updates a shared instance's port, scope, or resource limits.

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) PatchEnv

func (c *Client) PatchEnv(ctx context.Context, envID string, fields map[string]any) (Env, error)

PatchEnv changes an environment's colour or apply policy.

func (*Client) PatchRegistry

func (c *Client) PatchRegistry(ctx context.Context, id string, fields map[string]any) (Registry, error)

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) Plan

func (c *Client) Plan(ctx context.Context, planID string) (Plan, error)

Plan fetches one plan with its full change list.

func (*Client) PlanNow

func (c *Client) PlanNow(ctx context.Context, stackID string) ([]Plan, error)

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) Plans

func (c *Client) Plans(ctx context.Context, stackID string, limit int) ([]Plan, error)

func (*Client) ProbeStorage

func (c *Client) ProbeStorage(ctx context.Context, id string) (StorageEntry, error)

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 (c *Client) PutProxyEntry(ctx context.Context, name, yamlBody string) (ProxyConfig, error)

func (*Client) PutProxyOverride

func (c *Client) PutProxyOverride(ctx context.Context, yamlBody string) (ProxyConfig, error)

func (*Client) ReferenceCatalogue

func (c *Client) ReferenceCatalogue(ctx context.Context, appID string) ([]RefSource, error)

ReferenceCatalogue lists what a tile may reference.

func (*Client) Registries

func (c *Client) Registries(ctx context.Context) ([]Registry, error)

func (*Client) RegistryCredentials

func (c *Client) RegistryCredentials(ctx context.Context, org string) ([]RegistryCredential, error)

func (*Client) RegistryImages

func (c *Client) RegistryImages(ctx context.Context, org string) ([]RegistryImage, error)

func (*Client) RegistryTags

func (c *Client) RegistryTags(ctx context.Context, org, name string) ([]RegistryTag, error)

func (*Client) RejectOrgPlan

func (c *Client) RejectOrgPlan(ctx context.Context, planID string) (Plan, error)

func (*Client) RejectPlan

func (c *Client) RejectPlan(ctx context.Context, planID string) (Plan, error)

RejectPlan closes a pending plan without applying it.

func (*Client) Releases

func (c *Client) Releases(ctx context.Context, stackID string) ([]Release, error)

Releases lists what a stack can promote, newest first.

func (*Client) RemoveMember

func (c *Client) RemoveMember(ctx context.Context, org, userID string) error

func (*Client) ResetEnv

func (c *Client) ResetEnv(ctx context.Context, envID string, force bool) error

ResetEnv tears a config-managed environment down so the next apply rebuilds it from the file.

func (*Client) Resolve

func (c *Client) Resolve(ctx context.Context, path, envID string) (Target, error)

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

func (c *Client) ResolvedVars(ctx context.Context, appID string) ([]Var, error)

ResolvedVars returns the environment a deploy would produce, references expanded. Fails rather than omitting when the key can't read a secret.

func (*Client) Resources

func (c *Client) Resources(ctx context.Context, appID string) ([]Resource, error)

Resources lists the managed resources visible to a tile.

func (*Client) RestartApp

func (c *Client) RestartApp(ctx context.Context, appID string) (App, error)

RestartApp bounces a tile in place: no rebuild, no new image.

func (*Client) Restore

func (c *Client) Restore(ctx context.Context, backupID, runID string) (RestoreStatus, error)

Restore queues an archive to be written back over the live database or volume. Needs the backups:restore scope, which is granted separately from backups:write.

func (*Client) Rollback

func (c *Client) Rollback(ctx context.Context, appID, imageTag string) (string, error)

Rollback redeploys an image tag the tile has run before.

func (*Client) RunApp

func (c *Client) RunApp(ctx context.Context, appID string) error

RunApp fires one immediate run of a cron or function tile.

func (*Client) RunBackup

func (c *Client) RunBackup(ctx context.Context, id string) (BackupRun, error)

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 (c *Client) SetMemberRole(ctx context.Context, org, userID, role string) (Member, error)

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

func (c *Client) SetVarsAt(ctx context.Context, scope VarScope, vars []Var) ([]Var, error)

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) Settings

func (c *Client) Settings(ctx context.Context, kind, id string) (SettingsLevel, error)

Settings reads one level of the defaults cascade.

func (*Client) Stacks

func (c *Client) Stacks(ctx context.Context) ([]Stack, error)

Stacks lists stacks visible to the key. It doubles as the auth check: a 401/403 surfaces as an error.

func (*Client) StopApp

func (c *Client) StopApp(ctx context.Context, appID string) (App, error)

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) StopRun

func (c *Client) StopRun(ctx context.Context, appID, runID string) error

StopRun stops a cron or function run that is still in flight.

func (*Client) ToggleCron

func (c *Client) ToggleCron(ctx context.Context, appID string) (App, error)

ToggleCron pauses a running schedule or resumes a paused one. The answer carries the state it landed in.

func (*Client) UnresolvedVars

func (c *Client) UnresolvedVars(ctx context.Context, appID string) ([]Var, error)

UnresolvedVars lists a tile's variables exactly as stored, references unexpanded. This is what you edit against; ResolvedVars is what the container will see.

func (*Client) VarsAt

func (c *Client) VarsAt(ctx context.Context, scope VarScope) ([]Var, error)

VarsAt reads one variable set.

func (*Client) Volumes

func (c *Client) Volumes(ctx context.Context, appID string) ([]Volume, error)

Volumes lists an app's volumes.

type Config

type Config struct {
	URL string `json:"url"`
	Key string `json:"key"`
}

Config is the persisted CLI credential: which server, which key.

func Load

func Load() (Config, error)

Load reads the saved credential. Missing file → ErrNotLoggedIn.

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"`
	Shared   bool   `json:"shared"`
}

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"`
	// Shared offers a server-wide destination to every organization. The
	// 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 Env

type Env struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Slug string `json:"slug"`
}

Env is an environment within a stack.

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

func FindLink() (Link, string, error)

FindLink walks up from cwd looking for the nearest .stackr/link.json (like git finding .git). Returns the link and the repo root that holds it. os.ErrNotExist if no link is found up to the filesystem root.

type LogEvent

type LogEvent struct {
	Stream string `json:"stream"`
	Line   string `json:"line"`
}

LogEvent is one live log line with its origin stream ("stdout"/"stderr").

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.

func (RefSource) Expr

func (s RefSource) Expr(name string) string

Expr renders the reference expression for one output, the string you paste into a variable.

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

type RegistryImage struct {
	Name  string `json:"name"`
	Short string `json:"short"`
}

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 RestoreStatus added in v0.4.0

type RestoreStatus struct {
	ID     string `json:"id"`
	Status string `json:"status"`
	Step   string `json:"step"`
	Error  string `json:"error"`
}

RestoreStatus is one restore as the server's work queue tracks it.

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 Stack

type Stack struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

Stack is a stack visible to the key.

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 StoragePath struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Subpath  string `json:"subpath"`
	ForcedRO bool   `json:"forced_ro"`
	Volume   string `json:"volume"`
}

type StoragePathCreate

type StoragePathCreate struct {
	Name     string `json:"name"`
	Subpath  string `json:"subpath,omitempty"`
	ForcedRO bool   `json:"forced_ro,omitempty"`
}

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

type VarScope struct {
	App   string
	Env   string
	Stack string
	Org   string
}

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.

func (VarScope) Label

func (s VarScope) Label() string

Label names the scope for human output.

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.

Directories

Path Synopsis
Package cmd is the cobra command tree for the stackr CLI.
Package cmd is the cobra command tree for the stackr CLI.

Jump to

Keyboard shortcuts

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