redqueue 0.12.0__tar.gz → 0.13.1__tar.gz

{redqueue-0.12.0 → redqueue-0.13.1}/CHANGELOG.md

@@ -7,39 +7,82 @@ All notable public release changes are documented here.
 Development versions are tracked separately from formal release versions.
 开发版本与正式版本分开管理。
 
-## [0.12.0] - 2026-06-23
-
-### Added
-
-- Added the `redqueue` CLI and `python -m redqueue` module entry point for
-  developer debugging.
-- Added CLI commands for Redis compatibility checks, queue statistics, message
-  publish, consume with optional ack/nack/retry, delayed scheduling, due
-  release, and dead-letter inspection.
-- Added deterministic JSON CLI output and user-facing JSON validation errors.
-- Added CLI unit tests with injected fake Redis and queue clients.
+## [0.13.1] - 2026-06-27
 
 ### Fixed
 
-- Normalized `BRPOPLPUSH` timeout values to integer seconds for Redis versions
-  older than 6.2, improving Redis 5.x List consume compatibility.
-
-### 新增
-
-- 新增 `redqueue` CLI 和 `python -m redqueue` 模块入口，方便开发者调试。
-- 新增 Redis 兼容性检查、队列统计、消息发布、消费并可选 ack/nack/retry、
-  延迟调度、到期释放和死信查看命令。
-- CLI 输出稳定 JSON，并提供面向用户的 JSON 参数校验错误。
-- 新增基于 fake Redis 和 fake queue client 的 CLI 单元测试。
+- Fixed a compatibility regression where legacy messages with blank
+  `headers["trace_id"]` values could fail to construct or consume after
+  upgrading to `0.13.0`.
+- Fixed sync and async `publish(..., delay=..., message_id=...)` so delayed
+  publishing preserves caller-provided message ids.
 
 ### 修复
 
-- 对 Redis 6.2 以下版本使用 `BRPOPLPUSH` 时，将 timeout 规范为整数秒，
-  提升 Redis 5.x List 消费兼容性。
+- 修复升级到 `0.13.0` 后，历史消息中空白 `headers["trace_id"]` 可能导致
+  消息构造或消费失败的兼容性回归。
+- 修复同步和异步 `publish(..., delay=..., message_id=...)`，现在延迟发布会
+  保留调用方传入的消息 ID。
 
-## [0.11.2] - 2026-06-21
+## [0.13.0] - 2026-06-27
 
-### Fixed
+### Added
+
+- Added first-class `trace_id` support to `Message`, sync and async
+  `publish()`, sync and async `delay()`, List, Streams, and delayed task
+  backends.
+- Added trace propagation through message envelopes, retry, dead-letter,
+  delayed release, and requeue flows while remaining compatible with existing
+  `headers["trace_id"]` messages.
+- Added `trace_id` to monitoring events and CLI message output for lifecycle
+  correlation.
+- Added CLI `--trace-id` support for `publish` and `delay`.
+- Added `new_trace_id()` helper for callers that want RedQueue-generated trace
+  identifiers.
+
+### 新增
+
+- `Message`、同步和异步 `publish()`、同步和异步 `delay()`、List、Streams
+  和延迟任务后端新增一等 `trace_id` 支持。
+- trace 会穿过消息 envelope、重试、死信、延迟释放和重放流程，并兼容已有的
+  `headers["trace_id"]` 消息。
+- 监控事件和 CLI 消息输出新增 `trace_id`，方便按链路聚合生命周期事件。
+- CLI 的 `publish` 和 `delay` 命令新增 `--trace-id`。
+- 新增 `new_trace_id()` helper，方便调用方生成 RedQueue trace 标识。
+
+## [0.12.0] - 2026-06-23
+
+### Added
+
+- Added the `redqueue` CLI and `python -m redqueue` module entry point for
+  developer debugging.
+- Added CLI commands for Redis compatibility checks, queue statistics, message
+  publish, consume with optional ack/nack/retry, delayed scheduling, due
+  release, and dead-letter inspection.
+- Added deterministic JSON CLI output and user-facing JSON validation errors.
+- Added CLI unit tests with injected fake Redis and queue clients.
+
+### Fixed
+
+- Normalized `BRPOPLPUSH` timeout values to integer seconds for Redis versions
+  older than 6.2, improving Redis 5.x List consume compatibility.
+
+### 新增
+
+- 新增 `redqueue` CLI 和 `python -m redqueue` 模块入口，方便开发者调试。
+- 新增 Redis 兼容性检查、队列统计、消息发布、消费并可选 ack/nack/retry、
+  延迟调度、到期释放和死信查看命令。
+- CLI 输出稳定 JSON，并提供面向用户的 JSON 参数校验错误。
+- 新增基于 fake Redis 和 fake queue client 的 CLI 单元测试。
+
+### 修复
+
+- 对 Redis 6.2 以下版本使用 `BRPOPLPUSH` 时，将 timeout 规范为整数秒，
+  提升 Redis 5.x List 消费兼容性。
+
+## [0.11.2] - 2026-06-21
+
+### Fixed
 
 - Fixed cleanup for directly constructed sync clients when owned Redis backend
   initialization fails.

