hypeman

package module
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2026 License: Apache-2.0 Imports: 23 Imported by: 2

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

View Source 
const SnapshotCompressionConfigAlgorithmLz4 = shared.SnapshotCompressionConfigAlgorithmLz4

Equals "lz4"

View Source 
const SnapshotCompressionConfigAlgorithmZstd = shared.SnapshotCompressionConfigAlgorithmZstd

Equals "zstd"

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" api:"required"`
	// IOMMU group number
	IommuGroup int64 `json:"iommu_group" api:"required"`
	// PCI address
	PciAddress string `json:"pci_address" api:"required"`
	// PCI vendor ID (hex)
	VendorID string `json:"vendor_id" api:"required"`
	// Currently bound driver (null if none)
	CurrentDriver string `json:"current_driver" api:"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" api:"required"`
	// Build creation timestamp
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// Build job status
	//
	// Any of "queued", "building", "pushing", "ready", "failed", "cancelled".
	Status BuildStatus `json:"status" api:"required"`
	// Instance ID of the builder VM (for debugging)
	BuilderInstanceID string `json:"builder_instance_id" api:"nullable"`
	// Build completion timestamp
	CompletedAt time.Time `json:"completed_at" api:"nullable" format:"date-time"`
	// Build duration in milliseconds
	DurationMs int64 `json:"duration_ms" api:"nullable"`
	// Error message (only when status is failed)
	Error string `json:"error" api:"nullable"`
	// Digest of built image (only when status is ready)
	ImageDigest string `json:"image_digest" api:"nullable"`
	// Full image reference (only when status is ready)
	ImageRef   string          `json:"image_ref" api:"nullable"`
	Provenance BuildProvenance `json:"provenance"`
	// Position in build queue (only when status is queued)
	QueuePosition int64 `json:"queue_position" api:"nullable"`
	// Build start timestamp
	StartedAt time.Time `json:"started_at" api:"nullable" format:"date-time"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID                respjson.Field
		CreatedAt         respjson.Field
		Status            respjson.Field
		BuilderInstanceID 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
		Tags              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" api:"required" format:"date-time"`
	// Event type
	//
	// Any of "log", "status", "heartbeat".
	Type BuildEventType `json:"type" api:"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 BuildListParams added in v0.16.0 

type BuildListParams struct {
	// Filter builds by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (BuildListParams) URLQuery added in v0.16.0 

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

URLQuery serializes BuildListParams'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" api:"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"`
	// Number of vCPUs for builder VM (default 2)
	CPUs param.Opt[int64] `json:"cpus,omitzero"`
	// Dockerfile content. Required if not included in the source tarball.
	Dockerfile param.Opt[string] `json:"dockerfile,omitzero"`
	// Global cache identifier (e.g., "node", "python", "ubuntu", "browser"). When
	// specified, the build will import from cache/global/{key}. Admin builds will also
	// export to this location.
	GlobalCacheKey param.Opt[string] `json:"global_cache_key,omitzero"`
	// Custom image name for the build output. When set, the image is pushed to
	// {registry}/{image_name} instead of {registry}/builds/{id}.
	ImageName param.Opt[string] `json:"image_name,omitzero"`
	// Set to "true" to grant push access to global cache (operator-only). Admin builds
	// can populate the shared global cache that all tenant builds read from.
	IsAdminBuild param.Opt[string] `json:"is_admin_build,omitzero"`
	// Memory limit for builder VM in MB (default 2048)
	MemoryMB param.Opt[int64] `json:"memory_mb,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"`
	// JSON object of tags. Example: {"team":"backend","env":"staging"}
	Tags param.Opt[string] `json:"tags,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, query BuildListParams, 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
	Snapshots SnapshotService
	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" api:"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" api:"required"`
	// Registration timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// PCI device ID (hex)
	DeviceID string `json:"device_id" api:"required"`
	// IOMMU group number
	IommuGroup int64 `json:"iommu_group" api:"required"`
	// PCI address
	PciAddress string `json:"pci_address" api:"required"`
	// Type of PCI device
	//
	// Any of "gpu", "pci".
	Type DeviceType `json:"type" api:"required"`
	// PCI vendor ID (hex)
	VendorID string `json:"vendor_id" api:"required"`
	// Instance ID if attached
	AttachedTo string `json:"attached_to" api:"nullable"`
	// Device name (user-provided or auto-generated from PCI address)
	Name string `json:"name"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// 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
		Tags        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 DeviceListParams added in v0.16.0 

type DeviceListParams struct {
	// Filter devices by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (DeviceListParams) URLQuery added in v0.16.0 

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

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

type DeviceNewParams 

type DeviceNewParams struct {
	// PCI address of the device (required, e.g., "0000:a2:00.0")
	PciAddress string `json:"pci_address" api:"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"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,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, query DeviceListParams, 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" api:"required"`
	// Frame buffer size in MB
	FramebufferMB int64 `json:"framebuffer_mb" api:"required"`
	// Profile name (user-facing)
	Name string `json:"name" api:"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" api:"required"`
	// Total slots (VFs for vGPU, physical GPUs for passthrough)
	TotalSlots int64 `json:"total_slots" api:"required"`
	// Slots currently in use
	UsedSlots int64 `json:"used_slots" api:"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" api:"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" api:"required" format:"date-time"`
	// Resolved manifest digest
	Digest string `json:"digest" api:"required"`
	// Normalized OCI image reference (tag or digest)
	Name string `json:"name" api:"required"`
	// Build status
	//
	// Any of "pending", "pulling", "converting", "ready", "failed".
	Status ImageStatus `json:"status" api:"required"`
	// CMD from container metadata
	Cmd []string `json:"cmd" api:"nullable"`
	// Entrypoint from container metadata
	Entrypoint []string `json:"entrypoint" api:"nullable"`
	// Environment variables from container metadata
	Env map[string]string `json:"env"`
	// Error message if status is failed
	Error string `json:"error" api:"nullable"`
	// Position in build queue (null if not queued)
	QueuePosition int64 `json:"queue_position" api:"nullable"`
	// Disk size in bytes (null until ready)
	SizeBytes int64 `json:"size_bytes" api:"nullable"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// Working directory from container metadata
	WorkingDir string `json:"working_dir" api:"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
		Tags          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 ImageListParams added in v0.16.0 

