instance.go

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

package hypeman

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"slices"
	"time"

	"github.com/kernel/hypeman-go/internal/apijson"
	"github.com/kernel/hypeman-go/internal/apiquery"
	shimjson "github.com/kernel/hypeman-go/internal/encoding/json"
	"github.com/kernel/hypeman-go/internal/requestconfig"
	"github.com/kernel/hypeman-go/option"
	"github.com/kernel/hypeman-go/packages/param"
	"github.com/kernel/hypeman-go/packages/respjson"
	"github.com/kernel/hypeman-go/packages/ssestream"
	"github.com/kernel/hypeman-go/shared"
)

// 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.
type InstanceService struct {
	Options          []option.RequestOption
	AutoStandby      InstanceAutoStandbyService
	Volumes          InstanceVolumeService
	Snapshots        InstanceSnapshotService
	SnapshotSchedule InstanceSnapshotScheduleService
}

// 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 NewInstanceService(opts ...option.RequestOption) (r InstanceService) {
	r = InstanceService{}
	r.Options = opts
	r.AutoStandby = NewInstanceAutoStandbyService(opts...)
	r.Volumes = NewInstanceVolumeService(opts...)
	r.Snapshots = NewInstanceSnapshotService(opts...)
	r.SnapshotSchedule = NewInstanceSnapshotScheduleService(opts...)
	return
}

// Create and start instance
func (r *InstanceService) New(ctx context.Context, body InstanceNewParams, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	path := "instances"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Update mutable instance properties. TTL values are relative to when the update
// is committed. Expiration updates are rejected after the current deadline passes.
func (r *InstanceService) Update(ctx context.Context, id string, body InstanceUpdateParams, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPatch, path, body, &res, opts...)
	return res, err
}

// List instances
func (r *InstanceService) List(ctx context.Context, query InstanceListParams, opts ...option.RequestOption) (res *[]Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	path := "instances"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// Stop and delete instance
func (r *InstanceService) Delete(ctx context.Context, id string, body InstanceDeleteParams, opts ...option.RequestOption) (err error) {
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...)
	if id == "" {
		err = errors.New("missing required id parameter")
		return err
	}
	path := fmt.Sprintf("instances/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodDelete, path, body, nil, opts...)
	return err
}

// Fork an instance from stopped, standby, or running (with from_running=true)
func (r *InstanceService) Fork(ctx context.Context, id string, body InstanceForkParams, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/fork", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Get instance details
func (r *InstanceService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
	return res, err
}

// 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 (r *InstanceService) LogsStreaming(ctx context.Context, id string, query InstanceLogsParams, opts ...option.RequestOption) (stream *ssestream.Stream[string]) {
	var (
		raw *http.Response
		err error
	)
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithHeader("Accept", "text/event-stream")}, opts...)
	if id == "" {
		err = errors.New("missing required id parameter")
		return ssestream.NewStream[string](nil, err)
	}
	path := fmt.Sprintf("instances/%s/logs", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &raw, opts...)
	return ssestream.NewStream[string](ssestream.NewDecoder(raw), err)
}

// Restore instance from standby
func (r *InstanceService) Restore(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/restore", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, nil, &res, opts...)
	return res, err
}

