component

package
v0.1.0-alpha.1 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 24 Imported by: 0

README

Component Package

The component model every SemEngine component builds on: factory registration, immutable port declarations, typed ports, configuration schemas, and the lifecycle interface.

import "github.com/c360studio/semengine/component"

Overview

A component is one self-describing unit of a SemEngine process. There are five kinds: inputs (data sources), processors (data transformers), outputs (data sinks), storage (persistence), and gateways (query surfaces). Each one reports its metadata, its ports, its configuration schema, its health, and its data flow through the Discoverable interface.

The terms this README uses:

  • Factory: a function that builds a component from its raw JSON configuration and a Dependencies value. It decodes the configuration and does no I/O; the component's I/O starts in Start.
  • Port declarer: a function, registered beside the factory, that derives the component's ports from the same raw configuration without building anything. It lets a tool read a component's ports offline.
  • Declaration: the immutable port shape of one component instance (its name, factory, ports, and the resources it holds exclusively). The Registry keeps declarations, never the live component.
  • Boot admission: building each configured instance once at process start, checking that the ports the component reports equal the ports its declarer derives, and recording its declaration.
  • Sealing: closing boot admission. After SealComposition, the Registry refuses to create or admit another component until the process starts again with a new Registry.
  • Component manager: service.ComponentManager, which owns every live component and its lifecycle. It is not yet in SemEngine; it arrives with setup change 3.

Registration

A component package exports a Register(registry) function instead of registering itself in init(). The host creates a Registry, calls each package's Register, and hands the registry to the component manager. The manager calls CreateComponent for each enabled instance and then SealComposition.

Explicit registration keeps package imports free of side effects: a test builds a registry holding only the components it needs, and the host decides what is registered and in which order. The cost is that a new component package must be added to the host's list of Register calls.

Implementing a component

package mycomponent

import (
    "encoding/json"

    "github.com/c360studio/semengine/component"
)

// Config is this component's configuration; its factory decodes it.
type Config struct {
    Subject string `json:"subject"`
}

var schema = component.ConfigSchema{
    Properties: map[string]component.PropertySchema{
        "subject": {Type: "string", Description: "NATS subject the input publishes on"},
    },
    Required: []string{"subject"},
}

// outputPorts derives the ports from the configuration. The port declarer and
// the component both call it, so the declared and the reported ports agree.
func outputPorts(cfg Config) []component.Port {
    return []component.Port{{
        Name:      "output",
        Direction: component.DirectionOutput,
        Required:  true,
        Config:    component.NATSPort{Subject: cfg.Subject},
    }}
}

// declarePorts is the port declarer: no dependencies, no I/O.
func declarePorts(raw json.RawMessage, _ string) (component.PortConfig, error) {
    var cfg Config
    if err := json.Unmarshal(raw, &cfg); err != nil {
        return component.PortConfig{}, err
    }
    return component.PortConfigFrom(nil, outputPorts(cfg)), nil
}

type Input struct {
    cfg  Config
    deps component.Dependencies
}

func (c *Input) Meta() component.Metadata {
    return component.Metadata{Name: "my-input", Type: "input", Description: "Example input", Version: "1.0.0"}
}
func (c *Input) InputPorts() []component.Port         { return nil }
func (c *Input) OutputPorts() []component.Port        { return outputPorts(c.cfg) }
func (c *Input) ConfigSchema() component.ConfigSchema { return schema }
func (c *Input) Health() component.HealthStatus       { return component.HealthStatus{Healthy: true} }
func (c *Input) DataFlow() component.FlowMetrics      { return component.FlowMetrics{} }

// create is the factory.
func create(raw json.RawMessage, deps component.Dependencies) (component.Discoverable, error) {
    var cfg Config
    if err := json.Unmarshal(raw, &cfg); err != nil {
        return nil, err
    }
    return &Input{cfg: cfg, deps: deps}, nil
}

// Register adds this package's factory to a registry. The host calls it.
func Register(registry *component.Registry) error {
    return registry.RegisterWithConfig(component.RegistrationConfig{
        Name:        "my-input",
        Factory:     create,
        Ports:       declarePorts,
        Schema:      schema,
        Type:        "input",
        Protocol:    "nats",
        Domain:      "example",
        Description: "Example input",
        Version:     "1.0.0",
    })
}

A component that does work also implements LifecycleComponent: Initialize() error, Start(ctx) error and Stop(ctx) error beside Discoverable. Start and Stop refuse a nil context, and Stop joins the work Start began. AsLifecycleComponent reports whether a Discoverable implements it.

core Concepts

Discoverable Interface

Every component must implement:

type Discoverable interface {
    Meta() Metadata                  // Component metadata
    InputPorts() []Port              // Input port definitions
    OutputPorts() []Port             // Output port definitions
    ConfigSchema() ConfigSchema      // Configuration schema
    Health() HealthStatus            // Current health status
    DataFlow() FlowMetrics          // Data flow metrics
}
Dependencies

What the host passes to every factory:

type Dependencies struct {
    NATSClient      *natsclient.Client        // required: CreateComponent refuses a nil client
    MetricsRegistry *metric.MetricsRegistry   // may be nil
    Logger          *slog.Logger              // may be nil; GetLogger falls back to slog.Default()
    Platform        PlatformMeta              // the deployment's organization and platform
    Security        security.Config           // platform-wide security configuration
    ModelRegistry   model.RegistryReader      // the model registry chosen at boot; may be nil
    PayloadRegistry *payloadregistry.Registry // may be nil; a component that decodes BaseMessage needs it
    StoreRegistry   *storeregistry.Registry   // the stores storage components provide, filled by the manager
}

Dependencies carries no lifecycle manager and no tool registry. A component that needs the lifecycle manager (pkg/lifecycle) receives it from the host when it is registered or constructed. A contract test (internal/harness/contract/componentdeps_test.go) fails if component comes to import, directly or through another package, an agentic package, graph or a package under it, internal/graphmutation, pkg/lifecycle, or pkg/projection other than pkg/projection/contract.

Ports

A Port has a name, a direction, and a typed configuration (Config) that says what the port binds to:

// Core NATS publish or subscribe
component.NATSPort{Subject: "data.output"}

// JetStream stream and its subjects
component.JetStreamPort{StreamName: "EVENTS", Subjects: []string{"events.>"}}

// KV bucket watch; no keys means every key
component.KVWatchPort{Bucket: "CONFIG", Keys: []string{"app.*"}}

// KV bucket write, with the payload type it writes
component.KVWritePort{
    Bucket:    "ENTITY_STATES",
    Interface: &component.InterfaceContract{Type: "graph.EntityState", Version: "v1"},
}

// Network listener
component.NetworkPort{Protocol: "udp", Host: "0.0.0.0", Port: 14550}

The other port types are NATSRequestPort (request and reply), KVReadPort, HTTPClientPort, FilePort, TimerPort, StoreReadPort and StoreProvidePort, each in a port_*.go file.

Registry

  • NewRegistry() returns an empty registry.
  • RegisterWithConfig(RegistrationConfig) registers a factory and its static metadata. It refuses an empty name, a nil factory, an empty type, a nil port declarer (Ports), and a name already registered.
  • ListFactories() returns a copy of each registration's metadata, without its factory function; it returns no live component.
  • Declare(instanceName, config) runs a factory's port declarer for one configured instance and returns its Declaration, without building the component.
  • CreateComponent(instanceName, config, deps, prepare), SealComposition() and Snapshots() exist for the component manager. A consumer creates and composes components through that manager; a direct call is not refused, but it bypasses the manager's bookkeeping. CreateComponent refuses a disabled instance, a nil Dependencies.NATSClient, a port declaration that differs from the ports the built component reports, an instance name already admitted, an exclusive resource another instance holds, and any call after SealComposition. prepare may be nil.
Types
Factory
type Factory func(rawConfig json.RawMessage, deps Dependencies) (Discoverable, error)

Factory function signature for component creation.

Errors

Every refusal from RegisterWithConfig is a pkg/errs error of the invalid class:

