Kipchak has two new middlewares, both part of Kipchak Enterprise and both listed on the public roadmap. The Policy middleware decides what each caller may do. The Circuit Breaker middleware protects an API when a service it depends on stops answering.
Authorisation policies
Kipchak’s authentication middlewares establish who a request is from. Deciding what that caller may do has so far been left to each controller, which means every route must remember to check, and a route that does not is open to any authenticated caller. The Policy middleware moves that decision into one configuration file.
- Roles and permissions (RBAC). Roles are read from the verified token, including Keycloak’s nested roles and
identity provider groups mapped to roles, or assigned to the clients that Consumer Identity
names, so that clients using API keys or signed requests have roles as well. Roles inherit from one another and
grant permissions such as
orders:refund. OAuth scopes can act as permissions directly. - Attribute conditions (ABAC). A rule can compare the caller, the route’s arguments, the request and the time: for example, a caller may only reach the data of their own tenant, or an administrative route may only be used from the internal network.
- Open Policy Agent. A rule can hand its decision to Open Policy Agent through the existing OPA driver, for organisations that keep their policies outside the API.
- Denied by default. A request that no rule covers is refused, so a new route is closed until a rule opens it.
- Checks in code. Some decisions depend on what a route loads, such as whether an order belongs to the customer
asking for it.
Policy::authorise()applies the same rules and conditions inside a controller.
Rules are checked at the point where each route runs, after every middleware, so authentication attached to a single route has already verified the token. Every denial is logged with its reason, and with the Audit Log middleware the audit record of a denied request names the verified caller and the rule that refused it.
In worker-mode testing on the Kipchak Enterprise runtime image, with the Enterprise JWT middleware, the Audit Log and Open Policy Agent, 30,000 concurrent requests from seven kinds of caller each received the status the policy defined for them, at about 4,000 requests a second. No request was evaluated with another caller’s identity, and memory use remained constant.
composer require kipchak/middleware-policy
The Policy documentation describes rules, conditions and the Open Policy Agent input.
Circuit breakers
When a service that an API calls stops answering, every request that depends on it waits for the full timeout. Workers fill with requests that are only waiting, the API slows down for every caller, and the failing service receives a constant stream of retries. A circuit breaker detects the failures, stops calling the service for a period, and answers immediately instead. It then allows a single call through to establish whether the service has recovered.
- Every HTTP call, without code changes. A breaker guards the hosts named in its configuration. Every request to them made through the HTTP driver passes through it, including the requests made by the OPA, Vault, ClickHouse and OAuth 2 Token drivers.
- Shared by the fleet. With Valkey, every worker on every host shares each breaker. The fleet opens it together, and one worker, on any host, makes the trial call.
- Familiar failures. A call refused by an open breaker fails as a connection error, so existing error handling applies: the OPA driver reports Open Policy Agent as unreachable, and the Vault driver reports Vault as unavailable.
- Routes and other calls. A route can be answered with 503 and a
Retry-Afterheader while a service it needs is unavailable, and any other call, such as a database query or a third-party SDK, can be guarded in code. - No new point of failure. If Valkey cannot be reached, each worker keeps its own breakers until Valkey returns.
A breaker opens when enough of the calls in a recent window have failed, or when a number of calls in a row have failed. The second condition is needed for busy services: in testing, an API serving 3,400 requests a second never reached a 50% failure rate during a 12-second outage, because its window still held the successes from before the outage. Three failures in a row opened the breaker within a second.
In that test, two hosts shared one Valkey server and called Open Policy Agent through the Policy middleware. When Open Policy Agent was paused, the hosts went from serving four requests a second, each waiting two seconds, to answering every request in about 11 milliseconds. One trial call reached Open Policy Agent every three seconds, then every six, and the first trial after it returned closed the breaker on both hosts. With Valkey stopped instead, every request continued to succeed.
composer require kipchak/middleware-circuit-breaker
The Circuit Breaker documentation describes the breaker settings, the states and how the breakers are stored in Valkey.
Related improvements
Two existing packages were updated for these middlewares and released at the same time.
The HTTP driver, version 2.15, accepts Guzzle middleware that applies to every request made through it. The Circuit Breaker middleware uses this to reach the requests of every HTTP-based driver. Nothing changes for an API until such middleware is registered.
The Audit Log middleware, version 1.2, now records routes that are written as request handler objects in the same way as other routes. The Policy middleware applies to those routes as well, and requires version 1.2 when the Audit Log is installed.