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 IsFailure(status string) bool
- func IsTerminal(status string) bool
- type APIError
- type App
- type ApplyFailure
- type ApplyRequest
- type ApplyResult
- type Change
- type Client
- func (c *Client) App(ctx context.Context, wsID, appID uint) (*App, error)
- func (c *Client) Apply(ctx context.Context, wsID uint, manifests string, prune bool) (*ApplyResult, error)
- func (c *Client) Apps(ctx context.Context, wsID uint) ([]App, error)
- func (c *Client) Delete(ctx context.Context, wsID uint, manifests string) (*ApplyResult, error)
- func (c *Client) Deploy(ctx context.Context, wsID, appID uint, req DeployRequest) (*Deployment, error)
- func (c *Client) Deployment(ctx context.Context, wsID, appID, depID uint) (*Deployment, error)
- func (c *Client) Deployments(ctx context.Context, wsID, appID uint) ([]Deployment, error)
- func (c *Client) ImportEnv(ctx context.Context, wsID, appID uint, req ImportEnvRequest) error
- func (c *Client) Me(ctx context.Context) (*Me, error)
- func (c *Client) PlanApply(ctx context.Context, wsID uint, manifests string, prune bool) (*Plan, error)
- func (c *Client) PlanDelete(ctx context.Context, wsID uint, manifests string) (*Plan, error)
- func (c *Client) Releases(ctx context.Context, wsID, appID uint) ([]Release, error)
- func (c *Client) ResolveAppID(ctx context.Context, wsID uint, ref string) (uint, error)
- func (c *Client) ResolveWorkspaceID(ctx context.Context, ref string, fallbackID uint) (uint, error)
- func (c *Client) Rollback(ctx context.Context, wsID, appID uint, req RollbackRequest) (*Deployment, error)
- func (c *Client) SetEnv(ctx context.Context, wsID, appID uint, req SetEnvRequest) error
- func (c *Client) WaitForDeploy(ctx context.Context, wsID, appID, depID uint, onUpdate func(status string)) (*Deployment, error)
- func (c *Client) Workspaces(ctx context.Context) ([]Workspace, error)
- type DeployRequest
- type Deployment
- type ImportEnvRequest
- type Me
- type Plan
- type Release
- type RollbackRequest
- type SetEnvRequest
- type Workspace
Constants ¶
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.
Variables ¶
var Version = "dev"
Version is stamped at build time (see .goreleaser.yaml); used in User-Agent.
Functions ¶
func IsTerminal ¶
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.
type App ¶
type App struct {
ID uint `json:"id"`
Slug string `json:"slug"`
Name string `json:"name"`
Image string `json:"image"`
Tag string `json:"tag"`
Status string `json:"status"`
CurrentReleaseID *uint `json:"current_release_id"`
}
App is an application listing/detail (only the fields the CLI surfaces).
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 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 (*Client) Apply ¶
func (c *Client) Apply(ctx context.Context, wsID uint, manifests string, prune bool) (*ApplyResult, error)
Apply converges the workspace to the manifest bundle.
func (*Client) Deploy ¶
func (c *Client) Deploy(ctx context.Context, wsID, appID uint, req DeployRequest) (*Deployment, error)
func (*Client) Deployment ¶
Deployment resolves a single deployment. The API exposes no per-deployment GET route, so it is found within the (recent) deployments list.
func (*Client) Deployments ¶
func (*Client) PlanApply ¶
func (c *Client) PlanApply(ctx context.Context, wsID uint, 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) ResolveAppID ¶
ResolveAppID turns an app slug (or numeric id) into the numeric id paths use.
func (*Client) ResolveWorkspaceID ¶
ResolveWorkspaceID turns a user-supplied workspace reference into the numeric id the API addresses by. ref may be a numeric id, a UID, or a slug; an empty ref falls back to fallbackID (the persisted/bound workspace) and finally to the sole workspace the caller can see.
func (*Client) Rollback ¶
func (c *Client) Rollback(ctx context.Context, wsID, appID uint, req RollbackRequest) (*Deployment, error)
func (*Client) WaitForDeploy ¶
func (c *Client) WaitForDeploy(ctx context.Context, wsID, 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.
type DeployRequest ¶
type DeployRequest struct {
Tag string `json:"tag,omitempty"`
Strategy string `json:"strategy,omitempty"`
RegistryID *uint `json:"registry_id,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"`
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"`
}
Deployment is the deploy/rollback response and status object.
type ImportEnvRequest ¶
ImportEnvRequest is the body of POST .../env/import.
type Me ¶
type Me struct {
ID uint `json:"id"`
Name string `json:"name"`
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 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 RollbackRequest ¶
type RollbackRequest struct {
ReleaseID uint `json:"release_id"`
}
RollbackRequest is the body of POST .../rollback.
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.