stack

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Aug 19, 2026 License: MIT Imports: 7 Imported by: 1

Documentation

Overview

Package stack represents a cloud stack operations under the `/cloud/stack` API endpoint.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddRequest 

type AddRequest struct {
	ServerName           string `json:"server_name"`
	Name                 string `json:"name"`
	Label                string `json:"label"`
	EnableSSL            int    `json:"enable_ssl"`
	DockerCompose        string `json:"docker_compose"`
	EnvironmentVariables []models.EnvironmentVariable
}

AddRequest represents the construction / setup of a new cloud stack.

type AddResponse 

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

AddResponse is the response from calling the create stack api.

type BackupRequest added in v0.7.0 

type BackupRequest struct {
	ServerName string `json:"server_name"`
	Name       string `json:"name"`
}

BackupRequest creates a backup of a stack. Both fields are required.

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

func (s *Client) Add(ctx context.Context, request AddRequest) (response AddResponse, err error)

Add creates a new cloud stack.

Gotchas (validated live, May 2026)

  1. **Compose body must set `nz.sitehost.container.label` to a valid FQDN** for any container with type=www or type=application. The API rejects with "Unable to add stack, the hostname is invalid." if this label's value isn't a hostname-shaped string. The Label parameter on AddRequest is *not* the field being validated here — the check is on the compose body, not the API param. Set the same FQDN on both for consistency.

  2. **Stack Name must come from cloud.stack.GenerateName.** The API rejects custom-shaped names with the same generic "hostname is invalid" message; only platform-generated "cc<hex>" names are accepted.

  3. **Compose image references need an explicit version tag.** `image: registry-clients.sitehost.co.nz/g_<id>/<code>` is rejected with "There was no image version provided."; you must include the `:1.0-<build_id>` tag from cloud.image.version.list_all (or use the WaitForBuild helper which surfaces it).

  4. **Per-CCS write-time resource gate.** When the target CCS is at capacity the API returns "the number of new images required exceeds the number of available images on this server." The read-side fields on cloud.server.List (images_used / images_remaining) don't reliably reflect the live cap; provision a fresh CCS or free a slot.

func (*Client) Backup added in v0.7.0 

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

Backup creates a backup of a cloud stack via "cloud/stack/backup.json". ServerName and Name are required. Returns a scheduler job id; the backup is taken asynchronously.

func (*Client) Copy added in v0.7.0 

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

Copy duplicates an existing cloud stack onto a destination server via "cloud/stack/copy.json". SourceServer, Name, DestinationServer, and Label are required. The new stack inherits the source's docker_compose; Label sets the new stack's label.

SourceServer and DestinationServer may be the same when copying within a single server. Returns a scheduler job id.

func (*Client) Delete added in v0.7.0 

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

Delete removes a cloud stack via "cloud/stack/delete.json". Both ServerName and Name are required. Returns a scheduler job id; the operation is asynchronous.

Destructive: removes the stack and its configuration. The containers themselves are stopped and removed as part of the job.

func (*Client) GenerateName 

func (s *Client) GenerateName(ctx context.Context) (response GenerateNameResponse, err error)

GenerateName generate a new cloud stack name.

func (*Client) Get 

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

Get fetches a cloud stack.

func (*Client) List 

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

List fetches all cloud stacks on a specific server.

func (*Client) Overwrite added in v0.7.0 

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

Overwrite replaces a destination stack's contents with a source stack's via "cloud/stack/overwrite.json". SourceServer, Name (the source stack), DestinationServer, and DestinationStack are all required.

Destructive on the destination: the destination stack's docker_compose is replaced with the source's. Returns a scheduler job id.

func (*Client) PurgeCache added in v0.7.0 

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

PurgeCache clears cached content from a cloud stack via "cloud/stack/purge_cache.json". ServerName and Name are required. Returns a scheduler job id.

Non-destructive: only the stack's edge cache is cleared; the stack itself, its configuration, and its data are untouched.

func (*Client) Restart 

func (s *Client) Restart(ctx context.Context, request StopStartRestartRequest) (response StartStopRestartResponse, err error)

Restart restarts a stack on the given server.

func (*Client) Start 

func (s *Client) Start(ctx context.Context, request StopStartRestartRequest) (response StartStopRestartResponse, err error)

Start starts a cloud stack on a given server.

func (*Client) Stop 

