siemens / wfx

a lightweight, general-purpose workflow executor

wfx

A lightweight, general-purpose workflow executor.

Overview

Workflows are modeled as finite-state machines and are instantiated as Jobs through which the wfx and a client progress in lock-step to perform a task. Such a task could be software updating the client, progressing a work item through Kanban, … in essence anything requiring cooperation and coordination.

As being general purpose, wfx is only concerned with driving the (state) machinery, the specific actions a client should perform are encoded in the client implementation(s). Hence, one wfx instance can drive a multitude of wholly different workflows. Instantiating a workflow as a job augments it with additional metadata, the Job Definition, which contains job-specific information such as, e.g., URLs or other data the client (implementation) can make use of for this particular job.

To illustrate the concepts as well as the wfx / client interaction, consider the following figure

┌──────────────────────────────────────┐                       ┌──────────────┐
│                 wfx                  │                     ┌─┴────────────┐ │
│                                      │                     │   Client Y   │ │
│                                      │     poll for jobs   │              │ │
│                instantiate ┌───────┐ │◀────────────────────│              │ │
│  ┌────────────┐        ┌──▶│ Job 1 │ │────────────────────▶│──────┐       │ │
│  │ Workflow A ├────────┤   └───────┘ │◀─┐  job information │      ▼       │ │
│  └────────────┘        │   ┌───────┐ │  │                  │     act      │ │
│                   ┌────┼──▶│ Job 2 │ │  └──────────────────│◀─────┘       │ │
│  ┌────────────┐   │    │   └───────┘ │     update state    │              │ │
│  │ Workflow B ├───┘    │   ┌───────┐ │                     │              │ │
│  └────────────┘        └──▶│ Job 3 │ │           .         │              │ │
│                            └───────┘ │           .         │              │ │
│       ...                     ...    │           .         │              │ │
│                                      │                     │              ├─┘
└──────────────────────────────────────┘                     └──────────────┘

with the wfx having loaded a number of workflows Workflow A, Workflow B, … that got instantiated as Job 1, Job 2, Job 3, … with a Client Y working on Job 1: It polls the wfx for a new job or the current job's status, in return receives the job information, performs actions if applicable, and finally reports the new job status back to the wfx. This lock-step procedure is repeated until the workflow reaches a terminal state which could be identified with, e.g., success or failure.

wfx in (Example) Action

An exemplary Kanban-inspired workflow illustrating the interplay between the wfx as Kanban "Board", a Product Owner creating jobs, and a Developer executing them:

wfx Features & Non-Features

• Design Guidelines
  • Compact, scalable core focusing on the essentials
  • Proper interfaces to external systems for modularity and integrability: Accompanying and necessary services like artifact storage and device registry are likely already available or are better provided by specialized solutions
• Implementation
  • Extendable modularized source code architecture
  • Lightweight, no dependencies (statically linked binaries)
  • Efficient, native code for a wide variety of platforms and operating systems (as supported by the Go Language)
  • Fully documented REST API, see wfx OpenAPI Specification
  • Extensive test suite including load tests
• Deployment / Usability
  • Load / Unload workflows at run-time
  • Hot / Live reload of configuration file
  • Persistent Storage: built-in support for SQLite, PostgreSQL and MySQL
  • A complimentary built-in file server serving as artifact storage for dynamic deployments and integration without external file storage
  • Transport Layer Security (HTTPS) with support for custom certificates

wfx Clients

Currently, the following clients have support for wfx:

• SWUpdate - Software Update for Embedded Linux Devices implementing support for the Device Artifact Update Workflow Family

Documentation

Grouped by topic, the following documentation is available in docs/:

• Workflows: Core concepts of Workflows and Jobs
• Installation: How to install and deploy wfx.
• Configuration: How to configure wfx.
• Operation: How to operate wfx.
• Use-Cases: A collection of use-cases for wfx.
• API: wfx's north- and southbound APIs.

