redqueue 0.10.1__tar.gz → 0.11.1__tar.gz

{redqueue-0.10.1 → redqueue-0.11.1}/CHANGELOG.md

@@ -1,110 +1,164 @@
-# Changelog / 版本变更记录
-
-All notable public release changes are documented here.
-
-所有公开发布版本的重要变更都会记录在此文件中。
-
+# Changelog / 版本变更记录
+
+All notable public release changes are documented here.
+
+所有公开发布版本的重要变更都会记录在此文件中。
+
 Development versions are tracked separately from formal release versions.
 开发版本与正式版本分开管理。
 
-## [0.10.1] - 2026-06-20
+## [0.11.1] - 2026-06-21
 
 ### Fixed
 
-- Fixed Redis List `ack`, `nack`, `retry`, and dead-letter requeue when custom
-  serializers do not produce deterministic bytes.
-- Fixed delayed task scheduling cleanup so payload keys are removed if `ZADD`
-  fails after `SET`.
-- Fixed Streams dead-letter reads and moves by ensuring the consumer group also
-  exists on the dead-letter stream.
-- Fixed async client creation monitoring so `AsyncQueueClient` emits the same
-  `client.created` event as the synchronous client.
-- Removed duplicate delay scheduling monitoring events from the synchronous
-  client facade.
-- Normalized internal Redis Streams entry ids returned as bytes.
+- Fixed resource cleanup in sync and async `from_url()` when Redis capability
+  detection, configuration validation, or backend initialization fails after the
+  client created an owned Redis connection.
+- Added explicit `owns_redis` override support to sync and async `from_url()`
+  for advanced ownership control.
 
 ### 修复
 
