hypeman

package module
v0.9.1 Latest Latest
Warning

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

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

README

Hypeman Go API Library

Go Reference

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

It is generated with Stainless.

Installation

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

Or to pin the version:

go get -u 'github.com/kernel/hypeman-go@v0.8.0'

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.

Retries

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

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

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

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

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

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

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

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

Undocumented endpoints

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

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

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

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

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

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

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

Middleware

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

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

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

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

    return res, err
}

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

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

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

Semantic versioning

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

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

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

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

Development

Testing Preview Branches

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

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

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

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

Contributing

See the contributing documentation.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bool 

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

func BoolPtr 

func BoolPtr(v bool) *bool

func DefaultClientOptions 

func DefaultClientOptions() []option.RequestOption

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

func File 

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

func Float 

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

func FloatPtr 

func FloatPtr(v float64) *float64

func Int 

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

func IntPtr 

func IntPtr(v int64) *int64

func Opt 

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

func Ptr 

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

func String 

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

func StringPtr 

func StringPtr(v string) *string

func Time 

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

func TimePtr 

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

Types

type AvailableDevice 

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

func (AvailableDevice) RawJSON 

func (r AvailableDevice) RawJSON() string

Returns the unmodified JSON received from the API

func (*AvailableDevice) UnmarshalJSON 

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

type Client 

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

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

func NewClient 

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

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

func (*Client) Delete 

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

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

func (*Client) Execute 

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

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

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

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

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

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

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

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

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

func (*Client) Get 

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

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

func (*Client) Patch 

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

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

func (*Client) Post 

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

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

func (*Client) Put 

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

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

type Device 

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

func (Device) RawJSON 

func (r Device) RawJSON() string

Returns the unmodified JSON received from the API

func (*Device) UnmarshalJSON 

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

type DeviceNewParams 

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

func (DeviceNewParams) MarshalJSON 

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

func (*DeviceNewParams) UnmarshalJSON 

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

type DeviceService 

type DeviceService struct {
	Options []option.RequestOption
}

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

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

func NewDeviceService 

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

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

func (*DeviceService) Delete 

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

Unregister device

func (*DeviceService) Get 

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

Get device details

func (*DeviceService) List 

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

List registered devices

func (*DeviceService) ListAvailable 

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

Discover passthrough-capable devices on host

func (*DeviceService) New 

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

Register a device for passthrough

type DeviceType 

type DeviceType string

Type of PCI device 

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

type Error 

type Error = apierror.Error

type HealthCheckResponse 

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

func (HealthCheckResponse) RawJSON 

func (r HealthCheckResponse) RawJSON() string

Returns the unmodified JSON received from the API

func (*HealthCheckResponse) UnmarshalJSON 

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

type HealthCheckResponseStatus 

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

type HealthService 

type HealthService struct {
	Options []option.RequestOption
}

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

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

func NewHealthService 

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

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

func (*HealthService) Check 

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

Health check

type Image 

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

func (Image) RawJSON 

func (r Image) RawJSON() string

Returns the unmodified JSON received from the API

func (*Image) UnmarshalJSON 

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

type ImageNewParams 

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

func (ImageNewParams) MarshalJSON 

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

func (*ImageNewParams) UnmarshalJSON 

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

type ImageService 

type ImageService struct {
	Options []option.RequestOption
}

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

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

func NewImageService 

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

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

func (*ImageService) Delete 

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

Delete image

func (*ImageService) Get 

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

Get image details

func (*ImageService) List 

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

List images

func (*ImageService) New 

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

Pull and convert OCI image

type ImageStatus 

type ImageStatus string

Build status 

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

type Ingress 

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

func (Ingress) RawJSON 

func (r Ingress) RawJSON() string

Returns the unmodified JSON received from the API

func (*Ingress) UnmarshalJSON 

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

type IngressMatch 

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

func (IngressMatch) RawJSON 

