nadis 2.0.1

Redis 基础层:业务键有序分区消费、Stream/Proxy 生命周期、有界微批、幂等管线、锁与 RedisJob
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
//! RedisJob 低基数观测快照:运行循环只写进程内累计,查询不访问 Redis,也不接收运行期任意 label。

use std::collections::BTreeMap;
use std::sync::Mutex;

/// 调度触发脚本的封闭结局;文本用于 `redis_job_fire_total{result}` 的固定 label 域。
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum JobFireResult {
    /// 首次建立 Run 与 Dispatch 消息。
    Fired,
    /// 同一逻辑时刻已存在 Run,采用既有事实。
    Adopted,
    /// 误触发策略只推进逻辑时刻。
    Skipped,
    /// 候选尚未到期。
    NotDue,
    /// 下一逻辑时刻需要按新的 Redis 时间重算。
    NeedRecompute,
    /// 定义或命名空间状态不允许触发。
    StateMismatch,
    /// 定义修订或调度 score 已被其它节点推进。
    Stale,
}

impl JobFireResult {
    /// 业务作用:返回触发指标使用的稳定低基数结果文本。
    ///
    /// 参数说明: 无。
    ///
    /// 返回:与脚本封闭结局一一对应的 label 值。
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Fired => "fired",
            Self::Adopted => "adopted",
            Self::Skipped => "skipped",
            Self::NotDue => "not_due",
            Self::NeedRecompute => "need_recompute",
            Self::StateMismatch => "state_mismatch",
            Self::Stale => "stale",
        }
    }

    /// 业务作用:把批量触发脚本的已校验返回码映射为封闭指标结果。
    ///
    /// 参数说明:
    /// - `code`:批量调度脚本返回的单项状态码,仅接受固定协议名称。
    ///
    /// 返回:已知码返回对应结果;未知码返回 `None`,由协议层拒绝而不是扩张 label 域。
    pub(crate) fn from_script_code(code: &str) -> Option<Self> {
        match code {
            "OK" => Some(Self::Fired),
            "ADOPTED" => Some(Self::Adopted),
            "SKIPPED" => Some(Self::Skipped),
            "NOT_DUE" => Some(Self::NotDue),
            "NEED_RECOMPUTE" => Some(Self::NeedRecompute),
            "STATE_MISMATCH" => Some(Self::StateMismatch),
            "STALE" => Some(Self::Stale),
            _ => None,
        }
    }
}

/// 受监督循环的封闭身份;文本可直接作为低基数指标 label。
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum JobSupervisorLoop {
    /// RESP3 Fanout 订阅与通知定位。
    Subscription,
    /// 普通任务调度、可见性与恢复扫描。
    Scanner,
    /// Dispatch Stream 消费与 Handler 执行。
    Dispatcher,
    /// Fanout receipt、ready、lease 与根对账。
    FanoutMonitor,
    /// Completion、删除队列与 tombstone 有界回收。
    Completion,
    /// 执行器权威心跳。
    Heartbeat,
}

impl JobSupervisorLoop {
    /// 业务作用:返回指标和健康快照使用的稳定低基数文本。
    ///
    /// 参数说明: 无。
    ///
    /// 返回:不会包含 source、任务名或 endpoint 的固定循环名。
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Subscription => "subscription",
            Self::Scanner => "scanner",
            Self::Dispatcher => "dispatcher",
            Self::FanoutMonitor => "fanout_monitor",
            Self::Completion => "completion",
            Self::Heartbeat => "heartbeat",
        }
    }
}

/// 监督器最近一次代次迁移的封闭结局。
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum JobSupervisorResult {
    /// 当前代次正常运行。
    Running,
    /// 异常后仍在预算内,已安排下一代。
    RestartScheduled,
    /// 新代次已完成一次成功推进。
    Recovered,
    /// 重启次数或时间窗耗尽。
    BudgetExhausted,
    /// 维持 attempt 权威的循环退出,不允许原地重启。
    AuthorityLost,
}