// Put instance in standby (pause, snapshot, delete VMM)
func (r *InstanceService) Standby(ctx context.Context, id string, body InstanceStandbyParams, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/standby", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Start a stopped instance
func (r *InstanceService) Start(ctx context.Context, id string, body InstanceStartParams, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/start", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// 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 (r *InstanceService) Stat(ctx context.Context, id string, query InstanceStatParams, opts ...option.RequestOption) (res *PathInfo, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/stat", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// 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 (r *InstanceService) Stats(ctx context.Context, id string, opts ...option.RequestOption) (res *InstanceStats, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/stats", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
	return res, err
}

// Stop instance (graceful shutdown)
func (r *InstanceService) Stop(ctx context.Context, id string, opts ...option.RequestOption) (res *Instance, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/stop", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, nil, &res, opts...)
	return res, err
}

// Blocks until the instance reaches the specified target state, the timeout
// expires, or the instance enters a terminal/error state. Useful for avoiding
// client-side polling when waiting for state transitions (e.g. waiting for an
// instance to become Running).
func (r *InstanceService) Wait(ctx context.Context, id string, query InstanceWaitParams, opts ...option.RequestOption) (res *WaitForStateResponse, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("instances/%s/wait", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// Linux-only automatic standby policy based on active inbound TCP connections
// observed from the host conntrack table.
type AutoStandbyPolicy struct {
	// Whether automatic standby is enabled for this instance.
	Enabled bool `json:"enabled"`
	// How long the instance must have zero qualifying inbound TCP connections before
	// Hypeman places it into standby.
	IdleTimeout string `json:"idle_timeout"`
	// Optional destination TCP ports that should not keep the instance awake.
	IgnoreDestinationPorts []int64 `json:"ignore_destination_ports"`
	// Optional client CIDRs that should not keep the instance awake.
	IgnoreSourceCidrs []string `json:"ignore_source_cidrs"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Enabled                respjson.Field
		IdleTimeout            respjson.Field
		IgnoreDestinationPorts respjson.Field
		IgnoreSourceCidrs      respjson.Field
		ExtraFields            map[string]respjson.Field
		raw                    string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r AutoStandbyPolicy) RawJSON() string { return r.JSON.raw }
func (r *AutoStandbyPolicy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this AutoStandbyPolicy to a AutoStandbyPolicyParam.
//
// 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
// AutoStandbyPolicyParam.Overrides()
func (r AutoStandbyPolicy) ToParam() AutoStandbyPolicyParam {
	return param.Override[AutoStandbyPolicyParam](json.RawMessage(r.RawJSON()))
}

// Linux-only automatic standby policy based on active inbound TCP connections
// observed from the host conntrack table.
type AutoStandbyPolicyParam struct {
	// Whether automatic standby is enabled for this instance.
	Enabled param.Opt[bool] `json:"enabled,omitzero"`
	// How long the instance must have zero qualifying inbound TCP connections before
	// Hypeman places it into standby.
	IdleTimeout param.Opt[string] `json:"idle_timeout,omitzero"`
	// Optional destination TCP ports that should not keep the instance awake.
	IgnoreDestinationPorts []int64 `json:"ignore_destination_ports,omitzero"`
	// Optional client CIDRs that should not keep the instance awake.
	IgnoreSourceCidrs []string `json:"ignore_source_cidrs,omitzero"`
	paramObj
}

func (r AutoStandbyPolicyParam) MarshalJSON() (data []byte, err error) {
	type shadow AutoStandbyPolicyParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *AutoStandbyPolicyParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type AutoStandbyStatus struct {
	// Number of currently tracked qualifying inbound TCP connections.
	ActiveInboundConnections int64 `json:"active_inbound_connections" api:"required"`
	// Whether the instance has any auto-standby policy configured.
	Configured bool `json:"configured" api:"required"`
	// Whether the instance is currently eligible to enter standby.
	Eligible bool `json:"eligible" api:"required"`
	// Whether the configured auto-standby policy is enabled.
	Enabled bool `json:"enabled" api:"required"`
	// Any of "unsupported_platform", "policy_missing", "policy_disabled",
	// "instance_not_running", "network_disabled", "missing_ip", "has_vgpu",
	// "active_inbound_connections", "idle_timeout_not_elapsed", "observer_error",
	// "ready_for_standby".
	Reason AutoStandbyStatusReason `json:"reason" api:"required"`
	// Any of "unsupported", "disabled", "ineligible", "active", "idle_countdown",
	// "ready_for_standby", "standby_requested", "error".
	Status AutoStandbyStatusStatus `json:"status" api:"required"`
	// Whether the current host platform supports auto-standby diagnostics.
	Supported bool `json:"supported" api:"required"`
	// Diagnostic identifier for the runtime tracking mode in use.
	TrackingMode string `json:"tracking_mode" api:"required"`
	// Remaining time before the controller attempts standby, when applicable.
	CountdownRemaining string `json:"countdown_remaining" api:"nullable"`
	// Until when auto-standby is held off, if a hold is active.
	HoldUntil time.Time `json:"hold_until" api:"nullable" format:"date-time"`
	// When the controller most recently observed the instance become idle.
	IdleSince time.Time `json:"idle_since" api:"nullable" format:"date-time"`
	// Configured idle timeout from the auto-standby policy.
	IdleTimeout string `json:"idle_timeout" api:"nullable"`
	// Timestamp of the most recent qualifying inbound TCP activity the controller
	// observed.
	LastInboundActivityAt time.Time `json:"last_inbound_activity_at" api:"nullable" format:"date-time"`
	// When the controller expects to attempt standby next, if a countdown is active.
	NextStandbyAt time.Time `json:"next_standby_at" api:"nullable" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ActiveInboundConnections respjson.Field
		Configured               respjson.Field
		Eligible                 respjson.Field
		Enabled                  respjson.Field
		Reason                   respjson.Field
		Status                   respjson.Field
		Supported                respjson.Field
		TrackingMode             respjson.Field
		CountdownRemaining       respjson.Field
		HoldUntil                respjson.Field
		IdleSince                respjson.Field
		IdleTimeout              respjson.Field
		LastInboundActivityAt    respjson.Field
		NextStandbyAt            respjson.Field
		ExtraFields              map[string]respjson.Field
		raw                      string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r AutoStandbyStatus) RawJSON() string { return r.JSON.raw }
func (r *AutoStandbyStatus) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type AutoStandbyStatusReason string

const (
	AutoStandbyStatusReasonUnsupportedPlatform      AutoStandbyStatusReason = "unsupported_platform"
	AutoStandbyStatusReasonPolicyMissing            AutoStandbyStatusReason = "policy_missing"
	AutoStandbyStatusReasonPolicyDisabled           AutoStandbyStatusReason = "policy_disabled"
	AutoStandbyStatusReasonInstanceNotRunning       AutoStandbyStatusReason = "instance_not_running"
	AutoStandbyStatusReasonNetworkDisabled          AutoStandbyStatusReason = "network_disabled"
	AutoStandbyStatusReasonMissingIP                AutoStandbyStatusReason = "missing_ip"
	AutoStandbyStatusReasonHasVgpu                  AutoStandbyStatusReason = "has_vgpu"
	AutoStandbyStatusReasonActiveInboundConnections AutoStandbyStatusReason = "active_inbound_connections"
	AutoStandbyStatusReasonIdleTimeoutNotElapsed    AutoStandbyStatusReason = "idle_timeout_not_elapsed"
	AutoStandbyStatusReasonObserverError            AutoStandbyStatusReason = "observer_error"
	AutoStandbyStatusReasonReadyForStandby          AutoStandbyStatusReason = "ready_for_standby"
)

type AutoStandbyStatusStatus string

const (
	AutoStandbyStatusStatusUnsupported      AutoStandbyStatusStatus = "unsupported"
	AutoStandbyStatusStatusDisabled         AutoStandbyStatusStatus = "disabled"
	AutoStandbyStatusStatusIneligible       AutoStandbyStatusStatus = "ineligible"
	AutoStandbyStatusStatusActive           AutoStandbyStatusStatus = "active"
	AutoStandbyStatusStatusIdleCountdown    AutoStandbyStatusStatus = "idle_countdown"
	AutoStandbyStatusStatusReadyForStandby  AutoStandbyStatusStatus = "ready_for_standby"
	AutoStandbyStatusStatusStandbyRequested AutoStandbyStatusStatus = "standby_requested"
	AutoStandbyStatusStatusError            AutoStandbyStatusStatus = "error"
)

// Workload health check policy. Health is reported separately from instance
// lifecycle state.
type HealthCheck struct {
	Exec HealthCheckExec `json:"exec"`
	// Consecutive failed checks required to mark the workload unhealthy.
	FailureThreshold int64           `json:"failure_threshold"`
	HTTP             HealthCheckHTTP `json:"http"`
	// Delay between checks as a Go duration.
	Interval string `json:"interval"`
	// Startup grace period before failures can mark the workload unhealthy.
	StartPeriod string `json:"start_period"`
	// Consecutive successful checks required to mark the workload healthy.
	SuccessThreshold int64          `json:"success_threshold"`
	Tcp              HealthCheckTcp `json:"tcp"`
	// Per-check timeout as a Go duration.
	Timeout string `json:"timeout"`
	// Probe type. Omit health_check or set type=none to disable health checks.
	//
	// Any of "none", "http", "tcp", "exec".
	Type HealthCheckType `json:"type"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Exec             respjson.Field
		FailureThreshold respjson.Field
		HTTP             respjson.Field
		Interval         respjson.Field
		StartPeriod      respjson.Field
		SuccessThreshold respjson.Field
		Tcp              respjson.Field
		Timeout          respjson.Field
		Type             respjson.Field
		ExtraFields      map[string]respjson.Field
		raw              string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r HealthCheck) RawJSON() string { return r.JSON.raw }
func (r *HealthCheck) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this HealthCheck to a HealthCheckParam.
//
// 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
// HealthCheckParam.Overrides()
func (r HealthCheck) ToParam() HealthCheckParam {
	return param.Override[HealthCheckParam](json.RawMessage(r.RawJSON()))
}

// Probe type. Omit health_check or set type=none to disable health checks.
type HealthCheckType string

const (
	HealthCheckTypeNone HealthCheckType = "none"
	HealthCheckTypeHTTP HealthCheckType = "http"
	HealthCheckTypeTcp  HealthCheckType = "tcp"
	HealthCheckTypeExec HealthCheckType = "exec"
)

// Workload health check policy. Health is reported separately from instance
// lifecycle state.
type HealthCheckParam struct {
	// Consecutive failed checks required to mark the workload unhealthy.
	FailureThreshold param.Opt[int64] `json:"failure_threshold,omitzero"`
	// Delay between checks as a Go duration.
	Interval param.Opt[string] `json:"interval,omitzero"`
	// Startup grace period before failures can mark the workload unhealthy.
	StartPeriod param.Opt[string] `json:"start_period,omitzero"`
	// Consecutive successful checks required to mark the workload healthy.
	SuccessThreshold param.Opt[int64] `json:"success_threshold,omitzero"`
	// Per-check timeout as a Go duration.
	Timeout param.Opt[string]    `json:"timeout,omitzero"`
	Exec    HealthCheckExecParam `json:"exec,omitzero"`
	HTTP    HealthCheckHTTPParam `json:"http,omitzero"`
	Tcp     HealthCheckTcpParam  `json:"tcp,omitzero"`
	// Probe type. Omit health_check or set type=none to disable health checks.
	//
	// Any of "none", "http", "tcp", "exec".
	Type HealthCheckType `json:"type,omitzero"`
	paramObj
}

func (r HealthCheckParam) MarshalJSON() (data []byte, err error) {
	type shadow HealthCheckParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *HealthCheckParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type HealthCheckExec struct {
	// Command and arguments to run inside the guest after guest-agent readiness.
	Command []string `json:"command" api:"required"`
	// Optional working directory for the command.
	WorkingDir string `json:"working_dir"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Command     respjson.Field
		WorkingDir  respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r HealthCheckExec) RawJSON() string { return r.JSON.raw }
func (r *HealthCheckExec) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this HealthCheckExec to a HealthCheckExecParam.
//
// 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
// HealthCheckExecParam.Overrides()
func (r HealthCheckExec) ToParam() HealthCheckExecParam {
	return param.Override[HealthCheckExecParam](json.RawMessage(r.RawJSON()))
}

// The property Command is required.
type HealthCheckExecParam struct {
	// Command and arguments to run inside the guest after guest-agent readiness.
	Command []string `json:"command,omitzero" api:"required"`
	// Optional working directory for the command.
	WorkingDir param.Opt[string] `json:"working_dir,omitzero"`
	paramObj
}

func (r HealthCheckExecParam) MarshalJSON() (data []byte, err error) {
	type shadow HealthCheckExecParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *HealthCheckExecParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type HealthCheckHTTP struct {
	// Port to probe on the instance network address.
	Port int64 `json:"port" api:"required"`
	// Exact status code required for a successful probe.
	ExpectedStatus int64 `json:"expected_status"`
	// HTTP path to request.
	Path string `json:"path"`
	// HTTP scheme to use for the probe.
	//
	// Any of "http", "https".
	Scheme HealthCheckHTTPScheme `json:"scheme"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Port           respjson.Field
		ExpectedStatus respjson.Field
		Path           respjson.Field
		Scheme         respjson.Field
		ExtraFields    map[string]respjson.Field
		raw            string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r HealthCheckHTTP) RawJSON() string { return r.JSON.raw }
func (r *HealthCheckHTTP) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this HealthCheckHTTP to a HealthCheckHTTPParam.
//
// 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
// HealthCheckHTTPParam.Overrides()
func (r HealthCheckHTTP) ToParam() HealthCheckHTTPParam {
	return param.Override[HealthCheckHTTPParam](json.RawMessage(r.RawJSON()))
}

// HTTP scheme to use for the probe.
type HealthCheckHTTPScheme string

const (
	HealthCheckHTTPSchemeHTTP  HealthCheckHTTPScheme = "http"
	HealthCheckHTTPSchemeHTTPS HealthCheckHTTPScheme = "https"
)

// The property Port is required.
type HealthCheckHTTPParam struct {
	// Port to probe on the instance network address.
	Port int64 `json:"port" api:"required"`
	// Exact status code required for a successful probe.
	ExpectedStatus param.Opt[int64] `json:"expected_status,omitzero"`
	// HTTP path to request.
	Path param.Opt[string] `json:"path,omitzero"`
	// HTTP scheme to use for the probe.
	//
	// Any of "http", "https".
	Scheme HealthCheckHTTPScheme `json:"scheme,omitzero"`
	paramObj
}

func (r HealthCheckHTTPParam) MarshalJSON() (data []byte, err error) {
	type shadow HealthCheckHTTPParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *HealthCheckHTTPParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type HealthCheckTcp struct {
	// Port to open on the instance network address.
	Port int64 `json:"port" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Port        respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r HealthCheckTcp) RawJSON() string { return r.JSON.raw }
func (r *HealthCheckTcp) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this HealthCheckTcp to a HealthCheckTcpParam.
//
// 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
// HealthCheckTcpParam.Overrides()
func (r HealthCheckTcp) ToParam() HealthCheckTcpParam {
	return param.Override[HealthCheckTcpParam](json.RawMessage(r.RawJSON()))
}

// The property Port is required.
type HealthCheckTcpParam struct {
	// Port to open on the instance network address.
	Port int64 `json:"port" api:"required"`
	paramObj
}

func (r HealthCheckTcpParam) MarshalJSON() (data []byte, err error) {
	type shadow HealthCheckTcpParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *HealthCheckTcpParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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"`
	// Absolute expiration time, or null when automatic expiration is disabled.
	// Instance TTL is cleared on fork.
	ExpiresAt time.Time `json:"expires_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"`
	// Linux-only automatic standby policy based on active inbound TCP connections
	// observed from the host conntrack table.
	AutoStandby AutoStandbyPolicy `json:"auto_standby"`
	// The lifecycle phase the instance is currently in.
	CurrentPhase string `json:"current_phase"`
	// When the instance entered current_phase.
	CurrentPhaseSince time.Time `json:"current_phase_since" format:"date-time"`
	// 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"`
	// Workload health check policy. Health is reported separately from instance
	// lifecycle state.
	HealthCheck  HealthCheck          `json:"health_check"`
	HealthStatus InstanceHealthStatus `json:"health_status"`
	// Hotplug memory size (human-readable)
	HotplugSize string `json:"hotplug_size"`
	// Hypervisor backend running this instance
	//
	// Any of "cloud-hypervisor", "firecracker", "qemu", "qemu-microvm", "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"`
	// Cumulative milliseconds the instance has spent in each lifecycle phase,
	// including time accrued in the current phase up to the response time. Keys mirror
	// instance states lowercased (running, standby, paused, stopped, created,
	// initializing, shutdown). Consumers (e.g. billing) sum the phases they consider
	// billable.
	PhaseDurationsMs map[string]int64 `json:"phase_durations_ms"`
	// Resolved image platform as os/arch[/variant] (e.g. "linux/amd64"). amd64 images
	// on an arm64 host run under Rosetta emulation.
	Platform string `json:"platform"`
	// Whole-instance restart supervision policy.
	RestartPolicy RestartPolicy `json:"restart_policy"`
	// Runtime status for restart policy decisions.
	RestartStatus RestartStatus `json:"restart_status"`
	// 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
		ExpiresAt         respjson.Field
		Image             respjson.Field
		Name              respjson.Field
		State             respjson.Field
		AutoStandby       respjson.Field
		CurrentPhase      respjson.Field
		CurrentPhaseSince respjson.Field
		DiskIoBps         respjson.Field
		Env               respjson.Field
		ExitCode          respjson.Field
		ExitMessage       respjson.Field
		GPU               respjson.Field
		HasSnapshot       respjson.Field
		HealthCheck       respjson.Field
		HealthStatus      respjson.Field
		HotplugSize       respjson.Field
		Hypervisor        respjson.Field
		Network           respjson.Field
		OverlaySize       respjson.Field
		PhaseDurationsMs  respjson.Field
		Platform          respjson.Field
		RestartPolicy     respjson.Field
		RestartStatus     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
		raw               string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r Instance) RawJSON() string { return r.JSON.raw }
func (r *Instance) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// 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)
type InstanceState string

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

// GPU information attached to the instance
type InstanceGPU struct {
	// sysfs path of the assigned vGPU device
	DevicePath string `json:"device_path"`
	// mdev device UUID (mdev hosts only)
	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 {
		DevicePath  respjson.Field
		MdevUuid    respjson.Field
		Profile     respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r InstanceGPU) RawJSON() string { return r.JSON.raw }
func (r *InstanceGPU) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Hypervisor backend running this instance
type InstanceHypervisor string

const (
	InstanceHypervisorCloudHypervisor InstanceHypervisor = "cloud-hypervisor"
	InstanceHypervisorFirecracker     InstanceHypervisor = "firecracker"
	InstanceHypervisorQemu            InstanceHypervisor = "qemu"
	InstanceHypervisorQemuMicrovm     InstanceHypervisor = "qemu-microvm"
	InstanceHypervisorVz              InstanceHypervisor = "vz"
)

// Network configuration of the instance
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
		raw               string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r InstanceNetwork) RawJSON() string { return r.JSON.raw }
func (r *InstanceNetwork) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type InstanceHealthStatus struct {
	// Consecutive failed checks in the current health window.
	ConsecutiveFailures int64 `json:"consecutive_failures" api:"required"`
	// Consecutive successful checks in the current health window.
	ConsecutiveSuccesses int64 `json:"consecutive_successes" api:"required"`
	// Current workload health status.
	//
	// Any of "disabled", "starting", "healthy", "unhealthy", "unknown".
	Status InstanceHealthStatusStatus `json:"status" api:"required"`
	// Most recent check completion time.
	LastCheckedAt time.Time `json:"last_checked_at" api:"nullable" format:"date-time"`
	// Truncated error from the most recent failed check.
	LastError string `json:"last_error" api:"nullable"`
	// Most recent failed check completion time.
	LastFailureAt time.Time `json:"last_failure_at" api:"nullable" format:"date-time"`
	// Most recent successful check completion time.
	LastSuccessAt time.Time `json:"last_success_at" api:"nullable" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ConsecutiveFailures  respjson.Field
		ConsecutiveSuccesses respjson.Field
		Status               respjson.Field
		LastCheckedAt        respjson.Field
		LastError            respjson.Field
		LastFailureAt        respjson.Field
		LastSuccessAt        respjson.Field
		ExtraFields          map[string]respjson.Field
		raw                  string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r InstanceHealthStatus) RawJSON() string { return r.JSON.raw }
func (r *InstanceHealthStatus) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Current workload health status.
type InstanceHealthStatusStatus string

const (
	InstanceHealthStatusStatusDisabled  InstanceHealthStatusStatus = "disabled"
	InstanceHealthStatusStatusStarting  InstanceHealthStatusStatus = "starting"
	InstanceHealthStatusStatusHealthy   InstanceHealthStatusStatus = "healthy"
	InstanceHealthStatusStatusUnhealthy InstanceHealthStatusStatus = "unhealthy"
	InstanceHealthStatusStatusUnknown   InstanceHealthStatusStatus = "unknown"
)

// Real-time resource utilization statistics for a VM instance
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). Always 0 for macOS
	// guests, which use NAT with no per-instance 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
		raw                    string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r InstanceStats) RawJSON() string { return r.JSON.raw }
func (r *InstanceStats) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r PathInfo) RawJSON() string { return r.JSON.raw }
func (r *PathInfo) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Whole-instance restart supervision policy.
type RestartPolicy struct {
	// Delay before each restart attempt, expressed as a Go duration like "5s" or "1m".
	Backoff string `json:"backoff"`
	// Consecutive automatic restart attempts before blocking retries. 0 means
	// unlimited.
	MaxAttempts int64 `json:"max_attempts"`
	// Restart behavior when the guest program exits:
	//
	// - never: do not automatically restart
	// - always: restart after any guest exit
	// - on_failure: restart only for nonzero, signaled, OOM, or unknown exits
	//
	// Any of "never", "always", "on_failure".
	Policy RestartPolicyPolicy `json:"policy"`
	// Running this long resets the consecutive restart attempt count.
	StableAfter string `json:"stable_after"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Backoff     respjson.Field
		MaxAttempts respjson.Field
		Policy      respjson.Field
		StableAfter respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r RestartPolicy) RawJSON() string { return r.JSON.raw }
func (r *RestartPolicy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this RestartPolicy to a RestartPolicyParam.
//
// 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
// RestartPolicyParam.Overrides()
func (r RestartPolicy) ToParam() RestartPolicyParam {
	return param.Override[RestartPolicyParam](json.RawMessage(r.RawJSON()))
}

// Restart behavior when the guest program exits:
//
// - never: do not automatically restart
// - always: restart after any guest exit
// - on_failure: restart only for nonzero, signaled, OOM, or unknown exits
type RestartPolicyPolicy string

const (
	RestartPolicyPolicyNever     RestartPolicyPolicy = "never"
	RestartPolicyPolicyAlways    RestartPolicyPolicy = "always"
	RestartPolicyPolicyOnFailure RestartPolicyPolicy = "on_failure"
)

// Whole-instance restart supervision policy.
type RestartPolicyParam struct {
	// Delay before each restart attempt, expressed as a Go duration like "5s" or "1m".
	Backoff param.Opt[string] `json:"backoff,omitzero"`
	// Consecutive automatic restart attempts before blocking retries. 0 means
	// unlimited.
	MaxAttempts param.Opt[int64] `json:"max_attempts,omitzero"`
	// Running this long resets the consecutive restart attempt count.
	StableAfter param.Opt[string] `json:"stable_after,omitzero"`
	// Restart behavior when the guest program exits:
	//
	// - never: do not automatically restart
	// - always: restart after any guest exit
	// - on_failure: restart only for nonzero, signaled, OOM, or unknown exits
	//
	// Any of "never", "always", "on_failure".
	Policy RestartPolicyPolicy `json:"policy,omitzero"`
	paramObj
}

func (r RestartPolicyParam) MarshalJSON() (data []byte, err error) {
	type shadow RestartPolicyParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *RestartPolicyParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Runtime status for restart policy decisions.
type RestartStatus struct {
	// Consecutive automatic restart attempts in the current failure window.
	Attempts int64 `json:"attempts"`
	// Reason automatic restarts are currently blocked.
	//
	// Any of "manual_stop", "max_attempts_exceeded".
	BlockedReason RestartStatusBlockedReason `json:"blocked_reason" api:"nullable"`
	// Last time Hypeman attempted an automatic restart.
	LastAttemptAt time.Time `json:"last_attempt_at" api:"nullable" format:"date-time"`
	// Most recent non-exit failure signal that entered restart policy.
	//
	// Any of "health_check_failed".
	LastReason RestartStatusLastReason `json:"last_reason" api:"nullable"`
	// Next scheduled automatic restart attempt after backoff.
	NextAttemptAt time.Time `json:"next_attempt_at" api:"nullable" format:"date-time"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Attempts      respjson.Field
		BlockedReason respjson.Field
		LastAttemptAt respjson.Field
		LastReason    respjson.Field
		NextAttemptAt respjson.Field
		ExtraFields   map[string]respjson.Field
		raw           string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r RestartStatus) RawJSON() string { return r.JSON.raw }
func (r *RestartStatus) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Reason automatic restarts are currently blocked.
type RestartStatusBlockedReason string

const (
	RestartStatusBlockedReasonManualStop          RestartStatusBlockedReason = "manual_stop"
	RestartStatusBlockedReasonMaxAttemptsExceeded RestartStatusBlockedReason = "max_attempts_exceeded"
)

// Most recent non-exit failure signal that entered restart policy.
type RestartStatusLastReason string

const (
	RestartStatusLastReasonHealthCheckFailed RestartStatusLastReason = "health_check_failed"
)

// The properties Interval, Retention are required.
type SetSnapshotScheduleRequestParam struct {
	// Snapshot interval (Go duration format, minimum 1m).
	Interval string `json:"interval" api:"required"`
	// At least one of max_count or max_age must be provided.
	Retention SnapshotScheduleRetentionParam `json:"retention,omitzero" api:"required"`
	// Optional prefix for auto-generated scheduled snapshot names (max 47 chars).
	NamePrefix param.Opt[string] `json:"name_prefix,omitzero"`
	// User-defined key-value tags.
	Metadata map[string]string `json:"metadata,omitzero"`
	paramObj
}

func (r SetSnapshotScheduleRequestParam) MarshalJSON() (data []byte, err error) {
	type shadow SetSnapshotScheduleRequestParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *SetSnapshotScheduleRequestParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type SnapshotPolicy struct {
	Compression shared.SnapshotCompressionConfig `json:"compression"`
	// Delay before standby snapshot compression begins, expressed as a Go duration
	// like "30s" or "5m". Applies only to standby compression and defaults to
	// immediate start when omitted.
	StandbyCompressionDelay string `json:"standby_compression_delay"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Compression             respjson.Field
		StandbyCompressionDelay respjson.Field
		ExtraFields             map[string]respjson.Field
		raw                     string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r SnapshotPolicy) RawJSON() string { return r.JSON.raw }
func (r *SnapshotPolicy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// 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 (r SnapshotPolicy) ToParam() SnapshotPolicyParam {
	return param.Override[SnapshotPolicyParam](json.RawMessage(r.RawJSON()))
}

type SnapshotPolicyParam struct {
	// Delay before standby snapshot compression begins, expressed as a Go duration
	// like "30s" or "5m". Applies only to standby compression and defaults to
	// immediate start when omitted.
	StandbyCompressionDelay param.Opt[string]                     `json:"standby_compression_delay,omitzero"`
	Compression             shared.SnapshotCompressionConfigParam `json:"compression,omitzero"`
	paramObj
}

func (r SnapshotPolicyParam) MarshalJSON() (data []byte, err error) {
	type shadow SnapshotPolicyParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *SnapshotPolicyParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type SnapshotSchedule struct {
	// Schedule creation timestamp.
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// Source instance ID.
	InstanceID string `json:"instance_id" api:"required"`
	// Snapshot interval (Go duration format).
	Interval string `json:"interval" api:"required"`
	// Next scheduled run time.
	NextRunAt time.Time `json:"next_run_at" api:"required" format:"date-time"`
	// Automatic cleanup policy for scheduled snapshots.
	Retention SnapshotScheduleRetention `json:"retention" api:"required"`
	// Schedule update timestamp.
	UpdatedAt time.Time `json:"updated_at" api:"required" format:"date-time"`
	// Last schedule run error, if any.
	LastError string `json:"last_error" api:"nullable"`
	// Last schedule execution time.
	LastRunAt time.Time `json:"last_run_at" api:"nullable" format:"date-time"`
	// Snapshot ID produced by the last successful run.
	LastSnapshotID string `json:"last_snapshot_id" api:"nullable"`
	// User-defined key-value tags.
	Metadata map[string]string `json:"metadata"`
	// Optional prefix used for generated scheduled snapshot names.
	NamePrefix string `json:"name_prefix" api:"nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		CreatedAt      respjson.Field
		InstanceID     respjson.Field
		Interval       respjson.Field
		NextRunAt      respjson.Field
		Retention      respjson.Field
		UpdatedAt      respjson.Field
		LastError      respjson.Field
		LastRunAt      respjson.Field
		LastSnapshotID respjson.Field
		Metadata       respjson.Field
		NamePrefix     respjson.Field
		ExtraFields    map[string]respjson.Field
		raw            string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r SnapshotSchedule) RawJSON() string { return r.JSON.raw }
func (r *SnapshotSchedule) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Automatic cleanup policy for scheduled snapshots.
type SnapshotScheduleRetention struct {
	// Delete scheduled snapshots older than this duration (Go duration format).
	MaxAge string `json:"max_age"`
	// Keep at most this many scheduled snapshots for the instance (0 disables
	// count-based cleanup).
	MaxCount int64 `json:"max_count"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		MaxAge      respjson.Field
		MaxCount    respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r SnapshotScheduleRetention) RawJSON() string { return r.JSON.raw }
func (r *SnapshotScheduleRetention) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// ToParam converts this SnapshotScheduleRetention to a
// SnapshotScheduleRetentionParam.
//
// 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
// SnapshotScheduleRetentionParam.Overrides()
func (r SnapshotScheduleRetention) ToParam() SnapshotScheduleRetentionParam {
	return param.Override[SnapshotScheduleRetentionParam](json.RawMessage(r.RawJSON()))
}

// Automatic cleanup policy for scheduled snapshots.
type SnapshotScheduleRetentionParam struct {
	// Delete scheduled snapshots older than this duration (Go duration format).
	MaxAge param.Opt[string] `json:"max_age,omitzero"`
	// Keep at most this many scheduled snapshots for the instance (0 disables
	// count-based cleanup).
	MaxCount param.Opt[int64] `json:"max_count,omitzero"`
	paramObj
}

func (r SnapshotScheduleRetentionParam) MarshalJSON() (data []byte, err error) {
	type shadow SnapshotScheduleRetentionParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *SnapshotScheduleRetentionParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type StandbyInstanceRequestParam struct {
	// Delay before standby snapshot compression begins, expressed as a Go duration
	// like "30s" or "5m". Overrides the instance default for this standby operation
	// only.
	CompressionDelay param.Opt[string] `json:"compression_delay,omitzero"`
	// Compression settings for standby snapshot memory. Overrides instance defaults.
	Compression shared.SnapshotCompressionConfigParam `json:"compression,omitzero"`
	paramObj
}

func (r StandbyInstanceRequestParam) MarshalJSON() (data []byte, err error) {
	type shadow StandbyInstanceRequestParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *StandbyInstanceRequestParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r VolumeMount) RawJSON() string { return r.JSON.raw }
func (r *VolumeMount) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// 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 (r VolumeMount) ToParam() VolumeMountParam {
	return param.Override[VolumeMountParam](json.RawMessage(r.RawJSON()))
}

// The properties MountPath, VolumeID are required.
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"`
	paramObj
}

func (r VolumeMountParam) MarshalJSON() (data []byte, err error) {
	type shadow VolumeMountParam
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *VolumeMountParam) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type WaitForStateResponse struct {
	// Current instance state when the wait completed
	//
	// Any of "Created", "Initializing", "Running", "Paused", "Shutdown", "Stopped",
	// "Standby", "Unknown".
	State WaitForStateResponseState `json:"state" api:"required"`
	// Whether the timeout expired before the target state was reached
	TimedOut bool `json:"timed_out" api:"required"`
	// Error message when derived state is Unknown
	StateError string `json:"state_error" api:"nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		State       respjson.Field
		TimedOut    respjson.Field
		StateError  respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r WaitForStateResponse) RawJSON() string { return r.JSON.raw }
func (r *WaitForStateResponse) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Current instance state when the wait completed
type WaitForStateResponseState string

const (
	WaitForStateResponseStateCreated      WaitForStateResponseState = "Created"
	WaitForStateResponseStateInitializing WaitForStateResponseState = "Initializing"
	WaitForStateResponseStateRunning      WaitForStateResponseState = "Running"
	WaitForStateResponseStatePaused       WaitForStateResponseState = "Paused"
	WaitForStateResponseStateShutdown     WaitForStateResponseState = "Shutdown"
	WaitForStateResponseStateStopped      WaitForStateResponseState = "Stopped"
	WaitForStateResponseStateStandby      WaitForStateResponseState = "Standby"
	WaitForStateResponseStateUnknown      WaitForStateResponseState = "Unknown"
)

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"`
	// Absolute expiration time. Must be in the future and is mutually exclusive with
	// ttl.
	ExpiresAt param.Opt[time.Time] `json:"expires_at,omitzero" format:"date-time"`
	// 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"). Omit this
	// field for macOS guests, which clone the image's complete boot disk instead.
	OverlaySize param.Opt[string] `json:"overlay_size,omitzero"`
	// Target platform as os/arch[/variant]. Linux container guests support amd64 and
	// arm64. Experimental darwin/arm64 guests require an offline-imported macOS disk
	// image and vz on Apple silicon. Omit to use the cached native image or host
	// platform.
	Platform param.Opt[string] `json:"platform,omitzero"`
	// Base memory size (human-readable format like "1GB", "512MB", "2G"). macOS guests
	// default to their image's memory; explicit sizes must be at least 4 GiB in whole
	// MiB and within VZ host limits.
	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"`
	// Relative lifetime from instance creation, in Go duration format. Use "0s" or
	// omit both expiration fields to disable automatic expiration. Mutually exclusive
	// with expires_at.
	Ttl param.Opt[string] `json:"ttl,omitzero"`
	// Number of virtual CPUs. macOS guests default to their image's vCPUs; explicit
	// counts must be at least 2 and within VZ host limits.
	Vcpus param.Opt[int64] `json:"vcpus,omitzero"`
	// Linux-only automatic standby policy based on active inbound TCP connections
	// observed from the host conntrack table.
	AutoStandby AutoStandbyPolicyParam `json:"auto_standby,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"`
	// Workload health check policy. Health is reported separately from instance
	// lifecycle state.
	HealthCheck HealthCheckParam `json:"health_check,omitzero"`
	// Hypervisor backend to use for this instance. qemu uses the architecture-native
	// standard board; qemu-microvm uses QEMU's minimal Linux amd64 board and does not
	// support PCI devices, hotplug memory, or more than eight virtio-mmio devices.
	// Defaults to server configuration.
	//
	// Any of "cloud-hypervisor", "firecracker", "qemu", "qemu-microvm", "vz".
	Hypervisor InstanceNewParamsHypervisor `json:"hypervisor,omitzero"`
	// Network configuration for the instance
	Network InstanceNewParamsNetwork `json:"network,omitzero"`
	// Whole-instance restart supervision policy.
	RestartPolicy RestartPolicyParam `json:"restart_policy,omitzero"`
	// Snapshot policy for this instance. Controls compression settings applied when
	// creating snapshots or entering standby, plus any default standby-only
	// compression delay.
	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"`
	paramObj
}

func (r InstanceNewParams) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// The properties Inject, Source are required.
type InstanceNewParamsCredential struct {
	Inject []InstanceNewParamsCredentialInject `json:"inject,omitzero" api:"required"`
	Source InstanceNewParamsCredentialSource   `json:"source,omitzero" api:"required"`
	paramObj
}

func (r InstanceNewParamsCredential) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsCredential
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsCredential) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// The property As is required.
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"`
	paramObj
}

func (r InstanceNewParamsCredentialInject) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsCredentialInject
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsCredentialInject) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// 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.
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"`
	paramObj
}

func (r InstanceNewParamsCredentialInjectAs) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsCredentialInjectAs
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsCredentialInjectAs) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// The property Env is required.
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"`
	paramObj
}

