server

type AddIPOptions ¶ added in v0.7.0

type AddIPOptions struct {
	Name      string `url:"name"`
	IP        string `url:"-"`
	IPVersion int    `url:"-"`
}

AddIPOptions describes an IP address to add to a server.

Set exactly one of IP or IPVersion:

• IP: a real IPv4 or IPv6 address already allocated to the calling client_id.
• IPVersion: 4 or 6 to auto-allocate a free address of that family from the location's pool.

At the wire level the API takes a single `param` field whose value is either the address or the family number — that magic-string convention is awkward to expose, so the wrapper splits it into two typed fields and assembles `param` itself.

Note: "auto" works on Create but is rejected here. The two endpoints use different conventions:

• Create: params[ipv4][0]=auto (string "auto")
• AddIP: param=4 or param=6 (family number)

Live evidence (May 2026): AddIP{IP:"auto"} returns "Error: The ip address is invalid, please specify a valid ip address." AddIP{IPVersion:4} successfully allocates an IPv4 from the pool; AddIP{IPVersion:6} an IPv6.

The API uses "param" (not "address") for this field — the inconsistency with RemoveIPOptions ("address") is the API's, not gosh's.

type AllocatedIP ¶ added in v0.7.0

type AllocatedIP struct {
	IPAddr   string `json:"ip_addr"`
	Netmask  string `json:"netmask"`
	Gateway  string `json:"gateway"`
	Location string `json:"location"`
	Type     string `json:"type"` // "v4" or "v6"
}

AllocatedIP describes one IP currently allocated to the authenticated client, as returned by list_allocated_i_ps.

type AvailableIP ¶ added in v0.7.0

type AvailableIP struct {
	IPAddr string `json:"ip_addr"`
	Prefix int    `json:"prefix"`
	Family int    `json:"family"` // 4 for IPv4, 6 for IPv6
}

AvailableIP is a single IP entry from server.list_ips. The API returns objects, not strings — earlier versions of this wrapper had `Return []string` which silently dropped the per-IP shape.

type CanProvisionOptions ¶ added in v0.7.0

type CanProvisionOptions struct {
	Product  string `url:"product"`
	Location string `url:"location"`
	Distro   string `url:"distro"`
	Arch     string `url:"arch,omitempty"`
}

CanProvisionOptions checks resource availability for provisioning a server. Product, Location, and Distro are required; Arch is optional.

type ChangeStateOptions ¶ added in v0.7.0

type ChangeStateOptions struct {
	Name  string `url:"name"`
	State string `url:"state"`
}

ChangeStateOptions describes a server state transition. Valid State values: "power_on", "power_off", "rescue_on", "rescue_off", "reboot".

type ChangeStateResponse ¶ added in v0.7.0

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

ChangeStateResponse represents the response from change_state — a scheduler job for the state transition.

type Client ¶

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

Client is a Service to work with API Jobs.

func New(c *api.Client) *Client

func (s *Client) AddIP(ctx context.Context, opt AddIPOptions) (response IPJobResponse, err error)

func (s *Client) CanProvision(ctx context.Context, opt CanProvisionOptions) (response models.APIResponse, err error)

func (s *Client) ChangeState(ctx context.Context, opt ChangeStateOptions) (response ChangeStateResponse, err error)

func (s *Client) CommitDiskChanges(ctx context.Context, request CommitDiskChangesRequest) (response CommitDiskChangesResponse, err error)

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

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

func (s *Client) GenerateNetworkConfig(ctx context.Context, opt GenerateNetworkConfigOptions) (response GenerateNetworkConfigResponse, err error)

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

func (s *Client) GetState(ctx context.Context, opt GetStateOptions) (response GetStateResponse, err error)

func (s *Client) GetStatistics(ctx context.Context, opt GetStatisticsOptions) (response GetStatisticsResponse, err error)

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

func (s *Client) ListAllocatedIPs(ctx context.Context) (response ListAllocatedIPsResponse, err error)

func (s *Client) ListIPs(ctx context.Context, opt ListIPsOptions) (response ListIPsResponse, err error)

func (s *Client) ListImages(ctx context.Context) (response ListImagesResponse, err error)

func (s *Client) ListLocations(ctx context.Context) (response ListLocationsResponse, err error)

func (s *Client) ListResources(ctx context.Context) (response ListResourcesResponse, err error)

func (s *Client) ListStatisticTypes(ctx context.Context, opt ListStatisticTypesOptions) (response ListStatisticTypesResponse, err error)

