image

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package image provides access to the `/cloud/image` API endpoint.

Index

Constants

View Source 
const (
	BuildStatusSuccess = "success"
	BuildStatusFailed  = "failed"
	BuildStatusRunning = "running"
)

BuildStatus values returned by the platform CI for a custom image version. Compared as strings; not exhaustive — surface unknowns to the caller verbatim.

Variables

This section is empty.

Functions

func LintManifest added in v0.7.0 

func LintManifest(data []byte) error

LintManifest validates the bytes of a custom-image manifest.yml against the documented minimum schema:

  • top-level "version" key (must be 1)
  • "image.label" non-empty
  • "image.type" non-empty (typically "www" or a service name)
  • "image.provider" non-empty (the customer/account label)

Local lint is intentionally narrow: catch the "did you forget a required field" class of mistakes that otherwise only surface hours later in a failed CI build trace. The platform's CI remains the source of truth for the full schema.

Types

type Changelog added in v0.7.0 

type Changelog struct {
	Code      string `json:"code"`
	Label     string `json:"label"`
	Changelog string `json:"changelog"`
}

Changelog is the body of GetChangelogResponse.

type Client 

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

Client is a Service to work with API Jobs.

func New 

func New(c *api.Client) *Client

New is an initialisation function.

func (*Client) CloneURL added in v0.7.0 

func (s *Client) CloneURL(imageCode string) string

CloneURL returns the SSH git clone URL for a custom image's backing GitLab repository. The format is 

git@<host>:g_<client_id>/<image_code>.git

host defaults to "gitlab-clients.sitehost.co.nz" but can be overridden via api.SetCustomImageGitHost when constructing the underlying api.Client. client_id is the consumer's account ID (already on the api.Client). image_code is the image's Code as returned by Get / list_all.

**Why this is a helper rather than an API field:** the GitLab repo URL isn't returned by any /cloud/image endpoint — only the Docker registry URL is (registry_url). Consumers were expected to copy the repo URL from the Control Panel UI; this helper closes that gap so SDK consumers can clone without leaving the Go program.

func (*Client) Create added in v0.7.0 

func (s *Client) Create(ctx context.Context, request CreateRequest) (response JobResponse, err error)

Create creates a new custom image via /cloud/image/create.json.

Label is required. Code is optional — the API generates one from the label when omitted, but consumers usually want to specify it so the image's GitLab repository slug is predictable.

ForkID forks a public SiteHost image (the parent's id, available from cloud/image/list_all.json's is_public=1 entries). When zero, the image is built from scratch.

SSHKeys grants the listed customer-level SSH key IDs access to the backing GitLab repository at gitlab-clients.sitehost.co.nz. Without at least one key, the customer cannot push commits.

The endpoint returns a scheduler job; the image record (and its GitLab repository) is created asynchronously. Consumers should poll cloud/job until the job completes before attempting to clone.

func (*Client) Delete added in v0.7.0 

func (s *Client) Delete(ctx context.Context, request DeleteRequest) (response JobResponse, err error)

Delete deletes a custom image via /cloud/image/delete.json. The API rejects deletion if any container is still using a version of this image — clean those up first. Returns a scheduler job.

func (*Client) ForkFromImage added in v0.7.0 

func (s *Client) ForkFromImage(ctx context.Context, parentCode, label, code string, sshKeyIDs []int) (response JobResponse, err error)

ForkFromImage creates a new custom image forked from a SiteHost public image identified by parentCode (e.g. "sitehost-php80").

This composite helper resolves the public parent's numeric id by listing the platform stack-image catalogue and matching on Code+IsPublic, then calls Create with that fork_id. Without this helper, consumers have to do the list-filter-extract-id dance themselves.

