Documentation
¶
Overview ¶
Package client builds an authenticated Hostim API client from resolved config and maps API error responses (including 429 rate limiting) into Go errors.
Index ¶
- Constants
- Variables
- func Check(status int, body []byte) error
- func MergeVars(base, updates []api.EnvVar) []api.EnvVar
- func New(r config.Resolved) (*api.ClientWithResponses, error)
- func NewAnonymous(apiURL string) (*api.ClientWithResponses, error)
- func NormalizeApp(app *api.App)
- func ResolveProjectID(ctx context.Context, cl *api.ClientWithResponses, ref string) (string, error)
- type APIError
- type BuildResult
- type VolumeMount
Constants ¶
const ProjectIDPrefix = "hpr-"
ProjectIDPrefix is the prefix of the system-generated project identifiers used as the {projectName} path parameter by the API. Friendly project names are resolved to an ID before nested calls.
Variables ¶
var ErrBuildFailed = errors.New("build failed")
ErrBuildFailed is returned by PollBuild when the build reaches "failed".
var ErrDeployFailed = errors.New("deploy failed")
ErrDeployFailed is returned by PollBuild when a build-less (docker image) deploy cannot become healthy, e.g. the image can't be pulled.
var ErrEmptyResponse = errors.New("the API returned an empty response; retry, and report it if it keeps happening")
ErrEmptyResponse covers a 2xx answer with no payload: nothing the caller did causes it and no command can continue past it.
Functions ¶
func Check ¶
Check returns an *APIError if the response status is >= 400, else nil. Generated response structs expose StatusCode() and a Body []byte field, so callers use client.Check(resp.StatusCode(), resp.Body).
func MergeVars ¶ added in v0.1.22
MergeVars overlays updates onto base, replacing by name and appending new keys. The result is never nil, since the API rejects a null env array.
func New ¶
func New(r config.Resolved) (*api.ClientWithResponses, error)
New returns a ClientWithResponses that injects the Bearer token and transparently retries on 429 responses, honouring Retry-After.
func NewAnonymous ¶ added in v0.1.20
func NewAnonymous(apiURL string) (*api.ClientWithResponses, error)
NewAnonymous returns a client for the endpoints that take no token (the device-login flow), with the same 429 retry behaviour as New. Without it a single rate-limited poll would end a login that is otherwise fine.
func NormalizeApp ¶ added in v0.1.22
NormalizeApp replaces nil required-array fields with empty slices so they serialize as [] rather than null, which the API schema rejects.
func ResolveProjectID ¶ added in v0.1.22
ResolveProjectID maps a project reference (friendly name or ID) to the ID the API expects in the {projectName} path parameter. An ID (hpr-…) is returned as-is; a name is looked up via GetProjects. Callers pass whatever the user typed, so both work everywhere a project is referenced.
Types ¶
type APIError ¶
type APIError struct {
Status int
Code string // GenericMessage.error, when present
Message string // GenericMessage.message, when present
}
APIError is a structured error built from a non-2xx API response.
type BuildResult ¶
type BuildResult struct {
BuildStatus api.AppStatusBuildStatus
RuntimeStatus api.AppStatusRuntimeStatus
Status *api.AppStatus
}
BuildResult is the terminal outcome of a deploy poll.
func PollBuild ¶
func PollBuild( ctx context.Context, c *api.ClientWithResponses, project, app string, interval time.Duration, expectBuild bool, onTick func(*api.AppStatus), ) (BuildResult, error)
PollBuild polls an app's status until it reaches a terminal state or the context is cancelled. onTick, if non-nil, is called with each observed status so callers can render progress.
expectBuild selects what "terminal" means:
- true (git source): wait for buildStatus to reach succeeded/failed. A git deploy always runs a build, so the build outcome is the meaningful signal.
- false (docker image source): there is no build phase, so buildStatus stays empty and the app goes straight to running. Wait for runtimeStatus instead: running is success, imagePullBackoff is a definitive failure. Transient states (pending/crashing) keep polling until running or timeout.
It returns ErrBuildFailed / ErrDeployFailed (wrapped) on failure so callers can exit non-zero.
type VolumeMount ¶ added in v0.1.22
type VolumeMount = struct {
MountPath *string `json:"mountPath,omitempty"`
Name *string `json:"name,omitempty"`
}
VolumeMount matches the anonymous struct type of App.VolumeMounts, so it can be assigned directly.
func ParseVolumeMounts ¶ added in v0.1.22
func ParseVolumeMounts(specs []string) ([]VolumeMount, error)
ParseVolumeMounts turns "name:/mount/path" values into app volume mounts.
Source Files