type ImageListParams struct {
	// Filter images by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (ImageListParams) URLQuery added in v0.16.0 

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

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

type ImageNewParams 

type ImageNewParams struct {
	// OCI image reference (e.g., docker.io/library/nginx:latest)
	Name string `json:"name" api:"required"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,omitzero"`
	// 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, query ImageListParams, 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" api:"required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// Human-readable name
	Name string `json:"name" api:"required"`
	// Routing rules for this ingress
	Rules []IngressRule `json:"rules" api:"required"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// 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
		Tags        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 IngressListParams added in v0.16.0 

type IngressListParams struct {
	// Filter ingresses by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (IngressListParams) URLQuery added in v0.16.0 

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

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

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" api:"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" api:"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" api:"required"`
	// Routing rules for this ingress
	Rules []IngressRuleParam `json:"rules,omitzero" api:"required"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,omitzero"`
	// 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" api:"required"`
	Target IngressTarget `json:"target" api:"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" api:"required"`
	Target IngressTargetParam `json:"target,omitzero" api:"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, query IngressListParams, 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" api:"required"`
	// Target port on the instance
	Port int64 `json:"port" api:"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" api:"required"`
	// Target port on the instance
	Port int64 `json:"port" api:"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" api:"required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// OCI image reference
	Image string `json:"image" api:"required"`
	// Human-readable name
	Name string `json:"name" api:"required"`
	// Instance state:
	//
	// - Created: VMM created but not started (Cloud Hypervisor native)
	// - Initializing: VM is running while guest init is still in progress
	// - Running: Guest program has started and instance is ready
	// - 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", "Initializing", "Running", "Paused", "Shutdown", "Stopped",
	// "Standby", "Unknown".
	State InstanceState `json:"state" api:"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"`
	// App exit code (null if VM hasn't exited)
	ExitCode int64 `json:"exit_code" api:"nullable"`
	// Human-readable description of exit (e.g., "command not found", "killed by signal
	// 9 (SIGKILL) - OOM")
	ExitMessage string `json:"exit_message"`
	// 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", "firecracker", "qemu", "vz".
	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"`
	SnapshotPolicy SnapshotPolicy `json:"snapshot_policy"`
	// Start timestamp (RFC3339)
	StartedAt time.Time `json:"started_at" api:"nullable" format:"date-time"`
	// Error message if state couldn't be determined (only set when state is Unknown)
	StateError string `json:"state_error" api:"nullable"`
	// Stop timestamp (RFC3339)
	StoppedAt time.Time `json:"stopped_at" api:"nullable" format:"date-time"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// 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
		ExitCode       respjson.Field
		ExitMessage    respjson.Field
		GPU            respjson.Field
		HasSnapshot    respjson.Field
		HotplugSize    respjson.Field
		Hypervisor     respjson.Field
		Network        respjson.Field
		OverlaySize    respjson.Field
		Size           respjson.Field
		SnapshotPolicy respjson.Field
		StartedAt      respjson.Field
		StateError     respjson.Field
		StoppedAt      respjson.Field
		Tags           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 InstanceForkParams added in v0.15.0 

type InstanceForkParams struct {
	// Name for the forked instance (lowercase letters, digits, and dashes only; cannot
	// start or end with a dash)
	Name string `json:"name" api:"required"`
	// Allow forking from a running source instance. When true and source is Running,
	// the source is put into standby, forked, then restored back to Running.
	FromRunning param.Opt[bool] `json:"from_running,omitzero"`
	// Optional final state for the forked instance. Default is the source instance
	// state at fork time. For example, forking from Running defaults the fork result
	// to Running.
	//
	// Any of "Stopped", "Standby", "Running".
	TargetState InstanceForkParamsTargetState `json:"target_state,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceForkParams) MarshalJSON added in v0.15.0 

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

func (*InstanceForkParams) UnmarshalJSON added in v0.15.0 

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

type InstanceForkParamsTargetState added in v0.15.0 

type InstanceForkParamsTargetState string

Optional final state for the forked instance. Default is the source instance state at fork time. For example, forking from Running defaults the fork result to Running. 

const (
	InstanceForkParamsTargetStateStopped InstanceForkParamsTargetState = "Stopped"
	InstanceForkParamsTargetStateStandby InstanceForkParamsTargetState = "Standby"
	InstanceForkParamsTargetStateRunning InstanceForkParamsTargetState = "Running"
)

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"
	InstanceHypervisorFirecracker     InstanceHypervisor = "firecracker"
	InstanceHypervisorQemu            InstanceHypervisor = "qemu"
	InstanceHypervisorVz              InstanceHypervisor = "vz"
)

type InstanceListParams added in v0.12.0 

type InstanceListParams struct {
	// Filter instances by state (e.g., Running, Stopped)
	//
	// Any of "Created", "Initializing", "Running", "Paused", "Shutdown", "Stopped",
	// "Standby", "Unknown".
	State InstanceListParamsState `query:"state,omitzero" json:"-"`
	// Filter instances by tag key-value pairs. Uses deepObject style:
	// ?tags[team]=backend&tags[env]=staging Multiple entries are ANDed together. All
	// specified key-value pairs must match.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (InstanceListParams) URLQuery added in v0.12.0 

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

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

type InstanceListParamsState added in v0.12.0 

type InstanceListParamsState string

Filter instances by state (e.g., Running, Stopped) 

const (
	InstanceListParamsStateCreated      InstanceListParamsState = "Created"
	InstanceListParamsStateInitializing InstanceListParamsState = "Initializing"
	InstanceListParamsStateRunning      InstanceListParamsState = "Running"
	InstanceListParamsStatePaused       InstanceListParamsState = "Paused"
	InstanceListParamsStateShutdown     InstanceListParamsState = "Shutdown"
	InstanceListParamsStateStopped      InstanceListParamsState = "Stopped"
	InstanceListParamsStateStandby      InstanceListParamsState = "Standby"
	InstanceListParamsStateUnknown      InstanceListParamsState = "Unknown"
)

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" api:"nullable"`
	// Assigned MAC address (null if no network)
	Mac string `json:"mac" api:"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" api:"required"`
	// Human-readable name (lowercase letters, digits, and dashes only; cannot start or
	// end with a dash)
	Name string `json:"name" api:"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"). Omit to
	// disable hotplug memory.
	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"`
	// Skip guest-agent installation during boot. When true, the exec and stat APIs
	// will not work for this instance. The instance will still run, but remote command
	// execution will be unavailable.
	SkipGuestAgent param.Opt[bool] `json:"skip_guest_agent,omitzero"`
	// Skip kernel headers installation during boot for faster startup. When true, DKMS
	// (Dynamic Kernel Module Support) will not work, preventing compilation of
	// out-of-tree kernel modules (e.g., NVIDIA vGPU drivers). Recommended for
	// workloads that don't need kernel module compilation.
	SkipKernelHeaders param.Opt[bool] `json:"skip_kernel_headers,omitzero"`
	// Number of virtual CPUs
	Vcpus param.Opt[int64] `json:"vcpus,omitzero"`
	// Override image CMD (like docker run <image> <command>). Omit to use image
	// default.
	Cmd []string `json:"cmd,omitzero"`
	// Host-managed credential brokering policies keyed by guest-visible env var name.
	// Those guest env vars receive mock placeholder values, while the real values
	// remain host-scoped in the request `env` map and are only materialized on the
	// mediated egress path according to each credential's `source` and `inject` rules.
	Credentials map[string]InstanceNewParamsCredential `json:"credentials,omitzero"`
	// Device IDs or names to attach for GPU/PCI passthrough
	Devices []string `json:"devices,omitzero"`
	// Override image entrypoint (like docker run --entrypoint). Omit to use image
	// default.
	Entrypoint []string `json:"entrypoint,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", "firecracker", "qemu", "vz".
	Hypervisor InstanceNewParamsHypervisor `json:"hypervisor,omitzero"`
	// Network configuration for the instance
	Network InstanceNewParamsNetwork `json:"network,omitzero"`
	// Snapshot compression policy for this instance. Controls compression settings
	// applied when creating snapshots or entering standby.
	SnapshotPolicy SnapshotPolicyParam `json:"snapshot_policy,omitzero"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,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 InstanceNewParamsCredential added in v0.16.0 

type InstanceNewParamsCredential struct {
	Inject []InstanceNewParamsCredentialInject `json:"inject,omitzero" api:"required"`
	Source InstanceNewParamsCredentialSource   `json:"source,omitzero" api:"required"`
	// contains filtered or unexported fields
}

The properties Inject, Source are required.

func (InstanceNewParamsCredential) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsCredential) UnmarshalJSON added in v0.16.0 

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

type InstanceNewParamsCredentialInject added in v0.16.0 

type InstanceNewParamsCredentialInject struct {
	// Current v1 transform shape. Header templating is supported now; other transform
	// types (for example request signing) can be added in future revisions.
	As InstanceNewParamsCredentialInjectAs `json:"as,omitzero" api:"required"`
	// Optional destination host patterns (`api.example.com`, `*.example.com`). Omit to
	// allow injection on all destinations.
	Hosts []string `json:"hosts,omitzero"`
	// contains filtered or unexported fields
}

The property As is required.

func (InstanceNewParamsCredentialInject) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsCredentialInject) UnmarshalJSON added in v0.16.0 

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

