interfaces

package
v0.3.52 Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package interfaces defines shared interface types used across the workflow engine, handlers, and module packages. Placing these interfaces here breaks the direct handler→module concrete-type dependency and enables each package to be tested in isolation with mocks.

Index

Constants

This section is empty.

Variables

View Source 
var SizingMap = map[Size]SizingDefaults{
	SizeXS: {CPU: "0.25", Memory: "512Mi", DBStorage: "10Gi", CacheMemory: "256Mi"},
	SizeS:  {CPU: "1", Memory: "2Gi", DBStorage: "50Gi", CacheMemory: "1Gi"},
	SizeM:  {CPU: "2", Memory: "4Gi", DBStorage: "100Gi", CacheMemory: "4Gi"},
	SizeL:  {CPU: "4", Memory: "16Gi", DBStorage: "500Gi", CacheMemory: "16Gi"},
	SizeXL: {CPU: "8", Memory: "32Gi", DBStorage: "1Ti", CacheMemory: "64Gi"},
}

SizingMap defines the default resource allocations per size tier.

Functions

This section is empty.

Types

type ActionError added in v0.3.52 

type ActionError struct {
	Resource string `json:"resource"`
	Action   string `json:"action"`
	Error    string `json:"error"`
}

ActionError captures a resource-level error during apply or destroy.

type ApplyResult added in v0.3.52 

type ApplyResult struct {
	PlanID    string           `json:"plan_id"`
	Resources []ResourceOutput `json:"resources"`
	Errors    []ActionError    `json:"errors,omitempty"`
}

ApplyResult summarises the outcome of applying a plan.

type CapabilityDeclaration added in v0.3.52 

type CapabilityDeclaration struct {
	ResourceType string   `json:"resource_type"` // infra.database, infra.vpc, etc.
	Tier         int      `json:"tier"`          // 1=infra, 2=shared, 3=app
	Operations   []string `json:"operations"`    // create, read, update, delete, scale
}

CapabilityDeclaration describes a resource type supported by a provider.

type DestroyResult added in v0.3.52 

type DestroyResult struct {
	Destroyed []string      `json:"destroyed"`
	Errors    []ActionError `json:"errors,omitempty"`
}

DestroyResult summarises the outcome of a destroy operation.

type DiffResult added in v0.3.52 

type DiffResult struct {
	NeedsUpdate  bool          `json:"needs_update"`
	NeedsReplace bool          `json:"needs_replace"`
	Changes      []FieldChange `json:"changes"`
}

DiffResult summarises the differences between desired and actual resource state.

type DriftResult added in v0.3.52 

type DriftResult struct {
	Name     string         `json:"name"`
	Type     string         `json:"type"`
	Drifted  bool           `json:"drifted"`
	Expected map[string]any `json:"expected"`
	Actual   map[string]any `json:"actual"`
	Fields   []string       `json:"fields"` // which fields drifted
}

DriftResult captures detected drift between declared and actual resource state.

type EventEmitter 

type EventEmitter interface {
	EmitWorkflowStarted(ctx context.Context, workflowType, action string, data map[string]any)
	EmitWorkflowCompleted(ctx context.Context, workflowType, action string, duration time.Duration, results map[string]any)
	EmitWorkflowFailed(ctx context.Context, workflowType, action string, duration time.Duration, err error)
}

EventEmitter publishes workflow lifecycle events. *module.WorkflowEventEmitter satisfies this interface. All methods must be safe to call when no event bus is configured (no-ops).

type EventRecorder 

type EventRecorder interface {
	RecordEvent(ctx context.Context, executionID string, eventType string, data map[string]any) error
}

EventRecorder records pipeline execution events for observability. *store.EventRecorderAdapter and any compatible recorder satisfy this interface.

type FieldChange added in v0.3.52 

type FieldChange struct {
	Path     string `json:"path"`
	Old      any    `json:"old"`
	New      any    `json:"new"`
	ForceNew bool   `json:"force_new"` // change requires resource replacement
}

FieldChange describes a single field-level difference.

type HealthResult added in v0.3.52 

type HealthResult struct {
	Healthy bool   `json:"healthy"`
	Message string `json:"message,omitempty"`
}

HealthResult is the outcome of a health check for a resource.

type IaCProvider added in v0.3.52 

