api

package
v0.20.4 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package api is a thin wrapper over the Miabi /api/v1 HTTP surface, built on github.com/jkaninda/okapi/client. It unwraps the server's {success,data,error} envelope and maps the structured error to a Go error with a stable code.

Index

Constants

View Source
const (
	StatusSucceeded = "succeeded"
	StatusRunning   = "running" // legacy terminal success
	StatusFailed    = "failed"
	// StatusCanary is a canary serving part of the traffic. It is not terminal: it
	// waits for a human to promote or abort it.
	StatusCanary = "canary"
)

Deploy-status classification. The server treats succeeded (and the legacy "running") as terminal success and "failed" as terminal failure; everything else is in-progress.

View Source
const (
	BackupPending   = "pending"
	BackupRunning   = "running"
	BackupCompleted = "completed"
	BackupFailed    = "failed"
)

Backup-run statuses. These are NOT the deploy statuses: "running" is terminal for a deployment and in-flight for a backup, so they need their own classification.

View Source
const BackupRunTimeout = 30 * time.Minute

BackupRunTimeout bounds a manual database backup, which the server runs inline in the request.

View Source
const FileTransferTimeout = 30 * time.Minute

FileTransferTimeout bounds one volume file upload or download. The default 30s client timeout covers control-plane calls; moving a multi-hundred-MB file over a slow link is a different order of magnitude.

View Source
const MaxEventPage = 100

MaxEventPage is the largest page the workspace events feed serves.

View Source
const MaxListedVolumeFiles = 5000

MaxListedVolumeFiles mirrors the panel's listing cap. It is not reported in the payload, so a listing sitting exactly on it is the only signal that entries were dropped.

View Source
const MaxServerWait = 900 * time.Second

MaxServerWait is the longest ?wait= the server accepts on deploy and rollback.

View Source
const MaxVolumeUploadBytes = 512 << 20

MaxVolumeUploadBytes mirrors the panel's per-file upload cap, so an oversized file fails before it is read and sent rather than after.

View Source
const RestoreTimeout = 60 * time.Minute

RestoreTimeout bounds a restore. The panel runs the restore inline in the request — it pulls an image and unpacks an archive before answering — so the 30s control-plane deadline would abort a restore that is going fine.

Variables

View Source
var Version = "dev"

Version is stamped at build time (see .goreleaser.yaml); used in User-Agent.

Functions

func IsBackupFailure added in v0.12.0

func IsBackupFailure(status string) bool

IsBackupFailure reports a terminal backup failure.

func IsBackupTerminal added in v0.12.0

func IsBackupTerminal(status string) bool

IsBackupTerminal reports whether a backup run has settled.

func IsFailure

func IsFailure(status string) bool

IsFailure reports a terminal failure.

func IsRunTerminal added in v0.17.0

func IsRunTerminal(status string) bool

IsRunTerminal reports whether a pipeline run has settled.

func IsSettled added in v0.17.0

func IsSettled(status string) bool

IsSettled reports whether waiting on a deployment can stop: it is terminal, or it is a canary that will not move until someone promotes it.

func IsTerminal

func IsTerminal(status string) bool

IsTerminal reports whether a deployment status will not change further.

func MigrationSettled added in v0.16.0

func MigrationSettled(status string) bool

MigrationSettled reports whether a migration has stopped moving on its own: it cut over, waits for a person, or ended.

Types

type APIError

type APIError struct {
	StatusCode int    `json:"status_code"`
	Code       string `json:"code"`
	Message    string `json:"message"`
	Detail     string `json:"error"`
}

APIError is the server's structured error envelope.

func (*APIError) Error

func (e *APIError) Error() string

type Alert added in v0.17.0

type Alert struct {
	ID          uint      `json:"id"`
	Category    string    `json:"category"`
	Severity    string    `json:"severity"`
	State       string    `json:"state"` // firing | acknowledged | resolved
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	Count       int64     `json:"count"`
	SubjectType string    `json:"subject_type"`
	SubjectRef  string    `json:"subject_ref"`
	FirstSeen   time.Time `json:"first_seen"`
	LastSeen    time.Time `json:"last_seen"`
}

Alert is a deduplicated workspace alert.

type App

type App struct {
	ID          uint   `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	Image       string `json:"image"`
	Tag         string `json:"tag"`
	// SourceType is "image" or "git" — what the app builds from.
	SourceType       string    `json:"source_type"`
	GitRepo          string    `json:"git_repo,omitempty"`
	GitRef           string    `json:"git_ref,omitempty"`
	Status           string    `json:"status"`
	CurrentReleaseID *uint     `json:"current_release_id"`
	CreatedAt        time.Time `json:"created_at"`
}

App is an application listing/detail (only the fields the CLI surfaces). Name is the unique handle; DisplayName is the free-text label.

type AppDatabase added in v0.18.0

type AppDatabase struct {
	LogicalDatabase
	Kind         string `json:"kind"`
	InstanceName string `json:"instance_name"`
	Engine       string `json:"engine"`
	Host         string `json:"host"`
	Port         int    `json:"port"`
}

AppDatabase is a database linked to an app: a logical database (kind "database") or a whole instance such as Redis (kind "instance", id and name are the instance's).

type ApplyFailure

type ApplyFailure struct {
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	Action string `json:"action"`
	Error  string `json:"error"`
}

ApplyFailure is one resource that failed to converge.

type ApplyRequest

type ApplyRequest struct {
	Manifests string `json:"manifests"`
	Prune     bool   `json:"prune"`
	DryRun    bool   `json:"dry_run"`
	// Delete removes exactly the resources the bundle names instead of converging.
	Delete bool `json:"delete,omitempty"`
	// Force changes resources a GitOps project owns; its next sync reverts them.
	Force bool `json:"force,omitempty"`
}

ApplyRequest is the body of POST .../apply — a miabi.io/v1 manifest bundle and the converge options.

type ApplyResult

type ApplyResult struct {
	Plan     *Plan          `json:"plan"`
	Applied  int            `json:"applied"`
	DryRun   bool           `json:"dry_run"`
	Failures []ApplyFailure `json:"failures,omitempty"`
}

ApplyResult is what a non-dry-run apply returns.

type AttachVolumeRequest added in v0.12.0

type AttachVolumeRequest struct {
	VolumeID uint   `json:"volume_id"`
	Path     string `json:"path"`
}

AttachVolumeRequest is the body of POST .../apps/{id}/volumes.

type Backup added in v0.17.0

type Backup struct {
	ID          uint       `json:"id"`
	Number      int        `json:"number"`
	Status      string     `json:"status"`
	Trigger     string     `json:"trigger"`
	Destination string     `json:"destination"`
	SizeBytes   int64      `json:"size_bytes"`
	Comment     string     `json:"comment,omitempty"`
	Error       string     `json:"error,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	FinishedAt  *time.Time `json:"finished_at,omitempty"`
}

Backup is one logical-database backup run.

type Change

type Change struct {
	Action string `json:"action"` // create | update | delete | noop
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	Reason string `json:"reason,omitempty"`
}

Change is one planned operation on a resource.

type Client

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

Client talks to one panel with one token.

func New

func New(o Options) (*Client, error)

New builds a client from o. It returns an error only when a configured CA bundle cannot be read or parsed — a misconfigured trust root should fail loudly rather than silently fall back to the system roots.

func (*Client) AckAlert added in v0.17.0

func (c *Client) AckAlert(ctx context.Context, ws string, id uint) (*Alert, error)

