FlowWeaver for Go (flow-weaver-go)

A lightweight, embeddable, and declarative workflow engine for Go.

---

What is FlowWeaver?

FlowWeaver is a Go library that allows you to execute complex, stateful workflows described in simple YAML files. It's designed to be embedded into your own Go applications, providing them with a powerful automation and orchestration layer.

Think of it as a "recipe runner." You write the recipe (the "what") in a clean, declarative YAML format, and FlowWeaver provides the intelligent kitchen (the "how") to execute it reliably. It is not a standalone application, but a foundational library for building declarative, "as-code" systems.

Core Principles

FlowWeaver is built on a few key principles:

1. Declarative First: Workflows are described in simple, human-readable YAML. You define the desired flow of logic, not the imperative steps to implement it.
2. Embeddable & Lightweight: It's a standard Go library with minimal dependencies, designed to be a component within a larger application, not a heavy, standalone platform.
3. Extensible by Design: The engine itself knows nothing about networking, databases, or files. It's a "Bring Your Own Actions" model. You, the developer, provide it with the specific, domain-oriented actions it needs to execute.
4. Robust by Compilation: Workflows are "compiled" into a validated, in-memory state machine before execution, catching errors early and ensuring fast, reliable runs.

How It Works

The architecture is split into two parts: the language and the engine.

• The Language (YAML): You define your logic using a hierarchy of concepts:

  • Workflows: High-level, multi-step processes.
  • Flows: Reusable sequences of actions (like functions).
  • Steps: The individual building blocks, which can be an instruction or a control structure (loop, branch, parallel...).
  • Instructions: Calls to specific, atomic Actions.

• The Engine (Go): The flow-weaver-go library provides the runtime that:

  1. Parses and validates the YAML files.
  2. Compiles the workflow into an efficient in-memory state machine.
  3. Executes the state machine, calling the custom Action implementations that you provide and inject into the engine.

Project Status: 🔬 Experimental

This project is in an early, experimental phase. The goal is to create a robust and minimalist core. The API is unstable and subject to change.

This is a personal project, and contributions are not being accepted at this time.

Use Cases

While being developed as the core engine for the ProtocolSmith network testing platform, the FlowWeaver engine is generic enough to power a wide range of applications:

• CI/CD Pipelines: Create a simple, custom CI/CD runner.
• Business Process Orchestration (BPM): Automate business logic like order processing or invoicing.
• Home Automation: Define complex routines for a smart home.
• Infrastructure Automation: A lightweight alternative to more complex tools.

Relationship with ProtocolSmith

ProtocolSmith is the flagship application being built on top of the FlowWeaver engine.

• FlowWeaver is the generic, domain-agnostic framework.
• ProtocolSmith is the specialized application that provides an extensive library of network, http, and chaos actions to the FlowWeaver engine.

---

Project created and maintained by Guillaume Pineda / @gpineda-dev.