Overview

Referencedraft
On this page

This page describes what Relay is for and how it works. See the compatibility tiers for supported capabilities and the quickstart to run it.

The problem

DBOS Transact is a durable workflow library. An application that uses it keeps its workflow state in its own Postgres database, and on its own it recovers workflows when the process that started them comes back. Distributed recovery, a fleet view, and workflow management come from a separate control plane, Conductor, which is proprietary and which the vendor's public documentation describes as licensed for production use.

That leaves a gap. If a machine never comes back, its workflows stay stranded unless something else notices and hands them to a healthy process.

What Relay is

Relay is that control plane, rebuilt in the open. It targets the two contracts the ecosystem already uses:

  • the executor WebSocket protocol that the open-source SDKs implement, so an application should need no code change to connect, and
  • the Conductor HTTP API, published as an OpenAPI document, so the existing command-line client and generated clients should work against it.

The comparison that explains the shape of the project is headscale, the open-source control server for Tailscale. The client half is already open source and well specified; what is missing is the server the clients talk to, and the protocol between them can be recovered from the clients.

What Relay will hold

Relay is metadata-only by design. Its own small Postgres database is intended to hold organisations, applications, executors, instances, API keys, alert rules, audit entries, and its own metric samples.

Relay never executes direct raw SQL against an application's system database. Executors open outbound WebSockets to Relay, and workflow reads and mutations are dispatched over that socket to an executor, which answers from its own system database. When explicitly configured by an operator, Relay can optionally fall back to reading the system database via the official SDK client when no live executor is connected, with live executors taking precedence. See ADR 0004 and data plane.

What Relay will do

  • Accept executor connections, authenticate them, and track liveness.
  • Detect a dead executor and ask a healthy one to recover its workflows. See recovery.
  • Serve the HTTP API by routing each request to a healthy executor and mapping the answer onto the published schema.
  • Expose a dashboard for applications, executors, workflows, queues, and schedules.
  • Run as a single binary with one required setting, the database URL.

How it is built

Relay is built clean-room from public sources. The proprietary implementation is never downloaded, run, observed, or benchmarked. The canonical list of what may and may not be used is in the clean-room rules, and the reasoning is in ADR 0001.

Status

Implementation is in progress across the core control plane, executor protocol, and data plane. See compatibility tiers for milestone gates and goals and non-goals for the v1 boundary.

Facts about the ecosystem on this page come from the public documentation listed under sources. They are re-verified during discovery and recorded in the provenance ledger.