type InstanceNewParamsCredentialInjectAs added in v0.16.0 

type InstanceNewParamsCredentialInjectAs struct {
	// Template that must include `${value}`.
	Format string `json:"format" api:"required"`
	// Header name to set/mutate for matching outbound requests.
	Header string `json:"header" api:"required"`
	// contains filtered or unexported fields
}

Current v1 transform shape. Header templating is supported now; other transform types (for example request signing) can be added in future revisions.

The properties Format, Header are required.

func (InstanceNewParamsCredentialInjectAs) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsCredentialInjectAs) UnmarshalJSON added in v0.16.0 

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

type InstanceNewParamsCredentialSource added in v0.16.0 

type InstanceNewParamsCredentialSource struct {
	// Name of the real credential in the request `env` map. The guest-visible env var
	// key can receive a mock placeholder, while the mediated egress path resolves that
	// placeholder back to this real value only on the host.
	Env string `json:"env" api:"required"`
	// contains filtered or unexported fields
}

The property Env is required.

func (InstanceNewParamsCredentialSource) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsCredentialSource) UnmarshalJSON added in v0.16.0 

func (r *InstanceNewParamsCredentialSource) 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"
	InstanceNewParamsHypervisorFirecracker     InstanceNewParamsHypervisor = "firecracker"
	InstanceNewParamsHypervisorQemu            InstanceNewParamsHypervisor = "qemu"
	InstanceNewParamsHypervisorVz              InstanceNewParamsHypervisor = "vz"
)

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"`
	// Host-mediated outbound network policy. Omit this object, or set
	// `enabled: false`, to preserve normal direct outbound networking when
	// `network.enabled` is true.
	Egress InstanceNewParamsNetworkEgress `json:"egress,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 InstanceNewParamsNetworkEgress added in v0.16.0 

type InstanceNewParamsNetworkEgress struct {
	// Whether to enable the mediated egress path. When false or omitted, the instance
	// keeps normal direct outbound networking and host-managed credential rewriting is
	// disabled.
	Enabled param.Opt[bool] `json:"enabled,omitzero"`
	// Egress enforcement policy applied when mediation is enabled.
	Enforcement InstanceNewParamsNetworkEgressEnforcement `json:"enforcement,omitzero"`
	// contains filtered or unexported fields
}

Host-mediated outbound network policy. Omit this object, or set `enabled: false`, to preserve normal direct outbound networking when `network.enabled` is true.

func (InstanceNewParamsNetworkEgress) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsNetworkEgress) UnmarshalJSON added in v0.16.0 

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

type InstanceNewParamsNetworkEgressEnforcement added in v0.16.0 

type InstanceNewParamsNetworkEgressEnforcement struct {
	// `all` (default) rejects direct non-mediated TCP egress from the VM, while
	// `http_https_only` rejects direct egress only on TCP ports 80 and 443.
	//
	// Any of "all", "http_https_only".
	Mode string `json:"mode,omitzero"`
	// contains filtered or unexported fields
}

Egress enforcement policy applied when mediation is enabled.

func (InstanceNewParamsNetworkEgressEnforcement) MarshalJSON added in v0.16.0 

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

func (*InstanceNewParamsNetworkEgressEnforcement) UnmarshalJSON added in v0.16.0 

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

type InstanceService 

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

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) Fork added in v0.15.0 

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

Fork an instance from stopped, standby, or running (with from_running=true)

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, query InstanceListParams, 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, body InstanceStandbyParams, 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, body InstanceStartParams, 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) Stats added in v0.15.0 

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

Returns real-time resource utilization statistics for a running VM instance. Metrics are collected from /proc/<pid>/stat and /proc/<pid>/statm for CPU and memory, and from TAP interface statistics for network I/O.

func (*InstanceService) Stop 

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

Stop instance (graceful shutdown)

func (*InstanceService) Update added in v0.16.0 

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

Update mutable properties of a running instance. Currently supports updating only the environment variables referenced by existing credential policies, enabling secret/key rotation without instance restart.

type InstanceSnapshotNewParams added in v0.16.0 

type InstanceSnapshotNewParams struct {
	// Snapshot capture kind
	//
	// Any of "Standby", "Stopped".
	Kind SnapshotKind `json:"kind,omitzero" api:"required"`
	// Optional snapshot name (lowercase letters, digits, and dashes only; cannot start
	// or end with a dash)
	Name param.Opt[string] `json:"name,omitzero"`
	// Compression settings to use for this snapshot. Overrides instance and server
	// defaults.
	Compression shared.SnapshotCompressionConfigParam `json:"compression,omitzero"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceSnapshotNewParams) MarshalJSON added in v0.16.0 

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