The parent lookup uses /cloud/stack/image/list_all (the platform catalogue, where public images live) rather than /cloud/image/list_all (the customer-only endpoint, which returns just the calling client's own custom images). That distinction matters on bootstrap accounts: the customer endpoint is empty before the first fork, so a lookup against it would always miss public parents — exactly the case where this helper is most useful.

label is required (used as the new image's display label). code is the desired image code (slug used in the GitLab repo URL and registry); pass "" to let the API auto-generate it from label. sshKeyIDs are customer-level SSH key IDs that get push access to the backing GitLab repository — at least one is required for the consumer to push commits.

Returns the JobResponse from Create. Consumers should poll the job to completion before calling CloneURL or attempting a clone, since the GitLab repo is provisioned asynchronously.

func (*Client) Get 

func (s *Client) Get(ctx context.Context, request GetRequest) (response GetResponse, err error)

Get fetches a cloud image.

func (*Client) GetChangelog added in v0.7.0 

func (s *Client) GetChangelog(ctx context.Context, request GetChangelogRequest) (response GetChangelogResponse, err error)

GetChangelog returns the change log for a *public* SiteHost image via /cloud/image/get_changelog.json. This is for SiteHost-provided base images (e.g. "sitehost-php55"); custom images don't carry platform-managed changelogs.

func (*Client) List 

func (s *Client) List(ctx context.Context) (response ListResponse, err error)

List returns a list of stack images, specific to the customer.

func (*Client) WaitForBuild added in v0.7.0 

func (s *Client) WaitForBuild(ctx context.Context, imageID int, timeout, interval time.Duration) (version.Version, error)

WaitForBuild polls cloud/image/version/list_all for the named image (by numeric image_id) until the most-recent version reports a terminal build status (success or failed), or the timeout is reached. interval controls poll cadence.

Returns the terminating Version. If the build failed, the caller should fetch the trace via cloud.image.version.GetBuild(code, build_id) to surface the failure to the user.

Why a helper: the API doesn't expose a build-watching endpoint, so consumers always have to poll. Doing it consistently here also protects against the platform's "Only the last successfully built version is available to be deployed" rule — we always look at the latest version, never an older success.

type CreateRequest added in v0.7.0 

type CreateRequest struct {
	Label   string
	Code    string
	ForkID  int
	SSHKeys []int
}

CreateRequest creates a new custom image via /cloud/image/create.json. Label is required. Code is optional — the API generates one from the label if omitted. ForkID is the id of a public SiteHost image to fork from (optional; omit to build from scratch). SSHKeys is a list of customer-level SSH key IDs to grant access to the backing GitLab repository.

type DeleteRequest added in v0.7.0 

type DeleteRequest struct {
	Code string
}

DeleteRequest deletes a custom image via /cloud/image/delete.json.

type GetChangelogRequest added in v0.7.0 

type GetChangelogRequest struct {
	Code string
}

GetChangelogRequest fetches the change log for a public SiteHost image via /cloud/image/get_changelog.json. Code is the public image's code (e.g. "sitehost-php55").

type GetChangelogResponse added in v0.7.0 

type GetChangelogResponse struct {
	Return Changelog `json:"return"`
	models.APIResponse
}

GetChangelogResponse represents the return from /cloud/image/get_changelog.json.

type GetRequest 

type GetRequest struct {
	Code string `json:"code"`
}

GetRequest represents a request to get a specific image from the /cloud/image/get.json endpoint.

type GetResponse 

type GetResponse struct {
	Image models.CloudImage `json:"return"`
	models.APIResponse
}

GetResponse represents the return from the /cloud/image/get.json endpoint.

type JobResponse added in v0.7.0 

type JobResponse struct {
	Return struct {
		models.Job `json:"job"`
	} `json:"return"`
	models.APIResponse
}

JobResponse is the shared response for image write operations that queue a scheduler job (Create, Delete).

type LintError added in v0.7.0 

type LintError struct {
	Errors []string
}

LintError is returned by LintManifest when a manifest.yml fails schema validation. Errors holds one entry per problem found.

func (*LintError) Error added in v0.7.0 

func (e *LintError) Error() string

Error joins the lint errors into a single message.

type ListResponse 

type ListResponse struct {
	Return struct {
		models.Pagination
		Images []models.CloudImage `json:"data"`
	}
	models.APIResponse
}

ListResponse represents the return from the /cloud/image/list_all.json endpoint.

Source Files

View all Source files

Directories

Path Synopsis
Package version provides access to the /cloud/image/version endpoints — listing build history for a custom image, fetching build logs, and deleting individual versions.
 Package version provides access to the /cloud/image/version endpoints — listing build history for a custom image, fetching build logs, and deleting individual versions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.