api

package
v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 16 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"
)

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

func IsTerminal(status string) bool

IsTerminal reports whether a deployment status will not change further.

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

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

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

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

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

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

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

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

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, appID uint) 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, appID uint, req DeployRequest) (*Deployment, error)

func (*Client) Deployment

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

Deployment resolves a single deployment. The API exposes no per-deployment GET route, so it is found within the (recent) deployments 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 (c *Client) Deployments(ctx context.Context, ws string, appID uint) ([]Deployment, error)

func (*Client) DetachVolume added in v0.12.0

func (c *Client) DetachVolume(ctx context.Context, ws string, appID, 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, appID uint) ([]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, appID uint, req ImportEnvRequest) error

func (*Client) InvalidateBuildCache added in v0.11.0

func (c *Client) InvalidateBuildCache(ctx context.Context, ws string, appID uint) 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) 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) 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 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) 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) Releases

func (c *Client) Releases(ctx context.Context, ws string, appID uint) ([]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) ResolveAppID

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

ResolveAppID turns an app handle (or numeric id) into the numeric id paths use.

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) 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, appID uint) 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, 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

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, appID uint, req RollbackRequest) (*Deployment, error)

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) 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, 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) SetEnv

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

func (*Client) StartApp added in v0.10.0

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

func (*Client) StartDatabase added in v0.10.0

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

func (*Client) StopApp added in v0.10.0

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

func (*Client) StopDatabase added in v0.10.0

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

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) 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) 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, appID, depID uint, onUpdate func(status string)) (*Deployment, error)

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

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

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

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

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"`
	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 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 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"`
	StartedAt  *time.Time `json:"started_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 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

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 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 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"`
}

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"`
}

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