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
- Variables
- func IsBackupFailure(status string) bool
- func IsBackupTerminal(status string) bool
- func IsFailure(status string) bool
- func IsRunTerminal(status string) bool
- func IsSettled(status string) bool
- func IsTerminal(status string) bool
- func MigrationSettled(status string) bool
- type APIError
- type Alert
- type App
- type AppDatabase
- type ApplyFailure
- type ApplyRequest
- type ApplyResult
- type AttachVolumeRequest
- type Backup
- type Change
- type Client
- func (c *Client) AckAlert(ctx context.Context, ws string, id uint) (*Alert, error)
- func (c *Client) Alerts(ctx context.Context, ws string, activeOnly bool) ([]Alert, error)
- func (c *Client) App(ctx context.Context, ws string, appID uint) (*App, error)
- func (c *Client) AppDatabases(ctx context.Context, ws string, appID uint) ([]AppDatabase, error)
- func (c *Client) AppEvents(ctx context.Context, ws string, appID uint, limit int) ([]Event, error)
- func (c *Client) AppMigrations(ctx context.Context, ws string, appID uint) ([]Migration, error)
- func (c *Client) Apply(ctx context.Context, ws string, manifests string, prune bool) (*ApplyResult, error)
- func (c *Client) Apps(ctx context.Context, ws string) ([]App, error)
- func (c *Client) AttachDatabase(ctx context.Context, ws string, appID, dbID uint, req LinkDatabaseRequest) (*LinkDatabaseResult, error)
- func (c *Client) AttachVolume(ctx context.Context, ws string, appID uint, req AttachVolumeRequest) error
- func (c *Client) Backups(ctx context.Context, ws string, id, dbID uint) ([]Backup, error)
- func (c *Client) ClaimLoginToken(ctx context.Context, code string) (*LoginToken, error)
- func (c *Client) Config(ctx context.Context, ws string, id uint) (*Config, error)
- func (c *Client) ConfigData(ctx context.Context, ws string, id uint) (map[string]string, error)
- func (c *Client) ConfigUsage(ctx context.Context, ws string, id uint) ([]SecretUsage, error)
- func (c *Client) Configs(ctx context.Context, ws string) ([]Config, error)
- func (c *Client) CreateApp(ctx context.Context, ws string, req CreateAppRequest) (*App, error)
- func (c *Client) CreateConfig(ctx context.Context, ws string, req CreateConfigRequest) (*Config, error)
- func (c *Client) CreateDatabase(ctx context.Context, ws string, req CreateDatabaseRequest) (*DatabaseInstance, error)
- func (c *Client) CreateLogicalDatabase(ctx context.Context, ws string, id uint, req CreateLogicalDatabaseRequest) (*CreateLogicalDatabaseResult, error)
- func (c *Client) CreateSecret(ctx context.Context, ws string, req CreateSecretRequest) (*Secret, error)
- func (c *Client) CreateVolume(ctx context.Context, ws string, req CreateVolumeRequest) (*Volume, error)
- func (c *Client) Database(ctx context.Context, ws string, id uint) (*DatabaseInstance, error)
- func (c *Client) DatabaseCredentials(ctx context.Context, ws string, id uint) (*ConnectionInfo, error)
- func (c *Client) DatabaseEngines(ctx context.Context, ws string) ([]EngineDefault, error)
- func (c *Client) Databases(ctx context.Context, ws string) ([]DatabaseInstance, error)
- func (c *Client) Delete(ctx context.Context, ws string, manifests string) (*ApplyResult, error)
- func (c *Client) DeleteApp(ctx context.Context, ws string, appID uint) error
- func (c *Client) DeleteConfig(ctx context.Context, ws string, id uint) error
- func (c *Client) DeleteDatabaseInstance(ctx context.Context, ws string, id uint) error
- func (c *Client) DeleteLogicalDatabase(ctx context.Context, ws string, id, dbID uint) error
- func (c *Client) DeleteSecret(ctx context.Context, ws string, id uint) error
- func (c *Client) DeleteVolume(ctx context.Context, ws string, id uint) error
- func (c *Client) DeleteVolumeBackup(ctx context.Context, ws string, id, backupID uint) error
- func (c *Client) DeleteVolumeFile(ctx context.Context, ws string, id uint, path string) error
- func (c *Client) Deploy(ctx context.Context, ws string, appID uint, req DeployRequest, ...) (*DeployResult, error)
- func (c *Client) Deployment(ctx context.Context, ws string, appID, depID uint) (*Deployment, error)
- func (c *Client) DeploymentByNumber(ctx context.Context, ws string, appID uint, number int) (*Deployment, error)
- func (c *Client) Deployments(ctx context.Context, ws string, appID uint) ([]Deployment, error)
- func (c *Client) DetachDatabase(ctx context.Context, ws string, appID, dbID uint) error
- func (c *Client) DetachVolume(ctx context.Context, ws string, appID, volumeID uint) error
- func (c *Client) DownloadVolumeFile(ctx context.Context, ws string, id uint, path string, dst io.Writer) (int64, error)
- func (c *Client) EnvVars(ctx context.Context, ws string, appID uint) ([]EnvVar, error)
- func (c *Client) FindConfigByName(ctx context.Context, ws, name string) (*Config, error)
- func (c *Client) FindSecretByName(ctx context.Context, ws, name string) (*Secret, error)
- func (c *Client) FindVolumeBackup(ctx context.Context, ws string, id, backupID uint) (*VolumeBackup, error)
- func (c *Client) FindVolumeByName(ctx context.Context, ws, name string) (*Volume, error)
- func (c *Client) ImportEnv(ctx context.Context, ws string, appID uint, req ImportEnvRequest) error
- func (c *Client) InvalidateBuildCache(ctx context.Context, ws string, appID uint) error
- func (c *Client) LinkDatabaseInstance(ctx context.Context, ws string, appID, instID uint, req LinkDatabaseRequest) (*LinkDatabaseResult, error)
- func (c *Client) LogicalDatabaseConnection(ctx context.Context, ws string, id, dbID uint) (*ConnectionInfo, error)
- func (c *Client) LogicalDatabases(ctx context.Context, ws string, id uint) ([]LogicalDatabase, error)
- func (c *Client) Me(ctx context.Context) (*Me, error)
- func (c *Client) Migration(ctx context.Context, ws string, id uint) (*Migration, error)
- func (c *Client) MigrationAction(ctx context.Context, ws string, id uint, action string) (*Migration, error)
- func (c *Client) Migrations(ctx context.Context, ws string) ([]Migration, error)
- func (c *Client) PinVolumeBackup(ctx context.Context, ws string, id, backupID uint, pinned bool) (*VolumeBackup, error)
- func (c *Client) PipelineRun(ctx context.Context, ws string, runID uint) (*PipelineRun, error)
- func (c *Client) Pipelines(ctx context.Context, ws string) ([]Pipeline, error)
- func (c *Client) PlanApply(ctx context.Context, ws string, manifests string, prune bool) (*Plan, error)
- func (c *Client) PlanDelete(ctx context.Context, ws string, manifests string) (*Plan, error)
- func (c *Client) PlanMigration(ctx context.Context, ws string, appID uint, body StartMigration) (*MigrationPlan, error)
- func (c *Client) ReleaseByVersion(ctx context.Context, ws string, appID uint, version int) (*Release, error)
- func (c *Client) Releases(ctx context.Context, ws string, appID uint) ([]Release, error)
- func (c *Client) RerunPipelineRun(ctx context.Context, ws string, runID uint, req RerunPipelineRequest) (*PipelineRun, error)
- func (c *Client) ResolveAlert(ctx context.Context, ws string, id uint) (*Alert, error)
- func (c *Client) ResolveAppID(ctx context.Context, ws string, ref string) (uint, error)
- func (c *Client) ResolveConfigID(ctx context.Context, ws, ref string) (uint, error)
- func (c *Client) ResolveDatabaseID(ctx context.Context, ws, ref string) (uint, error)
- func (c *Client) ResolveLogicalDatabaseID(ctx context.Context, ws string, id uint, ref string) (uint, error)
- func (c *Client) ResolveSecretID(ctx context.Context, ws, ref string) (uint, error)
- func (c *Client) ResolveVolumeID(ctx context.Context, ws, ref string) (uint, error)
- func (c *Client) ResolveWorkspaceName(ctx context.Context, ref, fallback string) (string, error)
- func (c *Client) RestartApp(ctx context.Context, ws string, appID uint) error
- func (c *Client) RestartDatabase(ctx context.Context, ws string, id uint) error
- func (c *Client) RestoreVolumeBackup(ctx context.Context, ws string, id, backupID uint) error
- func (c *Client) ResyncAppPipeline(ctx context.Context, ws string, appID uint) (*ResyncPipelineResult, error)
- func (c *Client) RevealSecret(ctx context.Context, ws string, id uint) (string, error)
- func (c *Client) Rollback(ctx context.Context, ws string, appID uint, req RollbackRequest, ...) (*DeployResult, error)
- func (c *Client) RunBackup(ctx context.Context, ws string, id, dbID uint, comment string) (*Backup, error)
- func (c *Client) RunVolumeBackup(ctx context.Context, ws string, id uint) (*VolumeBackup, error)
- func (c *Client) SecretUsage(ctx context.Context, ws string, id uint) ([]SecretUsage, error)
- func (c *Client) Secrets(ctx context.Context, ws string) ([]Secret, error)
- func (c *Client) SetAppSource(ctx context.Context, ws string, appID uint, req SetAppSourceRequest) (*SetAppSourceResult, error)
- func (c *Client) SetEnv(ctx context.Context, ws string, appID uint, req SetEnvRequest) error
- func (c *Client) StartApp(ctx context.Context, ws string, appID uint) error
- func (c *Client) StartDatabase(ctx context.Context, ws string, id uint) error
- func (c *Client) StartMigration(ctx context.Context, ws string, appID uint, body StartMigration) (*Migration, error)
- func (c *Client) StopApp(ctx context.Context, ws string, appID uint) error
- func (c *Client) StopDatabase(ctx context.Context, ws string, id uint) error
- func (c *Client) TrafficSummary(ctx context.Context, ws string, appID uint, rng string) (*TrafficSummary, error)
- func (c *Client) TriggerPipeline(ctx context.Context, ws, pipeline string, req TriggerPipelineRequest) (*PipelineRun, error)
- func (c *Client) UnlinkDatabaseInstance(ctx context.Context, ws string, appID, instID uint) error
- func (c *Client) UpdateConfig(ctx context.Context, ws string, id uint, req UpdateConfigRequest) (*Config, error)
- func (c *Client) UpdateSecret(ctx context.Context, ws string, id uint, req UpdateSecretRequest) (*Secret, error)
- func (c *Client) UpgradeDatabase(ctx context.Context, ws string, id uint, req UpgradeDatabaseRequest) (*DatabaseInstance, error)
- func (c *Client) UploadVolumeFile(ctx context.Context, ws string, id uint, subdir, name string, ...) (string, error)
- func (c *Client) VerifyVolumeBackup(ctx context.Context, ws string, id, backupID uint) (*VerifyResult, error)
- func (c *Client) Volume(ctx context.Context, ws string, id uint) (*VolumeDetail, error)
- func (c *Client) VolumeBackupConfigured(ctx context.Context, ws string, id uint) (bool, error)
- func (c *Client) VolumeBackupLogs(ctx context.Context, ws string, id, backupID uint) ([]byte, error)
- func (c *Client) VolumeBackups(ctx context.Context, ws string, id uint) ([]VolumeBackup, error)
- func (c *Client) VolumeFiles(ctx context.Context, ws string, id uint) ([]VolumeFile, error)
- func (c *Client) Volumes(ctx context.Context, ws string) ([]Volume, error)
- func (c *Client) WaitForDeploy(ctx context.Context, ws string, appID, depID uint, ...) (*Deployment, error)
- func (c *Client) WaitForMigration(ctx context.Context, ws string, id uint, onPhase func(*Migration)) (*Migration, error)
- func (c *Client) WaitForPipelineRun(ctx context.Context, ws string, runID uint, onUpdate func(status string)) (*PipelineRun, error)
- func (c *Client) WaitForVolumeBackup(ctx context.Context, ws string, id, backupID uint, ...) (*VolumeBackup, error)
- func (c *Client) Workspace(ctx context.Context, ref string) (*Workspace, error)
- func (c *Client) WorkspaceEvents(ctx context.Context, ws string, limit int) ([]Event, error)
- func (c *Client) WorkspaceOverview(ctx context.Context, ws string) (*WorkspaceOverview, error)
- func (c *Client) WorkspaceStorage(ctx context.Context, ws string) (*WorkspaceStorage, error)
- func (c *Client) WorkspaceUsage(ctx context.Context, ws string) (map[string]any, error)
- func (c *Client) Workspaces(ctx context.Context) ([]Workspace, error)
- type Config
- type ConfigReveal
- type ConnectionInfo
- type CreateAppRequest
- type CreateConfigRequest
- type CreateDatabaseRequest
- type CreateLogicalDatabaseRequest
- type CreateLogicalDatabaseResult
- type CreateSecretRequest
- type CreateVolumeRequest
- type DatabaseInstance
- type DeployRequest
- type DeployResult
- type Deployment
- type EngineDefault
- type EnvVar
- type Event
- type ImportEnvRequest
- type LinkDatabaseRequest
- type LinkDatabaseResult
- type LogicalDatabase
- type LoginToken
- type Me
- type Migration
- type MigrationDBChoice
- type MigrationDBItem
- type MigrationIssue
- type MigrationPlan
- type Options
- type OverviewApp
- type Pipeline
- type PipelineRun
- type Plan
- type Release
- type RerunPipelineRequest
- type ResyncPipelineResult
- type RollbackRequest
- type ScopeError
- type Secret
- type SecretReveal
- type SecretUsage
- type SetAppSourceRequest
- type SetAppSourceResult
- type SetEnvRequest
- type SourceChange
- type StartMigration
- type TrafficSummary
- type TriggerPipelineRequest
- type UpdateConfigRequest
- type UpdateSecretRequest
- type UpgradeDatabaseRequest
- type VerifyResult
- type Volume
- type VolumeBackup
- type VolumeBackupStatus
- type VolumeDetail
- type VolumeFile
- type VolumeUploadResult
- type VolumeUsage
- type Workspace
- type WorkspaceOverview
- type WorkspaceStorage
Constants ¶
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.
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.
const BackupRunTimeout = 30 * time.Minute
BackupRunTimeout bounds a manual database backup, which the server runs inline in the request.
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.
const MaxEventPage = 100
MaxEventPage is the largest page the workspace events feed serves.
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.
const MaxServerWait = 900 * time.Second
MaxServerWait is the longest ?wait= the server accepts on deploy and rollback.
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.
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 ¶
var Version = "dev"
Version is stamped at build time (see .goreleaser.yaml); used in User-Agent.
Functions ¶
func IsBackupFailure ¶ added in v0.12.0
IsBackupFailure reports a terminal backup failure.
func IsBackupTerminal ¶ added in v0.12.0
IsBackupTerminal reports whether a backup run has settled.
func IsRunTerminal ¶ added in v0.17.0
IsRunTerminal reports whether a pipeline run has settled.
func IsSettled ¶ added in v0.17.0
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 ¶
IsTerminal reports whether a deployment status will not change further.
func MigrationSettled ¶ added in v0.16.0
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.
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"`
}
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
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 ¶
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
AckAlert acknowledges an alert: it stays active but stops re-notifying.
func (*Client) Alerts ¶ added in v0.17.0
Alerts lists a workspace's alerts; activeOnly keeps the firing and acknowledged ones.
func (*Client) AppDatabases ¶ added in v0.18.0
AppDatabases lists the databases linked to an app.
func (*Client) AppMigrations ¶ added in v0.16.0
func (*Client) Apply ¶
func (c *Client) Apply(ctx context.Context, ws string, manifests string, prune bool) (*ApplyResult, error)
Apply converges the workspace to the manifest bundle.
func (*Client) AttachDatabase ¶ added in v0.18.0
func (c *Client) AttachDatabase(ctx context.Context, ws string, appID, 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, appID uint, 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) ClaimLoginToken ¶ added in v0.10.0
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) ConfigData ¶ added in v0.10.0
ConfigData returns a config's decrypted files (admin only, audited).
func (*Client) ConfigUsage ¶ added in v0.10.0
func (*Client) Configs ¶ added in v0.10.0
Configs lists a workspace's configs (keys and digests, never content).
func (*Client) CreateConfig ¶ added in v0.10.0
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 (*Client) CreateVolume ¶ added in v0.12.0
func (*Client) DatabaseCredentials ¶ added in v0.10.0
func (*Client) DatabaseEngines ¶ added in v0.10.0
func (*Client) DeleteConfig ¶ added in v0.10.0
func (*Client) DeleteDatabaseInstance ¶ added in v0.10.0
func (*Client) DeleteLogicalDatabase ¶ added in v0.10.0
func (*Client) DeleteSecret ¶ added in v0.10.0
func (*Client) DeleteVolume ¶ added in v0.12.0
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 (*Client) DeleteVolumeFile ¶ added in v0.12.0
DeleteVolumeFile removes a file, or a directory and everything under it.
func (*Client) Deploy ¶
func (c *Client) Deploy(ctx context.Context, ws string, appID uint, 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 ¶
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, appID uint, 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 (*Client) DetachDatabase ¶ added in v0.18.0
func (*Client) DetachVolume ¶ added in v0.12.0
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
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
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
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
FindVolumeByName returns the named volume, or nil when none exists.
func (*Client) InvalidateBuildCache ¶ added in v0.11.0
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, appID, instID uint, req LinkDatabaseRequest) (*LinkDatabaseResult, error)
LinkDatabaseInstance links a whole instance (Redis) to an app.
func (*Client) LogicalDatabaseConnection ¶ added in v0.10.0
func (*Client) LogicalDatabases ¶ added in v0.10.0
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 (*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
PipelineRun returns one pipeline run.
func (*Client) PlanApply ¶
func (c *Client) PlanApply(ctx context.Context, ws string, manifests string, prune bool) (*Plan, error)
PlanApply previews converging the workspace to the manifest bundle (dry-run).
func (*Client) PlanDelete ¶
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, appID uint, body StartMigration) (*MigrationPlan, error)
func (*Client) ReleaseByVersion ¶ added in v0.10.0
func (c *Client) ReleaseByVersion(ctx context.Context, ws string, appID uint, 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) 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
ResolveAlert closes an alert.
func (*Client) ResolveAppID ¶
ResolveAppID turns an app handle (or numeric id) into the numeric id paths use.
func (*Client) ResolveConfigID ¶ added in v0.10.0
ResolveConfigID turns a config name (or numeric id) into its numeric id.
func (*Client) ResolveDatabaseID ¶ added in v0.10.0
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
ResolveSecretID turns a secret name (or numeric id) into its numeric id.
func (*Client) ResolveVolumeID ¶ added in v0.12.0
ResolveVolumeID turns a volume name (or numeric id) into its numeric id.
func (*Client) ResolveWorkspaceName ¶ added in v0.10.0
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 (*Client) RestartDatabase ¶ added in v0.10.0
func (*Client) RestoreVolumeBackup ¶ added in v0.12.0
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, appID uint) (*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
RevealSecret returns a secret's decrypted value (admin only, audited).
func (*Client) Rollback ¶
func (c *Client) Rollback(ctx context.Context, ws string, appID uint, 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
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) SecretUsage ¶ added in v0.10.0
func (*Client) Secrets ¶ added in v0.10.0
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, appID uint, 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) StartDatabase ¶ added in v0.10.0
func (*Client) StartMigration ¶ added in v0.16.0
func (*Client) StopDatabase ¶ added in v0.10.0
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 (*Client) UpdateConfig ¶ added in v0.10.0
func (*Client) UpdateSecret ¶ added in v0.10.0
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
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
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
VolumeBackups lists a volume's backup history, newest first as the panel returns it.
func (*Client) VolumeFiles ¶ added in v0.12.0
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
Volumes lists a workspace's managed volumes. The endpoint is not paginated.
func (*Client) WaitForDeploy ¶
func (c *Client) WaitForDeploy(ctx context.Context, ws string, appID, 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) WorkspaceEvents ¶ added in v0.17.0
WorkspaceEvents returns the newest events across the workspace. Pages are zero-based on the server.
func (*Client) WorkspaceOverview ¶ added in v0.17.0
WorkspaceOverview returns app health and resource counts for a workspace.
func (*Client) WorkspaceStorage ¶ added in v0.12.0
WorkspaceStorage returns the workspace's declared-vs-measured storage totals.
func (*Client) WorkspaceUsage ¶ added in v0.17.0
WorkspaceUsage returns resource usage against the plan's limits. It is passed through as-is: the shape grows with every new plan limit.
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
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 ¶
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
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
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 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"`
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
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 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.