err := registry.RegisterWithConfig(registration)
if errs.IsInvalid(err) {
    // A required field is missing, or the name is already registered.
}

CreateComponent wraps a factory's own error with errs.Wrap, so its class is the one the factory chose.

Concurrency

Every Registry method is safe for concurrent use; one read-write mutex guards the factories, the declarations and the sealed flag. A factory and a port declarer run without that mutex held. Sealing stops CreateComponent; it does not stop RegisterWithConfig.

Testing

  • Build a registry per test with NewRegistry() and register only the components the test needs; no registry is process-global.
  • A test in this module that needs NATS opens a server through internal/harness/natsfixture (natsfixture.Open).
  • Test a component through its Discoverable and LifecycleComponent methods, not its private fields.

Architecture Decisions

Explicit Registration vs init()

Decision: Use explicit Register() functions

Rationale:

  • Testability: Can create isolated registries without global state
  • Explicitness: Clear component dependency graph in the host's list of Register calls
  • Control: Application controls what gets registered and when
  • No side effects: Package imports don't modify global state
  • Deterministic: Registration order is explicit and controllable

Tradeoffs:

  • Requires the host to keep a list of Register calls
  • Registration must be explicitly called in main()
  • New components must be added to the host's list of Register calls
Dependency Injection via Struct

Decision: Use Dependencies struct

Rationale:

  • Avoids parameter proliferation
  • Easy to add dependencies without breaking factories
  • Enables testing with mock dependencies
  • Follows service architecture patterns
Factory Pattern

Decision: Components parse their own configuration

Rationale:

  • Enables flexible validation per component
  • Matches service constructor patterns
  • Centralizes configuration knowledge in component packages

