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, one Registry.Register call per factory. The Registration is the one home of a factory's configuration schema, description and version. 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: Snapshots returns a copy of each admitted Declaration. Once boot admission is complete, Registry is sealed; later component admission attempts fail until another process boot creates a fresh Registry.
Discoverable components report their typed ports, health and flow metrics. Dependencies.Platform is the deployment's types.PlatformMeta. 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 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 ¶
ParseSchemaTag returns an error for an invalid tag. The schema generators panic on one, naming the struct type, the field and the tag: every schema is built once from constant struct tags, so a bad tag is a programming error, as a bad pattern is to regexp.MustCompile. Missing descriptions use field names as fallback.
See docs/architecture/SCHEMA_TAG_SPEC.md for complete specification.
Index ¶
- Constants
- func GenerateCacheFieldSchema() map[string]CacheFieldInfo
- func GeneratePortFieldSchema() map[string]PortFieldInfo
- func ResolveSubject(ports []PortDefinition, portName, suffix string) (string, error)
- func SafeUnmarshal(rawConfig json.RawMessage, target any) error
- func ValidateComponentName(name string) error
- func ValidateFactoryConfig(rawConfig json.RawMessage) error
- type CacheFieldInfo
- type ConfigSchema
- type ConfigValidator
- type ConsumerConfig
- type DebugStatusProvider
- type Declaration
- type Dependencies
- type Direction
- type Discoverable
- type Factory
- type FilePort
- type FlowMetrics
- type HTTPClientPort
- type HealthStatus
- type InteractionPattern
- type InterfaceContract
- type JetStreamPort
- type KVReadPort
- type KVWatchPort
- type KVWritePort
- type Lifecycle
- func (l *Lifecycle) CountError()
- func (l *Lifecycle) CountInput(bytes int)
- func (l *Lifecycle) DataFlow() FlowMetrics
- func (l *Lifecycle) Health(stuck ...string) HealthStatus
- func (l *Lifecycle) Initialize() error
- func (l *Lifecycle) Start(ctx context.Context, start, cleanup func(context.Context) error) error
- func (l *Lifecycle) Stop(ctx context.Context) error
- type LifecycleComponent
- type ManagedComponent
- type NATSPort
- type NATSRequestPort
- type NetworkFacts
- type NetworkPort
- type Port
- type PortConfig
- type PortDeclarer
- type PortDefinition
- type PortFacts
- func (f PortFacts) ConnectionIDs() []string
- func (f PortFacts) InteractionPattern() InteractionPattern
- func (f PortFacts) Interface() (InterfaceContract, bool)
- func (f PortFacts) IsExclusive() bool
- func (f PortFacts) Kind() PortKind
- func (f PortFacts) NATSSubjects() []string
- func (f PortFacts) Network() (NetworkFacts, bool)
- func (f PortFacts) ResourceID() string
- func (f PortFacts) StoreReadBucket() (string, bool)
- func (f PortFacts) Stream() (StreamFacts, bool)
- type PortFieldInfo
- type PortKind
- type Portable
- type PropertySchema
- type Registration
- type Registry
- func (r *Registry) CreateComponent(instanceName string, config types.ComponentConfig, deps Dependencies, ...) (Discoverable, error)
- func (r *Registry) Declare(instanceName string, config types.ComponentConfig) (Declaration, error)
- func (r *Registry) ListFactories() map[string]*Registration
- func (r *Registry) Register(registration Registration) error
- func (r *Registry) SealComposition()
- func (r *Registry) Snapshots() []Declaration
- type SchemaDirectives
- type State
- type StoreProvidePort
- type StoreProvider
- type StoreReadPort
- type StreamFacts
- func (f StreamFacts) AckPolicy() string
- func (f StreamFacts) AckWait() string
- func (f StreamFacts) DeliverPolicy() string
- func (f StreamFacts) HeartbeatInterval() string
- func (f StreamFacts) Import() bool
- func (f StreamFacts) MaxAckPending() int
- func (f StreamFacts) MaxDeliver() int
- func (f StreamFacts) MaxSizeGB() int
- func (f StreamFacts) Name() string
- func (f StreamFacts) Replicas() int
- func (f StreamFacts) RetentionDays() int
- func (f StreamFacts) RetentionPolicy() string
- func (f StreamFacts) Storage() string
- func (f StreamFacts) Subjects() []string
- type TimerPort
- type Validatable
Examples ¶
Constants ¶
const ( MaxStringLength = 1024 // Maximum length for string values MaxJSONSize = 1024 * 1024 // Maximum JSON size (1MB) )
Config validation constants - security limits
const ( // DepModelRegistry states that a component consumes // Dependencies.ModelRegistry at construction or run time, 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 state which boot dependencies they consume; nothing reads the declaration, and every component receives Dependencies.ModelRegistry, the registry selected at boot. 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 decodes a component configuration into target, a non-nil pointer. It checks, in order: the target (nil, a nil pointer or a non-pointer is refused), the configuration (ValidateFactoryConfig), then decodes strictly, refusing a key the target does not define and data after the first value. Empty input returns at once, leaving the target's defaults and without calling Validate. After nonempty input decodes, a target that implements Validatable is validated last. Every refusal but Validate's own error is of the invalid class.
func ValidateComponentName ¶
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
- An invalid schema tag panics, naming the struct type, the field and the tag
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
}
Output:
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
}
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
}
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. InputFacts[i] describes InputPorts[i] and OutputFacts[i] describes OutputPorts[i]: both lists of each pair come from one projection, so readers take them by index together.
func (Declaration) ConflictWith ¶
func (d Declaration) ConflictWith(held Declaration) error
ConflictWith returns nil when no exclusive claim of d clashes with an exclusive claim of held, under the rule admission applies. Otherwise it returns a plain error naming the first clash: held's claims are visited in turn and, for each, d's, each side inputs first, then outputs, in declaration order. CreateComponent refuses a candidate with this error, so an offline check that calls it reports what admission would.
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 types.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.
type Discoverable ¶
type Discoverable interface {
// InputPorts returns the ports this component accepts data on
InputPorts() []Port
// OutputPorts returns the ports this component produces data on
OutputPorts() []Port
// 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 ¶
FilePort - File system access
func (FilePort) IsExclusive ¶
IsExclusive returns false as multiple components can read files
func (FilePort) ResourceID ¶
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"`
Messages int64 `json:"messages"` // input messages counted since construction
Bytes int64 `json:"bytes"` // their payload bytes
}
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; 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. It is the operator's way to 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 decision 5). 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) 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 Lifecycle ¶
type Lifecycle struct {
// contains filtered or unexported fields
}
Lifecycle is the processor shell of ADR-108: the part of a component that is the same for every component, which is starting once, stopping, rolling back a failed start, and answering Health and DataFlow. A LifecycleComponent holds a Lifecycle as an unexported field and answers the lifecycle half of that interface with one-line calls to it.
The component supplies what only it knows: a start function that acquires its resources and creates the run context for its continuing work, a cleanup function that releases them in its own order and ends that run context (ADR-113), and its current stuck states at each Health call. The shell holds no context and no cancel and creates neither, decides no release order, reports no readiness and registers no metrics: its counters are plain integers.
The zero value is a shell that has not been initialized. A Lifecycle must not be copied after first use.
Example ¶
package main
import (
"context"
"fmt"
"sync"
"sync/atomic"
"time"
"github.com/c360studio/semengine/component"
)
// sensor is a component as an outside author writes one: it holds a component.Lifecycle and
// gives it the two functions only the sensor knows, start and cleanup, and its stuck state at
// each Health read.
type sensor struct {
lifecycle component.Lifecycle
// calibrationLost is the sensor's one stuck state.
calibrationLost atomic.Bool
mu sync.Mutex
cancel context.CancelFunc
done chan struct{}
}
var _ component.LifecycleComponent = (*sensor)(nil)
func (s *sensor) Initialize() error { return s.lifecycle.Initialize() }
func (s *sensor) Start(ctx context.Context) error { return s.lifecycle.Start(ctx, s.start, s.cleanup) }
func (s *sensor) Stop(ctx context.Context) error { return s.lifecycle.Stop(ctx) }
func (s *sensor) Health() component.HealthStatus { return s.lifecycle.Health(s.stuck()) }
func (s *sensor) DataFlow() component.FlowMetrics { return s.lifecycle.DataFlow() }
func (s *sensor) InputPorts() []component.Port { return nil }
func (s *sensor) OutputPorts() []component.Port { return nil }
// start creates the run context for the sensor's continuing work (ADR-113): ending Start's
// context after Start returned stops nothing.
func (s *sensor) start(ctx context.Context) error {
runCtx, cancel := context.WithCancel(context.WithoutCancel(ctx))
done := make(chan struct{})
go func() {
defer close(done)
<-runCtx.Done() // the sensor's polling loop would run here
}()
s.mu.Lock()
s.cancel, s.done = cancel, done
s.mu.Unlock()
return nil
}
// cleanup ends the run context and joins the worker within Stop's bound.
func (s *sensor) cleanup(ctx context.Context) error {
s.mu.Lock()
cancel, done := s.cancel, s.done
s.mu.Unlock()
if cancel == nil {
return nil
}
cancel()
select {
case <-done:
return nil
case <-ctx.Done():
return ctx.Err()
}
}
// receive is what the sensor's subscription calls for each reading.
func (s *sensor) receive(payload []byte) {
s.lifecycle.CountInput(len(payload))
}
func (s *sensor) stuck() string {
if s.calibrationLost.Load() {
return "calibration lost"
}
return ""
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
s := &sensor{}
if err := s.Initialize(); err != nil {
fmt.Println("initialize:", err)
return
}
if err := s.Start(ctx); err != nil {
fmt.Println("start:", err)
return
}
s.receive([]byte("21.5"))
s.receive([]byte("21.7"))
fmt.Println(s.Health().Status, s.DataFlow().Messages, s.DataFlow().Bytes)
s.calibrationLost.Store(true)
h := s.Health()
fmt.Println(h.Status, h.LastError)
if err := s.Stop(ctx); err != nil {
fmt.Println("stop:", err)
return
}
fmt.Println(s.Health().Status, s.DataFlow().Messages)
}
Output: running 2 8 degraded calibration lost stopped 2
func (*Lifecycle) CountError ¶
func (l *Lifecycle) CountError()
CountError counts one processing error, reported as Health's ErrorCount and in DataFlow's ErrorRate.
func (*Lifecycle) CountInput ¶
CountInput counts one input message of the given payload bytes and records its time as the last activity.
func (*Lifecycle) DataFlow ¶
func (l *Lifecycle) DataFlow() FlowMetrics
DataFlow reports the CountInput totals since construction, running or not, and LastActivity, the time of the last CountInput or the zero time before the first. While running it also reports the totals per second of uptime and, once an input was counted, the counted errors per input; otherwise those rates are zero. DataFlow may be called at any time and never waits for Start or Stop.
func (*Lifecycle) Health ¶
func (l *Lifecycle) Health(stuck ...string) HealthStatus
Health reports whether the shell is running and the stuck states the component passes in. Not running: Healthy false, Status "stopped", no LastError and zero Uptime, whatever stuck holds. Running with no stuck state: Healthy true and Status "running". Running with stuck states: Healthy false, Status "degraded" and LastError the states joined by "; ". An empty string is not a stuck state and is ignored. ErrorCount is the number of CountError calls and never lowers Healthy (ADR-109, Decision 2). Health may be called at any time and never waits for Start or Stop.
func (*Lifecycle) Initialize ¶
Initialize marks the shell initialized and returns nil, every time. It does no I/O; it returns an error only so a component's Initialize can be the one line that calls it.
func (*Lifecycle) Start ¶
Start refuses a shell that was never initialized, running nothing, so a Start after Initialize is still admitted. Otherwise it is lifecycleguard's Start: a nil or ended context and a second Start are refused; start runs under ctx; a start that fails or panics is rolled back through cleanup, and a rollback that fails stays pending for the next Stop. The shell is running from the moment start returns nil until cleanup begins.
cleanup runs after a partial start as well as a complete one, so it must tolerate handles that were never acquired. It must not panic: a cleanup that panics leaves the guard's state behind it, so a later Stop cannot try again. The shell inherits that limitation from internal/lifecycleguard.
func (*Lifecycle) Stop ¶
Stop is lifecycleguard's Stop: it runs the cleanup Start was given even when ctx has already ended (clearing running status before cleanup begins) so teardown always initiates and ctx bounds only waits. Stop before Start returns nil and uses up the shell, a Stop after a successful cleanup is a no-op, a synchronous nil cleanup under an ended ctx marks the shell terminal while returning ctx.Err(), and a cleanup that fails stays pending for the next Stop.
type LifecycleComponent ¶
type LifecycleComponent interface {
Discoverable
Initialize() error
Start(ctx context.Context) error
Stop(ctx context.Context) error
}
LifecycleComponent is a component its host initializes, starts and stops. A caller can rely on these outcomes (ADR-108, Decision 3):
- Start and Stop refuse a nil context, and Start refuses a context that has already ended.
- Stop before Start is safe.
- Start(ctx) does its startup work under ctx and returns once the component is ready; if ctx ends first, Start returns that error and holds nothing. Ending ctx after Start returned stops nothing: the component runs its continuing work under a context of its own, which Stop ends (ADR-113).
- Stop(ctx) is the only stop. It drains, joins and cleans up within ctx's bound and returns nil only once everything is released; if ctx ends first, it returns that context's error and a later Stop tries again.
- A repeated Stop is a no-op once an earlier Stop's cleanup succeeded; after a failed cleanup, what is left stays pending for a later Stop.
- A second Start is refused. An instance never restarts; a host that needs the component again creates a new one.
- A failed Start holds nothing, or, when its own cleanup also fails, it returns both errors and a later Stop releases what it left.
- Configuration is validated once, at construction, and Initialize is idempotent and does no I/O.
Concurrent lifecycle calls are not part of the contract. Reads are: Health, DataFlow and DebugStatus may be called at any time, during Start or Stop and after Stop, and return without waiting for either; after Stop they report what the component knows then. Callers do so without waiting for Stop: the component manager's health and status routes, its health publisher (which ends only after the components have stopped) and the service manager's /readyz. The rule is tested for graph-ingest (TestGraphIngestHealthAndDataFlowAnswerDuringAndAfterStop) and is review only for components outside this module.
component.Lifecycle implements these rules for a component that holds one: nil contexts refused, ended Start contexts refused, Stop before Start safe, Stop initiating cleanup even when its context has already ended, one Start and no restart, a repeated Stop a no-op, a failed Start rolled back and a failed cleanup kept for the next Stop, Start refused before Initialize, Initialize idempotent with no I/O, and Health and DataFlow answering at any time without waiting. The component keeps the rest: its start creates the run context for its continuing work and its cleanup ends it, drains and joins that work within Stop's context and tolerates a partial start; it validates its configuration at construction; and its DebugStatus, if it has one, must not wait for Start or Stop.
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 boot configuration this instance was created from. The
// component set and each component's configuration are fixed at
// construction, so it never changes for the life of the instance.
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 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 ¶
IsExclusive returns false as multiple components can subscribe
func (NATSPort) ResourceID ¶
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) Protocol ¶
func (f NetworkFacts) Protocol() string
Protocol returns the network protocol.
type NetworkPort ¶
type NetworkPort struct {
Protocol string `json:"protocol"` // "udp" in any letter case is UDP; any other label ("tcp", "http") is TCP
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 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 ¶
Facts revalidates the current Port value and returns its immutable semantic projection.
func (Port) MarshalJSON ¶
MarshalJSON encodes Port with the same config.kind envelope as PortDefinition.
func (*Port) UnmarshalJSON ¶
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).
// 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 ¶
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 ¶
IsExclusive reports whether two ports may claim the same resource.
func (PortFacts) NATSSubjects ¶
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 ¶
ResourceID returns the canonical resource identity.
func (PortFacts) StoreReadBucket ¶
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 PropertySchema ¶
type PropertySchema struct {
Type string `json:"type"` // "string", "int", "bool", "float", "enum", "array", "object", "ports", "cache"
Description string `json:"description"`
// Default is a JSON value: nil, a string, a bool, a number, a []string,
// or a []any or map[string]any whose elements are these, at any depth.
// The registry copies such a default when it stores or lists a schema. A
// default of any other type is stored as is, so a pointer, slice or map
// it holds stays shared with the caller.
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 types.ComponentType `json:"type"` // One of the five types.ComponentType constants
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 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 (*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) Register ¶
func (r *Registry) Register(registration Registration) error
Register registers a component factory under registration.Name. It refuses, with an error of the invalid class naming the factory, a name ValidateComponentName refuses, a nil Factory or Ports, a Type that is not one of the five types.ComponentType constants, and a name already registered. The registry keeps its own copy: a later change to the caller's value, its schema or its dependency list changes nothing registered. The one exception is a schema default that is not a JSON value (PropertySchema.Default): it is stored as is, so a pointer, slice or map it holds stays shared.
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() []Declaration
Snapshots returns the admitted declarations, sorted by instance name. Each is a copy that shares no slice with the registry. 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. The message logger (service.MessageLogger) is its second reader: with "*" it monitors the subjects the admitted declarations name.
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 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 )
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 decision 5). 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) 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 ¶
IsExclusive returns false as multiple timers can run independently
func (TimerPort) ResourceID ¶
ResourceID returns unique identifier for timer ports
type Validatable ¶
type Validatable interface {
Validate() error
}
Validatable interface for configs that can self-validate