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.

[elezar]

From my perspective, it still seems as if what we're implementing in both cases are hooks (although maybe that's just tainted by me coming from the container world). That is to say that we're using hooks -- operations performed at specific points in some processing pipeline -- to provide an extension point for core functionality. The terms "interceptor" and "middleware" seem to come from their initial application area. In the case of the Gateway it is assumed that we will always trigger the operations around RPC methods, whereas it could be reasonable to extend this to other well-know phases in the gateway lifecycle (startup, shutdown, driver discovery?) some of which may have equivalents in the sandbox. For the sanbox, the choice of middleware is informed by the first integration point being checking or modifying HTTP requests even though the protocol for the hook is still gRPC.

One question I would like to pose is whether it would be feasible for a user to deploy a single entity that serves both Gateway Interceptor as well a Sandbox Middleware implementations? What would we call this service?

With all this said, I don't want to block on naming as long as we close the gap between the internals. From your comments above it seems as if that's already being discussed:

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

I think the list you provide here looks good in terms of calling out the common properties of the two extension points that are being implemented.

Then on:

Interceptors and Middleware are both ordered.

Yes, this makes sense too. Should we go further and say that there ordering is determined in the same way? For example, for the propsal here we include an order flag as well as tie-breaking rules for determinism, wherease the middleware uses a mixture of an explicit list per policy as well as implicit ordering for "global" middleware.

[drew]

One question I would like to pose is whether it would be feasible for a user to deploy a single entity that serves both Gateway Interceptor as well a Sandbox Middleware implementations? What would we call this service?

Yea, this is really interesting and should be possible today. This should work with Drivers as well. I don't think we (OpenShell) would call it anything specific. A user would call it something specific to the use case they are building towards. Eg my-openshell-governance-layer. That service would implement both gateway interceptors and supervisor middleware.

[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!