capacity

package module
v0.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package capacity defines Helmr's provider-neutral HTTP contract and canonical client for deployment capacity automation.

It does not decide desired host counts, define provider-specific policy or mutations, expose tenant APIs, describe Control DB internals, or implement the runtime reservation ledger.

Index

Constants

View Source
const (
	RoutePrefix                  = "/capacity/v0"
	WorkerGroupsPath             = "/worker-groups"
	WorkerInstancesPath          = "/worker-instances"
	ErrorCodeQueuedDemandPresent = "queued_demand_present"
)
View Source
const (
	RuntimeContract       = "helmr.vm-runtime.v0"
	SubstrateFormatExt4   = "ext4"
	SubstrateContractExt4 = "helmr.substrate.ext4.v0"
)
View Source
const WorkerTemplateSchema = "helmr.worker-template.v0"

Variables

This section is empty.

Functions

This section is empty.

Types

type CPUShape

type CPUShape struct {
	VCPUCount       int32  `json:"vcpu_count"`
	CPUConfigDigest string `json:"cpu_config_digest"`
}

type CPUTemplateKind

type CPUTemplateKind string
const (
	CPUTemplateNone   CPUTemplateKind = "none"
	CPUTemplateCustom CPUTemplateKind = "custom"
)

type CPUTemplateSelector

type CPUTemplateSelector struct {
	Kind   CPUTemplateKind `json:"kind"`
	Digest string          `json:"digest,omitempty"`
}

type Client

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

func NewClient

func NewClient(rawBaseURL, token string, options ...Option) (*Client, error)

func (*Client) ConfirmWorkerInstanceProviderAbsent

func (c *Client) ConfirmWorkerInstanceProviderAbsent(ctx context.Context, workerInstanceID string) (WorkerInstance, error)

func (*Client) DrainWorkerInstance

func (c *Client) DrainWorkerInstance(ctx context.Context, workerInstanceID string, request DrainWorkerInstanceRequest) (WorkerInstance, error)

func (*Client) GetWorkerInstance

func (c *Client) GetWorkerInstance(ctx context.Context, workerInstanceID string) (WorkerInstance, error)

func (*Client) ListWorkerInstances

func (c *Client) ListWorkerInstances(ctx context.Context, options ListWorkerInstancesOptions) (ListWorkerInstancesResponse, error)

func (*Client) Plan

func (c *Client) Plan(ctx context.Context, workerGroupID string, request PlanRequest) (PlanResponse, error)

func (*Client) ReconcileWorkerGroupPrimaryPools

func (c *Client) ReconcileWorkerGroupPrimaryPools(
	ctx context.Context,
	workerGroupID string,
	request ReconcileWorkerGroupPrimaryPoolsRequest,
) (ReconcileWorkerGroupPrimaryPoolsResponse, error)

func (*Client) ResolveWorkerGroup

func (c *Client) ResolveWorkerGroup(ctx context.Context, regionID, name string) (WorkerGroup, error)

func (*Client) ResolveWorkerPool

func (c *Client) ResolveWorkerPool(ctx context.Context, workerGroupID, name string) (WorkerPool, error)

type DrainWorkerInstanceRequest

type DrainWorkerInstanceRequest struct {
	ExpectedEpoch           int64 `json:"expected_epoch"`
	ExpectedClaimVersion    int64 `json:"expected_claim_version"`
	RequireZeroQueuedDemand bool  `json:"require_zero_queued_demand,omitempty"`
}

type HTTPError

type HTTPError struct {
	StatusCode int
	Status     string
	Code       string
	Message    string
	Details    map[string]json.RawMessage
}

func (*HTTPError) Error

func (e *HTTPError) Error() string

type Incompatibility

type Incompatibility struct {
	Reason string `json:"reason"`
	Count  int64  `json:"count"`
}

type ListWorkerInstancesOptions

type ListWorkerInstancesOptions struct {
	WorkerGroupID         string
	ResourceIDs           []string
	Statuses              []WorkerInstanceStatus
	HasUnreclaimedRuntime bool
	Limit                 int32
}

type ListWorkerInstancesResponse

type ListWorkerInstancesResponse struct {
	WorkerInstances []WorkerInstance `json:"worker_instances"`
}

type Option

type Option func(*Client)

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

type PlanRequest

type PlanRequest struct {
	Pools []PoolRequest `json:"pools"`
}

type PlanResponse

type PlanResponse struct {
	WorkerGroupID   string            `json:"worker_group_id"`
	WorkerGroupName string            `json:"worker_group_name"`
	RegionID        string            `json:"region_id"`
	GroupStatus     WorkerGroupStatus `json:"group_status"`
	Pools           []PoolPlan        `json:"pools"`
	UnmatchedDemand []Incompatibility `json:"unmatched_demand"`
	Complete        bool              `json:"complete"`
	ComputedAt      time.Time         `json:"computed_at"`
}

type PoolPlan

type PoolPlan struct {
	PoolID                       string `json:"pool_id"`
	PoolName                     string `json:"pool_name"`
	RecommendedAdditionalWorkers int32  `json:"recommended_additional_workers"`
	CompatibleQueuedItems        int64  `json:"compatible_queued_items"`
	RegisteringWorkers           int64  `json:"registering_workers"`
	ActiveWorkers                int64  `json:"active_workers"`
	Complete                     bool   `json:"complete"`
	Saturated                    bool   `json:"saturated"`
	ScaleInBlocked               bool   `json:"scale_in_blocked"`
}