type IaCProvider interface {
	Name() string
	Version() string
	Initialize(ctx context.Context, config map[string]any) error

	// Capabilities returns what resource types this provider supports.
	Capabilities() []CapabilityDeclaration

	// Lifecycle
	Plan(ctx context.Context, desired []ResourceSpec, current []ResourceState) (*Plan, error)
	Apply(ctx context.Context, plan *Plan) (*ApplyResult, error)
	Destroy(ctx context.Context, resources []ResourceRef) (*DestroyResult, error)

	// Observability
	Status(ctx context.Context, resources []ResourceRef) ([]ResourceStatus, error)
	DetectDrift(ctx context.Context, resources []ResourceRef) ([]DriftResult, error)

	// Migration
	Import(ctx context.Context, cloudID string, resourceType string) (*ResourceState, error)

	// Sizing
	ResolveSizing(resourceType string, size Size, hints *ResourceHints) (*ProviderSizing, error)

	// Resource drivers for fine-grained CRUD
	ResourceDriver(resourceType string) (ResourceDriver, error)

	Close() error
}

IaCProvider is the main interface that cloud provider plugins implement. Each provider (AWS, GCP, Azure, DO) implements this as a gRPC plugin.

type IaCStateStore added in v0.3.52 

type IaCStateStore interface {
	SaveResource(state ResourceState) error
	GetResource(name string) (*ResourceState, error)
	ListResources() ([]ResourceState, error)
	DeleteResource(name string) error

	SavePlan(plan Plan) error
	GetPlan(id string) (*Plan, error)

	Lock(resource string) error
	Unlock(resource string) error

	Close() error
}

IaCStateStore provides persistent state tracking for managed resources.

type MetricsRecorder 

type MetricsRecorder interface {
	RecordWorkflowExecution(workflowType, action, status string)
	RecordWorkflowDuration(workflowType, action string, duration time.Duration)
}

MetricsRecorder records workflow execution metrics. *module.MetricsCollector satisfies this interface. All methods must be safe to call when no metrics backend is configured (no-ops).

type PipelineContext added in v0.3.39 

type PipelineContext struct {
	// TriggerData is the original data from the trigger (immutable after creation).
	TriggerData map[string]any

	// StepOutputs maps step-name -> output from each completed step.
	StepOutputs map[string]map[string]any

	// Current is the merged state: trigger data + all step outputs.
	// Steps read from Current and their output is merged back into it.
	Current map[string]any

	// Metadata holds execution metadata (pipeline name, trace ID, etc.)
	Metadata map[string]any
}

PipelineContext carries data through a pipeline execution.

func NewPipelineContext added in v0.3.39 

func NewPipelineContext(triggerData map[string]any, metadata map[string]any) *PipelineContext

NewPipelineContext creates a PipelineContext initialized with trigger data.

func (*PipelineContext) MergeStepOutput added in v0.3.39 

func (pc *PipelineContext) MergeStepOutput(stepName string, output map[string]any)

MergeStepOutput records a step's output and merges it into Current.

type PipelineExecutor added in v0.3.51 

type PipelineExecutor interface {
	// ExecutePipeline runs a named pipeline synchronously and returns its
	// structured output. Returns _pipeline_output if set by
	// step.pipeline_output, otherwise the pipeline's merged Current state.
	ExecutePipeline(ctx context.Context, name string, data map[string]any) (map[string]any, error)
}

PipelineExecutor provides direct pipeline invocation for Go callers (gRPC servers, tests, etc.) without HTTP serialization overhead. *workflow.StdEngine satisfies this interface.

type PipelineRunner 

type PipelineRunner interface {
	// Run executes the pipeline with the given trigger data and returns the
	// merged result map (equivalent to PipelineContext.Current).
	Run(ctx context.Context, data map[string]any) (map[string]any, error)

	// SetLogger sets the logger used for pipeline execution.
	// Implementations should be idempotent: if a logger is already set,
	// a subsequent call should be a no-op.
	SetLogger(logger *slog.Logger)

	// SetEventRecorder sets the recorder used for pipeline execution events.
	// Implementations should be idempotent: if a recorder is already set,
	// a subsequent call should be a no-op.
	SetEventRecorder(recorder EventRecorder)
}

PipelineRunner is the interface satisfied by *module.Pipeline. It allows workflow handlers to execute pipelines without importing the concrete module types, enabling handler unit tests with mocks.

type PipelineStep added in v0.3.39 