func (r InstanceNewParamsCredentialSource) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsCredentialSource
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsCredentialSource) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// GPU configuration for the instance
type InstanceNewParamsGPU struct {
	// vGPU profile name (e.g., "L40S-1Q"). Only used in vGPU mode.
	Profile param.Opt[string] `json:"profile,omitzero"`
	paramObj
}

func (r InstanceNewParamsGPU) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsGPU
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsGPU) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Hypervisor backend to use for this instance. qemu uses the architecture-native
// standard board; qemu-microvm uses QEMU's minimal Linux amd64 board and does not
// support PCI devices, hotplug memory, or more than eight virtio-mmio devices.
// Defaults to server configuration.
type InstanceNewParamsHypervisor string

const (
	InstanceNewParamsHypervisorCloudHypervisor InstanceNewParamsHypervisor = "cloud-hypervisor"
	InstanceNewParamsHypervisorFirecracker     InstanceNewParamsHypervisor = "firecracker"
	InstanceNewParamsHypervisorQemu            InstanceNewParamsHypervisor = "qemu"
	InstanceNewParamsHypervisorQemuMicrovm     InstanceNewParamsHypervisor = "qemu-microvm"
	InstanceNewParamsHypervisorVz              InstanceNewParamsHypervisor = "vz"
)