type PoolRequest

type PoolRequest struct {
	PoolID               string `json:"pool_id"`
	MaxAdditionalWorkers int32  `json:"max_additional_workers"`
}

type ReconcileWorkerGroupPrimaryPoolsRequest

type ReconcileWorkerGroupPrimaryPoolsRequest struct {
	ExpectedGroupClaimVersion int64  `json:"expected_group_claim_version"`
	PoolID                    string `json:"pool_id"`
}

type ReconcileWorkerGroupPrimaryPoolsResponse

type ReconcileWorkerGroupPrimaryPoolsResponse struct {
	WorkerGroup WorkerGroup `json:"worker_group"`
	Applied     bool        `json:"applied"`
}

type ResourceVector

type ResourceVector struct {
	CPUMillis               int64 `json:"cpu_millis"`
	MemoryBytes             int64 `json:"memory_bytes"`
	GuestEphemeralDiskBytes int64 `json:"guest_ephemeral_disk_bytes"`
	VMSlots                 int64 `json:"vm_slots,omitempty"`
}

type RuntimeProfile

type RuntimeProfile struct {
	ID                        string              `json:"id"`
	Arch                      string              `json:"arch"`
	Contract                  string              `json:"contract"`
	VMRuntimeDescriptorDigest string              `json:"vm_runtime_descriptor_digest"`
	FirecrackerDigest         string              `json:"firecracker_digest"`
	FirecrackerVersion        string              `json:"firecracker_version"`
	SnapshotFormatVersion     string              `json:"snapshot_format_version"`
	HostKernelRelease         string              `json:"host_kernel_release"`
	CPUTemplate               CPUTemplateSelector `json:"cpu_template"`
	KernelDigest              string              `json:"kernel_digest"`
	InitramfsDigest           string              `json:"initramfs_digest"`
	RootfsDigest              string              `json:"rootfs_digest"`
}

func (RuntimeProfile) ExpectedID

func (p RuntimeProfile) ExpectedID() (string, error)

func (RuntimeProfile) Validate

func (p RuntimeProfile) Validate() error

type SubstrateProfile

type SubstrateProfile struct {
	Format   string `json:"format,omitempty"`
	Contract string `json:"contract,omitempty"`
}

type WorkerGroup

type WorkerGroup struct {
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	RegionID      string            `json:"region_id"`
	Status        WorkerGroupStatus `json:"status"`
	ClaimVersion  int64             `json:"claim_version"`
	PrimaryPoolID string            `json:"primary_pool_id,omitempty"`
}

type WorkerGroupStatus

type WorkerGroupStatus string
const (
	WorkerGroupStatusActive   WorkerGroupStatus = "active"
	WorkerGroupStatusPaused   WorkerGroupStatus = "paused"
	WorkerGroupStatusDraining WorkerGroupStatus = "draining"
	WorkerGroupStatusDisabled WorkerGroupStatus = "disabled"
)

type WorkerInstance

type WorkerInstance struct {
	ID                 string               `json:"id"`
	ResourceID         string               `json:"resource_id"`
	WorkerGroupID      string               `json:"worker_group_id"`
	WorkerPoolID       string               `json:"worker_pool_id"`
	Status             WorkerInstanceStatus `json:"status"`
	ClaimVersion       int64                `json:"claim_version"`
	CurrentEpoch       *int64               `json:"current_epoch,omitempty"`
	DrainingAt         *time.Time           `json:"draining_at,omitempty"`
	TerminationReadyAt *time.Time           `json:"termination_ready_at,omitempty"`
	LostAt             *time.Time           `json:"lost_at,omitempty"`
	CreatedAt          time.Time            `json:"created_at"`
	UpdatedAt          time.Time            `json:"updated_at"`
}

type WorkerInstanceStatus

type WorkerInstanceStatus string
const (
	WorkerInstanceStatusRegistering      WorkerInstanceStatus = "registering"
	WorkerInstanceStatusActive           WorkerInstanceStatus = "active"
	WorkerInstanceStatusDraining         WorkerInstanceStatus = "draining"
	WorkerInstanceStatusTerminationReady WorkerInstanceStatus = "termination_ready"
	WorkerInstanceStatusLost             WorkerInstanceStatus = "lost"
)

type WorkerPool

type WorkerPool struct {
	ID            string           `json:"id"`
	WorkerGroupID string           `json:"worker_group_id"`
	Name          string           `json:"name"`
	Status        WorkerPoolStatus `json:"status"`
}

type WorkerPoolStatus

type WorkerPoolStatus string
const (
	WorkerPoolStatusPending  WorkerPoolStatus = "pending"
	WorkerPoolStatusActive   WorkerPoolStatus = "active"
	WorkerPoolStatusDraining WorkerPoolStatus = "draining"
	WorkerPoolStatusDisabled WorkerPoolStatus = "disabled"
)

type WorkerTemplate

type WorkerTemplate struct {
	Schema    string           `json:"schema"`
	Runtime   RuntimeProfile   `json:"runtime"`
	CPUShapes []CPUShape       `json:"cpu_shapes"`
	Substrate SubstrateProfile `json:"substrate"`
	Capacity  ResourceVector   `json:"capacity"`
	PerVM     ResourceVector   `json:"per_vm"`
}

func (WorkerTemplate) Validate

func (t WorkerTemplate) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL