owner

Documentation

Overview

Package owner manages lease-based ownership of the local runtime's resident state. On Join, one instance becomes the owner — it holds the lease and renews it in the background — while others become followers that know who the owner is and (later) where to reach it.

The owner self-fences: if it cannot renew before the lease expires, Lost() fires and the caller MUST stop touching owned state, because another instance may have taken over. This is the in-process, no-daemon, cross-platform owner election described in docs/blueprints/local-runtime-owner-coordination.md.

Index

• Constants
• type Config
• type Owner
  • func Join(ctx context.Context, cfg Config) (*Owner, error)
  • func (o *Owner) Endpoint() string
  • func (o *Owner) Holder() liblease.Record
  • func (o *Owner) InstanceID() string
  • func (o *Owner) IsOwner() bool
  • func (o *Owner) Lost() <-chan struct{}
  • func (o *Owner) LostErr() error
  • func (o *Owner) Release() error
  • func (o *Owner) Role() Role
• type Role
  • func (r Role) String() string

Constants

const EndpointMetaKey = "endpoint"

EndpointMetaKey is the lease metadata key used to advertise the owner's transport endpoint.

Types

type Config

type Config struct {
	// LeasePath is the lease file; one owner per path (per user + data root).
	LeasePath string
	// TTL is the lease duration.
	TTL time.Duration
	// RenewInterval is how often the owner renews; defaults to TTL/3.
	RenewInterval time.Duration
	// Endpoint, if set, is advertised to followers via the lease record so they
	// can reach the owner once it serves a transport (P3). Empty = not serving.
	Endpoint string
}

Config controls a Join.

type Owner

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

Owner is the result of a Join: either this instance (RoleOwner) with a running renew loop, or a handle describing the current owner (RoleFollower).

func Join

func Join(ctx context.Context, cfg Config) (*Owner, error)

Join attempts to acquire ownership of the lease at cfg.LeasePath. If the lease is free it returns an Owner in RoleOwner and starts renewing in the background; if a live owner already holds it, it returns RoleFollower with the current holder. ctx bounds the renew loop's lifetime; cancelling it stops renewal (call Release for a clean handover).

func (*Owner) Endpoint

func (o *Owner) Endpoint() string

Endpoint returns the owner's advertised endpoint, or "" if none.

func (*Owner) Holder

func (o *Owner) Holder() liblease.Record

Holder returns the current owner's lease record.

func (*Owner) InstanceID

func (o *Owner) InstanceID() string

InstanceID is this owner's id, or the current owner's id for a follower.

func (*Owner) IsOwner

func (o *Owner) IsOwner() bool

IsOwner reports whether this instance holds the lease.

func (*Owner) Lost

func (o *Owner) Lost() <-chan struct{}

Lost is closed when the owner can no longer renew the lease (taken over or an I/O failure). The caller must stop touching owned state when it fires. It never fires for a follower.

func (*Owner) LostErr

func (o *Owner) LostErr() error

LostErr returns why ownership was lost, after Lost fires.

func (*Owner) Release

func (o *Owner) Release() error

Release stops renewing and relinquishes the lease so a successor can take over immediately rather than waiting out the TTL. Safe to call multiple times; a no-op for a follower.

func (*Owner) Role

func (o *Owner) Role() Role

Role reports whether this instance is the owner or a follower.

type Role

type Role int

Role is whether this instance owns the lease.

const (
	// RoleFollower means another instance currently owns the lease.
	RoleFollower Role = iota
	// RoleOwner means this instance holds and renews the lease.
	RoleOwner
)

func (Role) String

func (r Role) String() string