Documentation
¶
Overview ¶
Package graphingest provides the graph-ingest component for entity and triple ingestion.
Package graphingest provides graph-ingest, the component that writes entities and their triples into the ENTITY_STATES KV bucket, which it owns: it consumes entity messages from JetStream, serves the graph-mutation operations over NATS request/reply, and answers the entity reads declared for it in graph.QueryVerbs. The package README.md describes its ports, configuration, metrics and health.
Package graphingest query handlers
Index ¶
- func CreateGraphIngest(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)
- func DeclarePorts(rawConfig json.RawMessage, _ string) (component.PortConfig, error)
- func Register(registry *component.Registry) error
- type Component
- func (c *Component) CreateEntity(ctx context.Context, entity *graph.EntityState) error
- func (c *Component) DataFlow() component.FlowMetrics
- func (c *Component) DebugStatus() any
- func (c *Component) Health() component.HealthStatus
- func (c *Component) Initialize() error
- func (c *Component) InputPorts() []component.Port
- func (c *Component) OutputPorts() []component.Port
- func (c *Component) Start(ctx context.Context) error
- func (c *Component) Stop(ctx context.Context) error
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateGraphIngest ¶
func CreateGraphIngest(rawConfig json.RawMessage, deps component.Dependencies) (component.Discoverable, error)
CreateGraphIngest is the factory function for creating graph-ingest components
func DeclarePorts ¶
func DeclarePorts(rawConfig json.RawMessage, _ string) (component.PortConfig, error)
DeclarePorts is the component.PortDeclarer for graph-ingest: the ports CreateGraphIngest will report for rawConfig, computed without dependencies.
Types ¶
type Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component implements the graph-ingest processor
func (*Component) CreateEntity ¶
CreateEntity atomically creates a new entity. Existing keys are never overwritten; callers observe natsclient.ErrKVKeyExists and decide whether that conflict is acceptable for their operation. A nil context is refused as invalid before anything is read or written.
func (*Component) DataFlow ¶
func (c *Component) DataFlow() component.FlowMetrics
DataFlow reports input messages: each delivery on a stream input, redeliveries included, and each mutation request. Queries, in-process creates and the containers hierarchy inference creates are not input messages. ErrorRate is the processing errors counted (Health's ErrorCount) per input message.
func (*Component) DebugStatus ¶
DebugStatus implements component.DebugStatusProvider: the FULL poison inventory, sorted by entity ID, so a mass-poison event is enumerable in-band (the Health message and gauge are bounded; this is not).
func (*Component) Health ¶
func (c *Component) Health() component.HealthStatus
Health reports the shell's verdict (component.Lifecycle.Health) over graph-ingest's stuck states, not a count of past errors (ADR-109 Decision 2): a poisoned entity, a backlog the latest status tick could not read, or a lost input binding, which only a process restart clears (observeLostBinding). ErrorCount is reported and never lowers Healthy. A non-empty poison inventory degrades Health per-entity: status is "degraded", NOT "reset_required" (that stays a per-read error code), and the message carries count + a bounded ID/reason sample. Full enumeration rides DebugStatus.
func (*Component) Initialize ¶
Initialize marks the component initialized (no I/O). The factory validated the configuration.
func (*Component) InputPorts ¶
InputPorts returns input port definitions. Reads directly from config so ports are available before Initialize().
func (*Component) OutputPorts ¶
OutputPorts returns output port definitions. Reads directly from config so ports are available before Initialize().
func (*Component) Start ¶
Start begins processing (must be initialized first). The lifecycle state is the shell's (component.Lifecycle, over internal/lifecycleguard): a nil or ended context and a second Start are refused before anything is acquired; a Start that fails is rolled back through release, and a rollback that fails leaves release pending for the next Stop. A component with no NATS client, or an uninitialized one, is refused before the guard is consulted, so a later Start after Initialize is still admitted.
ctx bounds Start only. Everything Start does before it returns runs under ctx: connecting to NATS (or waiting while the client reconnects), bucket setup, the ENTITY_STATES sweep and consumer setup. A ctx that ends first fails Start. Subscriptions, the ingest pool, the entity cache's expiry sweep and the status loop run under a run context start creates and release ends, so ending ctx after Start returned stops nothing (ADR-113). Request handlers run under a context natsclient owns; release drains their subscriptions, which waits for running handlers.
func (*Component) Stop ¶
Stop gracefully shuts down the component through the shell, which runs release, the cleanup Start gave it: Stop before Start releases nothing; Stop during Start waits for it, or returns ctx's error first; a Stop whose release fails keeps it pending, and the next Stop runs it again; after a release that succeeded, Stop returns nil and runs nothing. Stop logs nothing itself: release logs "component stopped gracefully" when it succeeds.
type Config ¶
type Config struct {
Ports *component.PortConfig `json:"ports" schema:"type:ports,description:Port configuration,category:basic"`
EnableHierarchy bool `json:"enable_hierarchy" schema:"type:bool,description:Enable hierarchy inference,default:false,category:advanced"`
// IngestLanes is the number of keyed-concurrent ingest lanes (SemStreams ADR-072).
// Messages are partitioned by entity ID (same entity → one lane →
// serial in arrival order, preserving the arrival-order merge; different
// entities → parallel), so ingest is not bound to a single serial
// Get+CAS round-trip chain. Default 8 (concurrent); `1` selects fully
// serial ingest.
IngestLanes int `` /* 166-byte string literal not displayed */
}
Config holds configuration for graph-ingest component
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a valid default configuration
func (*Config) ApplyDefaults ¶
func (c *Config) ApplyDefaults()
ApplyDefaults sets default values for configuration. Validate only checks.