resultType) {
+ return distributedMapAsync(
+ name,
+ source,
+ processor,
+ maxConcurrency,
+ resultType,
+ DistributedMapConfig.builder().build());
+ }
+
/**
* Executes a submitter function and waits for an external callback, blocking until the callback completes.
*
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapConfig.java b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapConfig.java
new file mode 100644
index 0000000000..08525b976b
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapConfig.java
@@ -0,0 +1,148 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import java.time.Duration;
+import software.amazon.lambda.durable.serde.SerDes;
+
+/** Optional configuration for a distributed map run. */
+public class DistributedMapConfig {
+ private static final long MAX_TIMEOUT_SECONDS = 7776000; // 90 days
+
+ private final DistributedMapDestination destination;
+ private final CompletionConfig completionConfig;
+ private final Duration timeout;
+ private final SerDes resultSerDes;
+
+ private DistributedMapConfig(Builder builder) {
+ if (builder.timeout != null
+ && (builder.timeout.toSeconds() <= 0 || builder.timeout.toSeconds() > MAX_TIMEOUT_SECONDS)) {
+ throw new IllegalArgumentException(
+ "timeout must be positive and at most 90 days, got: " + builder.timeout.toSeconds() + "s");
+ }
+ this.destination = builder.destination;
+ this.completionConfig = builder.completionConfig;
+ this.timeout = builder.timeout;
+ this.resultSerDes = builder.resultSerDes;
+ }
+
+ public DistributedMapDestination destination() {
+ return destination;
+ }
+
+ public CompletionConfig completionConfig() {
+ return completionConfig;
+ }
+
+ public Duration timeout() {
+ return timeout;
+ }
+
+ public SerDes resultSerDes() {
+ return resultSerDes;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public Builder toBuilder() {
+ var builder = new Builder();
+ builder.destination = destination;
+ builder.completionConfig = completionConfig;
+ builder.timeout = timeout;
+ builder.resultSerDes = resultSerDes;
+ return builder;
+ }
+
+ /** Builder for DistributedMapConfig. */
+ public static class Builder {
+ private DistributedMapDestination destination;
+ private CompletionConfig completionConfig;
+ private Duration timeout;
+ private SerDes resultSerDes;
+
+ private Builder() {}
+
+ public Builder destination(DistributedMapDestination destination) {
+ this.destination = destination;
+ return this;
+ }
+
+ public Builder completionConfig(CompletionConfig completionConfig) {
+ this.completionConfig = completionConfig;
+ return this;
+ }
+
+ public Builder timeout(Duration timeout) {
+ this.timeout = timeout;
+ return this;
+ }
+
+ public Builder resultSerDes(SerDes resultSerDes) {
+ this.resultSerDes = resultSerDes;
+ return this;
+ }
+
+ public DistributedMapConfig build() {
+ return new DistributedMapConfig(this);
+ }
+ }
+
+ /**
+ * Failure-tolerance configuration for a distributed map run. {@code toleratedFailurePercentage} is a number from 0
+ * through 100 and may be fractional.
+ */
+ public record CompletionConfig(
+ Integer toleratedFailureCount, Double toleratedFailurePercentage, Integer minimumSampleSize) {
+
+ public CompletionConfig {
+ if (toleratedFailureCount != null && toleratedFailurePercentage != null) {
+ throw new IllegalArgumentException(
+ "toleratedFailureCount and toleratedFailurePercentage are mutually exclusive");
+ }
+ if (minimumSampleSize != null && toleratedFailurePercentage == null) {
+ throw new IllegalArgumentException("minimumSampleSize is only valid with toleratedFailurePercentage");
+ }
+ // Omitting the config means zero tolerated failures, so an empty one is rejected rather than omitted.
+ if (toleratedFailureCount == null && toleratedFailurePercentage == null) {
+ throw new IllegalArgumentException(
+ "a completion config must set toleratedFailureCount or toleratedFailurePercentage");
+ }
+ if (toleratedFailureCount != null && toleratedFailureCount < 0) {
+ throw new IllegalArgumentException(
+ "toleratedFailureCount must be non-negative, got: " + toleratedFailureCount);
+ }
+ if (toleratedFailurePercentage != null && !Double.isFinite(toleratedFailurePercentage)) {
+ throw new IllegalArgumentException(
+ "toleratedFailurePercentage must be a finite number, got: " + toleratedFailurePercentage);
+ }
+ if (toleratedFailurePercentage != null
+ && (toleratedFailurePercentage < 0 || toleratedFailurePercentage > 100)) {
+ throw new IllegalArgumentException(
+ "toleratedFailurePercentage must be between 0 and 100, got: " + toleratedFailurePercentage);
+ }
+ if (minimumSampleSize != null && minimumSampleSize < 1) {
+ throw new IllegalArgumentException("minimumSampleSize must be at least 1, got: " + minimumSampleSize);
+ }
+ }
+
+ /** Stops the run after more than this many items permanently fail. */
+ public static CompletionConfig failureCount(int count) {
+ return new CompletionConfig(count, null, null);
+ }
+
+ /** Abort once the failure rate exceeds this percentage, a number from 0 through 100 that may be fractional. */
+ public static CompletionConfig failurePercentage(double percentage) {
+ return new CompletionConfig(null, percentage, null);
+ }
+
+ /**
+ * Abort once the failure rate exceeds this percentage, a number from 0 through 100 that may be fractional,
+ * gated by a minimum sample size.
+ */
+ public static CompletionConfig failurePercentage(double percentage, int minimumSampleSize) {
+ return new CompletionConfig(null, percentage, minimumSampleSize);
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapDestination.java b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapDestination.java
new file mode 100644
index 0000000000..8e38a6f39f
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapDestination.java
@@ -0,0 +1,109 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import java.nio.charset.StandardCharsets;
+import software.amazon.lambda.durable.util.DistributedMapValidation;
+
+/** Destination routing for distributed map run results. */
+public record DistributedMapDestination(Success onSuccess, Failure onFailure) {
+ private static final int MAX_DESTINATION_KEY_PREFIX_BYTES = 900;
+
+ /** Routes only succeeded item records. */
+ public static DistributedMapDestination of(Success onSuccess) {
+ return new DistributedMapDestination(onSuccess, null);
+ }
+
+ /** Routes only failed item records. */
+ public static DistributedMapDestination of(Failure onFailure) {
+ return new DistributedMapDestination(null, onFailure);
+ }
+
+ /** Routes both succeeded and failed item records. */
+ public static DistributedMapDestination of(Success onSuccess, Failure onFailure) {
+ return new DistributedMapDestination(onSuccess, onFailure);
+ }
+
+ /** Route succeeded item records to an S3 prefix (defaults to include output only). */
+ public static Success s3Successes(String prefixUri) {
+ return s3Successes(prefixUri, false, true, null);
+ }
+
+ /** Route succeeded item records to an S3 prefix. */
+ public static Success s3Successes(
+ String prefixUri, boolean includeInput, boolean includeOutput, String expectedBucketOwner) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return new Success(
+ parsed.bucket(),
+ parsed.path() != null ? parsed.path() : "",
+ includeInput,
+ includeOutput,
+ expectedBucketOwner);
+ }
+
+ /** Route permanently-failed item records to an S3 prefix (defaults to include input and error). */
+ public static Failure s3Failures(String prefixUri) {
+ return s3Failures(prefixUri, true, true, null);
+ }
+
+ /** Route permanently-failed item records to an S3 prefix. */
+ public static Failure s3Failures(
+ String prefixUri, boolean includeInput, boolean includeError, String expectedBucketOwner) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return new Failure(
+ parsed.bucket(),
+ parsed.path() != null ? parsed.path() : "",
+ includeInput,
+ includeError,
+ expectedBucketOwner);
+ }
+
+ /**
+ * Rejects a destination key prefix the service would reject. The limit is 900 UTF-8 bytes, including a trailing
+ * slash when the URI has one, and it is measured in bytes rather than characters, so a multi-byte prefix under 900
+ * characters can still exceed it. The service applies the same limit when the start checkpoint is written, so
+ * checking it here fails the call that built the destination instead of the operation.
+ */
+ private static void validateDestinationPrefix(String prefix) {
+ if (prefix == null) {
+ return;
+ }
+ var bytes = prefix.getBytes(StandardCharsets.UTF_8).length;
+ if (bytes > MAX_DESTINATION_KEY_PREFIX_BYTES) {
+ throw new IllegalArgumentException("destination key prefix must be at most "
+ + MAX_DESTINATION_KEY_PREFIX_BYTES + " UTF-8 bytes, got: " + bytes);
+ }
+ }
+
+ /** S3 destination for succeeded distributed map items. */
+ public record Success(
+ String bucket, String prefix, boolean includeInput, boolean includeOutput, String expectedBucketOwner) {
+
+ public Success {
+ if (bucket == null || bucket.isEmpty()) {
+ throw new IllegalArgumentException("success destination bucket cannot be empty");
+ }
+ DistributedMapValidation.validateBucketOwner(expectedBucketOwner);
+ validateDestinationPrefix(prefix);
+ if (!includeInput && !includeOutput) {
+ throw new IllegalArgumentException("success destination must include at least one of input or output");
+ }
+ }
+ }
+
+ /** S3 destination for permanently-failed distributed map items. */
+ public record Failure(
+ String bucket, String prefix, boolean includeInput, boolean includeError, String expectedBucketOwner) {
+
+ public Failure {
+ if (bucket == null || bucket.isEmpty()) {
+ throw new IllegalArgumentException("failure destination bucket cannot be empty");
+ }
+ DistributedMapValidation.validateBucketOwner(expectedBucketOwner);
+ validateDestinationPrefix(prefix);
+ if (!includeInput && !includeError) {
+ throw new IllegalArgumentException("failure destination must include at least one of input or error");
+ }
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessor.java b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessor.java
new file mode 100644
index 0000000000..6c70ee05e1
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessor.java
@@ -0,0 +1,116 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import software.amazon.lambda.durable.util.DistributedMapValidation;
+
+/** Processor configuration for a distributed map run. */
+public class DistributedMapProcessor {
+
+ /** Per-batch response mode reported by the processor. */
+ public enum ResponseMode {
+ BATCH,
+ ITEM_OUTCOMES
+ }
+
+ private static final int MIN_BATCH_SIZE = 1;
+ private static final int MAX_BATCH_SIZE = 10000;
+ private static final int MAX_NAME_PREFIX_LENGTH = 36;
+
+ private final String functionName;
+ private final ResponseMode responseMode;
+ private final Integer batchSize;
+ private final DistributedMapProcessorRetryConfig retry;
+ private final String durableExecutionNamePrefix;
+
+ private DistributedMapProcessor(Builder builder) {
+ DistributedMapValidation.validateFunctionName(builder.functionName);
+ if (builder.batchSize != null && (builder.batchSize < MIN_BATCH_SIZE || builder.batchSize > MAX_BATCH_SIZE)) {
+ throw new IllegalArgumentException("batchSize must be between 1 and 10000, got: " + builder.batchSize);
+ }
+ if (builder.durableExecutionNamePrefix != null
+ && (builder.durableExecutionNamePrefix.isEmpty()
+ || builder.durableExecutionNamePrefix.length() > MAX_NAME_PREFIX_LENGTH)) {
+ throw new IllegalArgumentException("durableExecutionNamePrefix must be between 1 and 36 characters, got: "
+ + builder.durableExecutionNamePrefix.length());
+ }
+ this.functionName = builder.functionName;
+ this.responseMode = builder.responseMode;
+ this.batchSize = builder.batchSize;
+ this.retry = builder.retry;
+ this.durableExecutionNamePrefix = builder.durableExecutionNamePrefix;
+ }
+
+ public String functionName() {
+ return functionName;
+ }
+
+ public ResponseMode responseMode() {
+ return responseMode;
+ }
+
+ public Integer batchSize() {
+ return batchSize;
+ }
+
+ /** Returns the retry settings, or null for the service defaults. */
+ public DistributedMapProcessorRetryConfig retry() {
+ return retry;
+ }
+
+ public String durableExecutionNamePrefix() {
+ return durableExecutionNamePrefix;
+ }
+
+ /** Processor that reports a single pass/fail outcome for the whole batch, with no per-item results. */
+ public static Builder reportBatchOutcome(String functionName) {
+ return new Builder(functionName, ResponseMode.BATCH);
+ }
+
+ /**
+ * Processor that may report a failure or an output for each item. Every item it does not list succeeds with no
+ * output.
+ */
+ public static Builder reportItemOutcomes(String functionName) {
+ return new Builder(functionName, ResponseMode.ITEM_OUTCOMES);
+ }
+
+ /** Builder for DistributedMapProcessor. */
+ public static class Builder {
+ private final String functionName;
+ private final ResponseMode responseMode;
+ private Integer batchSize;
+ private DistributedMapProcessorRetryConfig retry;
+ private String durableExecutionNamePrefix;
+
+ private Builder(String functionName, ResponseMode responseMode) {
+ this.functionName = functionName;
+ this.responseMode = responseMode;
+ }
+
+ public Builder batchSize(int batchSize) {
+ this.batchSize = batchSize;
+ return this;
+ }
+
+ /**
+ * Sets the per-item retry policy. Omit it to take the service defaults of 2 attempts within 6 hours.
+ *
+ * @param retry the retry settings
+ * @return this builder
+ */
+ public Builder retry(DistributedMapProcessorRetryConfig retry) {
+ this.retry = retry;
+ return this;
+ }
+
+ public Builder durableExecutionNamePrefix(String durableExecutionNamePrefix) {
+ this.durableExecutionNamePrefix = durableExecutionNamePrefix;
+ return this;
+ }
+
+ public DistributedMapProcessor build() {
+ return new DistributedMapProcessor(this);
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfig.java b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfig.java
new file mode 100644
index 0000000000..bda75df6a5
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfig.java
@@ -0,0 +1,93 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import java.time.Duration;
+
+/**
+ * Retry settings for a distributed map processor.
+ *
+ * Retry policy belongs to the processor reference rather than the run, because it defines how the service invokes
+ * that function. One Lambda function can back several processor references with different policies.
+ */
+public class DistributedMapProcessorRetryConfig {
+
+ /** Sentinel for unbounded retry attempts (wire value -1). */
+ public static final int UNLIMITED = -1;
+
+ private static final long MIN_RETRY_DURATION_SECONDS = 60;
+ private static final long MAX_RETRY_DURATION_SECONDS = 21600;
+
+ private final Integer maxRetryAttempts;
+ private final Duration maxRetryDuration;
+
+ private DistributedMapProcessorRetryConfig(Builder builder) {
+ this.maxRetryAttempts = builder.maxRetryAttempts;
+ this.maxRetryDuration = builder.maxRetryDuration;
+ }
+
+ /** Returns the max retry attempts, UNLIMITED for unbounded, or null for the service default of 2. */
+ public Integer maxRetryAttempts() {
+ return maxRetryAttempts;
+ }
+
+ /** Returns the cumulative retry duration budget, or null for the service default of 6 hours. */
+ public Duration maxRetryDuration() {
+ return maxRetryDuration;
+ }
+
+ /**
+ * Creates a new builder for {@code DistributedMapProcessorRetryConfig}.
+ *
+ * @return a new builder instance
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** Builder for DistributedMapProcessorRetryConfig. */
+ public static class Builder {
+ private Integer maxRetryAttempts;
+ private Duration maxRetryDuration;
+
+ private Builder() {}
+
+ /**
+ * Sets the number of function-error retries before an item permanently fails. Pass {@link #UNLIMITED} for no
+ * attempt limit within the duration budget, or 0 to disable retries.
+ *
+ * @param maxRetryAttempts a non-negative count, or UNLIMITED
+ * @return this builder
+ */
+ public Builder maxRetryAttempts(int maxRetryAttempts) {
+ if (maxRetryAttempts < 0 && maxRetryAttempts != UNLIMITED) {
+ throw new IllegalArgumentException(
+ "maxRetryAttempts must be non-negative or DistributedMapProcessorRetryConfig.UNLIMITED, got: "
+ + maxRetryAttempts);
+ }
+ this.maxRetryAttempts = maxRetryAttempts;
+ return this;
+ }
+
+ /**
+ * Sets the cumulative backoff budget across all of an item's retries, from 1 minute through 6 hours.
+ *
+ * @param maxRetryDuration the budget
+ * @return this builder
+ */
+ public Builder maxRetryDuration(Duration maxRetryDuration) {
+ if (maxRetryDuration != null
+ && (maxRetryDuration.toSeconds() < MIN_RETRY_DURATION_SECONDS
+ || maxRetryDuration.toSeconds() > MAX_RETRY_DURATION_SECONDS)) {
+ throw new IllegalArgumentException("maxRetryDuration must be between 1 minute and 6 hours, got: "
+ + maxRetryDuration.toSeconds() + "s");
+ }
+ this.maxRetryDuration = maxRetryDuration;
+ return this;
+ }
+
+ public DistributedMapProcessorRetryConfig build() {
+ return new DistributedMapProcessorRetryConfig(this);
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapSource.java b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapSource.java
new file mode 100644
index 0000000000..70510466e6
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/config/DistributedMapSource.java
@@ -0,0 +1,331 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import software.amazon.lambda.durable.serde.SerDes;
+import software.amazon.lambda.durable.util.DistributedMapValidation;
+import software.amazon.lambda.durable.util.ParameterValidator;
+
+/**
+ * Source of items for a distributed map run.
+ *
+ * @param the item type produced by the source
+ */
+public class DistributedMapSource {
+
+ private static final long MAX_ITEMS_TO_READ = 100_000_000L;
+
+ /** The kind of source backing a distributed map. */
+ public enum SourceType {
+ INLINE,
+ S3,
+ READER_FUNCTION
+ }
+
+ /** How the bytes of an S3 object are split into items. */
+ public enum Format {
+ JSON_LINES,
+ JSON_ARRAY,
+ CSV
+ }
+
+ /** What an S3 source reads. */
+ public enum S3SourceType {
+ OBJECT,
+ LISTED_OBJECT_METADATA,
+ LISTED_OBJECTS
+ }
+
+ private final SourceType sourceType;
+ private final Long maxItems;
+ private final List inlineItems;
+ private final SerDes inlineSerDes;
+ private final S3SourceConfig s3;
+ private final ReaderSourceConfig reader;
+
+ private DistributedMapSource(
+ SourceType sourceType,
+ Long maxItems,
+ List inlineItems,
+ SerDes inlineSerDes,
+ S3SourceConfig s3,
+ ReaderSourceConfig reader) {
+ if (maxItems != null && (maxItems < 1 || maxItems > MAX_ITEMS_TO_READ)) {
+ throw new IllegalArgumentException(
+ "maxItems must be between 1 and " + MAX_ITEMS_TO_READ + ", got: " + maxItems);
+ }
+ this.sourceType = sourceType;
+ this.maxItems = maxItems;
+ // A null item is allowed and is sent as JSON null, so the copy must accept null elements.
+ this.inlineItems = inlineItems != null ? Collections.unmodifiableList(new ArrayList<>(inlineItems)) : null;
+ this.inlineSerDes = inlineSerDes;
+ this.s3 = s3;
+ this.reader = reader;
+ }
+
+ public SourceType sourceType() {
+ return sourceType;
+ }
+
+ public Long maxItems() {
+ return maxItems;
+ }
+
+ public List inlineItems() {
+ return inlineItems;
+ }
+
+ public SerDes inlineSerDes() {
+ return inlineSerDes;
+ }
+
+ public S3SourceConfig s3() {
+ return s3;
+ }
+
+ public ReaderSourceConfig reader() {
+ return reader;
+ }
+
+ /** An in-memory list of items embedded in the start checkpoint. */
+ public static DistributedMapSource inline(Collection items) {
+ return inline(items, null);
+ }
+
+ /** An in-memory list of items embedded in the start checkpoint, serialized with the given SerDes. */
+ public static DistributedMapSource inline(Collection items, SerDes serDes) {
+ ParameterValidator.validateOrderedCollection(items);
+ return new DistributedMapSource<>(SourceType.INLINE, null, new ArrayList<>(items), serDes, null, null);
+ }
+
+ /** Read a single S3 object, treating each line as an item. */
+ public static DistributedMapSource s3JsonLines(String uri) {
+ var parsed = DistributedMapValidation.parseS3Uri(uri);
+ if (parsed.path() == null) {
+ throw new IllegalArgumentException("s3JsonLines requires an S3 object key");
+ }
+ return s3(object(parsed.bucket(), parsed.path(), Format.JSON_LINES, null));
+ }
+
+ /** Read a single S3 object holding a JSON array, treating each element as an item. */
+ public static DistributedMapSource s3JsonArray(String uri) {
+ var parsed = DistributedMapValidation.parseS3Uri(uri);
+ if (parsed.path() == null) {
+ throw new IllegalArgumentException("s3JsonArray requires an S3 object key");
+ }
+ return s3(object(parsed.bucket(), parsed.path(), Format.JSON_ARRAY, null));
+ }
+
+ /** Read a single S3 object, treating each record as an item. */
+ public static DistributedMapSource s3Csv(String uri, CsvFormat format) {
+ var parsed = DistributedMapValidation.parseS3Uri(uri);
+ if (parsed.path() == null) {
+ throw new IllegalArgumentException("s3Csv requires an S3 object key");
+ }
+ return s3(object(parsed.bucket(), parsed.path(), Format.CSV, format));
+ }
+
+ /** Read each object under a prefix as one item (object contents are not read). */
+ public static DistributedMapSource s3Objects(String prefixUri) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return s3(new S3SourceConfig(
+ S3SourceType.LISTED_OBJECT_METADATA,
+ parsed.bucket(),
+ null,
+ null,
+ new ListedObjectMetadataConfig(prefixOrEmpty(parsed.path())),
+ null));
+ }
+
+ /** Read a prefix, flattening each object's lines into items. */
+ public static DistributedMapSource s3FlattenedJsonLines(String prefixUri) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return s3(listedObjects(parsed.bucket(), prefixOrEmpty(parsed.path()), Format.JSON_LINES, null));
+ }
+
+ /** Read a prefix, flattening each object's JSON array elements into items. */
+ public static DistributedMapSource s3FlattenedJsonArray(String prefixUri) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return s3(listedObjects(parsed.bucket(), prefixOrEmpty(parsed.path()), Format.JSON_ARRAY, null));
+ }
+
+ /** Read a prefix, flattening each object's records into items. */
+ public static DistributedMapSource s3FlattenedCsv(String prefixUri, CsvFormat format) {
+ var parsed = DistributedMapValidation.parseS3Uri(prefixUri);
+ return s3(listedObjects(parsed.bucket(), prefixOrEmpty(parsed.path()), Format.CSV, format));
+ }
+
+ private static S3SourceConfig object(String bucket, String key, Format format, CsvFormat csvFormat) {
+ return new S3SourceConfig(
+ S3SourceType.OBJECT, bucket, null, new ObjectConfig(key, format, csvFormat), null, null);
+ }
+
+ private static S3SourceConfig listedObjects(String bucket, String keyPrefix, Format format, CsvFormat csvFormat) {
+ return new S3SourceConfig(
+ S3SourceType.LISTED_OBJECTS,
+ bucket,
+ null,
+ null,
+ null,
+ new ListedObjectsConfig(keyPrefix, format, csvFormat));
+ }
+
+ /** Page items from a customer-supplied reader Lambda function. */
+ public static DistributedMapSource reader(String functionName) {
+ return reader(functionName, null, null);
+ }
+
+ /** Page items from a customer-supplied reader Lambda function with an initial state. */
+ public static DistributedMapSource reader(String functionName, S initialState, SerDes stateSerDes) {
+ return new DistributedMapSource<>(
+ SourceType.READER_FUNCTION,
+ null,
+ null,
+ null,
+ null,
+ new ReaderSourceConfig(functionName, initialState, stateSerDes));
+ }
+
+ /** Returns a copy limiting the total number of items read. */
+ public DistributedMapSource maxItems(long maxItems) {
+ return new DistributedMapSource<>(sourceType, maxItems, inlineItems, inlineSerDes, s3, reader);
+ }
+
+ /** Returns a copy asserting the expected S3 bucket owner (S3 sources only). */
+ public DistributedMapSource expectedBucketOwner(String accountId) {
+ if (s3 == null) {
+ throw new IllegalStateException("expectedBucketOwner only applies to S3 sources");
+ }
+ DistributedMapValidation.validateBucketOwner(accountId);
+ return new DistributedMapSource<>(
+ sourceType, maxItems, inlineItems, inlineSerDes, s3.withExpectedBucketOwner(accountId), reader);
+ }
+
+ private static DistributedMapSource s3(S3SourceConfig s3) {
+ return new DistributedMapSource<>(SourceType.S3, null, null, null, s3, null);
+ }
+
+ private static String prefixOrEmpty(String path) {
+ return path != null ? path : "";
+ }
+
+ /** Resolved S3 source configuration. Exactly one config block matching {@code type} is set. */
+ public record S3SourceConfig(
+ S3SourceType type,
+ String bucket,
+ String expectedBucketOwner,
+ ObjectConfig objectConfig,
+ ListedObjectMetadataConfig listedObjectMetadataConfig,
+ ListedObjectsConfig listedObjectsConfig) {
+
+ S3SourceConfig withExpectedBucketOwner(String owner) {
+ return new S3SourceConfig(
+ type, bucket, owner, objectConfig, listedObjectMetadataConfig, listedObjectsConfig);
+ }
+ }
+
+ /** Reads the single object at {@code key}. */
+ public record ObjectConfig(String key, Format format, CsvFormat csvFormat) {}
+
+ /** Lists the objects under {@code keyPrefix} without reading their contents. */
+ public record ListedObjectMetadataConfig(String keyPrefix) {}
+
+ /** Lists the objects under {@code keyPrefix} and reads every listed object as {@code format}. */
+ public record ListedObjectsConfig(String keyPrefix, Format format, CsvFormat csvFormat) {}
+
+ /** Resolved reader-function source configuration. */
+ public record ReaderSourceConfig(String functionName, Object initialState, SerDes stateSerDes) {
+ public ReaderSourceConfig {
+ DistributedMapValidation.validateFunctionName(functionName);
+ }
+ }
+
+ /** CSV parsing options for a distributed map S3 source. */
+ public record CsvFormat(HeaderLocation headerLocation, List columns, CsvDelimiter delimiter) {
+ private static final int MAX_CSV_COLUMNS = 1000;
+ private static final int MAX_CSV_COLUMN_LENGTH = 256;
+
+ /** Where the column header row comes from. */
+ public enum HeaderLocation {
+ FIRST_ROW,
+ GIVEN
+ }
+
+ public CsvFormat {
+ if (headerLocation == null) {
+ throw new IllegalArgumentException("CsvFormat requires a headerLocation");
+ }
+ if (headerLocation == HeaderLocation.GIVEN) {
+ if (columns == null) {
+ throw new IllegalArgumentException("CsvFormat with headerLocation GIVEN requires headers");
+ }
+ validateColumns("headers", columns);
+ } else {
+ validateColumns("expectedColumns", columns);
+ }
+ columns = columns != null ? List.copyOf(columns) : null;
+ delimiter = delimiter != null ? delimiter : CsvDelimiter.COMMA;
+ }
+
+ /**
+ * File has its own header row. Column names are used only for compile-time typing and are not sent on the wire.
+ */
+ public static CsvFormat expectedColumns(List columns) {
+ return new CsvFormat(HeaderLocation.FIRST_ROW, columns, CsvDelimiter.COMMA);
+ }
+
+ /** File has no header row. The given names are the columns, sent on the wire, and the first row is data. */
+ public static CsvFormat headers(List headers) {
+ return new CsvFormat(HeaderLocation.GIVEN, headers, CsvDelimiter.COMMA);
+ }
+
+ /** File has its own header row and no column names are declared. */
+ public static CsvFormat firstRow() {
+ return new CsvFormat(HeaderLocation.FIRST_ROW, null, CsvDelimiter.COMMA);
+ }
+
+ /** Returns a copy with the given delimiter. */
+ public CsvFormat withDelimiter(CsvDelimiter delimiter) {
+ return new CsvFormat(headerLocation, columns, delimiter);
+ }
+
+ private static void validateColumns(String parameterName, List columns) {
+ if (columns == null) {
+ return;
+ }
+ if (columns.isEmpty()) {
+ throw new IllegalArgumentException(parameterName + " cannot be empty");
+ }
+ if (columns.size() > MAX_CSV_COLUMNS) {
+ throw new IllegalArgumentException(
+ parameterName + " must hold at most " + MAX_CSV_COLUMNS + " names, got: " + columns.size());
+ }
+ for (var column : columns) {
+ if (column == null || column.isEmpty()) {
+ throw new IllegalArgumentException("each " + parameterName + " name cannot be empty");
+ }
+ if (column.length() > MAX_CSV_COLUMN_LENGTH) {
+ throw new IllegalArgumentException("each " + parameterName + " name must be at most "
+ + MAX_CSV_COLUMN_LENGTH + " characters, got: " + column.length());
+ }
+ }
+ if (new HashSet<>(columns).size() != columns.size()) {
+ throw new IllegalArgumentException(parameterName + " must not contain duplicates");
+ }
+ }
+ }
+
+ /** Delimiter for CSV distributed map sources. */
+ public enum CsvDelimiter {
+ COMMA,
+ PIPE,
+ SEMICOLON,
+ SPACE,
+ TAB
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/context/DurableContextImpl.java b/sdk/src/main/java/software/amazon/lambda/durable/context/DurableContextImpl.java
index 8081f78d11..e5568230d0 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/context/DurableContextImpl.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/context/DurableContextImpl.java
@@ -10,6 +10,7 @@
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Function;
+import software.amazon.awssdk.services.lambda.model.DistributedMapDetails;
import software.amazon.lambda.durable.DurableCallbackFuture;
import software.amazon.lambda.durable.DurableConfig;
import software.amazon.lambda.durable.DurableContext;
@@ -18,6 +19,9 @@
import software.amazon.lambda.durable.StepContext;
import software.amazon.lambda.durable.TypeToken;
import software.amazon.lambda.durable.config.CallbackConfig;
+import software.amazon.lambda.durable.config.DistributedMapConfig;
+import software.amazon.lambda.durable.config.DistributedMapProcessor;
+import software.amazon.lambda.durable.config.DistributedMapSource;
import software.amazon.lambda.durable.config.InvokeConfig;
import software.amazon.lambda.durable.config.MapConfig;
import software.amazon.lambda.durable.config.ParallelConfig;
@@ -31,12 +35,16 @@
import software.amazon.lambda.durable.execution.OperationIdGenerator;
import software.amazon.lambda.durable.execution.SuspendExecutionException;
import software.amazon.lambda.durable.execution.ThreadType;
+import software.amazon.lambda.durable.model.DistributedMapResult;
+import software.amazon.lambda.durable.model.DistributedMapStatus;
+import software.amazon.lambda.durable.model.DistributedMapSummary;
import software.amazon.lambda.durable.model.MapResult;
import software.amazon.lambda.durable.model.OperationIdentifier;
import software.amazon.lambda.durable.model.OperationSubType;
import software.amazon.lambda.durable.model.WaitForConditionResult;
import software.amazon.lambda.durable.operation.CallbackOperation;
import software.amazon.lambda.durable.operation.ChildContextOperation;
+import software.amazon.lambda.durable.operation.DistributedMapOperation;
import software.amazon.lambda.durable.operation.InvokeOperation;
import software.amazon.lambda.durable.operation.MapOperation;
import software.amazon.lambda.durable.operation.ParallelOperation;
@@ -371,6 +379,86 @@ public DurableFuture waitForConditionAsync(
return operation;
}
+ // =============== distributedMap ================
+
+ @Override
+ public DurableFuture distributedMapAsync(
+ String name,
+ DistributedMapSource source,
+ DistributedMapProcessor processor,
+ int maxConcurrency,
+ DistributedMapConfig config) {
+ return startDistributedMap(
+ name,
+ source,
+ processor,
+ maxConcurrency,
+ config,
+ false,
+ TypeToken.get(DistributedMapSummary.class),
+ DistributedMapOperation::toSummary);
+ }
+
+ @Override
+ public DurableFuture> distributedMapAsync(
+ String name,
+ DistributedMapSource source,
+ DistributedMapProcessor processor,
+ int maxConcurrency,
+ TypeToken resultType,
+ DistributedMapConfig config) {
+ Objects.requireNonNull(resultType, "resultType cannot be null");
+ Objects.requireNonNull(config, "config cannot be null");
+ var resultSerDes = config.resultSerDes() != null
+ ? config.resultSerDes()
+ : getDurableConfig().getSerDes();
+ @SuppressWarnings({"unchecked", "rawtypes"})
+ TypeToken> token = (TypeToken) TypeToken.get(DistributedMapResult.class);
+ return startDistributedMap(
+ name,
+ source,
+ processor,
+ maxConcurrency,
+ config,
+ true,
+ token,
+ (status, details) -> DistributedMapOperation.toResult(status, details, resultType, resultSerDes));
+ }
+
+ private DurableFuture startDistributedMap(
+ String name,
+ DistributedMapSource> source,
+ DistributedMapProcessor processor,
+ int maxConcurrency,
+ DistributedMapConfig config,
+ boolean collectResults,
+ TypeToken resultType,
+ BiFunction resultBuilder) {
+ Objects.requireNonNull(source, "source cannot be null");
+ Objects.requireNonNull(processor, "processor cannot be null");
+ Objects.requireNonNull(config, "config cannot be null");
+ ParameterValidator.validateOperationName(name);
+ if (maxConcurrency < 1) {
+ throw new IllegalArgumentException("maxConcurrency must be greater than zero, got: " + maxConcurrency);
+ }
+ if (!collectResults && config.resultSerDes() != null) {
+ throw new IllegalArgumentException(
+ "resultSerDes is set but this distributedMap call does not collect results, use a resultType overload");
+ }
+ var options = DistributedMapOperation.toOptions(
+ source, processor, maxConcurrency, config, getDurableConfig().getSerDes(), collectResults);
+ var operationId = nextOperationId();
+ var operation = new DistributedMapOperation<>(
+ OperationIdentifier.of(operationId, name, OperationSubType.DISTRIBUTED_MAP),
+ options,
+ resultType,
+ getDurableConfig().getSerDes(),
+ resultBuilder,
+ this);
+ operation.execute();
+ return operation;
+ }
+
// =============== withRetry ================
private static final Duration DEFAULT_BACKOFF_DELAY = Duration.ofSeconds(1);
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/BatchContext.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/BatchContext.java
new file mode 100644
index 0000000000..5e88a63925
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/BatchContext.java
@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import java.util.List;
+
+/**
+ * The context a batch function receives with its items.
+ *
+ * @param distributedMapRunArn the ARN of the distributed map run the batch belongs to
+ * @param itemIds the items' identifiers, assigned by the service. itemIds.get(i) is the id of items.get(i), so
+ * filtering or reordering the items breaks the pairing
+ */
+public record BatchContext(String distributedMapRunArn, List itemIds) {
+
+ /** Applies a defensive copy. */
+ public BatchContext {
+ itemIds = List.copyOf(itemIds);
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/DistributedMapHandlers.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/DistributedMapHandlers.java
new file mode 100644
index 0000000000..aa2d916dc5
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/DistributedMapHandlers.java
@@ -0,0 +1,412 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.config.CompletionConfig;
+import software.amazon.lambda.durable.config.MapConfig;
+import software.amazon.lambda.durable.execution.DurableExecutor;
+import software.amazon.lambda.durable.model.DistributedMapError;
+import software.amazon.lambda.durable.model.DurableExecutionInput;
+import software.amazon.lambda.durable.model.DurableExecutionOutput;
+import software.amazon.lambda.durable.model.MapResult;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+import software.amazon.lambda.durable.serde.SerDes;
+
+/** Authoring helpers that wrap a customer function into a distributed map processor or reader Lambda handler. */
+public final class DistributedMapHandlers {
+ private static final SerDes JSON = new JacksonSerDes();
+ private static final TypeToken OUTPUT_TYPE = TypeToken.get(String.class);
+ private static final int MIN_CONCURRENCY = 1;
+ private static final int DEFAULT_CONCURRENCY = 1;
+ private static final TypeToken EVENT_TYPE = TypeToken.get(ProcessorEvent.class);
+ private static final int READER_STATE_LIMIT = 32 * 1024;
+ private static final String ITEMS_OP_NAME = "distributed-map-items";
+
+ private DistributedMapHandlers() {}
+
+ /** Reader function: returns the page that follows the given state. */
+ @FunctionalInterface
+ public interface ReaderFunction {
+
+ /**
+ * Reads one page.
+ *
+ * @param state the state from the previous page, or null on the first call
+ * @param maxItemsPerPage the most items the page may hold
+ * @param context the reader context for this page request
+ * @return the page of items and the next state, or a null next state when the source is exhausted
+ */
+ ReaderPage apply(S state, Integer maxItemsPerPage, ReaderContext context);
+ }
+
+ /** Durable item function: processes one item under its own DurableContext. */
+ @FunctionalInterface
+ public interface DurableItemFunction {
+
+ /**
+ * Processes one item.
+ *
+ * @param context the durable context for this item's execution
+ * @param item the item to process
+ * @param itemContext the item context for this item
+ * @return the item's output
+ */
+ O apply(DurableContext context, I item, ItemContext itemContext);
+ }
+
+ /** Durable batch function: processes a whole batch under the batch's DurableContext. */
+ @FunctionalInterface
+ public interface DurableBatchFunction {
+
+ /**
+ * Processes the batch.
+ *
+ * @param context the durable context for the batch's execution
+ * @param items the items in the batch
+ * @param batchContext the batch context for the batch
+ */
+ void accept(DurableContext context, List items, BatchContext batchContext);
+ }
+
+ private static void validateConcurrency(int concurrency) {
+ if (concurrency < MIN_CONCURRENCY) {
+ throw new IllegalArgumentException(
+ "concurrency must be at least " + MIN_CONCURRENCY + ", got: " + concurrency);
+ }
+ }
+
+ /** Wraps a per-item function as a processor handler, running one item at a time. */
+ public static RequestHandler createDistributedMapItemHandler(
+ BiFunction func, TypeToken itemType, SerDes itemSerDes, SerDes resultSerDes) {
+ return createDistributedMapItemHandler(func, itemType, itemSerDes, resultSerDes, DEFAULT_CONCURRENCY);
+ }
+
+ /**
+ * Wraps a per-item function as a processor handler. Pair it with DistributedMapProcessor.reportItemOutcomes.
+ *
+ * @param concurrency the maximum number of items processed at the same time, at least 1. When greater than 1, the
+ * function, itemSerDes and resultSerDes are called from several threads at the same time, so each must be safe
+ * for concurrent calls.
+ */
+ public static RequestHandler createDistributedMapItemHandler(
+ BiFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ SerDes resultSerDes,
+ int concurrency) {
+ validateConcurrency(concurrency);
+ var inSerdes = itemSerDes != null ? itemSerDes : JSON;
+ var outSerdes = resultSerDes != null ? resultSerDes : JSON;
+ return (event, context) -> {
+ var records = event.records();
+ var outputs = new String[records.size()];
+ var errors = new Throwable[records.size()];
+ var pool = Executors.newFixedThreadPool(concurrency);
+ try {
+ var futures = new ArrayList>();
+ for (var i = 0; i < records.size(); i++) {
+ var index = i;
+ futures.add(pool.submit(() -> {
+ var record = records.get(index);
+ I item = toItem(inSerdes, record.body(), itemType);
+ O output = func.apply(item, new ItemContext(event.distributedMapRunArn(), record.itemId()));
+ outputs[index] = toOutput(outSerdes, output);
+ return null;
+ }));
+ }
+ for (var i = 0; i < futures.size(); i++) {
+ try {
+ futures.get(i).get();
+ } catch (ExecutionException e) {
+ errors[i] = e.getCause() != null ? e.getCause() : e;
+ }
+ }
+ } catch (InterruptedException e) {
+ pool.shutdownNow();
+ Thread.currentThread().interrupt();
+ throw new IllegalStateException("Distributed map item handler interrupted", e);
+ } finally {
+ pool.shutdown();
+ }
+
+ var results = new ArrayList();
+ var failures = new ArrayList();
+ for (var i = 0; i < records.size(); i++) {
+ var itemId = records.get(i).itemId();
+ if (errors[i] != null) {
+ failures.add(new ItemFailure(itemId, DistributedMapError.of(errors[i])));
+ } else {
+ results.add(new ItemResult(itemId, outputs[i]));
+ }
+ }
+ return new ItemHandlerResponse(results, failures);
+ };
+ }
+
+ /**
+ * Wraps a whole-batch function as a processor handler. Returning succeeds every item, throwing fails the batch.
+ * Pair it with DistributedMapProcessor.reportBatchOutcome.
+ */
+ public static RequestHandler createDistributedMapBatchHandler(
+ BiConsumer, BatchContext> func, TypeToken itemType, SerDes itemSerDes) {
+ var serdes = itemSerDes != null ? itemSerDes : JSON;
+ return (event, context) -> {
+ func.accept(
+ toItems(serdes, event, itemType),
+ new BatchContext(
+ event.distributedMapRunArn(),
+ event.records().stream()
+ .map(ProcessorRecord::itemId)
+ .toList()));
+ return null;
+ };
+ }
+
+ /**
+ * Wraps a reader function as a source handler. A null nextState signals the source is exhausted.
+ *
+ * itemSerDes must be the serdes the processor is configured with, since the processor deserializes every item
+ * body with its own item serdes. The reader and the processor are separate Lambdas, so nothing checks that they
+ * match.
+ */
+ public static RequestHandler createDistributedMapReader(
+ ReaderFunction func, TypeToken stateType, SerDes stateSerDes, SerDes itemSerDes) {
+ var serdes = stateSerDes != null ? stateSerDes : JSON;
+ var itemSerdes = itemSerDes != null ? itemSerDes : JSON;
+ return (event, context) -> {
+ S state = event.state() != null ? serdes.deserialize(event.state(), stateType) : null;
+
+ var page = func.apply(state, event.maxItemsPerPage(), new ReaderContext(event.distributedMapRunArn()));
+ if (page.items().size() > event.maxItemsPerPage()) {
+ throw new IllegalStateException("reader returned "
+ + page.items().size() + " items, exceeding maxItemsPerPage " + event.maxItemsPerPage());
+ }
+ var items = new ArrayList(page.items().size());
+ var index = 0;
+ for (I item : page.items()) {
+ var body = itemSerdes.serialize(item);
+ if (body == null) {
+ // The service requires every item to be a string, so a null item is sent as the JSON literal null.
+ if (item != null) {
+ throw new IllegalStateException(
+ "serialization of reader item " + index + " produced no string");
+ }
+ body = "null";
+ }
+ items.add(body);
+ index++;
+ }
+ String nextState = null;
+ if (page.nextState() != null) {
+ nextState = serdes.serialize(page.nextState());
+ if (nextState == null) {
+ throw new IllegalStateException("serialization of reader nextState produced no string");
+ }
+ if (nextState.getBytes(StandardCharsets.UTF_8).length > READER_STATE_LIMIT) {
+ throw new IllegalStateException(
+ "reader nextState exceeds the " + (READER_STATE_LIMIT / 1024) + " KB limit");
+ }
+ // The next call would repeat the same position, and the service rejects it as a source failure.
+ if (nextState.equals(event.state())) {
+ throw new IllegalStateException(
+ "reader nextState must differ from the state it was called with, or the next page repeats the same position");
+ }
+ }
+ return new ReaderResponse(items, nextState);
+ };
+ }
+
+ /** Durable variant of the item handler, running one item at a time. */
+ public static
+ RequestHandler
+ createDistributedMapItemHandlerWithDurableExecution(
+ DurableItemFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ SerDes resultSerDes) {
+ return createDistributedMapItemHandlerWithDurableExecution(
+ func, itemType, itemSerDes, resultSerDes, DEFAULT_CONCURRENCY, null);
+ }
+
+ /** Durable variant of the item handler, running one item at a time, with a durable execution config. */
+ public static
+ RequestHandler
+ createDistributedMapItemHandlerWithDurableExecution(
+ DurableItemFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ SerDes resultSerDes,
+ DurableConfig durableConfig) {
+ return createDistributedMapItemHandlerWithDurableExecution(
+ func, itemType, itemSerDes, resultSerDes, DEFAULT_CONCURRENCY, durableConfig);
+ }
+
+ /**
+ * Durable variant of the item handler. The function receives the per-item DurableContext, the item and its
+ * ItemContext.
+ *
+ * @param concurrency the maximum number of items processed at the same time, at least 1. When greater than 1, the
+ * function, itemSerDes and resultSerDes are called from several threads at the same time, so each must be safe
+ * for concurrent calls.
+ */
+ public static
+ RequestHandler
+ createDistributedMapItemHandlerWithDurableExecution(
+ DurableItemFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ SerDes resultSerDes,
+ int concurrency) {
+ return createDistributedMapItemHandlerWithDurableExecution(
+ func, itemType, itemSerDes, resultSerDes, concurrency, null);
+ }
+
+ /**
+ * Durable variant of the item handler. The function receives the per-item DurableContext, the item and its
+ * ItemContext.
+ *
+ * @param concurrency the maximum number of items processed at the same time, at least 1. When greater than 1, the
+ * function, itemSerDes and resultSerDes are called from several threads at the same time, so each must be safe
+ * for concurrent calls.
+ * @param durableConfig the config the wrapped durable execution runs under, for example to register plugins or
+ * supply a client. A null uses DurableConfig.defaultConfig.
+ */
+ public static
+ RequestHandler
+ createDistributedMapItemHandlerWithDurableExecution(
+ DurableItemFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ SerDes resultSerDes,
+ int concurrency,
+ DurableConfig durableConfig) {
+ validateConcurrency(concurrency);
+ var inSerdes = itemSerDes != null ? itemSerDes : JSON;
+ var outSerdes = resultSerDes != null ? resultSerDes : JSON;
+ return DurableExecutor.wrap(
+ EVENT_TYPE,
+ (event, ctx) -> {
+ var records = event.records();
+ var bodies = new ArrayList(records.size());
+ for (var record : records) {
+ bodies.add(record.body());
+ }
+ MapResult batch = ctx.map(
+ ITEMS_OP_NAME,
+ bodies,
+ OUTPUT_TYPE,
+ (body, index, mapContext) -> {
+ var itemContext = new ItemContext(
+ event.distributedMapRunArn(),
+ records.get(index).itemId());
+ O output = func.apply(mapContext, toItem(inSerdes, body, itemType), itemContext);
+ return toOutput(outSerdes, output);
+ },
+ MapConfig.builder()
+ .completionConfig(CompletionConfig.allCompleted())
+ .maxConcurrency(concurrency)
+ .build());
+
+ var results = new ArrayList();
+ var failures = new ArrayList();
+ for (var i = 0; i < records.size(); i++) {
+ var itemId = records.get(i).itemId();
+ var item = batch.getItem(i);
+ if (item.status() == MapResult.MapResultItem.Status.SUCCEEDED) {
+ results.add(new ItemResult(itemId, item.result()));
+ } else {
+ var error = item.error();
+ failures.add(new ItemFailure(
+ itemId,
+ error != null
+ ? new DistributedMapError(
+ error.errorType(), error.errorMessage(), null, error.stackTrace())
+ : null));
+ }
+ }
+ return new ItemHandlerResponse(results, failures);
+ },
+ configOrDefault(durableConfig));
+ }
+
+ /**
+ * Durable variant of the batch handler. The function receives the DurableContext, the items and their BatchContext.
+ */
+ public static
+ RequestHandler
+ createDistributedMapBatchHandlerWithDurableExecution(
+ DurableBatchFunction func, TypeToken itemType, SerDes itemSerDes) {
+ return createDistributedMapBatchHandlerWithDurableExecution(func, itemType, itemSerDes, null);
+ }
+
+ /**
+ * Durable variant of the batch handler. The function receives the DurableContext, the items and their BatchContext.
+ *
+ * @param durableConfig the config the wrapped durable execution runs under, for example to register plugins or
+ * supply a client. A null uses DurableConfig.defaultConfig.
+ */
+ public static
+ RequestHandler
+ createDistributedMapBatchHandlerWithDurableExecution(
+ DurableBatchFunction func,
+ TypeToken itemType,
+ SerDes itemSerDes,
+ DurableConfig durableConfig) {
+ var serdes = itemSerDes != null ? itemSerDes : JSON;
+ return DurableExecutor.wrap(
+ EVENT_TYPE,
+ (event, ctx) -> {
+ func.accept(
+ ctx,
+ toItems(serdes, event, itemType),
+ new BatchContext(
+ event.distributedMapRunArn(),
+ event.records().stream()
+ .map(ProcessorRecord::itemId)
+ .toList()));
+ return null;
+ },
+ configOrDefault(durableConfig));
+ }
+
+ private static DurableConfig configOrDefault(DurableConfig durableConfig) {
+ return durableConfig != null ? durableConfig : DurableConfig.defaultConfig();
+ }
+
+ private static List toItems(SerDes serdes, ProcessorEvent event, TypeToken itemType) {
+ var records = event.records();
+ var items = new ArrayList(records.size());
+ for (var record : records) {
+ items.add(toItem(serdes, record.body(), itemType));
+ }
+ return items;
+ }
+
+ private static I toItem(SerDes serdes, String body, TypeToken itemType) {
+ return serdes.deserialize(body, itemType);
+ }
+
+ /** Serializes an item's output, or returns null when the handler returned nothing. */
+ private static String toOutput(SerDes serdes, Object output) {
+ if (output == null) {
+ return null;
+ }
+ var body = serdes.serialize(output);
+ if (body == null) {
+ throw new IllegalStateException("serialization of item output produced no string");
+ }
+ return body;
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemContext.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemContext.java
new file mode 100644
index 0000000000..9c885b9d0c
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemContext.java
@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+/**
+ * The context an item function receives with one item.
+ *
+ * @param distributedMapRunArn the ARN of the distributed map run the item belongs to
+ * @param itemId the item's identifier, assigned by the service
+ */
+public record ItemContext(String distributedMapRunArn, String itemId) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemFailure.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemFailure.java
new file mode 100644
index 0000000000..f989607407
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemFailure.java
@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import software.amazon.lambda.durable.model.DistributedMapError;
+
+/**
+ * A failed item in a processor response.
+ *
+ * @param itemIdentifier the item's identifier, copied from the input record
+ * @param error why the item failed, or null to report a failure with no detail
+ */
+public record ItemFailure(String itemIdentifier, DistributedMapError error) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemHandlerResponse.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemHandlerResponse.java
new file mode 100644
index 0000000000..acb9d80a28
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemHandlerResponse.java
@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import java.util.List;
+
+/**
+ * The reply an item handler returns.
+ *
+ * A null list is omitted from the JSON rather than sent as null, because the Lambda runtime's serializer excludes
+ * null fields. The service treats an absent, null, or empty list identically, so this is a shape choice rather than a
+ * behavioural one.
+ *
+ * @param batchItemResults per-item outputs, or null to leave the key off the wire
+ * @param batchItemFailures the items that failed
+ */
+public record ItemHandlerResponse(List batchItemResults, List batchItemFailures) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemResult.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemResult.java
new file mode 100644
index 0000000000..82d50f25f0
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ItemResult.java
@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+/**
+ * A succeeded item in a processor response.
+ *
+ * @param itemIdentifier the item's identifier, copied from the input record
+ * @param output the item's output as the result serdes produced it, or null when the handler returned nothing. A null
+ * output means the item succeeded without an output.
+ */
+public record ItemResult(String itemIdentifier, String output) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorEvent.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorEvent.java
new file mode 100644
index 0000000000..53489873d3
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorEvent.java
@@ -0,0 +1,30 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import java.util.List;
+
+/**
+ * The batch the fan-out service sends to a processor function.
+ *
+ * @param distributedMapRunArn the ARN of the distributed map run this batch belongs to
+ * @param records the items in this batch
+ */
+public record ProcessorEvent(String distributedMapRunArn, List records) {
+
+ /**
+ * Rejects an event that is not a processor batch. This runs on instances the Lambda runtime deserializes as well as
+ * on hand-constructed ones, because a record can only be built through its canonical constructor.
+ */
+ public ProcessorEvent {
+ if (records == null) {
+ throw new IllegalStateException("expected a distributed map processor event carrying a 'records' array, "
+ + "the function must be triggered by a distributed map, not invoked directly. An event source "
+ + "such as SQS or S3 sends a capitalised 'Records' array, which is a different contract");
+ }
+ if (distributedMapRunArn == null || distributedMapRunArn.isEmpty()) {
+ throw new IllegalStateException(
+ "expected a distributed map processor event to have a 'distributedMapRunArn'");
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorRecord.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorRecord.java
new file mode 100644
index 0000000000..c4e331fc0c
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ProcessorRecord.java
@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+/**
+ * One record of a processor event.
+ *
+ * @param itemId the item's identifier, assigned by the service
+ * @param body the serialized item, as the item serdes produced it
+ */
+public record ProcessorRecord(String itemId, String body) {
+
+ /**
+ * Rejects a record with no item id. The wrappers report each outcome against this id, so a record without one would
+ * report its outcome against no item. This runs on instances the Lambda runtime deserializes as well.
+ */
+ public ProcessorRecord {
+ if (itemId == null || itemId.isEmpty()) {
+ throw new IllegalStateException("expected each distributed map processor record to have an 'itemId'");
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderContext.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderContext.java
new file mode 100644
index 0000000000..e1b0dca219
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderContext.java
@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+/**
+ * The context a reader function receives with each page request.
+ *
+ * @param distributedMapRunArn the ARN of the distributed map run the page is read for
+ */
+public record ReaderContext(String distributedMapRunArn) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderEvent.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderEvent.java
new file mode 100644
index 0000000000..15de692964
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderEvent.java
@@ -0,0 +1,26 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+/**
+ * The request the fan-out service sends to a reader function.
+ *
+ * @param distributedMapRunArn the ARN of the distributed map run this page is read for
+ * @param maxItemsPerPage the most items the reader may return in this page. Boxed because the Lambda runtime turns an
+ * absent primitive into zero, which would be indistinguishable from a real value
+ * @param state the opaque state from the previous call, or null on the first call
+ */
+public record ReaderEvent(String distributedMapRunArn, Integer maxItemsPerPage, String state) {
+
+ /** Rejects an event that is not a reader request. Runs on runtime-deserialized instances too. */
+ public ReaderEvent {
+ if (maxItemsPerPage == null) {
+ throw new IllegalStateException(
+ "expected a distributed map reader event carrying a numeric 'maxItemsPerPage', "
+ + "the function must be registered as a distributed map reader");
+ }
+ if (distributedMapRunArn == null || distributedMapRunArn.isEmpty()) {
+ throw new IllegalStateException("expected a distributed map reader event to have a 'distributedMapRunArn'");
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderPage.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderPage.java
new file mode 100644
index 0000000000..1c428ffbd2
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderPage.java
@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/** A page of items and the next state returned by a distributed map reader function. */
+public record ReaderPage(List items, S nextState) {
+
+ /** Applies a defensive copy and defaults. */
+ public ReaderPage {
+ // A null item is valid and is sent as the JSON literal null. List.copyOf rejects null elements.
+ items = items != null ? Collections.unmodifiableList(new ArrayList<>(items)) : Collections.emptyList();
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderResponse.java b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderResponse.java
new file mode 100644
index 0000000000..721434dfe1
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/dmap/ReaderResponse.java
@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import java.util.List;
+
+/**
+ * The page a reader function returns.
+ *
+ * A null nextState is omitted from the JSON rather than sent as null, because the Lambda runtime's serializer
+ * excludes null fields. Omitting the key is how the reader contract signals that the source is exhausted.
+ *
+ * @param items this page's items, each serialized with the reader's item serdes
+ * @param nextState the state to resume from, or null when the source is exhausted
+ */
+public record ReaderResponse(List items, String nextState) {}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/exception/DistributedMapException.java b/sdk/src/main/java/software/amazon/lambda/durable/exception/DistributedMapException.java
new file mode 100644
index 0000000000..3a29a47d61
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/exception/DistributedMapException.java
@@ -0,0 +1,75 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.exception;
+
+import software.amazon.lambda.durable.model.DistributedMapError;
+import software.amazon.lambda.durable.model.DistributedMapStatus;
+
+/**
+ * Thrown by throwIfError when a distributed map run did not fully succeed, or when an item failed on a run that
+ * otherwise succeeded. It reports an aggregate run result and is not a single operation failure, so it stays out of the
+ * DurableOperationException hierarchy.
+ */
+public class DistributedMapException extends DurableExecutionException {
+ private final DistributedMapStatus status;
+ private final DistributedMapError error;
+ private final long failureCount;
+
+ /** Run outcome failure describing the run status, failure count, and the run's error details. */
+ public DistributedMapException(DistributedMapStatus status, long failureCount, DistributedMapError error) {
+ super(runMessage(status, failureCount, error));
+ this.status = status;
+ this.error = error;
+ this.failureCount = failureCount;
+ }
+
+ /** Item failure surfacing the first failed item's error. */
+ public DistributedMapException(
+ DistributedMapStatus status, long failureCount, DistributedMapError error, String itemId) {
+ super(itemMessage(error, itemId));
+ this.status = status;
+ this.error = error;
+ this.failureCount = failureCount;
+ }
+
+ /** Returns the terminal run status. */
+ public DistributedMapStatus status() {
+ return status;
+ }
+
+ /** Returns the error details, or null when none were recorded. */
+ public DistributedMapError error() {
+ return error;
+ }
+
+ /** Returns the count of failed items. */
+ public long failureCount() {
+ return failureCount;
+ }
+
+ private static String runMessage(DistributedMapStatus status, long failureCount, DistributedMapError error) {
+ var message = new StringBuilder("Distributed map run ").append(status);
+ if (failureCount > 0) {
+ message.append(", ").append(failureCount).append(" item(s) failed");
+ }
+ if (error != null && error.errorMessage() != null) {
+ message.append(": ").append(error.errorMessage());
+ }
+ return message.toString();
+ }
+
+ private static String itemMessage(DistributedMapError error, String itemId) {
+ var type = error != null ? error.errorType() : null;
+ var message = error != null ? error.errorMessage() : null;
+ var hasType = type != null && !type.isEmpty();
+ var hasMessage = message != null && !message.isEmpty();
+ var result = new StringBuilder("Distributed map item ").append(itemId).append(" failed");
+ if (hasType) {
+ result.append(": ").append(type);
+ }
+ if (hasMessage) {
+ result.append(": ").append(message);
+ }
+ return result.toString();
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/execution/CheckpointManager.java b/sdk/src/main/java/software/amazon/lambda/durable/execution/CheckpointManager.java
index e3a0dd0b30..f4fd0f9390 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/execution/CheckpointManager.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/execution/CheckpointManager.java
@@ -5,6 +5,7 @@
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
+import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.Map;
@@ -17,6 +18,8 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.awscore.exception.AwsServiceException;
+import software.amazon.awssdk.core.SdkField;
+import software.amazon.awssdk.core.SdkPojo;
import software.amazon.awssdk.services.lambda.model.CheckpointUpdatedExecutionState;
import software.amazon.awssdk.services.lambda.model.Operation;
import software.amazon.awssdk.services.lambda.model.OperationType;
@@ -451,6 +454,7 @@ private static int estimateSize(OperationUpdate update) {
+ update.type().toString().length()
+ update.action().toString().length()
+ (update.payload() != null ? update.payload().length() : 0)
+ + stringSize(update.distributedMapOptions())
+ 100;
var options = update.chainedInvokeOptions();
if (options != null) {
@@ -480,4 +484,40 @@ private static long jsonStringFieldSize(String name, String value) {
}
return size;
}
+
+ /**
+ * Total length of every string in a model object, including nested objects, lists and maps. A distributed map START
+ * update carries its customer-supplied values (inline items, reader state, CSV headers, S3 locations, function
+ * names) in its options rather than the payload, so they are counted here.
+ */
+ private static int stringSize(Object value) {
+ if (value == null) {
+ return 0;
+ }
+ if (value instanceof String string) {
+ return string.length();
+ }
+ if (value instanceof SdkPojo pojo) {
+ var size = 0;
+ for (SdkField> field : pojo.sdkFields()) {
+ size += stringSize(field.getValueOrDefault(pojo));
+ }
+ return size;
+ }
+ if (value instanceof Collection> collection) {
+ var size = 0;
+ for (var element : collection) {
+ size += stringSize(element);
+ }
+ return size;
+ }
+ if (value instanceof Map, ?> map) {
+ var size = 0;
+ for (var entry : map.entrySet()) {
+ size += stringSize(entry.getKey()) + stringSize(entry.getValue());
+ }
+ return size;
+ }
+ return 0;
+ }
}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/execution/DurableExecutor.java b/sdk/src/main/java/software/amazon/lambda/durable/execution/DurableExecutor.java
index 64fe95c5a2..4c7a13ff99 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/execution/DurableExecutor.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/execution/DurableExecutor.java
@@ -29,6 +29,7 @@
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.TypeToken;
import software.amazon.lambda.durable.context.DurableContextImpl;
+import software.amazon.lambda.durable.dmap.ProcessorEvent;
import software.amazon.lambda.durable.exception.DurableOperationException;
import software.amazon.lambda.durable.exception.IllegalDurableOperationException;
import software.amazon.lambda.durable.exception.UnrecoverableDurableExecutionException;
@@ -41,6 +42,7 @@
import software.amazon.lambda.durable.plugin.InvocationStatus;
import software.amazon.lambda.durable.plugin.PluginInfoConverter;
import software.amazon.lambda.durable.plugin.PluginRunner;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
import software.amazon.lambda.durable.serde.SerDes;
import software.amazon.lambda.durable.util.ExceptionHelper;
@@ -58,6 +60,7 @@ public class DurableExecutor {
// Lambda response size limit is 6MB minus small epsilon for envelope
private static final int LAMBDA_RESPONSE_SIZE_LIMIT = 6 * 1024 * 1024 - 50;
+ private static final SerDes JSON = new JacksonSerDes();
private DurableExecutor() {}
@@ -96,6 +99,7 @@ private static final class Invocation {
private final DurableConfig config;
private final ExecutionManager manager;
private final PluginRunner plugins;
+ private final SerDes invocationSerDes;
private final String requestId;
private final String executionArn;
private final boolean isFirstInvocation;
@@ -117,6 +121,9 @@ private Invocation(
this.config = config;
this.manager = manager;
plugins = manager.getPluginRunner();
+ // A distributed map processor's input and result have a format the service defines, so a customer's SerDes
+ // must not change them. Durable operations inside the processor still use the config's SerDes.
+ invocationSerDes = inputType.getType() == ProcessorEvent.class ? JSON : config.getSerDes();
// Read on the runtime caller before executor dispatch: LMI carriers can be thread-local.
xRayTraceId = plugins.isEmpty() ? null : RuntimeTraceHeader.capture(lambdaContext);
requestId = lambdaContext != null ? lambdaContext.getAwsRequestId() : null;
@@ -167,7 +174,7 @@ private O invokeHandler() {
manager.setCurrentThreadContext(new ThreadContext(ROOT_THREAD_ID, ThreadType.CONTEXT));
Throwable inputFailure = null;
try {
- userInput = extractUserInput(manager.getExecutionOperation(), config.getSerDes(), inputType);
+ userInput = extractUserInput(manager.getExecutionOperation(), invocationSerDes, inputType);
} catch (Throwable failure) {
// Deserialize only once. Even failed input gets paired start/end hooks with a null input value.
inputFailure = failure;
@@ -212,7 +219,7 @@ private DurableExecutionOutput finishInvocation(O value, Throwable failure) {
if (failure != null) return finishFailure(ExceptionHelper.unwrapInvocationFailure(failure));
DurableExecutionOutput output;
try {
- var payload = config.getSerDes().serialize(value);
+ var payload = invocationSerDes.serialize(value);
output = DurableExecutionOutput.success(handleLargePayload(manager, payload));
} catch (Throwable deliveryFailure) {
// Checkpointing a large result fails with SuspendExecutionException when the token is already gone.
@@ -250,7 +257,7 @@ private DurableExecutionOutput finishTerminalFailure(Throwable cause) {
DurableExecutionOutput output;
try {
logger.debug("Execution failed: {}", cause.getMessage());
- output = DurableExecutionOutput.failure(buildErrorObject(cause, config.getSerDes()));
+ output = DurableExecutionOutput.failure(buildErrorObject(cause, invocationSerDes));
} catch (Throwable deliveryFailure) {
return failDelivery(deliveryFailure);
}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapError.java b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapError.java
new file mode 100644
index 0000000000..5b14bc2f7f
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapError.java
@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.model;
+
+import java.util.List;
+import software.amazon.lambda.durable.util.ExceptionHelper;
+
+/**
+ * Error details on a distributed map run or one of its items.
+ *
+ * Held as a record rather than the client's ErrorObject, so it survives serialization across checkpoint-and-replay
+ * cycles without requiring AWS SDK-specific Jackson modules.
+ */
+public record DistributedMapError(String errorType, String errorMessage, String errorData, List stackTrace) {
+
+ /** Creates an error from a throwable. */
+ public static DistributedMapError of(Throwable e) {
+ // errorData stays null. A throwable carries no machine-readable error data, so there is nothing to put here.
+ return new DistributedMapError(
+ e.getClass().getName(), e.getMessage(), null, ExceptionHelper.serializeStackTrace(e.getStackTrace()));
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapResult.java b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapResult.java
new file mode 100644
index 0000000000..917bc12dc8
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapResult.java
@@ -0,0 +1,140 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.model;
+
+import java.util.Collections;
+import java.util.List;
+import software.amazon.lambda.durable.exception.DistributedMapException;
+
+/**
+ * Outcome of a distributed map run with collected per-item results.
+ *
+ * An item whose status this SDK version does not recognize is kept in {@code items} with status
+ * {@link Item.Status#UNKNOWN_TO_SDK_VERSION}. It is excluded from {@link #succeeded()}, {@link #failed()},
+ * {@link #results()} and {@link #errors()}.
+ */
+public record DistributedMapResult(DistributedMapSummary summary, List- > items) {
+
+ /** Applies a defensive copy and defaults. */
+ public DistributedMapResult {
+ items = items != null ? List.copyOf(items) : Collections.emptyList();
+ }
+
+ /** Returns items that succeeded. */
+ public List
- > succeeded() {
+ return items.stream()
+ .filter(item -> item.status() == Item.Status.SUCCEEDED)
+ .toList();
+ }
+
+ /** Returns items that failed. */
+ public List
- > failed() {
+ return items.stream()
+ .filter(item -> item.status() == Item.Status.FAILED)
+ .toList();
+ }
+
+ /** Returns the outputs of succeeded items (includes null outputs from successful items). */
+ public List results() {
+ return succeeded().stream().map(Item::output).toList();
+ }
+
+ /** Returns the errors of failed items (includes nulls for items that failed without error details). */
+ public List errors() {
+ return failed().stream().map(Item::error).toList();
+ }
+
+ /** Returns the terminal run status. */
+ public DistributedMapStatus status() {
+ return summary.status();
+ }
+
+ /** Returns true only when the service read the complete source, or null before run creation. */
+ public Boolean sourceExhausted() {
+ return summary.sourceExhausted();
+ }
+
+ /** Returns the count of succeeded items. */
+ public long successCount() {
+ return summary.successCount();
+ }
+
+ /** Returns the count of failed items. */
+ public long failureCount() {
+ return summary.failureCount();
+ }
+
+ /**
+ * Returns the number of items the run read from its source. For an inline source, every admitted item counts as
+ * read when the run starts.
+ */
+ public long readCount() {
+ return summary.readCount();
+ }
+
+ /** Returns the total item count, or null until known. */
+ public Long totalCount() {
+ return summary.totalCount();
+ }
+
+ /** Returns the run ARN, or null when the run never started. */
+ public String distributedMapRunArn() {
+ return summary.distributedMapRunArn();
+ }
+
+ /** Returns why the run did not succeed, or null when the service recorded no error details. */
+ public DistributedMapError error() {
+ return summary.error();
+ }
+
+ /** Returns true when any item failed. */
+ public boolean hasFailure() {
+ return summary.hasFailure();
+ }
+
+ /**
+ * Throws DistributedMapException when the run did not succeed or any item failed. When the run succeeded and the
+ * result contains a failed item, the exception names the first failed item.
+ */
+ public void throwIfError() {
+ if (summary.status() != DistributedMapStatus.SUCCEEDED) {
+ summary.throwIfError();
+ return;
+ }
+ var failedItems = failed();
+ if (!failedItems.isEmpty()) {
+ var first = failedItems.get(0);
+ throw new DistributedMapException(summary.status(), summary.failureCount(), first.error(), first.itemId());
+ }
+ if (summary.hasFailure()) {
+ summary.throwIfError();
+ }
+ }
+
+ /** Outcome of a single distributed map item. */
+ public record Item(String itemId, Status status, O output, DistributedMapError error) {
+
+ /** Status of an individual distributed map item. */
+ public enum Status {
+ SUCCEEDED,
+ FAILED,
+ /** A status the backend returned that this SDK version does not recognize. */
+ UNKNOWN_TO_SDK_VERSION
+ }
+
+ /** Creates a succeeded item. */
+ public static Item succeeded(String itemId, O output) {
+ return new Item<>(itemId, Status.SUCCEEDED, output, null);
+ }
+
+ /** Creates a failed item. */
+ public static Item failed(String itemId, DistributedMapError error) {
+ return new Item<>(itemId, Status.FAILED, null, error);
+ }
+
+ /** Creates an item whose status this SDK version does not recognize. */
+ public static Item unknown(String itemId) {
+ return new Item<>(itemId, Status.UNKNOWN_TO_SDK_VERSION, null, null);
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapStatus.java b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapStatus.java
new file mode 100644
index 0000000000..421f6e836b
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapStatus.java
@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.model;
+
+/** Terminal status of a distributed map run. */
+public enum DistributedMapStatus {
+ SUCCEEDED,
+ FAILED,
+ STOPPED,
+ TIMED_OUT
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapSummary.java b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapSummary.java
new file mode 100644
index 0000000000..98c1ae354c
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/model/DistributedMapSummary.java
@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.model;
+
+import software.amazon.lambda.durable.exception.DistributedMapException;
+
+/**
+ * Outcome of a distributed map run, without per-item results.
+ *
+ * @param sourceExhausted true only when the service read the complete source, null before run creation
+ * @param readCount number of items the run read from its source; for an inline source, every admitted item counts as
+ * read when the run starts
+ * @param error why the run did not succeed, when the service recorded error details
+ */
+public record DistributedMapSummary(
+ DistributedMapStatus status,
+ Boolean sourceExhausted,
+ long successCount,
+ long failureCount,
+ long readCount,
+ String distributedMapRunArn,
+ DistributedMapError error,
+ Long totalCount) {
+
+ /** Returns true when any item failed. */
+ public boolean hasFailure() {
+ return failureCount > 0;
+ }
+
+ /** Throws DistributedMapException when the run did not fully succeed. */
+ public void throwIfError() {
+ if (status != DistributedMapStatus.SUCCEEDED || hasFailure()) {
+ throw new DistributedMapException(status, failureCount, error);
+ }
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/model/OperationSubType.java b/sdk/src/main/java/software/amazon/lambda/durable/model/OperationSubType.java
index c7273b9cde..8ebf4968e3 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/model/OperationSubType.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/model/OperationSubType.java
@@ -22,7 +22,8 @@ public enum OperationSubType {
PARALLEL_BRANCH(OperationType.CONTEXT, "ParallelBranch"),
WAIT_FOR_CALLBACK(OperationType.CONTEXT, "WaitForCallback"),
WAIT_FOR_CONDITION(OperationType.STEP, "WaitForCondition"),
- WITH_RETRY(OperationType.CONTEXT, "WithRetry");
+ WITH_RETRY(OperationType.CONTEXT, "WithRetry"),
+ DISTRIBUTED_MAP(OperationType.DISTRIBUTED_MAP, "DistributedMap");
private final OperationType operationType;
private final String value;
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/operation/BaseDurableOperation.java b/sdk/src/main/java/software/amazon/lambda/durable/operation/BaseDurableOperation.java
index cd884796e9..cf2af168ca 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/operation/BaseDurableOperation.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/operation/BaseDurableOperation.java
@@ -685,6 +685,10 @@ public static ErrorObject getErrorObject(Operation operation) {
: null;
case CONTEXT ->
operation.contextDetails() != null ? operation.contextDetails().error() : null;
+ case DISTRIBUTED_MAP ->
+ operation.distributedMapDetails() != null
+ ? operation.distributedMapDetails().error()
+ : null;
default -> null;
};
}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/operation/ChildContextOperation.java b/sdk/src/main/java/software/amazon/lambda/durable/operation/ChildContextOperation.java
index 062079ed8d..02ac1ca6ba 100644
--- a/sdk/src/main/java/software/amazon/lambda/durable/operation/ChildContextOperation.java
+++ b/sdk/src/main/java/software/amazon/lambda/durable/operation/ChildContextOperation.java
@@ -260,7 +260,7 @@ private Throwable translateException(Operation op, ErrorObject errorObject) {
case RUN_IN_CHILD_CONTEXT, WITH_RETRY -> new ChildContextFailedException(op);
// the following subtypes should not be able to reach here
- case PARALLEL, MAP, WAIT_FOR_CONDITION, STEP, WAIT, CALLBACK, CHAINED_INVOKE ->
+ case PARALLEL, MAP, WAIT_FOR_CONDITION, STEP, WAIT, CALLBACK, CHAINED_INVOKE, DISTRIBUTED_MAP ->
new IllegalStateException("Unexpected sub-type: " + getSubType());
};
}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/operation/DistributedMapOperation.java b/sdk/src/main/java/software/amazon/lambda/durable/operation/DistributedMapOperation.java
new file mode 100644
index 0000000000..16bac6aba8
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/operation/DistributedMapOperation.java
@@ -0,0 +1,436 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.operation;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.BiFunction;
+import software.amazon.awssdk.services.lambda.model.DistributedMapCsvDelimiter;
+import software.amazon.awssdk.services.lambda.model.DistributedMapCsvFormatOptions;
+import software.amazon.awssdk.services.lambda.model.DistributedMapCsvHeaderLocation;
+import software.amazon.awssdk.services.lambda.model.DistributedMapDestinationType;
+import software.amazon.awssdk.services.lambda.model.DistributedMapDetails;
+import software.amazon.awssdk.services.lambda.model.DistributedMapFunctionResponseType;
+import software.amazon.awssdk.services.lambda.model.DistributedMapInlineSourceConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapOnFailureConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapOnFailureInclude;
+import software.amazon.awssdk.services.lambda.model.DistributedMapOnSuccessConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapOnSuccessInclude;
+import software.amazon.awssdk.services.lambda.model.DistributedMapOptions;
+import software.amazon.awssdk.services.lambda.model.DistributedMapProcessorConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapReaderFunctionSourceConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapResultCollectionConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapResultCollectionMode;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3DestinationConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3ListedObjectMetadataConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3ListedObjectsConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3ObjectConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3SourceConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapS3SourceType;
+import software.amazon.awssdk.services.lambda.model.DistributedMapSourceConfig;
+import software.amazon.awssdk.services.lambda.model.DistributedMapSourceFormat;
+import software.amazon.awssdk.services.lambda.model.DistributedMapSourceType;
+import software.amazon.awssdk.services.lambda.model.ErrorObject;
+import software.amazon.awssdk.services.lambda.model.Operation;
+import software.amazon.awssdk.services.lambda.model.OperationAction;
+import software.amazon.awssdk.services.lambda.model.OperationStatus;
+import software.amazon.awssdk.services.lambda.model.OperationUpdate;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.config.DistributedMapConfig;
+import software.amazon.lambda.durable.config.DistributedMapDestination;
+import software.amazon.lambda.durable.config.DistributedMapProcessor;
+import software.amazon.lambda.durable.config.DistributedMapSource;
+import software.amazon.lambda.durable.context.DurableContextImpl;
+import software.amazon.lambda.durable.exception.DurableExecutionException;
+import software.amazon.lambda.durable.model.DistributedMapError;
+import software.amazon.lambda.durable.model.DistributedMapResult;
+import software.amazon.lambda.durable.model.DistributedMapStatus;
+import software.amazon.lambda.durable.model.DistributedMapSummary;
+import software.amazon.lambda.durable.model.OperationIdentifier;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+import software.amazon.lambda.durable.serde.SerDes;
+
+/**
+ * Durable operation that starts a distributed map run and waits for its terminal outcome.
+ *
+ * @param the resolved result type (a summary, or a result with collected items)
+ */
+public class DistributedMapOperation extends SerializableDurableOperation {
+ private final DistributedMapOptions options;
+ private final BiFunction resultBuilder;
+
+ private static final SerDes JSON = new JacksonSerDes();
+ private static final long INLINE_SIZE_LIMIT = 1024L * 1024L;
+ private static final long READER_STATE_LIMIT = 32L * 1024L;
+
+ public DistributedMapOperation(
+ OperationIdentifier operationIdentifier,
+ DistributedMapOptions options,
+ TypeToken resultType,
+ SerDes serDes,
+ BiFunction resultBuilder,
+ DurableContextImpl durableContext) {
+ super(operationIdentifier, resultType, serDes, durableContext);
+ this.options = options;
+ this.resultBuilder = resultBuilder;
+ }
+
+ /** Starts the operation. */
+ @Override
+ protected void start() {
+ sendOperationUpdate(
+ OperationUpdate.builder().action(OperationAction.START).distributedMapOptions(options));
+ pollUntilTerminal();
+ }
+
+ /** Replays the operation. */
+ @Override
+ protected void replay(Operation existing) {
+ switch (existing.status()) {
+ // The start checkpoint records the operation as PENDING, and it reaches STARTED only once the
+ // service confirms the run was created. A replay in that window waits for the outcome.
+ case PENDING, STARTED -> pollUntilTerminal();
+ case SUCCEEDED, FAILED, TIMED_OUT, STOPPED -> markAlreadyCompleted();
+ default ->
+ throw terminateExecutionWithIllegalDurableOperationException(
+ "Unexpected distributed map status: " + existing.statusAsString());
+ }
+ }
+
+ /**
+ * Polls until the operation reaches a terminal status. A poll completes on any update, so a PENDING to STARTED
+ * update would otherwise end polling while get() is still waiting for the outcome.
+ */
+ private void pollUntilTerminal() {
+ pollForOperationUpdates().thenAccept(op -> {
+ if (op != null && (op.status() == OperationStatus.PENDING || op.status() == OperationStatus.STARTED)) {
+ pollUntilTerminal();
+ }
+ });
+ }
+
+ /** Blocks until the operation completes and returns the resolved outcome. */
+ @Override
+ public R get() {
+ var op = waitForOperationCompletion();
+ // An unsuccessful run resolves with its summary, so callers can read the counts. Use
+ // DistributedMapSummary.throwIfError to opt into raising instead.
+ var runStatus = switch (op.status()) {
+ case SUCCEEDED -> DistributedMapStatus.SUCCEEDED;
+ case FAILED -> DistributedMapStatus.FAILED;
+ case TIMED_OUT -> DistributedMapStatus.TIMED_OUT;
+ case STOPPED -> DistributedMapStatus.STOPPED;
+ default ->
+ throw terminateExecutionWithIllegalDurableOperationException(
+ "Unexpected distributed map operation status: " + op.statusAsString());
+ };
+ var details = op.distributedMapDetails();
+ if (details == null) {
+ throw terminateExecutionWithIllegalDurableOperationException("DISTRIBUTED_MAP operation reached "
+ + op.statusAsString() + " but carried no DistributedMapDetails");
+ }
+ // SourceExhausted is required at terminal once a run exists, and is absent only when the operation
+ // failed before one was created, which is also when the run ARN is absent.
+ if (details.distributedMapRunArn() != null && details.sourceExhausted() == null) {
+ throw terminateExecutionWithIllegalDurableOperationException(
+ "DISTRIBUTED_MAP operation reached " + op.statusAsString() + " but carried no SourceExhausted");
+ }
+ return resultBuilder.apply(runStatus, details);
+ }
+
+ public static DistributedMapOptions toOptions(
+ DistributedMapSource> source,
+ DistributedMapProcessor processor,
+ int maxConcurrency,
+ DistributedMapConfig config,
+ SerDes defaultSerDes,
+ boolean collectResults) {
+ var builder = DistributedMapOptions.builder()
+ .maxConcurrency(maxConcurrency)
+ .source(sourceConfig(source, defaultSerDes))
+ .processor(processorConfig(processor));
+ if (config.destination() != null) {
+ var destination = destinationConfig(config.destination());
+ if (destination != null) {
+ builder.destination(destination);
+ }
+ }
+ var completion = completionConfig(config);
+ if (completion != null) {
+ builder.completionConfig(completion);
+ }
+ if (collectResults) {
+ builder.resultCollection(DistributedMapResultCollectionConfig.builder()
+ .mode(DistributedMapResultCollectionMode.INLINE)
+ .build());
+ }
+ if (config.timeout() != null) {
+ builder.timeoutSeconds((int) config.timeout().toSeconds());
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapSourceConfig sourceConfig(DistributedMapSource> source, SerDes defaultSerDes) {
+ var builder = DistributedMapSourceConfig.builder()
+ .type(DistributedMapSourceType.fromValue(source.sourceType().name()));
+ if (source.maxItems() != null) {
+ builder.maxItemsToRead(source.maxItems().longValue());
+ }
+ switch (source.sourceType()) {
+ case INLINE -> builder.inlineSourceConfig(inlineSourceConfig(source, defaultSerDes));
+ case S3 -> builder.s3SourceConfig(s3SourceConfig(source.s3()));
+ case READER_FUNCTION -> builder.readerFunctionSourceConfig(readerConfig(source.reader(), defaultSerDes));
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapInlineSourceConfig inlineSourceConfig(
+ DistributedMapSource> source, SerDes defaultSerDes) {
+ var serdes = source.inlineSerDes() != null ? source.inlineSerDes() : defaultSerDes;
+ var bodies = new ArrayList(source.inlineItems().size());
+ var items = source.inlineItems();
+ for (int index = 0; index < items.size(); index++) {
+ var item = items.get(index);
+ var body = serdes.serialize(item);
+ if (body == null) {
+ // The service requires every item to be a string. The default serdes returns null for a null item,
+ // so a null item is sent as the JSON literal null. Any other item with no serialized form is an error.
+ if (item != null) {
+ throw new IllegalArgumentException("serialization of inline item " + index + " produced no string");
+ }
+ body = "null";
+ }
+ bodies.add(body);
+ }
+ var arrayBytes = JSON.serialize(bodies).getBytes(StandardCharsets.UTF_8).length;
+ if (arrayBytes > INLINE_SIZE_LIMIT) {
+ throw new IllegalArgumentException(
+ "inline source exceeds the 1 MB limit (serialized size: " + arrayBytes + " bytes)");
+ }
+ return DistributedMapInlineSourceConfig.builder().items(bodies).build();
+ }
+
+ private static DistributedMapS3SourceConfig s3SourceConfig(DistributedMapSource.S3SourceConfig s3) {
+ var builder = DistributedMapS3SourceConfig.builder()
+ .type(DistributedMapS3SourceType.fromValue(s3.type().name()))
+ .bucket(s3.bucket());
+ if (s3.expectedBucketOwner() != null) {
+ builder.expectedBucketOwner(s3.expectedBucketOwner());
+ }
+ if (s3.objectConfig() != null) {
+ var object = s3.objectConfig();
+ var block = DistributedMapS3ObjectConfig.builder()
+ .key(object.key())
+ .format(DistributedMapSourceFormat.fromValue(object.format().name()));
+ if (object.csvFormat() != null) {
+ block.csvFormatOptions(csvFormatOptions(object.csvFormat()));
+ }
+ builder.objectConfig(block.build());
+ }
+ if (s3.listedObjectMetadataConfig() != null) {
+ builder.listedObjectMetadataConfig(DistributedMapS3ListedObjectMetadataConfig.builder()
+ .keyPrefix(s3.listedObjectMetadataConfig().keyPrefix())
+ .build());
+ }
+ if (s3.listedObjectsConfig() != null) {
+ var listed = s3.listedObjectsConfig();
+ var block = DistributedMapS3ListedObjectsConfig.builder()
+ .keyPrefix(listed.keyPrefix())
+ .format(DistributedMapSourceFormat.fromValue(listed.format().name()));
+ if (listed.csvFormat() != null) {
+ block.csvFormatOptions(csvFormatOptions(listed.csvFormat()));
+ }
+ builder.listedObjectsConfig(block.build());
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapCsvFormatOptions csvFormatOptions(DistributedMapSource.CsvFormat format) {
+ var builder = DistributedMapCsvFormatOptions.builder()
+ .headerLocation(DistributedMapCsvHeaderLocation.fromValue(
+ format.headerLocation().name()))
+ .delimiter(
+ DistributedMapCsvDelimiter.fromValue(format.delimiter().name()));
+ // Column names go on the wire only for headerless files (GIVEN), expectedColumns (FIRST_ROW) is compile-time
+ // only.
+ if (format.headerLocation() == DistributedMapSource.CsvFormat.HeaderLocation.GIVEN
+ && format.columns() != null) {
+ builder.headers(format.columns());
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapReaderFunctionSourceConfig readerConfig(
+ DistributedMapSource.ReaderSourceConfig reader, SerDes defaultSerDes) {
+ var builder = DistributedMapReaderFunctionSourceConfig.builder().functionName(reader.functionName());
+ if (reader.initialState() != null) {
+ var serdes = reader.stateSerDes() != null ? reader.stateSerDes() : defaultSerDes;
+ var state = serdes.serialize(reader.initialState());
+ if (state == null) {
+ throw new IllegalArgumentException("serialization of reader initialState produced no string");
+ }
+ if (state.getBytes(StandardCharsets.UTF_8).length > READER_STATE_LIMIT) {
+ throw new IllegalArgumentException("reader initialState exceeds the 32 KB limit");
+ }
+ builder.initialState(state);
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapProcessorConfig processorConfig(DistributedMapProcessor processor) {
+ var builder = DistributedMapProcessorConfig.builder().functionName(processor.functionName());
+ if (processor.durableExecutionNamePrefix() != null) {
+ builder.durableExecutionNamePrefix(processor.durableExecutionNamePrefix());
+ }
+ if (processor.responseMode() == DistributedMapProcessor.ResponseMode.ITEM_OUTCOMES) {
+ builder.functionResponseTypes(List.of(DistributedMapFunctionResponseType.REPORT_BATCH_ITEM_OUTCOMES));
+ }
+ if (processor.batchSize() != null) {
+ builder.batchSize(processor.batchSize());
+ }
+ if (processor.retry() != null) {
+ var retry = processor.retry();
+ if (retry.maxRetryAttempts() != null) {
+ builder.maxRetryAttempts(retry.maxRetryAttempts());
+ }
+ if (retry.maxRetryDuration() != null) {
+ builder.maxRetryDurationSeconds((int) retry.maxRetryDuration().toSeconds());
+ }
+ }
+ return builder.build();
+ }
+
+ private static software.amazon.awssdk.services.lambda.model.DistributedMapDestinationConfig destinationConfig(
+ software.amazon.lambda.durable.config.DistributedMapDestination destination) {
+ if (destination.onSuccess() == null && destination.onFailure() == null) {
+ return null; // omit an empty destination config from the wire
+ }
+ var builder = software.amazon.awssdk.services.lambda.model.DistributedMapDestinationConfig.builder();
+ DistributedMapDestination.Success onSuccess = destination.onSuccess();
+ if (onSuccess != null) {
+ var include = new ArrayList();
+ if (onSuccess.includeInput()) {
+ include.add(DistributedMapOnSuccessInclude.INPUT);
+ }
+ if (onSuccess.includeOutput()) {
+ include.add(DistributedMapOnSuccessInclude.OUTPUT);
+ }
+ builder.onSuccess(DistributedMapOnSuccessConfig.builder()
+ .type(DistributedMapDestinationType.S3)
+ .include(include)
+ .s3DestinationConfig(
+ s3Destination(onSuccess.bucket(), onSuccess.prefix(), onSuccess.expectedBucketOwner()))
+ .build());
+ }
+ DistributedMapDestination.Failure onFailure = destination.onFailure();
+ if (onFailure != null) {
+ var include = new ArrayList();
+ if (onFailure.includeInput()) {
+ include.add(DistributedMapOnFailureInclude.INPUT);
+ }
+ if (onFailure.includeError()) {
+ include.add(DistributedMapOnFailureInclude.ERROR);
+ }
+ builder.onFailure(DistributedMapOnFailureConfig.builder()
+ .type(DistributedMapDestinationType.S3)
+ .include(include)
+ .s3DestinationConfig(
+ s3Destination(onFailure.bucket(), onFailure.prefix(), onFailure.expectedBucketOwner()))
+ .build());
+ }
+ return builder.build();
+ }
+
+ private static DistributedMapS3DestinationConfig s3Destination(
+ String bucket, String keyPrefix, String expectedBucketOwner) {
+ var builder = DistributedMapS3DestinationConfig.builder().bucket(bucket).keyPrefix(keyPrefix);
+ if (expectedBucketOwner != null) {
+ builder.expectedBucketOwner(expectedBucketOwner);
+ }
+ return builder.build();
+ }
+
+ private static software.amazon.awssdk.services.lambda.model.DistributedMapCompletionConfig completionConfig(
+ DistributedMapConfig config) {
+ var completion = config.completionConfig();
+ if (completion == null) {
+ return null;
+ }
+ var builder = software.amazon.awssdk.services.lambda.model.DistributedMapCompletionConfig.builder();
+ if (completion.toleratedFailureCount() != null) {
+ builder.toleratedFailureCount(completion.toleratedFailureCount());
+ }
+ if (completion.toleratedFailurePercentage() != null) {
+ builder.toleratedFailurePercentage(
+ completion.toleratedFailurePercentage().floatValue());
+ }
+ if (completion.minimumSampleSize() != null) {
+ builder.minimumSampleSize(completion.minimumSampleSize());
+ }
+ return builder.build();
+ }
+
+ public static DistributedMapSummary toSummary(DistributedMapStatus runStatus, DistributedMapDetails details) {
+ // The service sends all three counts at every terminal state, and TotalCount once the run succeeded.
+ // Reading an absent count as zero would report a run that failed items as having none, so a missing
+ // count is a contract violation rather than a default.
+ var successCount = requireCount(details.successCount(), "SuccessCount");
+ var failureCount = requireCount(details.failureCount(), "FailureCount");
+ var readCount = requireCount(details.readCount(), "ReadCount");
+ if (runStatus == DistributedMapStatus.SUCCEEDED && details.totalCount() == null) {
+ throw new DurableExecutionException("missing distributed map TotalCount from backend");
+ }
+ return new DistributedMapSummary(
+ runStatus,
+ details.sourceExhausted(),
+ successCount,
+ failureCount,
+ readCount,
+ details.distributedMapRunArn(),
+ toError(details.error()),
+ details.totalCount());
+ }
+
+ private static long requireCount(Long count, String field) {
+ if (count == null) {
+ throw new DurableExecutionException("missing distributed map " + field + " from backend");
+ }
+ return count;
+ }
+
+ public static DistributedMapResult toResult(
+ DistributedMapStatus runStatus, DistributedMapDetails details, TypeToken resultType, SerDes serdes) {
+ var summary = toSummary(runStatus, details);
+ var items = new ArrayList>();
+ if (details.results() != null) {
+ for (var wire : details.results()) {
+ if (wire.itemId() == null || wire.itemId().isEmpty()) {
+ throw new DurableExecutionException("missing distributed map item id from backend");
+ }
+ var status = wire.statusAsString();
+ if (status == null) {
+ throw new DurableExecutionException("distributed map item " + wire.itemId()
+ + " has no status, which the service model" + " requires");
+ }
+ if (DistributedMapResult.Item.Status.SUCCEEDED.name().equals(status)) {
+ O output = wire.output() != null ? serdes.deserialize(wire.output(), resultType) : null;
+ items.add(DistributedMapResult.Item.succeeded(wire.itemId(), output));
+ } else if (DistributedMapResult.Item.Status.FAILED.name().equals(status)) {
+ items.add(DistributedMapResult.Item.failed(wire.itemId(), toError(wire.error())));
+ } else {
+ // A status added after this SDK version. Keep the item so the other items survive.
+ items.add(DistributedMapResult.Item.unknown(wire.itemId()));
+ }
+ }
+ }
+ return new DistributedMapResult<>(summary, items);
+ }
+
+ private static DistributedMapError toError(ErrorObject error) {
+ return error == null
+ ? null
+ : new DistributedMapError(
+ error.errorType(), error.errorMessage(), error.errorData(), error.stackTrace());
+ }
+}
diff --git a/sdk/src/main/java/software/amazon/lambda/durable/util/DistributedMapValidation.java b/sdk/src/main/java/software/amazon/lambda/durable/util/DistributedMapValidation.java
new file mode 100644
index 0000000000..b7b1f4fff2
--- /dev/null
+++ b/sdk/src/main/java/software/amazon/lambda/durable/util/DistributedMapValidation.java
@@ -0,0 +1,48 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.util;
+
+import java.util.regex.Pattern;
+
+/** Shared validation and S3 URI parsing for distributed map configuration. */
+public final class DistributedMapValidation {
+ private static final Pattern ACCOUNT_ID = Pattern.compile("\\d{12}");
+ private static final String S3_SCHEME = "s3://";
+ private static final int MAX_FUNCTION_NAME_LENGTH = 170;
+
+ private DistributedMapValidation() {}
+
+ public static void validateFunctionName(String functionName) {
+ if (functionName == null || functionName.isBlank()) {
+ throw new IllegalArgumentException("function name cannot be empty");
+ }
+ if (functionName.length() > MAX_FUNCTION_NAME_LENGTH) {
+ throw new IllegalArgumentException(
+ "function name must be at most 170 characters, got: " + functionName.length());
+ }
+ }
+
+ public static void validateBucketOwner(String expectedBucketOwner) {
+ if (expectedBucketOwner != null
+ && !ACCOUNT_ID.matcher(expectedBucketOwner).matches()) {
+ throw new IllegalArgumentException(
+ "expectedBucketOwner must be a 12-digit account id, got: " + expectedBucketOwner);
+ }
+ }
+
+ public static ParsedS3Uri parseS3Uri(String uri) {
+ if (uri == null || !uri.startsWith(S3_SCHEME)) {
+ throw new IllegalArgumentException("S3 URI must start with s3://, got: " + uri);
+ }
+ var remainder = uri.substring(S3_SCHEME.length());
+ var slash = remainder.indexOf('/');
+ var bucket = slash < 0 ? remainder : remainder.substring(0, slash);
+ var path = slash < 0 ? null : remainder.substring(slash + 1);
+ if (bucket.isEmpty()) {
+ throw new IllegalArgumentException("S3 URI must contain a bucket, got: " + uri);
+ }
+ return new ParsedS3Uri(bucket, path == null || path.isEmpty() ? null : path);
+ }
+
+ public record ParsedS3Uri(String bucket, String path) {}
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapConfigTest.java b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapConfigTest.java
new file mode 100644
index 0000000000..40b1e006ae
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapConfigTest.java
@@ -0,0 +1,132 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+
+class DistributedMapConfigTest {
+
+ @Test
+ void failureCount_setsCount() {
+ var config = DistributedMapConfig.CompletionConfig.failureCount(3);
+
+ assertEquals(3, config.toleratedFailureCount());
+ assertNull(config.toleratedFailurePercentage());
+ assertNull(config.minimumSampleSize());
+ }
+
+ @Test
+ void failureCount_withZero_shouldPass() {
+ assertEquals(0, DistributedMapConfig.CompletionConfig.failureCount(0).toleratedFailureCount());
+ }
+
+ @Test
+ void failurePercentage_setsPercentage() {
+ var config = DistributedMapConfig.CompletionConfig.failurePercentage(25);
+
+ assertNull(config.toleratedFailureCount());
+ assertEquals(25.0, config.toleratedFailurePercentage());
+ assertNull(config.minimumSampleSize());
+ }
+
+ @Test
+ void failurePercentage_fractional_shouldPass() {
+ assertEquals(
+ 12.5,
+ DistributedMapConfig.CompletionConfig.failurePercentage(12.5).toleratedFailurePercentage());
+ }
+
+ @Test
+ void failurePercentage_withMinimumSampleSize_setsBoth() {
+ var config = DistributedMapConfig.CompletionConfig.failurePercentage(25, 10);
+
+ assertEquals(25.0, config.toleratedFailurePercentage());
+ assertEquals(10, config.minimumSampleSize());
+ }
+
+ @Test
+ void failurePercentage_atBoundaries_shouldPass() {
+ assertEquals(
+ 0.0, DistributedMapConfig.CompletionConfig.failurePercentage(0).toleratedFailurePercentage());
+ assertEquals(
+ 100.0,
+ DistributedMapConfig.CompletionConfig.failurePercentage(100).toleratedFailurePercentage());
+ }
+
+ @Test
+ void countAndPercentage_mutuallyExclusive_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> new DistributedMapConfig.CompletionConfig(3, 25.0, null));
+ assertEquals(
+ "toleratedFailureCount and toleratedFailurePercentage are mutually exclusive", exception.getMessage());
+ }
+
+ @Test
+ void minimumSampleSize_withoutPercentage_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> new DistributedMapConfig.CompletionConfig(3, null, 5));
+ assertEquals("minimumSampleSize is only valid with toleratedFailurePercentage", exception.getMessage());
+ }
+
+ @Test
+ void completionConfig_onlyMinimumSampleSize_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> new DistributedMapConfig.CompletionConfig(null, null, 5));
+ assertEquals("minimumSampleSize is only valid with toleratedFailurePercentage", exception.getMessage());
+ }
+
+ @Test
+ void failureCount_negative_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapConfig.CompletionConfig.failureCount(-1));
+ assertEquals("toleratedFailureCount must be non-negative, got: -1", exception.getMessage());
+ }
+
+ @Test
+ void failurePercentage_negative_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapConfig.CompletionConfig.failurePercentage(-0.1));
+ assertEquals("toleratedFailurePercentage must be between 0 and 100, got: -0.1", exception.getMessage());
+ }
+
+ @Test
+ void failurePercentage_aboveHundred_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapConfig.CompletionConfig.failurePercentage(100.1));
+ assertEquals("toleratedFailurePercentage must be between 0 and 100, got: 100.1", exception.getMessage());
+ }
+
+ @Test
+ void failurePercentage_nan_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapConfig.CompletionConfig.failurePercentage(Double.NaN));
+ assertEquals("toleratedFailurePercentage must be a finite number, got: NaN", exception.getMessage());
+ }
+
+ @Test
+ void failurePercentage_infinite_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapConfig.CompletionConfig.failurePercentage(Double.POSITIVE_INFINITY));
+ assertEquals("toleratedFailurePercentage must be a finite number, got: Infinity", exception.getMessage());
+ }
+
+ @Test
+ void minimumSampleSize_belowOne_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapConfig.CompletionConfig.failurePercentage(25, 0));
+ assertEquals("minimumSampleSize must be at least 1, got: 0", exception.getMessage());
+ }
+
+ @Test
+ void emptyCompletionConfig_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> new DistributedMapConfig.CompletionConfig(null, null, null));
+ assertEquals(
+ "a completion config must set toleratedFailureCount or toleratedFailurePercentage",
+ exception.getMessage());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapDestinationTest.java b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapDestinationTest.java
new file mode 100644
index 0000000000..d2680e7c79
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapDestinationTest.java
@@ -0,0 +1,216 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+
+class DistributedMapDestinationTest {
+
+ @Test
+ void successes_defaultsIncludeOutputOnly() {
+ var destination = DistributedMapDestination.s3Successes("s3://bucket/results");
+
+ assertEquals("bucket", destination.bucket());
+ assertEquals("results", destination.prefix());
+ assertFalse(destination.includeInput());
+ assertTrue(destination.includeOutput());
+ assertNull(destination.expectedBucketOwner());
+ }
+
+ @Test
+ void successes_withoutPath_prefixIsEmpty() {
+ var destination = DistributedMapDestination.s3Successes("s3://bucket");
+
+ assertEquals("bucket", destination.bucket());
+ assertEquals("", destination.prefix());
+ }
+
+ @Test
+ void successes_withAllArguments() {
+ var destination = DistributedMapDestination.s3Successes("s3://bucket/out", true, true, "123456789012");
+
+ assertEquals("bucket", destination.bucket());
+ assertEquals("out", destination.prefix());
+ assertTrue(destination.includeInput());
+ assertTrue(destination.includeOutput());
+ assertEquals("123456789012", destination.expectedBucketOwner());
+ }
+
+ @Test
+ void successes_allIncludeOff_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Successes("s3://bucket/out", false, false, null));
+ assertEquals("success destination must include at least one of input or output", exception.getMessage());
+ }
+
+ @Test
+ void successDestination_allIncludeOff_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapDestination.Success("bucket", "", false, false, null));
+ assertEquals("success destination must include at least one of input or output", exception.getMessage());
+ }
+
+ @ParameterizedTest
+ @NullAndEmptySource
+ void successDestination_nullOrEmptyBucket_shouldThrow(String bucket) {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapDestination.Success(bucket, "", false, true, null));
+ assertEquals("success destination bucket cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void failures_defaultsIncludeInputAndError() {
+ var destination = DistributedMapDestination.s3Failures("s3://bucket/errors");
+
+ assertEquals("bucket", destination.bucket());
+ assertEquals("errors", destination.prefix());
+ assertTrue(destination.includeInput());
+ assertTrue(destination.includeError());
+ assertNull(destination.expectedBucketOwner());
+ }
+
+ @Test
+ void failures_withAllArguments() {
+ var destination = DistributedMapDestination.s3Failures("s3://bucket/err", true, false, "123456789012");
+
+ assertEquals("bucket", destination.bucket());
+ assertEquals("err", destination.prefix());
+ assertTrue(destination.includeInput());
+ assertFalse(destination.includeError());
+ assertEquals("123456789012", destination.expectedBucketOwner());
+ }
+
+ @Test
+ void failures_allIncludeOff_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Failures("s3://bucket/err", false, false, null));
+ assertEquals("failure destination must include at least one of input or error", exception.getMessage());
+ }
+
+ @Test
+ void failureDestination_allIncludeOff_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapDestination.Failure("bucket", "", false, false, null));
+ assertEquals("failure destination must include at least one of input or error", exception.getMessage());
+ }
+
+ @ParameterizedTest
+ @NullAndEmptySource
+ void failureDestination_nullOrEmptyBucket_shouldThrow(String bucket) {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapDestination.Failure(bucket, "", true, true, null));
+ assertEquals("failure destination bucket cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void successes_invalidBucketOwner_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Successes("s3://bucket/out", false, true, "123"));
+ assertEquals("expectedBucketOwner must be a 12-digit account id, got: 123", exception.getMessage());
+ }
+
+ @Test
+ void successes_invalidUri_shouldThrow() {
+ var exception =
+ assertThrows(IllegalArgumentException.class, () -> DistributedMapDestination.s3Successes("bucket/out"));
+ assertEquals("S3 URI must start with s3://, got: bucket/out", exception.getMessage());
+ }
+
+ @Test
+ void destinationConfig_onSuccess_routesSuccessOnly() {
+ var success = DistributedMapDestination.s3Successes("s3://bucket/ok");
+ var config = DistributedMapDestination.of(success);
+
+ assertSame(success, config.onSuccess());
+ assertNull(config.onFailure());
+ }
+
+ @Test
+ void destinationConfig_onFailure_routesFailureOnly() {
+ var failure = DistributedMapDestination.s3Failures("s3://bucket/bad");
+ var config = DistributedMapDestination.of(failure);
+
+ assertNull(config.onSuccess());
+ assertSame(failure, config.onFailure());
+ }
+
+ @Test
+ void destinationConfig_of_routesBoth() {
+ var success = DistributedMapDestination.s3Successes("s3://bucket/ok");
+ var failure = DistributedMapDestination.s3Failures("s3://bucket/bad");
+ var config = DistributedMapDestination.of(success, failure);
+
+ assertSame(success, config.onSuccess());
+ assertSame(failure, config.onFailure());
+ }
+
+ // ------------------------------------------------------------------
+ // key prefix length
+ // ------------------------------------------------------------------
+
+ private static String repeat(String unit, int times) {
+ return unit.repeat(times);
+ }
+
+ @Test
+ void successes_prefixAtTheByteLimit_isAccepted() {
+ var prefix = repeat("a", 900);
+
+ assertEquals(
+ prefix,
+ DistributedMapDestination.s3Successes("s3://bucket/" + prefix).prefix());
+ }
+
+ @Test
+ void successes_prefixOverTheByteLimit_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Successes("s3://bucket/" + repeat("a", 901)));
+ assertEquals("destination key prefix must be at most 900 UTF-8 bytes, got: 901", exception.getMessage());
+ }
+
+ @Test
+ void failures_prefixOverTheByteLimit_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Failures("s3://bucket/" + repeat("a", 901)));
+ assertEquals("destination key prefix must be at most 900 UTF-8 bytes, got: 901", exception.getMessage());
+ }
+
+ @Test
+ void successes_prefixCountsUtf8BytesNotCharacters() {
+ // This character is two UTF-8 bytes, so 450 of them are exactly 900 bytes while being only 450 characters.
+ var atTheLimit = repeat("\u00e9", 450);
+ assertEquals(450, atTheLimit.length());
+ assertEquals(
+ atTheLimit,
+ DistributedMapDestination.s3Successes("s3://bucket/" + atTheLimit)
+ .prefix());
+
+ var overTheLimit = atTheLimit + "\u00e9";
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Successes("s3://bucket/" + overTheLimit));
+ assertEquals("destination key prefix must be at most 900 UTF-8 bytes, got: 902", exception.getMessage());
+ }
+
+ @Test
+ void successes_prefixLengthCountsTheTrailingSlash() {
+ // 900 characters plus the trailing slash is 901 bytes, so the slash is what pushes it over.
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapDestination.s3Successes("s3://bucket/" + repeat("a", 900) + "/"));
+ assertEquals("destination key prefix must be at most 900 UTF-8 bytes, got: 901", exception.getMessage());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfigTest.java b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfigTest.java
new file mode 100644
index 0000000000..0f9178a8b8
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorRetryConfigTest.java
@@ -0,0 +1,80 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.time.Duration;
+import org.junit.jupiter.api.Test;
+
+class DistributedMapProcessorRetryConfigTest {
+
+ @Test
+ void build_defaultsAreNull() {
+ var retry = DistributedMapProcessorRetryConfig.builder().build();
+
+ assertNull(retry.maxRetryAttempts());
+ assertNull(retry.maxRetryDuration());
+ }
+
+ @Test
+ void maxRetryAttempts_zero_isStored() {
+ var retry =
+ DistributedMapProcessorRetryConfig.builder().maxRetryAttempts(0).build();
+
+ assertEquals(0, retry.maxRetryAttempts());
+ }
+
+ @Test
+ void maxRetryAttempts_unlimited_isStored() {
+ var retry = DistributedMapProcessorRetryConfig.builder()
+ .maxRetryAttempts(DistributedMapProcessorRetryConfig.UNLIMITED)
+ .build();
+
+ assertEquals(-1, retry.maxRetryAttempts());
+ }
+
+ @Test
+ void maxRetryAttempts_otherNegative_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessorRetryConfig.builder().maxRetryAttempts(-2));
+ assertEquals(
+ "maxRetryAttempts must be non-negative or DistributedMapProcessorRetryConfig.UNLIMITED, got: -2",
+ exception.getMessage());
+ }
+
+ @Test
+ void maxRetryDuration_atBoundaries_shouldPass() {
+ assertEquals(
+ Duration.ofMinutes(1),
+ DistributedMapProcessorRetryConfig.builder()
+ .maxRetryDuration(Duration.ofMinutes(1))
+ .build()
+ .maxRetryDuration());
+ assertEquals(
+ Duration.ofHours(6),
+ DistributedMapProcessorRetryConfig.builder()
+ .maxRetryDuration(Duration.ofHours(6))
+ .build()
+ .maxRetryDuration());
+ }
+
+ @Test
+ void maxRetryDuration_belowMinimum_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessorRetryConfig.builder().maxRetryDuration(Duration.ofSeconds(59)));
+ assertEquals("maxRetryDuration must be between 1 minute and 6 hours, got: 59s", exception.getMessage());
+ }
+
+ @Test
+ void maxRetryDuration_aboveMaximum_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessorRetryConfig.builder().maxRetryDuration(Duration.ofHours(7)));
+ assertEquals("maxRetryDuration must be between 1 minute and 6 hours, got: 25200s", exception.getMessage());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorTest.java b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorTest.java
new file mode 100644
index 0000000000..c6adde8f60
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapProcessorTest.java
@@ -0,0 +1,181 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.time.Duration;
+import org.junit.jupiter.api.Test;
+
+class DistributedMapProcessorTest {
+
+ @Test
+ void batch_setsBatchMode() {
+ var processor = DistributedMapProcessor.reportBatchOutcome("fn").build();
+
+ assertEquals("fn", processor.functionName());
+ assertEquals(DistributedMapProcessor.ResponseMode.BATCH, processor.responseMode());
+ }
+
+ @Test
+ void itemOutcomes_setsItemOutcomesMode() {
+ var processor = DistributedMapProcessor.reportItemOutcomes("fn").build();
+
+ assertEquals(DistributedMapProcessor.ResponseMode.ITEM_OUTCOMES, processor.responseMode());
+ }
+
+ @Test
+ void build_defaultsAreNull() {
+ var processor = DistributedMapProcessor.reportBatchOutcome("fn").build();
+
+ assertNull(processor.batchSize());
+ assertNull(processor.retry());
+ assertNull(processor.durableExecutionNamePrefix());
+ }
+
+ @Test
+ void batchSize_atBoundaries_shouldPass() {
+ assertEquals(
+ 1,
+ DistributedMapProcessor.reportBatchOutcome("fn")
+ .batchSize(1)
+ .build()
+ .batchSize());
+ assertEquals(
+ 10000,
+ DistributedMapProcessor.reportBatchOutcome("fn")
+ .batchSize(10000)
+ .build()
+ .batchSize());
+ }
+
+ @Test
+ void batchSize_belowMinimum_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("fn")
+ .batchSize(0)
+ .build());
+ assertEquals("batchSize must be between 1 and 10000, got: 0", exception.getMessage());
+ }
+
+ @Test
+ void batchSize_aboveMaximum_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("fn")
+ .batchSize(10001)
+ .build());
+ assertEquals("batchSize must be between 1 and 10000, got: 10001", exception.getMessage());
+ }
+
+ @Test
+ void durableExecutionNamePrefix_atBoundaries_shouldPass() {
+ assertEquals(
+ "a",
+ DistributedMapProcessor.reportBatchOutcome("fn")
+ .durableExecutionNamePrefix("a")
+ .build()
+ .durableExecutionNamePrefix());
+ var thirtySix = "a".repeat(36);
+ assertEquals(
+ thirtySix,
+ DistributedMapProcessor.reportBatchOutcome("fn")
+ .durableExecutionNamePrefix(thirtySix)
+ .build()
+ .durableExecutionNamePrefix());
+ }
+
+ @Test
+ void durableExecutionNamePrefix_empty_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("fn")
+ .durableExecutionNamePrefix("")
+ .build());
+ assertEquals("durableExecutionNamePrefix must be between 1 and 36 characters, got: 0", exception.getMessage());
+ }
+
+ @Test
+ void durableExecutionNamePrefix_tooLong_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("fn")
+ .durableExecutionNamePrefix("a".repeat(37))
+ .build());
+ assertEquals("durableExecutionNamePrefix must be between 1 and 36 characters, got: 37", exception.getMessage());
+ }
+
+ @Test
+ void retryFields_areStored() {
+ var processor = DistributedMapProcessor.reportBatchOutcome("fn")
+ .retry(DistributedMapProcessorRetryConfig.builder()
+ .maxRetryAttempts(3)
+ .maxRetryDuration(Duration.ofMinutes(5))
+ .build())
+ .build();
+
+ assertEquals(3, processor.retry().maxRetryAttempts());
+ assertEquals(Duration.ofMinutes(5), processor.retry().maxRetryDuration());
+ }
+
+ @Test
+ void unlimitedRetryAttempts_isStored() {
+ var processor = DistributedMapProcessor.reportBatchOutcome("fn")
+ .retry(DistributedMapProcessorRetryConfig.builder()
+ .maxRetryAttempts(DistributedMapProcessorRetryConfig.UNLIMITED)
+ .build())
+ .build();
+
+ assertEquals(
+ DistributedMapProcessorRetryConfig.UNLIMITED, processor.retry().maxRetryAttempts());
+ }
+
+ @Test
+ void functionName_empty_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("").build());
+ assertEquals("function name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void functionName_null_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome(null).build());
+ assertEquals("function name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void functionName_tooLong_shouldThrow() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapProcessor.reportBatchOutcome("a".repeat(171))
+ .build());
+ assertEquals("function name must be at most 170 characters, got: 171", exception.getMessage());
+ }
+
+ @Test
+ void functionName_atMaxLength_shouldPass() {
+ var name = "a".repeat(170);
+ assertEquals(
+ name, DistributedMapProcessor.reportBatchOutcome(name).build().functionName());
+ }
+
+ @Test
+ void build_allFieldsSet() {
+ var processor = DistributedMapProcessor.reportItemOutcomes("fn")
+ .batchSize(50)
+ .durableExecutionNamePrefix("job")
+ .retry(DistributedMapProcessorRetryConfig.builder()
+ .maxRetryDuration(Duration.ofMinutes(5))
+ .build())
+ .build();
+
+ assertEquals("fn", processor.functionName());
+ assertEquals(50, processor.batchSize());
+ assertEquals("job", processor.durableExecutionNamePrefix());
+ assertEquals(Duration.ofMinutes(5), processor.retry().maxRetryDuration());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapSourceTest.java b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapSourceTest.java
new file mode 100644
index 0000000000..2224422e87
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/config/DistributedMapSourceTest.java
@@ -0,0 +1,445 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.config;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+
+class DistributedMapSourceTest {
+
+ @Test
+ void inline_storesItems() {
+ var source = DistributedMapSource.inline(List.of("a", "b"));
+
+ assertEquals(DistributedMapSource.SourceType.INLINE, source.sourceType());
+ assertEquals(List.of("a", "b"), source.inlineItems());
+ assertNull(source.inlineSerDes());
+ assertNull(source.s3());
+ assertNull(source.reader());
+ }
+
+ @Test
+ void inline_withSerDes_storesSerDes() {
+ var serDes = new JacksonSerDes();
+
+ var source = DistributedMapSource.inline(List.of("a"), serDes);
+
+ assertEquals(DistributedMapSource.SourceType.INLINE, source.sourceType());
+ assertEquals(List.of("a"), source.inlineItems());
+ assertSame(serDes, source.inlineSerDes());
+ }
+
+ @Test
+ void inline_acceptsNullItem() {
+ var source = DistributedMapSource.inline(java.util.Arrays.asList("a", null));
+ assertEquals(java.util.Arrays.asList("a", null), source.inlineItems());
+ }
+
+ @Test
+ void inline_null_throws() {
+ var exception = assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.inline(null));
+ assertEquals("items cannot be null", exception.getMessage());
+ }
+
+ @Test
+ void inline_rejectsUnorderedSet() {
+ var unordered = new HashSet<>(List.of("a", "b"));
+
+ var exception = assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.inline(unordered));
+ assertEquals("items must have deterministic iteration order", exception.getMessage());
+ }
+
+ @Test
+ void inline_allowsLinkedHashSet() {
+ var ordered = new LinkedHashSet<>(List.of("a", "b"));
+
+ var source = DistributedMapSource.inline(ordered);
+
+ assertEquals(List.of("a", "b"), source.inlineItems());
+ }
+
+ @Test
+ void s3JsonLines_setsBucketKeyFormat() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl");
+
+ assertEquals(DistributedMapSource.SourceType.S3, source.sourceType());
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.OBJECT, s3.type());
+ assertEquals("bucket", s3.bucket());
+ assertEquals("data.jsonl", s3.objectConfig().key());
+ assertEquals(DistributedMapSource.Format.JSON_LINES, s3.objectConfig().format());
+ assertNull(s3.listedObjectMetadataConfig());
+ assertNull(s3.listedObjectsConfig());
+ }
+
+ @Test
+ void s3JsonLines_withoutKey_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.s3JsonLines("s3://bucket-only"));
+ assertEquals("s3JsonLines requires an S3 object key", exception.getMessage());
+ }
+
+ @Test
+ void s3JsonArray_setsFormat() {
+ DistributedMapSource source = DistributedMapSource.s3JsonArray("s3://bucket/data.json");
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.OBJECT, s3.type());
+ assertEquals("bucket", s3.bucket());
+ assertEquals("data.json", s3.objectConfig().key());
+ assertEquals(DistributedMapSource.Format.JSON_ARRAY, s3.objectConfig().format());
+ }
+
+ @Test
+ void s3JsonArray_withoutKey_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.s3JsonArray("s3://bucket-only"));
+ assertEquals("s3JsonArray requires an S3 object key", exception.getMessage());
+ }
+
+ @Test
+ void s3Csv_setsFormatAndCsvFormat() {
+ var format = DistributedMapSource.CsvFormat.headers(List.of("a", "b"));
+
+ DistributedMapSource source = DistributedMapSource.s3Csv("s3://bucket/data.csv", format);
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.OBJECT, s3.type());
+ assertEquals("bucket", s3.bucket());
+ assertEquals("data.csv", s3.objectConfig().key());
+ assertEquals(DistributedMapSource.Format.CSV, s3.objectConfig().format());
+ assertSame(format, s3.objectConfig().csvFormat());
+ }
+
+ @Test
+ void s3Csv_withoutKey_throws() {
+ var format = DistributedMapSource.CsvFormat.firstRow();
+
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.s3Csv("s3://bucket-only", format));
+ assertEquals("s3Csv requires an S3 object key", exception.getMessage());
+ }
+
+ @Test
+ void s3Objects_setsListedObjectMetadataWithPrefix() {
+ DistributedMapSource source = DistributedMapSource.s3Objects("s3://bucket/data/");
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.LISTED_OBJECT_METADATA, s3.type());
+ assertEquals("bucket", s3.bucket());
+ assertEquals("data/", s3.listedObjectMetadataConfig().keyPrefix());
+ assertNull(s3.objectConfig());
+ assertNull(s3.listedObjectsConfig());
+ }
+
+ @Test
+ void s3Objects_wholeBucket_allowsEmptyPrefix() {
+ DistributedMapSource source = DistributedMapSource.s3Objects("s3://bucket");
+
+ var s3 = source.s3();
+ assertEquals("bucket", s3.bucket());
+ assertEquals("", s3.listedObjectMetadataConfig().keyPrefix());
+ assertEquals(DistributedMapSource.S3SourceType.LISTED_OBJECT_METADATA, s3.type());
+ }
+
+ @Test
+ void s3FlattenedJsonLines_setsListedObjects() {
+ DistributedMapSource source = DistributedMapSource.s3FlattenedJsonLines("s3://bucket/prefix/");
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.LISTED_OBJECTS, s3.type());
+ assertEquals("bucket", s3.bucket());
+ assertEquals("prefix/", s3.listedObjectsConfig().keyPrefix());
+ assertEquals(
+ DistributedMapSource.Format.JSON_LINES, s3.listedObjectsConfig().format());
+ assertNull(s3.objectConfig());
+ }
+
+ @Test
+ void s3FlattenedJsonArray_setsListedObjects() {
+ DistributedMapSource source = DistributedMapSource.s3FlattenedJsonArray("s3://bucket/prefix/");
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.LISTED_OBJECTS, s3.type());
+ assertEquals(
+ DistributedMapSource.Format.JSON_ARRAY, s3.listedObjectsConfig().format());
+ }
+
+ @Test
+ void s3FlattenedCsv_setsListedObjects() {
+ var format = DistributedMapSource.CsvFormat.firstRow();
+
+ DistributedMapSource source = DistributedMapSource.s3FlattenedCsv("s3://bucket/prefix/", format);
+
+ var s3 = source.s3();
+ assertEquals(DistributedMapSource.S3SourceType.LISTED_OBJECTS, s3.type());
+ assertEquals(DistributedMapSource.Format.CSV, s3.listedObjectsConfig().format());
+ assertSame(format, s3.listedObjectsConfig().csvFormat());
+ }
+
+ @Test
+ void s3FlattenedCsv_wholeBucket_allowsEmptyPrefix() {
+ DistributedMapSource source =
+ DistributedMapSource.s3FlattenedCsv("s3://bucket", DistributedMapSource.CsvFormat.firstRow());
+
+ assertEquals("", source.s3().listedObjectsConfig().keyPrefix());
+ }
+
+ @Test
+ void reader_storesFunctionName() {
+ DistributedMapSource source = DistributedMapSource.reader("my-reader");
+
+ assertEquals(DistributedMapSource.SourceType.READER_FUNCTION, source.sourceType());
+ assertEquals("my-reader", source.reader().functionName());
+ assertNull(source.reader().initialState());
+ assertNull(source.reader().stateSerDes());
+ }
+
+ @Test
+ void reader_withInitialState_storesState() {
+ var serDes = new JacksonSerDes();
+
+ DistributedMapSource source = DistributedMapSource.reader("my-reader", "start-token", serDes);
+
+ assertEquals("my-reader", source.reader().functionName());
+ assertEquals("start-token", source.reader().initialState());
+ assertSame(serDes, source.reader().stateSerDes());
+ }
+
+ @Test
+ void reader_emptyFunctionName_throws() {
+ var exception = assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.reader(""));
+ assertEquals("function name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void maxItems_setsMaxItems() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl")
+ .maxItems(500);
+
+ assertEquals(500L, source.maxItems());
+ }
+
+ @Test
+ void maxItems_zero_throws() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl");
+
+ var exception = assertThrows(IllegalArgumentException.class, () -> source.maxItems(0));
+ assertEquals("maxItems must be between 1 and 100000000, got: 0", exception.getMessage());
+ }
+
+ @Test
+ void maxItems_atTheLimit_stores() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl")
+ .maxItems(100_000_000L);
+
+ assertEquals(100_000_000L, source.maxItems());
+ }
+
+ @Test
+ void maxItems_aboveTheLimit_throws() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl");
+
+ var exception = assertThrows(IllegalArgumentException.class, () -> source.maxItems(100_000_001L));
+ assertEquals("maxItems must be between 1 and 100000000, got: 100000001", exception.getMessage());
+ }
+
+ @Test
+ void expectedBucketOwner_twelveDigits_stores() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl")
+ .expectedBucketOwner("123456789012");
+
+ assertEquals("123456789012", source.s3().expectedBucketOwner());
+ }
+
+ @Test
+ void expectedBucketOwner_invalid_throws() {
+ DistributedMapSource source = DistributedMapSource.s3JsonLines("s3://bucket/data.jsonl");
+
+ var exception = assertThrows(IllegalArgumentException.class, () -> source.expectedBucketOwner("123"));
+ assertEquals("expectedBucketOwner must be a 12-digit account id, got: 123", exception.getMessage());
+ }
+
+ @Test
+ void expectedBucketOwner_onNonS3Source_throws() {
+ var source = DistributedMapSource.inline(List.of("a"));
+
+ var exception = assertThrows(IllegalStateException.class, () -> source.expectedBucketOwner("123456789012"));
+ assertEquals("expectedBucketOwner only applies to S3 sources", exception.getMessage());
+ }
+
+ @Test
+ void s3JsonLines_missingScheme_throws() {
+ var exception =
+ assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.s3JsonLines("bucket/key"));
+ assertEquals("S3 URI must start with s3://, got: bucket/key", exception.getMessage());
+ }
+
+ @Test
+ void s3Objects_missingBucket_throws() {
+ var exception = assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.s3Objects("s3:///key"));
+ assertEquals("S3 URI must contain a bucket, got: s3:///key", exception.getMessage());
+ }
+
+ @Test
+ void expectedColumns_setsFirstRowAndColumns() {
+ var format = DistributedMapSource.CsvFormat.expectedColumns(List.of("a", "b"));
+
+ assertEquals(DistributedMapSource.CsvFormat.HeaderLocation.FIRST_ROW, format.headerLocation());
+ assertEquals(List.of("a", "b"), format.columns());
+ assertEquals(DistributedMapSource.CsvDelimiter.COMMA, format.delimiter());
+ }
+
+ @Test
+ void headers_setsGivenAndColumns() {
+ var format = DistributedMapSource.CsvFormat.headers(List.of("a", "b"));
+
+ assertEquals(DistributedMapSource.CsvFormat.HeaderLocation.GIVEN, format.headerLocation());
+ assertEquals(List.of("a", "b"), format.columns());
+ assertEquals(DistributedMapSource.CsvDelimiter.COMMA, format.delimiter());
+ }
+
+ @Test
+ void firstRow_hasNoColumns() {
+ var format = DistributedMapSource.CsvFormat.firstRow();
+
+ assertEquals(DistributedMapSource.CsvFormat.HeaderLocation.FIRST_ROW, format.headerLocation());
+ assertNull(format.columns());
+ assertEquals(DistributedMapSource.CsvDelimiter.COMMA, format.delimiter());
+ }
+
+ @Test
+ void withDelimiter_setsDelimiter() {
+ var format = DistributedMapSource.CsvFormat.headers(List.of("a", "b"))
+ .withDelimiter(DistributedMapSource.CsvDelimiter.PIPE);
+
+ assertEquals(DistributedMapSource.CsvDelimiter.PIPE, format.delimiter());
+ assertEquals(DistributedMapSource.CsvFormat.HeaderLocation.GIVEN, format.headerLocation());
+ assertEquals(List.of("a", "b"), format.columns());
+ }
+
+ @Test
+ void constructor_nullDelimiter_defaultsToComma() {
+ var format = new DistributedMapSource.CsvFormat(
+ DistributedMapSource.CsvFormat.HeaderLocation.GIVEN, List.of("a"), null);
+
+ assertEquals(DistributedMapSource.CsvDelimiter.COMMA, format.delimiter());
+ }
+
+ @Test
+ void expectedColumns_empty_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.expectedColumns(List.of()));
+ assertEquals("expectedColumns cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void expectedColumns_aboveTheColumnLimit_throws() {
+ var columns =
+ java.util.stream.IntStream.range(0, 1001).mapToObj(i -> "c" + i).toList();
+
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.expectedColumns(columns));
+ assertEquals("expectedColumns must hold at most 1000 names, got: 1001", exception.getMessage());
+ }
+
+ @Test
+ void headers_nameAboveTheLengthLimit_throws() {
+ var columns = List.of("a".repeat(257));
+
+ var exception =
+ assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.headers(columns));
+ assertEquals("each headers name must be at most 256 characters, got: 257", exception.getMessage());
+ }
+
+ @Test
+ void expectedColumns_duplicates_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapSource.CsvFormat.expectedColumns(List.of("a", "a")));
+ assertEquals("expectedColumns must not contain duplicates", exception.getMessage());
+ }
+
+ @Test
+ void headers_empty_throws() {
+ var exception =
+ assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.headers(List.of()));
+ assertEquals("headers cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void headers_emptyName_throws() {
+ var exception =
+ assertThrows(IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.headers(List.of("")));
+ assertEquals("each headers name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void headers_nullName_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.headers(Arrays.asList("a", null)));
+ assertEquals("each headers name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void expectedColumns_emptyName_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.expectedColumns(List.of("")));
+ assertEquals("each expectedColumns name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void expectedColumns_nullName_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapSource.CsvFormat.expectedColumns(Arrays.asList("a", null)));
+ assertEquals("each expectedColumns name cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void headers_duplicates_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> DistributedMapSource.CsvFormat.headers(List.of("a", "a")));
+ assertEquals("headers must not contain duplicates", exception.getMessage());
+ }
+
+ @Test
+ void constructor_givenWithoutColumns_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapSource.CsvFormat(
+ DistributedMapSource.CsvFormat.HeaderLocation.GIVEN, null, null));
+ assertEquals("CsvFormat with headerLocation GIVEN requires headers", exception.getMessage());
+ }
+
+ @Test
+ void constructor_givenWithDuplicateColumns_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapSource.CsvFormat(
+ DistributedMapSource.CsvFormat.HeaderLocation.GIVEN, List.of("a", "a"), null));
+ assertEquals("headers must not contain duplicates", exception.getMessage());
+ }
+
+ @Test
+ void constructor_firstRowWithEmptyColumns_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> new DistributedMapSource.CsvFormat(
+ DistributedMapSource.CsvFormat.HeaderLocation.FIRST_ROW, List.of(), null));
+ assertEquals("expectedColumns cannot be empty", exception.getMessage());
+ }
+
+ @Test
+ void csvFormat_withoutHeaderLocation_throws() {
+ var exception = assertThrows(
+ IllegalArgumentException.class, () -> new DistributedMapSource.CsvFormat(null, null, null));
+ assertEquals("CsvFormat requires a headerLocation", exception.getMessage());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/context/DurableContextDistributedMapTest.java b/sdk/src/test/java/software/amazon/lambda/durable/context/DurableContextDistributedMapTest.java
new file mode 100644
index 0000000000..89ca5c2229
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/context/DurableContextDistributedMapTest.java
@@ -0,0 +1,194 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.context;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import software.amazon.awssdk.services.lambda.model.CheckpointUpdatedExecutionState;
+import software.amazon.awssdk.services.lambda.model.DistributedMapDetails;
+import software.amazon.awssdk.services.lambda.model.Operation;
+import software.amazon.awssdk.services.lambda.model.OperationStatus;
+import software.amazon.awssdk.services.lambda.model.OperationType;
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.TestUtils;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.config.DistributedMapConfig;
+import software.amazon.lambda.durable.config.DistributedMapProcessor;
+import software.amazon.lambda.durable.config.DistributedMapSource;
+import software.amazon.lambda.durable.execution.ExecutionManager;
+import software.amazon.lambda.durable.execution.ThreadContext;
+import software.amazon.lambda.durable.execution.ThreadType;
+import software.amazon.lambda.durable.model.DistributedMapResult;
+import software.amazon.lambda.durable.model.DistributedMapSummary;
+import software.amazon.lambda.durable.model.DurableExecutionInput;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+
+/** Exercises the ctx.distributedMap entrypoint overloads on DurableContextImpl. */
+class DurableContextDistributedMapTest {
+
+ private static final String EXECUTION_NAME = "349beff4-a89d-4bc8-a56f-af7a8af67a5f";
+ private static final String EXECUTION_OP_ID = "20dae574-53da-37a1-bfd5-b0e2e6ec715d";
+ private static final String EXECUTION_ARN = "arn:aws:lambda:us-east-1:123456789012:function:test/durable-execution/"
+ + EXECUTION_NAME + "/" + EXECUTION_OP_ID;
+
+ private static final Operation EXECUTION_OP = Operation.builder()
+ .id(EXECUTION_OP_ID)
+ .type(OperationType.EXECUTION)
+ .status(OperationStatus.STARTED)
+ .build();
+
+ // The first operation created inside a context always hashes the counter value "1".
+ private static final String FIRST_OP_ID = TestUtils.hashOperationId("1");
+
+ private DurableContext createTestContext() {
+ return createTestContext(List.of());
+ }
+
+ private DurableContext createTestContext(List initialOperations) {
+ var client = TestUtils.createMockClient();
+ var operations = new ArrayList<>(List.of(EXECUTION_OP));
+ operations.addAll(initialOperations);
+ var initialExecutionState =
+ CheckpointUpdatedExecutionState.builder().operations(operations).build();
+ var executionManager = new ExecutionManager(
+ new DurableExecutionInput(EXECUTION_ARN, "test-token", initialExecutionState),
+ DurableConfig.builder().withDurableExecutionClient(client).build(),
+ null);
+ var root = DurableContextImpl.createRootContext(
+ executionManager,
+ DurableConfig.builder().withDurableExecutionClient(client).build(),
+ null);
+ executionManager.registerActiveThread(null);
+ executionManager.setCurrentThreadContext(new ThreadContext(null, ThreadType.CONTEXT));
+ return root;
+ }
+
+ private DistributedMapSource source() {
+ return DistributedMapSource.inline(List.of("a"));
+ }
+
+ private DistributedMapProcessor processor() {
+ return DistributedMapProcessor.reportBatchOutcome("test-processor").build();
+ }
+
+ // A completed distributed map operation so a replay resolves without suspending.
+ private Operation completedDmapOp() {
+ var details = DistributedMapDetails.builder()
+ .sourceExhausted(true)
+ .successCount(1L)
+ .failureCount(0L)
+ .readCount(1L)
+ .totalCount(1L)
+ .build();
+ return Operation.builder()
+ .id(FIRST_OP_ID)
+ .status(OperationStatus.SUCCEEDED)
+ .distributedMapDetails(details)
+ .build();
+ }
+
+ @Test
+ void testMaxConcurrencyZeroThrows() {
+ var context = createTestContext();
+
+ var ex = assertThrows(
+ IllegalArgumentException.class, () -> context.distributedMap("m", source(), processor(), 0));
+ assertTrue(ex.getMessage().contains("maxConcurrency must be greater than zero"));
+ }
+
+ @Test
+ void testMaxConcurrencyNegativeThrows() {
+ var context = createTestContext();
+
+ assertThrows(IllegalArgumentException.class, () -> context.distributedMap("m", source(), processor(), -1));
+ }
+
+ @Test
+ void testResultSerDesOnSummaryCallThrows() {
+ var context = createTestContext();
+ // resultSerDes is only valid on a result-collecting overload, a summary call must reject it.
+ var config =
+ DistributedMapConfig.builder().resultSerDes(new JacksonSerDes()).build();
+
+ var ex = assertThrows(
+ IllegalArgumentException.class, () -> context.distributedMap("m", source(), processor(), 2, config));
+ assertTrue(ex.getMessage().contains("resultSerDes"));
+ }
+
+ @Test
+ void testSummaryOverloadReturnsSummary() {
+ var context = createTestContext(List.of(completedDmapOp()));
+
+ var summary = context.distributedMap("m", source(), processor(), 2);
+
+ assertNotNull(summary);
+ assertEquals(1, summary.successCount());
+ }
+
+ @Test
+ void testResultOverloadReturnsResult() {
+ var context = createTestContext(List.of(completedDmapOp()));
+
+ DistributedMapResult result = context.distributedMap(
+ "m",
+ source(),
+ processor(),
+ 2,
+ String.class,
+ DistributedMapConfig.builder().build());
+
+ assertNotNull(result);
+ assertNotNull(result.items());
+ assertEquals(1, result.summary().successCount());
+ }
+
+ @Test
+ void testClassOverloadDelegatesToTypeToken() {
+ // The Class overload forwards to the TypeToken overload, so both must resolve identically.
+ var classContext = createTestContext(List.of(completedDmapOp()));
+ DistributedMapResult fromClass = classContext.distributedMap(
+ "m",
+ source(),
+ processor(),
+ 2,
+ String.class,
+ DistributedMapConfig.builder().build());
+
+ var tokenContext = createTestContext(List.of(completedDmapOp()));
+ DistributedMapResult fromToken = tokenContext.distributedMap(
+ "m",
+ source(),
+ processor(),
+ 2,
+ new TypeToken() {},
+ DistributedMapConfig.builder().build());
+
+ assertEquals(fromToken.summary(), fromClass.summary());
+ assertEquals(fromToken.items(), fromClass.items());
+ }
+
+ @Test
+ void testSummaryConfigOptional() {
+ var context = createTestContext(List.of(completedDmapOp()));
+
+ // The no-config summary overload uses an empty config internally.
+ DistributedMapSummary summary = context.distributedMap("m", source(), processor(), 2);
+
+ assertNotNull(summary);
+ }
+
+ @Test
+ void testResultConfigOptional() {
+ var context = createTestContext(List.of(completedDmapOp()));
+
+ // The no-config result overload uses an empty config internally.
+ DistributedMapResult result = context.distributedMap("m", source(), processor(), 2, String.class);
+
+ assertNotNull(result);
+ assertNotNull(result.items());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapDurableHandlersTest.java b/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapDurableHandlersTest.java
new file mode 100644
index 0000000000..4e80e31bbe
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapDurableHandlersTest.java
@@ -0,0 +1,251 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.PropertyNamingStrategies;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicInteger;
+import org.junit.jupiter.api.Test;
+import software.amazon.awssdk.services.lambda.model.CheckpointUpdatedExecutionState;
+import software.amazon.awssdk.services.lambda.model.ContextDetails;
+import software.amazon.awssdk.services.lambda.model.ExecutionDetails;
+import software.amazon.awssdk.services.lambda.model.Operation;
+import software.amazon.awssdk.services.lambda.model.OperationAction;
+import software.amazon.awssdk.services.lambda.model.OperationStatus;
+import software.amazon.awssdk.services.lambda.model.OperationType;
+import software.amazon.awssdk.services.lambda.model.OperationUpdate;
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.TestUtils;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.client.DurableExecutionClient;
+import software.amazon.lambda.durable.model.DurableExecutionInput;
+import software.amazon.lambda.durable.model.ExecutionStatus;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+import software.amazon.lambda.durable.serde.SerDes;
+
+/**
+ * Tests that the durable processor wrappers run under the durable execution config the caller supplies. The config is
+ * how a durable processor registers plugins or supplies its own client, so the wrapper must not force the default.
+ */
+class DistributedMapDurableHandlersTest {
+ private static final String EXECUTION_OP_ID = "f3d7b0c0-1234-5678-90ab-cdef12345678";
+ private static final String EXECUTION_ARN =
+ "arn:aws:lambda:us-east-1:123456789012:function:test" + "/durable-execution/exec-name/" + EXECUTION_OP_ID;
+ private static final String RUN_ARN = "arn:aws:lambda:us-east-1:123456789012:distributed-map-run:run-1";
+
+ /** Counts deserialize calls, so a test can prove the config's own serdes read the event. */
+ private static final class RecordingSerDes implements SerDes {
+ private final SerDes delegate = new JacksonSerDes();
+ private final AtomicInteger deserializeCount = new AtomicInteger();
+
+ @Override
+ public String serialize(Object value) {
+ return delegate.serialize(value);
+ }
+
+ @Override
+ public T deserialize(String data, TypeToken typeToken) {
+ deserializeCount.incrementAndGet();
+ return delegate.deserialize(data, typeToken);
+ }
+ }
+
+ private static DurableConfig configWith(SerDes serDes) {
+ return DurableConfig.builder()
+ .withDurableExecutionClient(TestUtils.createMockClient())
+ .withSerDes(serDes)
+ .build();
+ }
+
+ // TestUtils.createMockClient echoes START and SUCCEED only. This client also echoes a failed child context.
+ private static DurableExecutionClient clientEchoingContextFailures() {
+ var delegate = TestUtils.createMockClient();
+ var client = mock(DurableExecutionClient.class);
+ when(client.checkpoint(any(), any(), any())).thenAnswer(invocation -> {
+ List updates = invocation.getArgument(2);
+ var response = delegate.checkpoint(invocation.getArgument(0), invocation.getArgument(1), updates);
+ var operations = new ArrayList();
+ // The delegate returns one operation per update, in update order.
+ for (var i = 0; i < updates.size(); i++) {
+ var operation = response.newExecutionState().operations().get(i);
+ var update = updates.get(i);
+ if (update.action() == OperationAction.FAIL && update.type() == OperationType.CONTEXT) {
+ operations.add(operation.toBuilder()
+ .status(OperationStatus.FAILED)
+ .contextDetails(ContextDetails.builder()
+ .error(update.error())
+ .build())
+ .build());
+ } else {
+ operations.add(operation);
+ }
+ }
+ return response.toBuilder()
+ .newExecutionState(CheckpointUpdatedExecutionState.builder()
+ .operations(operations)
+ .build())
+ .build();
+ });
+ return client;
+ }
+
+ // A first invocation of a durable function: one STARTED execution operation carrying the processor batch.
+ private static DurableExecutionInput durableInput(ProcessorEvent event) {
+ var executionOp = Operation.builder()
+ .id(EXECUTION_OP_ID)
+ .type(OperationType.EXECUTION)
+ .status(OperationStatus.STARTED)
+ .startTimestamp(Instant.parse("2026-08-15T00:00:00Z"))
+ .executionDetails(ExecutionDetails.builder()
+ .inputPayload(new JacksonSerDes().serialize(event))
+ .build())
+ .build();
+ return new DurableExecutionInput(
+ EXECUTION_ARN,
+ "token-1",
+ CheckpointUpdatedExecutionState.builder()
+ .operations(List.of(executionOp))
+ .build());
+ }
+
+ private static ProcessorEvent event(String... bodies) {
+ var records = new java.util.ArrayList();
+ for (var i = 0; i < bodies.length; i++) {
+ records.add(new ProcessorRecord(String.valueOf(i), bodies[i]));
+ }
+ return new ProcessorEvent(RUN_ARN, records);
+ }
+
+ @Test
+ void durableBatchHandlerRunsUnderTheSuppliedConfig() {
+ var serDes = new RecordingSerDes();
+ var seen = new java.util.ArrayList();
+ DistributedMapHandlers.DurableBatchFunction func = (ctx, items, batchCtx) ->
+ seen.addAll(ctx.step("copy", new TypeToken
>() {}, stepCtx -> items));
+
+ var handler = DistributedMapHandlers.createDistributedMapBatchHandlerWithDurableExecution(
+ func, TypeToken.get(Integer.class), null, configWith(serDes));
+ var output = handler.handleRequest(durableInput(event("1", "2")), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ assertEquals(List.of(1, 2), seen);
+ // The processor's event is always read with the default JSON SerDes. The step inside the processor uses the
+ // config's SerDes, so a call here means the supplied config reached the execution.
+ assertTrue(serDes.deserializeCount.get() > 0);
+ }
+
+ @Test
+ void durableItemHandlerRunsUnderTheSuppliedConfig() {
+ var serDes = new RecordingSerDes();
+ DistributedMapHandlers.DurableItemFunction func = (ctx, item, itemCtx) -> item * 2;
+
+ var handler = DistributedMapHandlers.createDistributedMapItemHandlerWithDurableExecution(
+ func, TypeToken.get(Integer.class), null, null, configWith(serDes));
+ var output = handler.handleRequest(durableInput(event("1", "2")), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ assertTrue(serDes.deserializeCount.get() > 0);
+ }
+
+ @Test
+ void durableItemHandlerPassesEachItemsOwnId() {
+ var seen = new ConcurrentHashMap();
+ DistributedMapHandlers.DurableItemFunction func = (ctx, item, itemCtx) -> {
+ seen.put(item, itemCtx);
+ return item;
+ };
+ var event = new ProcessorEvent(RUN_ARN, List.of(new ProcessorRecord("a", "1"), new ProcessorRecord("b", "2")));
+
+ var handler = DistributedMapHandlers.createDistributedMapItemHandlerWithDurableExecution(
+ func, TypeToken.get(Integer.class), null, null, configWith(new JacksonSerDes()));
+ var output = handler.handleRequest(durableInput(event), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ assertEquals(Map.of(1, new ItemContext(RUN_ARN, "a"), 2, new ItemContext(RUN_ARN, "b")), seen);
+ }
+
+ @Test
+ void durableBatchHandlerPassesIdsAlignedWithItems() {
+ var seenItems = new ArrayList();
+ var seenContext = new ArrayList();
+ DistributedMapHandlers.DurableBatchFunction func = (ctx, items, batchCtx) -> {
+ seenItems.addAll(items);
+ seenContext.add(batchCtx);
+ };
+ var event = new ProcessorEvent(RUN_ARN, List.of(new ProcessorRecord("a", "1"), new ProcessorRecord("b", "2")));
+
+ var handler = DistributedMapHandlers.createDistributedMapBatchHandlerWithDurableExecution(
+ func, TypeToken.get(Integer.class), null, configWith(new JacksonSerDes()));
+ var output = handler.handleRequest(durableInput(event), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ assertEquals(List.of(1, 2), seenItems);
+ assertEquals(List.of(new BatchContext(RUN_ARN, List.of("a", "b"))), seenContext);
+ }
+
+ // The service defines the processor's event and response format, so a custom SerDes on the config must not
+ // rename the envelope's fields.
+ @Test
+ void customSerDesDoesNotChangeTheProcessorEnvelope() {
+ var snakeCase = new JacksonSerDes(new ObjectMapper()
+ .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
+ .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES));
+ DistributedMapHandlers.DurableItemFunction func = (ctx, item, itemCtx) -> item * 2;
+
+ var handler = DistributedMapHandlers.createDistributedMapItemHandlerWithDurableExecution(
+ func, TypeToken.get(Integer.class), null, null, configWith(snakeCase));
+ var output = handler.handleRequest(durableInput(event("1")), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ assertTrue(output.result().contains("\"batchItemResults\""), output.result());
+ assertTrue(output.result().contains("\"itemIdentifier\":\"0\""), output.result());
+ assertTrue(output.result().contains("\"batchItemFailures\""), output.result());
+ }
+
+ @Test
+ void durableItemHandlerFailsItemWhoseOutputSerializesToNull() {
+ SerDes nullSerDes = new SerDes() {
+ @Override
+ public String serialize(Object value) {
+ return null;
+ }
+
+ @Override
+ public T deserialize(String data, TypeToken typeToken) {
+ return null;
+ }
+ };
+ DistributedMapHandlers.DurableItemFunction func = (ctx, item, itemCtx) -> item;
+
+ var handler = DistributedMapHandlers.createDistributedMapItemHandlerWithDurableExecution(
+ func,
+ TypeToken.get(Integer.class),
+ null,
+ nullSerDes,
+ DurableConfig.builder()
+ .withDurableExecutionClient(clientEchoingContextFailures())
+ .build());
+ var output = handler.handleRequest(durableInput(event("1")), null);
+
+ assertEquals(ExecutionStatus.SUCCEEDED, output.status());
+ var response = new JacksonSerDes().deserialize(output.result(), TypeToken.get(ItemHandlerResponse.class));
+ assertEquals(List.of(), response.batchItemResults());
+ var failure = response.batchItemFailures().get(0);
+ assertEquals("0", failure.itemIdentifier());
+ assertEquals(
+ "serialization of item output produced no string",
+ failure.error().errorMessage());
+ }
+}
diff --git a/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapHandlersTest.java b/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapHandlersTest.java
new file mode 100644
index 0000000000..35d6f41ab0
--- /dev/null
+++ b/sdk/src/test/java/software/amazon/lambda/durable/dmap/DistributedMapHandlersTest.java
@@ -0,0 +1,651 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.lambda.durable.dmap;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static software.amazon.lambda.durable.dmap.DistributedMapHandlers.*;
+
+import com.amazonaws.services.lambda.runtime.serialization.events.LambdaEventSerializers;
+import com.amazonaws.services.lambda.runtime.serialization.factories.JacksonFactory;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.io.ByteArrayInputStream;
+import java.io.UncheckedIOException;
+import java.lang.reflect.Type;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CyclicBarrier;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
+import software.amazon.lambda.durable.TypeToken;
+import software.amazon.lambda.durable.model.DistributedMapError;
+import software.amazon.lambda.durable.serde.JacksonSerDes;
+import software.amazon.lambda.durable.serde.SerDes;
+
+/** Unit tests for the distributed map authoring helpers (non-durable variants). */
+class DistributedMapHandlersTest {
+ private static final String RUN_ARN = "arn:aws:lambda:us-east-1:123456789012:distributed-map-run:run-1";
+
+ // Builds a single processor record. The body is the serialized item, as the wire carries it.
+ private static ProcessorRecord rec(String itemId, String body) {
+ return new ProcessorRecord(itemId, body);
+ }
+
+ // Builds a distributed map processor event carrying the given records.
+ private static ProcessorEvent processorEvent(ProcessorRecord... records) {
+ return new ProcessorEvent(RUN_ARN, List.of(records));
+ }
+
+ // Builds a distributed map reader event carrying the state and maxItemsPerPage fields.
+ private static ReaderEvent readerEvent(String state, int maxItemsPerPage) {
+ return new ReaderEvent(RUN_ARN, maxItemsPerPage, state);
+ }
+
+ private static DistributedMapError error(String type, String message) {
+ return new DistributedMapError(type, message, null, null);
+ }
+
+ private static void assertFailure(ItemFailure failure, String itemId, String type, String message) {
+ assertEquals(itemId, failure.itemIdentifier());
+ assertEquals(type, failure.error().errorType());
+ assertEquals(message, failure.error().errorMessage());
+ assertNull(failure.error().errorData());
+ assertFalse(failure.error().stackTrace().isEmpty());
+ }
+
+ /** Serdes whose wire form is not JSON, so an item that skipped serialization cannot be read back. */
+ private static final class PrefixSerDes implements SerDes {
+ @Override
+ public String serialize(Object value) {
+ return "p:" + value;
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public T deserialize(String data, TypeToken typeToken) {
+ if (!data.startsWith("p:")) {
+ throw new IllegalArgumentException("not a prefixed value: " + data);
+ }
+ return (T) Integer.valueOf(data.substring(2));
+ }
+ }
+
+ @Test
+ void itemHandlerReportsResultsInOrder() {
+ BiFunction func = (x, itemCtx) -> x * 2;
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(Integer.class), null, null, 1);
+
+ var resp = handler.handleRequest(processorEvent(rec("0", "2"), rec("1", "3")), null);
+
+ assertEquals(List.of(new ItemResult("0", "4"), new ItemResult("1", "6")), resp.batchItemResults());
+ assertEquals(List.of(), resp.batchItemFailures());
+ }
+
+ @Test
+ void itemHandlerCapturesFailuresWithFullyQualifiedErrorType() {
+ BiFunction func = (x, itemCtx) -> {
+ if (x.equals("bad")) {
+ throw new IllegalStateException("boom");
+ }
+ return x;
+ };
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(String.class), null, null, 1);
+
+ var resp = handler.handleRequest(processorEvent(rec("0", "\"ok\""), rec("1", "\"bad\"")), null);
+
+ assertEquals(List.of(new ItemResult("0", "\"ok\"")), resp.batchItemResults());
+ assertEquals(1, resp.batchItemFailures().size());
+ assertFailure(resp.batchItemFailures().get(0), "1", "java.lang.IllegalStateException", "boom");
+ }
+
+ @Test
+ void itemHandlerReportsAnEmptyResultsListWhenEveryItemFails() {
+ BiFunction func = (x, itemCtx) -> {
+ throw new IllegalStateException("nope");
+ };
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(Integer.class), null, null, 1);
+
+ var resp = handler.handleRequest(processorEvent(rec("7", "1")), null);
+
+ // Both lists are always reported, so an all-failing batch carries an empty results list rather than no key.
+ assertEquals(List.of(), resp.batchItemResults());
+ assertEquals(1, resp.batchItemFailures().size());
+ assertFailure(resp.batchItemFailures().get(0), "7", "java.lang.IllegalStateException", "nope");
+ }
+
+ @Test
+ void itemHandlerHonorsRequestedConcurrency() {
+ // Each item blocks until all four have arrived, so the batch only finishes if the pool really runs four
+ // items at once. At a smaller pool size the first item waits out the timeout and every item fails.
+ var barrier = new CyclicBarrier(4);
+ BiFunction func = (x, itemCtx) -> {
+ try {
+ barrier.await(5, TimeUnit.SECONDS);
+ } catch (Exception e) {
+ throw new IllegalStateException("barrier not reached", e);
+ }
+ return x;
+ };
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(Integer.class), null, null, 4);
+
+ var resp =
+ handler.handleRequest(processorEvent(rec("0", "0"), rec("1", "1"), rec("2", "2"), rec("3", "3")), null);
+
+ assertEquals(List.of(), resp.batchItemFailures());
+ // The four items are released together, so completion order is arbitrary while results stay in item order.
+ assertEquals(
+ List.of(
+ new ItemResult("0", "0"),
+ new ItemResult("1", "1"),
+ new ItemResult("2", "2"),
+ new ItemResult("3", "3")),
+ resp.batchItemResults());
+ }
+
+ @Test
+ void itemHandlerDefaultsToOneConcurrentHandler() {
+ var inFlight = new AtomicInteger();
+ var peakInFlight = new AtomicInteger();
+ BiFunction func = (x, itemCtx) -> {
+ peakInFlight.accumulateAndGet(inFlight.incrementAndGet(), Math::max);
+ try {
+ // Held briefly so a regression to a wider pool would actually overlap and be caught.
+ Thread.sleep(20);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ inFlight.decrementAndGet();
+ return x;
+ };
+ // The overload with no concurrency argument runs one handler at a time.
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(String.class), null, null);
+
+ var resp = handler.handleRequest(processorEvent(rec("0", "\"a\""), rec("1", "\"b\""), rec("2", "\"c\"")), null);
+
+ assertEquals(1, peakInFlight.get());
+ assertEquals(3, resp.batchItemResults().size());
+ }
+
+ @ParameterizedTest
+ @ValueSource(ints = {0, -1})
+ void itemHandlerRejectsNonPositiveConcurrency(int concurrency) {
+ var exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> DistributedMapHandlers.createDistributedMapItemHandler(
+ (item, itemCtx) -> item, TypeToken.get(String.class), null, null, concurrency));
+ assertEquals("concurrency must be at least 1, got: " + concurrency, exception.getMessage());
+ }
+
+ @Test
+ void itemHandlerReportsSerializationFailureAgainstTheOffendingItemOnly() {
+ // A result serdes that refuses exactly one value, standing in for a POJO the caller cannot serialize.
+ var refusingSerDes = new SerDes() {
+ private final SerDes delegate = new JacksonSerDes();
+
+ @Override
+ public String serialize(Object value) {
+ if ("boom".equals(value)) {
+ throw new IllegalStateException("cannot serialize");
+ }
+ return delegate.serialize(value);
+ }
+
+ @Override
+ public T deserialize(String data, TypeToken typeToken) {
+ return delegate.deserialize(data, typeToken);
+ }
+ };
+
+ var handler = DistributedMapHandlers.createDistributedMapItemHandler(
+ (item, itemCtx) -> item, TypeToken.get(String.class), null, refusingSerDes, 2);
+
+ var resp = handler.handleRequest(
+ processorEvent(rec("a", "\"ok\""), rec("b", "\"boom\""), rec("c", "\"fine\"")), null);
+
+ // The whole batch must not fail. Only item b is reported as failed.
+ assertEquals(2, resp.batchItemResults().size());
+ assertEquals("a", resp.batchItemResults().get(0).itemIdentifier());
+ assertEquals("c", resp.batchItemResults().get(1).itemIdentifier());
+ assertEquals(1, resp.batchItemFailures().size());
+ assertEquals("b", resp.batchItemFailures().get(0).itemIdentifier());
+ }
+
+ @ParameterizedTest
+ @ValueSource(ints = {1, 4})
+ void itemHandlerPassesTheRunArnAndEachItemsOwnId(int concurrency) {
+ var seen = new ConcurrentHashMap();
+ BiFunction func = (x, itemCtx) -> {
+ seen.put(x, itemCtx);
+ return x;
+ };
+ var handler = createDistributedMapItemHandler(func, TypeToken.get(Integer.class), null, null, concurrency);
+
+ handler.handleRequest(processorEvent(rec("a", "1"), rec("b", "2"), rec("c", "3")), null);
+
+ assertEquals(
+ Map.of(
+ 1, new ItemContext(RUN_ARN, "a"),
+ 2, new ItemContext(RUN_ARN, "b"),
+ 3, new ItemContext(RUN_ARN, "c")),
+ seen);
+ }
+
+ @Test
+ void batchHandlerPassesTheRunArnAndIdsAlignedWithItems() {
+ var seenItems = new ArrayList();
+ var seenContext = new ArrayList();
+ BiConsumer, BatchContext> func = (items, batchCtx) -> {
+ seenItems.addAll(items);
+ seenContext.add(batchCtx);
+ };
+ var handler = createDistributedMapBatchHandler(func, TypeToken.get(Integer.class), null);
+
+ handler.handleRequest(processorEvent(rec("a", "1"), rec("b", "2"), rec("c", "3")), null);
+
+ assertEquals(List.of(1, 2, 3), seenItems);
+ assertEquals(List.of(new BatchContext(RUN_ARN, List.of("a", "b", "c"))), seenContext);
+ }
+
+ @Test
+ void readerPassesTheRunArn() {
+ var seen = new ArrayList();
+ ReaderFunction read = (state, maxItemsPerPage, readerCtx) -> {
+ seen.add(readerCtx);
+ return new ReaderPage<>(List.of(), null);
+ };
+ var handler = createDistributedMapReader(read, TypeToken.get(Integer.class), null, null);
+
+ handler.handleRequest(readerEvent(null, 10), null);
+
+ assertEquals(List.of(new ReaderContext(RUN_ARN)), seen);
+ }
+
+ @ParameterizedTest
+ @NullAndEmptySource
+ void processorEventWithoutRunArnIsRejected(String runArn) {
+ var exception = assertThrows(IllegalStateException.class, () -> new ProcessorEvent(runArn, List.of()));
+ assertEquals(
+ "expected a distributed map processor event to have a 'distributedMapRunArn'", exception.getMessage());
+ }
+
+ @ParameterizedTest
+ @NullAndEmptySource
+ void readerEventWithoutRunArnIsRejected(String runArn) {
+ var exception = assertThrows(IllegalStateException.class, () -> new ReaderEvent(runArn, 10, null));
+ assertEquals(
+ "expected a distributed map reader event to have a 'distributedMapRunArn'", exception.getMessage());
+ }
+
+ @Test
+ void processorEventJsonCarriesTheRunArn() {
+ var json = "{\"distributedMapRunArn\":\"" + RUN_ARN + "\",\"records\":[{\"itemId\":\"a\",\"body\":\"1\"}]}";
+
+ var event = new JacksonSerDes().deserialize(json, TypeToken.get(ProcessorEvent.class));
+
+ assertEquals(processorEvent(rec("a", "1")), event);
+ }
+
+ @Test
+ void readerEventJsonCarriesTheRunArn() {
+ var json = "{\"distributedMapRunArn\":\"" + RUN_ARN + "\",\"maxItemsPerPage\":10,\"state\":\"s\"}";
+
+ var event = new JacksonSerDes().deserialize(json, TypeToken.get(ReaderEvent.class));
+
+ assertEquals(readerEvent("s", 10), event);
+ }
+
+ // Deserializes the way the Lambda Java runtime does for a RequestHandler whose input type is a POJO outside the
+ // runtime's supported event classes: JacksonFactory.getSerializer(Type), then fromJson(InputStream).
+ private static Object deserializeAsLambdaRuntime(String json, Class> type) {
+ assertFalse(LambdaEventSerializers.isLambdaSupportedEvent(type.getName()));
+ var serializer = JacksonFactory.getInstance().getSerializer((Type) type);
+ return serializer.fromJson(new ByteArrayInputStream(json.getBytes(StandardCharsets.UTF_8)));
+ }
+
+ @Test
+ void lambdaRuntimeReadsTheRunArnIntoProcessorEvent() {
+ var json = "{\"distributedMapRunArn\":\"" + RUN_ARN + "\",\"records\":[{\"itemId\":\"a\",\"body\":\"1\"}]}";
+
+ var event = deserializeAsLambdaRuntime(json, ProcessorEvent.class);
+
+ assertEquals(processorEvent(rec("a", "1")), event);
+ }
+
+ @Test
+ void lambdaRuntimeReadsTheRunArnIntoReaderEvent() {
+ var json = "{\"distributedMapRunArn\":\"" + RUN_ARN + "\",\"maxItemsPerPage\":10,\"state\":\"s\"}";
+
+ var event = deserializeAsLambdaRuntime(json, ReaderEvent.class);
+
+ assertEquals(readerEvent("s", 10), event);
+ }
+
+ @Test
+ void lambdaRuntimeRejectsReaderEventWithoutRunArn() {
+ var json = "{\"maxItemsPerPage\":10,\"state\":\"s\"}";
+
+ // The serializer wraps Jackson's exception, which wraps the IllegalStateException from the record constructor.
+ var exception =
+ assertThrows(UncheckedIOException.class, () -> deserializeAsLambdaRuntime(json, ReaderEvent.class));
+
+ var constructorFailure = exception.getCause().getCause();
+ assertInstanceOf(IllegalStateException.class, constructorFailure);
+ assertEquals(
+ "expected a distributed map reader event to have a 'distributedMapRunArn'",
+ constructorFailure.getMessage());
+ }
+
+ @Test
+ void processorEventRejectsMissingRecords() {
+ var ex = assertThrows(IllegalStateException.class, () -> new ProcessorEvent(RUN_ARN, null));
+ assertTrue(ex.getMessage().contains("'records' array"));
+ assertTrue(ex.getMessage().contains("not invoked directly"));
+ }
+
+ @Test
+ void readerEventRejectsMissingMaxItemsPerPage() {
+ var ex = assertThrows(IllegalStateException.class, () -> new ReaderEvent(RUN_ARN, null, "state"));
+ assertTrue(ex.getMessage().contains("'maxItemsPerPage'"));
+ }
+
+ @Test
+ void batchHandlerSucceedsAllItemsWhenFunctionReturns() {
+ var seen = new ArrayList();
+ BiConsumer, BatchContext> func = (items, batchCtx) -> seen.addAll(items);
+ var handler = createDistributedMapBatchHandler(func, TypeToken.get(Integer.class), null);
+
+ var resp = handler.handleRequest(processorEvent(rec("0", "1"), rec("1", "2")), null);
+
+ assertNull(resp);
+ assertEquals(List.of(1, 2), seen);
+ }
+
+ @Test
+ void batchHandlerFailsBatchWhenFunctionThrows() {
+ BiConsumer, BatchContext> func = (items, batchCtx) -> {
+ throw new RuntimeException("batch failed");
+ };
+ var handler = createDistributedMapBatchHandler(func, TypeToken.get(Integer.class), null);
+
+ var ex = assertThrows(RuntimeException.class, () -> handler.handleRequest(processorEvent(rec("0", "1")), null));
+ assertTrue(ex.getMessage().contains("batch failed"));
+ }
+
+ @Test
+ void readerReturnsItemsAndNextStateThenExhausts() {
+ ReaderFunction read = (state, maxItemsPerPage, readerCtx) ->
+ state == null ? new ReaderPage<>(List.of(1, 2), 1) : new ReaderPage<>(List.of(3), null);
+ var handler = createDistributedMapReader(read, TypeToken.get(Integer.class), null, null);
+
+ var first = handler.handleRequest(readerEvent(null, 10), null);
+ assertEquals(List.of("1", "2"), first.items());
+ assertEquals("1", first.nextState());
+
+ var second = handler.handleRequest(readerEvent("1", 10), null);
+ assertEquals(List.of("3"), second.items());
+ // Null rather than empty, so the runtime omits the key, which is how exhaustion is signalled.
+ assertNull(second.nextState());
+ }
+
+ @Test
+ void readerReceivesMaxItemsPerPage() {
+ ReaderFunction read =
+ (state, maxItemsPerPage, readerCtx) -> new ReaderPage<>(List.of(maxItemsPerPage), null);
+ var handler = createDistributedMapReader(read, TypeToken.get(Integer.class), null, null);
+
+ var page = handler.handleRequest(readerEvent(null, 7), null);
+
+ assertEquals(List.of("7"), page.items());
+ }
+
+ @Test
+ void readerRejectsPageOverMaxItemsPerPage() {
+ ReaderFunction