From 661cfeac1fa547ad2a586ec1f317ee8c420527b4 Mon Sep 17 00:00:00 2001
From: Matteo Valentini <matteo.valentini@nethesis.it>
Date: Thu, 3 Sep 2026 18:12:41 +0200
Subject: [PATCH] feat(agent): allow raw Redis responses

Opt-in byte responses let consumers perform strict per-entry decoding
without changing existing decoded clients.

Assisted-by: Codex:GPT-5
---
 .../usr/local/agent/pypkg/agent/__init__.py      | 14 +++++++++-----
 docs/modules/database.md                         | 16 ++++++++++++++++
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/core/imageroot/usr/local/agent/pypkg/agent/__init__.py b/core/imageroot/usr/local/agent/pypkg/agent/__init__.py
index 166ac7fd2e..cfa99a2445 100644
--- a/core/imageroot/usr/local/agent/pypkg/agent/__init__.py
+++ b/core/imageroot/usr/local/agent/pypkg/agent/__init__.py
@@ -50,13 +50,17 @@
 SD_INFO    = "<6>"  # informational
 SD_DEBUG   = "<7>"  # debug-level messages
 
-def redis_connect(privileged=False, use_replica=False, **kwargs):
+def redis_connect(
+    privileged=False, use_replica=False, *, decode_responses=True, **kwargs
+):
     """Connect to the Redis DB. If no arguments are given
     the leader Redis instance with default read-only access rights
     credentials is selected.
     - Set `privileged=True` to modify Redis DB. Replica cannot be modified.
     - Set `use_replica=True` to discover service startup configuration from
       the local Redis replica.
+    - Set `decode_responses=False` to receive Redis bulk strings as raw bytes.
+      By default, responses are decoded as UTF-8 strings.
 
     Any other keyword argument is passed to redis.Redis() constructor.
     """
@@ -79,10 +83,10 @@ def redis_connect(privileged=False, use_replica=False, **kwargs):
     kwargs.setdefault('db', 0)
     kwargs.setdefault('username', redis_username)
     kwargs.setdefault('password', redis_password)
-    #  we assume Redis keys and value strings are encoded UTF-8. Enabling this
-    #  option implicitly converts to UTF-8 strings instead of binary strings
-    #  (e.g. {b'key': b'value'} != {'key':'value'})
-    kwargs.setdefault('decode_responses', True)
+    # We assume Redis keys and value strings are encoded as UTF-8 by default.
+    # The opt-out is configured when the connection pool is created so raw
+    # clients receive the original bytes unchanged.
+    kwargs['decode_responses'] = decode_responses
 
     return redis.Redis(**kwargs)
 
diff --git a/docs/modules/database.md b/docs/modules/database.md
index 7afeaa0f60..0fce180349 100644
--- a/docs/modules/database.md
+++ b/docs/modules/database.md
@@ -43,3 +43,19 @@ import agent
 rdb = agent.redis_connect(use_replica=True)
 cluster_network = rdb.get('cluster/network')
 ```
+
+Redis responses are decoded from UTF-8 to strings by default. Consumers that
+need to validate or process each Redis bulk string independently can opt in to
+the original bytes with `decode_responses=False`:
+
+```python
+import agent
+
+raw_rdb = agent.redis_connect(
+    use_replica=True,
+    decode_responses=False,
+)
+for key in raw_rdb.scan_iter('cluster/*'):
+    raw_hash = raw_rdb.hgetall(key)
+    # key, raw_hash field names, and raw_hash values are bytes
+```