func (r IngressMatch) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressMatch) ToParam 

func (r IngressMatch) ToParam() IngressMatchParam

ToParam converts this IngressMatch to a IngressMatchParam.

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

func (*IngressMatch) UnmarshalJSON 

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

type IngressMatchParam 

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

The property Hostname is required.

func (IngressMatchParam) MarshalJSON 

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

func (*IngressMatchParam) UnmarshalJSON 

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

type IngressNewParams 

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

func (IngressNewParams) MarshalJSON 

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

func (*IngressNewParams) UnmarshalJSON 

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

type IngressRule 

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

func (IngressRule) RawJSON 

func (r IngressRule) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressRule) ToParam 

func (r IngressRule) ToParam() IngressRuleParam

ToParam converts this IngressRule to a IngressRuleParam.

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

func (*IngressRule) UnmarshalJSON 

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

type IngressRuleParam 

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

The properties Match, Target are required.

func (IngressRuleParam) MarshalJSON 

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

func (*IngressRuleParam) UnmarshalJSON 

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

type IngressService 

type IngressService struct {
	Options []option.RequestOption
}

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

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

func NewIngressService 

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

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

func (*IngressService) Delete 

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

Delete ingress

func (*IngressService) Get 

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

Get ingress details

func (*IngressService) List 

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

List ingresses

func (*IngressService) New 

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

Create ingress

type IngressTarget 

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

func (IngressTarget) RawJSON 

func (r IngressTarget) RawJSON() string

Returns the unmodified JSON received from the API

func (IngressTarget) ToParam 

func (r IngressTarget) ToParam() IngressTargetParam

ToParam converts this IngressTarget to a IngressTargetParam.

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

func (*IngressTarget) UnmarshalJSON 

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

type IngressTargetParam 

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

The properties Instance, Port are required.

func (IngressTargetParam) MarshalJSON 

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

func (*IngressTargetParam) UnmarshalJSON 

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

type Instance 

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

func (Instance) RawJSON 

func (r Instance) RawJSON() string

Returns the unmodified JSON received from the API

func (*Instance) UnmarshalJSON 

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