AckAlert acknowledges an alert: it stays active but stops re-notifying.

func (*Client) Alerts added in v0.17.0

func (c *Client) Alerts(ctx context.Context, ws string, activeOnly bool) ([]Alert, error)

Alerts lists a workspace's alerts; activeOnly keeps the firing and acknowledged ones.

func (*Client) App

func (c *Client) App(ctx context.Context, ws string, app string) (*App, error)

func (*Client) AppDatabases added in v0.18.0

func (c *Client) AppDatabases(ctx context.Context, ws string, app string) ([]AppDatabase, error)

AppDatabases lists the databases linked to an app.

func (*Client) AppEvents added in v0.17.0

func (c *Client) AppEvents(ctx context.Context, ws string, app string, limit int) ([]Event, error)

AppEvents returns an application's newest events.

func (*Client) AppMigrations added in v0.16.0

func (c *Client) AppMigrations(ctx context.Context, ws string, app string) ([]Migration, error)

func (*Client) Apply

func (c *Client) Apply(ctx context.Context, ws string, manifests string, prune, force bool) (*ApplyResult, error)

Apply converges the workspace to the manifest bundle.

func (*Client) Apps

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

func (*Client) AttachDatabase added in v0.18.0

func (c *Client) AttachDatabase(ctx context.Context, ws string, app string, dbID uint, req LinkDatabaseRequest) (*LinkDatabaseResult, error)

AttachDatabase links a logical database to an app and injects its connection.

func (*Client) AttachVolume added in v0.12.0

func (c *Client) AttachVolume(ctx context.Context, ws string, app string, req AttachVolumeRequest) error

AttachVolume mounts a volume into an application at path. It flags the app as needing a redeploy; it does not restart it.

func (*Client) Backups added in v0.17.0

func (c *Client) Backups(ctx context.Context, ws string, id, dbID uint) ([]Backup, error)

Backups lists a logical database's backup history.

func (*Client) ClaimLoginToken added in v0.10.0

func (c *Client) ClaimLoginToken(ctx context.Context, code string) (*LoginToken, error)

ClaimLoginToken exchanges a single-use hand-off code (delivered to the CLI's loopback callback by the browser login flow) for the minted token. The endpoint is public — the code is itself the short-lived, one-time credential — so this works on a client built without a token.

func (*Client) Config added in v0.10.0

func (c *Client) Config(ctx context.Context, ws string, id uint) (*Config, error)

func (*Client) ConfigData added in v0.10.0

func (c *Client) ConfigData(ctx context.Context, ws string, id uint) (map[string]string, error)

ConfigData returns a config's decrypted files (admin only, audited).

func (*Client) ConfigUsage added in v0.10.0

func (c *Client) ConfigUsage(ctx context.Context, ws string, id uint) ([]SecretUsage, error)

func (*Client) Configs added in v0.10.0

func (c *Client) Configs(ctx context.Context, ws string) ([]Config, error)

Configs lists a workspace's configs (keys and digests, never content).

func (*Client) CreateApp added in v0.10.0

func (c *Client) CreateApp(ctx context.Context, ws string, req CreateAppRequest) (*App, error)

func (*Client) CreateConfig added in v0.10.0

func (c *Client) CreateConfig(ctx context.Context, ws string, req CreateConfigRequest) (*Config, error)

func (*Client) CreateDatabase added in v0.10.0

func (c *Client) CreateDatabase(ctx context.Context, ws string, req CreateDatabaseRequest) (*DatabaseInstance, error)

func (*Client) CreateLogicalDatabase added in v0.10.0

func (c *Client) CreateLogicalDatabase(ctx context.Context, ws string, id uint, req CreateLogicalDatabaseRequest) (*CreateLogicalDatabaseResult, error)

func (*Client) CreateSecret added in v0.10.0

func (c *Client) CreateSecret(ctx context.Context, ws string, req CreateSecretRequest) (*Secret, error)

func (*Client) CreateVolume added in v0.12.0

func (c *Client) CreateVolume(ctx context.Context, ws string, req CreateVolumeRequest) (*Volume, error)

func (*Client) Database added in v0.10.0

func (c *Client) Database(ctx context.Context, ws string, id uint) (*DatabaseInstance, error)

func (*Client) DatabaseCredentials added in v0.10.0

func (c *Client) DatabaseCredentials(ctx context.Context, ws string, id uint) (*ConnectionInfo, error)

func (*Client) DatabaseEngines added in v0.10.0

func (c *Client) DatabaseEngines(ctx context.Context, ws string) ([]EngineDefault, error)

func (*Client) Databases added in v0.10.0

func (c *Client) Databases(ctx context.Context, ws string) ([]DatabaseInstance, error)

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, ws string, manifests string) (*ApplyResult, error)

Delete removes exactly the resources the bundle names.

func (*Client) DeleteApp added in v0.10.0

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

func (*Client) DeleteConfig added in v0.10.0

func (c *Client) DeleteConfig(ctx context.Context, ws string, id uint) error

func (*Client) DeleteDatabaseInstance added in v0.10.0

func (c *Client) DeleteDatabaseInstance(ctx context.Context, ws string, id uint) error

func (*Client) DeleteLogicalDatabase added in v0.10.0

func (c *Client) DeleteLogicalDatabase(ctx context.Context, ws string, id, dbID uint) error

func (*Client) DeleteSecret added in v0.10.0

func (c *Client) DeleteSecret(ctx context.Context, ws string, id uint) error

func (*Client) DeleteVolume added in v0.12.0

func (c *Client) DeleteVolume(ctx context.Context, ws string, id uint) error

DeleteVolume destroys a volume and its data. The server answers 409 while an application still mounts it.

func (*Client) DeleteVolumeBackup added in v0.12.0

func (c *Client) DeleteVolumeBackup(ctx context.Context, ws string, id, backupID uint) error

func (*Client) DeleteVolumeFile added in v0.12.0

func (c *Client) DeleteVolumeFile(ctx context.Context, ws string, id uint, path string) error

DeleteVolumeFile removes a file, or a directory and everything under it.

func (*Client) Deploy

func (c *Client) Deploy(ctx context.Context, ws string, app string, req DeployRequest, wait time.Duration) (*DeployResult, error)

Deploy triggers a deployment. A non-zero wait asks the server to hold the request until the deployment (or pipeline run) settles, up to MaxServerWait. Servers that predate ?wait answer at once, so callers must still check the status and poll when it is not settled.

func (*Client) Deployment

func (c *Client) Deployment(ctx context.Context, ws string, app string, depID uint) (*Deployment, error)

Deployment resolves a single deployment. Servers without the per-deployment GET route answer 404 (or 405), and it is then found within the recent list.

func (*Client) DeploymentByNumber added in v0.10.0

func (c *Client) DeploymentByNumber(ctx context.Context, ws string, app string, number int) (*Deployment, error)

DeploymentByNumber resolves a per-application deployment number (the value users pass) to the full deployment, whose durable ID API paths address by.

func (*Client) Deployments

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

func (*Client) DetachDatabase added in v0.18.0

func (c *Client) DetachDatabase(ctx context.Context, ws string, app string, dbID uint) error

func (*Client) DetachVolume added in v0.12.0

func (c *Client) DetachVolume(ctx context.Context, ws string, app string, volumeID uint) error

DetachVolume unmounts a volume from an application (the data is kept).

func (*Client) DownloadVolumeFile added in v0.12.0

func (c *Client) DownloadVolumeFile(ctx context.Context, ws string, id uint, path string, dst io.Writer) (int64, error)

