HTTP API Boundary Roadmap

Purpose

This roadmap records the accepted boundary for a future HTTP API. The current application exposes CLI commands and internal app-layer run contracts; it does not implement an HTTP server, HTTP routes, a serve command, app-level authentication, or in-app TLS.

Implemented internal run contracts are documented in docs/internal/app.md. This file is the canonical home for future HTTP boundary decisions until an HTTP implementation roadmap replaces it.

Accepted Direction

The future HTTP API should trigger configured distributor pipelines through the existing app-layer single-pipeline run path and in-memory coordinator.

The HTTP API is intentionally narrow:

A trigger request accepts only a pipeline ID as application input.
A trigger request starts work asynchronously and returns a run ID after admission.
Run status is read through a separate status endpoint keyed by run ID.
Status records expose run ID, pipeline ID, current status, timestamps, and completed report or error details when available.

The application remains a bundle distribution tool. The HTTP API must not turn distributor into a workflow engine, CMS, report generator, or public web authoring service.

Error Mapping

Future transport code should map app-layer errors without changing app-layer error ownership:

Unknown pipeline IDs map to 404 Not Found.
Duplicate in-flight runs for the same pipeline ID map to 409 Conflict.
Validation, config, source, destination, publish, transform, and notification errors map to transport errors according to their app-layer context.

Duplicate runs must not be queued. Run state remains in memory unless a later roadmap explicitly adds durable run storage.

Context And Lifetime

The request context guards admission. Once a run is admitted, execution is tied to the server or coordinator lifetime context rather than to the client request lifetime.

This split allows a client disconnect or request timeout to stop waiting for admission without canceling a run that has already been accepted.

Security Boundary

The first HTTP server should default to private binding, such as 127.0.0.1. Operators should expose it through a reverse proxy, private network, or external mTLS when transport security or remote access is required.

The first HTTP implementation should not include:

bearer-token authentication;
in-app TLS configuration;
public-network exposure defaults.

A later roadmap must explicitly change this security decision before any of those features are added.

Non-Goals

The future HTTP API should not add:

public CLI flags for selecting one pipeline during distributor run;
a CLI framework;
a generic workflow engine;
plugin execution;
durable run storage;
app-level authentication;
in-app TLS.

Verification Expectations

Any later HTTP implementation should preserve existing CLI behavior and keep the app-layer run contracts tested. At minimum, it should cover:

trigger requests with known and unknown pipeline IDs;
duplicate in-flight trigger requests;
asynchronous acceptance and status lookup;
private bind defaults;
request-context admission behavior;
coordinator-lifetime run execution.

3.2 KiB Raw Blame History