Apply review suggestions

Author: dwdougherty

content/commands/xadd.md

@@ -187,11 +187,13 @@ Prevents the creation of a new stream if the key does not exist. Available since
 Enables idempotent message processing (at-most-once production) to prevent duplicate entries. Available since Redis 8.6.
 
 - `IDMPAUTO producer-id`: Automatically generates a unique idempotent ID (iid) for the specified producer-id. Redis tracks this iid to prevent duplicate messages from the same producer-id.
-- `IDMP producer-id idempotent-id`: Uses the specified idempotent-id for the given producer-id. If this producer-id/idempotent-id combination was already used, the command returns the idempotent-id of the existing entry instead of creating a duplicate.
+- `IDMP producer-id idempotent-id`: Uses the specified idempotent-id for the given producer-id. If this producer-id/idempotent-id combination was already used, the command returns the ID of the existing entry instead of creating a duplicate.
 
 The producer-id identifies the source of the message, while the idempotent-id ensures uniqueness within that producer-id's message stream. Redis maintains an internal map of recent producer-id/idempotent-id combinations to detect and prevent duplicates.
 
-Use [`XCFGSET`]({{< relref "/commands/xcfgset" >}}) to configure how long idempotent IDs are retained (`DURATION`) and the maximum number tracked per producer (`MAXSIZE`).
+Both modes can only be specified when the entry ID is `*` (auto-generated).
+
+Use [`XCFGSET`]({{< relref "/commands/xcfgset" >}}) to configure how long idempotent IDs are retained (`IDMP-DURATION`) and the maximum number tracked per producer (`IDMP-MAXSIZE`).
 
 See [Idempotent message processing]({{< relref "/develop/data-types/streams/idempotency" >}}) for more information.
 
@@ -318,7 +320,7 @@ XADD mystream IDMP producer1 msg1 * field value
 XADD mystream IDMP producer1 msg1 * field different_value
 XADD mystream IDMPAUTO producer2 * field value
 XADD mystream IDMPAUTO producer2 * field value
-XCFGSET mystream DURATION 300 MAXSIZE 1000
+XCFGSET mystream IDMP-DURATION 300 IDMP-MAXSIZE 1000
 {{% /redis-cli %}}
 
 ## Redis Enterprise and Redis Cloud compatibility

content/commands/xcfgset.md

@@ -7,7 +7,7 @@ arguments:
   type: key
 - arguments:
   - name: duration-token
-    token: DURATION
+    token: IDMP-DURATION
     type: pure-token
   - name: duration
     type: integer
@@ -16,7 +16,7 @@ arguments:
   type: block
 - arguments:
   - name: maxsize-token
-    token: MAXSIZE
+    token: IDMP-MAXSIZE
     type: pure-token
   - name: maxsize
     type: integer
@@ -59,7 +59,7 @@ reply_schema:
   const: OK
 since: 8.6.0
 summary: Sets the IDMP configuration parameters for a stream.
-syntax_fmt: XCFGSET key [DURATION duration] [MAXSIZE maxsize]
+syntax_fmt: XCFGSET key [IDMP-DURATION duration] [IDMP-MAXSIZE maxsize]
 title: XCFGSET
 ---
 Sets the IDMP (Idempotent Message Processing) configuration parameters for a stream. This command configures how long idempotent IDs are retained and the maximum number of idempotent IDs tracked per producer.
@@ -74,15 +74,15 @@ The name of the stream key. The stream must already exist.
 
 ## Optional arguments
 
-<details open><summary><code>DURATION duration</code></summary>
+<details open><summary><code>IDMP-DURATION duration</code></summary>
 
-Sets the duration in seconds that each idempotent ID (iid) is kept in the stream's IDMP map. Valid range: 1-86400 seconds. Default: 100 seconds.
+Sets the duration in seconds that each idempotent ID (iid) is kept in the stream's IDMP map. Valid range: 1-86,400 seconds. Default: 100 seconds.
 
 When an idempotent ID expires, it can be reused for new messages. This provides an operational guarantee that Redis will not forget an idempotency ID before the duration elapses (unless capacity is reached).
 
 </details>
 