DownloadVolumeFile copies one file out of a volume into dst and returns the number of bytes written. It streams: a volume file can be as large as the panel's 512 MiB cap, and holding that in memory to hand it straight to a file on disk is the kind of thing that gets a CLI OOM-killed on a small box.

func (*Client) EnvVars added in v0.10.0

func (c *Client) EnvVars(ctx context.Context, ws string, app string) ([]EnvVar, error)

EnvVars lists an application's environment variables. Secret values come back masked — the API never returns them in plaintext.

func (*Client) FindConfigByName added in v0.10.0

func (c *Client) FindConfigByName(ctx context.Context, ws, name string) (*Config, error)

FindConfigByName returns the named config, or nil when none exists (used by `set` to choose between create and replace).

func (*Client) FindSecretByName added in v0.10.0

func (c *Client) FindSecretByName(ctx context.Context, ws, name string) (*Secret, error)

FindSecretByName returns the workspace secret with the given name, or nil when none exists (used by `set` to choose between create and rotate).

func (*Client) FindVolumeBackup added in v0.12.0

func (c *Client) FindVolumeBackup(ctx context.Context, ws string, id, backupID uint) (*VolumeBackup, error)

FindVolumeBackup returns one backup from the volume's history. There is no single-backup endpoint, so this filters the list.

func (*Client) FindVolumeByName added in v0.12.0

func (c *Client) FindVolumeByName(ctx context.Context, ws, name string) (*Volume, error)

FindVolumeByName returns the named volume, or nil when none exists.

func (*Client) ImportEnv

func (c *Client) ImportEnv(ctx context.Context, ws string, app string, req ImportEnvRequest) error

func (*Client) InvalidateBuildCache added in v0.11.0

func (c *Client) InvalidateBuildCache(ctx context.Context, ws string, app string) error

InvalidateBuildCache names a new build cache generation for the app, so the next build (a deploy or a pipeline run) rebuilds every layer and repopulates it.

func (*Client) LinkDatabaseInstance added in v0.18.0

func (c *Client) LinkDatabaseInstance(ctx context.Context, ws string, app string, instID uint, req LinkDatabaseRequest) (*LinkDatabaseResult, error)

LinkDatabaseInstance links a whole instance (Redis) to an app.

func (*Client) LogicalDatabaseConnection added in v0.10.0

func (c *Client) LogicalDatabaseConnection(ctx context.Context, ws string, id, dbID uint) (*ConnectionInfo, error)

func (*Client) LogicalDatabases added in v0.10.0

func (c *Client) LogicalDatabases(ctx context.Context, ws string, id uint) ([]LogicalDatabase, error)

func (*Client) Me

func (c *Client) Me(ctx context.Context) (*Me, error)

func (*Client) Migration added in v0.16.0

func (c *Client) Migration(ctx context.Context, ws string, id uint) (*Migration, error)

func (*Client) MigrationAction added in v0.16.0

func (c *Client) MigrationAction(ctx context.Context, ws string, id uint, action string) (*Migration, error)

MigrationAction runs cutover, cancel, rollback or finalize.

func (*Client) Migrations added in v0.16.0

func (c *Client) Migrations(ctx context.Context, ws string) ([]Migration, error)

func (*Client) PinVolumeBackup added in v0.15.0

func (c *Client) PinVolumeBackup(ctx context.Context, ws string, id, backupID uint, pinned bool) (*VolumeBackup, error)

PinVolumeBackup exempts a recovery point from retention, or lifts the exemption.

func (*Client) PipelineRun added in v0.17.0

func (c *Client) PipelineRun(ctx context.Context, ws string, runID uint) (*PipelineRun, error)

PipelineRun returns one pipeline run.

func (*Client) Pipelines added in v0.11.0

func (c *Client) Pipelines(ctx context.Context, ws string) ([]Pipeline, error)

Pipelines lists the workspace's pipeline definitions.

func (*Client) PlanApply

func (c *Client) PlanApply(ctx context.Context, ws string, manifests string, prune, force bool) (*Plan, error)

PlanApply previews converging the workspace to the manifest bundle (dry-run).

func (*Client) PlanDelete

func (c *Client) PlanDelete(ctx context.Context, ws string, manifests string) (*Plan, error)

PlanDelete previews deleting exactly the resources the bundle names (dry-run).

func (*Client) PlanMigration added in v0.16.0

func (c *Client) PlanMigration(ctx context.Context, ws string, app string, body StartMigration) (*MigrationPlan, error)

func (*Client) ReleaseByVersion added in v0.10.0

func (c *Client) ReleaseByVersion(ctx context.Context, ws string, app string, version int) (*Release, error)

ReleaseByVersion resolves a per-application release version to the full release (the ID is what the rollback API expects).

func (*Client) Releases

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

func (*Client) RerunPipelineRun added in v0.11.0

func (c *Client) RerunPipelineRun(ctx context.Context, ws string, runID uint, req RerunPipelineRequest) (*PipelineRun, error)

RerunPipelineRun re-runs an earlier run at the same ref and commit.

func (*Client) ResolveAlert added in v0.17.0

func (c *Client) ResolveAlert(ctx context.Context, ws string, id uint) (*Alert, error)

ResolveAlert closes an alert.

func (*Client) ResolveConfigID added in v0.10.0

func (c *Client) ResolveConfigID(ctx context.Context, ws, ref string) (uint, error)

ResolveConfigID turns a config name (or numeric id) into its numeric id.

func (*Client) ResolveDatabaseID added in v0.10.0

func (c *Client) ResolveDatabaseID(ctx context.Context, ws, ref string) (uint, error)

ResolveDatabaseID turns a database handle (or numeric id) into the numeric id.

func (*Client) ResolveLogicalDatabaseID added in v0.17.0

func (c *Client) ResolveLogicalDatabaseID(ctx context.Context, ws string, id uint, ref string) (uint, error)

ResolveLogicalDatabaseID picks a database hosted on instance id by name or numeric id. An empty ref selects the instance's only database.

func (*Client) ResolveSecretID added in v0.10.0

func (c *Client) ResolveSecretID(ctx context.Context, ws, ref string) (uint, error)

ResolveSecretID turns a secret name (or numeric id) into its numeric id.

func (*Client) ResolveVolumeID added in v0.12.0

func (c *Client) ResolveVolumeID(ctx context.Context, ws, ref string) (uint, error)

ResolveVolumeID turns a volume name (or numeric id) into its numeric id.

func (*Client) ResolveWorkspaceName added in v0.10.0

func (c *Client) ResolveWorkspaceName(ctx context.Context, ref, fallback string) (string, error)

ResolveWorkspaceName turns a user-supplied workspace reference into the canonical name (handle) the API addresses by. ref may be the name, a UID, or a numeric id (resolved to its name for back-compat); an empty ref falls back to fallback (the persisted/bound workspace) and finally to the sole workspace the caller can see. The returned value is always a name, since scoped routes are addressed by name.

func (*Client) RestartApp added in v0.10.0

func (c *Client) RestartApp(ctx context.Context, ws string, app string) error

func (*Client) RestartDatabase added in v0.10.0

func (c *Client) RestartDatabase(ctx context.Context, ws string, id uint) error

func (*Client) RestoreVolumeBackup added in v0.12.0

func (c *Client) RestoreVolumeBackup(ctx context.Context, ws string, id, backupID uint) error

RestoreVolumeBackup overwrites a volume's contents from one of its backups. The call blocks for the whole restore.

