hypeman

package module
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Jan 20, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

README

Hypeman Go API Library

Go Reference

The Hypeman Go library provides convenient access to the Hypeman REST API from applications written in Go.

It is generated with Stainless.

Installation

import (
	"github.com/kernel/hypeman-go" // imported as hypeman
)

Or to pin the version:

go get -u 'github.com/kernel/[email protected]'

Requirements

This library requires Go 1.22+.

Usage

The full API of this library can be found in api.md.

package main

import (
	"context"
	"fmt"

	"github.com/kernel/hypeman-go"
	"github.com/kernel/hypeman-go/option"
)

func main() {
	client := hypeman.NewClient(
		option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("HYPEMAN_API_KEY")
	)
	response, err := client.Health.Check(context.TODO())
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Status)
}
Request fields

The hypeman library uses the omitzero semantics from the Go 1.24+ encoding/json release for request fields.

Required primitive fields (int64, string, etc.) feature the tag `json:"...,required"`. These fields are always serialized, even their zero values.

Optional primitive types are wrapped in a param.Opt[T]. These fields can be set with the provided constructors, hypeman.String(string), hypeman.Int(int64), etc.

Any param.Opt[T], map, slice, struct or string enum uses the tag `json:"...,omitzero"`. Its zero value is considered omitted.

The param.IsOmitted(any) function can confirm the presence of any omitzero field.

p := hypeman.ExampleParams{
	ID:   "id_xxx",              // required property
	Name: hypeman.String("..."), // optional property

	Point: hypeman.Point{
		X: 0,              // required field will serialize as 0
		Y: hypeman.Int(1), // optional field will serialize as 1
		// ... omitted non-required fields will not be serialized
	},

	Origin: hypeman.Origin{}, // the zero value of [Origin] is considered omitted
}

To send null instead of a param.Opt[T], use param.Null[T](). To send null instead of a struct T, use param.NullStruct[T]().

p.Name = param.Null[string]()       // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

Request structs contain a .SetExtraFields(map[string]any) method which can send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching key. For security reasons, only use SetExtraFields with trusted data.

To send a custom value instead of a struct, use param.Override[T](value).

// In cases where the API specifies a given type,
// but you want to send something else, use [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Send a number instead of an object
custom := param.Override[hypeman.FooParams](12)
Request unions

Unions are represented as a struct with fields prefixed by "Of" for each of its variants, only one field can be non-zero. The non-zero field will be serialized.

Sub-properties of the union can be accessed via methods on the union struct. These methods return a mutable pointer to the underlying data, if present.

// Only one field can be non-zero, use param.IsOmitted() to check if a field is set
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline`
	OfDog *Dog `json:",omitzero,inline`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", Zip: 0},
		},
	},
}

// Mutating a field
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}
Response objects

All fields in response structs are ordinary value types (not pointers or wrappers). Response structs also include a special JSON field containing metadata about each property.

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owner       respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

To handle optional data, use the .Valid() method on the JSON field. .Valid() returns true if a field is not null, not present, or couldn't be marshaled.

If .Valid() is false, the corresponding field will simply be its zero value.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Accessing regular fields

res.Owners // 1
res.Name   // ""
res.Age    // 0

// Optional field checks

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// Raw JSON values

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

These .JSON structs also include an ExtraFields map containing any properties in the json response that were not specified in the struct. This can be useful for API features not yet present in the SDK.

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()
Response Unions

In responses, unions are represented by a flattened struct containing all possible fields from each of the object variants. To convert it to a variant use the .AsFooVariant() method or the .AsAny() method if present.

If a response value union contains primitive values, primitive fields will be alongside the properties but prefixed with Of and feature the tag json:"...,inline".

type AnimalUnion struct {
	// From variants [Dog], [Cat]
	Owner Person `json:"owner"`
	// From variant [Dog]
	DogBreed string `json:"dog_breed"`
	// From variant [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// If animal variant
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Switch on the variant
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}
RequestOptions

This library uses the functional options pattern. Functions defined in the option package return a RequestOption, which is a closure that mutates a RequestConfig. These options can be supplied to the client or at individual requests. For example:

client := hypeman.NewClient(
	// Adds a header to every request made by the client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Health.Check(context.TODO(), ...,
	// Override the header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Add an undocumented field to the request body, using sjson syntax
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

The request option option.WithDebugLog(nil) may be helpful while debugging.

See the full list of request options.

Pagination

This library provides some conveniences for working with paginated list endpoints.

You can use .ListAutoPaging() methods to iterate through items across all pages:

Or you can use simple .List() methods to fetch a single page and receive a standard response object with additional helper methods like .GetNextPage(), e.g.:

Errors

When the API returns a non-success status code, we return an error with type *hypeman.Error. This contains the StatusCode, *http.Request, and *http.Response values of the request, as well as the JSON of the error body (much like other response objects in the SDK).

To handle errors, we recommend that you use the errors.As pattern:

_, err := client.Health.Check(context.TODO())
if err != nil {
	var apierr *hypeman.Error
	if errors.As(err, &apierr) {
		println(string(apierr.DumpRequest(true)))  // Prints the serialized HTTP request
		println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response
	}
	panic(err.Error()) // GET "/health": 400 Bad Request { ... }
}

When other errors occur, they are returned unwrapped; for example, if HTTP transport fails, you might receive *url.Error wrapping *net.OpError.

Timeouts

Requests do not time out by default; use context to configure a timeout for a request lifecycle.

Note that if a request is retried, the context timeout does not start over. To set a per-retry timeout, use option.WithRequestTimeout().

// This sets the timeout for the request, including all the retries.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
client.Health.Check(
	ctx,
	// This sets the per-retry timeout
	option.WithRequestTimeout(20*time.Second),
)
File uploads

Request parameters that correspond to file uploads in multipart requests are typed as io.Reader. The contents of the io.Reader will by default be sent as a multipart form part with the file name of "anonymous_file" and content-type of "application/octet-stream".

The file name and content-type can be customized by implementing Name() string or ContentType() string on the run-time type of io.Reader. Note that os.File implements Name() string, so a file returned by os.Open will be sent with the file name on disk.

We also provide a helper hypeman.File(reader io.Reader, filename string, contentType string) which can be used to wrap any io.Reader with the appropriate file name and content type.

// A file from the file system
file, err := os.Open("/path/to/file")
hypeman.BuildNewParams{
	Source: file,
}

// A file from a string
hypeman.BuildNewParams{
	Source: strings.NewReader("my file contents"),
}

// With a custom filename and contentType
hypeman.BuildNewParams{
	Source: hypeman.File(strings.NewReader(`{"hello": "foo"}`), "file.go", "application/json"),
}
Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff. We retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors.

You can use the WithMaxRetries option to configure or disable this:

// Configure the default for all requests:
client := hypeman.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Override per-request:
client.Health.Check(context.TODO(), option.WithMaxRetries(5))
Accessing raw response data (e.g. response headers)

You can access the raw HTTP response data by using the option.WithResponseInto() request option. This is useful when you need to examine response headers, status codes, or other details.

// Create a variable to store the HTTP response
var response *http.Response
response, err := client.Health.Check(context.TODO(), option.WithResponseInto(&response))
if err != nil {
	// handle error
}
fmt.Printf("%+v\n", response)

fmt.Printf("Status Code: %d\n", response.StatusCode)
fmt.Printf("Headers: %+#v\n", response.Header)
Making custom/undocumented requests

This library is typed for convenient access to the documented API. If you need to access undocumented endpoints, params, or response properties, the library can still be used.

Undocumented endpoints

To make requests to undocumented endpoints, you can use client.Get, client.Post, and other HTTP verbs. RequestOptions on the client, such as retries, will be respected when making these requests.

var (
    // params can be an io.Reader, a []byte, an encoding/json serializable object,
    // or a "…Params" struct defined in this library.
    params map[string]any

    // result can be an []byte, *http.Response, a encoding/json deserializable object,
    // or a model defined in this library.
    result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
    …
}
Undocumented request params

To make requests using undocumented parameters, you may use either the option.WithQuerySet() or the option.WithJSONSet() methods.

params := FooNewParams{
    ID:   "id_xxxx",
    Data: FooNewParamsData{
        FirstName: hypeman.String("John"),
    },
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))
Undocumented response properties

