# 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.