func (*Client) ResyncAppPipeline added in v0.10.0

func (c *Client) ResyncAppPipeline(ctx context.Context, ws string, app string) (*ResyncPipelineResult, error)

ResyncAppPipeline reloads the repository's pipelines.yaml: adopting one when the app has none, and re-syncing the stored spec when it already has one.

func (*Client) RevealSecret added in v0.10.0

func (c *Client) RevealSecret(ctx context.Context, ws string, id uint) (string, error)

RevealSecret returns a secret's decrypted value (admin only, audited).

func (*Client) Rollback

func (c *Client) Rollback(ctx context.Context, ws string, app string, req RollbackRequest, wait time.Duration) (*DeployResult, error)

Rollback rolls back to a release. wait behaves as for Deploy.

func (*Client) RunBackup added in v0.17.0

func (c *Client) RunBackup(ctx context.Context, ws string, id, dbID uint, comment string) (*Backup, error)

RunBackup takes a manual backup to the workspace's configured destination and returns the finished record; its status says whether it succeeded.

func (*Client) RunVolumeBackup added in v0.12.0

func (c *Client) RunVolumeBackup(ctx context.Context, ws string, id uint) (*VolumeBackup, error)

RunVolumeBackup enqueues a backup and returns the pending record. The work happens in the panel's worker, so the record is not finished when this returns.

func (*Client) SealingKey added in v0.19.0

func (c *Client) SealingKey(ctx context.Context, ws string) (*SealingKey, error)

SealingKey returns the workspace's active public sealing key.

func (*Client) SecretUsage added in v0.10.0

func (c *Client) SecretUsage(ctx context.Context, ws string, id uint) ([]SecretUsage, error)

func (*Client) Secrets added in v0.10.0

func (c *Client) Secrets(ctx context.Context, ws string) ([]Secret, error)

Secrets lists a workspace's secrets (names + metadata, never values). The list endpoint is paginated; a large page size fetches them in one call.

func (*Client) SetAppSource added in v0.10.0

func (c *Client) SetAppSource(ctx context.Context, ws string, app string, req SetAppSourceRequest) (*SetAppSourceResult, error)

SetAppSource replaces where an app's image comes from, including switching between a prebuilt image and a Git build. It is a whole-source replacement: the server clears the fields belonging to the source being left, so a partial request would leave the app describing both.

func (*Client) SetEnv

func (c *Client) SetEnv(ctx context.Context, ws string, app string, req SetEnvRequest) error

func (*Client) StartApp added in v0.10.0

func (c *Client) StartApp(ctx context.Context, ws string, app string) error

func (*Client) StartDatabase added in v0.10.0

func (c *Client) StartDatabase(ctx context.Context, ws string, id uint) error

func (*Client) StartMigration added in v0.16.0

func (c *Client) StartMigration(ctx context.Context, ws string, app string, body StartMigration) (*Migration, error)

func (*Client) StopApp added in v0.10.0

func (c *Client) StopApp(ctx context.Context, ws string, app string) error

func (*Client) StopDatabase added in v0.10.0

func (c *Client) StopDatabase(ctx context.Context, ws string, id uint) error

func (*Client) TrafficSummary added in v0.17.0

func (c *Client) TrafficSummary(ctx context.Context, ws string, appID uint, rng string) (*TrafficSummary, error)

TrafficSummary returns HTTP traffic totals for one app over rng (15m, 1h, 24h, 7d…; empty means the server default of 24h).

func (*Client) TriggerPipeline added in v0.11.0

func (c *Client) TriggerPipeline(ctx context.Context, ws, pipeline string, req TriggerPipelineRequest) (*PipelineRun, error)

TriggerPipeline starts a manual run. The pipeline is addressed by numeric id or uid.

func (*Client) UnlinkDatabaseInstance added in v0.18.0

func (c *Client) UnlinkDatabaseInstance(ctx context.Context, ws string, app string, instID uint) error

func (*Client) UpdateConfig added in v0.10.0

func (c *Client) UpdateConfig(ctx context.Context, ws string, id uint, req UpdateConfigRequest) (*Config, error)

func (*Client) UpdateSecret added in v0.10.0

func (c *Client) UpdateSecret(ctx context.Context, ws string, id uint, req UpdateSecretRequest) (*Secret, error)

func (*Client) UpgradeDatabase added in v0.10.0

func (c *Client) UpgradeDatabase(ctx context.Context, ws string, id uint, req UpgradeDatabaseRequest) (*DatabaseInstance, error)

func (*Client) UploadVolumeFile added in v0.12.0

func (c *Client) UploadVolumeFile(ctx context.Context, ws string, id uint, subdir, name string, content io.Reader) (string, error)

UploadVolumeFile lands content in a volume as subdir/name (subdir may be empty) and returns the path it was written to. It overwrites an existing file.

func (*Client) VerifyVolumeBackup added in v0.15.0

func (c *Client) VerifyVolumeBackup(ctx context.Context, ws string, id, backupID uint) (*VerifyResult, error)

VerifyVolumeBackup re-checks a completed backup against the bucket: present, the size it was stored at, and for a sealed recovery point, still openable with the workspace passphrase.

func (*Client) Volume added in v0.12.0

func (c *Client) Volume(ctx context.Context, ws string, id uint) (*VolumeDetail, error)

Volume returns one volume with its live Docker state and the apps mounting it. The id must be numeric: unlike the file routes, this endpoint does not accept a name or a UID — resolve with ResolveVolumeID first.

func (*Client) VolumeBackupConfigured added in v0.12.0

func (c *Client) VolumeBackupConfigured(ctx context.Context, ws string, id uint) (bool, error)

VolumeBackupConfigured reports whether the workspace has an S3 target, which volume backups require.

func (*Client) VolumeBackupLogs added in v0.12.0

func (c *Client) VolumeBackupLogs(ctx context.Context, ws string, id, backupID uint) ([]byte, error)

VolumeBackupLogs downloads a run's full log, which the panel serves as a file rather than in the envelope.

func (*Client) VolumeBackups added in v0.12.0

func (c *Client) VolumeBackups(ctx context.Context, ws string, id uint) ([]VolumeBackup, error)

VolumeBackups lists a volume's backup history, newest first as the panel returns it.

func (*Client) VolumeFiles added in v0.12.0

func (c *Client) VolumeFiles(ctx context.Context, ws string, id uint) ([]VolumeFile, error)

VolumeFiles lists a volume's contents recursively, relative to its root. The panel caps the listing at 5000 entries.

func (*Client) Volumes added in v0.12.0

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

Volumes lists a workspace's managed volumes. The endpoint is not paginated.

func (*Client) WaitForDeploy

func (c *Client) WaitForDeploy(ctx context.Context, ws string, app string, depID uint, onUpdate func(status string)) (*Deployment, error)

WaitForDeploy polls a deployment until it settles (terminal, or a canary awaiting promotion) or the context is cancelled/times out, calling onUpdate (if non-nil) on each status change. It returns the final deployment.

func (*Client) WaitForMigration added in v0.16.0

func (c *Client) WaitForMigration(ctx context.Context, ws string, id uint, onPhase func(*Migration)) (*Migration, error)

WaitForMigration polls until the migration settles, reporting each phase change.

func (*Client) WaitForPipelineRun added in v0.17.0

func (c *Client) WaitForPipelineRun(ctx context.Context, ws string, runID uint, onUpdate func(status string)) (*PipelineRun, error)

