Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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`.
## Configuration
diff --git a/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.java b/src/main/java/io/github/hectorvent/floci/services/textract/TextractService.java
index 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<>();
@Inject
public 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.java
index 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));
+ }
+ @Test
void 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.java
new file mode 100644
index 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