instance

Documentation

Overview

Package instance defines the Instance domain entity, lifecycle management service interface, persistence store interface, and state machine for instance state transitions.

Index

• func ValidateTransition(current, target provider.InstanceState) error
• type CreateRequest
• type Instance
• type ListOptions
• type ListResult
• type ScaleRequest
• type Service
  • func NewService(store Store, providers *provider.Registry, events event.Bus, ...) Service
• type Store
• type UpdateRequest

Functions

func ValidateTransition

func ValidateTransition(current, target provider.InstanceState) error

ValidateTransition checks whether moving from the current state to the target state is allowed. It returns ctrlplane.ErrInvalidState if not.

Types

type CreateRequest

type CreateRequest struct {
	Name         string                `json:"name"                    validate:"required"`
	ProviderName string                `json:"provider_name,omitempty"`
	Region       string                `json:"region,omitempty"`
	Image        string                `json:"image"                   validate:"required"`
	Resources    provider.ResourceSpec `json:"resources"`
	Env          map[string]string     `json:"env,omitempty"`
	Ports        []provider.PortSpec   `json:"ports,omitempty"`
	Labels       map[string]string     `json:"labels,omitempty"`
}

CreateRequest holds the parameters for creating a new instance.

type Instance

type Instance struct {
	ctrlplane.Entity

	TenantID       string                 `db:"tenant_id"       json:"tenant_id"`
	Name           string                 `db:"name"            json:"name"`
	Slug           string                 `db:"slug"            json:"slug"`
	ProviderName   string                 `db:"provider_name"   json:"provider_name"`
	ProviderRef    string                 `db:"provider_ref"    json:"provider_ref"`
	Region         string                 `db:"region"          json:"region"`
	State          provider.InstanceState `db:"state"           json:"state"`
	Image          string                 `db:"image"           json:"image"`
	Resources      provider.ResourceSpec  `db:"resources"       json:"resources"`
	Env            map[string]string      `db:"env"             json:"env,omitempty"`
	Ports          []provider.PortSpec    `db:"ports"           json:"ports,omitempty"`
	Endpoints      []provider.Endpoint    `db:"endpoints"       json:"endpoints,omitempty"`
	Labels         map[string]string      `db:"labels"          json:"labels,omitempty"`
	CurrentRelease id.ID                  `db:"current_release" json:"current_release,omitzero"`
	SuspendedAt    *time.Time             `db:"suspended_at"    json:"suspended_at,omitempty"`
}

Instance represents a managed application instance belonging to a tenant.

type ListOptions

type ListOptions struct {
	State    string `json:"state,omitempty"`
	Label    string `json:"label,omitempty"`
	Provider string `json:"provider,omitempty"`
	Cursor   string `json:"cursor,omitempty"`
	Limit    int    `json:"limit,omitempty"`
}

ListOptions configures instance listing with optional filters and pagination.

type ListResult

type ListResult struct {
	Items      []*Instance `json:"items"`
	NextCursor string      `json:"next_cursor,omitempty"`
	Total      int         `json:"total"`
}

ListResult holds a page of instances with cursor-based pagination.

type ScaleRequest

type ScaleRequest struct {
	CPUMillis *int `json:"cpu_millis,omitempty"`
	MemoryMB  *int `json:"memory_mb,omitempty"`
	Replicas  *int `json:"replicas,omitempty"`
}

ScaleRequest holds the parameters for scaling an instance.

type Service

type Service interface {
	// Create provisions a new instance on the specified provider.
	Create(ctx context.Context, req CreateRequest) (*Instance, error)

	// Get returns an instance by ID, scoped to the tenant in context.
	Get(ctx context.Context, instanceID id.ID) (*Instance, error)

	// List returns instances for the current tenant with filtering.
	List(ctx context.Context, opts ListOptions) (*ListResult, error)

	// Update modifies instance configuration (env, labels, resources).
	Update(ctx context.Context, instanceID id.ID, req UpdateRequest) (*Instance, error)

	// Delete deprovisions and removes an instance.
	Delete(ctx context.Context, instanceID id.ID) error

	// Start starts a stopped instance.
	Start(ctx context.Context, instanceID id.ID) error

	// Stop gracefully stops an instance.
	Stop(ctx context.Context, instanceID id.ID) error

	// Restart performs a stop+start cycle.
	Restart(ctx context.Context, instanceID id.ID) error

	// Scale adjusts resource allocation.
	Scale(ctx context.Context, instanceID id.ID, req ScaleRequest) error

	// Suspend marks an instance as suspended (billing/abuse).
	Suspend(ctx context.Context, instanceID id.ID, reason string) error

	// Unsuspend restores a suspended instance.
	Unsuspend(ctx context.Context, instanceID id.ID) error
}

Service manages instance lifecycle operations.

func NewService

func NewService(store Store, providers *provider.Registry, events event.Bus, auth auth.Provider) Service

NewService creates a new instance service.

type Store

type Store interface {
	// Insert persists a new instance.
	Insert(ctx context.Context, inst *Instance) error

	// GetByID retrieves an instance by its ID within a tenant.
	GetByID(ctx context.Context, tenantID string, instanceID id.ID) (*Instance, error)

	// GetBySlug retrieves an instance by its slug within a tenant.
	GetBySlug(ctx context.Context, tenantID string, slug string) (*Instance, error)

	// List returns a filtered, paginated list of instances for a tenant.
	List(ctx context.Context, tenantID string, opts ListOptions) (*ListResult, error)

	// Update persists changes to an existing instance.
	Update(ctx context.Context, inst *Instance) error

	// Delete removes an instance from the store.
	Delete(ctx context.Context, tenantID string, instanceID id.ID) error

	// CountByTenant returns the total number of instances for a tenant.
	CountByTenant(ctx context.Context, tenantID string) (int, error)
}

Store is the persistence interface for instances.

type UpdateRequest

type UpdateRequest struct {
	Name   *string           `json:"name,omitempty"`
	Env    map[string]string `json:"env,omitempty"`
	Labels map[string]string `json:"labels,omitempty"`
}

UpdateRequest holds the parameters for updating an instance.