-<details open><summary><code>MAXSIZE maxsize</code></summary>
+<details open><summary><code>IDMP-MAXSIZE maxsize</code></summary>
 
 Sets the maximum number of most recent idempotent IDs kept for each producer in the stream's IDMP map. Valid range: 1-10,000 entries. Default: 100 entries.
 
@@ -92,18 +92,18 @@ When the capacity is reached, the oldest idempotent IDs for that producer are ev
 
 ## Behavior
 
-- Calling `XCFGSET` clears all existing producer IDMP maps for the stream
-- At least one of `DURATION` or `MAXSIZE` must be specified
-- The stream must exist before calling this command
-- Configuration changes apply immediately to all future IDMP operations
+- Calling `XCFGSET` clears all existing producer IDMP maps for the stream.
+- At least one of `IDMP-DURATION` or `IDMP-MAXSIZE` must be specified.
+- The stream must exist before calling this command.
+- Configuration changes apply immediately to all future IDMP operations.
 
 ## Examples
 
 ```redis-cli
 XADD mystream * field value
-XCFGSET mystream DURATION 300
-XCFGSET mystream MAXSIZE 1000
-XCFGSET mystream DURATION 600 MAXSIZE 500
+XCFGSET mystream IDMP-DURATION 300
+XCFGSET mystream IDMP-MAXSIZE 1000
+XCFGSET mystream IDMP-DURATION 600 IDMP-MAXSIZE 500
 ```
 
 ## Return information
@@ -127,6 +127,5 @@ The command returns an error in the following cases:
 - **WRONGTYPE**: The key exists but is not a stream
 - **ERR no such key**: The stream does not exist
 - **ERR syntax error**: Invalid command syntax or missing required arguments
-- **ERR invalid duration**: Duration value is outside the valid range (1-86400)
+- **ERR invalid duration**: Duration value is outside the valid range (1-86,400)
 - **ERR invalid maxsize**: Maxsize value is outside the valid range (1-10,000)
-

content/develop/data-types/streams/idempotency.md

@@ -17,6 +17,22 @@ weight: 10
 
 In Redis 8.6, streams support idempotent message processing (at-most-once production) to prevent duplicate entries when using at-least-once delivery patterns. This feature enables reliable message submission with automatic deduplication.
 
+Idempotent message processing ensures that handling the same message multiple times produces the same system state as handling it once.
+
+Beginning with Redis 8.6, streams support idempotent message processing (at-most-once production) to prevent duplicate entries when producers resend messages.
+
+Producers may need to resend messages under two scenarios:
+
+1. Producer-Redis network issues (disconnection and reconnection).
+
+    If a disconnection occurs after the producer executes `XADD`, but before it receives the reply, the producer has no way of knowing if that message was delivered.
+
+1. The producer crashes and restarts.
+
+    If the producer crashes after calling `XADD` but before receiving the reply and marking a message as delivered, after a restart, the producer has no way of knowing if that message was delivered.
+
+In both cases, to guarantee that the message is added to the stream, the producer must call `XADD` again with the same message. Without idempotent message processing, a retry may result in a message being delivered twice. With idempotent message processing, producers can guarantee at-most-once production even under such scenarios.
+
 A unique ID, called an idempotent ID or *iid*, is associated with each message that is added to a stream. 
 There are two ways to assign iids:
 
@@ -31,8 +47,8 @@ For (1), this is the producer’s responsibility, and for (2), Redis will calcul
 Use the [`XADD`]({{< relref "/commands/xadd" >}}) command with idempotency parameters, `IDMP` or `IDMPAUTO`:
 
 ```
-XADD mystream IDMP producer1 msg1 * field value      # producer-provided iid
-XADD mystream IDMPAUTO producer2 * field value       # Redis-generated iid
+XADD mystream IDMP producer-1 iid-1 * field value      # producer-1 (pid) and iid-1 (iid) are provided manually
+XADD mystream IDMPAUTO producer-2 * field value        # producer-2 (pid) is provided manually, Redis provides the iid
 ```
 
 ### Manual mode (`IDMP`)