WaitForPipelineRun polls a run until it settles, reporting each status change.

func (*Client) WaitForVolumeBackup added in v0.12.0

func (c *Client) WaitForVolumeBackup(ctx context.Context, ws string, id, backupID uint, onUpdate func(status string)) (*VolumeBackup, error)

WaitForVolumeBackup polls until the run settles, reporting each status change.

func (*Client) Workspace added in v0.17.0

func (c *Client) Workspace(ctx context.Context, ref string) (*Workspace, error)

Workspace fetches one workspace by name, UID or id.

func (*Client) WorkspaceEvents added in v0.17.0

func (c *Client) WorkspaceEvents(ctx context.Context, ws string, limit int) ([]Event, error)

WorkspaceEvents returns the newest events across the workspace. Pages are zero-based on the server.

func (*Client) WorkspaceOverview added in v0.17.0

func (c *Client) WorkspaceOverview(ctx context.Context, ws string) (*WorkspaceOverview, error)

WorkspaceOverview returns app health and resource counts for a workspace.

func (*Client) WorkspaceStorage added in v0.12.0

func (c *Client) WorkspaceStorage(ctx context.Context, ws string) (*WorkspaceStorage, error)

WorkspaceStorage returns the workspace's declared-vs-measured storage totals.

func (*Client) WorkspaceUsage added in v0.17.0

func (c *Client) WorkspaceUsage(ctx context.Context, ws string) (map[string]any, error)

WorkspaceUsage returns resource usage against the plan's limits. It is passed through as-is: the shape grows with every new plan limit.

func (*Client) Workspaces

func (c *Client) Workspaces(ctx context.Context) ([]Workspace, error)

type Config added in v0.10.0

type Config struct {
	ID          uint           `json:"id"`
	UID         string         `json:"uid"`
	Name        string         `json:"name"`
	DisplayName string         `json:"display_name"`
	Description string         `json:"description"`
	Digest      string         `json:"digest"`
	Mode        string         `json:"mode"`
	Sensitive   bool           `json:"sensitive"`
	Delimiters  []string       `json:"delimiters,omitempty"`
	Version     int            `json:"version"`
	Managed     bool           `json:"managed"`
	Keys        []string       `json:"keys"`
	Sizes       map[string]int `json:"sizes"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
}

Config is a workspace configuration file set. Content never comes back on a list or get — only keys, their sizes and the digest.

type ConfigReveal added in v0.10.0

type ConfigReveal struct {
	Data map[string]string `json:"data"`
}

ConfigReveal is the decrypted file set (admin only, audited).

type ConnectionInfo added in v0.10.0

type ConnectionInfo struct {
	Host     string `json:"host"`
	Port     int    `json:"port"`
	Username string `json:"username"`
	Password string `json:"password"`
	Database string `json:"database"`
	URI      string `json:"uri"`
}

ConnectionInfo is a revealed database connection (admin credentials / DSN).

type CreateAppRequest added in v0.10.0

type CreateAppRequest struct {
	DisplayName string   `json:"display_name"`
	Name        string   `json:"name,omitempty"`
	ServerID    uint     `json:"server_id,omitempty"`
	SourceType  string   `json:"source_type,omitempty"`
	Image       string   `json:"image,omitempty"`
	Tag         string   `json:"tag,omitempty"`
	GitRepo     string   `json:"git_repo,omitempty"`
	GitRef      string   `json:"git_ref,omitempty"`
	BuildMethod string   `json:"build_method,omitempty"`
	Port        int      `json:"port,omitempty"`
	Command     []string `json:"command,omitempty"`
}

CreateAppRequest is the body of POST .../apps (only the common fields the CLI exposes). SourceType is "image" or "git"; the CLI infers it from the flags. DisplayName is the required free-text label; Name pins the handle (the server otherwise derives it from DisplayName).

type CreateConfigRequest added in v0.10.0

type CreateConfigRequest struct {
	Name        string            `json:"name"`
	DisplayName string            `json:"display_name,omitempty"`
	Description string            `json:"description,omitempty"`
	Data        map[string]string `json:"data"`
	Mode        string            `json:"mode,omitempty"`
	Sensitive   bool              `json:"sensitive,omitempty"`
	Delimiters  []string          `json:"delimiters,omitempty"`
}

type CreateDatabaseRequest added in v0.10.0

type CreateDatabaseRequest struct {
	Name     string `json:"name"`
	Engine   string `json:"engine"`
	Version  string `json:"version,omitempty"`
	ServerID uint   `json:"server_id,omitempty"`
	SizeMB   int    `json:"size_mb,omitempty"`
}

CreateDatabaseRequest is the body of POST .../databases.

type CreateLogicalDatabaseRequest added in v0.10.0

type CreateLogicalDatabaseRequest struct {
	Name          string `json:"name"`
	ApplicationID *uint  `json:"application_id"`
}

CreateLogicalDatabaseRequest is the body of POST .../databases/{id}/databases.

type CreateLogicalDatabaseResult added in v0.10.0

type CreateLogicalDatabaseResult struct {
	Database    LogicalDatabase `json:"database"`
	EnvInjected bool            `json:"env_injected"`
}

CreateLogicalDatabaseResult is the create-logical-database response.

type CreateSecretRequest added in v0.10.0

type CreateSecretRequest struct {
	Name        string `json:"name"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
}

CreateSecretRequest is the body of POST .../secrets.

type CreateVolumeRequest added in v0.12.0

type CreateVolumeRequest struct {
	Name     string `json:"name"`
	ServerID uint   `json:"server_id,omitempty"`
	SizeMB   int    `json:"size_mb,omitempty"`
	// Driver is local (default) | nfs | cifs | host. DriverOpts are the backend's
	// mount options — NFS/CIFS need device (and usually o), host needs path. They
	// are encrypted at rest and never returned.
	Driver     string            `json:"driver,omitempty"`
	DriverOpts map[string]string `json:"driver_opts,omitempty"`
}

CreateVolumeRequest is the body of POST .../volumes. A volume is immutable once created — there is no update endpoint.

type DatabaseInstance added in v0.10.0

