rfc-0010: gateway interceptors

[drew]

Note

The RFC is open for feedback.

Summary

Adds RFC-0010 for Gateway Interceptors, a proposed gateway extension system for deployment-specific business logic around OpenShell gateway API operations.

Operators and external integrators need a flexible way to customize gateway API behavior to fit their own requirements — for example, enforcing tenancy, quotas, naming conventions, or policy authority. Today any such customization has to be hardcoded into gateway handlers or pushed into drivers, which mixes responsibilities and does not scale to deployment-specific requirements.

This RFC proposes a first-class extension system that lets external services observe, modify, validate, reject, or audit gateway operations at well-defined phases. We call these Gateway Interceptors.

Related to #1919

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[elezar]

The model seems similar to the middleware model that @pimlock is proposing in #1733. Is there some reasonable common name that could be used for both that signify intent (with qualifiers for which part of the system they are applied to)?

[drew]

Yea, good callout. I spoke with @pimlock about this early on and we felt the APIs and semantics were different enough that it was worth disambiguating and keeping them separate.

Roughly our extension points are now

• Drivers - provide entire implementations for the platform and infra layer.
• Gateway Interceptors - add additional business logic to the control plane
• Supervisor Middleware - extends the data plane and agent sandboxes

This seems ok to me, but I'll let other folks chime in as well.

[drew]

Had a followup discussion w/ @pimlock.

We agreed the high level names (interceptor and middleware) are still ok to be different because the API and mechanics of these extension points are different (still up for debate if others have strong opinions).

Where we want to align is on plumbing side of things. Interceptors and middleware should share mechanics for

• Exposing endpoints and auth (grpc, uds, mtls, bearer tokens)
• The concept of Operation Phases. The phases themselves will be different between the system. But the concept of hooking into specific phases of a request remains the same. Eg
  • Interceptor: method=CreateSandbox phase=pre_request
  • Middleware: method=HttpRequest phase=pre_credentials
• Align on “Evaluation” and “Result” mechanics. Interceptors and Middleware are run with an Evaluate method and return a Result. Method signature and message bodies are different.
• Align on failure policy mechanics, on_error: fail_closed|fail_open|ignore.
• Everything is observable through OCSF with relevant details include in the payload. We should build a help crate for this. Also lines up with the "Activity" idea from multi-player use cases #1977.
• Interceptors and Middleware are both ordered.

Areas where conventions might diverge

• Interceptors register against rpc method strings (eg CreateSandbox) that are not part of the Interceptor API itself. Middleware exposes named hooks that are part of the proto contract itself (eg HttpRequest).
• Middleware is selected per sandbox via the API at runtime (interceptors could enforce middleware configuration) while Interceptors are selected for the gateway at deploy time by operators on the gateway toml config.

We should also try and align this with drivers and any other extension point exposed over gRPC. Maybe build a package similar to https://github.com/hashicorp/go-plugin that handles all these common conventions on behalf of the integrator.

[ddurst-nvidia]

Thanks for updating the RFC, having a "nameable" GatewayInterceptor helps on readability, and reduces a lot of ambiguity I was seeing with "Interceptor."

I misspoke and got pulled into the weeds of the implementation branch. We should define a specific service ServiceName { rpc...} here, so the contract is fully named and can be referred to consistently in the RFC.

[ddurst-nvidia]

GatewayInterceptor is a huge help, thanks!

[ddurst-nvidia]

I can't quite tell from the text, but it seems like either the operation_input is populated or rpc_request depending on phase? If so, a oneof might be more appropriate.

[drew]

Yea, good call. Made this a oneof. Also renamed

• operation_input -> proposed_operation
• existing_state -> current_state
• rpc_request -> api_request

I still don't think this is quite right. I'll keep thinking on this and see how the prototype looks before committing to final names here.