type PipelineStep interface {
	// Name returns the step's unique name within the pipeline.
	Name() string

	// Execute runs the step with the pipeline context.
	Execute(ctx context.Context, pc *PipelineContext) (*StepResult, error)
}

PipelineStep is a single composable unit of work in a pipeline.

type Plan added in v0.3.52 

type Plan struct {
	ID        string       `json:"id"`
	Actions   []PlanAction `json:"actions"`
	CreatedAt time.Time    `json:"created_at"`
}

Plan is the complete execution plan for a set of infrastructure changes.

type PlanAction added in v0.3.52 

type PlanAction struct {
	Action   string         `json:"action"` // create, update, replace, delete
	Resource ResourceSpec   `json:"resource"`
	Current  *ResourceState `json:"current,omitempty"`
	Changes  []FieldChange  `json:"changes,omitempty"`
}

PlanAction is a single planned change within a Plan.

type ProviderSizing added in v0.3.52 

type ProviderSizing struct {
	InstanceType string         `json:"instance_type"`
	Specs        map[string]any `json:"specs"`
}

ProviderSizing is the concrete sizing resolved by a provider for a resource type.

type Reconfigurable added in v0.2.20 

type Reconfigurable interface {
	// Reconfigure applies new configuration to a running module.
	// The module should:
	//   1. Validate the new config
	//   2. Gracefully drain in-flight work
	//   3. Apply the new configuration
	//   4. Resume accepting new work
	// Returns an error if the new config is invalid or cannot be applied.
	Reconfigure(ctx context.Context, newConfig map[string]any) error
}

Reconfigurable is optionally implemented by modules that support runtime reconfiguration without requiring a full engine restart. When a config change affects only modules implementing this interface, the engine can perform a surgical update instead of a full stop/rebuild/start.

type ResourceDriver added in v0.3.52 

type ResourceDriver interface {
	Create(ctx context.Context, spec ResourceSpec) (*ResourceOutput, error)
	Read(ctx context.Context, ref ResourceRef) (*ResourceOutput, error)
	Update(ctx context.Context, ref ResourceRef, spec ResourceSpec) (*ResourceOutput, error)
	Delete(ctx context.Context, ref ResourceRef) error
	Diff(ctx context.Context, desired ResourceSpec, current *ResourceOutput) (*DiffResult, error)
	HealthCheck(ctx context.Context, ref ResourceRef) (*HealthResult, error)
	Scale(ctx context.Context, ref ResourceRef, replicas int) (*ResourceOutput, error)
}

ResourceDriver handles CRUD for a single resource type within a provider.

type ResourceHints added in v0.3.52 

type ResourceHints struct {
	CPU     string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory  string `json:"memory,omitempty" yaml:"memory,omitempty"`
	Storage string `json:"storage,omitempty" yaml:"storage,omitempty"`
}

ResourceHints are optional fine-grained overrides on top of the Size tier.

type ResourceOutput added in v0.3.52 

type ResourceOutput struct {
	Name       string         `json:"name"`
	Type       string         `json:"type"`
	ProviderID string         `json:"provider_id"`
	Outputs    map[string]any `json:"outputs"` // IPs, endpoints, connection strings
	Status     string         `json:"status"`
}

ResourceOutput is the concrete output of a provisioned or read resource.

type ResourceRef added in v0.3.52 

type ResourceRef struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	ProviderID string `json:"provider_id,omitempty"`
}

ResourceRef is a lightweight reference to an existing resource.

type ResourceSpec added in v0.3.52 

type ResourceSpec struct {
	Name      string         `json:"name"`
	Type      string         `json:"type"`
	Config    map[string]any `json:"config"`
	Size      Size           `json:"size,omitempty"`
	Hints     *ResourceHints `json:"hints,omitempty"`
	DependsOn []string       `json:"depends_on,omitempty"`
}

ResourceSpec is the desired state declaration for a single resource.

type ResourceState added in v0.3.52 

type ResourceState struct {
	ID             string         `json:"id"`
	Name           string         `json:"name"`
	Type           string         `json:"type"`
	Provider       string         `json:"provider"`
	ProviderID     string         `json:"provider_id"`
	ConfigHash     string         `json:"config_hash"`
	AppliedConfig  map[string]any `json:"applied_config"`
	Outputs        map[string]any `json:"outputs"`
	Dependencies   []string       `json:"dependencies"`
	CreatedAt      time.Time      `json:"created_at"`
	UpdatedAt      time.Time      `json:"updated_at"`
	LastDriftCheck time.Time      `json:"last_drift_check,omitempty"`
}