type DatabaseInstance struct {
	ID          uint      `json:"id"`
	Name        string    `json:"name"`
	DisplayName string    `json:"display_name"`
	Engine      string    `json:"engine"`
	Version     string    `json:"version"`
	Status      string    `json:"status"`
	ServerID    uint      `json:"server_id"`
	ServerName  string    `json:"server_name,omitempty"`
	Host        string    `json:"host"`
	Port        int       `json:"port"`
	AdminUser   string    `json:"admin_user"`
	SizeBytes   int64     `json:"size_bytes,omitempty"`
	NetworkName string    `json:"network_name,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
}

DatabaseInstance is a managed database server (only the fields the CLI shows). Name is the unique handle; DisplayName is the free-text label.

type DeployRequest

type DeployRequest struct {
	Tag        string `json:"tag,omitempty"`
	Strategy   string `json:"strategy,omitempty"`
	RegistryID *uint  `json:"registry_id,omitempty"`
	// NoCache rebuilds every layer for this deploy only (git-source apps).
	NoCache bool `json:"no_cache,omitempty"`
}

DeployRequest is the body of POST .../deploy. image is not part of the deploy contract (the app owns its image); only a tag/registry/strategy override.

type DeployResult added in v0.17.0

type DeployResult struct {
	Kind       string       `json:"kind"` // deployment | pipeline_run
	Deployment *Deployment  `json:"deployment,omitempty"`
	Run        *PipelineRun `json:"run,omitempty"`
	// WaitTimedOut is set when the server was asked to wait and gave up first.
	WaitTimedOut bool `json:"wait_timed_out,omitempty"`
}

DeployResult is what deploy and rollback answer. An app whose repository owns a pipeline deploys by running it, so exactly one of Deployment and Run is set.

type Deployment

type Deployment struct {
	ID uint `json:"id"`
	// Number is the per-application deployment number (1, 2, 3…) users address
	// deployments by; ID is the durable platform-wide key used in API paths.
	Number        int        `json:"number"`
	ApplicationID uint       `json:"application_id"`
	Status        string     `json:"status"`
	Image         string     `json:"image"`
	Trigger       string     `json:"trigger"`
	Strategy      string     `json:"strategy"`
	Error         string     `json:"error"`
	StartedAt     *time.Time `json:"started_at"`
	FinishedAt    *time.Time `json:"finished_at"`
	CreatedAt     time.Time  `json:"created_at"`
	// Current marks the deployment whose release is live right now.
	Current bool `json:"current"`
}

Deployment is the deploy/rollback response and status object.

type EngineDefault added in v0.10.0

type EngineDefault struct {
	Engine  string `json:"engine"`
	Image   string `json:"image"`
	Version string `json:"version"`
}

EngineDefault is one entry of GET /database-engines.

type EnvVar added in v0.10.0

type EnvVar struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	IsSecret bool   `json:"is_secret"`
}

EnvVar is one of an application's environment variables. The server masks the value of a secret var, so Value is never the plaintext for those.

type Event added in v0.17.0

type Event struct {
	ID            uint              `json:"id"`
	SubjectType   string            `json:"subject_type,omitempty"`
	ApplicationID uint              `json:"application_id,omitempty"`
	DatabaseID    uint              `json:"database_id,omitempty"`
	Type          string            `json:"type"`
	Severity      string            `json:"severity"`
	Message       string            `json:"message"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	AppName       string            `json:"app_name,omitempty"`
	DatabaseName  string            `json:"database_name,omitempty"`
	CreatedAt     time.Time         `json:"created_at"`
}

Event is one timeline event. AppName is only filled on the workspace-wide feed.

type ImportEnvRequest

type ImportEnvRequest struct {
	Content  string `json:"content"`
	IsSecret bool   `json:"is_secret"`
}

ImportEnvRequest is the body of POST .../env/import.

type LinkDatabaseRequest added in v0.18.0

type LinkDatabaseRequest struct {
	EnvPrefix string            `json:"env_prefix,omitempty"`
	EnvMap    map[string]string `json:"env_map,omitempty"`
}

LinkDatabaseRequest sets how a linked database's connection lands in the app env. EnvMap renames a field's var (url, database_url, host, port, name, user, password); an empty name skips it.

type LinkDatabaseResult added in v0.18.0

type LinkDatabaseResult struct {
	EnvInjected bool     `json:"env_injected"`
	EnvVars     []string `json:"env_vars"`
}

LinkDatabaseResult reports the vars a link injected.

type LogicalDatabase added in v0.10.0

type LogicalDatabase struct {
	ID            uint              `json:"id"`
	InstanceID    uint              `json:"instance_id"`
	Name          string            `json:"name"`
	Username      string            `json:"username"`
	Status        string            `json:"status"`
	ApplicationID *uint             `json:"application_id"`
	EnvPrefix     string            `json:"env_prefix,omitempty"`
	EnvMap        map[string]string `json:"env_map,omitempty"`
	EnvVars       []string          `json:"env_vars,omitempty"`
	SizeBytes     int64             `json:"size_bytes,omitempty"`
	CreatedAt     time.Time         `json:"created_at"`
}

LogicalDatabase is a database hosted on an instance (SQL engines).

type LoginToken added in v0.10.0

type LoginToken struct {
	Token     string `json:"token"`
	ServerURL string `json:"server_url"`
	ExpiresAt string `json:"expires_at"`
}

LoginToken is the minted CLI token returned by the login-token claim endpoint (the browser hands off a single-use code; this is what it exchanges to).

type Me

type Me struct {
	ID       uint   `json:"id"`
	Name     string `json:"name"`
	Username string `json:"username"`
	Email    string `json:"email"`
	Role     string `json:"role"`
	Auth     struct {
		Method      string   `json:"method"`       // api_key | jwt
		APIKeyID    *uint    `json:"api_key_id"`   // when method=api_key
		WorkspaceID *uint    `json:"workspace_id"` // set only for workspace-bound keys
		Scopes      []string `json:"scopes"`
	} `json:"auth"`
}

Me is GET /api/v1/me — the authenticated identity and, for an API key, its scopes and bound workspace.

type Migration added in v0.16.0

type Migration struct {
	ID       uint          `json:"id"`
	AppName  string        `json:"app_name"`
	Status   string        `json:"status"`
	Phase    string        `json:"phase"`
	Plan     MigrationPlan `json:"plan"`
	Progress struct {
		Items []struct {
			Kind   string `json:"kind"`
			Name   string `json:"name"`
			Status string `json:"status"`
			Bytes  int64  `json:"bytes"`
			Total  int64  `json:"total"`
		} `json:"items"`
		EstimatedDowntimeSeconds int    `json:"estimated_downtime_seconds"`
		Message                  string `json:"message"`
	} `json:"progress"`
	Report struct {
		Notes []string `json:"notes"`
	} `json:"report"`
	Error         string     `json:"error"`
	FinalizeAfter *time.Time `json:"finalize_after"`
	CreatedAt     time.Time  `json:"created_at"`
}

Migration is one location migration.

type MigrationDBChoice added in v0.16.0

type MigrationDBChoice struct {
	InstanceID       uint   `json:"instance_id"`
	Strategy         string `json:"strategy"`
	TargetInstanceID uint   `json:"target_instance_id,omitempty"`
}

MigrationDBChoice picks a strategy for one instance.

type MigrationDBItem added in v0.16.0

type MigrationDBItem struct {
	InstanceID   uint     `json:"instance_id"`
	InstanceName string   `json:"instance_name"`
	Engine       string   `json:"engine"`
	Version      string   `json:"version"`
	Exclusive    bool     `json:"exclusive"`
	Strategies   []string `json:"strategies"`
	Strategy     string   `json:"strategy"`
}

MigrationDBItem is one database instance in a plan.

type MigrationIssue added in v0.16.0

type MigrationIssue struct {
	Code     string `json:"code"`
	Message  string `json:"message"`
	Resource string `json:"resource,omitempty"`
}

MigrationIssue is a blocker or warning a migration plan raised.

type MigrationPlan added in v0.16.0

type MigrationPlan struct {
	Location      string `json:"location"`
	LocationLabel string `json:"location_label"`
	Volumes       []struct {
		VolumeID     uint   `json:"volume_id"`
		Name         string `json:"name"`
		Action       string `json:"action"`
		UsedBytes    int64  `json:"used_bytes"`
		StorageClass string `json:"storage_class"`
	} `json:"volumes"`
	Databases []MigrationDBItem `json:"databases"`
	Blockers  []MigrationIssue  `json:"blockers"`
	Warnings  []MigrationIssue  `json:"warnings"`
	CopyBytes int64             `json:"copy_bytes"`
}

MigrationPlan is POST /apps/{id}/migrations/plan: what moving an app would do.

type Options added in v0.10.0

type Options struct {
	BaseURL      string
	Token        string
	CAFile       string
	InsecureSkip bool
	Verbose      bool
}