func (s *Client) Stop(ctx context.Context, request StopStartRestartRequest) (response StartStopRestartResponse, err error)

Stop is for stopping a cloud stack on a given server.

func (*Client) Update added in v0.7.0 

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

Update modifies an existing cloud stack via "cloud/stack/update.json". ServerName and Name are required. Label, EnableSSL, DockerCompose, and EnvironmentVariables are sent when non-zero / non-empty; the caller can leave any of them at zero to skip updating that field.

Returns a scheduler job id; the operation is asynchronous.

type CopyRequest added in v0.7.0 

type CopyRequest struct {
	SourceServer      string `json:"source_server"`
	Name              string `json:"name"`
	DestinationServer string `json:"destination_server"`
	Label             string `json:"label"`
}

CopyRequest duplicates a stack onto a destination server. All four fields are required. SourceServer and DestinationServer may be the same when copying within a single server. Label is the new stack's label; the new stack's name is the same as the source's (the API does not expose a destination-name override on copy).

type DeleteRequest added in v0.7.0 

type DeleteRequest struct {
	ServerName string `json:"server_name"`
	Name       string `json:"name"`
}

DeleteRequest removes an existing stack. Both fields are required.

type GenerateNameResponse 

type GenerateNameResponse struct {
	Return struct {
		Name string `json:"name"`
	} `json:"return"`
	models.APIResponse
}

GenerateNameResponse represents the response from generate_name action.

type GetRequest 

type GetRequest struct {
	ServerName string `json:"server_name"`
	Name       string `json:"name"`
}

GetRequest represents a request to get a specific stack.

type GetResponse 

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

GetResponse GetReponse is the response for getting a single stack.

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 shape for the asynchronous write operations: Update, Delete, Copy, Overwrite, Backup, and PurgeCache. Each queues a scheduler job; the job id is returned for tracking.

type ListRequest 

type ListRequest struct {
	ServerName string `json:"server_name"`
}

ListRequest represents a listing request for stacks on a server.

type ListResponse 

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

ListResponse is the response for listing stacks.

type OverwriteRequest added in v0.7.0 

type OverwriteRequest struct {
	SourceServer      string `json:"source_server"`
	Name              string `json:"name"`
	DestinationServer string `json:"destination_server"`
	DestinationStack  string `json:"destination_stack"`
}

OverwriteRequest replaces a destination stack's contents with a source stack's. All four fields are required. DestinationStack identifies the existing target by name on DestinationServer; SourceServer + Name identify the source.

type PurgeCacheRequest added in v0.7.0 

type PurgeCacheRequest struct {
	ServerName string `json:"server_name"`
	Name       string `json:"name"`
}

PurgeCacheRequest clears cached content from a stack. Both fields are required.

type StartStopRestartResponse 

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

StartStopRestartResponse represents the response from start/stop/restart actions.

type StopStartRestartRequest 

type StopStartRestartRequest struct {
	ServerName string   `json:"server_name"`
	Name       string   `json:"name"`
	Containers []string `json:"containers"`
}

StopStartRestartRequest is a request to start, restart or stop a cloud stack/container.

type UpdateRequest added in v0.7.0 

type UpdateRequest struct {
	ServerName           string `json:"server_name"`
	Name                 string `json:"name"`
	Label                string `json:"label"`
	EnableSSL            int    `json:"enable_ssl"`
	DockerCompose        string `json:"docker_compose"`
	EnvironmentVariables []models.EnvironmentVariable
}

UpdateRequest modifies an existing stack. ServerName and Name are required (they identify the stack). Label, DockerCompose, and EnvironmentVariables are sent when non-empty; leave them at their zero value to skip updating that property. EnableSSL is always sent (0 or 1).

Source Files

View all Source files

Directories

Path Synopsis
Package environment represents a cloud stack environment operations under the `/cloud/stack/environment` API endpoint.
 Package environment represents a cloud stack environment operations under the `/cloud/stack/environment` API endpoint.
Package image provides access to the `/cloud/stack/image` API endpoint.
 Package image provides access to the `/cloud/stack/image` API endpoint.
ssl
letsencrypt
Package letsencrypt wraps SiteHost's Cloud-Container Let's Encrypt endpoints under /cloud/stack/ssl/lets_encrypt.
 Package letsencrypt wraps SiteHost's Cloud-Container Let's Encrypt endpoints under /cloud/stack/ssl/lets_encrypt.

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.