sandbox

package
v0.115.0-nightly Latest Latest
Warning

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

Go to latest
Published: Mar 20, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Create

func Create(name string) error

Create orchestrates the creation of a new sandbox cluster.

func DeleteState

func DeleteState(name string) error

DeleteState removes the sandbox state file.

func Destroy

func Destroy(name string, force bool) error

Destroy tears down a sandbox cluster.

func GenerateName

func GenerateName() string

GenerateName produces a random adjective-noun name like "swift-falcon".

func List

func List() error

List prints all sandbox clusters.

func Reset

func Reset() error

Reset tears down all sandbox infrastructure (floating IPs, firewall, SSH key) and removes the config file so the user can rerun setup from scratch. This is useful when switching datacenter locations (floating IPs are location-bound).

func Rollout

func Rollout(name string, flags RolloutFlags) error

Rollout builds, pushes, and performs a rolling upgrade on a sandbox cluster.

func SSHInto

func SSHInto(name string, nodeNum int) error

SSHInto opens an interactive SSH session to a sandbox node.

func SaveConfig

func SaveConfig(cfg *Config) error

SaveConfig writes the sandbox config to ~/.orama/sandbox.yaml.

func SaveState

func SaveState(state *SandboxState) error

SaveState persists the sandbox state to disk.

func Setup

func Setup() error

Setup runs the interactive sandbox setup wizard.

func Status

func Status(name string) error

Status prints the health report for a sandbox cluster.

Types

type Config

type Config struct {
	HetznerAPIToken string       `yaml:"hetzner_api_token"`
	Domain          string       `yaml:"domain"`
	Location        string       `yaml:"location"`    // Hetzner datacenter (default: fsn1)
	ServerType      string       `yaml:"server_type"` // Hetzner server type (default: cx22)
	FloatingIPs     []FloatIP    `yaml:"floating_ips"`
	SSHKey          SSHKeyConfig `yaml:"ssh_key"`
	FirewallID      int64        `yaml:"firewall_id,omitempty"` // Hetzner firewall resource ID
}

Config holds sandbox configuration, stored at ~/.orama/sandbox.yaml.

func LoadConfig

func LoadConfig() (*Config, error)

LoadConfig reads the sandbox config from ~/.orama/sandbox.yaml. Returns an error if the file doesn't exist (user must run setup first).

func (*Config) Defaults

func (c *Config) Defaults()

Defaults fills in default values for optional fields.

type CreateServerRequest

type CreateServerRequest struct {
	Name       string            `json:"name"`
	ServerType string            `json:"server_type"`
	Image      string            `json:"image"`
	Location   string            `json:"location"`
	SSHKeys    []int64           `json:"ssh_keys"`
	Labels     map[string]string `json:"labels"`
	Firewalls  []struct {
		Firewall int64 `json:"firewall"`
	} `json:"firewalls,omitempty"`
}

CreateServerRequest holds parameters for server creation.

type FloatIP

type FloatIP struct {
	ID int64  `yaml:"id"`
	IP string `yaml:"ip"`
}

FloatIP holds a Hetzner floating IP reference.

type HetznerClient

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

HetznerClient is a minimal Hetzner Cloud API client.

func NewHetznerClient

func NewHetznerClient(token string) *HetznerClient

NewHetznerClient creates a new Hetzner API client.

func (*HetznerClient) AssignFloatingIP

func (c *HetznerClient) AssignFloatingIP(floatingIPID, serverID int64) error

AssignFloatingIP assigns a floating IP to a server.

func (*HetznerClient) CreateFirewall

func (c *HetznerClient) CreateFirewall(name string, rules []HetznerFWRule, labels map[string]string) (*HetznerFirewall, error)

CreateFirewall creates a firewall with the given rules.

func (*HetznerClient) CreateFloatingIP

func (c *HetznerClient) CreateFloatingIP(location, description string, labels map[string]string) (*HetznerFloatingIP, error)

CreateFloatingIP creates a new floating IP.

func (*HetznerClient) CreateServer

func (c *HetznerClient) CreateServer(req CreateServerRequest) (*HetznerServer, error)

CreateServer creates a new server and returns it.

func (*HetznerClient) DeleteFirewall

func (c *HetznerClient) DeleteFirewall(id int64) error

DeleteFirewall deletes a firewall by ID.

func (*HetznerClient) DeleteFloatingIP

func (c *HetznerClient) DeleteFloatingIP(id int64) error

DeleteFloatingIP deletes a floating IP by ID.

