interfaces

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

• type EventEmitter
• type EventRecorder
• type MetricsRecorder
• type PipelineRunner
• type SchemaRegistrar
• type StepRegistryProvider
• type Trigger
• type TriggerRegistrar
• type WorkflowStoreProvider

Types

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 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 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 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 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 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.