properties

Documentation

Overview

Package properties is the guest-side application of dynamically- pushed VM properties. The host (weft-agent) publishes the full set of guest-readable properties for this VM on every change ; the subscriber mirrors them to a local POSIX tree so any in-VM process can `cat /run/weft/properties/<key>` without speaking a custom API.

Only the guest_readable=true properties reach this surface — the host filters before publishing (host-only metadata like cost-center or security labels never crosses the boundary).

Same Subscriber+ApplyFunc pattern as [[sshkeys]] / [[mesh]] / [[mounts]] : state pushed whole, missed messages self-heal on next publish. An empty set means "no properties" and IS applied — the guest tree is cleared.

Key conventions :

• Free-form, but the segment separator is "/" (k8s/Docker style).
• The "weft.boot/*" prefix is reserved for first-boot provisioning (set by CreateVM, consumed by the boot concern). Operators may read but should not hand-edit.
• "/" in the property key maps to filesystem nesting on apply. "owner" → <root>/owner ; "weft.boot/script" → <root>/weft.boot/script.

Index

• func HandleMessage(data []byte, apply ApplyFunc) error
• func Subject(vmID string) string
• type ApplyFunc
• type PropertySet
  • func (s PropertySet) Validate() error
• type Subscriber
  • func NewSubscriber(nc *nats.Conn, vmID string, apply ApplyFunc, logger *log.Logger) *Subscriber
  • func (s *Subscriber) Start() (*nats.Subscription, error)

Functions

func HandleMessage

func HandleMessage(data []byte, apply ApplyFunc) error

HandleMessage decodes a published update and applies it. Pure aside from the injected apply.

func Subject

func Subject(vmID string) string

Subject is the per-VM NATS subject the host publishes properties on.

Types

type ApplyFunc

type ApplyFunc func(PropertySet) error

ApplyFunc applies the desired set to the guest. The real impl syncs /run/weft/properties/ ; tests inject a stub.

type PropertySet

type PropertySet struct {
	Properties map[string]string `json:"properties"`
}

PropertySet is the desired set of properties at this point in time. Keys are property names ; values are the (possibly multi-line) content. An empty map means "no properties" and triggers a clear.

func (PropertySet) Validate

func (s PropertySet) Validate() error

Validate rejects keys that would escape the property tree on apply : empty, absolute paths, or paths containing "..". The host is supposed to filter these already ; this is the guest's defence in depth.

type Subscriber

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

Subscriber listens for this VM's property updates and applies each.

func NewSubscriber

func NewSubscriber(nc *nats.Conn, vmID string, apply ApplyFunc, logger *log.Logger) *Subscriber

NewSubscriber builds a Subscriber for vmID.

func (*Subscriber) Start

func (s *Subscriber) Start() (*nats.Subscription, error)

Start subscribes to the VM's properties subject. Returned subscription stays live until unsubscribed or the connection drops.