AEP 3: Policy probes (probe state of a specific policy configuration)

[msavy]

I have implemented my first version of policy probes (state inspection). I've settled on the name "policy probe", as that seems fairly common verbiage.

To keep it simple and allow incremental migration to this, I've done implemented it in a way that minimises changes and incompatibilities (hopefully no incompatibilities with existing policies).

Here's a high-level view of how it works:

• A policy that offers a probe just needs to implement the IPolicyProbe interface.
• The IPolicyProbe interface requires a method to be implemented that has params of: policy config, probe config, probe context, policy context.
  • policy config: usual policy config;
  • probe config: essentially stand-in information that the prober provides that would normally be in the request. it's a basic interface, so can be whatever they want. so, for example, in the case of IP rate limiting it can provide an IP address to probe against;
  • probe context: what the gateway knows about the policy config being probed, so contract info, api info, etc, etc.

With some simple refactoring, you can use the same code-paths as the standard policy, but instead of mutating you just return the existing state. The response is piped back to the manager, and in turn back to the client (browser or whatever).

I'd like to enhance this further soon with schemas, so that the payload can be better understood, especially for plugin policies.

Example:

    @Override
    public void probe(RateLimitingProbeConfig probeRequest, RateLimitingConfig policyConfig, ProbeContext probeContext,
         IPolicyContext context, IAsyncResultHandler<IPolicyProbeResponse> resultHandler) {
        String bucketId = bucketId(probeRequest, probeContext, policyConfig);
        IRateLimiterComponent rateLimiter = context.getComponent(IRateLimiterComponent.class);
        // Ask for rate limit, but don't actually decrement the counter.
        rateLimiter.accept(bucketId, getPeriod(policyConfig), policyConfig.getLimit(), 0, rateLimResult -> {
            RateLimitResponse remaining = rateLimResult.getResult();
            var probeResult = new RateLimitingProbeResponse()
                    .setStatus(remaining)
                    .setConfig(policyConfig);
            resultHandler.handle(AsyncResultImpl.create(probeResult));
        });
    }

Response example from gateway (arbitrary responses allowed):

{
	"config": {
		"limit": 1,
		"granularity": "Ip",
		"period": "Minute"
	},
	"status": {
		"accepted": true,
		"remaining": 1,
        "reset": 12345
	},
	"probeType": "RateLimitingProbeResponse"
}

The subsequent response from the API Manager to the client could be enriched, if that is beneficial.

---

Changes:

• New Manager API REST methods for probing policy states
• New Gateway API REST methods for probing policy states (manager calls gateway)
• New IPolicyProbe interface for policies to implement if they provide probes

This should not cause any breaking changes.

Targeting Apiman 3 beta/preview.

---

Please provide feedback!

[msavy]

This is completed and will be in Apiman 3.0.0.Final