func (s *Client) ListUpgrades(ctx context.Context, opt ListUpgradesOptions) (response ListUpgradesResponse, err error)

func (s *Client) RemoveIP(ctx context.Context, opt RemoveIPOptions) (response IPJobResponse, err error)

func (s *Client) SetPrimaryIP(ctx context.Context, opt SetPrimaryIPOptions) (response SetPrimaryIPResponse, err error)

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

func (s *Client) Upgrade(ctx context.Context, opts UpgradeRequest) (response UpdateResponse, err error)

func (s *Client) UpgradeComponents(ctx context.Context, request UpgradeComponentsRequest) (response UpgradeComponentsResponse, err error)

type CommitDiskChangesRequest ¶

type CommitDiskChangesRequest struct {
	ServerName string `json:"name"`
}

CommitDiskChangesRequest represents request params for CommitDiskChanges server endpoint.

type CommitDiskChangesResponse ¶

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

CommitDiskChangesResponse represents a result of a commit changes Server call.

type CreateRequest ¶

type CreateRequest struct {
	ClientID    string        `json:"client_id"`
	Label       string        `json:"label"`
	Location    string        `json:"location"`
	ProductCode string        `json:"product_code"`
	Image       string        `json:"image"`
	Params      ParamsOptions `json:"params"`
}

CreateRequest represents a request to create a Server.

type CreateResponse ¶

type CreateResponse struct {
	Return struct {
		models.Job `json:"job"`
		Name       string   `json:"name"`
		Password   string   `json:"password"`
		Ips        []string `json:"ips"`
		ServerID   string   `json:"server_id"`
	} `json:"return"`
	models.APIResponse
}

CreateResponse represents a result of the create a Server call.

type DeleteRequest ¶

type DeleteRequest struct {
	Name  string `json:"name"`
	Force bool   `json:"-"`
}

DeleteRequest represents a request to delete a Server.

Force, when set, appends `force_delete=1` to the form body. Required to tear down a fresh CCS that still has its auto-deployed `infra` stack present (collectd, nginx-proxy, LE companion); without Force the API rejects with "the server has containers." See the doc comment on Delete.

type DeleteResponse ¶

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

DeleteResponse represents a result of a delete Server call.

type DiskUpgradeOptions ¶ added in v0.7.0

type DiskUpgradeOptions struct {
	Included []int `json:"included"`
	Extra    []int `json:"extra"`
}

DiskUpgradeOptions is the per-disk-slot list of included and available extra disk sizes.

type ExtraDiskOption ¶ added in v0.7.0

type ExtraDiskOption struct {
	Price float64 `json:"price"`
	Size  int     `json:"size"`
}

ExtraDiskOption is the per-unit price/size offered for additional disk capacity.

type GenerateNetworkConfigOptions ¶ added in v0.7.0

type GenerateNetworkConfigOptions struct {
	Name string `url:"name"`
}

GenerateNetworkConfigOptions represents request params for the generate_network_config endpoint.

type GenerateNetworkConfigResponse ¶ added in v0.7.0

type GenerateNetworkConfigResponse struct {
	Return map[string]string `json:"return"`
	models.APIResponse
}

GenerateNetworkConfigResponse represents the response from generate_network_config. The Return map is keyed by file path (e.g. "/etc/netplan/50-cloud-init.yaml") with file contents as the value.

func (r *GenerateNetworkConfigResponse) UnmarshalJSON(data []byte) error

type GetRequest ¶

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

GetRequest represents request params for get server endpoint.

type GetResponse ¶

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

GetResponse represents a result of a get Server call.

type GetStateOptions ¶ added in v0.7.0

type GetStateOptions struct {
	Name string `url:"name"`
}

GetStateOptions represents request params for the get_state endpoint.

type GetStateResponse ¶ added in v0.7.0

type GetStateResponse struct {
	Return ServerState `json:"return"`
	models.APIResponse
}

GetStateResponse represents the response from get_state.

type GetStatisticsOptions ¶ added in v0.7.0

type GetStatisticsOptions struct {
	ServerName string `url:"server_name"`
}

GetStatisticsOptions identifies the server whose metric values to fetch. Like ListStatisticTypesOptions, the parameter is "server_name".

type GetStatisticsResponse ¶ added in v0.7.0

type GetStatisticsResponse struct {
	Return map[string]interface{} `json:"return"`
	models.APIResponse
}

GetStatisticsResponse is the response for get_statistics. The Return shape is server-specific and time-windowed; consumers typically deserialise selectively from the raw JSON when looking at specific metrics. Captured here as a generic map to keep gosh's surface usable without schema-locking.

