DEV: (cmds+) updates for streams idempotent production

content/commands/xadd.md

@@ -4,46 +4,76 @@ acl_categories:
 - '@stream'
 - '@fast'
 arguments:
-- display_text: key
-  key_spec_index: 0
+- key_spec_index: 0
   name: key
   type: key
-- display_text: nomkstream
-  name: nomkstream
+- name: nomkstream
   optional: true
   since: 6.2.0
   token: NOMKSTREAM
   type: pure-token
 - arguments:
+  - name: keepref
+    token: KEEPREF
+    type: pure-token
+  - name: delref
+    token: DELREF
+    type: pure-token
+  - name: acked
+    token: ACKED
+    type: pure-token
+  name: condition
+  optional: true
+  type: oneof
+- arguments:
+  - arguments:
+    - name: idmpauto-token
+      token: IDMPAUTO
+      type: pure-token
+    - display_text: producer-id
+      name: pid
+      type: string
+    name: idmpauto-with-pid
+    type: block
   - arguments:
-    - display_text: maxlen
-      name: maxlen
+    - name: idmp-token
+      token: IDMP
+      type: pure-token
+    - display_text: producer-id
+      name: pid
+      type: string
+    - display_text: idempotent-id
+      name: iid
+      type: string
+    name: idmp-with-pid-iid
+    type: block
+  name: idmp
+  optional: true
+  type: oneof
+- arguments:
+  - arguments:
+    - name: maxlen
       token: MAXLEN
       type: pure-token
-    - display_text: minid
-      name: minid
+    - name: minid
       since: 6.2.0
       token: MINID
       type: pure-token
     name: strategy
     type: oneof
   - arguments:
-    - display_text: equal
-      name: equal
+    - name: equal
       token: '='
       type: pure-token
-    - display_text: approximately
-      name: approximately
+    - name: approximately
       token: '~'
       type: pure-token
     name: operator
     optional: true
     type: oneof
-  - display_text: threshold
-    name: threshold
+  - name: threshold
     type: string
-  - display_text: count
-    name: count
+  - name: count
     optional: true
     since: 6.2.0
     token: LIMIT
@@ -52,21 +82,17 @@ arguments:
   optional: true
   type: block
 - arguments:
-  - display_text: auto-id
-    name: auto-id
+  - name: auto-id
     token: '*'
     type: pure-token
-  - display_text: id
-    name: id
+  - name: id
     type: string
   name: id-selector
   type: oneof
 - arguments:
-  - display_text: field
-    name: field
+  - name: field
     type: string
-  - display_text: value
-    name: value
+  - name: value
     type: string
   multiple: true
   name: data
@@ -116,8 +142,10 @@ linkTitle: XADD
 railroad_diagram: /images/railroad/xadd.svg
 since: 5.0.0
 summary: Appends a new message to a stream. Creates the key if it doesn't exist.
-syntax_fmt: "XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID> [= | ~] threshold\n  [LIMIT\_\
-  count]] <* | id> field value [field value ...]"
+syntax_fmt: "XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED]\n \
+  \ [IDMPAUTO producer-id | IDMP producer-id idempotent-id]\n \
+  \ [<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]] <* | id>\n \
+  \ field value [field value ...]"
 title: XADD
 ---
 
@@ -153,6 +181,24 @@ One or more field-value pairs that make up the stream entry. You must provide at
 Prevents the creation of a new stream if the key does not exist. Available since Redis 6.2.0.
 </details>
 
+<details open>
+<summary><code>IDMPAUTO producer-id | IDMP producer-id idempotent-id</code></summary>
+
+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 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.
+
+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.
+
+</details>
+
 <details open>
 <summary><code>KEEPREF | DELREF | ACKED</code></summary>
 
@@ -267,6 +313,16 @@ XLEN mystream
 XRANGE mystream - +
 {{% /redis-cli %}}
 
+### Idempotent message processing examples
+
+{{% redis-cli %}}
+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 IDMP-DURATION 300 IDMP-MAXSIZE 1000
+{{% /redis-cli %}}
+
 ## Redis Enterprise and Redis Cloud compatibility
 
 | Redis<br />Enterprise | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
@@ -280,13 +336,13 @@ XRANGE mystream - +
     tab2="RESP3" >}}
 
 One of the following:
-* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The ID of the added entry. The ID is the one automatically generated if an asterisk (`*`) is passed as the _id_ argument, otherwise the command just returns the same ID specified by the user during insertion.
+* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The ID of the added entry. The ID is the one automatically generated if an asterisk (`*`) is passed as the _id_ argument, otherwise the command just returns the same ID specified by the user during insertion. When using IDMP and a duplicate is detected, returns the ID of the existing entry.
 * [Nil reply](../../develop/reference/protocol-spec#bulk-strings): if the NOMKSTREAM option is given and the key doesn't exist.
 
 -tab-sep-
 
 One of the following:
-* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The ID of the added entry. The ID is the one automatically generated if an asterisk (`*`) is passed as the _id_ argument, otherwise the command just returns the same ID specified by the user during insertion.
+* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): The ID of the added entry. The ID is the one automatically generated if an asterisk (`*`) is passed as the _id_ argument, otherwise the command just returns the same ID specified by the user during insertion. When using IDMP and a duplicate is detected, returns the ID of the existing entry.
 * [Null reply](../../develop/reference/protocol-spec#nulls): if the NOMKSTREAM option is given and the key doesn't exist.
 
 {{< /multitabs >}}

content/commands/xcfgset.md

@@ -0,0 +1,131 @@
+---
+acl_categories:
+- STREAM
+arguments:
+- key_spec_index: 0
+  name: key
+  type: key
+- arguments:
+  - name: duration-token
+    token: IDMP-DURATION
+    type: pure-token
+  - name: duration
+    type: integer
+  name: duration-block
+  optional: true
+  type: block
+- arguments:
+  - name: maxsize-token
+    token: IDMP-MAXSIZE
+    type: pure-token
+  - name: maxsize
+    type: integer
+  name: maxsize-block
+  optional: true
+  type: block
+arity: -2
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+command_flags:
+- WRITE
+- FAST
+complexity: O(1)
+description: Sets the IDMP configuration parameters for a stream.
+function: xcfgsetCommand
+group: stream
+hidden: false
+key_specs:
+- begin_search:
+    index:
+      pos: 1
+  find_keys:
+    range:
+      lastkey: 0
+      limit: 0
+      step: 1
+  flags:
+  - RW
+  - UPDATE
+linkTitle: XCFGSET
+reply_schema:
+  const: OK
+since: 8.6.0
+summary: Sets the IDMP configuration parameters for a stream.
+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.
+
+## Required arguments
+
+<details open><summary><code>key</code></summary>
+
+The name of the stream key. The stream must already exist.
+
+</details>
+
+## Optional arguments
+
+<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-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>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.
+
+When the capacity is reached, the oldest idempotent IDs for that producer are evicted regardless of remaining duration. This prevents unbounded memory growth.
+
+</details>
+
+## Behavior
+
+- 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 IDMP-DURATION 300
+XCFGSET mystream IDMP-MAXSIZE 1000
+XCFGSET mystream IDMP-DURATION 600 IDMP-MAXSIZE 500
+```
+
+## Return information
+
+{{< multitabs id="return-info"
+    tab1="RESP2"
+    tab2="RESP3" >}}
+
+[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the configuration was set successfully.
+
+-tab-sep-
+
+[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the configuration was set successfully.
+
+{{< /multitabs >}}
+
+## Error conditions
+
+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-86,400)
+- **ERR invalid maxsize**: Maxsize value is outside the valid range (1-10,000)