Options configures a client: the server base URL, bearer token, TLS trust (a custom CA bundle path and/or skip-verify), and verbose HTTP logging.

type OverviewApp added in v0.17.0

type OverviewApp struct {
	ID     uint   `json:"id"`
	Name   string `json:"name"`
	Status string `json:"status"`
	Health string `json:"health"` // healthy | unhealthy | unknown
}

OverviewApp is one application's health in the workspace overview.

type Pipeline added in v0.11.0

type Pipeline struct {
	ID          uint      `json:"id"`
	Name        string    `json:"name"`
	DisplayName string    `json:"display_name"`
	Enabled     bool      `json:"enabled"`
	Source      string    `json:"source,omitempty"` // manual | repo
	CreatedAt   time.Time `json:"created_at"`
}

Pipeline is a CI/CD pipeline definition in the workspace.

type PipelineRun added in v0.11.0

type PipelineRun struct {
	ID         uint       `json:"id"`
	PipelineID uint       `json:"pipeline_id"`
	Number     int        `json:"number"`
	Status     string     `json:"status"`
	Trigger    string     `json:"trigger,omitempty"`
	Branch     string     `json:"branch,omitempty"`
	Commit     string     `json:"commit,omitempty"`
	NoCache    bool       `json:"no_cache,omitempty"`
	Error      string     `json:"error,omitempty"`
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
}

PipelineRun is one execution of a pipeline.

type Plan

type Plan struct {
	Changes []Change `json:"changes"`
}

Plan is what a dry-run apply returns.

type Release

type Release struct {
	ID            uint      `json:"id"`
	ApplicationID uint      `json:"application_id"`
	DeploymentID  uint      `json:"deployment_id"`
	Version       int       `json:"version"`
	Image         string    `json:"image"`
	Active        bool      `json:"active"`
	Digest        *string   `json:"digest"`
	CreatedAt     time.Time `json:"created_at"`
}

Release is one immutable release of an app.

type RerunPipelineRequest added in v0.11.0

type RerunPipelineRequest struct {
	NoCache bool `json:"no_cache,omitempty"`
}

RerunPipelineRequest is the body of POST .../pipeline-runs/{id}/rerun.

type ResyncPipelineResult added in v0.10.0

type ResyncPipelineResult struct {
	Pipeline *struct {
		Name       string `json:"name"`
		SourcePath string `json:"source_path"`
		SourceRef  string `json:"source_ref"`
	} `json:"pipeline"`
	Changed bool `json:"changed"`
	Adopted bool `json:"adopted"`
}

ResyncPipelineResult reports the pipeline the app ended up bound to. Changed is false when the repository's document already matched what was stored — a successful no-op, not a failure.

type RollbackRequest

type RollbackRequest struct {
	ReleaseID uint `json:"release_id"`
}

RollbackRequest is the body of POST .../rollback.

type ScopeError added in v0.17.0

type ScopeError struct {
	*APIError
	Scope string
}

ScopeError is a 403 caused by the API key lacking a scope, as opposed to the caller's workspace role.

func (*ScopeError) Error added in v0.17.0

func (e *ScopeError) Error() string

func (*ScopeError) Unwrap added in v0.17.0

func (e *ScopeError) Unwrap() error

type SealingKey added in v0.19.0

type SealingKey struct {
	Version   int    `json:"version"`
	PublicKey string `json:"public_key"`
}

SealingKey is the public key a workspace's secrets are sealed to.

type Secret added in v0.10.0

type Secret struct {
	ID          uint   `json:"id"`
	UID         string `json:"uid"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	Description string `json:"description"`
	// Version bumps on each value rotation.
	Version int `json:"version"`
	// Managed marks a secret owned by a platform resource (e.g. a managed
	// database); rotate it via its owner, not by hand.
	Managed bool `json:"managed"`
	// SealedKeyVersion is set when the value came from a sealed value in a manifest.
	SealedKeyVersion int       `json:"sealed_key_version,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

Secret is one entry of the workspace Vault. Values are write-only over the API and never appear here — reveal them explicitly (admin-only, audited). Name is the unique handle env refs use (${{ secrets.NAME }}); DisplayName is a label.

type SecretReveal added in v0.10.0

type SecretReveal struct {
	Value string `json:"value"`
}

SecretReveal is the payload of GET .../secrets/{id}/reveal.

type SecretUsage added in v0.10.0

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

SecretUsage is one app referencing a secret (GET .../secrets/{id}/usage).

type SetAppSourceRequest added in v0.10.0

type SetAppSourceRequest struct {
	SourceType string `json:"source_type"`

	Image      string `json:"image,omitempty"`
	Tag        string `json:"tag,omitempty"`
	RegistryID *uint  `json:"registry_id,omitempty"`

	GitRepo         string `json:"git_repo,omitempty"`
	GitRef          string `json:"git_ref,omitempty"`
	GitRepositoryID *uint  `json:"git_repository_id,omitempty"`
	BuildMethod     string `json:"build_method,omitempty"`
	Builder         string `json:"builder,omitempty"`
}

SetAppSourceRequest is a whole-source replacement. Only the fields of the chosen source_type are read; the server clears the other source's.

type SetAppSourceResult added in v0.10.0

type SetAppSourceResult struct {
	Application App          `json:"application"`
	Change      SourceChange `json:"change"`
}

type SetEnvRequest

type SetEnvRequest struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	IsSecret bool   `json:"is_secret"`
}

SetEnvRequest is the body of PUT .../env.

type SourceChange added in v0.10.0

type SourceChange struct {
	From string `json:"from"`
	To   string `json:"to"`
	// Switched is false when only the details changed (a new tag, a different branch).
	Switched bool `json:"switched"`
	// PipelineRemoved is true when leaving git dropped a repo-owned pipeline.
	PipelineRemoved bool `json:"pipeline_removed"`
	// RedeployRequired is true when the running container no longer matches the source.
	RedeployRequired bool `json:"redeploy_required"`
}

SourceChange reports what else moved when the source changed. None of it is visible in the app record afterwards, so it is worth surfacing.

type StartMigration added in v0.16.0

type StartMigration struct {
	Location      string              `json:"location"`
	Databases     []MigrationDBChoice `json:"databases,omitempty"`
	CutoverMode   string              `json:"cutover_mode,omitempty"`
	BandwidthKBps int                 `json:"bandwidth_kbps,omitempty"`
}

StartMigration is the body of POST /apps/{id}/migrations.

type TrafficSummary added in v0.17.0

type TrafficSummary struct {
	Totals struct {
		Requests     int64   `json:"requests"`
		ErrorRate    float64 `json:"error_rate"` // 0..1
		AvgLatencyMS float64 `json:"avg_latency_ms"`
		P95LatencyMS float64 `json:"p95_latency_ms"`
		P99LatencyMS float64 `json:"p99_latency_ms"`
	} `json:"totals"`
	Status struct {
		S2xx int64 `json:"s2xx"`
		S3xx int64 `json:"s3xx"`
		S4xx int64 `json:"s4xx"`
		S5xx int64 `json:"s5xx"`
	} `json:"status"`
}

TrafficSummary is the part of GET .../analytics/summary the CLI reads.

type TriggerPipelineRequest added in v0.11.0

type TriggerPipelineRequest struct {
	Branch  string `json:"branch,omitempty"`
	Commit  string `json:"commit,omitempty"`
	NoCache bool   `json:"no_cache,omitempty"`
}

TriggerPipelineRequest is the body of POST .../pipelines/{id}/trigger.