func (r *GetStatisticsResponse) UnmarshalJSON(data []byte) error

type IPJobResponse ¶ added in v0.7.0

type IPJobResponse struct {
	Return struct {
		models.Job `json:"job"`
		IPAddr     string `json:"ip_addr"`
	} `json:"return"`
	models.APIResponse
}

IPJobResponse represents the shared response from add_ip and remove_ip — a scheduler job plus the IP address that was affected.

type Image ¶ added in v0.7.0

type Image struct {
	Name   string `json:"name"`
	Code   string `json:"code"`
	Arch   string `json:"arch"`
	Distro string `json:"distro"`
	Type   string `json:"type"`
	OS     string `json:"os"`
}

Image is a server image entry from list_images.

type LastJob ¶ added in v0.7.0

type LastJob struct {
	ID    string `json:"id"`
	Type  string `json:"type"`
	State string `json:"state"`
}

LastJob is a brief summary of the most recent job affecting a server, returned by get_state.

type ListAllocatedIPsResponse ¶ added in v0.7.0

type ListAllocatedIPsResponse struct {
	Return map[string]AllocatedIP `json:"return"`
	models.APIResponse
}

ListAllocatedIPsResponse is the response for list_allocated_i_ps. Return is a map keyed by a transformed IP string (IPv4 dots preserved; IPv6 colons replaced with dots, double-colon replaced with double-dot). The IPAddr field on each value carries the original IP literal.

func (r *ListAllocatedIPsResponse) UnmarshalJSON(data []byte) error

type ListIPsOptions ¶ added in v0.7.0

type ListIPsOptions struct {
	Location string `url:"location"`
}

ListIPsOptions identifies the location whose available IPs to list. The Location field maps to the API's "location" parameter (a location code from server.ListLocations).

type ListIPsResponse ¶ added in v0.7.0

type ListIPsResponse struct {
	Return []AvailableIP `json:"return"`
	models.APIResponse
}

ListIPsResponse is the response for server.list_ips. The Return slice lists IPs available for new provisioning at the given location; empty when none are free.

type ListImagesResponse ¶ added in v0.7.0

type ListImagesResponse struct {
	Return []Image `json:"return"`
	models.APIResponse
}

ListImagesResponse represents the response from list_images.

type ListLocationsResponse ¶ added in v0.7.0

type ListLocationsResponse struct {
	Return []Location `json:"return"`
	models.APIResponse
}

ListLocationsResponse represents the response from list_locations.

type ListResourcesResponse ¶ added in v0.7.0

type ListResourcesResponse struct {
	Return []ResourceGroup `json:"return"`
	models.APIResponse
}

ListResourcesResponse represents the response from list_resources.

type ListResponse ¶ added in v0.3.1

type ListResponse struct {
	Return struct {
		models.Pagination
		Servers []models.Server `json:"data"`
	} `json:"return"`
	models.APIResponse
}

ListResponse lists all servers.

type ListStatisticTypesOptions ¶ added in v0.7.0

type ListStatisticTypesOptions struct {
	ServerName string `url:"server_name"`
}

ListStatisticTypesOptions identifies the server whose metric types to enumerate. The parameter is "server_name" — distinct from siblings that use plain "name".

type ListStatisticTypesResponse ¶ added in v0.7.0

type ListStatisticTypesResponse struct {
	Return []string `json:"return"`
	models.APIResponse
}

ListStatisticTypesResponse is the response for list_statistic_types. Return enumerates the metric type IDs the named server currently exposes.

type ListUpgradesOptions ¶ added in v0.7.0

type ListUpgradesOptions struct {
	Name string `url:"name"`
}

ListUpgradesOptions represents request params for the list_upgrades endpoint.

type ListUpgradesResponse ¶ added in v0.7.0

type ListUpgradesResponse struct {
	Return Upgrades `json:"return"`
	models.APIResponse
}

ListUpgradesResponse represents the response from list_upgrades.

type Location ¶ added in v0.7.0

type Location struct {
	Public             string   `json:"public"`
	OS                 []string `json:"os"`
	Label              string   `json:"label"`
	Code               string   `json:"code"`
	Datacenter         string   `json:"datacenter"`
	AvailableIPs       int      `json:"available_ips"`
	AvailableIPv4      int      `json:"available_ipv4"`
	AvailableIPv6      int      `json:"available_ipv6"`
	IPv6               bool     `json:"ipv6"`
	PublicPrivateCloud bool     `json:"public_private_cloud"`
	ProductTypes       []string `json:"product_types"`
}