impl JobSupervisorResult {
    /// 业务作用:返回指标和健康快照使用的稳定结局文本。
    ///
    /// 参数说明: 无。
    ///
    /// 返回:封闭、低基数的结果名称。
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Running => "running",
            Self::RestartScheduled => "restart_scheduled",
            Self::Recovered => "recovered",
            Self::BudgetExhausted => "budget_exhausted",
            Self::AuthorityLost => "authority_lost",
        }
    }
}

/// 单个受监督循环的只读指标投影。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JobSupervisorMetricsSnapshot {
    /// 封闭循环身份。
    pub loop_name: JobSupervisorLoop,
    /// 当前或下一次将运行的单调代次,初始为 1。
    pub generation: u64,
    /// 已安排的新代次数量。
    pub restart_total: u64,
    /// 最近一次代次迁移结局。
    pub result: JobSupervisorResult,
    /// 各封闭结局的历史累计,供带 `result` label 的 counter 保持单调。
    pub result_totals: BTreeMap<JobSupervisorResult, u64>,
}

#[derive(Debug, Clone)]
/// 业务作用:保存单个监督循环当前代次、重启累计和封闭结局历史。
struct SupervisorMetric {
    /// 当前或下一次运行的监督代次,计数达到上界后饱和。
    generation: u64,
    /// 已安排重启的累计次数,区别于成功恢复次数。
    restart_total: u64,
    /// 最近一次监督状态观测,供健康投影使用。
    result: JobSupervisorResult,
    /// 各封闭结局的累计观测次数,避免结果切换使 counter 回退。
    result_totals: BTreeMap<JobSupervisorResult, u64>,
}

impl Default for SupervisorMetric {
    /// 业务作用:建立尚未发生重启的首个监督代次。
    ///
    /// 参数说明: 无。
    ///
    /// 返回:generation=1、restart_total=0 的运行状态。
    fn default() -> Self {
        Self {
            generation: 1,
            restart_total: 0,
            result: JobSupervisorResult::Running,
            result_totals: ALL_SUPERVISOR_RESULTS
                .iter()
                .copied()
                .map(|result| (result, 0))
                .collect(),
        }
    }
}

/// 一个 source 的全部本地指标快照;数值读取不会发出 Redis 命令。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JobMetricsSnapshot {
    /// canonical source id,是冻结计划提供的低基数维度。
    pub qualifier: String,
    /// 固定指标名到当前值的映射;全集在 source 创建时一次性建立,运行期不会增长。
    pub values: BTreeMap<&'static str, i64>,
    /// 调度触发各封闭结局的单调累计;全集在 source 创建时建立。
    pub fire_results: BTreeMap<JobFireResult, u64>,
    /// 每类受监督循环的代次与重启累计。
    pub supervisors: Vec<JobSupervisorMetricsSnapshot>,
    /// Completion 双界裁剪后最近观测到的最旧 Stream ID。
    pub completion_oldest_id: Option<String>,
}

#[derive(Debug)]
/// 业务作用:集中保存一个 Redis source 的固定指标值、分片 gauge 与监督循环账目。
struct JobMetricsState {
    /// 预登记指标名对应的当前数值,不接受运行期新增名称。
    values: BTreeMap<&'static str, i64>,
    /// 各类调度结局的饱和累计。
    fire_results: BTreeMap<JobFireResult, u64>,
    /// 固定指标下各布局分片最近一次观测,用于计算 source 聚合值。
    shard_gauges: BTreeMap<&'static str, BTreeMap<u32, i64>>,
    /// 每类监督循环的代次与历史结局。
    supervisors: BTreeMap<JobSupervisorLoop, SupervisorMetric>,
    /// 最近一次完成流裁剪观测的最旧消息标识,空流时为 None。
    completion_oldest_id: Option<String>,
}

/// 单 source 进程内指标容器;所有 key 与 label 域在构造时封闭。
#[derive(Debug)]
pub(crate) struct JobMetrics {
    /// 冻结的数据源标识,限制对外指标的 source 维度。
    qualifier: String,
    /// 只保护进程内指标读写的锁,不在持锁期间执行 Redis I/O。
    state: Mutex<JobMetricsState>,
}

