Light, fluffy, and always free - The AWS Local Emulator alternative
feat(apigateway): implement GetUsage (#3561)
Ovidiu (Ovi)f99e5079161a
diff --git a/docs/services/api-gateway.md b/docs/services/api-gateway.mdindex 8dc9ec86f0..23dee68bbf 100644--- a/docs/services/api-gateway.md+++ b/docs/services/api-gateway.md@@ -53,7 +53,7 @@ duplicate override IDs.| **Stages** | CreateStage, GetStage, GetStages, UpdateStage, DeleteStage || **Authorizers** | CreateAuthorizer, GetAuthorizer, GetAuthorizers, UpdateAuthorizer, DeleteAuthorizer || **API Keys** | CreateApiKey, ImportApiKeys, GetApiKey, GetApiKeys, UpdateApiKey, DeleteApiKey |-| **Usage Plans** | CreateUsagePlan, GetUsagePlan, GetUsagePlans, UpdateUsagePlan, DeleteUsagePlan |+| **Usage Plans** | CreateUsagePlan, GetUsagePlan, GetUsagePlans, UpdateUsagePlan, DeleteUsagePlan, GetUsage || **Usage Plan Keys** | CreateUsagePlanKey, GetUsagePlanKey, GetUsagePlanKeys, DeleteUsagePlanKey || **Request Validators** | CreateRequestValidator, GetRequestValidator, GetRequestValidators, UpdateRequestValidator, DeleteRequestValidator || **Gateway Responses** | PutGatewayResponse, GetGatewayResponse, GetGatewayResponses, UpdateGatewayResponse, DeleteGatewayResponse |@@ -303,6 +303,32 @@ aws apigateway create-deployment \curl http://localhost:4566/restapis/$API_ID/dev/_user_request_/users```+### Usage reporting++`GetUsage` returns the real response envelope: a `values` map of API key id to one `[used, remaining]`+pair per day of the inclusive range, alongside `usagePlanId`, `startDate` and `endDate`. The second+element of each pair is the quota limit minus cumulative use on real API Gateway, not the quota+itself.++The operation pages over the API key entries with `limit` and `position`, defaulting to 25 keys a+page and emitting `position` only when another page exists.++Request acceptance and response page size are separate things here. Probed against real API+Gateway, every `limit` from 500 up to `Integer.MAX_VALUE` is accepted without error, so none is+rejected. That does not show the service ever returning more than 500 entries in one page, and the+documented contract caps a page at 500, so a larger `limit` is honoured as a request while the page+returned stays capped at 500.++The lower bound is a deliberate divergence: real API Gateway answers `limit=0` and `limit=-1` with+an `InternalFailure`, which is a fault rather than a contract, so a page size below one is rejected+as a `BadRequestException` instead of reproducing a 500.++**Both numbers are always zero.** Nothing meters requests per API key, and a usage plan stores no+quota to subtract from, so there is no limit to report against. Throttle settings are likewise+accepted and stored but never enforced. Storing a quota on the usage plan and counting on the+execute path are the two pieces still missing; a caller that sums the used counts gets zero, which+is what it already got before the action existed, without having to special-case a missing endpoint.+### Usage Plan Tags and Custom IDsUsage plans accept arbitrary tags, and the same reserved `floci:override-id` tag used fordiff --git a/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayController.java b/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayController.javaindex b8a2b7b3d3..d39b2161d5 100644--- a/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayController.java+++ b/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayController.java@@ -847,6 +847,57 @@ public class ApiGatewayController {}}+ /**+ * {@code GetUsage}. Returns the real response envelope with an entry per attached key and one+ * pair per day of the requested range.+ *+ * <p>Paginated over the API key entries with {@code limit} and {@code position}, defaulting to+ * 25 keys a page.+ *+ * <p>Each pair is {@code [used, remaining]}, not {@code [used, quota]}: measured against real+ * API Gateway, the second element is the quota limit minus the cumulative use so far in the+ * period. Both elements are {@code 0} here because the emulator neither meters requests per API+ * key nor stores a quota on a usage plan. Once a quota lives on {@code UsagePlan} and the+ * execute path counts per key, this method is where both feed in; until then a caller that sums+ * the used counts gets the same zero it already gets from an unsupported action, without having+ * to special-case a missing endpoint.+ */+ @GET+ @Path("/usageplans/{usagePlanId}/usage")+ public Response getUsage(@Context HttpHeaders headers,+ @PathParam("usagePlanId") String usagePlanId,+ @QueryParam("startDate") String startDate,+ @QueryParam("endDate") String endDate,+ @QueryParam("keyId") String keyId,+ @QueryParam("limit") Integer limit,+ @QueryParam("position") String position) {+ String region = regionResolver.resolveRegion(headers);+ ApiGatewayService.UsageReport report =+ service.getUsage(region, usagePlanId, startDate, endDate, keyId, limit, position);++ ObjectNode root = objectMapper.createObjectNode();+ // The wire key is "values", not "items": the Usage shape models this map with+ // locationName "values", and "items" is only the SDK-side member name. A body keyed+ // "items" parses to nothing in a real client.+ ObjectNode values = root.putObject("values");+ report.items().forEach((apiKeyId, perDay) -> {+ ArrayNode days = values.putArray(apiKeyId);+ for (long[] pair : perDay) {+ ArrayNode entry = days.addArray();+ entry.add(pair[0]);+ entry.add(pair[1]);+ }+ });+ root.put("usagePlanId", report.usagePlanId());+ root.put("startDate", report.startDate());+ root.put("endDate", report.endDate());+ // Only present when another page exists, matching the terminal page captured from AWS.+ if (report.position() != null) {+ root.put("position", report.position());+ }+ return Response.ok(root.toString()).type(MediaType.APPLICATION_JSON).build();+ }+@GET@Path("/usageplans/{usagePlanId}/keys")public Response getUsagePlanKeys(@Context HttpHeaders headers, @PathParam("usagePlanId") String usagePlanId) {diff --git a/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayService.java b/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayService.javaindex 3dc3b1c509..528eca9c52 100644--- a/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayService.java+++ b/src/main/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayService.java@@ -1,6 +1,10 @@package io.github.hectorvent.floci.services.apigateway;+import java.time.LocalDate;+import java.time.format.DateTimeParseException;+import java.time.temporal.ChronoUnit;import java.util.ArrayList;+import java.util.Comparator;import java.util.HashMap;import java.util.HashSet;import java.util.LinkedHashMap;@@ -56,6 +60,15 @@ import jakarta.inject.Inject;@ApplicationScopedpublic class ApiGatewayService {+ /** Documented default page size for GetUsage. */+ private static final int DEFAULT_USAGE_LIMIT = 25;+ /**+ * Documented maximum results per page. A larger {@code limit} is accepted, as real API Gateway+ * accepts one, but the page returned is still capped here.+ */+ private static final int MAX_USAGE_PAGE_SIZE = 500;++private static final Logger LOG = Logger.getLogger(ApiGatewayService.class);private final StorageBackend<String, RestApi> apiStore;@@ -1266,6 +1279,115 @@ public class ApiGatewayService {.orElseThrow(() -> new AwsException("NotFoundException", "Usage Plan Key not found", 404));}+ /**+ * Builds a {@code GetUsage} report for a usage plan.+ *+ * <p>Shape measured against real API Gateway: the envelope carries {@code usagePlanId},+ * {@code startDate}, {@code endDate} and an {@code items} map of API key id to one+ * {@code [used, remaining]} pair per day of the inclusive range. {@code position} is absent+ * when there is no further page, which is what stops a caller's pagination loop.+ *+ * <p><strong>Both numbers are zero.</strong> Nothing counts requests per API key, and a+ * {@link UsagePlan} carries no quota, so there is no limit to subtract from. Storing a quota on+ * the usage plan and counting on the execute path are the two pieces still missing; this method+ * is where they would surface.+ */+ public UsageReport getUsage(String region, String usagePlanId, String startDate, String endDate,+ String keyId, Integer limit, String position) {+ // Resolving the plan first gives the same NotFoundException an unknown id gets on AWS.+ getUsagePlan(region, usagePlanId);++ LocalDate start = parseUsageDate(startDate, "startDate");+ LocalDate end = parseUsageDate(endDate, "endDate");+ if (end.isBefore(start)) {+ throw new AwsException("BadRequestException", "Usage end date must be after start date", 400);+ }+ int days = (int) ChronoUnit.DAYS.between(start, end) + 1;+ int pageSize = resolveUsageLimit(limit);++ List<UsagePlanKey> keys = getUsagePlanKeys(region, usagePlanId).stream()+ .filter(key -> keyId == null || keyId.isBlank() || keyId.equals(key.getId()))+ .sorted(Comparator.comparing(UsagePlanKey::getId))+ .toList();++ // The page token is the last key id already returned, so a page resumes after it rather+ // than at a positional offset a concurrent key attachment could shift. Measured: an+ // unrecognised token is a BadRequestException, not an empty page.+ int from = 0;+ if (position != null && !position.isBlank()) {+ int previous = -1;+ for (int i = 0; i < keys.size(); i++) {+ if (position.equals(keys.get(i).getId())) {+ previous = i;+ break;+ }+ }+ if (previous < 0) {+ throw new AwsException("BadRequestException", "Invalid position parameter", 400);+ }+ from = previous + 1;+ }++ List<UsagePlanKey> page = keys.subList(Math.min(from, keys.size()),+ Math.min(from + pageSize, keys.size()));+ boolean more = from + pageSize < keys.size();++ Map<String, List<long[]>> items = new LinkedHashMap<>();+ for (UsagePlanKey key : page) {+ List<long[]> perDay = new ArrayList<>();+ for (int day = 0; day < days; day++) {+ // [used, remaining]: nothing is metered, and no quota is stored to subtract from.+ perDay.add(new long[] {0L, 0L});+ }+ items.put(key.getId(), perDay);+ }+ // A token only when another page exists; its absence is what ends a caller's loop.+ String next = more && !page.isEmpty() ? page.get(page.size() - 1).getId() : null;+ return new UsageReport(usagePlanId, start.toString(), end.toString(), items, next);+ }++ /**+ * Resolves the effective page size, which is not the same thing as accepting the request.+ *+ * <p>Request acceptance and response page size are separate. Probed against real API Gateway,+ * every {@code limit} from 500 up to {@link Integer#MAX_VALUE} is accepted without error, so+ * none is rejected here either. What that probe does <em>not</em> establish is that the service+ * ever returns more than 500 entries in one page, and the documented contract says 500 is the+ * maximum number of results per page. The effective page is therefore capped at 500 until a+ * real result with more than 500 keys shows otherwise.+ *+ * <p>The lower bound is a deliberate divergence: real API Gateway answers {@code limit=0} and+ * {@code limit=-1} with an {@code InternalFailure}, which is a fault rather than a contract, so+ * a page size below one is rejected as a bad request instead of reproducing a 500.+ */+ static int resolveUsageLimit(Integer limit) {+ if (limit == null) {+ return DEFAULT_USAGE_LIMIT;+ }+ if (limit < 1) {+ throw new AwsException("BadRequestException", "Invalid limit parameter", 400);+ }+ return Math.min(limit, MAX_USAGE_PAGE_SIZE);+ }++ /**+ * One {@code GetUsage} report: {@code items} maps an API key id to its per-day pairs, and+ * {@code position} is the continuation token, absent on the terminal page.+ */+ public record UsageReport(String usagePlanId, String startDate, String endDate,+ Map<String, List<long[]>> items, String position) {}++ private static LocalDate parseUsageDate(String value, String field) {+ if (value == null || value.isBlank()) {+ throw new AwsException("BadRequestException", field + " is required", 400);+ }+ try {+ return LocalDate.parse(value);+ } catch (DateTimeParseException e) {+ throw new AwsException("BadRequestException", field + " must be a date of the form YYYY-MM-DD", 400);+ }+ }+public List<UsagePlanKey> getUsagePlanKeys(String region, String usagePlanId) {String prefix = region + "::" + usagePlanId + "::";return usagePlanKeyStore.scan(k -> k.startsWith(prefix));diff --git a/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayGetUsageIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayGetUsageIntegrationTest.javanew file mode 100644index 0000000000..475278ac27--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayGetUsageIntegrationTest.java@@ -0,0 +1,223 @@+package io.github.hectorvent.floci.services.apigateway;++import io.quarkus.test.junit.QuarkusTest;+import io.restassured.http.ContentType;+import org.junit.jupiter.api.Test;++import static io.restassured.RestAssured.given;+import static org.hamcrest.Matchers.aMapWithSize;+import static org.hamcrest.Matchers.anEmptyMap;+import static org.hamcrest.Matchers.containsString;+import static org.hamcrest.Matchers.equalTo;+import static org.hamcrest.Matchers.hasSize;+import static org.hamcrest.Matchers.nullValue;+import static org.hamcrest.Matchers.notNullValue;++/**+ * {@code GetUsage}.+ *+ * <p>Envelope captured from real API Gateway: {@code values} maps an API key id to one pair per day+ * of the inclusive range, alongside {@code usagePlanId}, {@code startDate} and {@code endDate}, with+ * no {@code position} when there is no further page.+ *+ * <p>Each pair is {@code [used, remaining]}, not {@code [used, quota]}: on real API Gateway the+ * second element is the quota limit minus cumulative use. Both are zero here because nothing meters+ * requests per key and a usage plan stores no quota.+ */+@QuarkusTest+class ApiGatewayGetUsageIntegrationTest {++ private static String createUsagePlan(String name) {+ return given().contentType(ContentType.JSON)+ .body("{\"name\":\"" + name + "\"}")+ .when().post("/usageplans")+ .then().statusCode(201)+ .extract().path("id");+ }++ private static String createApiKeyOnPlan(String planId, String keyName) {+ String keyId = given().contentType(ContentType.JSON)+ .body("{\"name\":\"" + keyName + "\",\"enabled\":true}")+ .when().post("/apikeys")+ .then().statusCode(201)+ .extract().path("id");++ given().contentType(ContentType.JSON)+ .body("{\"keyId\":\"" + keyId + "\",\"keyType\":\"API_KEY\"}")+ .when().post("/usageplans/" + planId + "/keys")+ .then().statusCode(201);+ return keyId;+ }++ @Test+ void aPlanWithNoKeysReportsAnEmptyValuesMap() {+ String planId = createUsagePlan("usage-empty");++ given().when().get("/usageplans/" + planId + "/usage?startDate=2026-09-01&endDate=2026-09-13")+ .then().statusCode(200)+ .body("usagePlanId", equalTo(planId))+ .body("startDate", equalTo("2026-09-01"))+ .body("endDate", equalTo("2026-09-13"))+ .body("values", anEmptyMap());+ }++ // API key ids are random and can start with a digit, which a dotted GPath parses as a number.+ // Every lookup into values therefore uses bracket notation.+ @Test+ void eachKeyGetsOnePairPerDayOfTheInclusiveRange() {+ String planId = createUsagePlan("usage-range");+ String keyId = createApiKeyOnPlan(planId, "usage-range-key");++ given().when().get("/usageplans/" + planId + "/usage?startDate=2026-09-01&endDate=2026-09-13")+ .then().statusCode(200)+ // 1 to 13 September inclusive is 13 days, matching real API Gateway.+ .body("values['" + keyId + "']", hasSize(13))+ .body("values['" + keyId + "'][0]", hasSize(2))+ .body("values['" + keyId + "'][0][0]", equalTo(0))+ .body("values['" + keyId + "'][0][1]", equalTo(0));+ }++ @Test+ void aSingleDayRangeIsOnePair() {+ String planId = createUsagePlan("usage-oneday");+ String keyId = createApiKeyOnPlan(planId, "usage-oneday-key");++ given().when().get("/usageplans/" + planId + "/usage?startDate=2026-09-05&endDate=2026-09-05")+ .then().statusCode(200)+ .body("values['" + keyId + "']", hasSize(1));+ }++ @Test+ void theKeyIdFilterNarrowsToOneKey() {+ String planId = createUsagePlan("usage-filter");+ String first = createApiKeyOnPlan(planId, "usage-filter-a");+ createApiKeyOnPlan(planId, "usage-filter-b");++ given().when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&keyId=" + first)+ .then().statusCode(200)+ .body("values", aMapWithSize(1))+ .body("values['" + first + "']", hasSize(2));+ }++ @Test+ void anUnknownUsagePlanIsNotFound() {+ given().when().get("/usageplans/nosuchplan/usage?startDate=2026-09-01&endDate=2026-09-13")+ .then().statusCode(404);+ }++ @Test+ void anEndDateBeforeTheStartDateIsRejected() {+ String planId = createUsagePlan("usage-reversed");++ given().when().get("/usageplans/" + planId + "/usage?startDate=2026-09-13&endDate=2026-09-01")+ .then().statusCode(400)+ .body(containsString("Usage end date must be after start date"));+ }++ @Test+ void aMissingStartDateIsRejected() {+ String planId = createUsagePlan("usage-nodate");++ given().when().get("/usageplans/" + planId + "/usage?endDate=2026-09-13")+ .then().statusCode(400)+ .body(containsString("startDate"));+ }++ @Test+ void aMalformedDateIsRejected() {+ String planId = createUsagePlan("usage-baddate");++ given().when().get("/usageplans/" + planId + "/usage?startDate=13-09-2026&endDate=2026-09-13")+ .then().statusCode(400)+ .body(containsString("YYYY-MM-DD"));+ }++ @Test+ void pagingCrossesAKeyBoundaryAndRoundTripsThePosition() {+ String planId = createUsagePlan("usage-paged");+ for (int i = 0; i < 3; i++) {+ createApiKeyOnPlan(planId, "usage-paged-" + i);+ }++ String position = given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&limit=2")+ .then().statusCode(200)+ .body("values", aMapWithSize(2))+ .body("position", notNullValue())+ .extract().path("position");++ given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&limit=2&position=" + position)+ .then().statusCode(200)+ .body("values", aMapWithSize(1))+ // No token on the terminal page, matching the capture from real AWS.+ .body("position", nullValue());+ }++ @Test+ void aSinglePageCarriesNoPosition() {+ String planId = createUsagePlan("usage-onepage");+ createApiKeyOnPlan(planId, "usage-onepage-key");++ given()+ .when().get("/usageplans/" + planId + "/usage?startDate=2026-09-01&endDate=2026-09-02")+ .then().statusCode(200)+ .body("values", aMapWithSize(1))+ .body("position", nullValue());+ }++ @Test+ void anUnrecognisedPositionIsRejected() {+ String planId = createUsagePlan("usage-badpos");+ createApiKeyOnPlan(planId, "usage-badpos-key");++ given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&position=nonsense")+ .then().statusCode(400)+ .body(containsString("Invalid position parameter"));+ }++ @Test+ void aLimitBelowOneIsRejected() {+ String planId = createUsagePlan("usage-zerolimit");++ given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&limit=0")+ .then().statusCode(400)+ .body(containsString("Invalid limit parameter"));+ }++ @Test+ void aLimitAboveTheDocumentedMaximumIsAccepted() {+ String planId = createUsagePlan("usage-biglimit");+ createApiKeyOnPlan(planId, "usage-biglimit-key");++ // Probed against real API Gateway: every value from 500 up to Integer.MAX_VALUE is accepted+ // without error, so the documented maximum of 500 is not a rejection boundary.+ for (String limit : new String[] {"500", "501", "100000", "2147483647"}) {+ given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&limit=" + limit)+ .then().statusCode(200)+ .body("values", aMapWithSize(1));+ }+ }++ @Test+ void aNegativeLimitIsRejected() {+ String planId = createUsagePlan("usage-neglimit");++ // Real API Gateway answers a negative limit with an InternalFailure. That is a fault, not a+ // contract, so this rejects rather than reproducing a 500.+ given()+ .when().get("/usageplans/" + planId + "/usage"+ + "?startDate=2026-09-01&endDate=2026-09-02&limit=-1")+ .then().statusCode(400)+ .body(containsString("Invalid limit parameter"));+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayUsageLimitTest.java b/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayUsageLimitTest.javanew file mode 100644index 0000000000..dac460c019--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/apigateway/ApiGatewayUsageLimitTest.java@@ -0,0 +1,46 @@+package io.github.hectorvent.floci.services.apigateway;++import io.github.hectorvent.floci.core.common.AwsException;+import org.junit.jupiter.api.Test;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertThrows;++/**+ * {@code GetUsage}'s {@code limit} separates two things that are easy to conflate: whether a+ * request is accepted, and how large a page the response may carry.+ *+ * <p>Probed against real API Gateway, every value from 500 up to {@link Integer#MAX_VALUE} is+ * accepted, so none is rejected. That probe does not show the service ever returning more than 500+ * entries in one page, and the documented contract caps a page at 500, so the effective page size+ * stays capped even though the larger request is honoured.+ */+class ApiGatewayUsageLimitTest {++ @Test+ void anAbsentLimitUsesTheDocumentedDefault() {+ assertEquals(25, ApiGatewayService.resolveUsageLimit(null));+ }++ @Test+ void aLimitWithinTheDocumentedMaximumIsUsedAsGiven() {+ assertEquals(1, ApiGatewayService.resolveUsageLimit(1));+ assertEquals(100, ApiGatewayService.resolveUsageLimit(100));+ assertEquals(500, ApiGatewayService.resolveUsageLimit(500));+ }++ @Test+ void aLimitAboveTheMaximumIsAcceptedButThePageStaysCapped() {+ // Accepted, not rejected: real API Gateway accepts these.+ // Capped, not honoured verbatim: nothing shows it returning more than 500 in one page.+ assertEquals(500, ApiGatewayService.resolveUsageLimit(501));+ assertEquals(500, ApiGatewayService.resolveUsageLimit(100_000));+ assertEquals(500, ApiGatewayService.resolveUsageLimit(Integer.MAX_VALUE));+ }++ @Test+ void aLimitBelowOneIsRejected() {+ assertThrows(AwsException.class, () -> ApiGatewayService.resolveUsageLimit(0));+ assertThrows(AwsException.class, () -> ApiGatewayService.resolveUsageLimit(-1));+ }+}