Documentation
¶
Overview ¶
Package component defines the public bring-up contract for services an embedding repository composes alongside deploy. A component is a value the embedding repository already owns: Core never constructs it, never reads its configuration, and never hands it Core state. Core owns only ordering — every registered component is assembled before the agent harness is constructed, started before the harness starts, and stopped after the harness closes, in the exact reverse of the resolved order.
Index ¶
Constants ¶
const ( // MaxNameBytes bounds a component name. MaxNameBytes = 64 // MaxEventBytes bounds an event passed to ICapabilities.Log. Together with // MaxNameBytes it keeps the namespaced record "component.<name>.<event>" // inside the 128-byte telemetry event field. MaxEventBytes = 48 )
Variables ¶
var ( // ErrNilOption reports a nil functional option, named by its 1-based // position in the option list. ErrNilOption = errors.New("component: option is nil") // ErrNilDefinition reports a nil definition supplied as a requirement or // to Order. ErrNilDefinition = errors.New("component: definition is nil") // ErrName reports a name outside the accepted grammar or byte bound. ErrName = errors.New("component: name must match [a-z][a-z0-9-]* within 64 bytes") // ErrMissingAssemble reports a definition constructed without WithAssemble. ErrMissingAssemble = errors.New("component: assemble function is required") // ErrRequirement reports a self-referential or repeated requirement. ErrRequirement = errors.New("component: invalid requirement") // ErrDuplicateName reports two definitions sharing one name in one ordered // set. ErrDuplicateName = errors.New("component: duplicate name") // ErrMissingRequirement reports a requirement that is absent from the // ordered set, naming both components. ErrMissingRequirement = errors.New("component: requirement is not in the ordered set") // ErrDependencyCycle reports a cycle, naming the full path it traverses. ErrDependencyCycle = errors.New("component: dependency cycle") )
Functions ¶
This section is empty.
Types ¶
type Definition ¶
type Definition struct {
// contains filtered or unexported fields
}
Definition is one immutable named unit of bring-up work. It holds no Core state, so a resolved order can be computed without any infrastructure.
func New ¶
func New(name string, options ...Option) (*Definition, error)
New validates the complete option set and returns an immutable definition.
func Order ¶
func Order(definitions ...*Definition) ([]*Definition, error)
Order resolves definitions into a deterministic initialization order using Kahn's algorithm with the ready set processed in registration order, never map iteration order. It is pure: it performs no I/O and invokes no definition function.
func (*Definition) Assemble ¶
func (definition *Definition) Assemble(ctx context.Context, capabilities ICapabilities) error
Assemble runs the required assembly function.
func (*Definition) Name ¶
func (definition *Definition) Name() string
Name reports the registered component name.
type ICapabilities ¶
type ICapabilities interface {
// Log writes one INFO record through Core's reporter as event
// "component.<name>.<event>", with message redacted of Core's configured
// secrets unless the embedding binary opted into raw diagnostics.
Log(ctx context.Context, event string, message string) error
}
ICapabilities is the only typed Core surface a component receives.
type Option ¶
type Option func(settings *settings) error
Option configures one Definition. New validates the complete option set before returning a definition.
func WithAssemble ¶
func WithAssemble(assemble func(ctx context.Context, capabilities ICapabilities) error) Option
WithAssemble sets the required assembly function. It runs during bootstrap.AssembleCore, before the harness factory is invoked. The component stores what it builds in the embedding repository's own variables; Core injects nothing.
func WithRequires ¶
func WithRequires(requirements ...*Definition) Option
WithRequires declares dependencies by pointer identity; repeatable.
func WithStart ¶
WithStart sets an optional start hook, run immediately before the harness starts. Its context is Core's lifecycle context, cancelled at shutdown, so goroutines started here are children of the Core lifecycle.
Source Files