To access undocumented response properties, you may either access the raw JSON of the response as a string with result.JSON.RawJSON(), or get the raw JSON of a particular field on the result with result.JSON.Foo.Raw().

Any fields that are not present on the response struct will be saved and can be accessed by result.JSON.ExtraFields() which returns the extra fields as a map[string]Field.

Middleware

We provide option.WithMiddleware which applies the given middleware to requests.

func Logger(req *http.Request, next option.MiddlewareNext) (res *http.Response, err error) {
	// Before the request
	start := time.Now()
	LogReq(req)

	// Forward the request to the next handler
	res, err = next(req)

	// Handle stuff after the request
	end := time.Now()
	LogRes(res, err, start - end)

    return res, err
}

client := hypeman.NewClient(
	option.WithMiddleware(Logger),
)

When multiple middlewares are provided as variadic arguments, the middlewares are applied left to right. If option.WithMiddleware is given multiple times, for example first in the client then the method, the middleware in the client will run first and the middleware given in the method will run next.

You may also replace the default http.Client with option.WithHTTPClient(client). Only one http client is accepted (this overwrites any previous client) and receives requests after any middleware has been applied.

Semantic versioning

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

  1. Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals.)
  2. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open an issue with questions, bugs, or suggestions.

Development

Testing Preview Branches

When developing features in the main hypeman repo, Stainless automatically creates preview branches in stainless-sdks/hypeman-go with your API changes. You can check out these branches locally to test the SDK changes:

# Checkout preview/<branch> (e.g., if working on "devices" branch in hypeman)
./scripts/checkout-preview devices

# Checkout an exact branch name
./scripts/checkout-preview -b main
./scripts/checkout-preview -b preview/my-feature

The script automatically adds the stainless remote if it doesn't exist.

Contributing

See the contributing documentation.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bool 

func Bool(b bool) param.Opt[bool]

func BoolPtr 

func BoolPtr(v bool) *bool

func DefaultClientOptions 

func DefaultClientOptions() []option.RequestOption

DefaultClientOptions read from the environment (HYPEMAN_API_KEY, HYPEMAN_BASE_URL). This should be used to initialize new clients.

func File 

func File(rdr io.Reader, filename string, contentType string) file

func Float 

func Float(f float64) param.Opt[float64]

func FloatPtr 

func FloatPtr(v float64) *float64

func Int 

func Int(i int64) param.Opt[int64]

func IntPtr 

func IntPtr(v int64) *int64

func Opt 

func Opt[T comparable](v T) param.Opt[T]

func Ptr 

func Ptr[T any](v T) *T

func String 

func String(s string) param.Opt[string]

func StringPtr 

func StringPtr(v string) *string

func Time 

func Time(t time.Time) param.Opt[time.Time]

func TimePtr 

func TimePtr(v time.Time) *time.Time

Types

type AvailableDevice 

type AvailableDevice struct {
	// PCI device ID (hex)
	DeviceID string `json:"device_id,required"`
	// IOMMU group number
	IommuGroup int64 `json:"iommu_group,required"`
	// PCI address
	PciAddress string `json:"pci_address,required"`
	// PCI vendor ID (hex)
	VendorID string `json:"vendor_id,required"`
	// Currently bound driver (null if none)
	CurrentDriver string `json:"current_driver,nullable"`
	// Human-readable device name
	DeviceName string `json:"device_name"`
	// Human-readable vendor name
	VendorName string `json:"vendor_name"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		DeviceID      respjson.Field
		IommuGroup    respjson.Field
		PciAddress    respjson.Field
		VendorID      respjson.Field
		CurrentDriver respjson.Field
		DeviceName    respjson.Field
		VendorName    respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (AvailableDevice) RawJSON 

func (r AvailableDevice) RawJSON() string

Returns the unmodified JSON received from the API

func (*AvailableDevice) UnmarshalJSON 

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

type Build added in v0.9.3 

type Build struct {
	// Build job identifier
	ID string `json:"id,required"`
	// Build creation timestamp
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// Build job status
	//
	// Any of "queued", "building", "pushing", "ready", "failed", "cancelled".
	Status BuildStatus `json:"status,required"`
	// Build completion timestamp
	CompletedAt time.Time `json:"completed_at,nullable" format:"date-time"`
	// Build duration in milliseconds
	DurationMs int64 `json:"duration_ms,nullable"`
	// Error message (only when status is failed)
	Error string `json:"error,nullable"`
	// Digest of built image (only when status is ready)
	ImageDigest string `json:"image_digest,nullable"`
	// Full image reference (only when status is ready)
	ImageRef   string          `json:"image_ref,nullable"`
	Provenance BuildProvenance `json:"provenance"`
	// Position in build queue (only when status is queued)
	QueuePosition int64 `json:"queue_position,nullable"`
	// Build start timestamp
	StartedAt time.Time `json:"started_at,nullable" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID            respjson.Field
		CreatedAt     respjson.Field
		Status        respjson.Field
		CompletedAt   respjson.Field
		DurationMs    respjson.Field
		Error         respjson.Field
		ImageDigest   respjson.Field
		ImageRef      respjson.Field
		Provenance    respjson.Field
		QueuePosition respjson.Field
		StartedAt     respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Build) RawJSON added in v0.9.3 

func (r Build) RawJSON() string

Returns the unmodified JSON received from the API

func (*Build) UnmarshalJSON added in v0.9.3 

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

type BuildEvent added in v0.9.3 

type BuildEvent struct {
	// Event timestamp
	Timestamp time.Time `json:"timestamp,required" format:"date-time"`
	// Event type
	//
	// Any of "log", "status", "heartbeat".
	Type BuildEventType `json:"type,required"`
	// Log line content (only for type=log)
	Content string `json:"content"`
	// New build status (only for type=status)
	//
	// Any of "queued", "building", "pushing", "ready", "failed", "cancelled".
	Status BuildStatus `json:"status"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Timestamp   respjson.Field
		Type        respjson.Field
		Content     respjson.Field
		Status      respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (BuildEvent) RawJSON added in v0.9.3 

func (r BuildEvent) RawJSON() string

Returns the unmodified JSON received from the API

func (*BuildEvent) UnmarshalJSON added in v0.9.3 

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

type BuildEventType added in v0.9.3 

type BuildEventType string

Event type 

const (
	BuildEventTypeLog       BuildEventType = "log"
	BuildEventTypeStatus    BuildEventType = "status"
	BuildEventTypeHeartbeat BuildEventType = "heartbeat"
)

type BuildEventsParams added in v0.9.3 

type BuildEventsParams struct {
	// Continue streaming new events after initial output
	Follow param.Opt[bool] `query:"follow,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (BuildEventsParams) URLQuery added in v0.9.3 

func (r BuildEventsParams) URLQuery() (v url.Values, err error)

URLQuery serializes BuildEventsParams's query parameters as `url.Values`.

type BuildNewParams added in v0.9.3 

type BuildNewParams struct {
	// Source tarball (tar.gz) containing application code and optionally a Dockerfile
	Source io.Reader `json:"source,omitzero,required" format:"binary"`
	// Optional pinned base image digest
	BaseImageDigest param.Opt[string] `json:"base_image_digest,omitzero"`
	// Tenant-specific cache key prefix
	CacheScope param.Opt[string] `json:"cache_scope,omitzero"`
	// Dockerfile content. Required if not included in the source tarball.
	Dockerfile param.Opt[string] `json:"dockerfile,omitzero"`
	// JSON array of secret references to inject during build. Each object has "id"
	// (required) for use with --mount=type=secret,id=... Example: [{"id":
	// "npm_token"}, {"id": "github_token"}]
	Secrets param.Opt[string] `json:"secrets,omitzero"`
	// Build timeout (default 600)
	TimeoutSeconds param.Opt[int64] `json:"timeout_seconds,omitzero"`
	// contains filtered or unexported fields
}

func (BuildNewParams) MarshalMultipart added in v0.9.3 

func (r BuildNewParams) MarshalMultipart() (data []byte, contentType string, err error)

type BuildProvenance added in v0.9.3 

type BuildProvenance struct {
	// Pinned base image digest used
	BaseImageDigest string `json:"base_image_digest"`
	// BuildKit version used
	BuildkitVersion string `json:"buildkit_version"`
	// Map of lockfile names to SHA256 hashes
	LockfileHashes map[string]string `json:"lockfile_hashes"`
	// SHA256 hash of source tarball
	SourceHash string `json:"source_hash"`
	// Build completion timestamp
	Timestamp time.Time `json:"timestamp" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		BaseImageDigest respjson.Field
		BuildkitVersion respjson.Field
		LockfileHashes  respjson.Field
		SourceHash      respjson.Field
		Timestamp       respjson.Field
		ExtraFields     map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (BuildProvenance) RawJSON added in v0.9.3 

func (r BuildProvenance) RawJSON() string

Returns the unmodified JSON received from the API

func (*BuildProvenance) UnmarshalJSON added in v0.9.3 

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

type BuildService added in v0.9.3 

type BuildService struct {
	Options []option.RequestOption
}

BuildService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewBuildService method instead.

func NewBuildService added in v0.9.3 

func NewBuildService(opts ...option.RequestOption) (r BuildService)

NewBuildService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*BuildService) Cancel added in v0.9.3 

func (r *BuildService) Cancel(ctx context.Context, id string, opts ...option.RequestOption) (err error)

Cancel build

func (*BuildService) EventsStreaming added in v0.9.3 

func (r *BuildService) EventsStreaming(ctx context.Context, id string, query BuildEventsParams, opts ...option.RequestOption) (stream *ssestream.Stream[BuildEvent])

Streams build events as Server-Sent Events. Events include:

- `log`: Build log lines with timestamp and content - `status`: Build status changes (queued→building→pushing→ready/failed) - `heartbeat`: Keep-alive events sent every 30s to prevent connection timeouts

Returns existing logs as events, then continues streaming if follow=true.

func (*BuildService) Get added in v0.9.3 

func (r *BuildService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Build, err error)

Get build details

func (*BuildService) List added in v0.9.3 

func (r *BuildService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Build, err error)

List builds

func (*BuildService) New added in v0.9.3 

func (r *BuildService) New(ctx context.Context, body BuildNewParams, opts ...option.RequestOption) (res *Build, err error)

Creates a new build job. Source code should be uploaded as a tar.gz archive in the multipart form data.

type BuildStatus added in v0.9.3 

type BuildStatus string

Build job status 

const (
	BuildStatusQueued    BuildStatus = "queued"
	BuildStatusBuilding  BuildStatus = "building"
	BuildStatusPushing   BuildStatus = "pushing"
	BuildStatusReady     BuildStatus = "ready"
	BuildStatusFailed    BuildStatus = "failed"
	BuildStatusCancelled BuildStatus = "cancelled"
)

type Client 

type Client struct {
	Options   []option.RequestOption
	Health    HealthService
	Images    ImageService
	Instances InstanceService
	Volumes   VolumeService
	Devices   DeviceService
	Ingresses IngressService
	Resources ResourceService
	Builds    BuildService
}

Client creates a struct with services and top level methods that help with interacting with the hypeman API. You should not instantiate this client directly, and instead use the NewClient method instead.

func NewClient 

func NewClient(opts ...option.RequestOption) (r Client)

NewClient generates a new client with the default option read from the environment (HYPEMAN_API_KEY, HYPEMAN_BASE_URL). The option passed in as arguments are applied after these default arguments, and all option will be passed down to the services and requests that this client makes.

func (*Client) Delete 

func (r *Client) Delete(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error

Delete makes a DELETE request with the given URL, params, and optionally deserializes to a response. See [Execute] documentation on the params and response.

func (*Client) Execute 

func (r *Client) Execute(ctx context.Context, method string, path string, params any, res any, opts ...option.RequestOption) error

Execute makes a request with the given context, method, URL, request params, response, and request options. This is useful for hitting undocumented endpoints while retaining the base URL, auth, retries, and other options from the client.

If a byte slice or an io.Reader is supplied to params, it will be used as-is for the request body.

The params is by default serialized into the body using encoding/json. If your type implements a MarshalJSON function, it will be used instead to serialize the request. If a URLQuery method is implemented, the returned url.Values will be used as query strings to the url.

If your params struct uses param.Field, you must provide either [MarshalJSON], [URLQuery], and/or [MarshalForm] functions. It is undefined behavior to use a struct uses param.Field without specifying how it is serialized.

Any "…Params" object defined in this library can be used as the request argument. Note that 'path' arguments will not be forwarded into the url.

The response body will be deserialized into the res variable, depending on its type:

  • A pointer to a *http.Response is populated by the raw response.
  • A pointer to a byte array will be populated with the contents of the request body.
  • A pointer to any other type uses this library's default JSON decoding, which respects UnmarshalJSON if it is defined on the type.
  • A nil value will not read the response body.

For even greater flexibility, see option.WithResponseInto and option.WithResponseBodyInto.

func (*Client) Get 

func (r *Client) Get(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error

Get makes a GET request with the given URL, params, and optionally deserializes to a response. See [Execute] documentation on the params and response.

func (*Client) Patch 

func (r *Client) Patch(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error

Patch makes a PATCH request with the given URL, params, and optionally deserializes to a response. See [Execute] documentation on the params and response.

func (*Client) Post 

func (r *Client) Post(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error

Post makes a POST request with the given URL, params, and optionally deserializes to a response. See [Execute] documentation on the params and response.

func (*Client) Put 

func (r *Client) Put(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error

Put makes a PUT request with the given URL, params, and optionally deserializes to a response. See [Execute] documentation on the params and response.

type Device 

type Device struct {
	// Auto-generated unique identifier (CUID2 format)
	ID string `json:"id,required"`
	// Whether the device is currently bound to the vfio-pci driver, which is required
	// for VM passthrough.
	//
	//   - true: Device is bound to vfio-pci and ready for (or currently in use by) a VM.
	//     The device's native driver has been unloaded.
	//   - false: Device is using its native driver (e.g., nvidia) or no driver. Hypeman
	//     will automatically bind to vfio-pci when attaching to an instance.
	BoundToVfio bool `json:"bound_to_vfio,required"`
	// Registration timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// PCI device ID (hex)
	DeviceID string `json:"device_id,required"`
	// IOMMU group number
	IommuGroup int64 `json:"iommu_group,required"`
	// PCI address
	PciAddress string `json:"pci_address,required"`
	// Type of PCI device
	//
	// Any of "gpu", "pci".
	Type DeviceType `json:"type,required"`
	// PCI vendor ID (hex)
	VendorID string `json:"vendor_id,required"`
	// Instance ID if attached
	AttachedTo string `json:"attached_to,nullable"`
	// Device name (user-provided or auto-generated from PCI address)
	Name string `json:"name"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		BoundToVfio respjson.Field
		CreatedAt   respjson.Field
		DeviceID    respjson.Field
		IommuGroup  respjson.Field
		PciAddress  respjson.Field
		Type        respjson.Field
		VendorID    respjson.Field
		AttachedTo  respjson.Field
		Name        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Device) RawJSON 

func (r Device) RawJSON() string

Returns the unmodified JSON received from the API

func (*Device) UnmarshalJSON 

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

type DeviceNewParams 

type DeviceNewParams struct {
	// PCI address of the device (required, e.g., "0000:a2:00.0")
	PciAddress string `json:"pci_address,required"`
	// Optional globally unique device name. If not provided, a name is auto-generated
	// from the PCI address (e.g., "pci-0000-a2-00-0")
	Name param.Opt[string] `json:"name,omitzero"`
	// contains filtered or unexported fields
}

func (DeviceNewParams) MarshalJSON 

func (r DeviceNewParams) MarshalJSON() (data []byte, err error)

func (*DeviceNewParams) UnmarshalJSON 

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

type DeviceService 

type DeviceService struct {
	Options []option.RequestOption
}

DeviceService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewDeviceService method instead.

func NewDeviceService 

func NewDeviceService(opts ...option.RequestOption) (r DeviceService)

NewDeviceService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*DeviceService) Delete 

func (r *DeviceService) Delete(ctx context.Context, id string, opts ...option.RequestOption) (err error)

