92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# 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.
|