-- 修复自定义序列化器输出字节不稳定时，Redis List `ack`、`nack`、`retry`
-  和死信重放无法精确删除原始消息的问题。
-- 修复延迟任务在 `SET` 成功但 `ZADD` 失败时残留 payload key 的问题。
-- 修复 Streams 死信读取和搬移前未确保死信 stream 消费组存在的问题。
-- 修复异步客户端创建时未与同步客户端一致发出 `client.created` 监控事件的问题。
-- 移除同步客户端门面层重复发出的延迟调度监控事件。
-- 统一规范化 Redis Streams 返回的 bytes 类型 entry id。
-
-### Validation
-
-- `python -m ruff check .`
-- `PYTHONPATH=src python -m mypy`
-- `PYTHONPATH=src python -m pytest`
-- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
-
-### 验证
-
-- `python -m ruff check .`
-- `PYTHONPATH=src python -m mypy`
-- `PYTHONPATH=src python -m pytest`
-- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
-
-## [0.10.0] - 2026-06-20
-
-### Added
-
-- Initial public release of RedQueue.
-- Synchronous `QueueClient` and asynchronous `AsyncQueueClient`.
-- Redis List backend with reliable processing, ack, nack, retry, recovery, and
-  dead-letter support.
-- Redis Streams backend with consumer groups, ack, retry, dead-letter support,
-  and pending recovery.
-- Delayed tasks based on Redis Sorted Set.
-- Redis version and capability detection through `INFO server`.
-- Unified exception hierarchy with structured context.
-- JSON serializer and custom serializer protocol.
-- Monitoring hook system with safe wrapper, in-memory hook, and composite hook.
-- Unit, contract, asynchronous, and opt-in Redis integration tests.
-- GitHub Actions CI and local quality check script.
-
-### 新增
-
-- RedQueue 首个公开发布版本。
-- 同步 `QueueClient` 与异步 `AsyncQueueClient`。
-- Redis List 后端，支持可靠处理、ack、nack、retry、恢复和死信。
-- Redis Streams 后端，支持消费组、ack、retry、死信和 pending 恢复。
-- 基于 Redis Sorted Set 的延迟任务。
-- 通过 `INFO server` 进行 Redis 版本与能力探测。
-- 带结构化上下文的统一异常体系。
-- JSON 序列化器与自定义序列化协议。
-- 监控 hook 系统，包含安全包装、内存 hook 和组合 hook。
-- 单元测试、契约测试、异步测试和可选 Redis 集成测试。
-- GitHub Actions CI 与本地质量检查脚本。
-
-### Compatibility
-
-- Python `>=3.9`.
-- Runtime dependency `redis==6.4.0`.
-- Redis Streams require Redis `>=5.0`.
-- Redis Streams `XAUTOCLAIM` and List `BLMOVE` are used when Redis `>=6.2`.
-- Delayed tasks use Redis Sorted Set.
-
-### 兼容性
-
-- Python `>=3.9`。
-- 运行依赖 `redis==6.4.0`。
-- Redis Streams 要求 Redis `>=5.0`。
-- Redis `>=6.2` 时使用 Streams `XAUTOCLAIM` 与 List `BLMOVE`。
-- 延迟任务使用 Redis Sorted Set。
-
-### Validation
-
-- `python -m ruff check .`
-- `PYTHONPATH=src python -m mypy`
-- `PYTHONPATH=src python -m pytest`
-- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
-
-### 验证
-
-- `python -m ruff check .`
-- `PYTHONPATH=src python -m mypy`
-- `PYTHONPATH=src python -m pytest`
-- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
+- 修复同步和异步 `from_url()` 在自动创建 Redis 连接后，如果 Redis 能力探测、
+  配置校验或后端初始化失败，已创建连接未释放的问题。
+- 同步和异步 `from_url()` 新增显式 `owns_redis` 覆盖支持，用于高级资源所有权
+  控制。
+
+## [0.11.0] - 2026-06-21
+
+### Added
+
+- Added synchronous `RedisConnectionManager` and asynchronous
+  `AsyncRedisConnectionManager` for shared Redis connection pool ownership.
+- Added client context manager support for explicit sync and async resource
+  cleanup.
+- Added `connection_manager` and `pool_options` support to sync and async
+  `from_url` constructors.
+- Added `README-zh-CN.md` and converted `README.md` to English-only content.
+- Added `CONTRIBUTING.md` with the project branch model and contribution
+  workflow.
+- Added `CODE_OF_CONDUCT.md`.
+
+### Changed
+
+- Updated formal release version to `0.11.0`.
+- Documented the branch model: `main`, `develop`, `feature/*`, `release/*`,
+  and `hotfix/*`.
+
+### 新增
+
+- 新增同步 `RedisConnectionManager` 和异步 `AsyncRedisConnectionManager`，
+  用于共享 Redis 连接池所有权管理。
+- 新增客户端上下文管理器支持，用于显式释放同步和异步资源。
+- 同步和异步 `from_url` 构造器新增 `connection_manager` 和 `pool_options`
+  支持。
+- 新增 `README-zh-CN.md`，并将 `README.md` 调整为纯英文文档。
+- 新增 `CONTRIBUTING.md`，记录项目分支模型和贡献流程。
+- 新增 `CODE_OF_CONDUCT.md`。
+
+### 变更
+
+- 正式版本更新为 `0.11.0`。
+- 记录分支模型：`main`、`develop`、`feature/*`、`release/*` 和 `hotfix/*`。
+
+## [0.10.1] - 2026-06-20
+
+### Fixed
+
+- Fixed Redis List `ack`, `nack`, `retry`, and dead-letter requeue when custom
+  serializers do not produce deterministic bytes.
+- Fixed delayed task scheduling cleanup so payload keys are removed if `ZADD`
+  fails after `SET`.
+- Fixed Streams dead-letter reads and moves by ensuring the consumer group also
+  exists on the dead-letter stream.
+- Fixed async client creation monitoring so `AsyncQueueClient` emits the same
+  `client.created` event as the synchronous client.
+- Removed duplicate delay scheduling monitoring events from the synchronous
+  client facade.
+- Normalized internal Redis Streams entry ids returned as bytes.
+
+### 修复
+
+- 修复自定义序列化器输出字节不稳定时，Redis List `ack`、`nack`、`retry`
+  和死信重放无法精确删除原始消息的问题。
+- 修复延迟任务在 `SET` 成功但 `ZADD` 失败时残留 payload key 的问题。
+- 修复 Streams 死信读取和搬移前未确保死信 stream 消费组存在的问题。
+- 修复异步客户端创建时未与同步客户端一致发出 `client.created` 监控事件的问题。
+- 移除同步客户端门面层重复发出的延迟调度监控事件。
+- 统一规范化 Redis Streams 返回的 bytes 类型 entry id。
+
+### Validation
+
+- `python -m ruff check .`
+- `PYTHONPATH=src python -m mypy`
+- `PYTHONPATH=src python -m pytest`
+- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
+
+### 验证
+
+- `python -m ruff check .`
+- `PYTHONPATH=src python -m mypy`
+- `PYTHONPATH=src python -m pytest`
+- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
+
+## [0.10.0] - 2026-06-20
+
+### Added
+
+- Initial public release of RedQueue.
+- Synchronous `QueueClient` and asynchronous `AsyncQueueClient`.
+- Redis List backend with reliable processing, ack, nack, retry, recovery, and
+  dead-letter support.
+- Redis Streams backend with consumer groups, ack, retry, dead-letter support,
+  and pending recovery.
+- Delayed tasks based on Redis Sorted Set.
+- Redis version and capability detection through `INFO server`.
+- Unified exception hierarchy with structured context.
+- JSON serializer and custom serializer protocol.
+- Monitoring hook system with safe wrapper, in-memory hook, and composite hook.
+- Unit, contract, asynchronous, and opt-in Redis integration tests.
+- GitHub Actions CI and local quality check script.
+
+### 新增
+
+- RedQueue 首个公开发布版本。
+- 同步 `QueueClient` 与异步 `AsyncQueueClient`。
+- Redis List 后端，支持可靠处理、ack、nack、retry、恢复和死信。
+- Redis Streams 后端，支持消费组、ack、retry、死信和 pending 恢复。
+- 基于 Redis Sorted Set 的延迟任务。
+- 通过 `INFO server` 进行 Redis 版本与能力探测。
+- 带结构化上下文的统一异常体系。
+- JSON 序列化器与自定义序列化协议。
+- 监控 hook 系统，包含安全包装、内存 hook 和组合 hook。
+- 单元测试、契约测试、异步测试和可选 Redis 集成测试。
+- GitHub Actions CI 与本地质量检查脚本。
+
+### Compatibility
+
+- Python `>=3.9`.
+- Runtime dependency `redis==6.4.0`.
+- Redis Streams require Redis `>=5.0`.
+- Redis Streams `XAUTOCLAIM` and List `BLMOVE` are used when Redis `>=6.2`.
+- Delayed tasks use Redis Sorted Set.
+
+### 兼容性
+
+- Python `>=3.9`。
+- 运行依赖 `redis==6.4.0`。
+- Redis Streams 要求 Redis `>=5.0`。
+- Redis `>=6.2` 时使用 Streams `XAUTOCLAIM` 与 List `BLMOVE`。
+- 延迟任务使用 Redis Sorted Set。
+
+### Validation
+
+- `python -m ruff check .`
+- `PYTHONPATH=src python -m mypy`
+- `PYTHONPATH=src python -m pytest`
+- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`
+
+### 验证
+
+- `python -m ruff check .`
+- `PYTHONPATH=src python -m mypy`
+- `PYTHONPATH=src python -m pytest`
+- `REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration`

redqueue-0.11.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Code of Conduct
+
+RedQueue follows a simple contributor covenant: be respectful, direct, and
+focused on improving the project.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Be respectful of different experience levels and viewpoints.
+- Give and receive technical feedback with concrete reasoning.
+- Keep discussions focused on the code, documentation, tests, and project
+  outcomes.
+- Assume good intent, but correct issues clearly when they affect quality,
+  safety, or maintainability.
+
+## Unacceptable Behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Personal attacks or sustained disruption of project discussions.
+- Publishing private information without explicit permission.
+- Sharing credentials, tokens, or sensitive operational data.
+- Any behavior that makes collaboration unsafe or unproductive.
+
+## Scope
+
+This code of conduct applies in project repositories, issues, pull requests,
+discussion channels, release processes, and other spaces representing RedQueue.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, reject pull requests, or restrict
+participation when behavior violates this code of conduct. Enforcement should be
+proportional, documented where appropriate, and focused on restoring productive
+collaboration.
+
+## Reporting
+
+Report issues through the project issue tracker or by contacting the maintainer
+listed in the project metadata. Do not include sensitive personal information in
+public reports.

redqueue-0.11.1/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to RedQueue
+
+Thank you for contributing to RedQueue. This project favors small, well-tested
+changes that preserve Redis compatibility and clear resource ownership.
+
+## Branch Model
+
+RedQueue uses a lightweight Git Flow model:
+
+- `main`: stable release branch and the latest formal release. Release branches
+  and urgent hotfixes merge here.
+- `develop`: integration branch for the next minor release.
+- `feature/<name>`: feature branches created from `develop` and merged back to
+  `develop`.
+- `release/<minor>`: release stabilization branches such as `release/0.11`.
+- `hotfix/<version>`: urgent patch branches created from `main`, then merged
+  back to both `main` and `develop`.
+
+## Workflow
+
+1. Create feature branches from `develop`.
+2. Keep changes focused and avoid unrelated refactors.
+3. Add or update tests for behavioral changes.
+4. Update documentation when public APIs or workflows change.
+5. Open a pull request into `develop` for regular work, or into the active
+   `release/<minor>` branch for release stabilization fixes.
+6. After a release is stabilized, merge `release/<minor>` into `main`, tag the
+   release from `main`, and publish the package.
+
+## Versioning
+
+- Development versions use `0.1x.xdevN`.
+- Formal releases use `0.1x.x`.
+- Development and formal release version streams are independent.
+- Patch releases fix defects.
+- Minor releases may add compatible features.
+
+## Quality Checks
+
+Run the local quality gate before opening a pull request:
+
+```bash
+PYTHONPATH=src python scripts/check.py
+```
+
+Run Redis integration tests when Redis behavior changes:
+
+```bash
+REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m integration
+```
+
+Run real Redis availability and performance tests when queue reliability or
+connection behavior changes:
+
+```bash
+REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m "integration and availability"
+REDQUEUE_REDIS_URL=redis://127.0.0.1:6379/0 PYTHONPATH=src python -m pytest -m "integration and performance"
+```
+
+## Python Source Requirements
+
+Every Python source file must include:
+
+```python
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+```
+
+Use Google-style docstrings for public classes, functions, and non-trivial
+internal helpers.
+
+## Compatibility Expectations
+
+- Python runtime support starts at `>=3.9`.
+- Redis Streams require Redis `>=5.0`.
+- Redis 5.x must continue to use `XPENDING`/`XCLAIM` fallback for pending
+  recovery.
+- Redis `>=6.2` may use `XAUTOCLAIM` and `BLMOVE`.
+- Keep sync and async APIs aligned unless there is a documented reason not to.
+
+## Pull Request Checklist
+
+- Tests cover the changed behavior.
+- `ruff`, `mypy`, and `pytest` pass.
+- Public docs are updated when public behavior changes.
+- Changelog entries are added for release branches.
+- No credentials, tokens, local Redis data, or build artifacts are committed.