control

type Config ¶

type Config struct {
	Factory          SessionFactory
	Locker           Locker
	IdleTimeout      time.Duration
	AbsoluteLifetime time.Duration
	SweepInterval    time.Duration
	CleanupTimeout   time.Duration
	Now              func() time.Time
	NewHandleID      func() HandleID
}

type ExecuteFunc ¶

type ExecuteFunc func(context.Context, Session) error

ExecuteFunc runs inside the per-device write queue. The Session value is valid only for the duration of the callback and must not be retained.

type Handle ¶

type Handle struct {
	ID                HandleID
	DeviceID          domain.DeviceID
	Generation        uint64
	Ownership         Ownership
	Capabilities      []string
	State             HandleState
	CreatedAt         time.Time
	LastUsedAt        time.Time
	IdleExpiresAt     time.Time
	AbsoluteExpiresAt time.Time
}

Handle identifies one generation of one device control session.

type HandleID ¶

type HandleID string

HandleID is an opaque control lease identifier.

type HandleState ¶

type HandleState string

const (
	HandleReady    HandleState = "ready"
	HandleDraining HandleState = "draining"
	HandleExpired  HandleState = "expired"
	HandleClosed   HandleState = "closed"
	HandleFenced   HandleState = "fenced"
)

type Lock ¶

type Lock interface {
	Release() error
}

Lock is held for the complete lifetime of a device session.

type Locker ¶

type Locker interface {
	Acquire(context.Context, domain.DeviceID) (Lock, error)
}

Locker prevents independent local processes from controlling one device at the same time.

type OpenRequest ¶

type OpenRequest struct {
	DeviceID         domain.DeviceID
	Capabilities     []string
	Ownership        Ownership
	IdleTimeout      time.Duration
	AbsoluteLifetime time.Duration
}

type Ownership ¶

type Ownership string

const (
	OwnershipOwned    Ownership = "owned"
	OwnershipAttached Ownership = "attached"
)

type Ref ¶

type Ref struct {
	ID                 HandleID
	ExpectedGeneration uint64
}

Ref fences an operation to the exact handle generation observed by its caller.

type Registry ¶

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

Registry owns one actor per stable device identity.

func NewRegistry(config Config) (*Registry, error)

func (r *Registry) Close(ctx context.Context, deviceID domain.DeviceID, ref Ref) (Handle, error)

func (r *Registry) Drain(ctx context.Context) error

func (r *Registry) Execute(ctx context.Context, deviceID domain.DeviceID, ref Ref, capability string, execute ExecuteFunc) error

func (r *Registry) Get(ctx context.Context, deviceID domain.DeviceID, ref Ref) (Snapshot, error)

func (r *Registry) Open(ctx context.Context, request OpenRequest) (Handle, error)

func (r *Registry) Quiescent(ctx context.Context) (bool, error)

func (r *Registry) Reconnect(ctx context.Context, deviceID domain.DeviceID, ref Ref) (Handle, error)

func (r *Registry) State() TransportState

type Session ¶

type Session interface {
	Close(context.Context) error
	Disconnect(context.Context) error
}

Session is the protocol adapter resource owned by a DeviceActor. Concrete implementations may expose richer APIs to Execute callbacks.

type SessionFactory ¶

type SessionFactory interface {
	Open(context.Context, domain.DeviceID, uint64, []string) (Session, error)
}

SessionFactory creates a fresh protocol session for one fenced generation.

type SessionState ¶

type SessionState string

const (
	SessionAbsent    SessionState = "absent"
	SessionOpening   SessionState = "opening"
	SessionReady     SessionState = "ready"
	SessionDraining  SessionState = "draining"
	SessionClosing   SessionState = "closing"
	SessionClosed    SessionState = "closed"
	SessionUncertain SessionState = "uncertain"
)

type Snapshot ¶

type Snapshot struct {
	Transport TransportState
	Session   SessionState
	Handle    *Handle
}

Snapshot reports the three independent lifecycle state machines.

type TransportState ¶

type TransportState string

const (
	TransportRunning  TransportState = "running"
	TransportDraining TransportState = "draining"
	TransportClosed   TransportState = "closed"
)