Workflow Server

tramai-server exposes registered workflows over HTTP. It is the runtime module for teams that want to trigger, inspect, resume, cancel, and observe workflows from outside JVM application code.

What This Covers

Workflow discovery and run creation
Webhook-triggered workflow runs
Workflow resume, cancellation, and status
Per-run SSE event streams
Generated OpenAPI 3.1 document
Dashboard-adjacent endpoints (workers, schedules, audit)

When to Use It

Add tramai-server when:

external agents need to start or inspect workflows
you need webhook integration (GitHub, Slack, etc.)
you want SSE streams for run progress
multiple services need to trigger the same workflows

Minimum Setup

Dependency

implementation("dev.tramai:tramai-server:0.3.1")
implementation("dev.tramai:tramai-orchestration:0.3.1")

Configuration

tramai:
  server:
    max-request-body-bytes: 1048576
    max-run-history-size: 1000
    sse-event-buffer-size: 100
    max-audit-entries: 10000
    webhooks:
      secret: ""

The server also uses standard Spring Boot HTTP configuration (server.port, etc.).

Core Endpoints

Workflow Lifecycle

Method	Path	Purpose
`GET`	`/workflows`	List registered workflow names
`POST`	`/workflows/{name}/run`	Start a new run from JSON state
`POST`	`/workflows/{name}/runs/{id}/resume`	Resume a persisted run
`GET`	`/workflows/{name}/runs`	List runs with `offset` and `limit`
`GET`	`/workflows/{name}/runs/{id}`	Fetch run detail
`DELETE`	`/workflows/{name}/runs/{id}`	Request cancellation
`GET`	`/workflows/{name}/runs/{id}/events`	Stream run events over SSE

Webhooks and Discovery

Method	Path	Purpose
`POST`	`/webhooks/{name}`	Start a workflow from webhook payload
`GET`	`/openapi.json`	Generated OpenAPI 3.1 description

Dashboard-Adjacent

Method	Path	Purpose
`GET`	`/workers`	List worker status
`GET`	`/workers/events`	Stream worker status changes (SSE)
`GET`	`/schedules`	List schedule summaries
`GET`	`/schedules/events`	Stream schedule updates (SSE)
`GET`	`/audit`	Query in-memory audit log

These endpoints are grouped behind the dashboard feature flag.

Example: Starting a Run

POST /workflows/invoice/run
Content-Type: application/json
Idempotency-Key: inv-123

{"invoiceId":"inv-123","amount":125}

Response:

{
  "workflowId": "7f8c...",
  "status": "running",
  "definitionVersion": "1.0.0",
  "result": null
}

Run Status Model

Status	Meaning
`pending`	Run created, not yet started
`running`	Workflow actively executing
`delayed`	Workflow suspended (delay step)
`waiting_for_gate`	Workflow paused at approval gate
`cancelling`	Cancellation requested, not yet applied
`cancelled`	Run terminated by cancellation
`failed`	Run terminated by error
`completed`	Run finished successfully

Idempotency

The server supports idempotent run creation via Idempotency-Key header. If the key matches an earlier run for the same workflow, the existing run record is returned.

Webhook idempotency reuses delivery identifiers (X-GitHub-Delivery or X-Delivery-ID).

Webhooks

POST /webhooks/{name}
X-Hub-Signature-256: sha256=...
X-GitHub-Delivery: ...

Current implementation:

signature verification is GitHub-style HMAC SHA-256
the verifier reads tramai.server.webhooks.secret
the webhook body is decoded as the workflow's initial state JSON
a successful webhook returns 202 Accepted

SSE Event Stream

GET /workflows/{name}/runs/{id}/events

Current behavior:

uses Last-Event-ID for replay position
the run store keeps a bounded in-memory event buffer per run
the stream closes when the run reaches a terminal state

The event stream is a run-lifecycle feed, not a full tracing backend.

Error Model

The server returns Spring ProblemDetail responses:

Status	Meaning
400	Invalid workflow JSON
401	Invalid webhook signature
413	Oversized request body
404	Unknown workflow or run

Limitations

run history is in-memory unless workflow persistence handles state separately
cancellation is cooperative (coroutine-based), not hard-stop external process management
the OpenAPI document is generated from registered workflow names and route shapes, not from full request/response schemas
webhook verification currently supports one HMAC-SHA-256 verifier — a general plugin layer exists in tramai-platform

Next Steps

Platform Operations — API keys, multi-tenancy, plugins
Scheduling — cron-triggered workflows
MCP Integration — expose workflows as MCP tools