impl JobMetrics {
    /// 业务作用:按冻结 source 建立完整指标值与封闭结局域,避免运行期事件扩张指标名称。
    ///
    /// 参数说明:
    /// - `qualifier`:计划冻结的规范数据源标识,作为快照固定身份。
    ///
    /// 返回:全部计数和 gauge 为零、监督器处于首代的本地容器。
    pub(crate) fn new(qualifier: impl Into<String>) -> Self {
        let values = JOB_METRIC_NAMES
            .iter()
            .copied()
            .map(|name| (name, 0))
            .collect();
        let supervisors = ALL_SUPERVISOR_LOOPS
            .iter()
            .copied()
            .map(|loop_name| (loop_name, SupervisorMetric::default()))
            .collect();
        Self {
            qualifier: qualifier.into(),
            state: Mutex::new(JobMetricsState {
                values,
                fire_results: ALL_FIRE_RESULTS
                    .iter()
                    .copied()
                    .map(|result| (result, 0))
                    .collect(),
                shard_gauges: BTreeMap::new(),
                supervisors,
                completion_oldest_id: None,
            }),
        }
    }

    /// 业务作用:累计一个已预登记的低基数计数器。
    ///
    /// 参数说明:
    /// - `name`:本模块预登记的指标名,外部输入不能动态扩展名称。
    /// - `delta`:本次增加的数量,负值按零处理,溢出时饱和。
    ///
    /// 返回:无;未知名称被忽略,防止运行期输入扩张指标域。
    pub(crate) fn add(&self, name: &'static str, delta: i64) {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Some(value) = state.values.get_mut(name) {
            *value = value.saturating_add(delta.max(0));
        }
    }

    /// 业务作用:更新一个已预登记的 gauge。
    ///
    /// 参数说明:
    /// - `name`:固定全集内需要覆盖的指标名。
    /// - `value`:当前观测值,原样保存,不执行非负归一化。
    ///
    /// 返回:无;未知名称被忽略,指标域保持封闭。
    pub(crate) fn set(&self, name: &'static str, value: i64) {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Some(current) = state.values.get_mut(name) {
            *current = value;
        }
    }

    /// 业务作用:更新一个分片局部 gauge,并把全部已观测分片求和发布为 source 聚合值。
    ///
    /// 参数说明:
    /// - `name`:固定全集内的聚合 gauge 名称。
    /// - `shard`:调用方保证属于冻结布局的分片下标,不作为对外 label。
    /// - `value`:该分片最新观测值,负值按零保存。
    ///
    /// 返回:无;已知名称更新分片观测并饱和求和,未知名称被忽略;未观测的分片不计入总值。
    pub(crate) fn set_shard_gauge(&self, name: &'static str, shard: u32, value: i64) {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if !state.values.contains_key(name) {
            return;
        }
        let aggregate = {
            let shards = state.shard_gauges.entry(name).or_default();
            shards.insert(shard, value.max(0));
            shards.values().copied().fold(0_i64, i64::saturating_add)
        };
        state.values.insert(name, aggregate);
    }

    /// 业务作用:累计一批调度触发的封闭结局,使各 result series 保持独立单调。
    ///
    /// 参数说明:
    /// - `result`:脚本返回码映射出的封闭结局,不接受任意错误文本。
    /// - `delta`:本轮该类结局的数量。
    ///
    /// 返回:无;对应结局累计增加,达到整数上界后饱和而不回绕。
    pub(crate) fn record_fire(&self, result: JobFireResult, delta: u64) {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Some(total) = state.fire_results.get_mut(&result) {
            *total = total.saturating_add(delta);
        }
    }

    /// 业务作用:记录一个循环安排新代次,并同步监督器公开计数与 generation。
    ///
    /// 参数说明:
    /// - `loop_name`:本次已安排新代次的封闭循环身份。
    ///
    /// 返回:饱和递增后的 generation;同时增加重启累计和安排重启的结局累计,不启动循环。
    pub(crate) fn restart_scheduled(&self, loop_name: JobSupervisorLoop) -> u64 {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let metric = state.supervisors.entry(loop_name).or_default();
        metric.generation = metric.generation.saturating_add(1);
        metric.restart_total = metric.restart_total.saturating_add(1);
        metric.result = JobSupervisorResult::RestartScheduled;
        if let Some(total) = metric
            .result_totals
            .get_mut(&JobSupervisorResult::RestartScheduled)
        {
            *total = total.saturating_add(1);
        }
        metric.generation
    }

    /// 业务作用:记录一个新代次已成功推进的观测,实际健康恢复由监督器控制。
    ///
    /// 参数说明:
    /// - `loop_name`:已经完成成功推进的封闭循环身份。
    ///
    /// 返回:无;更新最近结局并累计恢复观测,不改变代次或累计重启次数。
    pub(crate) fn recovered(&self, loop_name: JobSupervisorLoop) {
        self.set_supervisor_result(loop_name, JobSupervisorResult::Recovered);
    }

    /// 业务作用:记录循环重启预算耗尽。
    ///
    /// 参数说明:
    /// - `loop_name`:已无法继续重启的封闭循环身份。
    ///
    /// 返回:无;更新结局并累计预算耗尽观测,source 健康门禁仍须由调用方关闭。
    pub(crate) fn budget_exhausted(&self, loop_name: JobSupervisorLoop) {
        self.set_supervisor_result(loop_name, JobSupervisorResult::BudgetExhausted);
    }

    /// 业务作用:记录权威循环失效且不得原地重启。
    ///
    /// 参数说明:
    /// - `loop_name`:已经失去权威的封闭循环身份。
    ///
    /// 返回:无;更新结局并累计失权观测,本函数不直接撤销租约或关闭 source。
    pub(crate) fn authority_lost(&self, loop_name: JobSupervisorLoop) {
        self.set_supervisor_result(loop_name, JobSupervisorResult::AuthorityLost);
    }

    /// 业务作用:记录 Completion 双界裁剪数量、最旧 ID 与积压年龄。
    ///
    /// 参数说明:
    /// - `length_trimmed`:按长度上限裁剪的数量,负值不减少累计。
    /// - `retention_trimmed`:按保留期限裁剪的数量,负值不减少累计。
    /// - `oldest_id`:裁剪后最旧 Stream ID,空流为 None;无法解析毫秒部分时年龄记为零。
    /// - `redis_now`:本轮 Redis 权威毫秒时间,用于估算最旧条目的年龄。
    ///
    /// 返回:无;依次更新裁剪累计、非负年龄和最旧 ID,跨字段更新不构成原子观测批次。
    pub(crate) fn record_completion_trim(
        &self,
        length_trimmed: i64,
        retention_trimmed: i64,
        oldest_id: Option<&str>,
        redis_now: i64,
    ) {
        self.add("redis_job_completion_length_trimmed_total", length_trimmed);
        self.add(
            "redis_job_completion_retention_trimmed_total",
            retention_trimmed,
        );
        let oldest_millis = oldest_id
            .and_then(|id| id.split_once('-').map(|(millis, _)| millis))
            .and_then(|millis| millis.parse::<i64>().ok());
        self.set(
            "redis_job_completion_oldest_age_ms",
            oldest_millis.map_or(0, |oldest| redis_now.saturating_sub(oldest).max(0)),
        );
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        state.completion_oldest_id = oldest_id.map(ToOwned::to_owned);
    }

    /// 业务作用:读取当前 source 的完整本地指标快照。
    ///
    /// 参数说明: 无。
    ///
    /// 返回:固定指标全集、监督代次与 Completion 观测;不访问 Redis。
    pub(crate) fn snapshot(&self) -> JobMetricsSnapshot {
        let state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        JobMetricsSnapshot {
            qualifier: self.qualifier.clone(),
            values: state.values.clone(),
            fire_results: state.fire_results.clone(),
            supervisors: state
                .supervisors
                .iter()
                .map(|(loop_name, metric)| JobSupervisorMetricsSnapshot {
                    loop_name: *loop_name,
                    generation: metric.generation,
                    restart_total: metric.restart_total,
                    result: metric.result,
                    result_totals: metric.result_totals.clone(),
                })
                .collect(),
            completion_oldest_id: state.completion_oldest_id.clone(),
        }
    }

    /// 业务作用:更新监督循环最近结局并累计该结局的观测次数,保留代次和重启累计。
    ///
    /// 参数说明:
    /// - `loop_name`:当前观测所属的封闭循环身份。
    /// - `result`:需要发布并累计的封闭结局,连续相同结局也分别计数。
    ///
    /// 返回:无;最近结局被覆盖,对应累计饱和增加,generation 与 restart_total 保持原值。
    fn set_supervisor_result(&self, loop_name: JobSupervisorLoop, result: JobSupervisorResult) {
        let mut state = self
            .state
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let metric = state.supervisors.entry(loop_name).or_default();
        metric.result = result;
        if let Some(total) = metric.result_totals.get_mut(&result) {
            *total = total.saturating_add(1);
        }
    }
}

