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
//! Job 的封闭枚举:状态、结果码、并发、误触发、触发类型、调度类型、Fanout 失败策略与线编码。
//!
//! 每个值的 `wire_name()` 都进入 definitionDigest、Lua ARGV 与 Redis 字段,是持久线协议:改名或改集合
//! 会让多实现对同一状态迁移产生分歧。未知线名一律 fail-closed,不静默降级成默认值。
/// 业务作用:为一个封闭枚举生成线协议名称与解析;名称集合是持久协议的一部分,不可改动。
macro_rules! wire_enum {
($(#[$emeta:meta])* $name:ident { $($(#[$vmeta:meta])* $variant:ident => $wire:literal),+ $(,)? }) => {
$(#[$emeta])*
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum $name { $($(#[$vmeta])* $variant),+ }
impl $name {
/// 业务作用:返回该值的线协议名称;进入 definitionDigest、Lua ARGV 与 Redis 字段,不可改动。
///
/// 参数说明: 无。
///
/// 返回:固定大写下划线名称。
pub fn wire_name(self) -> &'static str {
match self { $(Self::$variant => $wire),+ }
}
/// 业务作用:从线协议名称解析枚举;未知名称 fail-closed,不静默降级。
///
/// 参数说明:
/// - `text`: 线协议名称。
///
/// 返回:已知名称返回对应值;未知返回 `None`。
pub fn parse(text: &str) -> Option<Self> {
Some(match text { $($wire => Self::$variant,)+ _ => return None })
}
}
};
}
wire_enum! {
/// Run 状态机的封闭状态集合。
JobState {
/// Run 已创建,尚未进入执行队列。
Created => "CREATED",
/// Run 已排队,等待执行器领取。
Queued => "QUEUED",
/// Run 受并发门禁限制,等待前序执行释放资格。
Blocked => "BLOCKED",
/// 当前 attempt 已取得执行权。
Running => "RUNNING",
/// 当前 attempt 结束后等待重试时刻。
RetryWait => "RETRY_WAIT",
/// Fanout 根正在建立子任务集合。
FanoutCreating => "FANOUT_CREATING",
/// Fanout 根等待子任务结果聚合。
WaitingChildren => "WAITING_CHILDREN",
/// 子任务尚未找到满足要求的可用执行能力。
AwaitingCapability => "AWAITING_CAPABILITY",
/// 子任务已定向投递,等待目标执行器回执。
AwaitingReceipt => "AWAITING_RECEIPT",
/// 目标执行器已确认接收,尚未完成业务执行。
Received => "RECEIVED",
/// 业务执行或子任务聚合成功终结。
Succeeded => "SUCCEEDED",
/// 业务执行或聚合按失败结果终结。
Failed => "FAILED",
/// 执行已耗尽允许的重试或存活预算。
Dead => "DEAD",
/// 调度或并发策略决定跳过本次 Run。
Skipped => "SKIPPED",
/// Run 已按取消请求终结。
Cancelled => "CANCELLED",
}
}
wire_enum! {
/// 任务定义状态;`CONFLICT` 表示同修订号出现语义分歧、已封闭调度,需显式管理动作选择。
JobDefinitionState {
/// 定义存在但尚未允许调度。
Disabled => "DISABLED",
/// 定义允许按触发策略创建 Run。
Enabled => "ENABLED",
/// 定义已暂停调度,保留管理状态。
Paused => "PAUSED",
/// 同修订号存在语义分歧,调度被封闭。
Conflict => "CONFLICT",
/// 定义已进入删除状态,旧修订号不能使其复活。
Deleted => "DELETED",
}
}
wire_enum! {
/// Handler 返回结果码;框架异常默认按可重试失败处理。
JobResultCode {
/// Handler 已完成本次业务工作。
Success => "SUCCESS",
/// 本次执行失败,允许在重试预算内再次尝试。
Retry => "RETRY",
/// 业务明确拒绝后续自动重试。
FailPermanent => "FAIL_PERMANENT",
/// 本次执行因取消而结束。
Cancelled => "CANCELLED",
/// 本次执行超过允许时长。
Timeout => "TIMEOUT",
}
}
wire_enum! {
/// 并发策略;不含协作式取消策略,避免旧 Handler 未确认退出前开放第二个执行权。
JobConcurrency {
/// 同一任务依次执行,后续 Run 进入串行积压队列。
SerialQueue => "SERIAL_QUEUE",
/// 已有执行占用时跳过新 Run。
DiscardIfRunning => "DISCARD_IF_RUNNING",
/// 允许同一任务的多个 Run 并行执行。
Parallel => "PARALLEL",
}
}
wire_enum! {
/// 误触发策略。
JobMisfire {
/// 跳过已经错过的逻辑触发时刻。
DoNothing => "DO_NOTHING",
/// 将错过的触发合并为一次当前执行。
FireOnceNow => "FIRE_ONCE_NOW",
/// 在补偿预算内依次补建错过的触发。
CatchUp => "CATCH_UP",
}
}
wire_enum! {
/// 触发类型;`FANOUT_ONLY` 只作为 Fanout 根,不进入普通调度扫描。
JobTrigger {
/// 参与普通任务调度的根触发。
Scheduled => "SCHEDULED",
/// 仅作为 Fanout 根使用,不进入普通调度扫描。
FanoutOnly => "FANOUT_ONLY",
}
}
wire_enum! {
/// 调度类型。
JobScheduleType {
/// 按 Cron 表达式计算逻辑触发时刻。
Cron => "CRON",
/// 按固定时间间隔推进逻辑触发时刻。
FixedRate => "FIXED_RATE",
/// 从前次执行完成时刻起等待固定延迟再触发。
FixedDelay => "FIXED_DELAY",
/// 只接受显式手工触发。
Manual => "MANUAL",
/// 仅作为 Fanout 根,不创建普通周期触发。
FanoutOnly => "FANOUT_ONLY",
}
}
wire_enum! {
/// Fanout 失败策略;不含线程/task 取消类策略。
JobFanoutFailurePolicy {
/// 目标失效后允许重新选择满足能力要求的执行器。
ReassignOnFailure => "REASSIGN_ON_FAILURE",
/// 保持触发时的执行器快照约束,不能任意替换缺席目标。
StrictSnapshot => "STRICT_SNAPSHOT",
/// 无法继续投递的子任务允许按跳过结果聚合。
BestEffort => "BEST_EFFORT",
}
}
wire_enum! {
/// Fanout 通知与回执的 Pub/Sub 模式;`Sharded` 用 SPUBLISH(同 slot 定向),`Broadcast` 用 PUBLISH。
JobPubSubMode {
/// 使用 SPUBLISH 向频道所在 slot 的订阅者投递。
Sharded => "SHARDED",
/// 使用 PUBLISH 向普通频道订阅者广播。
Broadcast => "BROADCAST",
}
}
wire_enum! {
/// 执行器登记状态;`Draining` 停止进入新能力快照但保留已有 attempt 的续期权。
JobExecutorState {
/// 执行器可进入新能力快照并接受任务分配。
Active => "ACTIVE",
/// 停止接受新分配,但保留已有 attempt 的续期权。
Draining => "DRAINING",
}
}
wire_enum! {
/// 串行队列积压溢出策略;只在 `SERIAL_QUEUE` 并发下生效,决定超过 backlog 上限时丢弃哪一端。
JobSerialOverflowPolicy {
/// 积压超过上限时跳过队列中最旧的待执行 Run。
SkipOldest => "SKIP_OLDEST",
/// 积压超过上限时跳过最新加入的 Run。
SkipNewest => "SKIP_NEWEST",
}
}
/// 业务作用:从配置的线协议名反序列化串行溢出策略;未知名称 fail-closed,不静默取默认。
///
/// 参数说明:
/// - `deserializer`: 配置来源的反序列化器,期望一个线协议名字符串。
///
/// 返回:已知名称返回对应策略;未知名称返回反序列化错误。
impl<'de> serde::Deserialize<'de> for JobSerialOverflowPolicy {
/// 业务作用:从配置的线协议名反序列化串行溢出策略,未知值不会落到默认策略。
///
/// 参数说明:`deserializer` 提供待解析的线协议字符串。
///
/// 返回:已知名称返回对应策略;未知名称或输入类型错误时返回反序列化错误。
fn deserialize<D>(deserializer: D) -> core::result::Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let text = <String as serde::Deserialize>::deserialize(deserializer)?;
Self::parse(&text)
.ok_or_else(|| <D::Error as serde::de::Error>::custom("未知的串行溢出策略线协议名"))
}
}
impl serde::Serialize for JobSerialOverflowPolicy {
/// 业务作用:把串行溢出策略写成持久配置使用的线协议名称。
///
/// 参数说明:`serializer` 为目标配置序列化器。
///
/// 返回:序列化成功返回目标值;底层写出失败返回序列化错误。
fn serialize<S>(&self, serializer: S) -> core::result::Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serializer.serialize_str(self.wire_name())
}
}
impl JobPubSubMode {
/// 业务作用:返回该模式对应的 Redis 发布命令名;投递、回执与唤醒脚本据此选择广播还是同 slot 定向。
///
/// 参数说明: 无。
///
/// 返回:`Sharded` 返回 `SPUBLISH`,`Broadcast` 返回 `PUBLISH`。
pub fn publish_command(self) -> &'static str {
match self {
Self::Sharded => "SPUBLISH",
Self::Broadcast => "PUBLISH",
}
}
}
/// 业务作用:从配置的线协议名反序列化 Pub/Sub 模式;未知名称 fail-closed,不静默取默认。
///
/// 参数说明:
/// - `deserializer`: 配置来源的反序列化器,期望一个线协议名字符串。
///
/// 返回:已知名称返回对应模式;未知名称返回反序列化错误。
impl<'de> serde::Deserialize<'de> for JobPubSubMode {
/// 业务作用:从配置的线协议名反序列化 Pub/Sub 模式,避免节点静默形成混合通知拓扑。
///
/// 参数说明:`deserializer` 提供待解析的线协议字符串。
///
/// 返回:已知名称返回对应模式;未知名称或输入类型错误时返回反序列化错误。
fn deserialize<D>(deserializer: D) -> core::result::Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let text = <String as serde::Deserialize>::deserialize(deserializer)?;
Self::parse(&text)
.ok_or_else(|| <D::Error as serde::de::Error>::custom("未知的 Pub/Sub 模式线协议名"))
}
}
impl serde::Serialize for JobPubSubMode {
/// 业务作用:把 Pub/Sub 模式写成持久配置使用的线协议名称。
///
/// 参数说明:`serializer` 为目标配置序列化器。
///
/// 返回:序列化成功返回目标值;底层写出失败返回序列化错误。
fn serialize<S>(&self, serializer: S) -> core::result::Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serializer.serialize_str(self.wire_name())
}
}
wire_enum! {
/// payload 线编码;JSON 走独立无类型注册表路径,Protobuf/RAW 原样透传字节。
JobWireCodec {
/// 以 JSON 表示业务正文,不依赖类型注册表。
Json => "JSON",
/// 原样传递 Protobuf 编码字节,由业务匹配消息类型。
Protobuf => "PROTOBUF",
/// 原样传递不作结构解释的业务字节。
Raw => "RAW",
}
}