service (the component manager) and componentregistry (a host's list of Register calls) are not yet in SemEngine.

Documentation

Overview

Package component defines the Discoverable interface and related types

Package component defines SemEngine component factories, lifecycle interfaces, dependencies, configuration schemas, ports, and immutable registry declarations.

Applications register component factories explicitly during process composition. Factories are side-effect free: they construct a Discoverable, while I/O begins in Start and all owned work joins Stop.

Component creation is a boot operation of the component manager (service.ComponentManager). It constructs every enabled component from its constructor-captured configuration, captures the component's declared ports and resources, and admits an immutable declaration to Registry. The manager retains the concrete handle as the sole lifecycle owner. Registry does not refuse a direct call; such a call bypasses the manager's bookkeeping.

Registry read surfaces return defensive values and never expose a live component handle. Once boot admission is complete, Registry is sealed; later component admission attempts fail until another process boot creates a fresh Registry.

Discoverable components describe metadata, health, flow metrics, schemas, and typed ports. Port declarations support core NATS subjects, JetStream, KV watches and writes, request/reply, network listeners, APIs, and related framework patterns. Registry.Declare produces the same declaration values offline, for static diagram validation, without constructing a component.

Package component provides port configuration and management for component connections.

Package component provides schema validation and helper functions

Package component provides schema tag parsing and generation for component configuration.

The schema tag system eliminates duplication between Config structs and ConfigSchema definitions by auto-generating schemas from struct tags. This provides a single source of truth for configuration metadata and follows Go stdlib patterns (similar to json tags).

Basic Usage

Define configuration with schema tags:

type MyConfig struct {
    Name string `json:"name" schema:"type:string,description:Component name,category:basic"`
    Port int    `json:"port" schema:"type:int,description:Port,min:1,max:65535,default:8080"`
}

Generate schema at init time:

var schema = component.GenerateConfigSchema(reflect.TypeOf(MyConfig{}))

Tag Syntax

Tags use comma-separated directives with colon-separated key-value pairs:

  • type:string - Field data type (required)
  • description:text - Field description (recommended)
  • category:basic - UI organization (basic or advanced)
  • default:value - Default value
  • min:N, max:N - Numeric constraints
  • enum:a|b|c - Valid enum values (pipe-separated)
  • readonly, editable - Boolean flags for PortDefinition fields
  • required, hidden - Boolean flags for validation and UI

Performance

Schema generation uses reflection but is designed for init-time execution:

  • Call GenerateConfigSchema once at package init
  • Cache result in package-level variable
  • Zero reflection cost at runtime

Error Handling

Invalid tags result in graceful degradation:

  • Fields with invalid tags are skipped
  • Errors are wrapped with context using pkg/errors
  • Missing descriptions use field names as fallback

See docs/architecture/SCHEMA_TAG_SPEC.md for complete specification.

Index

Examples

Constants

View Source
const (
	MaxStringLength = 1024        // Maximum length for string values
	MaxJSONSize     = 1024 * 1024 // Maximum JSON size (1MB)
)

Config validation constants - security limits

View Source
const (
	// DepModelRegistry signals that a component consumes
	// Dependencies.ModelRegistry at construction or run time. Components
	// that declare this consume the model registry selected at boot.
	// Later model_registry writes require process restart.
	DepModelRegistry = "model-registry"
)

Dependency identifiers used by Registration.Dependencies. Components declare these at registration to opt into framework-driven behavior (e.g., restart when a named runtime dependency changes). Kept as typed constants so refactors are compiler-checked.

Variables

This section is empty.

Functions

func GenerateCacheFieldSchema

func GenerateCacheFieldSchema() map[string]CacheFieldInfo

GenerateCacheFieldSchema generates metadata for cache.Config fields. This describes which fields in cache.Config are editable and their constraints, enabling the UI to render appropriate controls for cache configuration.

The function examines cache.Config struct tags to determine:

  • Field types (for appropriate UI controls)
  • Editability (whether users can modify the field)
  • Enum values (for strategy field)
  • Numeric constraints (for size limits)

All cache.Config fields are marked as "editable" to allow runtime configuration.

This metadata is included in ConfigSchema for fields with type "cache", allowing the frontend to correctly render cache configuration forms.

Returns:

  • Map of field names to CacheFieldInfo with type, editability, and constraint metadata

func GeneratePortFieldSchema

func GeneratePortFieldSchema() map[string]PortFieldInfo

GeneratePortFieldSchema returns the canonical common-envelope metadata. Kind-specific data remains inside config and is validated by the closed port binding table; schema generation does not reflect retired flat fields.

This metadata is included in ConfigSchema for fields with type "ports", allowing the frontend to correctly render port configuration forms.

Returns:

  • Map of field names to PortFieldInfo with type and editability metadata

func ResolveSubject

func ResolveSubject(ports []PortDefinition, portName, suffix string) (string, error)

ResolveSubject returns the configured NATS subject for one uniquely named port with a trailing wildcard replaced by suffix.

func SafeUnmarshal

func SafeUnmarshal(rawConfig json.RawMessage, target any) error

SafeUnmarshal performs validated unmarshaling into a target struct It validates the JSON first, then unmarshals with additional type checking

func ValidateComponentName

func ValidateComponentName(name string) error

ValidateComponentName validates component/instance names for security

func ValidateFactoryConfig

func ValidateFactoryConfig(rawConfig json.RawMessage) error

ValidateFactoryConfig performs validation before passing to factory This is the main security gate for all component configurations

Types

type CacheFieldInfo

type CacheFieldInfo struct {
	Type     string   `json:"type"`
	Editable bool     `json:"editable"`
	Enum     []string `json:"enum,omitempty"` // For strategy field
	Min      *int     `json:"min,omitempty"`  // For numeric fields
}

CacheFieldInfo describes metadata for cache.Config fields

type ConfigSchema

type ConfigSchema struct {
	Properties map[string]PropertySchema `json:"properties"`
	Required   []string                  `json:"required"`
}

ConfigSchema describes the configuration parameters for a component

func GenerateConfigSchema

func GenerateConfigSchema(configType reflect.Type) ConfigSchema

GenerateConfigSchema generates a ConfigSchema from a struct type using reflection. This function performs one-time reflection at initialization to extract schema metadata from struct field tags, eliminating the need for manual schema definitions.

Usage Pattern:

type MyComponentConfig struct {
    Name string `json:"name" schema:"type:string,description:Name,category:basic"`
    Port int    `json:"port" schema:"type:int,description:Port,min:1,max:65535"`
}

var schema = component.GenerateConfigSchema(reflect.TypeOf(MyComponentConfig{}))

Field Processing:

  • Only exported fields with both 'json' and 'schema' tags are included
  • json:"-" fields are skipped
  • Fields without schema tags are skipped
  • Invalid schema tags result in skipped fields (graceful degradation)

Special Handling:

  • Fields with type "ports" automatically include PortFieldSchema metadata
  • Default values are converted from strings to appropriate types
  • Required fields are added to the schema's Required list

Performance:

  • Call once at init() time - reflection cost is paid only once
  • Generated schemas are cached in package-level variables
  • Zero reflection overhead at runtime

Parameters:

  • configType: The reflect.Type of the config struct (use reflect.TypeOf(ConfigStruct{})) Pointer types are automatically dereferenced

Returns:

  • ConfigSchema with Properties map and Required list populated from struct tags
  • Empty schema for non-struct types
Example

ExampleGenerateConfigSchema demonstrates how to use schema tags to auto-generate configuration schemas from struct definitions

package main

import (
	"encoding/json"
	"fmt"
	"reflect"

	"github.com/c360studio/semengine/component"
)

func main() {
	// Define a configuration struct with schema tags
	type ComponentConfig struct {
		// Basic configuration
		Name    string `json:"name"    schema:"type:string,description:Component name,category:basic"`
		Port    int    `json:"port"    schema:"type:int,description:Listen port,min:1,max:65535,default:8080,category:basic"`
		Enabled bool   `json:"enabled" schema:"type:bool,description:Enable component,default:true,category:basic"`

		// Advanced configuration
		Timeout  string `json:"timeout"   schema:"type:string,description:Request timeout,default:30s,category:advanced"`
		LogLevel string `json:"log_level" schema:"type:enum,description:Logging level,enum:debug|info|warn|error,default:info,category:advanced"`

		// Required field
		APIKey string `json:"api_key" schema:"required,type:string,description:Authentication API key"`
	}

	// Generate the schema at init time (one-time reflection cost)
	schema := component.GenerateConfigSchema(reflect.TypeOf(ComponentConfig{}))

	// The generated schema can be used for validation, UI generation, etc.
	schemaJSON, _ := json.MarshalIndent(schema, "", "  ")
	fmt.Println(string(schemaJSON))

	// Output will show the generated schema with all properties
}

type ConfigValidator

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

ConfigValidator provides secure validation for component configurations

func NewConfigValidator

func NewConfigValidator() *ConfigValidator

NewConfigValidator creates a validator with secure defaults

func (*ConfigValidator) ValidateConfig

func (v *ConfigValidator) ValidateConfig(rawConfig json.RawMessage) error

ValidateConfig performs comprehensive validation on raw JSON config This prevents injection attacks, resource exhaustion, and malformed input

type ConsumerConfig

type ConsumerConfig struct {
	DeliverPolicy     string
	AckPolicy         string
	MaxDeliver        int
	AckWait           time.Duration
	HeartbeatInterval time.Duration
	MaxAckPending     int // 0 = inherited/default/capped server policy; -1 = unlimited outstanding acks (gh#480)
}

ConsumerConfig holds extracted JetStream consumer configuration.

Duration fields (AckWait, HeartbeatInterval) are zero-valued when the port-level string is empty; consumers may apply their component default. Invalid declarations are rejected before a ConsumerConfig is returned.

func GetConsumerConfig

func GetConsumerConfig(port Port) (ConsumerConfig, error)

GetConsumerConfig validates a JetStream port through the canonical facts projection and extracts its consumer configuration. A non-JetStream or invalid port returns an error rather than silently receiving defaults. Unset fields receive these defaults: - DeliverPolicy: "new" (safe default - don't replay historical messages) - AckPolicy: "explicit" - MaxDeliver: 3 - AckWait, HeartbeatInterval: zero (caller applies per-component default)

type DebugStatusProvider

type DebugStatusProvider interface {
	// DebugStatus returns extended debug information for the component.
	// The returned value should be JSON-serializable.
	DebugStatus() any
}

DebugStatusProvider is an optional interface for components that can provide extended debug information beyond basic health status.

type Declaration

type Declaration struct {
	InstanceName       string
	FactoryIdentity    string
	ComponentType      types.ComponentType
	InputPorts         []Port
	OutputPorts        []Port
	InputFacts         []PortFacts
	OutputFacts        []PortFacts
	ExclusiveResources []string
}

Declaration is the immutable port shape of one component instance: what the Registry retains for an admitted component, and what Declare produces for a configured-but-unconstructed one. It carries no lifecycle, health, readiness, grouping, or orchestration state.

type Dependencies

type Dependencies struct {
	NATSClient      *natsclient.Client        // NATS client for messaging
	MetricsRegistry *metric.MetricsRegistry   // Metrics registry for Prometheus (can be nil)
	Logger          *slog.Logger              // Structured logger (can be nil, defaults to slog.Default())
	Platform        PlatformMeta              // Platform identity (organization and platform)
	Security        security.Config           // Platform-wide security configuration
	ModelRegistry   model.RegistryReader      // Boot-selected model registry (can be nil)
	PayloadRegistry *payloadregistry.Registry // Shared payload registry (can be nil; components unmarshaling BaseMessage require it)

	// StoreRegistry is the shared {StorageInstance → storage.StreamableStore}
	// resolver (ADR-063). The ComponentManager populates it from the boot-composed
	// storage components' store-provide ports at Start and clears entries at Stop;
	// content-fetch consumers (graph-embedding, fusion) resolve a StorageRef's
	// StorageInstance through it, lazily per-fetch. Concrete framework-leaf type
	// per the PayloadRegistry precedent.
	//
	// Can be nil — deployments with no offloaded-content fetch pay zero cost. A
	// consumer that receives a StorageReference without this exact-name authority
	// reports content-unresolved and excludes the body; it never selects another
	// store or degrades solely because the name is unresolved.
	StoreRegistry *storeregistry.Registry
}

Dependencies provides all external dependencies needed by components.

It carries no lifecycle manager and no tool registry. A component that needs the lifecycle manager receives it from its host when it is registered or constructed, so importing component reaches no graph or agentic package.

PayloadRegistry uses the concrete *payloadregistry.Registry rather than an interface on purpose: payloadregistry is a leaf package this package already imports, so there's no cycle to dodge, and message.NewDecoder also requires the concrete type. An interface here would force callers to type-assert at every Decoder construction site — pure friction for no abstraction win.

func (*Dependencies) GetLogger

func (d *Dependencies) GetLogger() *slog.Logger

GetLogger returns the configured logger or a default logger if none is provided

func (*Dependencies) GetLoggerWithComponent

func (d *Dependencies) GetLoggerWithComponent(componentName string) *slog.Logger

GetLoggerWithComponent returns a logger configured with component context

type Direction

type Direction string

Direction identifies whether data enters or leaves a component.

const (
	DirectionInput  Direction = "input"
	DirectionOutput Direction = "output"
)

Direction constants for port data flow.

type Discoverable

type Discoverable interface {
	// Meta returns basic component information
	Meta() Metadata

	// InputPorts returns the ports this component accepts data on
	InputPorts() []Port

	// OutputPorts returns the ports this component produces data on
	OutputPorts() []Port

	// ConfigSchema returns the configuration schema for this component
	ConfigSchema() ConfigSchema

	// Health returns current health status
	Health() HealthStatus

	// DataFlow returns current data flow metrics
	DataFlow() FlowMetrics
}

Discoverable defines the interface for components that can be discovered and inspected by the management layer. This interface enables dynamic discovery of component capabilities, configuration, and health status.

Components implementing this interface can be: - Input components: Accept external data (UDP, TCP, HTTP) - Processor components: Transform data (plugins) - Output components: Send data to external systems - Storage components: Store and retrieve data (ObjectStore, KV)

type Factory

type Factory func(rawConfig json.RawMessage, deps Dependencies) (Discoverable, error)

Factory creates a component instance from configuration following service pattern The factory function receives raw JSON configuration and dependencies, parses its own config, and returns a properly initialized component that implements the Discoverable interface. All I/O operations should be performed in the component's Start() method, not in the factory. This pattern matches service constructors: func(rawConfig json.RawMessage, deps Dependencies) (Service, error)

type FilePort

type FilePort struct {
	Path    string `json:"path"`
	Pattern string `json:"pattern,omitempty"`
}

FilePort - File system access

func (FilePort) IsExclusive

func (f FilePort) IsExclusive() bool

IsExclusive returns false as multiple components can read files

func (FilePort) Kind

func (f FilePort) Kind() PortKind

Kind returns the canonical port kind.

func (FilePort) ResourceID

func (f FilePort) ResourceID() string

ResourceID returns unique identifier for file ports

type FlowMetrics

type FlowMetrics struct {
	MessagesPerSecond float64   `json:"messages_per_second"`
	BytesPerSecond    float64   `json:"bytes_per_second"`
	ErrorRate         float64   `json:"error_rate"`
	LastActivity      time.Time `json:"last_activity"`
}

FlowMetrics describes the current data flow through a component

type HTTPClientPort

type HTTPClientPort struct {
	Method        string             `json:"method,omitempty"`         // Required HTTP method
	URLPattern    string             `json:"url_pattern"`              // target endpoint/resource pattern; NO inline creds, NO query-string secrets
	TriggerPort   string             `json:"trigger_port,omitempty"`   // NAME of a sibling TimerPort driving cadence (empty = event-driven/internal)
	AuthRef       string             `json:"auth_ref,omitempty"`       // credential key name resolved at runtime; NEVER a secret value; empty = unauthenticated
	ContactPolicy string             `json:"contact_policy,omitempty"` // public User-Agent/contact identity (feeds often require it); not a secret
	Interface     *InterfaceContract `json:"interface,omitempty"`      // message-interface contract this port produces
}

HTTPClientPort describes an outbound HTTP-client / polling input dependency: a relationship where the component initiates connections to an external HTTP resource (REST API, alert feed, snapshot endpoint) rather than binding a listener (NetworkPort) or consuming a NATS subject (NATSPort).

It is a DESCRIPTOR, not a runtime — like TimerPort it declares the dependency shape so lifecycle/config/health/flowgraph/ownership/telemetry tooling can SEE it; the polling/HTTP execution stays in the component. Cadence is NOT owned here: when polling is timer-driven the component also declares a TimerPort and this port references it by name via TriggerPort (single source of truth for the interval).

Secrets never appear in this descriptor. AuthRef carries a credential REFERENCE (a key name resolved at runtime from the component's secret source), never a value. No field holds a secret.

func (HTTPClientPort) IsExclusive

func (h HTTPClientPort) IsExclusive() bool

IsExclusive returns false: an outbound client relationship is shareable (multiple components may poll the same endpoint), unlike a NetworkPort listener.

func (HTTPClientPort) Kind

func (h HTTPClientPort) Kind() PortKind

Kind returns the canonical port kind.

func (HTTPClientPort) ResourceID

func (h HTTPClientPort) ResourceID() string

ResourceID returns a unique identifier for the HTTP client dependency. Two ports with the same method and URL pattern identify the same external resource.

type HealthStatus

type HealthStatus struct {
	Healthy    bool          `json:"healthy"`
	LastCheck  time.Time     `json:"last_check"`
	ErrorCount int           `json:"error_count"`
	LastError  string        `json:"last_error,omitempty"`
	Uptime     time.Duration `json:"uptime"`
	Status     string        `json:"status"`
}

HealthStatus describes the current health state of a component

type InteractionPattern

type InteractionPattern string

InteractionPattern is the canonical communication behavior of a resolved port.

const (
	PatternTimer      InteractionPattern = "timer"
	PatternNetwork    InteractionPattern = "network"
	PatternHTTPClient InteractionPattern = "http-client"
	PatternStream     InteractionPattern = "stream"
	PatternRequest    InteractionPattern = "request"
	PatternWatch      InteractionPattern = "watch"
	PatternRead       InteractionPattern = "read"
	PatternStore      InteractionPattern = "store"
)

Canonical interaction patterns projected from resolved ports.

type InterfaceContract

type InterfaceContract struct {
	Type       string   `json:"type"`
	Version    string   `json:"version,omitempty"`
	Compatible []string `json:"compatible,omitempty"`
}

InterfaceContract defines the payload contract carried across a port.

type JetStreamPort

type JetStreamPort struct {
	// Stream configuration (for outputs)
	StreamName      string   `json:"stream_name"`              // e.g., "ENTITY_EVENTS"
	Subjects        []string `json:"subjects"`                 // e.g., ["events.graph.entity.>"]
	Storage         string   `json:"storage,omitempty"`        // "file" or "memory" when declared
	RetentionPolicy string   `json:"retention,omitempty"`      // "limits", "interest", or "work_queue" when declared
	RetentionDays   int      `json:"retention_days,omitempty"` // Declared message retention in days
	MaxSizeGB       int      `json:"max_size_gb,omitempty"`    // Declared maximum stream size in GiB
	Replicas        int      `json:"replicas,omitempty"`       // Declared replica count

	// Consumer configuration (for inputs)
	ConsumerName  string `json:"consumer_name,omitempty"`  // Durable consumer name
	DeliverPolicy string `json:"deliver_policy,omitempty"` // Declared delivery policy
	AckPolicy     string `json:"ack_policy,omitempty"`     // Declared acknowledgement policy
	MaxDeliver    int    `json:"max_deliver,omitempty"`    // Declared maximum redelivery attempts
	// AckWait is the duration the JetStream server waits for an ack before
	// redelivering. Strings are parsed via time.ParseDuration ("90s",
	// "2m", "5m"). Empty falls through to a per-component default. The
	// component-level default is a starting point; this port-level field
	// lets operators tune ack_wait for long-running consumers (LLM model
	// calls, slow tool execution) without forking the component. Per
	// docs/operations/14-timeout-chain.md: ack_wait must comfortably
	// exceed the longest legitimate per-task wallclock budget so that
	// healthy long-tail work isn't reaped before it can ack.
	AckWait string `json:"ack_wait,omitempty"`
	// HeartbeatInterval is the cadence at which the consumer goroutine
	// fires msg.InProgress() to reset the ack clock. Strings are parsed
	// via time.ParseDuration ("60s", "90s"). Empty falls through to a
	// per-component default. Typed delivery owners require it to be at most
	// half the shortest positive BackOff interval, or half the effective AckWait
	// (an explicit positive value or the 30s server default) when BackOff is
	// empty, so one missed heartbeat does not trigger redelivery. Honored by
	// heartbeat-enabled typed consumers and by the explicitly held legacy
	// AgentRun binding; pure-ack consumers ignore it. New integrations use
	// natsclient.ConsumeDeliveryWithHeartbeat.
	HeartbeatInterval string `json:"heartbeat_interval,omitempty"`
	// MaxAckPending caps the number of delivered-but-unacked messages the
	// server keeps in flight for this consumer — the consumer-side backpressure
	// lever. Empty/0 leaves policy to NATS, which may inherit a stream limit,
	// apply its default, or cap it under server/account policy; -1 is unlimited
	// outstanding acknowledgements. gh#480: there was previously no
	// config path to this at all, so operators could not tune ingest backpressure.
	MaxAckPending int `json:"max_ack_pending,omitempty"`

	// Import declares this INPUT port an import lane: the operator states that
	// entities arriving here were minted by a PEER deployment, so graph-ingest
	// accepts a foreign org.platform on it and refuses a subject claiming this
	// deployment's own pair (ADR-102 d5). Absent or false is the ordinary lane,
	// where the deployment's own authority is required — the fail-closed
	// default, so an operator who declares nothing imports nothing. It is a
	// statement of trust, not a value the operator computes: the framework
	// already holds the local pair and compares against it. Nothing on the wire
	// is authenticated; the recorded provenance is this declaration plus the
	// envelope `source` string. Meaningless on an output port and ignored
	// there.
	Import bool `json:"import,omitempty"`

	// Interface contract
	Interface *InterfaceContract `json:"interface,omitempty"`
}

JetStreamPort - NATS JetStream for durable, at-least-once messaging

func (JetStreamPort) IsExclusive

func (j JetStreamPort) IsExclusive() bool

IsExclusive returns false as JetStream manages consumer coordination

func (JetStreamPort) Kind

func (j JetStreamPort) Kind() PortKind

Kind returns the canonical port kind.

func (JetStreamPort) ResourceID

func (j JetStreamPort) ResourceID() string

ResourceID returns unique identifier for JetStream ports

type KVReadPort

type KVReadPort struct {
	Bucket    string             `json:"bucket"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

KVReadPort declares exact or list access to current values in one KV bucket. It is metadata only: acquisition and missing-value policy remain component-owned.

func (KVReadPort) IsExclusive

func (k KVReadPort) IsExclusive() bool

IsExclusive reports that concurrent readers may share a bucket.

func (KVReadPort) Kind

func (k KVReadPort) Kind() PortKind

Kind returns the canonical port kind.

func (KVReadPort) ResourceID

func (k KVReadPort) ResourceID() string

ResourceID returns the canonical KV read resource identity.

type KVWatchPort

type KVWatchPort struct {
	Bucket    string             `json:"bucket"`            // e.g., "ENTITY_STATES"
	Keys      []string           `json:"keys,omitempty"`    // Keys to watch, empty = all
	History   bool               `json:"history,omitempty"` // Include historical values
	Interface *InterfaceContract `json:"interface,omitempty"`
}

KVWatchPort - NATS KV Watch for state observation

func (KVWatchPort) IsExclusive

func (k KVWatchPort) IsExclusive() bool

IsExclusive returns false as multiple watchers are allowed

func (KVWatchPort) Kind

func (k KVWatchPort) Kind() PortKind

Kind returns the canonical port kind.

func (KVWatchPort) ResourceID

func (k KVWatchPort) ResourceID() string

ResourceID returns unique identifier for KV watch ports

type KVWritePort

type KVWritePort struct {
	Bucket    string             `json:"bucket"`              // e.g., "ENTITY_STATES"
	Interface *InterfaceContract `json:"interface,omitempty"` // Data type contract
}

KVWritePort - NATS KV Write for state persistence

func (KVWritePort) IsExclusive

func (k KVWritePort) IsExclusive() bool

IsExclusive returns false as multiple writers are allowed (with CAS handling)

func (KVWritePort) Kind

func (k KVWritePort) Kind() PortKind

Kind returns the canonical port kind.

func (KVWritePort) ResourceID

func (k KVWritePort) ResourceID() string

ResourceID returns unique identifier for KV write ports

type LifecycleComponent

type LifecycleComponent interface {
	Discoverable
	Initialize() error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

LifecycleComponent defines the portable lifecycle contract for components. Initialize performs setup without runtime authority. Start accepts the context that owns continuing work. Stop uses its exact caller context to bound the component's terminal admission fence, cancellation, join, and cleanup; the resource owner determines that sequence's protocol-specific ordering. Exact resource ordering preserves admitted callback authority where native drain requires it; no universal cancel-before-drain order is implied.

During controlled shutdown, callers keep the accepted Start context live until a separately bounded Stop drains, joins, and finalizes the owner and returns nil. Ending the Start context first is abort cancellation. Stop then makes bounded best-effort progress under its exact caller authority and may return accurate native cleanup or deadline errors. Abort cleanup does not invent replacement authority, detach cleanup, or promise a second rejoin; if the bound wins, the portable contract makes no complete-join or leak-freedom claim.

Nil Start and Stop contexts are rejected before action. A completed repeated Stop is a no-op. Concurrent lifecycle calls, result replay, later rejoin after a Stop bound wins, reinitialization, and same-instance restart are not portable guarantees.

func AsLifecycleComponent

func AsLifecycleComponent(comp Discoverable) (LifecycleComponent, bool)

AsLifecycleComponent safely casts a component to LifecycleComponent

type ManagedComponent

type ManagedComponent struct {
	// Component is the actual component instance
	Component Discoverable

	// State tracks the current lifecycle state
	State State

	// Config is the effective component configuration this instance was
	// created from. The ComponentManager retains it so a per-component runtime
	// config update can restart the component only when the effective config
	// actually changed — a no-op update is skipped instead of stop/start-cycling
	// a healthy running component (gh#520).
	Config types.ComponentConfig

	// StartOrder tracks the order components were started for reverse shutdown
	StartOrder int

	// LastError tracks the last error that occurred during lifecycle operations
	LastError error
}

ManagedComponent tracks a component and its lifecycle state This is used by ComponentManager to properly manage component lifecycle

type Metadata

type Metadata struct {
	Name        string `json:"name"`
	Type        string `json:"type"` // "input", "processor", "output", "storage"
	Description string `json:"description"`
	Version     string `json:"version"`
}

Metadata describes what a component is

type NATSPort

type NATSPort struct {
	Subject   string             `json:"subject"`
	Queue     string             `json:"queue,omitempty"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

NATSPort - NATS pub/sub

func (NATSPort) IsExclusive

func (n NATSPort) IsExclusive() bool

IsExclusive returns false as multiple components can subscribe

func (NATSPort) Kind

func (n NATSPort) Kind() PortKind

Kind returns the canonical port kind.

func (NATSPort) ResourceID

func (n NATSPort) ResourceID() string

ResourceID returns unique identifier for NATS ports

type NATSRequestPort

type NATSRequestPort struct {
	Subject   string             `json:"subject"`
	Timeout   string             `json:"timeout,omitempty"` // Duration string e.g. "1s", "500ms"
	Retries   int                `json:"retries,omitempty"`
	Interface *InterfaceContract `json:"interface,omitempty"`
}

NATSRequestPort - NATS Request/Response pattern for synchronous operations

func (NATSRequestPort) IsExclusive

func (n NATSRequestPort) IsExclusive() bool

IsExclusive returns false as multiple components can handle requests

func (NATSRequestPort) Kind

func (n NATSRequestPort) Kind() PortKind

Kind returns the canonical port kind.

func (NATSRequestPort) ResourceID

func (n NATSRequestPort) ResourceID() string

ResourceID returns unique identifier for NATS request ports

type NetworkFacts

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

NetworkFacts is the immutable listener binding portion of PortFacts.

func (NetworkFacts) Host

func (f NetworkFacts) Host() string

Host returns the configured bind host.

func (NetworkFacts) Port

func (f NetworkFacts) Port() int

Port returns the configured bind port.

func (NetworkFacts) Protocol

func (f NetworkFacts) Protocol() string

Protocol returns the network protocol.

type NetworkPort

type NetworkPort struct {
	Protocol string `json:"protocol"` // "tcp", "udp"
	Host     string `json:"host"`     // "0.0.0.0", "localhost"
	Port     int    `json:"port"`     // 14550, 8080
}

NetworkPort - TCP/UDP network bindings

func (NetworkPort) IsExclusive

func (n NetworkPort) IsExclusive() bool

IsExclusive returns true as network ports are exclusive

func (NetworkPort) Kind

func (n NetworkPort) Kind() PortKind

Kind returns the canonical port kind.

func (NetworkPort) ResourceID

func (n NetworkPort) ResourceID() string

ResourceID returns unique identifier for network ports

type PlatformMeta

type PlatformMeta = types.PlatformMeta

PlatformMeta provides platform identity to components. Type alias to avoid import cycles while maintaining compatibility.

type Port

type Port struct {
	Name        string    `json:"name"`
	Direction   Direction `json:"direction"`
	Required    bool      `json:"required,omitempty"`
	Description string    `json:"description,omitempty"`
	External    bool      `json:"external,omitempty"` // fed from outside the composition; see PortDefinition.External
	Config      Portable  `json:"config"`
}

Port is a resolved component I/O declaration.

func (Port) Facts

func (p Port) Facts() (PortFacts, error)

Facts revalidates the current Port value and returns its immutable semantic projection.

func (Port) MarshalJSON

func (p Port) MarshalJSON() ([]byte, error)

MarshalJSON encodes Port with the same config.kind envelope as PortDefinition.

func (*Port) UnmarshalJSON

func (p *Port) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and resolves a runtime port.

type PortConfig

type PortConfig struct {
	Inputs  []PortDefinition `json:"inputs,omitempty"`
	Outputs []PortDefinition `json:"outputs,omitempty"`
}

PortConfig groups semantic declarations by data-flow direction.

func PortConfigFrom

func PortConfigFrom(inputs, outputs []Port) PortConfig

PortConfigFrom returns the configuration-shaped declaration of already resolved ports: the inverse of resolving a PortConfig lane by lane. Factories whose constructor resolves ports use it to expose the same ports as their PortDeclarer without a second derivation.

func (*PortConfig) UnmarshalJSON

func (p *PortConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects unknown top-level lanes such as the retired kv_write lane.

type PortDeclarer

type PortDeclarer func(rawConfig json.RawMessage, instanceName string) (PortConfig, error)

PortDeclarer declares a factory's ports as a pure function of the raw component configuration and the instance name. It takes no dependencies, performs no I/O, and constructs nothing: it is the static fact a registration carries beside Schema, evaluated offline by composition validation and verified against the constructed component at boot admission. The constructor MUST derive its ports from the same function so the two cannot drift.

type PortDefinition

type PortDefinition struct {
	Name        string `json:"name" schema:"readonly,type:string,description:Port identifier"`
	Required    bool   `json:"required,omitempty" schema:"readonly,type:bool,description:Whether port connection is required"`
	Description string `json:"description,omitempty" schema:"readonly,type:string,description:Human-readable port description"`
	// External declares that this input is fed from outside the composition
	// — a UI, a peer process, a rule action — so no publisher in the
	// composition's graph is expected. It is an operator statement, not a
	// predicted framework value: composition validation suppresses only the
	// no-publisher orphan finding for this port and nothing else (ADR-100
	// owner ruling on user.message, 2026-08-26). Meaningful on inputs.
	External bool     `` /* 142-byte string literal not displayed */
	Config   Portable `json:"config" schema:"editable,type:object,description:Typed semantic port configuration"`
}

PortDefinition is a configuration-shaped semantic port declaration.

func (PortDefinition) MarshalJSON

func (p PortDefinition) MarshalJSON() ([]byte, error)

MarshalJSON writes the canonical common port envelope.

func (PortDefinition) Resolve

func (d PortDefinition) Resolve(direction Direction) (Port, error)

Resolve validates and resolves a configuration declaration for one direction.

func (*PortDefinition) UnmarshalJSON

func (p *PortDefinition) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes the canonical common port envelope.

type PortFacts

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

PortFacts is an immutable semantic projection of one resolved Port.

func (PortFacts) ConnectionIDs

func (f PortFacts) ConnectionIDs() []string

ConnectionIDs returns defensive copies of the identifiers used for flow matching.

func (PortFacts) InteractionPattern

func (f PortFacts) InteractionPattern() InteractionPattern

InteractionPattern returns the canonical communication behavior.

func (PortFacts) Interface

func (f PortFacts) Interface() (InterfaceContract, bool)

Interface returns a defensive copy of the semantic interface contract.

func (PortFacts) IsExclusive

func (f PortFacts) IsExclusive() bool

IsExclusive reports whether two ports may claim the same resource.

func (PortFacts) Kind

func (f PortFacts) Kind() PortKind

Kind returns the canonical port kind.

func (PortFacts) NATSSubjects

func (f PortFacts) NATSSubjects() []string

NATSSubjects returns defensive copies of declared NATS subject families.

func (PortFacts) Network

func (f PortFacts) Network() (NetworkFacts, bool)

Network returns the immutable network binding when the port declares one.

func (PortFacts) ResourceID

func (f PortFacts) ResourceID() string

ResourceID returns the canonical resource identity.

func (PortFacts) StoreReadBucket

func (f PortFacts) StoreReadBucket() (string, bool)

StoreReadBucket returns the configured content-store bucket for a store-read port.

func (PortFacts) Stream

func (f PortFacts) Stream() (StreamFacts, bool)

Stream returns the immutable JetStream projection when the port declares one.

type PortFieldInfo

type PortFieldInfo struct {
	Type                 string                   `json:"type"`
	Editable             bool                     `json:"editable"`
	Minimum              *int                     `json:"minimum,omitempty"`
	Enum                 []string                 `json:"enum,omitempty"`
	Required             []string                 `json:"required,omitempty"`
	AnyRequired          [][]string               `json:"anyRequired,omitempty"`
	RequiredByDirection  map[Direction][]string   `json:"requiredByDirection,omitempty"`
	Directions           []Direction              `json:"directions,omitempty"`
	Properties           map[string]PortFieldInfo `json:"properties,omitempty"`
	Variants             map[string]PortFieldInfo `json:"variants,omitempty"`
	Items                *PortFieldInfo           `json:"items,omitempty"`
	AdditionalProperties *bool                    `json:"additionalProperties,omitempty"`
	// contains filtered or unexported fields
}

PortFieldInfo describes metadata for PortDefinition fields

type PortKind

type PortKind string

PortKind is the closed vocabulary of semantic component port kinds.

const (
	PortKindTimer        PortKind = "timer"
	PortKindNetwork      PortKind = "network"
	PortKindFile         PortKind = "file"
	PortKindHTTPClient   PortKind = "http-client"
	PortKindNATS         PortKind = "nats"
	PortKindNATSRequest  PortKind = "nats-request"
	PortKindJetStream    PortKind = "jetstream"
	PortKindKVWatch      PortKind = "kv-watch"
	PortKindKVRead       PortKind = "kv-read"
	PortKindKVWrite      PortKind = "kv-write"
	PortKindStoreRead    PortKind = "store-read"
	PortKindStoreProvide PortKind = "store-provide"
)

Canonical port kinds. Alternate spellings and custom kinds are not accepted.

type Portable

type Portable interface {
	ResourceID() string
	IsExclusive() bool
	Kind() PortKind
}

Portable is the common semantic contract implemented by every port config.

type PropertySchema

type PropertySchema struct {
	Type        string                    `json:"type"` // "string", "int", "bool", "float", "enum", "array", "object", "ports", "cache"
	Description string                    `json:"description"`
	Default     any                       `json:"default,omitempty"`
	Enum        []string                  `json:"enum,omitempty"`        // Valid string values
	Minimum     *int                      `json:"minimum,omitempty"`     // For numeric types
	Maximum     *int                      `json:"maximum,omitempty"`     // For numeric types
	MinLength   *int                      `json:"minLength,omitempty"`   // Minimum string length
	MaxLength   *int                      `json:"maxLength,omitempty"`   // Maximum string length
	Pattern     string                    `json:"pattern,omitempty"`     // Regular expression for string values
	Category    string                    `json:"category,omitempty"`    // "basic" or "advanced" for UI organization
	PortFields  map[string]PortFieldInfo  `json:"portFields,omitempty"`  // Metadata for port fields (when type is "ports")
	CacheFields map[string]CacheFieldInfo `json:"cacheFields,omitempty"` // Metadata for cache fields (when type is "cache")
	Properties  map[string]PropertySchema `json:"properties,omitempty"`  // Nested properties for object types
	// AdditionalProperties controls whether object fields outside Properties
	// are accepted. nil preserves JSON Schema's permissive default.
	AdditionalProperties *bool           `json:"additionalProperties,omitempty"`
	Required             []string        `json:"required,omitempty"` // Required nested fields for object types
	Items                *PropertySchema `json:"items,omitempty"`    // Item schema for array types
}

PropertySchema describes a single configuration property

type Registration

type Registration struct {
	Name         string       `json:"name"`         // Factory name (e.g., "udp-input")
	Type         string       `json:"type"`         // Component type (input/processor/output/storage)
	Protocol     string       `json:"protocol"`     // Technical protocol (udp, mavlink, websocket, etc.)
	Domain       string       `json:"domain"`       // Business domain (robotics, semantic, network, storage)
	Description  string       `json:"description"`  // Human-readable description
	Version      string       `json:"version"`      // Component version
	Schema       ConfigSchema `json:"schema"`       // Schema as static metadata (Feature 011)
	Factory      Factory      `json:"-"`            // Factory function (not serializable)
	Ports        PortDeclarer `json:"-"`            // Static port declaration (not serializable)
	Dependencies []string     `json:"dependencies"` // Boot dependencies such as DepModelRegistry
}

Registration holds factory and metadata for a component type

type RegistrationConfig

type RegistrationConfig struct {
	Name         string       // Component name (e.g., "udp", "websocket", "graph-processor")
	Factory      Factory      // Factory function to create component instances
	Ports        PortDeclarer // Pure port declaration the constructor's ports must equal
	Schema       ConfigSchema // Configuration schema for validation and discovery
	Type         string       // Component type: "input", "processor", "output", "storage"
	Protocol     string       // Technical protocol (udp, tcp, websocket, file, etc.)
	Domain       string       // Business domain (network, storage, processing, robotics, semantic)
	Description  string       // Human-readable description of the component
	Version      string       // Component version (semver recommended)
	Dependencies []string     // Runtime deps declared via constants like DepModelRegistry
}

RegistrationConfig provides a clean API for component registration. This config struct replaces the previous 7-8 parameter function signatures. It maps 1:1 to Registration struct fields for simplicity.

type Registry

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

Registry manages component factories and immutable admitted declarations. Runtime component handles remain private to ComponentManager.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new empty component registry

func (*Registry) CreateComponent

func (r *Registry) CreateComponent(
	instanceName string,
	config types.ComponentConfig,
	deps Dependencies,
	prepare func(Discoverable) error,
) (Discoverable, error)

CreateComponent is the boot-admission seam. It exists for the component manager (service.ComponentManager): a consumer creates and composes components through that manager, and a direct call bypasses the manager's bookkeeping. prepare must finish all fallible owner-local setup before the Registry publishes the immutable declaration.

func (*Registry) Declare

func (r *Registry) Declare(instanceName string, config types.ComponentConfig) (Declaration, error)

Declare evaluates the named factory's port declarer for one configured instance and resolves the result through the canonical port resolver. It constructs nothing and needs no dependencies: this is the offline half of the declaration the Registry verifies at admission.

func (*Registry) ListFactories

func (r *Registry) ListFactories() map[string]*Registration

ListFactories returns all registered component factories This provides information about what types of components can be created.

func (*Registry) RegisterFactory

func (r *Registry) RegisterFactory(name string, registration *Registration) error

RegisterFactory registers a component factory with the given name Returns an error if a factory with the same name is already registered.

func (*Registry) RegisterWithConfig

func (r *Registry) RegisterWithConfig(config RegistrationConfig) error

RegisterWithConfig registers a component using a configuration struct. This is the recommended registration method that replaces the multi-parameter functions.

Example usage:

registry.RegisterWithConfig(component.RegistrationConfig{
    Name:        "udp",
    Factory:     CreateUDPInput,
    Schema:      udpSchema,
    Type:        "input",
    Protocol:    "udp",
    Domain:      "network",
    Description: "UDP input component for receiving network data",
    Version:     "1.0.0",
})

func (*Registry) SealComposition

func (r *Registry) SealComposition()

SealComposition closes boot admission for the current process. It exists for the component manager (service.ComponentManager), which seals the composition once boot admission is complete; a direct call bypasses the manager's bookkeeping.

func (*Registry) Snapshots

func (r *Registry) Snapshots() []declarationSnapshot

Snapshots returns a deterministic defensive copy of the complete admission set. It exists for the component manager (service.ComponentManager): a consumer reads admitted components through that manager, and a direct call bypasses the manager's bookkeeping.

type SchemaDirectives

type SchemaDirectives struct {
	// core (required)
	Type        string // REQUIRED - field type
	Description string // REQUIRED (warning if missing)

	// UI Organization
	Category string // "basic" or "advanced"
	ReadOnly bool   // For PortDefinition fields
	Editable bool   // For PortDefinition fields
	Hidden   bool   // Hide from UI

	// Constraints
	Default  any      // Type-specific default value (stored as string, converted during schema generation)
	Required bool     // Field must be provided
	Min      *int     // Numeric minimum
	Max      *int     // Numeric maximum
	Enum     []string // Valid enum values

	// Future extensions (stored but not used yet)
	Help        string
	Placeholder string
	Pattern     string
	Format      string
}

SchemaDirectives represents parsed schema tag directives

func ParseSchemaTag

func ParseSchemaTag(tag string) (SchemaDirectives, error)

ParseSchemaTag parses a schema struct tag into directives.

Tag Syntax:

  • Directives are comma-separated
  • Key-value pairs use colon: "key:value"
  • Boolean flags have no colon: "readonly", "required"
  • Enum values are pipe-separated: "enum:val1|val2|val3"
  • Whitespace is trimmed from all values

Required Directives:

  • type: Field data type (string, int, bool, float, enum, array, object, ports)

Recommended Directives:

  • description: Human-readable field description (used for UI and documentation)

Optional Directives:

  • category: UI organization (basic, advanced)
  • default: Default value (converted to appropriate type)
  • min/max: Numeric constraints
  • enum: Valid values for enum types (pipe-separated)
  • readonly: Field is read-only (boolean flag)
  • editable: Field is user-editable (boolean flag)
  • hidden: Field is hidden from UI (boolean flag)
  • required: Field must be provided (boolean flag)

Example Tags:

schema:"type:string,description:Component name,category:basic"
schema:"type:int,description:Port,min:1,max:65535,default:8080"
schema:"type:enum,description:Level,enum:debug|info|warn,default:info"
schema:"required,type:string,description:API key"
schema:"readonly,type:string,description:System ID"

Returns an error if:

  • Tag is empty
  • Type directive is missing
  • Type value is invalid
  • Directive syntax is malformed
  • Numeric values cannot be parsed

See SCHEMA_TAG_SPEC.md for complete specification.

Example

ExampleParseSchemaTag demonstrates parsing individual schema tags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	// Parse a simple field tag
	tag := "type:int,description:Port number,min:1,max:65535,default:8080"
	directives, err := component.ParseSchemaTag(tag)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Description: %s\n", directives.Description)
	fmt.Printf("Min: %d\n", *directives.Min)
	fmt.Printf("Max: %d\n", *directives.Max)
	fmt.Printf("Default: %s\n", directives.Default)

}
Output:
Type: int
Description: Port number
Min: 1
Max: 65535
Default: 8080
Example (Enum)

ExampleParseSchemaTag_enum demonstrates parsing enum tags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	tag := "type:enum,description:Log level,enum:debug|info|warn|error,default:info"
	directives, _ := component.ParseSchemaTag(tag)

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Description: %s\n", directives.Description)
	fmt.Printf("Enum values: %v\n", directives.Enum)
	fmt.Printf("Default: %s\n", directives.Default)

}
Output:
Type: enum
Description: Log level
Enum values: [debug info warn error]
Default: info
Example (Flags)

ExampleParseSchemaTag_flags demonstrates boolean flags

package main

import (
	"fmt"

	"github.com/c360studio/semengine/component"
)

func main() {
	tag := "required,readonly,type:string,description:System identifier"
	directives, _ := component.ParseSchemaTag(tag)

	fmt.Printf("Type: %s\n", directives.Type)
	fmt.Printf("Required: %v\n", directives.Required)
	fmt.Printf("ReadOnly: %v\n", directives.ReadOnly)

}
Output:
Type: string
Required: true
ReadOnly: true

type SimpleMockComponent

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

SimpleMockComponent is a simple component implementation for testing

func (*SimpleMockComponent) ConfigSchema

func (m *SimpleMockComponent) ConfigSchema() ConfigSchema

ConfigSchema returns the component's configuration schema

func (*SimpleMockComponent) DataFlow

func (m *SimpleMockComponent) DataFlow() FlowMetrics

DataFlow returns the component's data flow metrics (zeros for mock)

func (*SimpleMockComponent) Health

func (m *SimpleMockComponent) Health() HealthStatus

Health returns the component's health status (always healthy for mock)

func (*SimpleMockComponent) InputPorts

func (m *SimpleMockComponent) InputPorts() []Port

InputPorts returns the component's input ports (none for mock)

func (*SimpleMockComponent) Meta

func (m *SimpleMockComponent) Meta() Metadata

Meta returns the component metadata

func (*SimpleMockComponent) OutputPorts

func (m *SimpleMockComponent) OutputPorts() []Port

OutputPorts returns the component's output ports (none for mock)

type State

type State int

State represents the current lifecycle state of a component

const (
	// StateCreated indicates component was created but not initialized
	StateCreated State = iota
	// StateInitialized indicates component was initialized but not started
	StateInitialized
	// StateStarted indicates component is running
	StateStarted
	// StateStopped indicates component was stopped
	StateStopped
	// StateFailed indicates component failed during lifecycle operation
	StateFailed
)

func (State) String

func (cs State) String() string

String returns a string representation of the component state

type StoreProvidePort

type StoreProvidePort struct {
	Instance string `json:"instance"` // StorageInstance name this component owns
}

StoreProvidePort declares that a storage component OWNS (provides) a store instance, addressable by its StorageInstance name (ADR-063). It is the flowgraph marker for store ownership and complements the StoreProvider interface the ComponentManager reads to populate the shared StoreRegistry.

Non-exclusive by design. Duplicate live Store ownership is owner-local runtime state and remains enforced by storeregistry.Register; it is not a declaration-derived exclusive-resource claim.

func (StoreProvidePort) IsExclusive

func (s StoreProvidePort) IsExclusive() bool

IsExclusive returns false — ownership conflicts are caught at registry-population time, not here (see the type doc).

func (StoreProvidePort) Kind

func (s StoreProvidePort) Kind() PortKind

Kind returns the canonical port kind.

func (StoreProvidePort) ResourceID

func (s StoreProvidePort) ResourceID() string

ResourceID returns a unique identifier for store provide ports.

type StoreProvider

type StoreProvider interface {
	ProvidedStores() map[string]storage.StreamableStore
}

StoreProvider is implemented by storage components that own one or more stores addressable by StorageInstance name (ADR-063). For the boot-composed component set, ComponentManager reads this AFTER a component Starts to populate the shared StoreRegistry and clears those entries when the component Stops. A desired-state write does not swap a handle in the running process.

The map is keyed by the StorageInstance name each store STAMPS into refs (store.InstanceName()), so the registry key, the store-provide port token, and the ref's StorageInstance are the same value by construction. Returns nil/empty before Start (no store yet) or for a component that provides no store.

type StoreReadPort

type StoreReadPort struct {
	Bucket    string             `json:"bucket"`              // Storage bucket name (e.g., "MESSAGES")
	Interface *InterfaceContract `json:"interface,omitempty"` // Optional content type contract
}

StoreReadPort declares streaming read access to a content storage bucket. Components use this to read large content (documents, images, video) from storage backends (NATS ObjectStore, filesystem, etc.) without coupling to a specific backend implementation.

func (StoreReadPort) IsExclusive

func (s StoreReadPort) IsExclusive() bool

IsExclusive returns false as multiple readers are allowed

func (StoreReadPort) Kind

func (s StoreReadPort) Kind() PortKind

Kind returns the canonical port kind.

func (StoreReadPort) ResourceID

func (s StoreReadPort) ResourceID() string

ResourceID returns unique identifier for store read ports

type StreamFacts

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

StreamFacts is the immutable JetStream-specific portion of PortFacts.

func (StreamFacts) AckPolicy

func (f StreamFacts) AckPolicy() string

AckPolicy returns the declared consumer acknowledgement policy.

func (StreamFacts) AckWait

func (f StreamFacts) AckWait() string

AckWait returns the declared acknowledgement timeout.

func (StreamFacts) DeliverPolicy

func (f StreamFacts) DeliverPolicy() string

DeliverPolicy returns the declared consumer delivery policy.

func (StreamFacts) HeartbeatInterval

func (f StreamFacts) HeartbeatInterval() string

HeartbeatInterval returns the declared consumer heartbeat interval.

func (StreamFacts) Import

func (f StreamFacts) Import() bool

Import reports whether the operator declared this port an import lane — the one place a foreign org.platform is admitted (ADR-102 d5). False is the fail-closed default for every port that does not say otherwise.

func (StreamFacts) MaxAckPending

func (f StreamFacts) MaxAckPending() int

MaxAckPending returns the declared unacknowledged-message ceiling.

func (StreamFacts) MaxDeliver

func (f StreamFacts) MaxDeliver() int

MaxDeliver returns the declared maximum delivery attempts.

func (StreamFacts) MaxSizeGB

func (f StreamFacts) MaxSizeGB() int

MaxSizeGB returns the declared stream size limit in GiB.

func (StreamFacts) Name

func (f StreamFacts) Name() string

Name returns the declared stream name.

func (StreamFacts) Replicas

func (f StreamFacts) Replicas() int

Replicas returns the declared stream replica count.

func (StreamFacts) RetentionDays

func (f StreamFacts) RetentionDays() int

RetentionDays returns the declared stream retention duration in days.

func (StreamFacts) RetentionPolicy

func (f StreamFacts) RetentionPolicy() string

RetentionPolicy returns the declared JetStream retention policy.

func (StreamFacts) Storage

func (f StreamFacts) Storage() string

Storage returns the declared JetStream storage mode.

func (StreamFacts) Subjects

func (f StreamFacts) Subjects() []string

Subjects returns a defensive copy of the declared subjects.

type TimerPort

type TimerPort struct {
	Interval  string             `json:"interval"` // Duration string e.g. "30s", "1m"
	Interface *InterfaceContract `json:"interface,omitempty"`
}

TimerPort represents a periodic timer trigger port

func (TimerPort) IsExclusive

func (t TimerPort) IsExclusive() bool

IsExclusive returns false as multiple timers can run independently

func (TimerPort) Kind

func (t TimerPort) Kind() PortKind

Kind returns the canonical port kind.

func (TimerPort) ResourceID

func (t TimerPort) ResourceID() string

ResourceID returns unique identifier for timer ports

type Validatable

type Validatable interface {
	Validate() error
}

Validatable interface for configs that can self-validate

type ValidationError

type ValidationError struct {
	Field   string `json:"field"`   // Name of the field that failed validation
	Message string `json:"message"` // Human-readable error message
	Code    string `json:"code"`    // Machine-readable error code (see above)
}

ValidationError represents a validation error for a specific configuration field. It provides structured error information that can be displayed to users and mapped to specific form fields in the UI.

Error codes are standardized across frontend and backend:

  • "required": Field is required but missing
  • "min": Numeric value below minimum threshold
  • "max": Numeric value above maximum threshold
  • "enum": Value not in allowed enum values
  • "type": Value doesn't match expected type (string, int, bool, etc.)
  • "pattern": String doesn't match required pattern (future use)

func ValidateConfig

func ValidateConfig(config map[string]any, schema ConfigSchema) []ValidationError

ValidateConfig validates a configuration map against a ConfigSchema. It checks required fields, type constraints, min/max bounds, and enum values.

The validation is lenient - unknown fields are allowed to support backward compatibility and future schema evolution. Only explicitly defined properties are validated against their schema constraints.

Returns a slice of ValidationError containing all validation failures found. An empty slice indicates the configuration is valid.

Example usage:

schema := component.ConfigSchema{
    Properties: map[string]component.PropertySchema{
        "port": {
            Type:     "int",
            Minimum:  ptrInt(1),
            Maximum:  ptrInt(65535),
            Category: "basic",
        },
    },
    Required: []string{"port"},
}

config := map[string]any{"port": 99999}
errors := component.ValidateConfig(config, schema)
if len(errors) > 0 {
    // Handle validation errors
    fmt.Printf("Validation failed: %s\n", errors[0].Message)
}

Jump to

Keyboard shortcuts

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