core

Documentation

Overview

Package instance owns networking state attached to exact Wago instances.

Index

• Variables
• type Config
  • func DefaultConfig() Config
• type LockedState
  • func (s LockedState) OutputScratch(size int) []byte
• type Manager
  • func NewManager() *Manager
  • func NewManagerConfigured(config Config) (*Manager, error)
  • func (m *Manager) AfterInstantiate(_ *wago.InstantiateContext, instance *wago.Instance) error
  • func (m *Manager) Attach(instance *wago.Instance) error
  • func (m *Manager) BeforeClose(context *wago.InstanceContext)
  • func (m *Manager) Detach(instance *wago.Instance) error
  • func (m *Manager) ForInstance(instance *wago.Instance) (*State, bool)
  • func (m *Manager) FromHost(module wago.HostModule) (*State, bool)
  • func (m *Manager) Len() int
• type NamespaceFactory
• type PollVisitor
• type State
  • func (s *State) Close() error
  • func (s *State) CloseHandle(handle resource.Handle, kind resource.Kind) error
  • func (s *State) LookupNamespace(namespaceHandle resource.Handle) (nscore.Namespace, error)
  • func (s *State) NamespaceHandle() resource.Handle
  • func (s *State) Policy() *policy.Policy
  • func (s *State) Poll(budget readiness.Budget, visit PollVisitor) (readiness.Report, nscore.Progress, error)
  • func (s *State) Quotas() *quota.Account
  • func (s *State) Readiness() *readiness.Coordinator
  • func (s *State) Resources() *resource.Table
  • func (s *State) WithLock(operation func(LockedState) error) error

Variables

var (
	ErrInvalidInstance      = errors.New("net: invalid Wago instance")
	ErrAlreadyAttached      = errors.New("net: instance state already attached")
	ErrInvalidConfig        = errors.New("net: invalid instance manager config")
	ErrInvalidBackendResult = errors.New("net: invalid backend result")
	ErrTeardownPanicked     = errors.New("net: instance teardown panicked")
)

Types

type Config

type Config struct {
	Policy           policy.Config
	Limits           quota.Limits
	Readiness        readiness.Config
	NamespaceFactory NamespaceFactory
}

Config fixes immutable policy, finite accounting, readiness storage, and an optional namespace factory for every state attached by a Manager.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig preserves the core extension's state-only behavior: finite default quotas and readiness storage with no automatically created namespace.

type LockedState

type LockedState struct {
	Resources *resource.Table
	Readiness *readiness.Coordinator
	// contains filtered or unexported fields
}

LockedState exposes shared ownership primitives only while State holds its lifecycle mutex. Protocol operation packages must not retain these pointers.

func (LockedState) OutputScratch

func (s LockedState) OutputScratch(size int) []byte

OutputScratch returns zeroed instance-owned temporary output storage while the State lifecycle lock is held. Protocol operations must not retain the returned slice. Capacity grows lazily and is reused across checked calls so successful steady-state output paths do not add per-call garbage.

type Manager

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

Manager is an extension-local attachment map. It must be owned by an extension value; it is intentionally not a package-global registry.

func NewManager

func NewManager() *Manager

NewManager creates an empty extension-local manager with finite defaults and no automatically created namespace.

func NewManagerConfigured

func NewManagerConfigured(config Config) (*Manager, error)

NewManagerConfigured validates and deep-copies manager authority before any instance can be attached.

func (*Manager) AfterInstantiate

func (m *Manager) AfterInstantiate(_ *wago.InstantiateContext, instance *wago.Instance) error

AfterInstantiate is a Wago lifecycle hook that attaches fresh state after a Runtime instance has been created.

func (*Manager) Attach

func (m *Manager) Attach(instance *wago.Instance) error

Attach creates and publishes one isolated state for instance. An optional namespace is fully quota-owned, generation-safe, and poll-registered before publication; every failed stage is rolled back synchronously.

func (*Manager) BeforeClose

func (m *Manager) BeforeClose(context *wago.InstanceContext)

BeforeClose is a Wago lifecycle hook that removes state before instance memory and runtime resources are invalidated. Wago close hooks cannot return errors, so all resources are attempted and cleanup errors are contained.

func (*Manager) Detach

func (m *Manager) Detach(instance *wago.Instance) error

Detach unpublishes state before closing it, so fresh manager lookups fail closed immediately while any in-flight State operation still serializes on that State's lifecycle mutex until teardown completes. Repeated and concurrent detach calls are exactly-once from the manager's perspective.

func (*Manager) ForInstance

func (m *Manager) ForInstance(instance *wago.Instance) (*State, bool)

ForInstance returns state only for the exact attached instance pointer.

func (*Manager) FromHost

func (m *Manager) FromHost(module wago.HostModule) (*State, bool)

FromHost resolves the exact calling instance through Wago's optional host module identity surface. HostModule-only mocks and low-level imports without Runtime lifecycle attachment fail closed.

func (*Manager) Len

func (m *Manager) Len() int

Len returns the number of attached live instances.

type NamespaceFactory

type NamespaceFactory func(*policy.Policy, *quota.Account) (nscore.Namespace, error)

NamespaceFactory constructs one backend namespace for one exact instance. The returned value must not be shared with another instance. Policy and quota pointers belong to that exact state and let backend resources enforce common authority and accounting without exposing backend types above this layer.

type PollVisitor

type PollVisitor func(events []readiness.Event, report readiness.Report, progress nscore.Progress) error

PollVisitor receives one bounded readiness result while State still owns its reusable event storage and lifecycle lock. The callback must not retain events.

type State

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

State is the networking ownership root for one exact Wago instance.

func (*State) Close

func (s *State) Close() error

Close stops polling before releasing resources so no readiness lookup can race teardown, then closes the ledger to discard failed-operation reservations that never reached a resource owner. Teardown attempts every stage and restores all state invariants before re-propagating the first panic.

func (*State) CloseHandle

func (s *State) CloseHandle(handle resource.Handle, kind resource.Kind) error

CloseHandle removes readiness before closing one exact kind-checked resource. A wrong-kind request cannot unregister a valid handle.

func (*State) LookupNamespace

func (s *State) LookupNamespace(namespaceHandle resource.Handle) (nscore.Namespace, error)

LookupNamespace resolves one exact namespace handle to its backend-neutral implementation while serializing the lookup against teardown. It is intended for trusted host-side link/service integration, never direct guest retention.

func (*State) NamespaceHandle

func (s *State) NamespaceHandle() resource.Handle

NamespaceHandle returns the automatically created namespace handle, or zero when the extension was configured without a namespace.

func (*State) Policy

func (s *State) Policy() *policy.Policy

Policy returns the immutable endpoint policy compiled for this instance.

func (*State) Poll

func (s *State) Poll(budget readiness.Budget, visit PollVisitor) (readiness.Report, nscore.Progress, error)

Poll performs one bounded nonblocking coordinator pass using per-instance scratch storage. The visitor runs before the lifecycle lock is released so no concurrent poll or teardown can overwrite or invalidate the result.

func (*State) Quotas

func (s *State) Quotas() *quota.Account

Quotas returns the instance's bounded accounting ledger.

func (*State) Readiness

func (s *State) Readiness() *readiness.Coordinator

Readiness returns the instance's bounded poll coordinator.

func (*State) Resources

func (s *State) Resources() *resource.Table

Resources returns the instance's generation-safe resource table.

func (*State) WithLock

func (s *State) WithLock(operation func(LockedState) error) error

WithLock serializes one protocol operation against polling and teardown.