func (*HetznerClient) DeleteSSHKey

func (c *HetznerClient) DeleteSSHKey(id int64) error

DeleteSSHKey deletes an SSH key by ID.

func (*HetznerClient) DeleteServer

func (c *HetznerClient) DeleteServer(id int64) error

DeleteServer deletes a server by ID.

func (*HetznerClient) GetSSHKey

func (c *HetznerClient) GetSSHKey(id int64) (*HetznerSSHKey, error)

GetSSHKey retrieves an SSH key by ID.

func (*HetznerClient) GetServer

func (c *HetznerClient) GetServer(id int64) (*HetznerServer, error)

GetServer retrieves a server by ID.

func (*HetznerClient) ListFirewallsByLabel

func (c *HetznerClient) ListFirewallsByLabel(selector string) ([]HetznerFirewall, error)

ListFirewallsByLabel lists firewalls filtered by label.

func (*HetznerClient) ListFloatingIPsByLabel

func (c *HetznerClient) ListFloatingIPsByLabel(selector string) ([]HetznerFloatingIP, error)

ListFloatingIPsByLabel lists floating IPs filtered by label.

func (*HetznerClient) ListLocations

func (c *HetznerClient) ListLocations() ([]HetznerLocation, error)

ListLocations returns all available Hetzner datacenter locations.

func (*HetznerClient) ListSSHKeysByFingerprint

func (c *HetznerClient) ListSSHKeysByFingerprint(fingerprint string) ([]HetznerSSHKey, error)

ListSSHKeysByFingerprint finds SSH keys matching a fingerprint.

func (*HetznerClient) ListServerTypes

func (c *HetznerClient) ListServerTypes() ([]HetznerServerType, error)

ListServerTypes returns all available server types.

func (*HetznerClient) ListServersByLabel

func (c *HetznerClient) ListServersByLabel(selector string) ([]HetznerServer, error)

ListServersByLabel lists servers filtered by a label selector.

func (*HetznerClient) UnassignFloatingIP

func (c *HetznerClient) UnassignFloatingIP(floatingIPID int64) error

UnassignFloatingIP removes a floating IP assignment.

func (*HetznerClient) UploadSSHKey

func (c *HetznerClient) UploadSSHKey(name, publicKey string) (*HetznerSSHKey, error)

UploadSSHKey uploads a public key to Hetzner.

func (*HetznerClient) ValidateToken

func (c *HetznerClient) ValidateToken() error

ValidateToken checks if the API token is valid by making a simple request.

func (*HetznerClient) WaitForServer

func (c *HetznerClient) WaitForServer(id int64, timeout time.Duration) (*HetznerServer, error)

WaitForServer polls until the server reaches "running" status.

type HetznerError