ResourceState is the persisted state record for a single managed resource.

type ResourceStatus added in v0.3.52 

type ResourceStatus struct {
	Name       string         `json:"name"`
	Type       string         `json:"type"`
	ProviderID string         `json:"provider_id"`
	Status     string         `json:"status"` // running, stopped, degraded, unknown
	Outputs    map[string]any `json:"outputs"`
}

ResourceStatus is the live status of a provisioned resource.

type SchemaRegistrar 

type SchemaRegistrar interface {
	// Name returns the module name (used for logging).
	Name() string

	// RegisterAdminSchemas registers all admin API request/response schemas
	// onto this generator. Equivalent to calling module.RegisterAdminSchemas(gen).
	RegisterAdminSchemas()

	// ApplySchemas applies all previously registered component schemas and
	// operation schema overrides to the current OpenAPI spec.
	ApplySchemas()
}

SchemaRegistrar is implemented by any service that can register admin schemas into an OpenAPI specification and apply them. Using this interface in cmd/server allows the server to enrich the OpenAPI spec without holding a concrete *module.OpenAPIGenerator pointer.

*module.OpenAPIGenerator satisfies this interface.

type Size added in v0.3.52 

type Size string

Size is the abstract sizing tier for a resource. 

const (
	SizeXS Size = "xs"
	SizeS  Size = "s"
	SizeM  Size = "m"
	SizeL  Size = "l"
	SizeXL Size = "xl"
)

type SizingDefaults added in v0.3.52 

type SizingDefaults struct {
	CPU         string `json:"cpu"`
	Memory      string `json:"memory"`
	DBStorage   string `json:"db_storage"`
	CacheMemory string `json:"cache_memory"`
}

SizingDefaults holds the concrete resource values for a given size tier.

type StepRegistrar added in v0.3.39 

type StepRegistrar interface {
	StepRegistryProvider
	// Create instantiates a PipelineStep of the given type.
	// app must be a modular.Application; it is typed as any to avoid
	// coupling this interfaces package to the modular dependency.
	Create(stepType, name string, config map[string]any, app any) (PipelineStep, error)
}

StepRegistrar manages step type registration and creation. It embeds StepRegistryProvider for type enumeration and adds a Create method for instantiating steps. Register is intentionally omitted from this interface because factory signatures use modular.Application (a concrete type) which cannot be expressed here without creating an import cycle.

type StepRegistryProvider 

type StepRegistryProvider interface {
	// Types returns all registered step type names.
	Types() []string
}

StepRegistryProvider exposes the step types registered in a step registry. *module.StepRegistry satisfies this interface.

type StepResult added in v0.3.39 

type StepResult struct {
	// Output is the data produced by this step.
	Output map[string]any

	// NextStep overrides the default next step (for conditional routing).
	// Empty string means continue to the next step in sequence.
	NextStep string

	// Stop indicates the pipeline should stop after this step (success).
	Stop bool
}

StepResult is the output of a single pipeline step execution.

type Trigger 

type Trigger interface {
	modular.Module
	modular.Startable
	modular.Stoppable

	// Configure sets up the trigger from configuration.
	Configure(app modular.Application, triggerConfig any) error
}

Trigger defines what can start a workflow execution. Moving this interface here breaks the engine→module import dependency while preserving backward compatibility via the type alias in the module package.

*module.HTTPTrigger, *module.ScheduleTrigger, and other concrete trigger implementations all satisfy this interface.

type TriggerRegistrar 

type TriggerRegistrar interface {
	// RegisterTrigger adds a trigger to the registry.
	RegisterTrigger(trigger Trigger)
}

TriggerRegistrar manages registered triggers. *module.TriggerRegistry satisfies this interface.

type WorkflowStoreProvider 

type WorkflowStoreProvider interface {
	// Name returns the module name (used for logging).
	Name() string

	// WorkflowStore returns the underlying workflow data store as an opaque
	// value. The caller is responsible for asserting the concrete type
	// (typically *module.V1Store) when further operations are required.
	WorkflowStore() any
}

WorkflowStoreProvider is implemented by any service that exposes a workflow data store. Using this interface in cmd/server decouples the server startup code from the concrete *module.WorkflowRegistry type.

*module.WorkflowRegistry satisfies this interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.