Problem statement
Implement the edge router that sits in front of two backing services: every call is routed by its path prefix over the network, and each client is held to its own allowance.
Requirements
ClientRateLimiter
tryAcquire(String clientId)
- Count the calls made for each client id on its own and answer whether that client may be served right now
- Allow the first gateway.rate-limit calls a client makes inside one window and refuse every further call in the same window. The allowance is read from configuration, never fixed in code
- Calls from one client can arrive at the same moment: exactly gateway.rate-limit of them are allowed through, the rest are refused
- A window opens with a client's first allowed call and runs for gateway.rate-window-ms milliseconds. Refused calls never push the end of that window further out
- The first call a client makes after its window has run out opens a fresh window and the full allowance is available again
- A refusal reports how long the caller should wait: the whole number of seconds still left in the window, rounded up, and never below 1
GatewayController
route(HttpServletRequest request)
- Answer GET /api/** by handing the request to one of the backing services and replying 200 OK with the answer that service gave, exactly as it came back
- Identify the caller from the X-Client-Id request header. A request that carries no such header, or a blank one, is answered with 400 and the message "X-Client-Id header is required", reaches no backing service, and is not counted against anybody's allowance
- Check every identified caller against its allowance before doing anything else with the request. A caller that is over its allowance is answered with 429 and the message "Rate limit exceeded", reaches no backing service, and the answer carries a Retry-After header holding the seconds the limiter reported
- Read the first path segment after /api/ as the route prefix and everything after it as the remaining path
- Look the prefix up in the gateway.routes map. The value found there is the base path of a backing service on this same server: reach that service over HTTP at its base path followed by the remaining path, and reply with what it answered. A request that carries no remaining path reaches the base path itself
- Answer a prefix the map does not know with 404 and the message "No route for path: /api/" followed by the requested prefix. Nothing is handed to a backing service, but the request still counts against the caller's allowance
- Count every /api/** request a caller makes against the same allowance, whichever prefix it names
- Keep callers apart: one client using up its allowance leaves every other client fully served inside the same window
Provided backing services and support
- Both backing services run inside this same application: GET /peers/catalog/** and GET /peers/orders/** answer with the service name and the path they were asked for, and write every inbound call they receive to the provided PeerCallLog
- GatewayRoutes holds the prefix to base path map read from the gateway.routes properties; LocalServerAddress reports the base URL this server is listening on
- PeerResponse, RateDecision, the error types and the error handler are provided; the shipped configuration registers the two prefixes and allows every client 60 calls a minute
Sample Requests & Responses
Expand to view details on sample requests and responses.
GET /api/catalog/items/42
Response (200 OK):
{
"service": "catalog",
"path": "items/42"
}
GET /api/orders/7/lines
Response (200 OK):
{
"service": "orders",
"path": "7/lines"
}
GET /api/reports/monthly
Response (404 Not Found):
{
"error": "No route for path: /api/reports",
"timestamp": "2026-08-11T09:56:15.146941Z",
"path": "/api/reports/monthly"
}
GET /api/catalog/items/42 without a client id
Response (400 Bad Request):
{
"error": "X-Client-Id header is required",
"timestamp": "2026-08-11T09:56:15.199932Z",
"path": "/api/catalog/items/42"
}
GET /api/catalog/items/1 once the caller is over its allowance
Response (429 Too Many Requests):
HTTP/1.1 429
Retry-After: 58
Content-Type: application/json
{
"error": "Rate limit exceeded",
"timestamp": "2026-08-11T09:56:17.466634Z",
"path": "/api/catalog/items/1"
}
GET /peers/catalog/items/42 (a provided backing service, reachable directly)
Response (200 OK):
{
"service": "catalog",
"path": "items/42"
}
