limit concurrent downloads per user and queue the rest

server/src/main/java/au/org/aodn/ogcapi/server/core/configuration/Config.java

@@ -9,6 +9,7 @@
 import au.org.aodn.ogcapi.server.core.util.GeometryUtils;
 import au.org.aodn.ogcapi.server.core.util.RestTemplateUtils;
 import au.org.aodn.ogcapi.server.processes.BatchJobProperties;
+import au.org.aodn.ogcapi.server.processes.DownloadLimitProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.PostConstruct;
@@ -35,6 +36,7 @@
         GNProperties.class,
         DasProperties.class,
         BatchJobProperties.class,
+        DownloadLimitProperties.class,
         OgcApiProperties.class
 })
 public class Config {

server/src/main/java/au/org/aodn/ogcapi/server/core/model/DownloadExecutionResponse.java

@@ -4,10 +4,18 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
 
-@Schema(description = "Compatible download execution response with the submitted AWS Batch job ID.")
+@Schema(description = "Compatible download execution response with the submitted job ID, "
+        + "and whether the download is waiting for a free per-user slot.")
 public record DownloadExecutionResponse(
         @JsonProperty("message") InlineValue message,
         @JsonProperty("status") InlineValue status,
-        @JsonProperty("jobID") String jobId
+        @JsonProperty("jobID") String jobId,
+        @Schema(description = "True when the download was accepted but is waiting for one of "
+                + "this user's concurrent download slots to free. It still has a job ID and "
+                + "will start on its own; nothing further is required from the caller.")
+        @JsonProperty("queued") boolean queued,
+        @Schema(description = "How many of this user's downloads, including this one, are "
+                + "waiting ahead of it; 1 means it starts next. Omitted unless queued.")
+        @JsonProperty("queuePosition") Integer queuePosition
 ) implements InlineResponse200 {
 }

server/src/main/java/au/org/aodn/ogcapi/server/core/model/DownloadJobStatusInfo.java

@@ -31,6 +31,19 @@ public class DownloadJobStatusInfo extends StatusInfo {
     @Schema(description = "Link to the metadata page supplied when the download was submitted.")
     private String metadataUrl;
 
+    @JsonProperty("queued")
+    @Schema(description = "True while the download is waiting for one of this user's "
+            + "concurrent download slots to free. Always present, so clients never have to "
+            + "infer the queued state from the message text.")
+    private boolean queued;
+
+    @JsonProperty("queuePosition")
+    @JsonInclude(JsonInclude.Include.NON_ABSENT)
+    @Schema(description = "How many of this user's downloads, including this one, are waiting "
+            + "ahead of it; 1 means it starts next. Omitted unless queued. This is a position, "
+            + "not an estimated time: it depends on when the running downloads finish.")
+    private Integer queuePosition;
+
     public String getCollection() {
         return collection;
     }
@@ -62,4 +75,20 @@ public String getMetadataUrl() {
     public void setMetadataUrl(String metadataUrl) {
         this.metadataUrl = metadataUrl;
     }
+
+    public boolean isQueued() {
+        return queued;
+    }
+
+    public void setQueued(boolean queued) {
+        this.queued = queued;
+    }
+
+    public Integer getQueuePosition() {
+        return queuePosition;
+    }
+
+    public void setQueuePosition(Integer queuePosition) {
+        this.queuePosition = queuePosition;
+    }
 }

server/src/main/java/au/org/aodn/ogcapi/server/processes/DownloadAdmission.java

@@ -0,0 +1,21 @@
+package au.org.aodn.ogcapi.server.processes;
+
+/**
+ * The outcome of accepting a download: the job id the caller polls, and whether it went
+ * straight to AWS Batch or is waiting for one of that user's slots to free.
+ *
+ * @param jobId         the AWS Batch job id when submitted, or a locally minted id when held
+ * @param queued        true while the download is waiting rather than running
+ * @param queuePosition how many of this user's downloads, including this one, are waiting
+ *                      ahead of it. 1 means it is next. Null when not queued.
+ */
+public record DownloadAdmission(String jobId, boolean queued, Integer queuePosition) {
+
+    static DownloadAdmission submitted(String awsJobId) {
+        return new DownloadAdmission(awsJobId, false, null);
+    }
+
+    static DownloadAdmission queued(String jobId, int queuePosition) {
+        return new DownloadAdmission(jobId, true, queuePosition);
+    }
+}