// Network configuration for the instance
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"`
	paramObj
}

func (r InstanceNewParamsNetwork) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsNetwork
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsNetwork) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Host-mediated outbound network policy. Omit this object, or set
// `enabled: false`, to preserve normal direct outbound networking when
// `network.enabled` is true.
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"`
	paramObj
}

func (r InstanceNewParamsNetworkEgress) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsNetworkEgress
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsNetworkEgress) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Egress enforcement policy applied when mediation is enabled.
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"`
	paramObj
}

func (r InstanceNewParamsNetworkEgressEnforcement) MarshalJSON() (data []byte, err error) {
	type shadow InstanceNewParamsNetworkEgressEnforcement
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceNewParamsNetworkEgressEnforcement) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

func init() {
	apijson.RegisterFieldValidator[InstanceNewParamsNetworkEgressEnforcement](
		"mode", "all", "http_https_only",
	)
}

type InstanceUpdateParams struct {
	// Absolute expiration time. Must be in the future and is mutually exclusive with
	// ttl.
	ExpiresAt param.Opt[time.Time] `json:"expires_at,omitzero" format:"date-time"`
	// Relative lifetime from when this update is committed, in Go duration format. Use
	// "0s" to disable automatic expiration. Mutually exclusive with expires_at.
	Ttl param.Opt[string] `json:"ttl,omitzero"`
	// Linux-only automatic standby policy based on active inbound TCP connections
	// observed from the host conntrack table.
	AutoStandby AutoStandbyPolicyParam `json:"auto_standby,omitzero"`
	// 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"`
	// Workload health check policy. Health is reported separately from instance
	// lifecycle state.
	HealthCheck HealthCheckParam `json:"health_check,omitzero"`
	// Whole-instance restart supervision policy.
	RestartPolicy RestartPolicyParam `json:"restart_policy,omitzero"`
	paramObj
}