type 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 {
	// Whether instance is attached to the default network
	Enabled bool `json:"enabled"`
	// Assigned IP address (null if no network)
	IP string `json:"ip,nullable"`
	// Assigned MAC address (null if no network)
	Mac string `json:"mac,nullable"`
	// Network name (always "default" when enabled)
	Name string `json:"name"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Enabled     respjson.Field
		IP          respjson.Field
		Mac         respjson.Field
		Name        respjson.Field
		ExtraFields map[string]respjson.Field
		// contains filtered or unexported fields
	} `json:"-"`
}

Network configuration of the instance

func (InstanceNetwork) RawJSON 

func (r InstanceNetwork) RawJSON() string

Returns the unmodified JSON received from the API

func (*InstanceNetwork) UnmarshalJSON 

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

type InstanceNewParams 

type InstanceNewParams struct {
	// OCI image reference
	Image string `json:"image,required"`
	// Human-readable name (lowercase letters, digits, and dashes only; cannot start or
	// end with a dash)
	Name string `json:"name,required"`
	// Additional memory for hotplug (human-readable format like "3GB", "1G")
	HotplugSize param.Opt[string] `json:"hotplug_size,omitzero"`
	// Writable overlay disk size (human-readable format like "10GB", "50G")
	OverlaySize param.Opt[string] `json:"overlay_size,omitzero"`
	// Base memory size (human-readable format like "1GB", "512MB", "2G")
	Size param.Opt[string] `json:"size,omitzero"`
	// Number of virtual CPUs
	Vcpus param.Opt[int64] `json:"vcpus,omitzero"`
	// Device IDs or names to attach for GPU/PCI passthrough
	Devices []string `json:"devices,omitzero"`
	// Environment variables
	Env map[string]string `json:"env,omitzero"`
	// Network configuration for the instance
	Network InstanceNewParamsNetwork `json:"network,omitzero"`
	// Volumes to attach to the instance at creation time
	Volumes []VolumeMountParam `json:"volumes,omitzero"`
	// contains filtered or unexported fields
}

func (InstanceNewParams) MarshalJSON 

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

func (*InstanceNewParams) UnmarshalJSON 

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

type InstanceNewParamsNetwork 

type InstanceNewParamsNetwork struct {
	// Whether to attach instance to the default network
	Enabled param.Opt[bool] `json:"enabled,omitzero"`
	// contains filtered or unexported fields
}

Network configuration for the instance

func (InstanceNewParamsNetwork) MarshalJSON 

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

func (*InstanceNewParamsNetwork) UnmarshalJSON 

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

type InstanceService 

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

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

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

func NewInstanceService 

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

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

func (*InstanceService) Delete 

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

Stop and delete instance

func (*InstanceService) Get 

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

Get instance details

func (*InstanceService) List 

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

List instances

func (*InstanceService) LogsStreaming 

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

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

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

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

func (*InstanceService) New 

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

Create and start instance

func (*InstanceService) Restore 

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

Restore instance from standby

func (*InstanceService) Standby 

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

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

func (*InstanceService) Start 

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

Start a stopped instance

func (*InstanceService) Stat 

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

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

func (*InstanceService) Stop 

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

Stop instance (graceful shutdown)

type InstanceStatParams 

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

func (InstanceStatParams) URLQuery 

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

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

type InstanceState 

type InstanceState string

Instance state:

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

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

type InstanceVolumeAttachParams 

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

func (InstanceVolumeAttachParams) MarshalJSON 

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

func (*InstanceVolumeAttachParams) UnmarshalJSON 

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

type InstanceVolumeDetachParams 

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

type InstanceVolumeService 

type InstanceVolumeService struct {
	Options []option.RequestOption
}

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

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

func NewInstanceVolumeService 

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

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

func (*InstanceVolumeService) Attach 

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

Attach volume to instance

func (*InstanceVolumeService) Detach 

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

Detach volume from instance

type PathInfo 

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

func (PathInfo) RawJSON 

func (r PathInfo) RawJSON() string

Returns the unmodified JSON received from the API

func (*PathInfo) UnmarshalJSON 

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

type Volume 

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

func (Volume) RawJSON 

func (r Volume) RawJSON() string

Returns the unmodified JSON received from the API

func (*Volume) UnmarshalJSON 

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

type VolumeAttachment 

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

func (VolumeAttachment) RawJSON 

func (r VolumeAttachment) RawJSON() string

Returns the unmodified JSON received from the API

func (*VolumeAttachment) UnmarshalJSON 

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

type VolumeMount 

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

func (VolumeMount) RawJSON 

func (r VolumeMount) RawJSON() string

Returns the unmodified JSON received from the API

func (VolumeMount) ToParam 

func (r VolumeMount) ToParam() VolumeMountParam

ToParam converts this VolumeMount to a VolumeMountParam.

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

func (*VolumeMount) UnmarshalJSON 

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

type VolumeMountParam 

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

The properties MountPath, VolumeID are required.

func (VolumeMountParam) MarshalJSON 

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

func (*VolumeMountParam) UnmarshalJSON 

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

type VolumeNewParams 

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

func (VolumeNewParams) MarshalJSON 

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

func (*VolumeNewParams) UnmarshalJSON 

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

type VolumeService 

type VolumeService struct {
	Options []option.RequestOption
}

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

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

func NewVolumeService 

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

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

func (*VolumeService) Delete 

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

Delete volume

func (*VolumeService) Get 

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

Get volume details

func (*VolumeService) List 

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

List volumes

func (*VolumeService) New 

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

Creates a new volume. Supports two modes:

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

Source Files

View all Source files

Directories

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

Jump to

Keyboard shortcuts

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