Light, fluffy, and always free - The AWS Local Emulator alternative
fix(textract): retain async results until expiry (#3965)
Daniël van Ziel4618d633e05c
diff --git a/docs/services/textract.md b/docs/services/textract.mdindex 440307796b..91f1e74ec9 100644--- a/docs/services/textract.md+++ b/docs/services/textract.md@@ -32,7 +32,7 @@ Every block includes: `Id` (UUID), `Confidence` (99.9), `Page` (1), and a `Geome### Async job lifecycle-`Start*` operations store a job ID in memory and return it immediately. `Get*` calls with a valid job ID always return `JobStatus: SUCCEEDED`. Job IDs are not persisted across restarts. Using a `GetDocumentTextDetection` job ID in `GetDocumentAnalysis` (or vice-versa) returns `InvalidJobIdException`.+`Start*` operations store a job ID and its result in memory and return the ID immediately. `Get*` calls with a valid job ID return `JobStatus: SUCCEEDED` and the same result every time, so a result can be fetched repeatedly. A job is retained for 7 days, after which it expires and `Get*` returns `InvalidJobIdException`; expired jobs are also swept when a new job is stored. The store is capped at 10,000 jobs: once the cap is reached the oldest job is evicted first, which AWS does not do, so a job that is still inside its 7-day window can read as `InvalidJobIdException` once enough newer jobs exist. Job IDs are not persisted across restarts. Using a `GetDocumentTextDetection` job ID in `GetDocumentAnalysis` (or vice-versa) returns `InvalidJobIdException`.## Configurationdiff --git a/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.java b/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.javaindex 6df006bb05..0826873f52 100644--- a/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.java+++ b/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.java@@ -10,6 +10,12 @@ import io.github.hectorvent.floci.core.common.Resettable;import jakarta.enterprise.context.ApplicationScoped;import jakarta.inject.Inject;import jakarta.ws.rs.core.Response;+import java.time.Clock;+import java.time.Duration;+import java.time.Instant;+import java.util.Comparator;+import java.util.List;+import java.util.Map;import java.util.Optional;import java.util.UUID;import java.util.concurrent.ConcurrentHashMap;@@ -32,18 +38,29 @@ import java.util.concurrent.ConcurrentHashMap;public class TextractService implements Resettable {static final String MODEL_VERSION = "1.0";private static final String SERVICE_KEY = "textract";+ /** AWS retains asynchronous results for about 7 days; an expired job reads as an invalid job. */+ static final Duration RESULT_RETENTION = Duration.ofDays(7);+ /** Hard cap so a producer that never reads its results cannot grow the store without bound. */+ static final int MAX_RETAINED_JOBS = 10_000;private final ObjectMapper objectMapper;private final AiMockConfigLoader mockConfigLoader;- /** In-memory async job store: jobId to jobType ("TEXT_DETECTION" or "DOCUMENT_ANALYSIS"). */- private final ConcurrentHashMap<String, String> asyncJobs = new ConcurrentHashMap<>();+ private final Clock clock;+ /** In-memory async job store: jobId to the job's type, creation time, and stable result. */+ private final ConcurrentHashMap<String, AsyncJob> asyncJobs = new ConcurrentHashMap<>();@Injectpublic TextractService(ObjectMapper objectMapper, AiMockConfigLoader mockConfigLoader) {+ this(objectMapper, mockConfigLoader, Clock.systemUTC());+ }+ TextractService(ObjectMapper objectMapper, AiMockConfigLoader mockConfigLoader, Clock clock) {this.objectMapper = objectMapper;this.mockConfigLoader = mockConfigLoader;+ this.clock = clock;}public void clear() {asyncJobs.clear();}+ /** A completed async job, retained until {@link #RESULT_RETENTION} elapses. */+ record AsyncJob(String jobType, Instant createdAt, ObjectNode result) {}/*** DetectDocumentText — returns a stub PAGE + LINE + WORD block hierarchy.* Response shape: https://docs.aws.amazon.com/textract/latest/dg/API_DetectDocumentText.html@@ -80,25 +97,17 @@ public class TextractService implements Resettable {*/public Response startDocumentTextDetection() {String jobId = UUID.randomUUID().toString();- asyncJobs.put(jobId, "TEXT_DETECTION");+ storeJob(jobId, "TEXT_DETECTION", buildTextDetectionResult());ObjectNode root = objectMapper.createObjectNode();root.put("JobId", jobId);return Response.ok(root).build();}/**- * GetDocumentTextDetection — returns SUCCEEDED + stub blocks for any known JobId.+ * GetDocumentTextDetection — returns the job's stable SUCCEEDED result until it expires.* Response shape: https://docs.aws.amazon.com/textract/latest/dg/API_GetDocumentTextDetection.html*/public Response getDocumentTextDetection(String jobId) {- requireKnownJob(jobId, "TEXT_DETECTION");- ObjectNode root = objectMapper.createObjectNode();- root.put("JobStatus", "SUCCEEDED");- root.set("DocumentMetadata", buildDocumentMetadata(1));- root.set("Blocks", buildStubBlocks());- root.put("DetectDocumentTextModelVersion", MODEL_VERSION);- //after a successful job, we remove it to avoid memory growth- asyncJobs.remove(jobId);- return Response.ok(root).build();+ return Response.ok(requireJobResult(jobId, "TEXT_DETECTION")).build();}/*** StartDocumentAnalysis — enqueues a fake async job and immediately marks it SUCCEEDED.@@ -106,42 +115,76 @@ public class TextractService implements Resettable {*/public Response startDocumentAnalysis() {String jobId = UUID.randomUUID().toString();- asyncJobs.put(jobId, "DOCUMENT_ANALYSIS");+ storeJob(jobId, "DOCUMENT_ANALYSIS", buildDocumentAnalysisResult());ObjectNode root = objectMapper.createObjectNode();root.put("JobId", jobId);return Response.ok(root).build();}/**- * GetDocumentAnalysis — returns SUCCEEDED + stub blocks for any known JobId.+ * GetDocumentAnalysis — returns the job's stable SUCCEEDED result until it expires.* Response shape: https://docs.aws.amazon.com/textract/latest/dg/API_GetDocumentAnalysis.html*/public Response getDocumentAnalysis(String jobId) {- requireKnownJob(jobId, "DOCUMENT_ANALYSIS");+ return Response.ok(requireJobResult(jobId, "DOCUMENT_ANALYSIS")).build();+ }+ private ObjectNode buildTextDetectionResult() {+ ObjectNode root = objectMapper.createObjectNode();+ root.put("JobStatus", "SUCCEEDED");+ root.set("DocumentMetadata", buildDocumentMetadata(1));+ root.set("Blocks", buildStubBlocks());+ root.put("DetectDocumentTextModelVersion", MODEL_VERSION);+ return root;+ }+ private ObjectNode buildDocumentAnalysisResult() {ObjectNode root = objectMapper.createObjectNode();root.put("JobStatus", "SUCCEEDED");root.set("DocumentMetadata", buildDocumentMetadata(1));root.set("Blocks", buildStubBlocks());root.put("AnalyzeDocumentModelVersion", MODEL_VERSION);-- //after a successful job, we remove it to avoid memory growth- asyncJobs.remove(jobId);-- return Response.ok(root).build();+ return root;+ }+ private void storeJob(String jobId, String jobType, ObjectNode result) {+ sweepExpired();+ asyncJobs.put(jobId, new AsyncJob(jobType, clock.instant(), result));+ enforceCapacity();}// Private helpers- private void requireKnownJob(String jobId, String expectedType) {+ private ObjectNode requireJobResult(String jobId, String expectedType) {if (jobId == null || jobId.isBlank()) {throw new AwsException("ValidationException", "JobId is required.", 400);}- String type = asyncJobs.get(jobId);- if (type == null) {- throw new AwsException("InvalidJobIdException",- "An invalid job identifier was passed to an Amazon Textract operation.", 400);+ AsyncJob job = asyncJobs.get(jobId);+ if (job == null) {+ throw invalidJobId();}- if (!expectedType.equals(type)) {+ if (job.createdAt().isBefore(clock.instant().minus(RESULT_RETENTION))) {+ asyncJobs.remove(jobId);+ throw invalidJobId();+ }+ if (!expectedType.equals(job.jobType())) {throw new AwsException("InvalidJobIdException","Job was not started by the correct operation.", 400);}+ return job.result();+ }+ private static AwsException invalidJobId() {+ return new AwsException("InvalidJobIdException",+ "An invalid job identifier was passed to an Amazon Textract operation.", 400);+ }+ private void sweepExpired() {+ Instant cutoff = clock.instant().minus(RESULT_RETENTION);+ asyncJobs.entrySet().removeIf(entry -> entry.getValue().createdAt().isBefore(cutoff));+ }+ private void enforceCapacity() {+ int excess = asyncJobs.size() - MAX_RETAINED_JOBS;+ if (excess <= 0) {+ return;+ }+ List<Map.Entry<String, AsyncJob>> oldest = asyncJobs.entrySet().stream()+ .sorted(Map.Entry.comparingByValue(Comparator.comparing(AsyncJob::createdAt)))+ .limit(excess)+ .toList();+ oldest.forEach(entry -> asyncJobs.remove(entry.getKey(), entry.getValue()));}private ObjectNode buildDocumentMetadata(int pages) {ObjectNode meta = objectMapper.createObjectNode();diff --git a/src/test/java/io/github/hectorvent/floci/services/textract/TextractIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/textract/TextractIntegrationTest.javaindex 76d5d524ab..c05720837a 100644--- a/src/test/java/io/github/hectorvent/floci/services/textract/TextractIntegrationTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/textract/TextractIntegrationTest.java@@ -114,6 +114,40 @@ class TextractIntegrationTest {.body("Blocks", hasSize(3));}@Test+ void asyncResultCanBeReadMoreThanOnceWithStableBlocks() {+ String jobId = given()+ .contentType(CONTENT_TYPE)+ .header("X-Amz-Target", "Textract.StartDocumentTextDetection")+ .header("Authorization", AUTH_HEADER)+ .body("{\"DocumentLocation\":{\"S3Object\":{\"Bucket\":\"my-bucket\",\"Name\":\"test.pdf\"}}}")+ .when()+ .post("/")+ .then()+ .statusCode(200)+ .extract().path("JobId");+ String firstBlockId = given()+ .contentType(CONTENT_TYPE)+ .header("X-Amz-Target", "Textract.GetDocumentTextDetection")+ .header("Authorization", AUTH_HEADER)+ .body("{\"JobId\":\"" + jobId + "\"}")+ .when()+ .post("/")+ .then()+ .statusCode(200)+ .extract().path("Blocks[0].Id");+ String secondBlockId = given()+ .contentType(CONTENT_TYPE)+ .header("X-Amz-Target", "Textract.GetDocumentTextDetection")+ .header("Authorization", AUTH_HEADER)+ .body("{\"JobId\":\"" + jobId + "\"}")+ .when()+ .post("/")+ .then()+ .statusCode(200)+ .extract().path("Blocks[0].Id");+ assertThat(secondBlockId, equalTo(firstBlockId));+ }+ @Testvoid getDocumentTextDetection_unknownJobId_returns400() {given().contentType(CONTENT_TYPE)diff --git a/src/test/java/io/github/hectorvent/floci/services/textract/TextractServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/textract/TextractServiceTest.javanew file mode 100644index 0000000000..703e7e62de--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/textract/TextractServiceTest.java@@ -0,0 +1,98 @@+package io.github.hectorvent.floci.services.textract;++import com.fasterxml.jackson.databind.ObjectMapper;+import com.fasterxml.jackson.databind.node.ObjectNode;+import io.github.hectorvent.floci.core.common.AiMockConfigLoader;+import io.github.hectorvent.floci.core.common.AwsException;+import org.junit.jupiter.api.Test;++import java.time.Clock;+import java.time.Duration;+import java.time.Instant;+import java.time.ZoneId;+import java.time.ZoneOffset;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertThrows;+import static org.mockito.Mockito.mock;++class TextractServiceTest {++ private static final Instant START = Instant.parse("2026-01-01T00:00:00Z");++ @Test+ void repeatedGetReturnsTheSameStableResult() {+ TextractService service = serviceAt(START);+ String jobId = startJob(service, "TEXT_DETECTION");++ ObjectNode first = (ObjectNode) service.getDocumentTextDetection(jobId).getEntity();+ ObjectNode second = (ObjectNode) service.getDocumentTextDetection(jobId).getEntity();++ assertEquals(first, second);+ assertEquals("SUCCEEDED", second.get("JobStatus").asText());+ }++ @Test+ void getBeforeExpiryStillReturnsTheResult() {+ MutableClock clock = new MutableClock(START);+ TextractService service = new TextractService(new ObjectMapper(), mock(AiMockConfigLoader.class), clock);+ String jobId = startJob(service, "DOCUMENT_ANALYSIS");++ clock.advance(TextractService.RESULT_RETENTION.minusSeconds(1));++ assertEquals(200, service.getDocumentAnalysis(jobId).getStatus());+ }++ @Test+ void expiredJobReadsAsInvalid() {+ MutableClock clock = new MutableClock(START);+ TextractService service = new TextractService(new ObjectMapper(), mock(AiMockConfigLoader.class), clock);+ String jobId = startJob(service, "TEXT_DETECTION");++ clock.advance(TextractService.RESULT_RETENTION.plusSeconds(1));++ AwsException exception = assertThrows(AwsException.class,+ () -> service.getDocumentTextDetection(jobId));+ assertEquals("InvalidJobIdException", exception.getErrorCode());+ assertEquals(400, exception.getHttpStatus());+ }++ private static String startJob(TextractService service, String jobType) {+ ObjectNode response = jobType.equals("DOCUMENT_ANALYSIS")+ ? (ObjectNode) service.startDocumentAnalysis().getEntity()+ : (ObjectNode) service.startDocumentTextDetection().getEntity();+ return response.get("JobId").asText();+ }++ private static TextractService serviceAt(Instant instant) {+ return new TextractService(new ObjectMapper(), mock(AiMockConfigLoader.class), new MutableClock(instant));+ }++ private static final class MutableClock extends Clock {++ private Instant instant;++ private MutableClock(Instant instant) {+ this.instant = instant;+ }++ private void advance(Duration duration) {+ instant = instant.plus(duration);+ }++ @Override+ public ZoneId getZone() {+ return ZoneOffset.UTC;+ }++ @Override+ public Clock withZone(ZoneId zone) {+ return this;+ }++ @Override+ public Instant instant() {+ return instant;+ }+ }+}\ No newline at end of file