managed

Documentation

Overview

Package managed coordinates attach-or-start behavior while retaining exact ownership of only the daemon candidate it launches. Process creation, endpoint discovery, and transport implementations remain injected.

A Connector starts a daemon only when Discovery returns ErrEndpointNotFound. Existing endpoints, including incompatible or unauthenticated endpoints, are never killed, replaced, or silently bypassed. Startup is serialized by a caller-supplied current-user lock and bounded by both the operation context and the configured timeout. Failed or canceled launches are shut down and joined; Shutdown never targets a daemon found through Discovery. A candidate's process result is separate from its containment join: ownership is released only after Wait confirms that every owned resource is safe. A retryable or unclassified join failure permits a later proof attempt. An explicitly non-retryable join failure is retained for manual recovery and is returned by later Shutdown calls without repeating unsafe cleanup actions.

Index

• Variables
• type Candidate
• type Config
• type Connector
  • func New(config Config) (*Connector, error)
  • func (connector *Connector) Close() error
  • func (*Connector) Format(state fmt.State, _ rune)
  • func (*Connector) GoString() string
  • func (connector *Connector) Initialize(ctx context.Context, request client.InitializeRequest) (session client.Session, resultErr error)
  • func (*Connector) MarshalJSON() ([]byte, error)
  • func (connector *Connector) Shutdown(ctx context.Context) error
  • func (*Connector) String() string
• type Discovery
• type Starter
• type StartupLease
• type StartupLock

Variables

var (
	// ErrEndpointNotFound is returned only after secure discovery proves that no
	// usable endpoint metadata exists. It is the sole condition that authorizes
	// managed startup.
	ErrEndpointNotFound = errors.New("local daemon endpoint was not found")
	// ErrStartupTimeout reports that a launched daemon did not publish and serve
	// a usable endpoint within the configured startup budget.
	ErrStartupTimeout = errors.New("local daemon startup timed out")
	// ErrClosed reports use after the managed connector has closed.
	ErrClosed = errors.New("managed connector is closed")
	// ErrCandidateExited reports that the child launched by this connector
	// terminated before a usable initialized endpoint was available.
	ErrCandidateExited = errors.New("managed daemon candidate exited before startup completed")
	// ErrShutdownTimeout reports that an owned candidate did not join within the
	// connector's bounded shutdown budget.
	ErrShutdownTimeout = errors.New("managed daemon shutdown timed out")
	// ErrCandidateJoin reports that a candidate process exited, but one or more
	// of its owned containment resources could not yet be safely released.
	ErrCandidateJoin = errors.New("managed daemon candidate resources did not join")
)

Types

type Candidate

type Candidate interface {
	Done() <-chan struct{}
	Result() error
	BeginShutdown() error
	Wait(context.Context) error
}

Candidate is the exact child process lifetime returned by Starter. Done closes exactly once after the child exits and the platform supervisor has attempted its terminal cleanup. Result is safe after Done closes and reports only the child process outcome. BeginShutdown is idempotent and nonblocking. Wait honors its context and returns nil only after every process and containment resource owned by the candidate is safe to release. A Wait error may implement Retryable() bool. False means cleanup cannot safely be repeated and the candidate must remain owned for manual recovery.

type Config

type Config struct {
	Discovery       Discovery
	Starter         Starter
	StartupLock     StartupLock
	StartupTimeout  time.Duration
	RetryInterval   time.Duration
	ShutdownTimeout time.Duration
}

Config supplies platform-owned managed-start boundaries.

type Connector

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

Connector implements client.Connector with bounded attach-or-start policy.

func New

func New(config Config) (*Connector, error)

New constructs a managed connector without performing I/O.

func (*Connector) Close

func (connector *Connector) Close() error

Close is the context-free compatibility alias for bounded Shutdown. It does not close sessions already returned to callers.

func (*Connector) Format

func (*Connector) Format(state fmt.State, _ rune)

Format prevents every fmt verb from traversing dependency implementations.

func (*Connector) GoString

func (*Connector) GoString() string

GoString prevents %#v from recursively formatting dependency state.

func (*Connector) Initialize

func (connector *Connector) Initialize(
	ctx context.Context,
	request client.InitializeRequest,
) (session client.Session, resultErr error)

Initialize attaches to an existing endpoint or performs one serialized, bounded launch after secure discovery proves the endpoint is absent.

func (*Connector) MarshalJSON

func (*Connector) MarshalJSON() ([]byte, error)

MarshalJSON makes accidental structured serialization visibly redacted.

func (*Connector) Shutdown

func (connector *Connector) Shutdown(ctx context.Context) error

Shutdown closes admission, cancels in-flight initialization, and boundedly shuts down and joins only the exact candidate launched by this connector. A daemon discovered before launch is external and is never stopped.

func (*Connector) String

func (*Connector) String() string

String prevents dependency implementations from leaking endpoint material.

type Discovery

type Discovery interface {
	Discover(context.Context) (client.Connector, error)
}

Discovery resolves current-user endpoint state into a configured connector. It must return ErrEndpointNotFound only after safely handling stale metadata; malformed, untrusted, or incompatible metadata is a hard error.

type Starter

type Starter interface {
	Start(context.Context) (Candidate, error)
}

Starter launches one local daemon candidate whose lifetime is independent of the launch context. A non-nil candidate returned with an error is still owned by the caller and will be shut down and joined.

type StartupLease

type StartupLease interface {
	Release() error
}

StartupLease releases one acquired startup lock. Release must be idempotent and nonblocking so cleanup cannot escape the bounded startup operation.

type StartupLock

type StartupLock interface {
	Acquire(context.Context) (StartupLease, error)
}

StartupLock serializes discovery recheck and process launch across clients.