node

package
v0.6.31 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package node is the service's one lifecycle model: a tree of nodes, each with a name, a logger, an instrumentation scope, start and stop hooks, its own goroutines and an optional readiness probe.

The SDK's own parts (config, listeners, presence) and the author's components and dependencies are nodes of the same tree. Start walks the tree depth-first in creation order; Stop walks it back in exact reverse, so a node always stops before anything created ahead of it — a component before the dependency it uses, a child before its parent.

Stopping a node cancels its context, runs its stop hooks in reverse, then waits for its goroutines. A node whose start failed is stopped too: stop hooks must tolerate a partial start.

Index

Constants

View Source
const DefaultProbeInterval = 5 * time.Second

DefaultProbeInterval is the ProbeInterval of a tree that sets none.

Variables

View Source
var (
	ErrStopTimeout = lifecycle.ErrStopTimeout
	ErrPanic       = lifecycle.ErrPanic
)

Lifecycle errors are shared with xshutdown.

Functions

This section is empty.

Types

type Condition

type Condition struct {
	Ready bool
	Err   error
}

Condition is a node's current state as a dependency: ready, or why not.

type Group

type Group interface {
	Go(fn func(ctx context.Context) error)
}

Group runs goroutines owned by a node; *Node is one.

type Kind

type Kind int

Kind of node.

const (
	System Kind = iota
	Root
	Component
	Dependency
	Singleton
)

Node kinds. System nodes are the SDK's own; Root is the author's tree.

type Node

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

Node is one element of the tree.

func New

func New(service string, log *xlog.Logger, env any) *Node

New creates a tree and returns its service root. env is service-wide data any node can reach through Env.

func (*Node) Budget

func (n *Node) Budget(fn func(context.Context) (context.Context, context.CancelFunc))

Budget narrows this node's shutdown deadline without changing its children.

func (*Node) Child

func (n *Node) Child(name string, kind Kind, optional bool) *Node

Child creates a node under n. Names are unique within a namespace: a duplicate path gets a numeric suffix. After Start only a starting parent may create children (a dependency building its internals); anything else is a programming error and panics.

func (*Node) Children

func (n *Node) Children() []*Node

Children are n's direct children in creation (start) order.

func (*Node) Condition

func (n *Node) Condition() (Condition, bool)

Condition of the node; false for a node that reports none.

func (*Node) Env

func (n *Node) Env() any

Env is the service-wide data given to New.

func (*Node) Failed

func (n *Node) Failed() <-chan error

Failed delivers the first background failure of the tree.

func (*Node) Go

func (n *Node) Go(fn func(context.Context) error)

Go registers work owned by this node's lifetime.

func (*Node) Kind

func (n *Node) Kind() Kind

Kind of the node.

func (*Node) Log

func (n *Node) Log() *xlog.Logger

Log is the node's logger.

func (*Node) Name

func (n *Node) Name() string

Name of the node.

func (*Node) OnStart

func (n *Node) OnStart(fn func(context.Context) error)

OnStart adds a startup hook.

func (*Node) OnStop

func (n *Node) OnStop(fn func(context.Context) error)

OnStop adds a cleanup hook, invoked in reverse order.

func (*Node) Optional

func (n *Node) Optional() bool

Optional reports whether the node is an optional dependency.

func (*Node) Path

func (n *Node) Path() string

Path of the node within its namespace ("" for a root).

func (*Node) ProbeInterval

func (n *Node) ProbeInterval() time.Duration

ProbeInterval is how often the service evaluates its health.

func (*Node) Readiness

func (n *Node) Readiness() probe.Probe

Readiness is the readiness of n's subtree, evaluated on every check so nodes created during start count too.

func (*Node) Ready

func (n *Node) Ready(p probe.Probe)

Ready makes p part of the service readiness.

func (*Node) Scope

func (n *Node) Scope() *xtrace.Scope

Scope is the node's instrumentation scope.

func (*Node) SetCondition

func (n *Node) SetCondition(fn func() Condition)

SetCondition installs what Condition reports.

func (*Node) SetProbeInterval

func (n *Node) SetProbeInterval(d time.Duration)

SetProbeInterval sets how often the service evaluates its health, for nodes that check something periodically; d <= 0 keeps the default.

func (*Node) Start

func (n *Node) Start(ctx context.Context) error

Start starts the lifecycle tree.

func (*Node) Stop

func (n *Node) Stop(ctx context.Context) error

Stop unwinds the lifecycle tree.

func (*Node) Walk

func (n *Node) Walk(fn func(*Node))

Walk visits n's subtree depth-first in creation order.

type Tree

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

Tree is shared by every node of one service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL