exposure

Documentation

Overview

Package exposure is the registry of everything Flynn has open to the network: the record that makes the inbound-exposure boundary observable and time-bounded. Where bindguard decides whether a listener may bind (the gate) and netguard decides where the agent may connect (the egress gate), exposure tracks what is currently listening, why, since when, and until when, and tears it down when its lease ends.

The invariant it enforces is "nothing stays exposed silently": every listener opened through it is recorded and enumerable (List), logged on open and on close, and, when given a TTL, closed automatically when the lease expires rather than lingering until a process dies. An ephemeral exposure (a preview server, a temporary tunnel) is bounded by construction; a long-lived one (the control-plane API) is at least always visible.

The registry is the in-process record today; a durable, control-plane-visible resource kind is the natural upgrade once managed services land, and this is the mechanism it would write through.

Index

• type Meta
• type Record
• type Registry
  • func New(clk clock.Timing, obs observe.Logger) *Registry
  • func (r *Registry) List() []Record
  • func (r *Registry) Listen(network, addr string, exp bindguard.Exposure, meta Meta) (net.Listener, error)

Types

type Meta

type Meta struct {
	// Purpose is a short human label for the audit trail, e.g. "control-plane API".
	Purpose string
	// Exposed reports whether the bind reached beyond loopback (an explicit, audited
	// off-host exposure) rather than the loopback default.
	Exposed bool
	// TTL, when positive, is how long the exposure may live before the registry tears
	// it down automatically. Zero means no lease: it lives until closed explicitly.
	TTL time.Duration
}

Meta describes why something is exposed, for the audit record and the teardown lease.

type Record

type Record struct {
	ID       string
	Addr     string
	Purpose  string
	Exposed  bool
	OpenedAt time.Time
	// ExpiresAt is the lease deadline, or the zero time when there is no TTL.
	ExpiresAt time.Time
}

Record is a snapshot of one live exposure, returned by List for observation.

type Registry

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

Registry tracks live network exposures and enforces their leases. The zero value is not usable; build one with New. It is safe for concurrent use.

func New

func New(clk clock.Timing, obs observe.Logger) *Registry

New returns a Registry that schedules TTL teardown on clk and logs lifecycle events to obs. A nil clk uses the system clock; a nil obs discards.

func (*Registry) List

func (r *Registry) List() []Record

List returns a snapshot of the live exposures, sorted by open time, so an operator (or the control plane) can see exactly what is currently reachable.

func (*Registry) Listen

func (r *Registry) Listen(network, addr string, exp bindguard.Exposure, meta Meta) (net.Listener, error)

Listen opens a listener through the bind-safe gate (bindguard) and registers it, so every exposure flows through one chokepoint that records it. The returned listener is wrapped: closing it deregisters the exposure. If meta.TTL is positive, the registry closes the listener when the lease expires.