workflow

README

Workflow Engine

A configurable workflow engine built on GoCodeAlone's Modular library v1.3.9, allowing applications to be built entirely from YAML configuration files.

Overview

This workflow engine lets you create applications by chaining together modular components based on YAML configuration files. You can configure the same codebase to operate as:

• An API server with authentication middleware
• An event processing system
• A bidirectional chat system with triage capabilities

All without changing code - just by modifying configuration files.

Requirements

• Go 1.23 or later
• GoCodeAlone/modular v1.3.9

Architecture

The workflow engine is built on these core concepts:

• Modules: Self-contained components that provide specific functionality
• Workflows: Configurations that chain modules together to create application behavior
• Handlers: Components that understand how to interpret and configure specific workflow types

Module Types

The engine supports several types of modules:

• HTTP Server: Handles HTTP requests
• HTTP Router: Routes HTTP requests to handlers
• HTTP Handlers: Processes HTTP requests and generates responses
• Authentication Middleware: Validates requests before they reach handlers
• Message Broker: Facilitates message-based communication
• Message Handlers: Processes messages from specific topics

Configuration

Applications are defined via YAML configuration files. Here's a basic example:

modules:
  - name: http-server
    type: http.server
    config:
      address: ":8080"
  - name: router
    type: http.router
  - name: hello-handler
    type: http.handler

workflows:
  http:
    routes:
      - method: GET
        path: /hello
        handler: hello-handler

Advanced Configuration

You can create more complex applications with authentication and messaging:

modules:
  - name: api-http-server
    type: http.server
    config:
      address: ":8080"
  - name: api-router
    type: http.router
  - name: auth-middleware
    type: http.middleware.auth
  - name: users-api
    type: api.handler
    config:
      resourceName: "users"
  - name: message-broker
    type: messaging.broker

workflows:
  http:
    routes:
      - method: GET
        path: /api/users
        handler: users-api
        middlewares:
          - auth-middleware
  messaging:
    subscriptions:
      - topic: user-events
        handler: user-event-handler

Example Applications

The repository includes several example applications:

1. API Server: A RESTful API with protected endpoints
2. Event Processor: A message-based event processing system
3. SMS Chat: A bidirectional chat system with triage workflow

Usage

Run any example by specifying the configuration file:

go run example/main.go -config example/api-server-config.yaml

Extending

To extend the workflow engine with custom modules:

1. Implement the appropriate interfaces in the module package
2. Register your module type in the BuildFromConfig method of the engine
3. Create a configuration file that uses your new module type

Testing

Run the tests to verify the workflow engine functionality:

go test ./...

Documentation

Index

• type Engine
• type ModuleFactory
• type StartStopModule
• type StdEngine
  • func NewStdEngine(app modular.Application, logger modular.Logger) *StdEngine
  • func (e *StdEngine) AddModuleType(moduleType string, factory ModuleFactory)
  • func (e *StdEngine) BuildFromConfig(cfg *config.WorkflowConfig) error
  • func (e *StdEngine) RegisterTrigger(trigger module.Trigger)
  • func (e *StdEngine) RegisterWorkflowHandler(handler WorkflowHandler)
  • func (e *StdEngine) Start(ctx context.Context) error
  • func (e *StdEngine) Stop(ctx context.Context) error
  • func (e *StdEngine) TriggerWorkflow(ctx context.Context, workflowType string, action string, ...) error
• type WorkflowHandler

Types

type Engine

type Engine interface {
	RegisterWorkflowHandler(handler WorkflowHandler)
	RegisterTrigger(trigger module.Trigger)
	AddModuleType(moduleType string, factory ModuleFactory)
	BuildFromConfig(cfg *config.WorkflowConfig) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	TriggerWorkflow(ctx context.Context, workflowType string, action string, data map[string]interface{}) error
}

type ModuleFactory

type ModuleFactory func(name string, config map[string]interface{}) modular.Module

ModuleFactory is a function that creates a module from a name and configuration

type StartStopModule

type StartStopModule interface {
	modular.Module
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

StartStopModule extends the basic Module interface with lifecycle methods

type StdEngine

type StdEngine struct {
	// contains filtered or unexported fields
}

StdEngine represents the workflow execution engine

func NewStdEngine

func NewStdEngine(app modular.Application, logger modular.Logger) *StdEngine

NewStdEngine creates a new workflow engine

func (*StdEngine) AddModuleType

func (e *StdEngine) AddModuleType(moduleType string, factory ModuleFactory)

AddModuleType registers a factory function for a module type

func (*StdEngine) BuildFromConfig

func (e *StdEngine) BuildFromConfig(cfg *config.WorkflowConfig) error

BuildFromConfig builds a workflow from configuration

func (*StdEngine) RegisterTrigger

func (e *StdEngine) RegisterTrigger(trigger module.Trigger)

RegisterTrigger registers a trigger with the engine

func (*StdEngine) RegisterWorkflowHandler

func (e *StdEngine) RegisterWorkflowHandler(handler WorkflowHandler)

RegisterWorkflowHandler adds a workflow handler to the engine

func (*StdEngine) Start

func (e *StdEngine) Start(ctx context.Context) error

Start starts all modules and triggers

func (*StdEngine) Stop

func (e *StdEngine) Stop(ctx context.Context) error

Stop stops all modules and triggers

func (*StdEngine) TriggerWorkflow

func (e *StdEngine) TriggerWorkflow(ctx context.Context, workflowType string, action string, data map[string]interface{}) error

TriggerWorkflow starts a workflow based on a trigger

type WorkflowHandler

type WorkflowHandler interface {
	// CanHandle returns true if this handler can process the given workflow type
	CanHandle(workflowType string) bool

	// ConfigureWorkflow sets up the workflow from configuration
	ConfigureWorkflow(app modular.Application, workflowConfig interface{}) error

	// ExecuteWorkflow executes a workflow with the given action and input data
	ExecuteWorkflow(ctx context.Context, workflowType string, action string, data map[string]interface{}) (map[string]interface{}, error)
}

WorkflowHandler interface for handling different workflow types