type HetznerError struct {
	Error struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

HetznerError represents an API error response.

type HetznerFWRule

type HetznerFWRule struct {
	Direction   string   `json:"direction"`
	Protocol    string   `json:"protocol"`
	Port        string   `json:"port"`
	SourceIPs   []string `json:"source_ips"`
	Description string   `json:"description,omitempty"`
}

HetznerFWRule represents a firewall rule.

func SandboxFirewallRules

func SandboxFirewallRules() []HetznerFWRule

SandboxFirewallRules returns the standard firewall rules for sandbox nodes.

type HetznerFirewall

type HetznerFirewall struct {
	ID     int64             `json:"id"`
	Name   string            `json:"name"`
	Rules  []HetznerFWRule   `json:"rules"`
	Labels map[string]string `json:"labels"`
}

HetznerFirewall represents a Hetzner firewall.

type HetznerFloatingIP

type HetznerFloatingIP struct {
	ID           int64             `json:"id"`
	IP           string            `json:"ip"`
	Server       *int64            `json:"server"` // nil if unassigned
	Labels       map[string]string `json:"labels"`
	Description  string            `json:"description"`
	HomeLocation struct {
		Name string `json:"name"`
	} `json:"home_location"`
}

HetznerFloatingIP represents a Hetzner floating IP.

type HetznerLocation

type HetznerLocation struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`        // e.g., "fsn1", "nbg1", "hel1"
	Description string `json:"description"` // e.g., "Falkenstein DC Park 1"
	City        string `json:"city"`
	Country     string `json:"country"` // ISO 3166-1 alpha-2
}

HetznerLocation represents a Hetzner datacenter location.

type HetznerPublicNet

type HetznerPublicNet struct {
	IPv4 struct {
		IP string `json:"ip"`
	} `json:"ipv4"`
}

HetznerPublicNet holds public networking info for a server.

type HetznerSSHKey

type HetznerSSHKey struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Fingerprint string `json:"fingerprint"`
	PublicKey   string `json:"public_key"`
}

HetznerSSHKey represents a Hetzner SSH key.

type HetznerServer

type HetznerServer struct {
	ID         int64             `json:"id"`
	Name       string            `json:"name"`
	Status     string            `json:"status"` // initializing, running, off, ...
	PublicNet  HetznerPublicNet  `json:"public_net"`
	Labels     map[string]string `json:"labels"`
	ServerType struct {
		Name string `json:"name"`
	} `json:"server_type"`
}

HetznerServer represents a Hetzner Cloud server.

type HetznerServerType

type HetznerServerType struct {
	ID           int64   `json:"id"`
	Name         string  `json:"name"`        // e.g., "cx22", "cx23"
	Description  string  `json:"description"` // e.g., "CX23"
	Cores        int     `json:"cores"`
	Memory       float64 `json:"memory"` // GB
	Disk         int     `json:"disk"`   // GB
	Architecture string  `json:"architecture"`
	Deprecation  *struct {
		Announced        string `json:"announced"`
		UnavailableAfter string `json:"unavailable_after"`
	} `json:"deprecation"` // nil = not deprecated
	Prices []struct {
		Location string `json:"location"`
		Hourly   struct {
			Gross string `json:"gross"`
		} `json:"price_hourly"`
		Monthly struct {
			Gross string `json:"gross"`
		} `json:"price_monthly"`
	} `json:"prices"`
}

HetznerServerType represents a Hetzner server type with pricing.

type RolloutFlags

type RolloutFlags struct {
	AnyoneClient bool
}

RolloutFlags holds optional flags passed through to `orama node upgrade`.

type SSHKeyConfig

type SSHKeyConfig struct {
	HetznerID   int64  `yaml:"hetzner_id"`
	VaultTarget string `yaml:"vault_target"` // e.g. "sandbox/root"
}

SSHKeyConfig holds the wallet vault target and Hetzner resource ID.

type SandboxState

type SandboxState struct {
	Name      string        `yaml:"name"`
	CreatedAt time.Time     `yaml:"created_at"`
	Domain    string        `yaml:"domain"`
	Status    SandboxStatus `yaml:"status"`
	Servers   []ServerState `yaml:"servers"`
}

SandboxState holds the full state of an active sandbox cluster.

func FindActiveSandbox

func FindActiveSandbox() (*SandboxState, error)

FindActiveSandbox returns the first sandbox in running or creating state. Returns nil if no active sandbox exists.

func ListStates

func ListStates() ([]*SandboxState, error)

ListStates returns all sandbox states from disk.

func LoadState

func LoadState(name string) (*SandboxState, error)

LoadState reads a sandbox state from disk.

func (*SandboxState) GenesisServer

func (s *SandboxState) GenesisServer() ServerState

GenesisServer returns the first server (genesis node).

func (*SandboxState) NameserverNodes

func (s *SandboxState) NameserverNodes() []ServerState

NameserverNodes returns only the nameserver nodes.

func (*SandboxState) RegularNodes

func (s *SandboxState) RegularNodes() []ServerState

RegularNodes returns only the non-nameserver nodes.

func (*SandboxState) ToNodes

func (s *SandboxState) ToNodes(vaultTarget string) []inspector.Node

ToNodes converts sandbox servers to inspector.Node structs for SSH operations. Sets VaultTarget on each node so PrepareNodeKeys resolves from the wallet.

type SandboxStatus

type SandboxStatus string

SandboxStatus represents the lifecycle state of a sandbox.

const (
	StatusCreating   SandboxStatus = "creating"
	StatusRunning    SandboxStatus = "running"
	StatusDestroying SandboxStatus = "destroying"
	StatusError      SandboxStatus = "error"
)

type ServerState

type ServerState struct {
	ID         int64  `yaml:"id"`                    // Hetzner server ID
	Name       string `yaml:"name"`                  // e.g., sbx-feature-webrtc-1
	IP         string `yaml:"ip"`                    // Public IPv4
	Role       string `yaml:"role"`                  // "nameserver" or "node"
	FloatingIP string `yaml:"floating_ip,omitempty"` // Only for nameserver nodes
	WgIP       string `yaml:"wg_ip,omitempty"`       // WireGuard IP (populated after install)
}

ServerState holds the state of a single server in the sandbox.

Jump to

Keyboard shortcuts

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