Unregister device

func (*DeviceService) Get 

func (r *DeviceService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Device, err error)

Get device details

func (*DeviceService) List 

func (r *DeviceService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Device, err error)

List registered devices

func (*DeviceService) ListAvailable 

func (r *DeviceService) ListAvailable(ctx context.Context, opts ...option.RequestOption) (res *[]AvailableDevice, err error)

Discover passthrough-capable devices on host

func (*DeviceService) New 

func (r *DeviceService) New(ctx context.Context, body DeviceNewParams, opts ...option.RequestOption) (res *Device, err error)

Register a device for passthrough

type DeviceType 

type DeviceType string

Type of PCI device 

const (
	DeviceTypeGPU DeviceType = "gpu"
	DeviceTypePci DeviceType = "pci"
)

type DiskBreakdown added in v0.9.3 

type DiskBreakdown struct {
	// Disk used by exported rootfs images
	ImagesBytes int64 `json:"images_bytes"`
	// Disk used by OCI layer cache (shared blobs)
	OciCacheBytes int64 `json:"oci_cache_bytes"`
	// Disk used by instance overlays (rootfs + volume overlays)
	OverlaysBytes int64 `json:"overlays_bytes"`
	// Disk used by volumes
	VolumesBytes int64 `json:"volumes_bytes"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ImagesBytes   respjson.Field
		OciCacheBytes respjson.Field
		OverlaysBytes respjson.Field
		VolumesBytes  respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (DiskBreakdown) RawJSON added in v0.9.3 

func (r DiskBreakdown) RawJSON() string

Returns the unmodified JSON received from the API

func (*DiskBreakdown) UnmarshalJSON added in v0.9.3 

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

type Error 

type Error = apierror.Error

type GPUProfile added in v0.9.3 

type GPUProfile struct {
	// Number of instances that can be created with this profile
	Available int64 `json:"available,required"`
	// Frame buffer size in MB
	FramebufferMB int64 `json:"framebuffer_mb,required"`
	// Profile name (user-facing)
	Name string `json:"name,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Available     respjson.Field
		FramebufferMB respjson.Field
		Name          respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

Available vGPU profile

func (GPUProfile) RawJSON added in v0.9.3 

func (r GPUProfile) RawJSON() string

Returns the unmodified JSON received from the API

func (*GPUProfile) UnmarshalJSON added in v0.9.3 

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

type GPUResourceStatus added in v0.9.3 

type GPUResourceStatus struct {
	// GPU mode (vgpu for SR-IOV/mdev, passthrough for whole GPU)
	//
	// Any of "vgpu", "passthrough".
	Mode GPUResourceStatusMode `json:"mode,required"`
	// Total slots (VFs for vGPU, physical GPUs for passthrough)
	TotalSlots int64 `json:"total_slots,required"`
	// Slots currently in use
	UsedSlots int64 `json:"used_slots,required"`
	// Physical GPUs (only in passthrough mode)
	Devices []PassthroughDevice `json:"devices"`
	// Available vGPU profiles (only in vGPU mode)
	Profiles []GPUProfile `json:"profiles"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Mode        respjson.Field
		TotalSlots  respjson.Field
		UsedSlots   respjson.Field
		Devices     respjson.Field
		Profiles    respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

GPU resource status. Null if no GPUs available.

func (GPUResourceStatus) RawJSON added in v0.9.3 

func (r GPUResourceStatus) RawJSON() string

Returns the unmodified JSON received from the API

func (*GPUResourceStatus) UnmarshalJSON added in v0.9.3 

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

type GPUResourceStatusMode added in v0.9.3 

type GPUResourceStatusMode string

GPU mode (vgpu for SR-IOV/mdev, passthrough for whole GPU) 

const (
	GPUResourceStatusModeVgpu        GPUResourceStatusMode = "vgpu"
	GPUResourceStatusModePassthrough GPUResourceStatusMode = "passthrough"
)

type HealthCheckResponse 

type HealthCheckResponse struct {
	// Any of "ok".
	Status HealthCheckResponseStatus `json:"status,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Status      respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (HealthCheckResponse) RawJSON 

func (r HealthCheckResponse) RawJSON() string

Returns the unmodified JSON received from the API

func (*HealthCheckResponse) UnmarshalJSON 

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

type HealthCheckResponseStatus 

type HealthCheckResponseStatus string
const (
	HealthCheckResponseStatusOk HealthCheckResponseStatus = "ok"
)

type HealthService 

type HealthService struct {
	Options []option.RequestOption
}

HealthService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewHealthService method instead.

func NewHealthService 

func NewHealthService(opts ...option.RequestOption) (r HealthService)

NewHealthService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*HealthService) Check 

func (r *HealthService) Check(ctx context.Context, opts ...option.RequestOption) (res *HealthCheckResponse, err error)

Health check

type Image 

type Image struct {
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// Resolved manifest digest
	Digest string `json:"digest,required"`
	// Normalized OCI image reference (tag or digest)
	Name string `json:"name,required"`
	// Build status
	//
	// Any of "pending", "pulling", "converting", "ready", "failed".
	Status ImageStatus `json:"status,required"`
	// CMD from container metadata
	Cmd []string `json:"cmd,nullable"`
	// Entrypoint from container metadata
	Entrypoint []string `json:"entrypoint,nullable"`
	// Environment variables from container metadata
	Env map[string]string `json:"env"`
	// Error message if status is failed
	Error string `json:"error,nullable"`
	// Position in build queue (null if not queued)
	QueuePosition int64 `json:"queue_position,nullable"`
	// Disk size in bytes (null until ready)
	SizeBytes int64 `json:"size_bytes,nullable"`
	// Working directory from container metadata
	WorkingDir string `json:"working_dir,nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		CreatedAt     respjson.Field
		Digest        respjson.Field
		Name          respjson.Field
		Status        respjson.Field
		Cmd           respjson.Field
		Entrypoint    respjson.Field
		Env           respjson.Field
		Error         respjson.Field
		QueuePosition respjson.Field
		SizeBytes     respjson.Field
		WorkingDir    respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Image) RawJSON 

func (r Image) RawJSON() string

Returns the unmodified JSON received from the API

func (*Image) UnmarshalJSON 

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

type ImageNewParams 

type ImageNewParams struct {
	// OCI image reference (e.g., docker.io/library/nginx:latest)
	Name string `json:"name,required"`
	// contains filtered or unexported fields
}

func (ImageNewParams) MarshalJSON 

func (r ImageNewParams) MarshalJSON() (data []byte, err error)

func (*ImageNewParams) UnmarshalJSON 

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

type ImageService 

type ImageService struct {
	Options []option.RequestOption
}

ImageService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewImageService method instead.

func NewImageService 

func NewImageService(opts ...option.RequestOption) (r ImageService)

NewImageService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*ImageService) Delete 

func (r *ImageService) Delete(ctx context.Context, name string, opts ...option.RequestOption) (err error)

Delete image

func (*ImageService) Get 

func (r *ImageService) Get(ctx context.Context, name string, opts ...option.RequestOption) (res *Image, err error)

Get image details

func (*ImageService) List 

func (r *ImageService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Image, err error)

List images

func (*ImageService) New 

func (r *ImageService) New(ctx context.Context, body ImageNewParams, opts ...option.RequestOption) (res *Image, err error)

Pull and convert OCI image

type ImageStatus 

type ImageStatus string

Build status 

const (
	ImageStatusPending    ImageStatus = "pending"
	ImageStatusPulling    ImageStatus = "pulling"
	ImageStatusConverting ImageStatus = "converting"
	ImageStatusReady      ImageStatus = "ready"
	ImageStatusFailed     ImageStatus = "failed"
)

type Ingress 

type Ingress struct {
	// Auto-generated unique identifier
	ID string `json:"id,required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// Human-readable name
	Name string `json:"name,required"`
	// Routing rules for this ingress
	Rules []IngressRule `json:"rules,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		CreatedAt   respjson.Field
		Name        respjson.Field
		Rules       respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Ingress) RawJSON 

func (r Ingress) RawJSON() string

Returns the unmodified JSON received from the API

func (*Ingress) UnmarshalJSON 

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

type IngressMatch 

type IngressMatch struct {
	// Hostname to match. Can be:
	//
	// - Literal: "api.example.com" (exact match on Host header)
	// - Pattern: "{instance}.example.com" (dynamic routing based on subdomain)
	//
	// Pattern hostnames use named captures in curly braces (e.g., {instance}, {app})
	// that extract parts of the hostname for routing. The extracted values can be
	// referenced in the target.instance field.
	Hostname string `json:"hostname,required"`
	// Host port to listen on for this rule (default 80)
	Port int64 `json:"port"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Hostname    respjson.Field
		Port        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (IngressMatch) RawJSON 

func (r IngressMatch) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressMatch) ToParam 

func (r IngressMatch) ToParam() IngressMatchParam

ToParam converts this IngressMatch to a IngressMatchParam.

Warning: the fields of the param type will not be present. ToParam should only be used at the last possible moment before sending a request. Test for this with IngressMatchParam.Overrides()

func (*IngressMatch) UnmarshalJSON 

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

type IngressMatchParam 

type IngressMatchParam struct {
	// Hostname to match. Can be:
	//
	// - Literal: "api.example.com" (exact match on Host header)
	// - Pattern: "{instance}.example.com" (dynamic routing based on subdomain)
	//
	// Pattern hostnames use named captures in curly braces (e.g., {instance}, {app})
	// that extract parts of the hostname for routing. The extracted values can be
	// referenced in the target.instance field.
	Hostname string `json:"hostname,required"`
	// Host port to listen on for this rule (default 80)
	Port param.Opt[int64] `json:"port,omitzero"`
	// contains filtered or unexported fields
}

The property Hostname is required.

func (IngressMatchParam) MarshalJSON 

func (r IngressMatchParam) MarshalJSON() (data []byte, err error)

func (*IngressMatchParam) UnmarshalJSON 

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

type IngressNewParams 

type IngressNewParams struct {
	// Human-readable name (lowercase letters, digits, and dashes only; cannot start or
	// end with a dash)
	Name string `json:"name,required"`
	// Routing rules for this ingress
	Rules []IngressRuleParam `json:"rules,omitzero,required"`
	// contains filtered or unexported fields
}

func (IngressNewParams) MarshalJSON 

func (r IngressNewParams) MarshalJSON() (data []byte, err error)

func (*IngressNewParams) UnmarshalJSON 

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

type IngressRule 

type IngressRule struct {
	Match  IngressMatch  `json:"match,required"`
	Target IngressTarget `json:"target,required"`
	// Auto-create HTTP to HTTPS redirect for this hostname (only applies when tls is
	// enabled)
	RedirectHTTP bool `json:"redirect_http"`
	// Enable TLS termination (certificate auto-issued via ACME).
	Tls bool `json:"tls"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Match        respjson.Field
		Target       respjson.Field
		RedirectHTTP respjson.Field
		Tls          respjson.Field
		ExtraFields  map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (IngressRule) RawJSON 

func (r IngressRule) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressRule) ToParam 

func (r IngressRule) ToParam() IngressRuleParam

ToParam converts this IngressRule to a IngressRuleParam.

Warning: the fields of the param type will not be present. ToParam should only be used at the last possible moment before sending a request. Test for this with IngressRuleParam.Overrides()

func (*IngressRule) UnmarshalJSON 

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

type IngressRuleParam 

type IngressRuleParam struct {
	Match  IngressMatchParam  `json:"match,omitzero,required"`
	Target IngressTargetParam `json:"target,omitzero,required"`
	// Auto-create HTTP to HTTPS redirect for this hostname (only applies when tls is
	// enabled)
	RedirectHTTP param.Opt[bool] `json:"redirect_http,omitzero"`
	// Enable TLS termination (certificate auto-issued via ACME).
	Tls param.Opt[bool] `json:"tls,omitzero"`
	// contains filtered or unexported fields
}

The properties Match, Target are required.

func (IngressRuleParam) MarshalJSON 

func (r IngressRuleParam) MarshalJSON() (data []byte, err error)

func (*IngressRuleParam) UnmarshalJSON 

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

type IngressService 

type IngressService struct {
	Options []option.RequestOption
}

IngressService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewIngressService method instead.

func NewIngressService 

func NewIngressService(opts ...option.RequestOption) (r IngressService)

NewIngressService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*IngressService) Delete 

func (r *IngressService) Delete(ctx context.Context, id string, opts ...option.RequestOption) (err error)

Delete ingress

func (*IngressService) Get 

func (r *IngressService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Ingress, err error)

Get ingress details

func (*IngressService) List 

func (r *IngressService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Ingress, err error)

List ingresses

func (*IngressService) New 

func (r *IngressService) New(ctx context.Context, body IngressNewParams, opts ...option.RequestOption) (res *Ingress, err error)

Create ingress

type IngressTarget 

type IngressTarget struct {
	// Target instance name, ID, or capture reference.
	//
	//   - For literal hostnames: Use the instance name or ID directly (e.g., "my-api")
	//   - For pattern hostnames: Reference a capture from the hostname (e.g.,
	//     "{instance}")
	//
	// When using pattern hostnames, the instance is resolved dynamically at request
	// time.
	Instance string `json:"instance,required"`
	// Target port on the instance
	Port int64 `json:"port,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Instance    respjson.Field
		Port        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (IngressTarget) RawJSON 

func (r IngressTarget) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressTarget) ToParam 

func (r IngressTarget) ToParam() IngressTargetParam

ToParam converts this IngressTarget to a IngressTargetParam.

Warning: the fields of the param type will not be present. ToParam should only be used at the last possible moment before sending a request. Test for this with IngressTargetParam.Overrides()

func (*IngressTarget) UnmarshalJSON 

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

type IngressTargetParam 

type IngressTargetParam struct {
	// Target instance name, ID, or capture reference.
	//
	//   - For literal hostnames: Use the instance name or ID directly (e.g., "my-api")
	//   - For pattern hostnames: Reference a capture from the hostname (e.g.,
	//     "{instance}")
	//
	// When using pattern hostnames, the instance is resolved dynamically at request
	// time.
	Instance string `json:"instance,required"`
	// Target port on the instance
	Port int64 `json:"port,required"`
	// contains filtered or unexported fields
}

The properties Instance, Port are required.

func (IngressTargetParam) MarshalJSON 

func (r IngressTargetParam) MarshalJSON() (data []byte, err error)

func (*IngressTargetParam) UnmarshalJSON 

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

type Instance 

type Instance struct {
	// Auto-generated unique identifier (CUID2 format)
	ID string `json:"id,required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// OCI image reference
	Image string `json:"image,required"`
	// Human-readable name
	Name string `json:"name,required"`
	// Instance state:
	//
	// - Created: VMM created but not started (Cloud Hypervisor native)
	// - Running: VM is actively running (Cloud Hypervisor native)
	// - Paused: VM is paused (Cloud Hypervisor native)
	// - Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
	// - Stopped: No VMM running, no snapshot exists
	// - Standby: No VMM running, snapshot exists (can be restored)
	// - Unknown: Failed to determine state (see state_error for details)
	//
	// Any of "Created", "Running", "Paused", "Shutdown", "Stopped", "Standby",
	// "Unknown".
	State InstanceState `json:"state,required"`
	// Disk I/O rate limit (human-readable, e.g., "100MB/s")
	DiskIoBps string `json:"disk_io_bps"`
	// Environment variables
	Env map[string]string `json:"env"`
	// GPU information attached to the instance
	GPU InstanceGPU `json:"gpu"`
	// Whether a snapshot exists for this instance
	HasSnapshot bool `json:"has_snapshot"`
	// Hotplug memory size (human-readable)
	HotplugSize string `json:"hotplug_size"`
	// Hypervisor running this instance
	//
	// Any of "cloud-hypervisor", "qemu".
	Hypervisor InstanceHypervisor `json:"hypervisor"`
	// Network configuration of the instance
	Network InstanceNetwork `json:"network"`
	// Writable overlay disk size (human-readable)
	OverlaySize string `json:"overlay_size"`
	// Base memory size (human-readable)
	Size string `json:"size"`
	// Start timestamp (RFC3339)
	StartedAt time.Time `json:"started_at,nullable" format:"date-time"`
	// Error message if state couldn't be determined (only set when state is Unknown)
	StateError string `json:"state_error,nullable"`
	// Stop timestamp (RFC3339)
	StoppedAt time.Time `json:"stopped_at,nullable" format:"date-time"`
	// Number of virtual CPUs
	Vcpus int64 `json:"vcpus"`
	// Volumes attached to the instance
	Volumes []VolumeMount `json:"volumes"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		CreatedAt   respjson.Field
		Image       respjson.Field
		Name        respjson.Field
		State       respjson.Field
		DiskIoBps   respjson.Field
		Env         respjson.Field
		GPU         respjson.Field
		HasSnapshot respjson.Field
		HotplugSize respjson.Field
		Hypervisor  respjson.Field
		Network     respjson.Field
		OverlaySize respjson.Field
		Size        respjson.Field
		StartedAt   respjson.Field
		StateError  respjson.Field
		StoppedAt   respjson.Field
		Vcpus       respjson.Field
		Volumes     respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Instance) RawJSON 

func (r Instance) RawJSON() string

Returns the unmodified JSON received from the API

func (*Instance) UnmarshalJSON 

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

type InstanceGPU added in v0.9.2 

type InstanceGPU struct {
	// mdev device UUID
	MdevUuid string `json:"mdev_uuid"`
	// vGPU profile name
	Profile string `json:"profile"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		MdevUuid    respjson.Field
		Profile     respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

GPU information attached to the instance

func (InstanceGPU) RawJSON added in v0.9.2 

func (r InstanceGPU) RawJSON() string

Returns the unmodified JSON received from the API

func (*InstanceGPU) UnmarshalJSON added in v0.9.2 

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

type InstanceHypervisor added in v0.9.2 

type InstanceHypervisor string

Hypervisor running this instance 

const (
	InstanceHypervisorCloudHypervisor InstanceHypervisor = "cloud-hypervisor"
	InstanceHypervisorQemu            InstanceHypervisor = "qemu"
)

type InstanceLogsParams 

type InstanceLogsParams struct {
	// Continue streaming new lines after initial output
	Follow param.Opt[bool] `query:"follow,omitzero" json:"-"`
	// Number of lines to return from end
	Tail param.Opt[int64] `query:"tail,omitzero" json:"-"`
	// Log source to stream:
	//
	// - app: Guest application logs (serial console output)
	// - vmm: Cloud Hypervisor VMM logs (hypervisor stdout+stderr)
	// - hypeman: Hypeman operations log (actions taken on this instance)
	//
	// Any of "app", "vmm", "hypeman".
	Source InstanceLogsParamsSource `query:"source,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (InstanceLogsParams) URLQuery 

func (r InstanceLogsParams) URLQuery() (v url.Values, err error)

URLQuery serializes InstanceLogsParams's query parameters as `url.Values`.

type InstanceLogsParamsSource 

type InstanceLogsParamsSource string

Log source to stream:

- app: Guest application logs (serial console output) - vmm: Cloud Hypervisor VMM logs (hypervisor stdout+stderr) - hypeman: Hypeman operations log (actions taken on this instance) 

const (
	InstanceLogsParamsSourceApp     InstanceLogsParamsSource = "app"
	InstanceLogsParamsSourceVmm     InstanceLogsParamsSource = "vmm"
	InstanceLogsParamsSourceHypeman InstanceLogsParamsSource = "hypeman"
)

type InstanceNetwork 

type InstanceNetwork struct {
	// Download bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
	BandwidthDownload string `json:"bandwidth_download"`
	// Upload bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
	BandwidthUpload string `json:"bandwidth_upload"`
	// Whether instance is attached to the default network
	Enabled bool `json:"enabled"`
	// Assigned IP address (null if no network)
	IP string `json:"ip,nullable"`
	// Assigned MAC address (null if no network)
	Mac string `json:"mac,nullable"`
	// Network name (always "default" when enabled)
	Name string `json:"name"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		BandwidthDownload respjson.Field
		BandwidthUpload   respjson.Field
		Enabled           respjson.Field
		IP                respjson.Field
		Mac               respjson.Field
		Name              respjson.Field
		ExtraFields       map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

Network configuration of the instance

func (InstanceNetwork) RawJSON 

func (r InstanceNetwork) RawJSON() string

Returns the unmodified JSON received from the API

func (*InstanceNetwork) UnmarshalJSON 

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

type InstanceNewParams 

type InstanceNewParams struct {
	// OCI image reference
	Image string `json:"image,required"`
	// Human-readable name (lowercase letters, digits, and dashes only; cannot start or
	// end with a dash)
	Name string `json:"name,required"`
	// Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share
	// based on CPU allocation if configured.
	DiskIoBps param.Opt[string] `json:"disk_io_bps,omitzero"`
	// Additional memory for hotplug (human-readable format like "3GB", "1G")
	HotplugSize param.Opt[string] `json:"hotplug_size,omitzero"`
	// Writable overlay disk size (human-readable format like "10GB", "50G")
	OverlaySize param.Opt[string] `json:"overlay_size,omitzero"`
	// Base memory size (human-readable format like "1GB", "512MB", "2G")
	Size param.Opt[string] `json:"size,omitzero"`
	// Number of virtual CPUs
	Vcpus param.Opt[int64] `json:"vcpus,omitzero"`
	// Device IDs or names to attach for GPU/PCI passthrough
	Devices []string `json:"devices,omitzero"`
	// Environment variables
	Env map[string]string `json:"env,omitzero"`
	// GPU configuration for the instance
	GPU InstanceNewParamsGPU `json:"gpu,omitzero"`
	// Hypervisor to use for this instance. Defaults to server configuration.
	//
	// Any of "cloud-hypervisor", "qemu".
	Hypervisor InstanceNewParamsHypervisor `json:"hypervisor,omitzero"`
	// Network configuration for the instance
	Network InstanceNewParamsNetwork `json:"network,omitzero"`
	// Volumes to attach to the instance at creation time
	Volumes []VolumeMountParam `json:"volumes,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceNewParams) MarshalJSON 

func (r InstanceNewParams) MarshalJSON() (data []byte, err error)

func (*InstanceNewParams) UnmarshalJSON 

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

type InstanceNewParamsGPU added in v0.9.2 

type InstanceNewParamsGPU struct {
	// vGPU profile name (e.g., "L40S-1Q"). Only used in vGPU mode.
	Profile param.Opt[string] `json:"profile,omitzero"`
	// contains filtered or unexported fields
}

GPU configuration for the instance

func (InstanceNewParamsGPU) MarshalJSON added in v0.9.2 

func (r InstanceNewParamsGPU) MarshalJSON() (data []byte, err error)

func (*InstanceNewParamsGPU) UnmarshalJSON added in v0.9.2 

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

type InstanceNewParamsHypervisor added in v0.9.2 

type InstanceNewParamsHypervisor string

Hypervisor to use for this instance. Defaults to server configuration. 

const (
	InstanceNewParamsHypervisorCloudHypervisor InstanceNewParamsHypervisor = "cloud-hypervisor"
	InstanceNewParamsHypervisorQemu            InstanceNewParamsHypervisor = "qemu"
)

type InstanceNewParamsNetwork 

type InstanceNewParamsNetwork struct {
	// Download bandwidth limit (external→VM, e.g., "1Gbps", "125MB/s"). Defaults to
	// proportional share based on CPU allocation.
	BandwidthDownload param.Opt[string] `json:"bandwidth_download,omitzero"`
	// Upload bandwidth limit (VM→external, e.g., "1Gbps", "125MB/s"). Defaults to
	// proportional share based on CPU allocation.
	BandwidthUpload param.Opt[string] `json:"bandwidth_upload,omitzero"`
	// Whether to attach instance to the default network
	Enabled param.Opt[bool] `json:"enabled,omitzero"`
	// contains filtered or unexported fields
}

Network configuration for the instance

func (InstanceNewParamsNetwork) MarshalJSON 

func (r InstanceNewParamsNetwork) MarshalJSON() (data []byte, err error)

func (*InstanceNewParamsNetwork) UnmarshalJSON 

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

type InstanceService 

type InstanceService struct {
	Options []option.RequestOption
	Volumes InstanceVolumeService
}

InstanceService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewInstanceService method instead.

func NewInstanceService 

func NewInstanceService(opts ...option.RequestOption) (r InstanceService)

NewInstanceService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*InstanceService) Delete 

func (r *InstanceService) Delete(ctx context.Context, id string, opts ...option.RequestOption) (err error)

Stop and delete instance

func (*InstanceService) Get 

func (r *InstanceService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error)

Get instance details

func (*InstanceService) List 

func (r *InstanceService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Instance, err error)

List instances

func (*InstanceService) LogsStreaming 

func (r *InstanceService) LogsStreaming(ctx context.Context, id string, query InstanceLogsParams, opts ...option.RequestOption) (stream *ssestream.Stream[string])

Streams instance logs as Server-Sent Events. Use the `source` parameter to select which log to stream:

- `app` (default): Guest application logs (serial console) - `vmm`: Cloud Hypervisor VMM logs - `hypeman`: Hypeman operations log

Returns the last N lines (controlled by `tail` parameter), then optionally continues streaming new lines if `follow=true`.

func (*InstanceService) New 

func (r *InstanceService) New(ctx context.Context, body InstanceNewParams, opts ...option.RequestOption) (res *Instance, err error)

Create and start instance

func (*InstanceService) Restore 

func (r *InstanceService) Restore(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error)

Restore instance from standby

func (*InstanceService) Standby 

func (r *InstanceService) Standby(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error)

Put instance in standby (pause, snapshot, delete VMM)

func (*InstanceService) Start 

func (r *InstanceService) Start(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error)

Start a stopped instance

func (*InstanceService) Stat 

func (r *InstanceService) Stat(ctx context.Context, id string, query InstanceStatParams, opts ...option.RequestOption) (res *PathInfo, err error)

Returns information about a path in the guest filesystem. Useful for checking if a path exists, its type, and permissions before performing file operations.

func (*InstanceService) Stop 

func (r *InstanceService) Stop(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error)

Stop instance (graceful shutdown)

type InstanceStatParams 

type InstanceStatParams struct {
	// Path to stat in the guest filesystem
	Path string `query:"path,required" json:"-"`
	// Follow symbolic links (like stat vs lstat)
	FollowLinks param.Opt[bool] `query:"follow_links,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (InstanceStatParams) URLQuery 

func (r InstanceStatParams) URLQuery() (v url.Values, err error)

URLQuery serializes InstanceStatParams's query parameters as `url.Values`.

type InstanceState 

type InstanceState string

Instance state:

- Created: VMM created but not started (Cloud Hypervisor native) - Running: VM is actively running (Cloud Hypervisor native) - Paused: VM is paused (Cloud Hypervisor native) - Shutdown: VM shut down but VMM exists (Cloud Hypervisor native) - Stopped: No VMM running, no snapshot exists - Standby: No VMM running, snapshot exists (can be restored) - Unknown: Failed to determine state (see state_error for details) 

const (
	InstanceStateCreated  InstanceState = "Created"
	InstanceStateRunning  InstanceState = "Running"
	InstanceStatePaused   InstanceState = "Paused"
	InstanceStateShutdown InstanceState = "Shutdown"
	InstanceStateStopped  InstanceState = "Stopped"
	InstanceStateStandby  InstanceState = "Standby"
	InstanceStateUnknown  InstanceState = "Unknown"
)

type InstanceVolumeAttachParams 

type InstanceVolumeAttachParams struct {
	ID string `path:"id,required" json:"-"`
	// Path where volume should be mounted
	MountPath string `json:"mount_path,required"`
	// Mount as read-only
	Readonly param.Opt[bool] `json:"readonly,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceVolumeAttachParams) MarshalJSON 

func (r InstanceVolumeAttachParams) MarshalJSON() (data []byte, err error)

func (*InstanceVolumeAttachParams) UnmarshalJSON 

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

type InstanceVolumeDetachParams 

type InstanceVolumeDetachParams struct {
	ID string `path:"id,required" json:"-"`
	// contains filtered or unexported fields
}

type InstanceVolumeService 

type InstanceVolumeService struct {
	Options []option.RequestOption
}

InstanceVolumeService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewInstanceVolumeService method instead.

func NewInstanceVolumeService 

func NewInstanceVolumeService(opts ...option.RequestOption) (r InstanceVolumeService)

NewInstanceVolumeService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*InstanceVolumeService) Attach 

func (r *InstanceVolumeService) Attach(ctx context.Context, volumeID string, params InstanceVolumeAttachParams, opts ...option.RequestOption) (res *Instance, err error)

Attach volume to instance

func (*InstanceVolumeService) Detach 

func (r *InstanceVolumeService) Detach(ctx context.Context, volumeID string, body InstanceVolumeDetachParams, opts ...option.RequestOption) (res *Instance, err error)

Detach volume from instance

type PassthroughDevice added in v0.9.3 

type PassthroughDevice struct {
	// Whether this GPU is available (not attached to an instance)
	Available bool `json:"available,required"`
	// GPU name
	Name string `json:"name,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Available   respjson.Field
		Name        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

Physical GPU available for passthrough

func (PassthroughDevice) RawJSON added in v0.9.3 

func (r PassthroughDevice) RawJSON() string

Returns the unmodified JSON received from the API

func (*PassthroughDevice) UnmarshalJSON added in v0.9.3 

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

type PathInfo 

type PathInfo struct {
	// Whether the path exists
	Exists bool `json:"exists,required"`
	// Error message if stat failed (e.g., permission denied). Only set when exists is
	// false due to an error rather than the path not existing.
	Error string `json:"error,nullable"`
	// True if this is a directory
	IsDir bool `json:"is_dir"`
	// True if this is a regular file
	IsFile bool `json:"is_file"`
	// True if this is a symbolic link (only set when follow_links=false)
	IsSymlink bool `json:"is_symlink"`
	// Symlink target path (only set when is_symlink=true)
	LinkTarget string `json:"link_target,nullable"`
	// File mode (Unix permissions)
	Mode int64 `json:"mode"`
	// File size in bytes
	Size int64 `json:"size"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Exists      respjson.Field
		Error       respjson.Field
		IsDir       respjson.Field
		IsFile      respjson.Field
		IsSymlink   respjson.Field
		LinkTarget  respjson.Field
		Mode        respjson.Field
		Size        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (PathInfo) RawJSON 

func (r PathInfo) RawJSON() string

Returns the unmodified JSON received from the API

func (*PathInfo) UnmarshalJSON 

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

type ResourceAllocation added in v0.9.3 

type ResourceAllocation struct {
	// vCPUs allocated
	CPU int64 `json:"cpu"`
	// Disk allocated in bytes (overlay + volumes)
	DiskBytes int64 `json:"disk_bytes"`
	// Instance identifier
	InstanceID string `json:"instance_id"`
	// Instance name
	InstanceName string `json:"instance_name"`
	// Memory allocated in bytes
	MemoryBytes int64 `json:"memory_bytes"`
	// Download bandwidth limit in bytes/sec (external→VM)
	NetworkDownloadBps int64 `json:"network_download_bps"`
	// Upload bandwidth limit in bytes/sec (VM→external)
	NetworkUploadBps int64 `json:"network_upload_bps"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		CPU                respjson.Field
		DiskBytes          respjson.Field
		InstanceID         respjson.Field
		InstanceName       respjson.Field
		MemoryBytes        respjson.Field
		NetworkDownloadBps respjson.Field
		NetworkUploadBps   respjson.Field
		ExtraFields        map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (ResourceAllocation) RawJSON added in v0.9.3 

func (r ResourceAllocation) RawJSON() string

Returns the unmodified JSON received from the API

func (*ResourceAllocation) UnmarshalJSON added in v0.9.3 

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

type ResourceService added in v0.9.3 

type ResourceService struct {
	Options []option.RequestOption
}

ResourceService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewResourceService method instead.

func NewResourceService added in v0.9.3 

func NewResourceService(opts ...option.RequestOption) (r ResourceService)

NewResourceService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*ResourceService) Get added in v0.9.3 

func (r *ResourceService) Get(ctx context.Context, opts ...option.RequestOption) (res *Resources, err error)

Returns current host resource capacity, allocation status, and per-instance breakdown. Resources include CPU, memory, disk, and network. Oversubscription ratios are applied to calculate effective limits.

type ResourceStatus added in v0.9.3 

type ResourceStatus struct {
	// Currently allocated resources
	Allocated int64 `json:"allocated,required"`
	// Available for allocation (effective_limit - allocated)
	Available int64 `json:"available,required"`
	// Raw host capacity
	Capacity int64 `json:"capacity,required"`
	// Capacity after oversubscription (capacity \* ratio)
	EffectiveLimit int64 `json:"effective_limit,required"`
	// Oversubscription ratio applied
	OversubRatio float64 `json:"oversub_ratio,required"`
	// Resource type
	Type string `json:"type,required"`
	// How capacity was determined (detected, configured)
	Source string `json:"source"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Allocated      respjson.Field
		Available      respjson.Field
		Capacity       respjson.Field
		EffectiveLimit respjson.Field
		OversubRatio   respjson.Field
		Type           respjson.Field
		Source         respjson.Field
		ExtraFields    map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (ResourceStatus) RawJSON added in v0.9.3 

func (r ResourceStatus) RawJSON() string

Returns the unmodified JSON received from the API

func (*ResourceStatus) UnmarshalJSON added in v0.9.3 

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

type Resources added in v0.9.3 

type Resources struct {
	Allocations   []ResourceAllocation `json:"allocations,required"`
	CPU           ResourceStatus       `json:"cpu,required"`
	Disk          ResourceStatus       `json:"disk,required"`
	Memory        ResourceStatus       `json:"memory,required"`
	Network       ResourceStatus       `json:"network,required"`
	DiskBreakdown DiskBreakdown        `json:"disk_breakdown"`
	// GPU resource status. Null if no GPUs available.
	GPU GPUResourceStatus `json:"gpu,nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Allocations   respjson.Field
		CPU           respjson.Field
		Disk          respjson.Field
		Memory        respjson.Field
		Network       respjson.Field
		DiskBreakdown respjson.Field
		GPU           respjson.Field
		ExtraFields   map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Resources) RawJSON added in v0.9.3 

func (r Resources) RawJSON() string

Returns the unmodified JSON received from the API

func (*Resources) UnmarshalJSON added in v0.9.3 

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

type Volume 

type Volume struct {
	// Unique identifier
	ID string `json:"id,required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at,required" format:"date-time"`
	// Volume name
	Name string `json:"name,required"`
	// Size in gigabytes
	SizeGB int64 `json:"size_gb,required"`
	// List of current attachments (empty if not attached)
	Attachments []VolumeAttachment `json:"attachments"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		CreatedAt   respjson.Field
		Name        respjson.Field
		SizeGB      respjson.Field
		Attachments respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Volume) RawJSON 

func (r Volume) RawJSON() string

Returns the unmodified JSON received from the API

func (*Volume) UnmarshalJSON 

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

type VolumeAttachment 

type VolumeAttachment struct {
	// ID of the instance this volume is attached to
	InstanceID string `json:"instance_id,required"`
	// Mount path in the guest
	MountPath string `json:"mount_path,required"`
	// Whether the attachment is read-only
	Readonly bool `json:"readonly,required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		InstanceID  respjson.Field
		MountPath   respjson.Field
		Readonly    respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (VolumeAttachment) RawJSON 

func (r VolumeAttachment) RawJSON() string

Returns the unmodified JSON received from the API

func (*VolumeAttachment) UnmarshalJSON 

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

type VolumeMount 

type VolumeMount struct {
	// Path where volume is mounted in the guest
	MountPath string `json:"mount_path,required"`
	// Volume identifier
	VolumeID string `json:"volume_id,required"`
	// Create per-instance overlay for writes (requires readonly=true)
	Overlay bool `json:"overlay"`
	// Max overlay size as human-readable string (e.g., "1GB"). Required if
	// overlay=true.
	OverlaySize string `json:"overlay_size"`
	// Whether volume is mounted read-only
	Readonly bool `json:"readonly"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		MountPath   respjson.Field
		VolumeID    respjson.Field
		Overlay     respjson.Field
		OverlaySize respjson.Field
		Readonly    respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (VolumeMount) RawJSON 

func (r VolumeMount) RawJSON() string

Returns the unmodified JSON received from the API

func (VolumeMount) ToParam 

func (r VolumeMount) ToParam() VolumeMountParam

ToParam converts this VolumeMount to a VolumeMountParam.

Warning: the fields of the param type will not be present. ToParam should only be used at the last possible moment before sending a request. Test for this with VolumeMountParam.Overrides()

func (*VolumeMount) UnmarshalJSON 

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

type VolumeMountParam 

type VolumeMountParam struct {
	// Path where volume is mounted in the guest
	MountPath string `json:"mount_path,required"`
	// Volume identifier
	VolumeID string `json:"volume_id,required"`
	// Create per-instance overlay for writes (requires readonly=true)
	Overlay param.Opt[bool] `json:"overlay,omitzero"`
	// Max overlay size as human-readable string (e.g., "1GB"). Required if
	// overlay=true.
	OverlaySize param.Opt[string] `json:"overlay_size,omitzero"`
	// Whether volume is mounted read-only
	Readonly param.Opt[bool] `json:"readonly,omitzero"`
	// contains filtered or unexported fields
}

The properties MountPath, VolumeID are required.

func (VolumeMountParam) MarshalJSON 

func (r VolumeMountParam) MarshalJSON() (data []byte, err error)

func (*VolumeMountParam) UnmarshalJSON 

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

type VolumeNewParams 

type VolumeNewParams struct {
	// Volume name
	Name string `json:"name,required"`
	// Size in gigabytes
	SizeGB int64 `json:"size_gb,required"`
	// Optional custom identifier (auto-generated if not provided)
	ID param.Opt[string] `json:"id,omitzero"`
	// contains filtered or unexported fields
}

func (VolumeNewParams) MarshalJSON 

func (r VolumeNewParams) MarshalJSON() (data []byte, err error)

func (*VolumeNewParams) UnmarshalJSON 

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

type VolumeService 

type VolumeService struct {
	Options []option.RequestOption
}

VolumeService contains methods and other services that help with interacting with the hypeman API.

Note, unlike clients, this service does not read variables from the environment automatically. You should not instantiate this service directly, and instead use the NewVolumeService method instead.

func NewVolumeService 

func NewVolumeService(opts ...option.RequestOption) (r VolumeService)

NewVolumeService generates a new service that applies the given options to each request. These options are applied after the parent client's options (if there is one), and before any request-specific options.

func (*VolumeService) Delete 

func (r *VolumeService) Delete(ctx context.Context, id string, opts ...option.RequestOption) (err error)

Delete volume

func (*VolumeService) Get 

func (r *VolumeService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Volume, err error)

Get volume details

func (*VolumeService) List 

func (r *VolumeService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Volume, err error)

List volumes

func (*VolumeService) New 

func (r *VolumeService) New(ctx context.Context, body VolumeNewParams, opts ...option.RequestOption) (res *Volume, err error)

Creates a new volume. Supports two modes:

  • JSON body: Creates an empty volume of the specified size
  • Multipart form: Creates a volume pre-populated with content from a tar.gz archive

Source Files

View all Source files

Directories

Path Synopsis
examples
push command
Example: Push a local Docker image to hypeman
 Example: Push a local Docker image to hypeman
apierror
apiform
apijson
apiquery
encoding/json
Package json implements encoding and decoding of JSON as defined in RFC 7159.
 Package json implements encoding and decoding of JSON as defined in RFC 7159.
encoding/json/sentinel
encoding/json/shims
This package provides shims over Go 1.2{2,3} APIs which are missing from Go 1.22, and used by the Go 1.24 encoding/json package.
 This package provides shims over Go 1.2{2,3} APIs which are missing from Go 1.22, and used by the Go 1.24 encoding/json package.
paramutil
requestconfig
testutil
Package lib provides manually-maintained functionality that extends the auto-generated SDK.
 Package lib provides manually-maintained functionality that extends the auto-generated SDK.
packages
param
respjson
ssestream
shared
constant

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.