nadis
nadis 是 Redis 基础层,覆盖连接、常用命令、pipeline、nonce 幂等计数、分布式锁、leader、Pub/Sub、Stream、分区消费和可选 RedisJob、RediSearch/RedisJSON。它把旧系统兼容协议和纯 Rust 增强协议用 CompatibilityProfile 明确区分,避免业务无意混用持久化边界。
它解决两类容易被业务代码错误拼装的原子边界:计数写与 nonce 凭证在同一 Lua 内结算,分布式任务的调度、租约、fencing、Fanout 与完成状态也只通过封闭脚本迁移。业务只调用类型化 API,不接触账本命令或裸 Lua 返回值。
分区消费由 Redis 负责持久接管,每个 RunningPartition 独占 napart Runner 集合;默认按源共享,
可配置 group 或 stream 隔离慢组或慢物理 Stream 的调度与容量。不同 Redis 源始终独立。业务键
顺序覆盖 handler、ACK 和精确重试。ACK 结果不确定时保留提交责任,不重跑成功 handler。全部消费组
受源级有界记录与正文总预算约束,隔离模式将预算分为固定域份额。正常停机超时可以继续等待同一个排干操作。
普通 Stream、共享消费组 Proxy 与 AutoPipeline 可由 Application 按命名计划管理:统一放行消费和 调用、限制微批参数字节、等待真实任务退出,并在缺少 PEL 证据时保留 consumer。业务无需另建消费 或关闭 owner;具体配置与边界见受管入口。
Handler 通过 JobContext::parameter::<T>() 获取 JSON 参数,T 可以是包含集合、映射或嵌套结构的任意 serde::DeserializeOwned 类型;框架会先执行重复键、深度和节点预算校验。非 JSON 参数通过 payload() 读取原始字节并由业务按声明的 codec 解码,框架不会猜测 Protobuf 类型。
业务项目通过门面开启 redis:
[]
= { = "2.0.0", = ["redis"] }
连接 Redis
use ;
async
profile 必须显式选择:
LegacyV1: 与旧版/历史 Redis 协议互通。RustV2: 纯 Rust 集群增强协议,包含 Redis TIME、fencing 等新语义。
不同 profile 不要共享同一持久化 namespace。
常用命令
let client = connect.await?;
client.set.await?;
let name: = client.get.await?;
client.h_set.await?;
let level: = client.h_get.await?;
client.expire.await?;
nasa::redis::Json<T> 使用标准 serde_json 编码。需要处理序列化失败时,先调用
Json(&value).to_bytes()?,再把字节交给 Redis 命令;直接作为命令参数时,序列化失败会 panic。
浮点 NaN 和无穷会编码为 JSON null,要求有限数值的业务必须先校验。整数 map key 可以编码为
字符串键,数组等复合 key 会被拒绝;解码不会根据类名或类型元数据自动选择业务类型。
Cluster 多 key 命令会做同 slot 守卫;需要跨 key 时请使用 {tag} 约束 slot。分区运行时以
“分区组”为同槽单位:同组所有 stream、锁、marker 和控制 key 固定到一个 slot。partition.count
增加的是组内并发,不会把单组分散到多个 master。partition.groups 可拆出不同 hash tag,
但不同组仍可能落在同一 master;需要跨 master 扩吞吐时须同时核对实际 slot 分布。
Redis 相对 TTL 最终由 signed 64-bit 毫秒或秒参数表达;超过服务端范围的 Duration 会在本地
返回配置错误,不会截断、回绕或发送负 TTL。
Pipeline
适合批量读写并减少 RTT。命令入队后通过 execute().await 统一发送,再从 Ticket 取结果。
let mut pipe = client.pipeline;
let name = pipe.?;
let age = pipe.?;
pipe.execute.await?;
let name = name.await_result?;
let age = age.await_result?;
需要防重放的计数必须显式使用 nonce API。直发与批量入口共用同一账本;每条批量命令拥有自己的 nonce 和完整原子 Lua,不存在“先查 nonce、再入队原生命令”的并发窗口:
let settled = client.incr_by_idempotent.await?;
let mut batch = client.idempotent_pipeline.await?;
let replay = batch.decr_by_idempotent?;
let next = batch.h_incr_by_idempotent?;
batch.execute.await?;
assert_eq!;
let quota = next.await_result?;
String、Hash 与 ZSet 共提供九个 *_idempotent helper。nonce 不能为空;同一目标、结构成员与 nonce 在窗口内只结算一次,即使重放时改变方向或 delta 也返回首次结果。专用会话只在 execute() 提交;达到普通 Pipeline 的条数或字节上限会在入队前拒绝,尚未提交的整会话确定未发送。普通 pipeline() 不推断 nonce,也不会改变原命令语义。首次调用会确认账本布局;受管 Redis 仅预留本地指标,未显式配置且未调用时不会探测额外能力。
HASH_FIELD 需要全部 master 支持 HPEXPIRE;HASH_BUCKET 使用时间桶;AUTO 只在全量响应明确确认命令不存在时选择时间桶。探测超时、ACL 拒绝、拓扑不稳或节点结果缺失会拒绝本次准备且不建立 marker,后续调用可重新探测。与 Java LegacyV1 共享账本还要求 key、Hash field 和 ZSet member 的序列化字节一致。
RedisJob
直接依赖 nadis 时开启 job feature;业务经 nasa 门面时开启 redis-job。nadis::job 提供无全局 leader 的分布式任务运行时。多节点可以同时扫描,到期触发、领取、续租、完成、恢复和 Fanout assignment 都由 Redis 时间、CAS、owner、attempt token 与 fencing 收敛。普通任务可以共享 Worker Stream 与独立容量池;Fanout 目标必须声明为 FANOUT_ONLY,避免普通 Dispatcher 与定向 shard 竞争同一 Handler。
运行架构
RedisJob 将一次任务执行拆成四个持久阶段:定义与能力登记、调度与投递、执行权租约、终态对账。
业务定义/Handler
│ Prepare:source、namespace、schema、codec、能力快照冻结
▼
Redis 调度账本 ── Dispatch Stream/定向 inbox ──> Executor
│ │ │
│ └─ receipt/ready └─ start:owner + attempt token + lease
▼
扫描器:receipt、ready、lease、root 分桶对账 ──> CAS/Lua 终态提交与 Fanout 聚合
Prepare 阶段只发布已通过配置、定义、codec、容量和 source 门禁的计划;Dispatcher 取得执行权后才调用 Handler。Handler 外部写入必须携带 attempt_token 并在副作用前调用 checkpoint(),租约失效、取消或本地保守截止到达后立即停止。扫描器不是单一 leader,重复扫描依靠 Redis 权威时间、CAS、assignment epoch 和 fencing 收敛。
普通 Run 通过 Worker Stream 分发;Fanout 先冻结兼容执行器快照,再为每个快照成员建立一个 shard。目标先写入持久 receipt,再申请本地 Handler 槽位;容量不足进入独立容量窗口。容量超窗优先切换兼容目标,无候选时重开窗口并保留 assignment,不把健康满载节点改判为失联。
参数与编码
JSON Handler 使用 JobContext::parameter::<T>() 反序列化参数,支持 Vec<T>、HashMap<K, V>、嵌套结构和其它 serde::DeserializeOwned 类型。框架在业务类型反序列化前拒绝重复键、危险类型元数据、过深结构和节点数超限;反序列化失败返回结构化 InvalidPayload。Protobuf 或 RAW 参数不做类型猜测,业务通过 payload() 按定义的 codec 解码。
schema_id 与 wire_codec 是持久合同,不能由 Handler 根据 payload 内容动态选择;同一 Worker 的定义、Fanout 快照和执行器能力必须使用兼容的 schema 与 codec。
Fanout 目标在持久确认接收后若本地执行槽暂满,会在 fanout_capacity_wait_ms 窗口内保留当前 assignment、延后 ready 并清除普通唤醒计数;短时容量背压不会被当作节点失联,也不会产生 SKIPPED 或消耗节点切换配额。默认窗口为 10_000 毫秒,是防止单个满载目标无限占用分片的有界策略。连续等待超窗后,系统优先切换到兼容目标;没有可切换目标时重开容量等待窗口,继续保留当前 assignment,不把健康满载目标判为失联。只有稳定目标节点真的改变才增加 assignmentCount,同一节点的新启动或心跳证据只推进 assignment epoch。
容量路由使用独立的 capacityRouteCount 预算,不消耗故障重分配的 assignmentCount;每次容量迁移还会在 shard HASH 中累加 capacityRouteTotal。capacityRouteCount 用于当前调度裁决,成功取得执行权后清除;capacityRouteTotal 保留到 shard 清理前,供运维审计迁移次数。运行时指标反映进程级即时计数,不能替代该持久字段。
let definition = builder
.qualifier
.fixed_rate_ms
.build?;
let plan = new
.register?;
每个定义的 qualifier 是强路由字段。prepare_sources 接受冻结的 RedisJobSources,每个 source 独立拥有客户端、namespace、键布局、连接角色、监督代次、健康、指标和停机边界;未知、禁用或 client 身份不一致的 source 在写定义前拒绝。独立运行时可用 shutdown_source(qualifier, budget) 只排空一个 source,其它 source 继续领取和续租;全量停机使用 shutdown(budget)。启动先建立 Fanout 订阅再逐项登记能力;任一登记失败都会关闭本地准入,并按全部已尝试 Worker 坐标尝试全量注销,包含“脚本已提交但回包丢失”的能力。若 Redis 持续不可达而无法取得注销确认,本地不再接纳或处理工作,服务端成员与能力记录只由 TTL 和 Registry GC 收敛。JobControl 提供 trigger、单任务 pause/resume、当前 source 的 pause_namespace/resume_namespace、cancel、delete 与 conflict resolve;命名空间暂停阻止新的普通 Run 触发、尚未领取的普通 Run 和可见性消息重建,不撤销已有 attempt,也不影响其它 source。普通定义不宣告 Fanout 能力,删除 FANOUT_ONLY 定义会在 tombstone 提交后同步撤销执行器能力,撤销失败可用相同定义修订号幂等补偿,避免新 Fanout 快照继续选择已失去 Handler 的节点。JobQuery 提供 definition、run、Fanout、健康和无 Redis I/O 的指标快照。
停机先发布 Draining 并关闭新准入,再等待监督循环与已接纳 Handler。绝对期限到达时会对剩余 Tokio task 提交 abort,但注销 Registry 前仍会逐个 await JoinHandle,直到 future 实际结束、权威 guard 析构且容量许可释放;取消请求本身不作为所有权已终止的证据。
执行器心跳以最近一次 Redis 成功回包中的 redisNow/expireAt 折算本地保守权威截止,并使用不与
其它状态脚本共享断链结局的独立连接 lane。单机装载、Cluster 切换或槽迁移产生的
LOADING、TRYAGAIN、CLUSTERDOWN、MASTERDOWN、MOVED、ASK、READONLY
以及 Redis 的 ERR max number of clients reached 容量响应与传输失败一样,只能在该截止前有上限退避;
认证、ACL、本地客户端配置、RESP 解析、返回类型、其它 ERR 文案、跨 slot 或脚本合同错误立即拒绝;
兼容实现不得依赖未声明的模糊文案匹配,也不得把确定性的凭据或协议错误延迟到租约截止。
受监督运行时为每个逻辑心跳携带稳定请求 ID 和最后确认的 heartbeatRevision,因此传输重发只读取
第一次执行结果,不会重复延长服务端存活期;脚本也拒绝续期已经到期但尚未 GC 的记录。第一次续租若
已在 Redis 执行但其结果始终无法在旧截止前取回,本地仍会立即关闭准入,服务端成员可能保留到该次
续租的 TTL 到期;Fanout 投递必须依赖持久 receipt 和失联重分配收敛,不能把成员记录等同于进程确认。
后续成功会把 Degraded 恢复为 Up;NotFound、权威 revision 不一致、协议响应非法或已确认截止耗尽
会让 source 进入 NotReady。监督器只记录 source、循环与封闭原因,不记录 endpoint、payload 或凭据。
命名空间暂停或恢复按调度分片逐一发布,不是跨分片原子事务。控制调用返回错误时,部分分片可能已经进入目标状态,调用方不得据此判定整个 source 已暂停或已恢复,必须使用同一 actor 幂等重试直至成功。JobControl::namespace_governance 聚合 enabled、paused、untouched 与 unknown 分片数、最近权威时刻和 actor;混合状态或未知持久值都会把 divergent 置真,供治理面告警与续作,但不会把逐分片操作包装为原子成功。该门禁只阻止普通 Run 取得新执行权:已经取得的 attempt 可以继续续期和完成,已经建立的 Fanout 批次也会继续投递和收敛。
手工 trigger 在存在环境 trace 时只记录 trace_id 到派生 run_id 的映射;业务 request_id 原文
不进入日志。Run hash 与共享 Lua 的跨语言线协议在所有实现共同扩展前保持不变,因此 worker 侧
暂不从 RedisJob 持久状态恢复该 trace。
JSON Handler 在业务反序列化前递归拒绝重复键、@class/@type、过深或节点过多的结构。运行时只支持已经声明的协议、codec 与 Cron 语义,不承诺无限 Run 历史、永久 nonce、永久 Fanout 去重,也不会把普通本地定时任务自动升级为 RedisJob。
分布式锁
use DistributedLock;
let lock = new;
let guard = lock.lock.await?;
// 临界区:同一把锁由 watchdog 续租。
guard.unlock.await?;
也可以用 with_lock 包裹业务 future:
lock.with_lock.await?;
Leader
适合单 leader 后台任务或和 nasched 的 NadisLeaderGate 配合。
let lock = new;
let leader = elect;
leader.run_if_leader.await;
// 正常停机显式退位并等待锁释放。
leader.shutdown.await;
最后一个 Leader 句柄被直接丢弃时也会停止竞选并尝试释放锁,但 Drop 只能作为异常路径兜底;
服务停机仍应调用 shutdown().await。
Pub/Sub
let mut sub = client.sub.await?;
client.r#pub.await?;
if let Some = sub.next_message.await
分布式雪花 workerId
Redis 分配使用显式初始化、编号永久不复用的账本。管理方须从账本外证明首次初始化权威, 并保证已确认领取记录不会丢失或回退;不存在的 key 不能证明这是首次部署。
use ;
let cfg = default;
let namespace = WorkerIdNamespace ;
// 管理方确认整个 ID 空间未使用后,独立执行一次 namespace.initialize(&client, &cfg)。
let = namespace.allocate.await?;
let id = sf.generate;
lease.release.await?;
缺失账本、身份/位布局不符或容量耗尽均拒绝分配;release 不归还编号,没有 TTL 自动回收。
alloc_worker_id/build_with_redis 始终返回错误。incarnation 不进入 ID 位编码,改名不保证新旧 ID 空间隔离。
build_local 固定 workerId=1,同一 ID 空间只允许一个共享生成器;重启须越过上一实例的逻辑时间上界。
Application 使用 redis.snowflake.<name> 与 app.snowflake(name).await,由框架领取和关闭生成器。
Stream 消费
发布用 client.publish/publish_default/publish_many;订阅是 builder 链:
let sub = client
.subscribe // stream key
.group // 消费组 + 消费者名
.on
.start
.await?;
// 停机:
sub.shutdown.await;
单点和 Redis Cluster 都支持该 builder。Cluster 下每个订阅只读取一个 stream key,专用
ClusterConnection 按该 key 的 slot 路由并跟随 MOVED/ASK;API 不提供跨 slot 的多 stream
阻塞读。阻塞连接与普通命令连接隔离,订阅停机会取消阻塞读、idle、错误退避、重连和在途
handler;若取消与 XACK 同时发生,确认结果按不确定态处理,不会伪报未执行。
组内竞争消费、ack 策略、重投上限(max_redeliver)、毒消息策略(poison_policy)按下方 stream.* 配置;分区消费(同 key 串行、跨节点再均衡)入口为 PreparedPartition/RunningPartition,配置见 partition.*。
PreparedPartition::try_register_legacy 在注册点拒绝重复 (topic,event),并保留原 handler;
兼容链式 register 保存首个注册错误,随后由 start 返回。topic/event 必须非空、无首尾空白、
无控制字符且不超过 256 字节。没有任何 handler 的消费运行时不能启动。
prepare 只准备 Stream/group;start 复验全部路由和远端合同。全部组的监督任务就绪前不抢锁、
不读取、不调用 handler,启动事务提交后才一次性开放消费。远端 group 在 prepare 后被删除时
会幂等补齐;Stream 类型不符等错误会使启动失败,并关闭尚未激活的任务。
批量 handler 仍按 (topic,event) 接收一次成功解码子集的 Vec<T>,单条类型解码失败独立留在
PEL。一次批量调用返回失败、超时或 panic 时,该次传入的成功解码子集整体进入重投。
业务键有序分区消费
register_partitioned 将多个 topic 绑定为一个不可变消费计划,逐条 handler 接收
PartitionRecord<T>,包含已解码数据、完整 (stream,id) 和显式 passthrough。key 提取一次后,
同一摘要同时用于本地 gate 与 napart strict 路由;没有 key 的记录使用 relaxed 类型。兼容批量
入口仍按 Vec 调用和重投。
同一实例、同一计划的业务键顺序覆盖全部物理组。跨进程串行要求生产者把相同业务键路由到相同
物理 Stream;系统仍为 at-least-once,业务必须幂等。RustV2 使用原子 fencing,LegacyV1 的
holder 复验不能提供相同强度的原子拒绝。
注册示例、容量配置、恢复屏障、发布未知结果、停机报告及能力边界见
Redis 分区消费。Redis 消费器自己拥有执行器生命周期,不使用 Application
配置的命名 Runner。使用 Application 时通过 configure_redis_partition 登记计划,
由 redis 子能力统一管理 Ready、逐源健康和聚合停机。
执行域与消费架构
每个 RunningPartition 都拥有私有 Runner 注册表。不同 Redis 源互不共享本地任务、容量或停机
控制;同源内通过 partition.executor.scope 决定隔离粒度:
| 模式 | Runner 数量 | 容量使用 |
|---|---|---|
source(默认) |
1 | 全部组使用同一份源级预算 |
group |
默认组与隔离组的总数 | 每组获得固定份额 |
stream |
全部组的物理分区数之和 | 每个物理 Stream 获得固定份额 |
来源持锁与 PEL 恢复
↓
读取前预留 record / payload / batch / 后继责任
↓
共享记录账本 + 同计划同业务键顺序门禁
↓
来源所属 Runner → 受监督业务任务 → 稳定执行结果
↙ ↘
独立提交 ACK 原坐标精确重试
↓
有界异步 XDEL
每域有独立的提交和重试监督,网络等待不持有共享账本锁。同计划同业务键的后继仍需等待原记录 确认或处置完成。ACK 已确认而删除队列满时,Commit 保留删除交接责任,业务顺序门禁可以继续推进。 域表和份额在启动前固定,再平衡或重获租约不重新分配;所有配置的 Stream 都占份额,包括当前未 持锁的 Stream。空闲域不借出容量,源级总量也不会随 Runner 数量扩大。
以下配置提供两个组、每组两个物理 Stream;stream 模式共有四个 Runner,每个 Runner 两个本地槽。
redis:
stream:
batch_size: 16
partition:
enabled: true
count: 2
groups:
notifications:
count: 2
topics:
executor:
scope: stream
partitions: 2
max_runners: 4
max_total_partitions: 8
limits:
max_inflight_records: 256
max_record_bytes: 65536
max_inflight_payload_bytes: 16777216
max_active_batches: 16
max_async_delete_records: 256
此片段合并进带 url、namespace 和 profile 的 Redis 配置。其它记录后继上限采用默认值时,
每域可保留 64 条记录、4 MiB 估算正文、4 个读取批次和 64 个待删 ID。正文同时覆盖原始 Envelope
与解码对象,单条线格式上限不等于对象存活内存上限。最低批次预留不够时 start 拒绝启动。
执行隔离不提供独立线程、Redis 连接或外部服务;共享连接阻塞、同步阻塞线程仍可影响多个域。
snapshot() 同时报告聚合责任与 execution_domains,可区分域满载、来源 Park、提交未知和 Runner
降级。正常停机覆盖全部域,任一任务、I/O 或锁未取得退出证明时 converged 保持 false。
PROXY 共享消费组
PreparedProxy 适合一个共享 stream 上的多 consumer 并行消费;它不提供分区顺序或 owner fencing,
handler 必须幂等。默认 handler 超时为 10 秒,reclaim idle 为 30 秒,stream 写入使用
MAXLEN ~ 1000000 控制历史长度。
use ;
let mut prepared = prepare.await?;
prepared.;
let proxy = prepared.start.await?;
proxy.publish.await?;
proxy.shutdown.await;
consumers 最大 256,batch_size 最大 10000;reclaim_min_idle_ms、handler_timeout_ms 和
drain_deadline_ms 必须大于 0,所有 timer 时长不超过 365 天。直接丢弃 RunningProxy 会立即
停止 consumer/reclaim,但不会冒险删除可能含 PEL 的 consumer;正常停机应显式调用
shutdown().await。
RediSearch 文档
开启 derive feature 后可派生 RedisDocument。
生产注意
Application 受管 Redis 客户端由 "redis" 组件关闭,业务一次性收尾可以在其关闭前使用
app.register_graceful_shutdown,不应重复关闭同一个受管客户端。业务自己启动的 Stream、Partition 或
其它长期消费循环,应先由对应 owner 停止准入并确认退出;一次性 future 不能替代运行期间的任务监督。
RedisConfig的url在 Debug 输出中会脱敏,但不要把明文连接串写进仓库。RustV2和LegacyV1的分区/锁/stream 协议不要混同一 namespace。- 非幂等命令遇到 Redis IO 错误时,框架不会透明重试;调用方要按业务处理“执行状态未知”。
- ACK 后异步 XDEL 只回收 stream 空间,不改变确认语义;删除暂时失败会在后续周期重试,
停机做末次 flush。删除 owner 退出时,剩余待删份额转为
delete_retained_records并归还容量, 不撤销 ACK,也不重跑 handler。末次删除仍失败时 entry 会保留在 stream;仅在 autoTrim 同时启用时, 才会由其保留窗继续回收。持续删除失败会先积累有界待删 ID,再通过队列反压暂停消费; 这是为了避免 ACK 已成功后静默遗失待删 ID。应把RunningPartition::async_delete_pending()接入运行时 gauge,并对持续非零告警。 - Partition 正常停机应显式调用
RunningPartition::shutdown().await。直接 Drop 会关闭准入并启动 best-effort drain。必须检查返回报告的converged;等待超时后可再次等待同一个操作,只有显式force_shutdown_until才请求有损中止,不能把取消请求当作 handler、I/O 或锁已退出的证明。
YML 配置与使用
推荐把 Redis 配置放在 redis: 根节点,然后直接反序列化为
nasa::redis::RedisConfig。url、namespace、profile 必填;其它字段都有默认值。
完整示例:
redis:
url: ${APP_REDIS_URL}
namespace: order-service
profile: RustV2
command:
timeout_ms: 0
response_timeout_ms: 30000
pipeline:
session_max_commands: 1000
session_max_bytes: 4194304
dedicated_conn: true
idempotent_counter:
ttl_mode: AUTO
nonce_ttl_ms: 604800000
bucket_span_ms: 86400000
ledger_shards: 256
ledger_key_prefix: rpidem
layout_marker_id: primary
lock:
prefix: "DISTRIBUTED-LOCK:"
lease_ms: 30000
stream:
poll_timeout_ms: 500
batch_size: 100
data_expire_ms: 3600000
auto_trim_rate_ms: 60000
async_del_record_period_ms: 5000
inflight_max: 1000
partition:
enabled: false
default_group: SINGLE-CONSUME
count: 64
rebalance_ms: 10000
min_idle_ms: 30000
holds_check_interval_ms: 5000
drain_timeout_ms: 35000
max_redeliver: 5
handler_timeout_ms: 30000
poison_policy: Park
groups:
hot:
topics:
count: 128
batch_size: 500
poll_timeout_ms: 100
字段说明:
| 键 | 默认值 | 说明 |
|---|---|---|
url |
必填 | Redis URI;单点和 cluster 都用 redis URI 传入,密码写在 URI 中。 |
namespace |
必填 | 协议命名空间;不同系统、不同 profile 不要复用。 |
profile |
必填 | RustV2 或 LegacyV1,决定 key 布局、锁、stream 和分区协议。 |
command.timeout_ms |
0 |
单命令业务超时;0 表示不限,非零最大 365 天。 |
command.response_timeout_ms |
30000 |
连接级响应超时;0 表示不限,非零最大 365 天。 |
pipeline.session_max_commands |
1000 |
单个 PipelineSession 自动滚动 flush 的命令数。 |
pipeline.session_max_bytes |
4194304 |
单批参数字节上限。 |
pipeline.dedicated_conn |
true |
pipeline 是否使用独立连接 lane。 |
idempotent_counter |
未显式配置 | nonce 账本布局;缺省时首次调用使用保守默认值,未调用不触发能力探测。 |
lock.prefix |
DISTRIBUTED-LOCK: |
分布式锁 key 前缀。 |
lock.lease_ms |
30000 |
锁租约;有效范围 3s 到 300s。 |
stream.poll_timeout_ms |
500 |
冷流轮询间隔,必须大于 0 且不超过 365 天。 |
stream.batch_size |
100 |
XREADGROUP 单批数量,范围 1–10000。 |
stream.data_expire_ms |
3600000 |
stream 数据保留窗口,最大 365 天。 |
stream.auto_trim_rate_ms |
60000 |
自动 XTRIM 周期;0 表示禁用,非零最大 365 天。 |
stream.async_del_record_period_ms |
5000 |
ACK 后批量 XDEL 周期;0 表示禁用,entry 留在 stream;若启用 autoTrim,则按其保留窗回收。 |
stream.inflight_max |
1000 |
每物理组同时读取批次数上限,还受 partition.limits 共享预算约束。 |
partition.enabled |
false |
是否启用分区消费。 |
partition.default_group |
SINGLE-CONSUME |
默认消费组。 |
partition.count |
64 |
默认分区数,必须大于 0。 |
partition.rebalance_ms |
10000 |
重平衡周期。 |
partition.min_idle_ms |
30000 |
PEL 消息可接管的最小 idle,最大 365 天。 |
partition.holds_check_interval_ms |
5000 |
owner 持锁状态的复核周期,最大 365 天。 |
partition.drain_timeout_ms |
35000 |
普通停机本次等待窗口,超时返回未收敛报告并继续排干;最大 365 天。 |
partition.max_redeliver |
5 |
连续重投上限。 |
partition.handler_timeout_ms |
30000 |
单个 handler 桶执行超时,最大 365 天。 |
partition.poison_policy |
Park |
Drop、Park 或 Dlq。 |
partition.groups |
{} |
topic 隔离组,可覆盖分区数、batch、poll、超时和毒消息策略;最多 256 组。 |
partition.executor |
scope: source,每 Runner 8 槽、4096 在途 |
支持 source、group、stream 隔离;域数、总槽数和固定容量份额在启动前校验,详见分区消费说明。 |
partition.limits |
4096 条,256 MiB 正文 | 默认组与隔离组共享的发布、读取、任务、后继、提交、重投、gate 和删除预算。 |
启动代码:
let client = connect.await?;
Cluster 使用注意:多 key 命令必须同 slot;普通业务 key 可使用 {tenant} 这类 hash tag。
分区运行时会自动给每个分区组生成组级 hash tag,并在启动时校验全部协议 key 同槽。
默认组与隔离组的 resolved 分区总数最多 65536,配置 topic 总数最多 4096;这些边界限制单实例
启动时的 task、channel 和扫描状态规模。隔离组覆盖的 poll、idle、持锁复核、handler 与 drain
时长也使用相同上限,不能绕过全局配置保护。
普通 Stream、Proxy 与微批的受管入口
组合 application,redis 并声明 "redis" 后,redis_streams、redis_proxies、redis_pipelines
提供命名计划。前两项在 Service UserHook 只登记 handler,Prepare 建立 owner,统一 Ready 后消费;
AutoPipeline 也支持 Batch。具体 YAML 和 getter 见
napp。
运行架构与责任边界
命名配置 + handler 计划 → 受管 Redis 来源 → Prepare 建立领域 owner
→ Ready 与共享启动许可 → 消费 / Proxy 发布 / 微批入队
→ 关闭新工作 → 同一截止点排干与清理 → 归还 Redis 来源
普通 Stream 按显式读取模式处理记录;组模式的 on_success 在 handler 失败时保留 PEL,不自动重投。
Proxy 以共享组竞争、回收和毒消息策略处理自己的信封格式;两者不能共用同源同 stream/group。
AutoPipeline 合并命令传输,既不提供 Redis 事务,也不提供业务键有序消费。需要分区执行与业务键
顺序时使用 PreparedPartition / RunningPartition。Service 的命名发送入口在放行前明确拒绝,
Batch 仅装配 AutoPipeline,不创建长期 Stream 或 Proxy 消费计划。
独立 start() 保持立即激活;需要准备屏障时使用 start_suspended() 后显式 activate()。
多个入口共同开放时使用 start_suspended_with_activation(token),仅由宿主取消共享 token 发布许可,
不逐项调用 activate()。受管入口与宿主终端共用许可,公开 Ready 后首次调用无需等待监控激活。
Stream、Proxy、AutoPipeline 的 with_running 在本地任务责任完整的保护内执行短小同步裁决,
闭包不能阻塞或重入领域句柄;已退出的关键 owner 阻止 Ready 发布,不把本地存活等同远端可用。
Stream 的 begin_shutdown() / wait_closed()、Proxy 的 begin_shutdown_until() / wait_closed()
和 AutoPipeline 的 shutdown_result() 都保留真实退出证据,可在前一次等待被取消后再次等待。
Proxy 强制关闭、查询失败或摘要不完整时保留 consumer/PEL;不把未知 pending 当作零。
ProxyStopReport.cleanup 区分完整清理、合法 pending、证据不可用和预算耗尽,后两类在宿主中
进入次要停机失败。删除回包超时保留结果未知。收尾 owner 被执行器销毁时,旧入口关闭,状态读取
报告失败;Proxy 未取得全部 join 证据时保持 terminated: false,不会把任务取消冒充优雅退出。
受管微批要求有限单条参数字节 M 和单批软上限 B,正常合批与排干均不超过 B+M 的保守参数字节边界,
每批同时受条数限制;独立 MicroBatchCfg 的零字节限制仍表示不限。队列上界只计算已接纳命令参数,
不涵盖编码、响应、Cmd 预留容量及等待中的调用者。关闭拒绝新的入队,已接纳命令逐项返回执行结果或
ExecutionUnknown,不会自动重放写入。submit 没有逐条回执需求时才适用。
三个领域句柄的 observation() 返回本地任务数、处理进展与未完成责任;微批同时提供排队参数字节
和传输失败批次数。completed 表示本地处理结束,包含 handler 失败及结果未知,不是业务成功计数。
同一消息重投可形成多次处理,未完成次数不等于 PEL 大小。最近进展为 None 时尚无可验证的运行进展;
有效空轮询不会被误判为消费失败。barrier() 只建立已入队工作的处理顺序,不汇总此前写入的错误。