Adding a System-Level Policy

[O-sura]

Problem

This requirement emerged during the implementation of the API analytics feature, specifically for AI and MCP analytics use cases.

AI analytics requires access to metadata such as:

- Vendor Name and Version
- Vendor Model
- Token usage details

For MCP analytics, it requires access to metadata such as:

Request attributes
- jsonRpcMethod
- capability
- capabilityName
- clientInfo
  - requestedProtocolVersion
  - name
  - version

Response attributes
- isError
- errorCode

In the current gateway behavior, when an API is deployed without any policies attached, the policy engine does not provide a way to intercept requests or responses. As a result, extracting the required metadata is not possible unless a policy is explicitly attached, which is not appropriate for system-level concerns.

Beyond the current analytics use case, similar interception capabilities may be required as new platform features are introduced in the future. These requirements may arise during feature implementation and should be supported without requiring API developers to attach policies or modify their API configurations.

Proposed Approach

Introduce a system-managed interception mechanism (system logic / system policy).

Key characteristics:

• Fully managed by the platform.
• Automatically attached by the policy engine.
• Not exposed in the Policy Hub.
• Not configurable or visible to API developers.

Capabilities:

• Intercept both request and response flows.
• Access headers, bodies, and contextual metadata.
• Enable internal services to extract required information reliably.

[O-sura]

We initially explored implementing system policies directly inside the policy-engine (compiled in via system policy manifests and enforced at the engine layer), but that approach had several limitations and complexities when complying with the current architecture. Based on those findings, we’ve now moved the system policy logic into the gateway-controller, where policies are injected into the derived policy chains before they are sent to the policy-engine.

New approach (gateway-controller driven):

• System policies are injected in the gateway-controller when building stored policy config routes, so they are part of the same policy chain as user-defined policies.
• Whether a system policy is applied is decided by the gateway-controller config (e.g., analytics.enabled), instead of being hardwired.
• Adding a new system policy now only requires updating the controller’s default system policies list and having the corresponding policy implementation available in the policy-engine binary.

[O-sura]

This is completed. Closing the discussion.