Location is a datacenter location entry from list_locations. Public is returned as a string flag ("0"/"1") by the API.

type Number ¶ added in v0.7.0

type Number float64

Number tolerates the server API's mixed JSON-string / JSON-number serialisation of numeric fields. ResourceQuota.UsedUnits and TotalUnits are the known cases: when usage is non-zero the value arrives as a JSON string (`"783"`), when usage is zero it arrives as a JSON number (`0`), within the same response. Mirrors bandwidth.Number from PR #43, which surfaced the same quirk on the parallel /bandwidth/list_resources endpoint.

func (n *Number) UnmarshalJSON(b []byte) error

type ParamsOptions ¶

type ParamsOptions struct {
	Name string `json:"name,omitempty"`
	// IPv4 — see the IP-allocation paths section above. Most
	// callers want []string{"auto"}.
	IPv4      []string `json:"ipv4"`
	IPv6      []string `json:"ipv6,omitempty"`
	SSHKeys   []string `json:"ssh_keys,omitempty"`
	ContactID string   `json:"contact_id,omitempty"`
	Backup    string   `json:"backup,omitempty"`
	SendEmail string   `json:"send_email,omitempty"`
}

ParamsOptions represents the additional parameters in the request to create a Server.

IP allocation paths ¶

IPv4 / IPv6 control how the new server gets its address(es). There are three paths consumers should know about:

1. **Auto-allocation (recommended for most cases).** Pass []string{"auto"} for IPv4 and/or IPv6. The platform picks a free address from the location's pool and binds it to the new server. This is the path the public API docs explicitly recommend ("simply pass the string 'auto' to automatically assign an IPv4 address").

2. **Specific pre-allocated address.** Pass the address(es) directly, e.g. []string{"203.0.113.10"}. The address must already be allocated to the calling client_id — the platform won't transfer pool IPs at provision time this way. server.ListIPs(location) returns the IPs currently allocated to the client; if it returns [] that does NOT mean the pool is exhausted, only that this client has no allocations there. Use server.ListLocations to read pool-wide capacity (`available_ipv4`, `available_ipv6`).

3. **Manual allocation by SiteHost staff.** Reseller-style arrangements may have IPs reserved for specific clients via SiteHost ops, then accessed via path (2) once visible in ListIPs. Out of band relative to the API.

Don't conflate "ListIPs returned []" with "pool exhausted" — the wrapper's empty result almost always means "use 'auto' instead, or check ListLocations." A previous gosh session wasted ~30 minutes retrying because of this confusion.

type QuotaUsage ¶ added in v0.7.0

type QuotaUsage struct {
	Total int `json:"total"`
	Used  int `json:"used"`
}

QuotaUsage is a total/used pair returned within UpgradeQuota.

type RemoveIPOptions ¶ added in v0.7.0

type RemoveIPOptions struct {
	Name string `url:"name"`
	IP   string `url:"address"`
}