func (*InstanceSnapshotNewParams) UnmarshalJSON added in v0.16.0 

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

type InstanceSnapshotRestoreParams added in v0.16.0 

type InstanceSnapshotRestoreParams struct {
	ID string `path:"id" api:"required" json:"-"`
	// Optional hypervisor override. Allowed only when restoring from a Stopped
	// snapshot. Standby snapshots must restore with their original hypervisor.
	//
	// Any of "cloud-hypervisor", "firecracker", "qemu", "vz".
	TargetHypervisor InstanceSnapshotRestoreParamsTargetHypervisor `json:"target_hypervisor,omitzero"`
	// Optional final state after restore. Defaults by snapshot kind:
	//
	// - Standby snapshot defaults to Running
	// - Stopped snapshot defaults to Stopped
	//
	// Any of "Stopped", "Standby", "Running".
	TargetState InstanceSnapshotRestoreParamsTargetState `json:"target_state,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceSnapshotRestoreParams) MarshalJSON added in v0.16.0 

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

func (*InstanceSnapshotRestoreParams) UnmarshalJSON added in v0.16.0 

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

type InstanceSnapshotRestoreParamsTargetHypervisor added in v0.16.0 

type InstanceSnapshotRestoreParamsTargetHypervisor string

Optional hypervisor override. Allowed only when restoring from a Stopped snapshot. Standby snapshots must restore with their original hypervisor. 

const (
	InstanceSnapshotRestoreParamsTargetHypervisorCloudHypervisor InstanceSnapshotRestoreParamsTargetHypervisor = "cloud-hypervisor"
	InstanceSnapshotRestoreParamsTargetHypervisorFirecracker     InstanceSnapshotRestoreParamsTargetHypervisor = "firecracker"
	InstanceSnapshotRestoreParamsTargetHypervisorQemu            InstanceSnapshotRestoreParamsTargetHypervisor = "qemu"
	InstanceSnapshotRestoreParamsTargetHypervisorVz              InstanceSnapshotRestoreParamsTargetHypervisor = "vz"
)

type InstanceSnapshotRestoreParamsTargetState added in v0.16.0 

type InstanceSnapshotRestoreParamsTargetState string

Optional final state after restore. Defaults by snapshot kind:

- Standby snapshot defaults to Running - Stopped snapshot defaults to Stopped 

const (
	InstanceSnapshotRestoreParamsTargetStateStopped InstanceSnapshotRestoreParamsTargetState = "Stopped"
	InstanceSnapshotRestoreParamsTargetStateStandby InstanceSnapshotRestoreParamsTargetState = "Standby"
	InstanceSnapshotRestoreParamsTargetStateRunning InstanceSnapshotRestoreParamsTargetState = "Running"
)

type InstanceSnapshotService added in v0.16.0 

type InstanceSnapshotService struct {
	Options []option.RequestOption
}

InstanceSnapshotService 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 NewInstanceSnapshotService method instead.

func NewInstanceSnapshotService added in v0.16.0 

func NewInstanceSnapshotService(opts ...option.RequestOption) (r InstanceSnapshotService)

NewInstanceSnapshotService 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 (*InstanceSnapshotService) New added in v0.16.0 

func (r *InstanceSnapshotService) New(ctx context.Context, id string, body InstanceSnapshotNewParams, opts ...option.RequestOption) (res *Snapshot, err error)

Create a snapshot for an instance

func (*InstanceSnapshotService) Restore added in v0.16.0 

func (r *InstanceSnapshotService) Restore(ctx context.Context, snapshotID string, params InstanceSnapshotRestoreParams, opts ...option.RequestOption) (res *Instance, err error)

Restore an instance from a snapshot in-place

type InstanceStandbyParams added in v0.16.0 

type InstanceStandbyParams struct {
	Compression shared.SnapshotCompressionConfigParam `json:"compression,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceStandbyParams) MarshalJSON added in v0.16.0 

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

func (*InstanceStandbyParams) UnmarshalJSON added in v0.16.0 

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

type InstanceStartParams added in v0.10.0 

type InstanceStartParams struct {
	// Override image CMD for this run. Omit to keep previous value.
	Cmd []string `json:"cmd,omitzero"`
	// Override image entrypoint for this run. Omit to keep previous value.
	Entrypoint []string `json:"entrypoint,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceStartParams) MarshalJSON added in v0.10.0 

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

func (*InstanceStartParams) UnmarshalJSON added in v0.10.0 

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

type InstanceStatParams 

type InstanceStatParams struct {
	// Path to stat in the guest filesystem
	Path string `query:"path" api:"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) - Initializing: VM is running while guest init is still in progress - Running: Guest program has started and instance is ready - 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"
	InstanceStateInitializing InstanceState = "Initializing"
	InstanceStateRunning      InstanceState = "Running"
	InstanceStatePaused       InstanceState = "Paused"
	InstanceStateShutdown     InstanceState = "Shutdown"
	InstanceStateStopped      InstanceState = "Stopped"
	InstanceStateStandby      InstanceState = "Standby"
	InstanceStateUnknown      InstanceState = "Unknown"
)

type InstanceStats added in v0.15.0 

type InstanceStats struct {
	// Total memory allocated to the VM (Size + HotplugSize) in bytes
	AllocatedMemoryBytes int64 `json:"allocated_memory_bytes" api:"required"`
	// Number of vCPUs allocated to the VM
	AllocatedVcpus int64 `json:"allocated_vcpus" api:"required"`
	// Total CPU time consumed by the VM hypervisor process in seconds
	CPUSeconds float64 `json:"cpu_seconds" api:"required"`
	// Instance identifier
	InstanceID string `json:"instance_id" api:"required"`
	// Instance name
	InstanceName string `json:"instance_name" api:"required"`
	// Resident Set Size - actual physical memory used by the VM in bytes
	MemoryRssBytes int64 `json:"memory_rss_bytes" api:"required"`
	// Virtual Memory Size - total virtual memory allocated in bytes
	MemoryVmsBytes int64 `json:"memory_vms_bytes" api:"required"`
	// Total network bytes received by the VM (from TAP interface)
	NetworkRxBytes int64 `json:"network_rx_bytes" api:"required"`
	// Total network bytes transmitted by the VM (from TAP interface)
	NetworkTxBytes int64 `json:"network_tx_bytes" api:"required"`
	// Memory utilization ratio (RSS / allocated memory). Only present when
	// allocated_memory_bytes > 0.
	MemoryUtilizationRatio float64 `json:"memory_utilization_ratio" api:"nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		AllocatedMemoryBytes   respjson.Field
		AllocatedVcpus         respjson.Field
		CPUSeconds             respjson.Field
		InstanceID             respjson.Field
		InstanceName           respjson.Field
		MemoryRssBytes         respjson.Field
		MemoryVmsBytes         respjson.Field
		NetworkRxBytes         respjson.Field
		NetworkTxBytes         respjson.Field
		MemoryUtilizationRatio respjson.Field
		ExtraFields            map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

Real-time resource utilization statistics for a VM instance

func (InstanceStats) RawJSON added in v0.15.0 

func (r InstanceStats) RawJSON() string

Returns the unmodified JSON received from the API

func (*InstanceStats) UnmarshalJSON added in v0.15.0 

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

type InstanceUpdateParams added in v0.16.0 

type InstanceUpdateParams struct {
	// Environment variables to update (merged with existing). Only keys referenced by
	// the instance's existing credential `source.env` bindings are accepted. Use this
	// to rotate real credential values without restarting the VM.
	Env map[string]string `json:"env,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceUpdateParams) MarshalJSON added in v0.16.0 

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

func (*InstanceUpdateParams) UnmarshalJSON added in v0.16.0 

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

type InstanceVolumeAttachParams 

type InstanceVolumeAttachParams struct {
	ID string `path:"id" api:"required" json:"-"`
	// Path where volume should be mounted
	MountPath string `json:"mount_path" api:"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" api:"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 MemoryReclaimAction added in v0.16.0 

type MemoryReclaimAction struct {
	AppliedReclaimBytes int64 `json:"applied_reclaim_bytes" api:"required"`
	AssignedMemoryBytes int64 `json:"assigned_memory_bytes" api:"required"`
	// Any of "cloud-hypervisor", "firecracker", "qemu", "vz".
	Hypervisor                     MemoryReclaimActionHypervisor `json:"hypervisor" api:"required"`
	InstanceID                     string                        `json:"instance_id" api:"required"`
	InstanceName                   string                        `json:"instance_name" api:"required"`
	PlannedTargetGuestMemoryBytes  int64                         `json:"planned_target_guest_memory_bytes" api:"required"`
	PreviousTargetGuestMemoryBytes int64                         `json:"previous_target_guest_memory_bytes" api:"required"`
	ProtectedFloorBytes            int64                         `json:"protected_floor_bytes" api:"required"`
	// Result of this VM's reclaim step.
	Status                 string `json:"status" api:"required"`
	TargetGuestMemoryBytes int64  `json:"target_guest_memory_bytes" api:"required"`
	// Error message when status is error or unsupported.
	Error string `json:"error"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		AppliedReclaimBytes            respjson.Field
		AssignedMemoryBytes            respjson.Field
		Hypervisor                     respjson.Field
		InstanceID                     respjson.Field
		InstanceName                   respjson.Field
		PlannedTargetGuestMemoryBytes  respjson.Field
		PreviousTargetGuestMemoryBytes respjson.Field
		ProtectedFloorBytes            respjson.Field
		Status                         respjson.Field
		TargetGuestMemoryBytes         respjson.Field
		Error                          respjson.Field
		ExtraFields                    map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (MemoryReclaimAction) RawJSON added in v0.16.0 

func (r MemoryReclaimAction) RawJSON() string

Returns the unmodified JSON received from the API

func (*MemoryReclaimAction) UnmarshalJSON added in v0.16.0 

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

type MemoryReclaimActionHypervisor added in v0.16.0 

type MemoryReclaimActionHypervisor string
const (
	MemoryReclaimActionHypervisorCloudHypervisor MemoryReclaimActionHypervisor = "cloud-hypervisor"
	MemoryReclaimActionHypervisorFirecracker     MemoryReclaimActionHypervisor = "firecracker"
	MemoryReclaimActionHypervisorQemu            MemoryReclaimActionHypervisor = "qemu"
	MemoryReclaimActionHypervisorVz              MemoryReclaimActionHypervisor = "vz"
)

type MemoryReclaimRequestParam added in v0.16.0 

type MemoryReclaimRequestParam struct {
	// Total bytes of guest memory to reclaim across eligible VMs.
	ReclaimBytes int64 `json:"reclaim_bytes" api:"required"`
	// Calculate a reclaim plan without applying balloon changes or creating a hold.
	DryRun param.Opt[bool] `json:"dry_run,omitzero"`
	// How long to keep the reclaim hold active (Go duration string). Defaults to 5m
	// when omitted.
	HoldFor param.Opt[string] `json:"hold_for,omitzero"`
	// Optional operator-provided reason attached to logs and traces.
	Reason param.Opt[string] `json:"reason,omitzero"`
	// contains filtered or unexported fields
}

The property ReclaimBytes is required.

func (MemoryReclaimRequestParam) MarshalJSON added in v0.16.0 

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

func (*MemoryReclaimRequestParam) UnmarshalJSON added in v0.16.0 

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

type MemoryReclaimResponse added in v0.16.0 

type MemoryReclaimResponse struct {
	Actions             []MemoryReclaimAction `json:"actions" api:"required"`
	AppliedReclaimBytes int64                 `json:"applied_reclaim_bytes" api:"required"`
	HostAvailableBytes  int64                 `json:"host_available_bytes" api:"required"`
	// Any of "healthy", "pressure".
	HostPressureState     MemoryReclaimResponseHostPressureState `json:"host_pressure_state" api:"required"`
	PlannedReclaimBytes   int64                                  `json:"planned_reclaim_bytes" api:"required"`
	RequestedReclaimBytes int64                                  `json:"requested_reclaim_bytes" api:"required"`
	// When the current manual reclaim hold expires.
	HoldUntil time.Time `json:"hold_until" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Actions               respjson.Field
		AppliedReclaimBytes   respjson.Field
		HostAvailableBytes    respjson.Field
		HostPressureState     respjson.Field
		PlannedReclaimBytes   respjson.Field
		RequestedReclaimBytes respjson.Field
		HoldUntil             respjson.Field
		ExtraFields           map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (MemoryReclaimResponse) RawJSON added in v0.16.0 

func (r MemoryReclaimResponse) RawJSON() string

Returns the unmodified JSON received from the API

func (*MemoryReclaimResponse) UnmarshalJSON added in v0.16.0 

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

type MemoryReclaimResponseHostPressureState added in v0.16.0 

type MemoryReclaimResponseHostPressureState string
const (
	MemoryReclaimResponseHostPressureStateHealthy  MemoryReclaimResponseHostPressureState = "healthy"
	MemoryReclaimResponseHostPressureStatePressure MemoryReclaimResponseHostPressureState = "pressure"
)

type PassthroughDevice added in v0.9.3 

type PassthroughDevice struct {
	// Whether this GPU is available (not attached to an instance)
	Available bool `json:"available" api:"required"`
	// GPU name
	Name string `json:"name" api:"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" api:"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" api:"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" api:"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"`
	// Disk I/O bandwidth limit in bytes/sec
	DiskIoBps int64 `json:"disk_io_bps"`
	// 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
		DiskIoBps          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 ResourceReclaimMemoryParams added in v0.16.0 

type ResourceReclaimMemoryParams struct {
	MemoryReclaimRequest MemoryReclaimRequestParam
	// contains filtered or unexported fields
}

func (ResourceReclaimMemoryParams) MarshalJSON added in v0.16.0 

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

func (*ResourceReclaimMemoryParams) UnmarshalJSON added in v0.16.0 

func (r *ResourceReclaimMemoryParams) 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.

func (*ResourceService) ReclaimMemory added in v0.16.0 

func (r *ResourceService) ReclaimMemory(ctx context.Context, body ResourceReclaimMemoryParams, opts ...option.RequestOption) (res *MemoryReclaimResponse, err error)

Requests runtime balloon inflation across reclaim-eligible guests. The same planner used by host-pressure reclaim is applied, including protected floors and per-VM step limits.

type ResourceStatus added in v0.9.3 

type ResourceStatus struct {
	// Currently allocated resources
	Allocated int64 `json:"allocated" api:"required"`
	// Available for allocation (effective_limit - allocated)
	Available int64 `json:"available" api:"required"`
	// Raw host capacity
	Capacity int64 `json:"capacity" api:"required"`
	// Capacity after oversubscription (capacity \* ratio)
	EffectiveLimit int64 `json:"effective_limit" api:"required"`
	// Oversubscription ratio applied
	OversubRatio float64 `json:"oversub_ratio" api:"required"`
	// Resource type
	Type string `json:"type" api:"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" api:"required"`
	CPU           ResourceStatus       `json:"cpu" api:"required"`
	Disk          ResourceStatus       `json:"disk" api:"required"`
	Memory        ResourceStatus       `json:"memory" api:"required"`
	Network       ResourceStatus       `json:"network" api:"required"`
	DiskBreakdown DiskBreakdown        `json:"disk_breakdown"`
	DiskIo        ResourceStatus       `json:"disk_io"`
	// GPU resource status. Null if no GPUs available.
	GPU GPUResourceStatus `json:"gpu" api:"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
		DiskIo        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 Snapshot added in v0.16.0 

type Snapshot struct {
	// Auto-generated unique snapshot identifier
	ID string `json:"id" api:"required"`
	// Snapshot creation timestamp
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// Snapshot capture kind
	//
	// Any of "Standby", "Stopped".
	Kind SnapshotKind `json:"kind" api:"required"`
	// Total payload size in bytes
	SizeBytes int64 `json:"size_bytes" api:"required"`
	// Source instance hypervisor at snapshot creation time
	//
	// Any of "cloud-hypervisor", "firecracker", "qemu", "vz".
	SourceHypervisor SnapshotSourceHypervisor `json:"source_hypervisor" api:"required"`
	// Source instance ID at snapshot creation time
	SourceInstanceID string `json:"source_instance_id" api:"required"`
	// Source instance name at snapshot creation time
	SourceInstanceName string `json:"source_instance_name" api:"required"`
	// Compressed memory payload size in bytes
	CompressedSizeBytes int64                            `json:"compressed_size_bytes" api:"nullable"`
	Compression         shared.SnapshotCompressionConfig `json:"compression"`
	// Compression error message when compression_state is error
	CompressionError string `json:"compression_error" api:"nullable"`
	// Compression status of the snapshot payload memory file
	//
	// Any of "none", "compressing", "compressed", "error".
	CompressionState SnapshotCompressionState `json:"compression_state"`
	// Optional human-readable snapshot name (unique per source instance)
	Name string `json:"name" api:"nullable"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// Uncompressed memory payload size in bytes
	UncompressedSizeBytes int64 `json:"uncompressed_size_bytes" api:"nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID                    respjson.Field
		CreatedAt             respjson.Field
		Kind                  respjson.Field
		SizeBytes             respjson.Field
		SourceHypervisor      respjson.Field
		SourceInstanceID      respjson.Field
		SourceInstanceName    respjson.Field
		CompressedSizeBytes   respjson.Field
		Compression           respjson.Field
		CompressionError      respjson.Field
		CompressionState      respjson.Field
		Name                  respjson.Field
		Tags                  respjson.Field
		UncompressedSizeBytes respjson.Field
		ExtraFields           map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (Snapshot) RawJSON added in v0.16.0 

func (r Snapshot) RawJSON() string

Returns the unmodified JSON received from the API

func (*Snapshot) UnmarshalJSON added in v0.16.0 

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

type SnapshotCompressionConfig added in v0.16.0 

type SnapshotCompressionConfig = shared.SnapshotCompressionConfig

This is an alias to an internal type.

type SnapshotCompressionConfigAlgorithm added in v0.16.0 

type SnapshotCompressionConfigAlgorithm = shared.SnapshotCompressionConfigAlgorithm

Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.

This is an alias to an internal type.

type SnapshotCompressionConfigParam added in v0.16.0 

type SnapshotCompressionConfigParam = shared.SnapshotCompressionConfigParam

This is an alias to an internal type.

type SnapshotCompressionState added in v0.16.0 

type SnapshotCompressionState string

Compression status of the snapshot payload memory file 

const (
	SnapshotCompressionStateNone        SnapshotCompressionState = "none"
	SnapshotCompressionStateCompressing SnapshotCompressionState = "compressing"
	SnapshotCompressionStateCompressed  SnapshotCompressionState = "compressed"
	SnapshotCompressionStateError       SnapshotCompressionState = "error"
)

type SnapshotForkParams added in v0.16.0 

type SnapshotForkParams struct {
	// Name for the new instance (lowercase letters, digits, and dashes only; cannot
	// start or end with a dash)
	Name string `json:"name" api:"required"`
	// Optional hypervisor override. Allowed only when forking from a Stopped snapshot.
	// Standby snapshots must fork with their original hypervisor.
	//
	// Any of "cloud-hypervisor", "firecracker", "qemu", "vz".
	TargetHypervisor SnapshotForkParamsTargetHypervisor `json:"target_hypervisor,omitzero"`
	// Optional final state for the forked instance. Defaults by snapshot kind:
	//
	// - Standby snapshot defaults to Running
	// - Stopped snapshot defaults to Stopped
	//
	// Any of "Stopped", "Standby", "Running".
	TargetState SnapshotForkParamsTargetState `json:"target_state,omitzero"`
	// contains filtered or unexported fields
}

func (SnapshotForkParams) MarshalJSON added in v0.16.0 

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

func (*SnapshotForkParams) UnmarshalJSON added in v0.16.0 

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

type SnapshotForkParamsTargetHypervisor added in v0.16.0 

type SnapshotForkParamsTargetHypervisor string

Optional hypervisor override. Allowed only when forking from a Stopped snapshot. Standby snapshots must fork with their original hypervisor. 

const (
	SnapshotForkParamsTargetHypervisorCloudHypervisor SnapshotForkParamsTargetHypervisor = "cloud-hypervisor"
	SnapshotForkParamsTargetHypervisorFirecracker     SnapshotForkParamsTargetHypervisor = "firecracker"
	SnapshotForkParamsTargetHypervisorQemu            SnapshotForkParamsTargetHypervisor = "qemu"
	SnapshotForkParamsTargetHypervisorVz              SnapshotForkParamsTargetHypervisor = "vz"
)

type SnapshotForkParamsTargetState added in v0.16.0 

type SnapshotForkParamsTargetState string

Optional final state for the forked instance. Defaults by snapshot kind:

- Standby snapshot defaults to Running - Stopped snapshot defaults to Stopped 

const (
	SnapshotForkParamsTargetStateStopped SnapshotForkParamsTargetState = "Stopped"
	SnapshotForkParamsTargetStateStandby SnapshotForkParamsTargetState = "Standby"
	SnapshotForkParamsTargetStateRunning SnapshotForkParamsTargetState = "Running"
)

type SnapshotKind added in v0.16.0 

type SnapshotKind string

Snapshot capture kind 

const (
	SnapshotKindStandby SnapshotKind = "Standby"
	SnapshotKindStopped SnapshotKind = "Stopped"
)

type SnapshotListParams added in v0.16.0 

type SnapshotListParams struct {
	// Filter snapshots by snapshot name
	Name param.Opt[string] `query:"name,omitzero" json:"-"`
	// Filter snapshots by source instance ID
	SourceInstanceID param.Opt[string] `query:"source_instance_id,omitzero" json:"-"`
	// Filter snapshots by kind
	//
	// Any of "Standby", "Stopped".
	Kind SnapshotKind `query:"kind,omitzero" json:"-"`
	// Filter snapshots by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (SnapshotListParams) URLQuery added in v0.16.0 

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

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

type SnapshotPolicy added in v0.16.0 

type SnapshotPolicy struct {
	Compression shared.SnapshotCompressionConfig `json:"compression"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Compression respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

func (SnapshotPolicy) RawJSON added in v0.16.0 

func (r SnapshotPolicy) RawJSON() string

Returns the unmodified JSON received from the API

func (SnapshotPolicy) ToParam added in v0.16.0 

func (r SnapshotPolicy) ToParam() SnapshotPolicyParam

ToParam converts this SnapshotPolicy to a SnapshotPolicyParam.

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 SnapshotPolicyParam.Overrides()

func (*SnapshotPolicy) UnmarshalJSON added in v0.16.0 

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

type SnapshotPolicyParam added in v0.16.0 

type SnapshotPolicyParam struct {
	Compression shared.SnapshotCompressionConfigParam `json:"compression,omitzero"`
	// contains filtered or unexported fields
}

func (SnapshotPolicyParam) MarshalJSON added in v0.16.0 

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

func (*SnapshotPolicyParam) UnmarshalJSON added in v0.16.0 

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

type SnapshotService added in v0.16.0 

type SnapshotService struct {
	Options []option.RequestOption
}

SnapshotService 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 NewSnapshotService method instead.

func NewSnapshotService added in v0.16.0 

func NewSnapshotService(opts ...option.RequestOption) (r SnapshotService)

NewSnapshotService 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 (*SnapshotService) Delete added in v0.16.0 

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

Delete a snapshot

func (*SnapshotService) Fork added in v0.16.0 

func (r *SnapshotService) Fork(ctx context.Context, snapshotID string, body SnapshotForkParams, opts ...option.RequestOption) (res *Instance, err error)

Fork a new instance from a snapshot

func (*SnapshotService) Get added in v0.16.0 

func (r *SnapshotService) Get(ctx context.Context, snapshotID string, opts ...option.RequestOption) (res *Snapshot, err error)

Get snapshot details

func (*SnapshotService) List added in v0.16.0 

func (r *SnapshotService) List(ctx context.Context, query SnapshotListParams, opts ...option.RequestOption) (res *[]Snapshot, err error)

List snapshots

type SnapshotSourceHypervisor added in v0.16.0 

type SnapshotSourceHypervisor string

Source instance hypervisor at snapshot creation time 

const (
	SnapshotSourceHypervisorCloudHypervisor SnapshotSourceHypervisor = "cloud-hypervisor"
	SnapshotSourceHypervisorFirecracker     SnapshotSourceHypervisor = "firecracker"
	SnapshotSourceHypervisorQemu            SnapshotSourceHypervisor = "qemu"
	SnapshotSourceHypervisorVz              SnapshotSourceHypervisor = "vz"
)

type Volume 

type Volume struct {
	// Unique identifier
	ID string `json:"id" api:"required"`
	// Creation timestamp (RFC3339)
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// Volume name
	Name string `json:"name" api:"required"`
	// Size in gigabytes
	SizeGB int64 `json:"size_gb" api:"required"`
	// List of current attachments (empty if not attached)
	Attachments []VolumeAttachment `json:"attachments"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags"`
	// 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
		Tags        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" api:"required"`
	// Mount path in the guest
	MountPath string `json:"mount_path" api:"required"`
	// Whether the attachment is read-only
	Readonly bool `json:"readonly" api:"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 VolumeListParams added in v0.16.0 

type VolumeListParams struct {
	// Filter volumes by tag key-value pairs.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (VolumeListParams) URLQuery added in v0.16.0 

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

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

type VolumeMount 

type VolumeMount struct {
	// Path where volume is mounted in the guest
	MountPath string `json:"mount_path" api:"required"`
	// Volume identifier
	VolumeID string `json:"volume_id" api:"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" api:"required"`
	// Volume identifier
	VolumeID string `json:"volume_id" api:"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 VolumeNewFromArchiveParams added in v0.9.6 

type VolumeNewFromArchiveParams struct {
	// Volume name
	Name string `query:"name" api:"required" json:"-"`
	// Maximum size in GB (extraction fails if content exceeds this)
	SizeGB int64 `query:"size_gb" api:"required" json:"-"`
	// Optional custom volume ID (auto-generated if not provided)
	ID param.Opt[string] `query:"id,omitzero" json:"-"`
	// Tags for the created volume.
	Tags map[string]string `query:"tags,omitzero" json:"-"`
	// contains filtered or unexported fields
}

func (VolumeNewFromArchiveParams) MarshalMultipart added in v0.9.6 

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

func (VolumeNewFromArchiveParams) URLQuery added in v0.9.6 

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

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

type VolumeNewParams 

type VolumeNewParams struct {
	// Volume name
	Name string `json:"name" api:"required"`
	// Size in gigabytes
	SizeGB int64 `json:"size_gb" api:"required"`
	// Optional custom identifier (auto-generated if not provided)
	ID param.Opt[string] `json:"id,omitzero"`
	// User-defined key-value tags.
	Tags map[string]string `json:"tags,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, query VolumeListParams, 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 empty volume of the specified size.

func (*VolumeService) NewFromArchive added in v0.9.6 

func (r *VolumeService) NewFromArchive(ctx context.Context, body io.Reader, params VolumeNewFromArchiveParams, opts ...option.RequestOption) (res *Volume, err error)

Creates a new volume pre-populated with content from a tar.gz archive. The archive is streamed directly into the volume's root directory.

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
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.