feat(openworkflow, server, cli): server by jamescmartinez · Pull Request #466 · openworkflowdev/openworkflow

jamescmartinez · 2026-04-16T18:11:30Z

👉 closing this PR for now since there are a few prerequisites I want to knock out first. I'll reopen, rebase and finish when ready.

🚧 wip

Right now, openworkflow has no central server. Every worker talks directly to Postgres/SQLite, and the dashboard does too. That's fine for dev / a single-node setup, but it means every worker needs DB credentials, there's no place to put auth/rate-limiting/audit logging, and you can't run workers in environments that shouldn't have direct DB access (edge, untrusted tenants, other languages down the line).

This PR adds @openworkflow/server, an HTTP wrapper around the Backend interface, plus a matching BackendHttp client so workers and the dashboard can point at a URL instead of a database. The DB stays behind the server, and the server becomes the single place to add cross-cutting concerns later (scheduling, retention/cleanup like #370, etc.)

The full shared Backend test suite runs end-to-end against BackendHttp -> Server -> BackendPostgres to prove wire compatibility.

todo:

update docs (readme, public docs, and architecture; no api reference until v1)
cli init
move /metrics to the server from the dashboard
document lack of security for this v0 api (for now, at least)
(maybe) hook up google AIP linter since that was inspo for routes
add example

Copilot

Pull request overview

Introduces an HTTP server layer for OpenWorkflow by proxying the Backend interface over REST (Hono), plus an HTTP client backend implementation intended to let workers/dashboard talk to a server instead of directly to Postgres/SQLite.

Changes:

Added @openworkflow/server package implementing an HTTP API wrapper around Backend (including health/readiness endpoints) with validation + error mapping.
Added BackendHttp client that implements Backend over HTTP, including date-field parsing and BackendError rethrow semantics.
Updated CLI to add openworkflow server start and refactored graceful shutdown wiring.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.json	Adds the new `packages/server` TS project reference.
packages/server/tsconfig.json	New TS config for building the server package.
packages/server/package.json	New `@openworkflow/server` package definition and build scripts.
packages/server/server.ts	Implements the Hono server: routes for workflow runs, step attempts, and signals; verb dispatch; health endpoints; node `serve()`.
packages/server/schemas.ts	Zod request-body schemas used by the server for request validation.
packages/server/errors.ts	Centralized error mapping (`BackendError`→HTTP, validation→400, internal scrubbing) and JSON body parsing helper.
packages/server/server.test.ts	End-to-end suite: `BackendHttp -> Server -> BackendPostgres`, plus server-specific validation/error-path tests.
packages/openworkflow/http/backend.ts	Adds `BackendHttp` implementation for the `Backend` interface over HTTP.
packages/openworkflow/internal.ts	Exposes `BackendError` utilities and exports `STEP_KINDS` for runtime use.
packages/openworkflow/core/error.ts	Introduces `BackendError`, `BackendErrorCode`, and runtime `BACKEND_ERROR_CODES` + guard.
packages/openworkflow/core/error.test.ts	Adds unit test coverage for `BackendError`.
packages/openworkflow/core/step-attempt.ts	Introduces runtime `STEP_KINDS` tuple and derives `StepKind` from it.
packages/cli/tsconfig.json	Adds a TS project reference to `../server`.
packages/cli/package.json	Adds `@openworkflow/server` as a devDependency for monorepo builds/tests.
packages/cli/commands.ts	Adds `serverStart`; refactors graceful shutdown into a shared helper.
packages/cli/cli.ts	Wires the new `openworkflow server start` command into the CLI.
package-lock.json	Links the new workspace package and updates CLI devDependencies.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pkg-pr-new · 2026-04-16T22:13:21Z

Open in StackBlitz

npm i https://pkg.pr.new/openworkflowdev/openworkflow/@openworkflow/cli@466

npm i https://pkg.pr.new/openworkflowdev/openworkflow/@openworkflow/dashboard@466

npm i https://pkg.pr.new/openworkflowdev/openworkflow@466

commit: a27eab4

codecov · 2026-04-16T22:15:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

- Fix TS2379/TS2375/TS2322 errors from `exactOptionalPropertyTypes` by normalizing zod-parsed error bodies into `SerializedError` and by conditionally spreading optional options. - Cast `retryPolicy` to `RetryPolicy` and step-attempt `context` to `StepAttemptContext | null` at the HTTP boundary. - Work around TS2589 deep-instantiation in Hono's `JSONParsed<T>` by routing complex response bodies through a `jsonResponse` helper and splitting step-attempt routes across sub-apps. - Re-export `RetryPolicy`, `SerializedError`, and `StepAttemptContext` from `openworkflow/internal` so the server package can reference them. - Drop unused `BACKEND_ERROR_CODES` and `HttpValidationError` exports, and deduplicate the worker-lease schemas to satisfy knip. - Reformat server sources with prettier.

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 20 out of 22 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

feat(openworkflow, server, cli): server

ad76d8c

Copilot AI review requested due to automatic review settings April 16, 2026 18:11

Copilot started reviewing on behalf of jamescmartinez April 16, 2026 18:11 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/server/server.ts

Comment thread packages/cli/commands.ts Outdated

Comment thread packages/cli/commands.ts Outdated

Comment thread packages/openworkflow/http/backend.ts

Copilot AI review requested due to automatic review settings April 16, 2026 22:31

Copilot started reviewing on behalf of jamescmartinez April 16, 2026 22:31 View session

jamescmartinez force-pushed the server branch from 21456c1 to 34ae828 Compare April 16, 2026 22:31

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/openworkflow/core/error.ts Outdated

Comment thread packages/server/server.ts

Comment thread packages/server/schemas.ts Outdated

Comment thread packages/server/schemas.ts

Comment thread packages/server/schemas.ts Outdated

jamescmartinez added 2 commits April 16, 2026 22:34

Merge branch 'main' into server

f0f14a1

fix: feedback

605d925

Copilot AI review requested due to automatic review settings April 17, 2026 03:52

Copilot started reviewing on behalf of jamescmartinez April 17, 2026 03:52 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/cli/package.json

Comment thread packages/cli/commands.ts Outdated

jamescmartinez added 3 commits April 17, 2026 14:17

fix: set server package to private

af98238

fix: update cspell ignore list for healthz and readyz

281a3d5

Merge branch 'main' into server

f8c1ed5

Copilot AI review requested due to automatic review settings April 17, 2026 19:27

Copilot started reviewing on behalf of jamescmartinez April 17, 2026 19:27 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/server/errors.ts Outdated

Comment thread packages/cli/package.json

Comment thread packages/server/package.json

fix: feedback

a27eab4

jamescmartinez marked this pull request as draft April 17, 2026 20:16

jamescmartinez closed this Apr 17, 2026

jamescmartinez deleted the server branch April 23, 2026 12:39

Conversation

jamescmartinez commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jamescmartinez commented Apr 16, 2026 •

edited

Loading

pkg-pr-new Bot commented Apr 16, 2026 •

edited

Loading

codecov Bot commented Apr 16, 2026 •

edited

Loading