You can also browse the rendered documentation at https://siemens.github.io/wfx/.

Roadmap

The roadmap is tracked via Github issues.

Contributing

Contributions are encouraged and welcome!

See CONTRIBUTING.md for details.

License

Copyright ©️ 2023 Siemens AG.

Released under the Apache-2.0 license.

wfx's Issues

Plugin System for Request (Pre-)Processing

Description

This feature proposes the addition of a mechanism to integrate user-defined middlewares into wfx.
Middlewares serve as an intermediary layer processing incoming HTTP requests before they are handed over to wfx's internal middlewares and request handler.

Functional Requirements

1. The middleware must have the capability to modify an incoming HTTP request, including but not limited to, rewriting headers and altering the URL for rerouting purposes.
2. The middleware should offer the option to send an HTTP response back to the client, preempting further processing by any subsequent middleware or by wfx itself.

Motivation

Implementing this feature will provide developers with a modular approach to add custom functionalities, such as
authentication and authorization mechanisms, to wfx. This enhancement will significantly improve the flexibility and
extensibility of wfx.

Proposed Solution (optional)

There are multiple methodologies for introducing plugins into a Go application:

1. Native Go plugins (buildmode=plugin)
2. Utilizing Go's C FFI bindings
3. Incorporating a scripting language interpreter, such as gopher-lua
4. Spawning subprocesses and establishing communication through a suitable channel, as demonstrated by hashicorp/go-plugin

After evaluating these options, the following conclusions were reached:

1. Native Go Plugins: Highly restrictive due to stringent conditions for loading native plugins. Both the plugin and wfx must be compiled using identical go.mod files. This creates a tightly coupled relationship between wfx and its plugins, impeding the ability to upgrade wfx independently of the plugins.

2. Go's C FFI Bindings: This approach is flexible, given that C ABI acts as a common interface. However, it introduces potential risks, such as crashing or compromising the host process (wfx), primarily due to shared memory concerns. Moreover, Go's C FFI is not renowned for performance.

3. Scripting Language Interpreter: Limited in scope as plugins must be written in a specific language, potentially causing difficulties when incorporating third-party libraries.

4. Spawning Subprocesses: Both robust and flexible, this approach isolates plugins in separate child processes, mitigating risks associated with crashing or compromising the host. Additionally, it permits plugins to be written in any language capable of implementing the designated communication channel.

Based on these evaluations, it is recommended to adopt a variation of the fourth approach for the implementation of this feature.

Notify clients on job updates

Description

We are aiming to build a more efficient mechanism within wfx to notify one or more clients instantly when there is a change in the job status.

Motivation

As of now, clients are required to repeatedly make polling requests to keep track of job status updates. This approach is inherently flawed due to the possibility of multiple job updates occurring between two consecutive polls, leading to time-of-check to time-of-use (TOCTOU) inconsistencies. Although one might think of compensating for this by retrieving the job status update history, this method is not only convoluted but also scales poorly due to the influx of client requests burdening the server.

Proposed Solution (optional)

We propose the introduction of a new (HTTP) API endpoint, /jobs/{id}/status/subscribe, supporting the GET method and having Content-type: text/event-stream.
This allows us to use server-sent events (SSE) and seamlessly notify clients upon any job status update.

Benefits:

• Relies on established HTTP protocols, ensuring compatibility even with (corporate) proxies.
• Compliant with the HTML5 standard, which guarantees longevity and support.
• Offers excellent library support, and is straightforward to integrate independently.

Drawbacks:

• Limited to a maximum of 6 concurrent client connections per browser, which could be constraining when developing a web-based interface for wfx. However, this limit is expandable when leveraging HTTP/2.

Alternative Solutions:

WebSockets were considered but deemed excessive for our needs. Additionally, it supports bidirectional communication, which is not a requirement for this feature. Moreover, it's known to have issues with proxy servers.