66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
|
# ADR 0003: Keep Flux as the connection broker
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted.
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Coolify v5 needs to send host primitive requests to many managed hosts, including
|
||
|
|
hosts behind NAT, firewalls, or corporate networks. coold can solve the host
|
||
|
|
inbound problem by dialing out, but Laravel request workers should not own
|
||
|
|
thousands of long-lived HTTP/2 agent streams or in-memory pending response maps.
|
||
|
|
|
||
|
|
The system also needs a place to translate between Coolify's short-lived local
|
||
|
|
request/response lane and coold's long-lived outbound stream without turning that
|
||
|
|
place into another product control plane.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
Flux is the central connection broker between Coolify Laravel and coold agents.
|
||
|
|
Laravel talks to Flux over a local Unix socket. coold agents dial Flux over an
|
||
|
|
outbound authenticated gRPC stream. Flux keeps the connected-host stream
|
||
|
|
registry, routes requests to the selected host stream, tracks pending request IDs,
|
||
|
|
and resolves typed responses back to Laravel.
|
||
|
|
|
||
|
|
Flux owns transport concerns: stream lifecycle, request correlation, timeouts,
|
||
|
|
disconnected-host responses, pending-request caps, late-result handling, and
|
||
|
|
host-agent authentication for inbound coold streams.
|
||
|
|
|
||
|
|
Flux must not own Coolify product concepts. It does not decide which user may
|
||
|
|
deploy, which host should run an application, what a domain means, how rollback
|
||
|
|
works, or how deployment state advances. Flux treats `containers.start` or
|
||
|
|
`images.pull` as protocol frames routed to a host, not as product actions.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
### Positive
|
||
|
|
|
||
|
|
- Hosts can remain behind NAT because coold dials out to Flux.
|
||
|
|
- Laravel stays focused on durable product state and short-lived request work.
|
||
|
|
- Long-lived stream management can scale and fail independently from PHP-FPM
|
||
|
|
workers.
|
||
|
|
- Backpressure, timeouts, and disconnected-host behavior have one transport
|
||
|
|
boundary.
|
||
|
|
- Flux can be tested as a protocol router without needing Coolify's app model.
|
||
|
|
|
||
|
|
### Negative
|
||
|
|
|
||
|
|
- The architecture has one more runtime component to deploy and monitor.
|
||
|
|
- Protocol changes must stay coordinated across Coolify, Flux, and coold.
|
||
|
|
- Flux outage blocks dispatch to connected hosts even when Laravel and hosts are
|
||
|
|
otherwise healthy.
|
||
|
|
- Flux must stay intentionally narrow; adding product decisions would create a
|
||
|
|
second control plane.
|
||
|
|
|
||
|
|
## Boundary rules
|
||
|
|
|
||
|
|
- Coolify chooses the target host; Flux only routes to that host's connected
|
||
|
|
stream.
|
||
|
|
- coold authenticates to Flux as a host agent; Laravel reaches Flux through the
|
||
|
|
local Unix-socket lane.
|
||
|
|
- Flux may answer transport failures such as disconnected host, timeout, or
|
||
|
|
pending-cap overflow.
|
||
|
|
- Flux may not inspect product ownership, RBAC, billing, deployment state,
|
||
|
|
domains, secrets, or audit meaning.
|