@@ -61,6 +77,13 @@ XADD mystream IDMPAUTO producer1 * field value
 - Content-based: The same content produces the same iid.
 - Performance: Slightly slower due to hash calculation.
 
+For both IDMP and IDMPAUTO, each producer application is required to use the same pid after it restarts.
+
+For IDMP, each producer application is responsible for:
+
+- Providing a unique iid for each entry (either globally, or just for each pid).
+- Reusing the same (pid, iid) when resending a message (even after it restarts).
+
 Here's an illustration of how message processing in Redis Streams works with and without idempotent production:
 
 {{< image filename="images/dev/stream/stream-idempotency.png" alt="Idempotent message processing in Redis Streams" >}}
@@ -70,54 +93,53 @@ Here's an illustration of how message processing in Redis Streams works with and
 Configure idempotency settings for a stream using [`XCFGSET`]({{< relref "/commands/xcfgset" >}}):
 
 ```
-XCFGSET mystream DURATION 300 MAXSIZE 1000
+XCFGSET mystream IDMP-DURATION 300 IDMP-MAXSIZE 1000
 ```
 
 ### Parameters
 
-- `DURATION`: How long (in seconds) to retain iids (1-86400 seconds, the default is 100).
-- `MAXSIZE`: The maximum number of per-producer iids to track (1-10,000 entries, the default is 100).
+- `IDMP-DURATION`: How long (in seconds) to retain iids (1-86400 seconds, the default is 100).
+- `IDMP-MAXSIZE`: The maximum number of per-producer iids to track (1-10,000 entries, the default is 100).
 
 ### Expiration behavior
 
 Idempotent IDs are removed when either condition is met:
 
-- Time-based: iids expire after the configured `DURATION`.
-- Capacity-based: Oldest iids are evicted when `MAXSIZE` is reached.
+- Time-based: iids expire after the configured `IDMP-DURATION`.
+- Capacity-based: Oldest iids are evicted when `IDMP-MAXSIZE` is reached. Redis never keeps more than `IDMP-MAXSIZE` iids per pid. In other words, `IDMP-MAXSIZE` is *stronger* than `IDMP-DURATION`.
 
 ### Determine optimal configuration values
 
-`DURATION` is an operational guarantee: Redis will not discard a previously sent iid for the specified duration (unless reaching `MAXSIZE` iids for that producer).
-If a producer application crashes and stops sending messages to Redis, Redis will keep each iid for `DURATION` seconds, after which they will be discarded.
-You should know how long it may take your producer application to recover from a crash and start resending messages. 
-`DURATION` should be set accordingly.
-If `DURATION` is set too high, Redis will waste memory by retaining iids for a longer duration than necessary.
+`IDMP-DURATION` is an operational guarantee: Redis will not discard a previously sent iid for the specified duration (unless reaching `IDMP-MAXSIZE` iids for that producer).
+If a producer application crashes and stops sending messages to Redis, Redis will keep each iid for `IDMP-DURATION` seconds, after which they will be discarded.
+You should know how long it may take your producer application to recover from a crash and start resending messages, so you should set `IDMP-DURATION` accordingly.
+If `IDMP-DURATION` is set too high, Redis will waste memory by retaining iids for a longer duration than necessary.
 
-**Example**: if a producer crashes, it may take up to 1,000 seconds until it recovers and restarts sending messages. You should set `DURATION` to 1000.
+**Example**: if a producer crashes, it may take up to 1,000 seconds until it recovers and restarts sending messages. You should set `IDMP-DURATION` to 1000.
 
 When a producer application retrieves an `XADD` reply from Redis, it usually marks the message as *delivered* in a transaction database or log file. 
 If the application crashes, it needs to resend undelivered messages after recovering from the crash.
 Since a few messages may have not been marked as delivered as a result of the crash, the application will likely resend these messages.
 Using iids will allow Redis to detect such duplicate messages and filter them.
-Setting `MAXSIZE` correctly ensures that Redis retains a sufficient number of recent iids.
-If `MAXSIZE` is set too high, Redis will waste memory by retaining too many iids.
+Setting `IDMP-MAXSIZE` correctly ensures that Redis retains a sufficient number of recent iids.
+If `IDMP-MAXSIZE` is set too high, Redis will waste memory by retaining too many iids.
 Usually this number can be very small, and often, even *one* is enough.
