feat(gateway): authorize listener requirements for external compute drivers
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 8.7k
- Forks
- 1.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 253
Description
Problem Statement
The compute-driver protocol allows built-in and external drivers to report
gateway listener requirements. The gateway currently authorizes only a narrow
hard-coded set:
- Docker and Podman may request an exact listener address.
- Podman may request the IPv4 default-route or loopback interface.
- All requirements from other driver identities are rejected.
This is an appropriate initial boundary for #2492, but it means an external
driver can implement the protocol RPC without being able to use it. Simply
trusting every connected driver would be unsafe because a requirement can
cause the gateway to bind an additional host socket.
Related design work: #2215, #2492, and #2538.
Proposed Design
Add an operator-controlled capability policy for external compute drivers.
The policy should bind authority to the configured driver identity and constrain
which listener selectors that driver may request. The gateway remains the
authority that resolves semantic selectors, validates the resulting addresses,
and binds sockets.
The initial design should preserve these invariants:
- External drivers receive no listener authority by default.
- Capabilities distinguish exact-address, default-route, and loopback
requirements rather than granting one unrestricted listener capability. - Exact-address authority can be constrained by address family, CIDR, port,
or another operator-owned boundary. - Wildcard, multicast, zero-port, and incompatible-port listeners remain
invalid regardless of driver capability. - Driver-reported reasons and resolved listener provenance remain observable,
but do not grant authority. - Endpoint advertisement and callback API exposure remain gateway-owned and
separate from network reachability authority.
Acceptance criteria
- Define the configuration and protocol relationship for granting an
external driver listener capabilities. - Default-deny every external driver that has no explicit operator grant.
- Define selector-specific constraints for exact-address, default-route,
and loopback requirements. - Preserve gateway-side resolution, validation, binding, and callback-only
routing. - Define driver identity and configuration provenance strongly enough that
one configured driver cannot exercise another driver's grant. - Define startup failure and diagnostic behavior for unauthorized,
unresolvable, and unbindable requirements. - Cover old drivers that return
UNIMPLEMENTEDand external drivers that
return no requirements. - Add positive and negative tests using a fake external driver.
- Document the external-driver authorization boundary and examples.
Alternatives Considered
- Keep the built-in driver-name allowlist permanently. This is safe but makes
the common protocol unusable for external runtimes that need host
reachability. - Trust any connected compute driver. This conflates access to the driver
control channel with authority to expose host sockets. - Let external drivers create their own host listener or forwarding process.
This avoids gateway configuration but fragments authorization, lifecycle,
observability, and callback-only API enforcement. - Expand #2538 to cover listener capabilities. That issue concerns the
gateway-owned callback endpoint and old-driver migration; operator-granted
host-bind authority is a separate security and configuration decision.
Agent Investigation
- Reviewed #2215, which requires the semantic callback contract to work for
external drivers and identifies listener negotiation as a separately
authorized capability. - Reviewed #2538, which tracks callback endpoint capability negotiation and
migration for old and external drivers, but does not define operator-granted
listener authority. - Reviewed #2492. Its gateway validation currently authorizes exact listener
requirements only for Docker and Podman, and semantic default-route or
loopback requirements only for Podman. - Searched open and closed issues for an external-driver listener capability
or authorization issue. No dedicated follow-up was found.
Checklist
- I have reviewed existing issues and architecture documentation.
- This proposal keeps endpoint identity, API exposure, and listener
reachability as separate authority layers.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing #2492's gateway validation and the related designs in #2215 and #2538. Define the operator configuration and protocol relationship, then use positive and negative fake external-driver tests to verify default denial, selector constraints, legacy responses, diagnostics, and gateway-owned binding and routing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, networking, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100