func (r InstanceUpdateParams) MarshalJSON() (data []byte, err error) {
	type shadow InstanceUpdateParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceUpdateParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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:"-"`
	paramObj
}

// URLQuery serializes [InstanceListParams]'s query parameters as `url.Values`.
func (r InstanceListParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// Filter instances by state (e.g., Running, Stopped)
type InstanceListParamsState string

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 InstanceDeleteParams struct {
	// Whether to attempt graceful guest shutdown before deleting the instance
	GracefulShutdown param.Opt[bool] `query:"graceful_shutdown,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [InstanceDeleteParams]'s query parameters as `url.Values`.
func (r InstanceDeleteParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

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"`
	paramObj
}

func (r InstanceForkParams) MarshalJSON() (data []byte, err error) {
	type shadow InstanceForkParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceForkParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// 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.
type InstanceForkParamsTargetState string

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

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", "swtpm".
	Source InstanceLogsParamsSource `query:"source,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [InstanceLogsParams]'s query parameters as `url.Values`.
func (r InstanceLogsParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// 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)
type InstanceLogsParamsSource string

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

type InstanceStandbyParams struct {
	StandbyInstanceRequest StandbyInstanceRequestParam
	paramObj
}

func (r InstanceStandbyParams) MarshalJSON() (data []byte, err error) {
	return shimjson.Marshal(r.StandbyInstanceRequest)
}
func (r *InstanceStandbyParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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"`
	paramObj
}

func (r InstanceStartParams) MarshalJSON() (data []byte, err error) {
	type shadow InstanceStartParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *InstanceStartParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

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:"-"`
	paramObj
}

// URLQuery serializes [InstanceStatParams]'s query parameters as `url.Values`.
func (r InstanceStatParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

type InstanceWaitParams struct {
	// Target state to wait for
	//
	// Any of "Created", "Initializing", "Running", "Paused", "Shutdown", "Stopped",
	// "Standby", "Unknown".
	State InstanceWaitParamsState `query:"state,omitzero" api:"required" json:"-"`
	// Maximum duration to wait (Go duration format, e.g. "30s", "2m"). Capped at 5
	// minutes. Defaults to 60 seconds.
	Timeout param.Opt[string] `query:"timeout,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [InstanceWaitParams]'s query parameters as `url.Values`.
func (r InstanceWaitParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// Target state to wait for
type InstanceWaitParamsState string

const (
	InstanceWaitParamsStateCreated      InstanceWaitParamsState = "Created"
	InstanceWaitParamsStateInitializing InstanceWaitParamsState = "Initializing"
	InstanceWaitParamsStateRunning      InstanceWaitParamsState = "Running"
	InstanceWaitParamsStatePaused       InstanceWaitParamsState = "Paused"
	InstanceWaitParamsStateShutdown     InstanceWaitParamsState = "Shutdown"
	InstanceWaitParamsStateStopped      InstanceWaitParamsState = "Stopped"
	InstanceWaitParamsStateStandby      InstanceWaitParamsState = "Standby"
	InstanceWaitParamsStateUnknown      InstanceWaitParamsState = "Unknown"
)