network

Documentation

Overview

Package network manages user-defined named networks: VM-independent records that workspaces can join so multiple workspaces share a subnet and address each other by name. This package owns the registry and address allocation only — a backend-neutral data model persisted under the state directory. Live realization (host bridge, cross-VM connectivity, name resolution) is a separate supervisor-side concern layered on top of these records.

Index

• func IndexPath(stateDir string) string
• func Join(stateDir, name, workspace string) (string, error)
• func Leave(stateDir, name, workspace string) error
• func LeaveAll(stateDir, workspace string) error
• func Remove(stateDir, name string, force bool) error
• func ValidName(name string) bool
• func WriteIndex(stateDir string, idx Index) error
• type Index
  • func ReadIndex(stateDir string) (Index, error)
• type Member
• type Record
  • func Create(stateDir, name, subnet string) (Record, error)
  • func Get(stateDir, name string) (Record, error)
  • func List(stateDir string) ([]Record, error)

Functions

func IndexPath

func IndexPath(stateDir string) string

IndexPath returns the registry file path for a state directory.

func Join

func Join(stateDir, name, workspace string) (string, error)

Join allocates a stable member IP for workspace on the named network and persists it. If the workspace is already a member, its existing IP is returned unchanged so an address survives stop/start. It fails closed when the subnet has no free host address.

func Leave

func Leave(stateDir, name, workspace string) error

Leave removes a workspace's membership from a network, freeing its IP. It is idempotent and never errors on an unknown network or non-member.

func LeaveAll

func LeaveAll(stateDir, workspace string) error

LeaveAll removes a workspace from every network it belongs to. Use it when a workspace is deleted so no network keeps a member that no longer exists.

func Remove

func Remove(stateDir, name string, force bool) error

Remove deletes a network. It fails closed while the network still has members unless force is set.

func ValidName

func ValidName(name string) bool

ValidName reports whether name is a usable network name: a DNS-label-like token (lowercase letters, digits, hyphens; must start alphanumeric).

func WriteIndex

func WriteIndex(stateDir string, idx Index) error

WriteIndex persists the registry.

Types

type Index

type Index struct {
	Networks []Record `json:"networks"`
}

Index is the persisted set of named networks.

func ReadIndex

func ReadIndex(stateDir string) (Index, error)

ReadIndex loads the registry, returning an empty Index when none exists.

type Member

type Member struct {
	Workspace string `json:"workspace"`
	IP        string `json:"ip"`
}

Member is a workspace's stable address on a network.

type Record

type Record struct {
	Name      string   `json:"name"`
	Subnet    string   `json:"subnet"`  // CIDR, e.g. 10.44.1.0/24
	Gateway   string   `json:"gateway"` // first usable host, e.g. 10.44.1.1
	CreatedAt string   `json:"created_at,omitempty"`
	Members   []Member `json:"members,omitempty"`
}

Record is one named network.

func Create

func Create(stateDir, name, subnet string) (Record, error)

Create registers a new named network. When subnet is empty an unused /24 is allocated from the managed range. It fails closed on a duplicate name or an overlapping subnet.

func Get

func Get(stateDir, name string) (Record, error)

Get returns one network by name.

func List

func List(stateDir string) ([]Record, error)

List returns all networks sorted by name.