-If your application marks messages as delivered asynchronously, you should know how long it may take from the time it retrieved a `XADD` reply from Redis until the message is marked as delivered; this duration is called *mark-delay*. `MAXSIZE` should be set to
+If your application marks messages as delivered asynchronously, you should know how long it may take from the time it retrieved a `XADD` reply from Redis until the message is marked as delivered; this duration is called *mark-delay*. `IDMP-MAXSIZE` should be set to
 
 `mark-delay [in msec] * (messages / msec) + some margin.`
 
-**Example**: a producer is sending 1K msgs/sec (1 msg/msec), and takes up to 80 msec to mark each message as delivered, `MAXSIZE` should be set to `1 * 80 + margin = 100` iids.
+**Example**: a producer is sending 1K msgs/sec (1 msg/msec), and takes up to 80 msec to mark each message as delivered, `IDMP-MAXSIZE` should be set to `1 * 80 + margin = 100` iids.
 
 ## Producer isolation
 
 Each producer maintains independent idempotency tracking:
 
 ```
-XADD mystream IDMP producer1 msg1 * field value    # Producer 1's tracking
-XADD mystream IDMP producer2 msg1 * field value    # Producer 2's tracking (independent)
+XADD mystream IDMP producer-1 iid-1 * field value    # producer-1 is tracking
+XADD mystream IDMP producer-2 iid-1 * field value    # producer-2 is tracking (independent)
 ```
 
-Producers can use the same idempotent ID without conflicts.
+Producers can use the same iid without conflicts, as long as long as the pids are different.
 
 ## Monitoring
 
@@ -127,13 +149,13 @@ Use [`XINFO STREAM`]({{< relref "/commands/xinfo-stream" >}}) to monitor idempot
 XINFO STREAM mystream
 ```
 
-Returns additional fields when idempotency is begin used:
+Returns additional fields when idempotency is being used:
 
 - `idmp-duration`: Current duration setting.
 - `idmp-maxsize`: Current maxsize setting.
-- `pids-tracked`: Number of active producers.
-- `iids-tracked`: Total idempotent IDs currently stored.
-- `iids-added`: Lifetime count of idempotent messages added.
+- `pids-tracked`: The number of pids currently tracked in the stream
+- `iids-tracked`: Total number of iids currently tracked.
+- `iids-added`: Lifetime count of messages with idempotent IDs.
 - `iids-duplicates`: Lifetime count of duplicates prevented.
 
 ## Best practices
@@ -142,8 +164,7 @@ Returns additional fields when idempotency is begin used:
 
 Use globally unique, persistent producer IDs:
 
-- Recommended: UUID v4 for global uniqueness.
-- Alternative: `hostname:process_id` or application-assigned IDs.
+- Recommended: Use short producer IDs to save memory and increase performance.
 - Persistence: Use the same producer ID after restarts to maintain idempotency tracking.
 
 ### Configuration tuning
@@ -168,13 +189,13 @@ Idempotency introduces minimal overhead:
 - Memory: <1.5% additional memory usage.
 - Latency: Negligible impact on per-operation latency.
 
-Manual mode (IDMP) is slightly faster than automatic mode (IDMPAUTO) due to avoiding hash calculation.
+Manual mode (IDMP) is slightly faster than automatic mode (IDMPAUTO) since it avoids hash calculations.
 
 ## Persistence
 
 Idempotency tracking persists across Redis restarts:
 
 - RDB/AOF: All producer-idempotent ID pairs are saved.
 - Recovery: Tracking remains active after restart.
-- Configuration: `DURATION` and `MAXSIZE` settings persist.
-- Important: Running `XCFGSET` clears all existing tracking data. Use without `DURATION` and `MAXSIZE` to clear data. 
+- Configuration: `IDMP-DURATION` and `IDMP-MAXSIZE` settings persist.
+- Important: Executing `XCFGSET` with different `IDMP-DURATION` or `IDMP-MAXSIZE` values than the current values for a particular key clears its IDMP map.