nadis 2.0.1

Redis 基础层:业务键有序分区消费、Stream/Proxy 生命周期、有界微批、幂等管线、锁与 RedisJob
Documentation
//! Job 标识线协议:Run、Fanout、shard 与 Worker 的稳定字节标识。
//!
//! 所有标识都以 4 字节网络序长度前缀拼接 UTF-8 字段后取 SHA-256,是持久线协议:多节点据此对同一逻辑
//! Run/Fanout 收敛为同一批次。任何字段顺序或编码漂移都会让重试落到不同标识,破坏"同因果只处理一次"。

use crate::idempotent::wire::framed_digest;

/// 业务作用:生成固定 128 位协议标识(摘要前 16 字节的小写 hex)。
///
/// 参数说明:
/// - `fields`: 按协议顺序排列的字段。
///
/// 返回:32 位小写 hex。
fn digest128(fields: &[&str]) -> String {
    let parts: Vec<&[u8]> = fields.iter().map(|f| f.as_bytes()).collect();
    hex::encode(&framed_digest(&parts)[..16])
}

/// 业务作用:生成完整 256 位协议摘要的小写 hex。
///
/// 参数说明:
/// - `fields`: 按协议顺序排列的字段。
///
/// 返回:64 位小写 hex。
fn digest256(fields: &[&str]) -> String {
    hex::encode(framed_digest(
        &fields.iter().map(|f| f.as_bytes()).collect::<Vec<_>>(),
    ))
}

/// 业务作用:生成自动调度 Run 的稳定幂等标识;同一逻辑触发时刻只对应一个 Run。
///
/// 参数说明:
/// - `qualifier`:冻结的数据源标识,使不同 source 的同名任务保持隔离。
/// - `namespace`:任务所属命名空间。
/// - `job_name`:已校验的任务名。
/// - `logical_fire_at`:调度确定的逻辑触发毫秒时刻,不使用本次扫描时刻替代。
/// - `trigger_type`:触发类型的协议名称;不同触发语义使用不同标识。
///
/// 返回:32 位小写 hex 标识。
pub fn scheduled_run_id(
    qualifier: &str,
    namespace: &str,
    job_name: &str,
    logical_fire_at: i64,
    trigger_type: &str,
) -> String {
    digest128(&[
        qualifier,
        namespace,
        job_name,
        &logical_fire_at.to_string(),
        trigger_type,
    ])
}

/// 业务作用:生成手工触发 Run 的稳定幂等标识;同一 source、命名空间和任务内的相同请求身份映射到同一 Run。
///
/// 参数说明:
/// - `qualifier`:冻结的数据源标识。
/// - `namespace`:任务所属命名空间。
/// - `job_name`:已校验的任务名。
/// - `request_id`:调用方提供的幂等请求标识;重试必须保留原值,观测时间不参与计算。
///
/// 返回:32 位小写 hex 标识。
pub fn manual_run_id(qualifier: &str, namespace: &str, job_name: &str, request_id: &str) -> String {
    digest128(&[qualifier, namespace, job_name, "MANUAL", request_id])
}

/// 业务作用:生成与根 attempt 一一对应的 Fanout 标识,使网络重试采用同一批次。
///
/// 参数说明:
/// - `root_run_id`:已经冻结的根 Run 标识。
/// - `root_attempt`:根执行尝试编号,调用方须在持久创建前校验为正数。
///
/// 返回:32 位小写 hex 标识。
pub fn fanout_id(root_run_id: &str, root_attempt: i32) -> String {
    digest128(&[root_run_id, &root_attempt.to_string()])
}

/// 业务作用:生成不随目标重分配变化的 Fanout shard 标识。
///
/// 参数说明:
/// - `fanout_id`:分片所属的冻结批次标识。
/// - `seq`:批次内的稳定序号,投递重试和目标重分配均保留原值。
///
/// 返回:32 位小写 hex 标识。
pub fn shard_run_id(fanout_id: &str, seq: i64) -> String {
    digest128(&[fanout_id, &seq.to_string()])
}

/// 业务作用:生成完整 Worker 摘要作为 Stream 路由键,避免截断碰撞共享消费通道。
///
/// 参数说明:
/// - `worker_name`: Worker 能力名。
///
/// 返回:64 位小写 hex 摘要。
pub fn worker_key(worker_name: &str) -> String {
    digest256(&[worker_name])
}

/// 业务作用:生成能力快照的跨语言完整摘要,source 与成员字段分别编码以消除分隔符歧义。
///
/// 参数说明:
/// - `qualifier`:快照所属的冻结数据源标识。
/// - `namespace`:快照所属的任务命名空间。
/// - `worker_name`:被选定成员共同满足的 Worker 能力名。
/// - `selected_at`:Redis 选定成员的毫秒时刻,作为快照身份的一部分。
/// - `members`: 已按稳定顺序展开的 nodeIdentity、executorId、heartbeatRevision 字段。
///
/// 返回:64 位小写 hex 摘要;成员顺序原样参与计算,调用方必须先完成稳定排序。
pub fn snapshot_digest(
    qualifier: &str,
    namespace: &str,
    worker_name: &str,
    selected_at: i64,
    members: &[String],
) -> String {
    let selected_at = selected_at.to_string();
    let mut fields = Vec::with_capacity(4 + members.len());
    fields.extend([qualifier, namespace, worker_name, selected_at.as_str()]);
    fields.extend(members.iter().map(String::as_str));
    digest256(&fields)
}