Documentation
¶
Overview ¶
Package ports defines the driven ports (interfaces) for the Trellis engine.
These interfaces decouple the core logic from external implementations, allowing the engine to work with various storage backends, graph sources, and signal managers.
Key Interfaces ¶
- GraphLoader: Responsible for loading Node definitions (e.g., from Loam or Memory).
- StateStore: Responsible for persisting and loading session State.
- DistributedLocker: Provides distributed locking for handling concurrent session access.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunStateStoreContract ¶ added in v0.6.0
func RunStateStoreContract(t *testing.T, store StateStore)
RunStateStoreContract runs a suite of tests to verify that a StateStore implementation adheres to the defined interface contract.
Types ¶
type ActionDispatcher ¶
type ActionDispatcher interface {
Dispatch(req domain.ActionRequest) (domain.ActionResponse, error)
}
ActionDispatcher defines how side-effects are executed. The engine emits requests, and the host implements this interface to handle them.
type ContentConverter ¶ added in v0.7.17
type ContentConverter interface {
// Convert takes raw content and returns the transformed representation.
Convert(ctx context.Context, content string) (string, error)
}
ContentConverter defines a generic interface for transforming rendered content. The engine applies this as a post-processing step after interpolation, remaining agnostic of what the conversion does (e.g., Markdown to HTML, sanitization, i18n).
type DistributedLocker ¶ added in v0.7.0
type DistributedLocker interface {
// Lock attempts to acquire a distributed lock for the given key (e.g., session ID).
// It blocks until the lock is acquired, the context is canceled, or the TTL expires (implementation specific).
// Returns an UnlockFunc that MUST be called to release the lock.
Lock(ctx context.Context, key string, ttl time.Duration) (UnlockFunc, error)
}
DistributedLocker defines the interface for distributed concurrency control. It allows the Session Manager to coordinate access across multiple instances (replicas).
type GraphLoader ¶
type GraphLoader interface {
// GetNode retrieves the raw definition of a node by ID.
// It returns the raw bytes (which the compiler will parse) or an error.
GetNode(id string) ([]byte, error)
// ListNodes returns a simplified list of all node IDs available in the graph.
// This is used for introspection and visualization tools (e.g. 'trellis graph').
ListNodes() ([]string, error)
}
GraphLoader defines how the engine retrieves node definitions. This allows the storage layer (Loam, FS, Memory) to be decoupled.
type StateStore ¶ added in v0.6.0
type StateStore interface {
// Save persists the state for a given session ID.
Save(ctx context.Context, sessionID string, state *domain.State) error
// Load retrieves the state for a given session ID.
// Returns domain.ErrSessionNotFound if the session does not exist.
Load(ctx context.Context, sessionID string) (*domain.State, error)
// Delete removes the state for a given session ID.
Delete(ctx context.Context, sessionID string) error
// List returns all active session IDs.
List(ctx context.Context) ([]string, error)
}
StateStore defines the interface for persisting execution state. This allows for durable execution, enabling "Stop & Resume" workflows.
type StatelessEngine ¶ added in v0.7.10
type StatelessEngine interface {
// Render calculates the presentation (actions) for a given state without advancing it.
Render(ctx context.Context, state *domain.State) ([]domain.ActionRequest, bool, error)
Navigate(ctx context.Context, state *domain.State, input any) (*domain.State, error)
// Signal triggers a global event on the state machine, potentially causing a transition.
Signal(ctx context.Context, state *domain.State, signal string) (*domain.State, error)
// Inspect returns the current graph structure for introspection.
Inspect() ([]domain.Node, error)
}
StatelessEngine defines the interface for state machine cores that do not maintain internal state. This is the primary interface used by adapters (e.g., HTTP, MCP) that manage state externally or per-request.
type UnlockFunc ¶ added in v0.7.0
UnlockFunc is a function that releases a distributed lock.
type Watchable ¶ added in v0.3.2
type Watchable interface {
// Watch returns a channel that is signaled when the underlying graph changes.
// It returns a string (the event type, e.g. "reload") or an error.
Watch(ctx context.Context) (<-chan string, error)
}
Watchable defines an interface for loaders that can notify about backend changes. This is typically used for hot-reload or dev-mode functionality.
Source Files
Directories