{redqueue-0.12.0 → redqueue-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redqueue
-Version: 0.12.0
+Version: 0.13.1
 Summary: Redis-backed Python message queue library with List, Streams, delayed tasks, and monitoring.
 Project-URL: Homepage, https://github.com/SpringMirror-pear/redqueue
 Project-URL: Repository, https://github.com/SpringMirror-pear/redqueue.git
@@ -51,6 +51,7 @@ https://github.com/SpringMirror-pear/redqueue.git
 - Sync client `QueueClient` and async client `AsyncQueueClient`.
 - Redis connection pool managers for shared sync and async resources.
 - `redqueue` CLI for local debugging and operational checks.
+- First-class `trace_id` propagation for lifecycle tracing.
 - Unified exception hierarchy with structured context.
 - Monitoring events for publish, consume, ack, nack, retry, dead letter, delay,
   and backend errors.
@@ -111,6 +112,12 @@ redqueue publish --queue emails --payload '{"to":"user@example.com"}'
 redqueue consume --queue emails --timeout 1 --ack
 ```
 
+Publish with trace correlation:
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}' --trace-id trace-123
+```
+
 Delayed task debugging:
 
 ```bash
@@ -131,7 +138,7 @@ All command output is JSON so it can be piped into scripts or log processors.
 Synchronous List queue:
 
 ```python
-from redqueue import QueueClient
+from redqueue import QueueClient, new_trace_id
 
 client = QueueClient.from_url(
     "redis://127.0.0.1:6379/0",
@@ -139,11 +146,13 @@ client = QueueClient.from_url(
     backend="list",
 )
 
-message_id = client.publish({"to": "user@example.com"})
+trace_id = new_trace_id()
+message_id = client.publish({"to": "user@example.com"}, trace_id=trace_id)
 message = client.consume(timeout=1)
 
 if message is not None:
     try:
+        print(message.trace_id)
         print(message.payload)
         client.ack(message)
     except Exception:
@@ -197,10 +206,30 @@ Delayed task:
 from redqueue import QueueClient
 
 client = QueueClient.from_url("redis://127.0.0.1:6379/0", queue="emails")
-client.delay({"to": "later@example.com"}, delay_seconds=60)
+client.delay({"to": "later@example.com"}, delay_seconds=60, trace_id="trace-123")
 released = client.schedule_due(limit=100)
 ```
 
+Trace IDs:
+
+```python
+from redqueue import InMemoryMonitoringHook, QueueClient, new_trace_id
+
+hook = InMemoryMonitoringHook()
+client = QueueClient.from_url(
+    "redis://127.0.0.1:6379/0",
+    queue="emails",
+    monitoring=hook,
+)
+
+trace_id = new_trace_id()
+client.publish({"to": "user@example.com"}, trace_id=trace_id)
+message = client.consume(timeout=1)
+
+assert message.trace_id == trace_id
+assert hook.events[-1].trace_id == trace_id
+```
+
 Connection pool management:
 
 ```python
@@ -338,7 +367,7 @@ REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m "
 
 Latest local run on Python `3.14.5`:
 
-- Full test suite without `REDQUEUE_REDIS_URL`: `77 passed, 8 skipped`.
+- Full test suite without `REDQUEUE_REDIS_URL`: `102 passed, 8 skipped`.
 - Real Redis availability suite: `3 passed` with
   `redis://127.0.0.1:6379/0`.
 - Real Redis server: Redis for Windows `5.0.14.1`.

{redqueue-0.12.0 → redqueue-0.13.1}/README-zh-CN.md

@@ -14,10 +14,11 @@ https://github.com/SpringMirror-pear/redqueue.git
   `BRPOPLPUSH`。
 - 基于 Redis Streams 的消费组后端，Streams 要求 Redis `>=5.0`。
 - 基于 Redis Sorted Set 的延迟任务。
-- 同步客户端 `QueueClient` 与异步客户端 `AsyncQueueClient`。
-- 支持同步和异步 Redis 连接池管理器，方便多个客户端共享连接池。
-- 提供 `redqueue` CLI，用于本地调试和运行时检查。
-- 带结构化上下文的统一异常体系。
+- 同步客户端 `QueueClient` 与异步客户端 `AsyncQueueClient`。
+- 支持同步和异步 Redis 连接池管理器，方便多个客户端共享连接池。
+- 提供 `redqueue` CLI，用于本地调试和运行时检查。
+- 一等 `trace_id` 链路追踪能力，贯穿消息生命周期。
+- 带结构化上下文的统一异常体系。
 - 针对发布、消费、确认、拒绝、重试、死信、延迟和后端错误的监控事件。
 - 通过 `INFO server` 探测 Redis 能力。
 - Apache License 2.0。
@@ -42,61 +43,67 @@ Redis：
 
 ## 安装
 
-```bash
-pip install redqueue
-```
-
-安装后会提供 `redqueue` 命令。从源码目录调试时也可以使用
-`python -m redqueue`。
-
-本地开发：
+```bash
+pip install redqueue
+```
+
+安装后会提供 `redqueue` 命令。从源码目录调试时也可以使用
+`python -m redqueue`。
+
+本地开发：
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+## CLI
+
+检查 Redis 兼容性：
 
 ```bash
-python -m pip install -r requirements.txt
-```
-
-## CLI
-
-检查 Redis 兼容性：
-
-```bash
-redqueue check --url redis://127.0.0.1:6379/0
-```
-
-查看队列统计：
-
-```bash
-redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
-```
-
-发布和消费消息：
-
-```bash
-redqueue publish --queue emails --payload '{"to":"user@example.com"}'
-redqueue consume --queue emails --timeout 1 --ack
-```
-
-调试延迟任务：
-
-```bash
-redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
-redqueue schedule-due --queue emails --limit 100
-```
-
-查看死信：
-
-```bash
-redqueue dead-letters --queue emails --limit 20
-```
-
-所有命令都输出 JSON，方便接入脚本和日志处理流程。
-
-## 快速开始
+redqueue check --url redis://127.0.0.1:6379/0
+```
+
+查看队列统计：
+
+```bash
+redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
+```
+
+发布和消费消息：
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}'
+redqueue consume --queue emails --timeout 1 --ack
+```
+
+发布时指定 trace：
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}' --trace-id trace-123
+```
+
+调试延迟任务：
+
+```bash
+redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
+redqueue schedule-due --queue emails --limit 100
+```
+
+查看死信：
+
+```bash
+redqueue dead-letters --queue emails --limit 20
+```
+
+所有命令都输出 JSON，方便接入脚本和日志处理流程。
+
+## 快速开始
 
 同步 List 队列：
 
 ```python
-from redqueue import QueueClient
+from redqueue import QueueClient, new_trace_id
 
 client = QueueClient.from_url(
     "redis://127.0.0.1:6379/0",
@@ -104,11 +111,13 @@ client = QueueClient.from_url(
     backend="list",
 )
 
-message_id = client.publish({"to": "user@example.com"})
+trace_id = new_trace_id()
+message_id = client.publish({"to": "user@example.com"}, trace_id=trace_id)
 message = client.consume(timeout=1)
 
 if message is not None:
     try:
+        print(message.trace_id)
         print(message.payload)
         client.ack(message)
     except Exception:
@@ -162,10 +171,30 @@ asyncio.run(main())
 from redqueue import QueueClient
 
 client = QueueClient.from_url("redis://127.0.0.1:6379/0", queue="emails")
-client.delay({"to": "later@example.com"}, delay_seconds=60)
+client.delay({"to": "later@example.com"}, delay_seconds=60, trace_id="trace-123")
 released = client.schedule_due(limit=100)
 ```
 
+链路追踪：
+
+```python
+from redqueue import InMemoryMonitoringHook, QueueClient, new_trace_id
+
+hook = InMemoryMonitoringHook()
+client = QueueClient.from_url(
+    "redis://127.0.0.1:6379/0",
+    queue="emails",
+    monitoring=hook,
+)
+
+trace_id = new_trace_id()
+client.publish({"to": "user@example.com"}, trace_id=trace_id)
+message = client.consume(timeout=1)
+
+assert message.trace_id == trace_id
+assert hook.events[-1].trace_id == trace_id
+```
+
 连接池管理：
 
 ```python
@@ -300,7 +329,7 @@ REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m "
 
 Python `3.14.5` 最新本地运行结果：
 
-- 未设置 `REDQUEUE_REDIS_URL` 时的完整测试套件：`77 passed, 8 skipped`。
+- 未设置 `REDQUEUE_REDIS_URL` 时的完整测试套件：`102 passed, 8 skipped`。
 - 真实 Redis 可用性套件：使用 `redis://127.0.0.1:6379/0` 时 `3 passed`。
 - 真实 Redis 服务端：Redis for Windows `5.0.14.1`。
 - 可用性套件覆盖：List processing 恢复、List 死信重放、Streams Redis

{redqueue-0.12.0 → redqueue-0.13.1}/README.md

@@ -15,10 +15,11 @@ https://github.com/SpringMirror-pear/redqueue.git
   fallback on older compatible Redis versions.
 - Redis Streams backend with consumer groups. Streams require Redis `>=5.0`.
 - Delayed tasks based on Redis Sorted Set.
-- Sync client `QueueClient` and async client `AsyncQueueClient`.
-- Redis connection pool managers for shared sync and async resources.
-- `redqueue` CLI for local debugging and operational checks.
-- Unified exception hierarchy with structured context.
+- Sync client `QueueClient` and async client `AsyncQueueClient`.
+- Redis connection pool managers for shared sync and async resources.
+- `redqueue` CLI for local debugging and operational checks.
+- First-class `trace_id` propagation for lifecycle tracing.
+- Unified exception hierarchy with structured context.
 - Monitoring events for publish, consume, ack, nack, retry, dead letter, delay,
   and backend errors.
 - Redis capability detection from `INFO server`.
@@ -44,61 +45,67 @@ Redis:
 
 ## Installation
 
-```bash
-pip install redqueue
-```
-
-The package installs a `redqueue` command. You can also run it with
-`python -m redqueue` from a source checkout.
-
-For local development:
+```bash
+pip install redqueue
+```
+
+The package installs a `redqueue` command. You can also run it with
+`python -m redqueue` from a source checkout.
+
+For local development:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+## CLI
+
+Check Redis compatibility:
 
 ```bash
-python -m pip install -r requirements.txt
-```
-
-## CLI
-
-Check Redis compatibility:
-
-```bash
-redqueue check --url redis://127.0.0.1:6379/0
-```
-
-Inspect queue counts:
-
-```bash
-redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
-```
-
-Publish and consume messages:
-
-```bash
-redqueue publish --queue emails --payload '{"to":"user@example.com"}'
-redqueue consume --queue emails --timeout 1 --ack
-```
-
-Delayed task debugging:
-
-```bash
-redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
-redqueue schedule-due --queue emails --limit 100
-```
-
-Dead-letter inspection:
-
-```bash
-redqueue dead-letters --queue emails --limit 20
-```
-
-All command output is JSON so it can be piped into scripts or log processors.
-
-## Quick Start
+redqueue check --url redis://127.0.0.1:6379/0
+```
+
+Inspect queue counts:
+
+```bash
+redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
+```
+
+Publish and consume messages:
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}'
+redqueue consume --queue emails --timeout 1 --ack
+```
+
+Publish with trace correlation:
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}' --trace-id trace-123
+```
+
+Delayed task debugging:
+
+```bash
+redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
+redqueue schedule-due --queue emails --limit 100
+```
+
+Dead-letter inspection:
+
+```bash
+redqueue dead-letters --queue emails --limit 20
+```
+
+All command output is JSON so it can be piped into scripts or log processors.
+
+## Quick Start
 
 Synchronous List queue:
 
 ```python
-from redqueue import QueueClient
+from redqueue import QueueClient, new_trace_id
 
 client = QueueClient.from_url(
     "redis://127.0.0.1:6379/0",
@@ -106,11 +113,13 @@ client = QueueClient.from_url(
     backend="list",
 )
 
-message_id = client.publish({"to": "user@example.com"})
+trace_id = new_trace_id()
+message_id = client.publish({"to": "user@example.com"}, trace_id=trace_id)
 message = client.consume(timeout=1)
 
 if message is not None:
     try:
+        print(message.trace_id)
         print(message.payload)
         client.ack(message)
     except Exception:
@@ -164,10 +173,30 @@ Delayed task:
 from redqueue import QueueClient
 
 client = QueueClient.from_url("redis://127.0.0.1:6379/0", queue="emails")
-client.delay({"to": "later@example.com"}, delay_seconds=60)
+client.delay({"to": "later@example.com"}, delay_seconds=60, trace_id="trace-123")
 released = client.schedule_due(limit=100)
 ```
 
+Trace IDs:
+
+```python
+from redqueue import InMemoryMonitoringHook, QueueClient, new_trace_id
+
+hook = InMemoryMonitoringHook()
+client = QueueClient.from_url(
+    "redis://127.0.0.1:6379/0",
+    queue="emails",
+    monitoring=hook,
+)
+
+trace_id = new_trace_id()
+client.publish({"to": "user@example.com"}, trace_id=trace_id)
+message = client.consume(timeout=1)
+
+assert message.trace_id == trace_id
+assert hook.events[-1].trace_id == trace_id
+```
+
 Connection pool management:
 
 ```python
@@ -235,7 +264,7 @@ RedQueue uses a lightweight Git Flow model:
 ## Documentation
 
 - Chinese README: [README-zh-CN.md](README-zh-CN.md)
-- API: [docs/API.md](docs/API.md)
+- API: [docs/API.md](docs/API.md)
 - Examples: [examples/README.md](examples/README.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 - Release process: [docs/RELEASE.md](docs/RELEASE.md)
@@ -245,7 +274,7 @@ RedQueue uses a lightweight Git Flow model:
 
 ## Examples
 
-The `examples/` directory contains runnable scripts for synchronous List queues,
+The `examples/` directory contains runnable scripts for synchronous List queues,
 asynchronous List queues, Streams, delayed tasks, monitoring hooks, custom
 serializers, and Redis compatibility checks.
 
@@ -305,7 +334,7 @@ REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m "
 
 Latest local run on Python `3.14.5`:
 
-- Full test suite without `REDQUEUE_REDIS_URL`: `77 passed, 8 skipped`.
+- Full test suite without `REDQUEUE_REDIS_URL`: `102 passed, 8 skipped`.
 - Real Redis availability suite: `3 passed` with
   `redis://127.0.0.1:6379/0`.
 - Real Redis server: Redis for Windows `5.0.14.1`.