type UpdateConfigRequest added in v0.10.0

type UpdateConfigRequest struct {
	Data        map[string]string `json:"data,omitempty"`
	DisplayName string            `json:"display_name,omitempty"`
	Description string            `json:"description,omitempty"`
	Mode        string            `json:"mode,omitempty"`
	Delimiters  []string          `json:"delimiters,omitempty"`
}

type UpdateSecretRequest added in v0.10.0

type UpdateSecretRequest struct {
	Value       string `json:"value"`
	Description string `json:"description"`
}

UpdateSecretRequest is the body of PUT .../secrets/{id}. A blank Value keeps the stored value (a description-only edit); a new value rotates the secret.

type UpgradeDatabaseRequest added in v0.10.0

type UpgradeDatabaseRequest struct {
	Version  string `json:"version"`
	StopApps bool   `json:"stop_apps,omitempty"`
}

UpgradeDatabaseRequest is the body of POST .../databases/{id}/upgrade.

type VerifyResult added in v0.15.0

type VerifyResult struct {
	Ref        string   `json:"ref"`
	OK         bool     `json:"ok"`
	Checked    int      `json:"checked"`
	Missing    []string `json:"missing,omitempty"`
	Resized    []string `json:"resized,omitempty"`
	EnvelopeOK bool     `json:"envelope_ok"`
	Error      string   `json:"error,omitempty"`
}

VerifyResult is what a backup verification found.

type Volume added in v0.12.0

type Volume struct {
	ID          uint   `json:"id"`
	UID         string `json:"uid"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	// DockerName is the underlying Docker volume, which is not the handle.
	DockerName string `json:"docker_name"`
	// ServerID is the node the volume lives on (0 = the local control-plane node);
	// ServerName is its display name, populated on read.
	ServerID       uint       `json:"server_id"`
	ServerName     string     `json:"server_name,omitempty"`
	Mountpoint     string     `json:"mountpoint,omitempty"`
	SizeBytes      int64      `json:"size_bytes"`
	UsedBytes      int64      `json:"used_bytes"`
	UsedMeasuredAt *time.Time `json:"used_measured_at,omitempty"`
	// Driver is local (node-local) | nfs | cifs (shared) | host (an operator-managed
	// bind). AccessMode follows from it: rwo for local, rwx for everything else.
	Driver     string `json:"driver"`
	AccessMode string `json:"access_mode"`
	HostPath   string `json:"host_path,omitempty"`
	// Imported marks a volume that adopted a pre-existing external Docker volume.
	Imported  bool      `json:"imported"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Volume is a workspace-owned managed volume. Name is the unique handle the CLI and API address it by; DisplayName is the free-text label the UI shows.

SizeBytes is the *declared* capacity asked for at create time (0 = unbounded); UsedBytes is the last *measured* on-disk usage, refreshed by the panel's storage sweep. They are different numbers: a nil UsedMeasuredAt means the volume has never been measured, not that it is empty.

type VolumeBackup added in v0.12.0

type VolumeBackup struct {
	ID          uint `json:"id"`
	WorkspaceID uint `json:"workspace_id"`
	VolumeID    uint `json:"volume_id"`
	ServerID    uint `json:"server_id"`
	// VolumeName is the Docker volume that was archived, not the handle.
	VolumeName string `json:"volume_name"`
	Status     string `json:"status"`  // pending | running | completed | failed
	Trigger    string `json:"trigger"` // manual | scheduled
	S3Bucket   string `json:"s3_bucket,omitempty"`
	S3Path     string `json:"s3_path,omitempty"`
	Filename   string `json:"filename,omitempty"`
	SizeBytes  int64  `json:"size_bytes"`
	// Logs is the tail the record carries; the full log is a separate download.
	Logs       string     `json:"logs,omitempty"`
	Error      string     `json:"error,omitempty"`
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`

	// Ref names a recovery point (Enterprise); empty on a plain archive.
	Ref          string     `json:"ref,omitempty"`
	Consistency  string     `json:"consistency,omitempty"` // hot
	Encrypted    bool       `json:"encrypted"`
	Pinned       bool       `json:"pinned"`
	VerifiedAt   *time.Time `json:"verified_at,omitempty"`
	VerifyStatus string     `json:"verify_status,omitempty"` // ok | failed; empty = never
	VerifyError  string     `json:"verify_error,omitempty"`
}

VolumeBackup is one backup run of a volume's contents to S3.

type VolumeBackupStatus added in v0.12.0

type VolumeBackupStatus struct {
	S3Configured bool `json:"s3_configured"`
	Entitled     bool `json:"entitled"`
	Mutable      bool `json:"mutable"`
	Sealing      bool `json:"sealing"`
}

VolumeBackupStatus is GET .../volumes/{id}/backups/status.

type VolumeDetail added in v0.12.0

type VolumeDetail struct {
	// Inlined for -o yaml: encoding/json flattens an anonymous struct on its own,
	// gopkg.in/yaml.v3 nests it under "volume" unless told otherwise.
	Volume `yaml:",inline"`
	Exists bool          `json:"exists"`
	InUse  bool          `json:"in_use"`
	UsedBy []VolumeUsage `json:"used_by"`
}

VolumeDetail is GET .../volumes/{id}: the stored volume plus live Docker state (Exists) and the applications that mount it.

type VolumeFile added in v0.12.0

type VolumeFile struct {
	Path    string `json:"path"`
	Size    int64  `json:"size"`
	ModTime int64  `json:"mod_time"`
	IsDir   bool   `json:"is_dir"`
}

VolumeFile is one entry of a volume's recursive file listing. Path is relative to the volume root; ModTime is unix seconds; directories report size 0.

type VolumeUploadResult added in v0.12.0

type VolumeUploadResult struct {
	Path string `json:"path"`
}

VolumeUploadResult is the payload of POST .../volumes/{id}/files: the path the file landed on, relative to the volume root.

type VolumeUsage added in v0.12.0

type VolumeUsage struct {
	AppID          uint   `json:"app_id"`
	AppName        string `json:"app_name"`
	AppDisplayName string `json:"app_display_name"`
	Path           string `json:"path"`
}

VolumeUsage is one application mounting a volume, with its mount path.

type Workspace

type Workspace struct {
	ID          uint   `json:"id"`
	UID         string `json:"uid"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	Role        string `json:"role"`
}

Workspace is one entry of GET /api/v1/workspaces. Name is the unique handle; DisplayName is the free-text label.

type WorkspaceOverview added in v0.17.0

type WorkspaceOverview struct {
	Apps         []OverviewApp `json:"apps"`
	TotalApps    int           `json:"total_apps"`
	Running      int           `json:"running"`
	Failed       int           `json:"failed"`
	Databases    int           `json:"databases"`
	Stacks       int           `json:"stacks"`
	RecentEvents []Event       `json:"recent_events"`
}

WorkspaceOverview is GET .../overview.

type WorkspaceStorage added in v0.12.0

type WorkspaceStorage struct {
	DeclaredBytes int64      `json:"declared_bytes"`
	UsedBytes     int64      `json:"used_bytes"`
	LimitMB       int        `json:"limit_mb"`
	MeasuredAt    *time.Time `json:"measured_at,omitempty"`
	VolumeCount   int64      `json:"volume_count"`
}

WorkspaceStorage is GET .../storage: the workspace's declared-vs-measured storage totals. LimitMB is the plan's cap, -1 when unlimited.

Jump to

Keyboard shortcuts

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