RemoveIPOptions describes an IP address to remove from a server. The API uses "address" here (distinct from add_ip's "param") — the inconsistency is the API's, not gosh's.

type ResourceGroup ¶ added in v0.7.0

type ResourceGroup struct {
	ClientID  string          `json:"client_id"`
	GroupID   string          `json:"group_id"`
	GroupName string          `json:"group_name"`
	Quotas    []ResourceQuota `json:"quotas"`
}

ResourceGroup represents a per-client resource quota group from list_resources.

type ResourceQuota ¶ added in v0.7.0

type ResourceQuota struct {
	AttributeID    string   `json:"attribute_id"`
	AttributeName  string   `json:"attribute_name"`
	AttributeUnit  string   `json:"attribute_unit"`
	AttributeType  string   `json:"attribute_type"`
	TotalUnits     Number   `json:"total_units"`
	UsedUnits      Number   `json:"used_units"`
	AvailableUnits int      `json:"available_units"`
	Objects        []string `json:"objects"`
}

ResourceQuota is a single quota entry inside a resource group. AvailableUnits is returned as a number (and may be negative when over-quota).

TotalUnits and UsedUnits use Number because the API mixes JSON-string and JSON-number forms within a single response — see the Number type documentation. Same quirk as the parallel /bandwidth/list_resources endpoint addressed in #43.

type ServerState ¶ added in v0.7.0

type ServerState struct {
	State   string  `json:"state"`
	Rescue  bool    `json:"rescue"`
	LastJob LastJob `json:"last_job"`
}

ServerState is the runtime state of a server.

type SetPrimaryIPOptions ¶ added in v0.7.0

type SetPrimaryIPOptions struct {
	Name string `url:"name"`
	IP   string `url:"address"`
}

SetPrimaryIPOptions describes the new primary IP for a server. Uses "address" like remove_ip.

type SetPrimaryIPResponse ¶ added in v0.7.0

type SetPrimaryIPResponse struct {
	Return struct {
		IPAddr string `json:"ip_addr"`
	} `json:"return"`
	models.APIResponse
}

SetPrimaryIPResponse represents the synchronous response from set_primary_ip.

type UpdateRequest ¶

type UpdateRequest struct {
	Name  string `json:"name"`
	Label string `json:"label"`
}

UpdateRequest represents a request to update a Server.

type UpdateResponse ¶

type UpdateResponse struct {
	models.APIResponse
}

UpdateResponse represents a result of a update Server call.

type UpgradeComponentsRequest ¶ added in v0.7.0

type UpgradeComponentsRequest struct {
	Name  string `json:"name"`
	Cores int    `json:"upgrade[cores],omitempty"`
	// RAM is the new total RAM amount in GB, expressed as a
	// string per the API's expectation (e.g. "8" or "16").
	RAM string `json:"upgrade[ram],omitempty"`
	// Disk maps each disk's label (the device name as the
	// platform sees it) to the new total size in GB. The
	// label varies by hypervisor / disk attachment type — Xen
	// surfaces "xvda1" / "xvdb1", virtio surfaces "vda" /
	// "vdb", SCSI / SATA surface "sda" / "scsi0", etc.
	//
	// **Don't hardcode a label.** The right value differs per
	// server. Discover dynamically by reading server.Get's
	// Partitions field — each Partition has a Name (the label
	// the upgrade endpoint expects).
	//
	// API expectations confirmed by live probing:
	//   - Passing a scalar: rejected with
	//     "Please specify an array of disk upgrades."
	//   - Passing array indexed by 0/1/...: rejected with
	//     "Please specify a valid disk label." (the index has
	//     to be a real device name, not a position number).
	//   - Correct: keyed by the actual disk label, e.g.
	//     `map[string]int{"xvda1": 80}` for Xen,
	//     `map[string]int{"scsi0": 80}` for SCSI.
	//
	// The public docs example shows `upgrade[disk][0]=10` but
	// the description text reveals the real form:
	// `upgrade[disk][xvda1]=10` — the index is a device name.
	Disk map[string]int `json:"upgrade[disk],omitempty"`
}

UpgradeComponentsRequest configures a hardware-component upgrade on a server via /server/upgrade.json. At least one of Cores / RAM / Disk should be set; passing zero / empty for all is a no-op.

Disk is the upgrade path most consumers actually want — VPS products commonly grow disk independently of their plan, where Cores/RAM are tied to the product code. CCS products reject component upgrades entirely (use the Upgrade method against /server/upgrade_plan.json for CCS resizing instead).

type UpgradeComponentsResponse ¶ added in v0.7.0

type UpgradeComponentsResponse struct {
	Return struct {
		models.Job `json:"job"`
		Cores      bool `json:"cores"`
		RAM        bool `json:"ram"`
		Disk       bool `json:"disk"`
	} `json:"return"`
	models.APIResponse
}

UpgradeComponentsResponse represents a result of an /server/upgrade.json call. Returns a scheduler job plus per-component bool flags indicating which upgrades were accepted (true) versus rejected (false / missing).

type UpgradeQuota ¶ added in v0.7.0

type UpgradeQuota struct {
	RAM   QuotaUsage `json:"ram"`
	Disk  QuotaUsage `json:"disk"`
	Cores QuotaUsage `json:"cores"`
}

UpgradeQuota is the overall quota / usage block from list_upgrades.

type UpgradeRequest ¶

type UpgradeRequest struct {
	Name string `json:"name"`
	Plan string `json:"plan"`
}

UpgradeRequest represents a request to upgrade a Server's plan (product code). Wraps /server/upgrade_plan.json — note the historical method-name / endpoint-name mismatch.

type UpgradeResponse ¶

type UpgradeResponse struct {
	models.APIResponse
}

UpgradeResponse represents a result of a upgrade Server call.

type Upgrades ¶ added in v0.7.0

type Upgrades struct {
	Quota     UpgradeQuota                  `json:"quota"`
	ExtraDisk ExtraDiskOption               `json:"extra-disk"`
	Disk      map[string]DiskUpgradeOptions `json:"disk"`
}

Upgrades is the upgrade-availability information for a server. The Disk map is keyed by disk slot identifier (e.g. "scsi0").