/// source 创建时预登记的全部监督循环。
const ALL_SUPERVISOR_LOOPS: [JobSupervisorLoop; 6] = [
    JobSupervisorLoop::Subscription,
    JobSupervisorLoop::Scanner,
    JobSupervisorLoop::Dispatcher,
    JobSupervisorLoop::FanoutMonitor,
    JobSupervisorLoop::Completion,
    JobSupervisorLoop::Heartbeat,
];

/// 监督结局的固定 label 域,包含尚未发生的零值项。
const ALL_SUPERVISOR_RESULTS: [JobSupervisorResult; 5] = [
    JobSupervisorResult::Running,
    JobSupervisorResult::RestartScheduled,
    JobSupervisorResult::Recovered,
    JobSupervisorResult::BudgetExhausted,
    JobSupervisorResult::AuthorityLost,
];

/// 调度结果的固定 label 域,协议外文本不能加入。
const ALL_FIRE_RESULTS: [JobFireResult; 7] = [
    JobFireResult::Fired,
    JobFireResult::Adopted,
    JobFireResult::Skipped,
    JobFireResult::NotDue,
    JobFireResult::NeedRecompute,
    JobFireResult::StateMismatch,
    JobFireResult::Stale,
];

/// source 创建时建立的固定指标名,更新操作忽略未知名称。
const JOB_METRIC_NAMES: [&str; 36] = [
    "redis_job_schedule_lag_ms",
    "redis_job_due_scan_total",
    "redis_job_fire_total",
    "redis_job_visible_size",
    "redis_job_running",
    "redis_job_started_total",
    "redis_job_success_total",
    "redis_job_failed_total",
    "redis_job_retry_total",
    "redis_job_dead_total",
    "redis_job_skipped_total",
    "redis_job_lease_expired_total",
    "redis_job_stale_finish_total",
    "redis_job_fencing_regression_total",
    "redis_job_self_fence_total",
    "redis_job_serial_wait_depth",
    "redis_job_executor_capacity",
    "redis_job_definition_conflict_total",
    "redis_job_capable_executor_count",
    "redis_job_invalid_payload_total",
    "redis_job_fanout_shard_total",
    "redis_job_fanout_receipt_timeout_total",
    "redis_job_fanout_receipt_retry_total",
    "redis_job_fanout_reassign_total",
    "redis_job_fanout_stale_assignment_total",
    "redis_job_fanout_delivery_pending",
    "redis_job_fanout_ready_wakeup_total",
    "redis_job_fanout_capacity_defer_total",
    "redis_job_fanout_capacity_exhausted_total",
    "redis_job_fanout_gc_pending",
    "redis_job_registry_gc_total",
    "redis_job_script_reload_total",
    "redis_job_completion_length_trimmed_total",
    "redis_job_completion_retention_trimmed_total",
    "redis_job_completion_oldest_age_ms",
    "redis_job_pubsub_recovery_window_ms",
];