tasklite-engine 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tasklite/__init__.py +35 -18
- tasklite/backend/base.py +87 -77
- tasklite/backend/memory.py +150 -95
- tasklite/backend/sqlite_backend.py +336 -255
- tasklite/engine/__init__.py +1 -1
- tasklite/engine/admission.py +113 -236
- tasklite/engine/channel.py +426 -296
- tasklite/engine/completion.py +153 -121
- tasklite/engine/config.py +31 -28
- tasklite/engine/dispatch.py +186 -207
- tasklite/engine/errorclass.py +79 -64
- tasklite/engine/governor.py +160 -21
- tasklite/engine/in_flight.py +39 -38
- tasklite/engine/ops.py +72 -72
- tasklite/engine/recovery.py +64 -160
- tasklite/engine/resource.py +34 -34
- tasklite/engine/runtime.py +118 -37
- tasklite/engine/scheduler.py +95 -52
- tasklite/engine/selection.py +244 -0
- tasklite/engine/session.py +16 -21
- tasklite/engine/store.py +368 -208
- tasklite/engine/types.py +20 -20
- tasklite/engine/wait.py +3 -3
- tasklite/exceptions.py +8 -0
- tasklite/hooks.py +16 -16
- tasklite/models/artifact.py +80 -0
- tasklite/models/attempt.py +17 -14
- tasklite/models/context.py +117 -135
- tasklite/models/job.py +53 -73
- tasklite/models/state.py +138 -141
- tasklite/models/task.py +30 -19
- tasklite/models/trigger.py +18 -0
- tasklite/pipeline.py +107 -96
- tasklite/selection.py +116 -0
- tasklite/testing.py +17 -11
- tasklite/triggers.py +46 -0
- tasklite/utils/artifact.py +203 -0
- tasklite/utils/clock.py +27 -1
- tasklite/utils/encoding.py +6 -6
- tasklite/utils/ipc.py +503 -614
- tasklite/utils/lockfile.py +8 -8
- tasklite/wrappers/discovery.py +74 -79
- {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/METADATA +51 -82
- tasklite_engine-2.2.0.dist-info/RECORD +55 -0
- {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/WHEEL +1 -1
- tasklite_engine-2.0.0.dist-info/RECORD +0 -49
- {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/licenses/LICENSE +0 -0
- {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/top_level.txt +0 -0
tasklite/__init__.py
CHANGED
|
@@ -7,10 +7,10 @@
|
|
|
7
7
|
|
|
8
8
|
公开面:TaskLite 门面(六步调用契约)、模型层、异常族、错误分类
|
|
9
9
|
(ErrorClassifier 与 ERR_* 错误码)、单射编码族、资源体系、失败档案
|
|
10
|
-
条目、用户钩子三件套、准入与重入队策略 seam、排序策略 seam
|
|
11
|
-
|
|
12
|
-
...`` 是唯一承诺稳定的导入面)。``__version__``
|
|
13
|
-
|
|
10
|
+
条目、用户钩子三件套、准入与重入队策略 seam、排序策略 seam、执行选择
|
|
11
|
+
规则值对象、持久化后端与运行摘要值对象,均经本文件集中导出
|
|
12
|
+
(``from tasklite import ...`` 是唯一承诺稳定的导入面)。``__version__``
|
|
13
|
+
为版本单一事实源(pyproject 动态读取点)。
|
|
14
14
|
|
|
15
15
|
分层单向依赖红线:``tasklite/models/`` 严禁 import
|
|
16
16
|
``tasklite/engine/``(IPC 声明读写一律下沉 ``tasklite/utils/ipc.py``),
|
|
@@ -22,14 +22,18 @@
|
|
|
22
22
|
"""
|
|
23
23
|
from __future__ import annotations
|
|
24
24
|
|
|
25
|
-
__version__ = "2.
|
|
25
|
+
__version__ = "2.2.0"
|
|
26
26
|
|
|
27
27
|
# ── 门面(六步调用契约的唯一入口)────────────────────────────────────
|
|
28
28
|
from .pipeline import TaskLite
|
|
29
29
|
|
|
30
|
+
# ── 执行选择(pipeline 级规则值对象与规则集)─────────────────────────
|
|
31
|
+
from .selection import Exclude, Selection, Skip
|
|
32
|
+
|
|
30
33
|
# ── 模型层:规格 / 实例 / 轨迹 / 上下文 ──────────────────────────────
|
|
31
34
|
from .models.attempt import AttemptRecord
|
|
32
35
|
from .models.context import JobContext
|
|
36
|
+
from .models.trigger import TriggerContext
|
|
33
37
|
from .models.job import Job, JobRuntimeState
|
|
34
38
|
from .models.task import Task, TaskRegistry, validate_resource_amounts
|
|
35
39
|
|
|
@@ -49,6 +53,8 @@ from .engine.errorclass import (
|
|
|
49
53
|
ERR_COMMIT_FAILURE,
|
|
50
54
|
ERR_DEADLOCK_GAP,
|
|
51
55
|
ERR_DEPENDENCY_DEADLOCK,
|
|
56
|
+
ERR_DEPENDENCY_EXCLUDED,
|
|
57
|
+
ERR_DEPENDENCY_SKIPPED,
|
|
52
58
|
ERR_DISPATCH_FAILURE,
|
|
53
59
|
ERR_IPC_WRITE_DEGRADED_PREFIX,
|
|
54
60
|
ERR_JOB_DEPENDENCY,
|
|
@@ -60,6 +66,7 @@ from .engine.errorclass import (
|
|
|
60
66
|
ERR_PROCESS_CRASH_PREFIX,
|
|
61
67
|
ERR_PROCESS_SIGNAL_DEATH,
|
|
62
68
|
ERR_RESOURCE_DEADLOCK,
|
|
69
|
+
ERR_SKIPPED,
|
|
63
70
|
ERR_TIMEOUT_PREFIX,
|
|
64
71
|
FATAL_EXCEPTIONS,
|
|
65
72
|
TRANSIENT_EXCEPTIONS,
|
|
@@ -68,7 +75,7 @@ from .engine.errorclass import (
|
|
|
68
75
|
ErrorClassifier,
|
|
69
76
|
ValidationErrorItem,
|
|
70
77
|
ValidationResult,
|
|
71
|
-
|
|
78
|
+
classify_error_category,
|
|
72
79
|
classify_exception,
|
|
73
80
|
is_transient_exception,
|
|
74
81
|
validate_payload_errors,
|
|
@@ -81,15 +88,16 @@ from .engine.resource import (
|
|
|
81
88
|
Resource,
|
|
82
89
|
)
|
|
83
90
|
|
|
84
|
-
# ──
|
|
91
|
+
# ── 失败档案条目与挂起条目 ───────────────────────────────────────────
|
|
92
|
+
from .engine.ops import SuspendEntry
|
|
85
93
|
from .engine.store import FailureEntry
|
|
86
94
|
|
|
87
|
-
# ── 策略 seam:准入(
|
|
95
|
+
# ── 策略 seam:准入(trigger)与重入队(节奏)─────────────────────────
|
|
88
96
|
from .engine.admission import (
|
|
89
97
|
ImmediateRequeuePolicy,
|
|
90
98
|
RequeuePlan,
|
|
91
99
|
RequeuePolicy,
|
|
92
|
-
|
|
100
|
+
TriggerRegistry,
|
|
93
101
|
)
|
|
94
102
|
|
|
95
103
|
# ── 策略 seam:调度排序 ──────────────────────────────────────────────
|
|
@@ -97,11 +105,11 @@ from .engine.scheduler import FifoOrderingPolicy, OrderingPolicy
|
|
|
97
105
|
|
|
98
106
|
# ── 运行值对象:run()/stop() 调用边界直接遭遇的形状 ──────────────────
|
|
99
107
|
from .engine.types import (
|
|
100
|
-
|
|
108
|
+
AttemptOutcome,
|
|
101
109
|
ExitReason,
|
|
102
110
|
RunSummary,
|
|
103
111
|
StopMode,
|
|
104
|
-
|
|
112
|
+
RunStats,
|
|
105
113
|
)
|
|
106
114
|
|
|
107
115
|
# ── 持久化后端 ───────────────────────────────────────────────────────
|
|
@@ -114,7 +122,7 @@ from .utils.encoding import (
|
|
|
114
122
|
encode_identifier,
|
|
115
123
|
encode_job_component,
|
|
116
124
|
percent_encode,
|
|
117
|
-
|
|
125
|
+
encode_job_uid_filename,
|
|
118
126
|
)
|
|
119
127
|
|
|
120
128
|
# ── JSON 序列化统一出口 ──────────────────────────────────────────────
|
|
@@ -123,10 +131,15 @@ from .utils import jsonutil
|
|
|
123
131
|
__all__ = [
|
|
124
132
|
# 门面
|
|
125
133
|
"TaskLite",
|
|
134
|
+
# 执行选择
|
|
135
|
+
"Exclude",
|
|
136
|
+
"Selection",
|
|
137
|
+
"Skip",
|
|
126
138
|
# 模型层
|
|
127
139
|
"AttemptRecord",
|
|
128
140
|
"Job",
|
|
129
141
|
"JobContext",
|
|
142
|
+
"TriggerContext",
|
|
130
143
|
"JobRuntimeState",
|
|
131
144
|
"Task",
|
|
132
145
|
"TaskRegistry",
|
|
@@ -146,7 +159,7 @@ __all__ = [
|
|
|
146
159
|
"ErrorClassifier",
|
|
147
160
|
"ValidationErrorItem",
|
|
148
161
|
"ValidationResult",
|
|
149
|
-
"
|
|
162
|
+
"classify_error_category",
|
|
150
163
|
"classify_exception",
|
|
151
164
|
"is_transient_exception",
|
|
152
165
|
"validate_payload_errors",
|
|
@@ -160,6 +173,9 @@ __all__ = [
|
|
|
160
173
|
"ERR_COMMIT_FAILURE",
|
|
161
174
|
"ERR_DISPATCH_FAILURE",
|
|
162
175
|
"ERR_DEADLOCK_GAP",
|
|
176
|
+
"ERR_DEPENDENCY_EXCLUDED",
|
|
177
|
+
"ERR_DEPENDENCY_SKIPPED",
|
|
178
|
+
"ERR_SKIPPED",
|
|
163
179
|
"ERR_TIMEOUT_PREFIX",
|
|
164
180
|
"ERR_PROCESS_CRASH_PREFIX",
|
|
165
181
|
"ERR_NO_IPC_RESULT",
|
|
@@ -172,21 +188,22 @@ __all__ = [
|
|
|
172
188
|
"CapacityResource",
|
|
173
189
|
"RateLimitResource",
|
|
174
190
|
"Resource",
|
|
175
|
-
#
|
|
191
|
+
# 失败档案与挂起
|
|
176
192
|
"FailureEntry",
|
|
193
|
+
"SuspendEntry",
|
|
177
194
|
# 策略 seam
|
|
178
195
|
"ImmediateRequeuePolicy",
|
|
179
196
|
"RequeuePlan",
|
|
180
197
|
"RequeuePolicy",
|
|
181
|
-
"
|
|
198
|
+
"TriggerRegistry",
|
|
182
199
|
"FifoOrderingPolicy",
|
|
183
200
|
"OrderingPolicy",
|
|
184
201
|
# 运行值对象
|
|
185
|
-
"
|
|
202
|
+
"AttemptOutcome",
|
|
186
203
|
"ExitReason",
|
|
187
204
|
"RunSummary",
|
|
188
205
|
"StopMode",
|
|
189
|
-
"
|
|
206
|
+
"RunStats",
|
|
190
207
|
# 持久化后端
|
|
191
208
|
"InMemoryStateBackend",
|
|
192
209
|
"SQLiteStateBackend",
|
|
@@ -196,7 +213,7 @@ __all__ = [
|
|
|
196
213
|
"encode_identifier",
|
|
197
214
|
"encode_job_component",
|
|
198
215
|
"percent_encode",
|
|
199
|
-
"
|
|
216
|
+
"encode_job_uid_filename",
|
|
200
217
|
# 序列化
|
|
201
218
|
"jsonutil",
|
|
202
219
|
]
|
tasklite/backend/base.py
CHANGED
|
@@ -5,10 +5,10 @@ delta 语义组织:队列行的「弹出」从不单独落盘——被弹出
|
|
|
5
5
|
磁盘队列中,直到 commit_job_success / commit_job_failure /
|
|
6
6
|
commit_retry / commit_skip 的事务内才删除(at-least-once 崩溃契约)。
|
|
7
7
|
|
|
8
|
-
失败档案(failed)术语:按 uid 唯一终态,
|
|
9
|
-
成功 commit 删 failed 同名行、失败 commit 删
|
|
8
|
+
失败档案(failed)术语:按 uid 唯一终态,successes/failed 全局互斥——
|
|
9
|
+
成功 commit 删 failed 同名行、失败 commit 删 successes 行,「最终状态唯一」
|
|
10
10
|
由此保证;失败历史与执行时间线由 attempts 旁路轨迹承接,本表不注入
|
|
11
|
-
计数字段。attempts 为 append-only 旁路观测面:不参与
|
|
11
|
+
计数字段。attempts 为 append-only 旁路观测面:不参与 successes/failed 的
|
|
12
12
|
互斥与 REPLACE 语义。
|
|
13
13
|
"""
|
|
14
14
|
from __future__ import annotations
|
|
@@ -19,7 +19,7 @@ from typing import Any, Callable, Mapping, Sequence
|
|
|
19
19
|
from ..models.attempt import ATTEMPT_OUTCOMES, AttemptRecord
|
|
20
20
|
|
|
21
21
|
|
|
22
|
-
def validate_queue_replacement(
|
|
22
|
+
def validate_queue_replacement(job_snapshots: Any) -> None:
|
|
23
23
|
"""整表替换集统一形状校验(save_queue / replace_queue_atomic 共用)。
|
|
24
24
|
|
|
25
25
|
契约:替换集必须是 job dict 的 list/tuple(与 load_queue 行形态一致);
|
|
@@ -29,16 +29,16 @@ def validate_queue_replacement(jobs: Any) -> None:
|
|
|
29
29
|
混过校验,SQLite 腿「DELETE 全表成功 + INSERT 全跳过」会静默清空整条
|
|
30
30
|
队列且事务正常提交,与 Memory 腿抛 TypeError 且队列原状形成行为分叉。
|
|
31
31
|
"""
|
|
32
|
-
if not isinstance(
|
|
32
|
+
if not isinstance(job_snapshots, (list, tuple)):
|
|
33
33
|
raise TypeError(
|
|
34
34
|
f"queue replacement must be a list of job dicts, "
|
|
35
|
-
f"got {type(
|
|
35
|
+
f"got {type(job_snapshots).__name__}"
|
|
36
36
|
)
|
|
37
|
-
for i,
|
|
38
|
-
if not isinstance(
|
|
37
|
+
for i, job_snapshot in enumerate(job_snapshots):
|
|
38
|
+
if not isinstance(job_snapshot, dict):
|
|
39
39
|
raise TypeError(
|
|
40
40
|
f"queue replacement item #{i} must be a job dict, "
|
|
41
|
-
f"got {type(
|
|
41
|
+
f"got {type(job_snapshot).__name__}"
|
|
42
42
|
)
|
|
43
43
|
|
|
44
44
|
|
|
@@ -46,7 +46,7 @@ def validate_attempt_dispatch(record: Any) -> None:
|
|
|
46
46
|
"""尝试轨迹插入门卫:只接受「派发即插行」形态。
|
|
47
47
|
|
|
48
48
|
契约(attempts append-only 协议的插入侧):AttemptRecord 且
|
|
49
|
-
outcome="running"、finished_at 与
|
|
49
|
+
outcome="running"、finished_at 与 error_message 均为 None——收尾字段由
|
|
50
50
|
``update_attempt`` 唯一写入;插入侧出现收尾字段说明调用方绕过了
|
|
51
51
|
派发点协议(终态行伪装成派发行,时间线出现空洞),fail-loud 拒绝。
|
|
52
52
|
"""
|
|
@@ -55,16 +55,16 @@ def validate_attempt_dispatch(record: Any) -> None:
|
|
|
55
55
|
f"attempt record must be an AttemptRecord, "
|
|
56
56
|
f"got {type(record).__name__} ({record!r})"
|
|
57
57
|
)
|
|
58
|
-
if record.outcome != "running" or record.finished_at is not None or record.
|
|
58
|
+
if record.outcome != "running" or record.finished_at is not None or record.error_message is not None:
|
|
59
59
|
raise ValueError(
|
|
60
60
|
"dispatch append must be a fresh running row "
|
|
61
|
-
"(outcome='running', finished_at=None,
|
|
61
|
+
"(outcome='running', finished_at=None, error_message=None), got "
|
|
62
62
|
f"outcome={record.outcome!r} finished_at={record.finished_at!r} "
|
|
63
|
-
f"
|
|
63
|
+
f"error_message={record.error_message!r}"
|
|
64
64
|
)
|
|
65
65
|
|
|
66
66
|
|
|
67
|
-
def validate_attempt_finish(outcome: Any, finished_at: Any,
|
|
67
|
+
def validate_attempt_finish(outcome: Any, finished_at: Any, error_message: Any) -> None:
|
|
68
68
|
"""尝试轨迹收尾门卫:outcome 属终态词汇、收尾时刻与错误形态合法。
|
|
69
69
|
|
|
70
70
|
running 是插入侧专属形态——收尾接口把 running 写回会把已派发行
|
|
@@ -84,39 +84,39 @@ def validate_attempt_finish(outcome: Any, finished_at: Any, error: Any) -> None:
|
|
|
84
84
|
)
|
|
85
85
|
if not finished_at:
|
|
86
86
|
raise ValueError("finished_at must be a non-empty str")
|
|
87
|
-
if
|
|
87
|
+
if error_message is not None and not isinstance(error_message, str):
|
|
88
88
|
raise TypeError(
|
|
89
|
-
f"
|
|
89
|
+
f"error_message must be a str or None, got {type(error_message).__name__} ({error_message!r})"
|
|
90
90
|
)
|
|
91
|
-
if
|
|
92
|
-
raise ValueError("
|
|
91
|
+
if error_message == "":
|
|
92
|
+
raise ValueError("error_message must be a non-empty str or None")
|
|
93
93
|
|
|
94
94
|
|
|
95
95
|
class AbstractStateBackend(ABC):
|
|
96
96
|
"""管线状态持久化抽象契约(SQLite / Memory 双腿共同口径)。
|
|
97
97
|
|
|
98
98
|
语义分组:
|
|
99
|
-
- 全量加载(
|
|
99
|
+
- 全量加载(load_successes / load_failed / load_failure_payloads /
|
|
100
100
|
load_cursors / load_queue):仅启动装配与测试装配使用;
|
|
101
101
|
- 整表重写(save_queue / replace_queue_atomic):读-改-写必须经
|
|
102
102
|
``replace_queue_atomic`` 收敛进单个写事务;
|
|
103
103
|
- delta 提交(commit_job_success / commit_job_failure /
|
|
104
|
-
commit_retry /
|
|
104
|
+
commit_retry / commit_job_failures / commit_skip):逐 job 单事务
|
|
105
105
|
碎片化,禁止多 job 混合长事务;返回 False 表示持久化失败且后端
|
|
106
106
|
保持调用前状态,调用方不得推进内存镜像并走崩溃契约;
|
|
107
107
|
- 增量入队(enqueue_jobs):不做全量覆盖,与运行中 delta 提交并发
|
|
108
108
|
安全(写入侧不覆盖);
|
|
109
|
-
- 定向删除与种子(delete_queue_uids / delete_failed /
|
|
110
|
-
|
|
109
|
+
- 定向删除与种子(delete_queue_uids / delete_failed / delete_successes /
|
|
110
|
+
seed_successes / seed_cursor):加载期 repair 差量落盘与运维接缝;
|
|
111
111
|
- 尝试轨迹(append_attempt / update_attempt / load_attempts):
|
|
112
112
|
append-only 旁路观测面;
|
|
113
|
-
- 元数据(
|
|
113
|
+
- 元数据(get_engine_metadata / set_engine_metadata):框架级键值(fencing 的 last_run_id 等)。
|
|
114
114
|
"""
|
|
115
115
|
|
|
116
116
|
# 全量加载 -------------------------------------------------------
|
|
117
117
|
|
|
118
118
|
@abstractmethod
|
|
119
|
-
def
|
|
119
|
+
def load_successes(self) -> dict[str, dict[str, Any]]:
|
|
120
120
|
"""加载全部成功终态(uid → meta)。"""
|
|
121
121
|
|
|
122
122
|
@abstractmethod
|
|
@@ -124,7 +124,7 @@ class AbstractStateBackend(ABC):
|
|
|
124
124
|
"""加载全部失败档案终态(uid → 失败 meta)。"""
|
|
125
125
|
|
|
126
126
|
@abstractmethod
|
|
127
|
-
def
|
|
127
|
+
def load_failure_payloads(self) -> dict[str, dict[str, Any]]:
|
|
128
128
|
"""读取失败档案各 uid 的原始业务 payload 快照(无快照的 uid 不出现)。"""
|
|
129
129
|
|
|
130
130
|
@abstractmethod
|
|
@@ -133,12 +133,12 @@ class AbstractStateBackend(ABC):
|
|
|
133
133
|
|
|
134
134
|
@abstractmethod
|
|
135
135
|
def load_queue(self) -> list[dict[str, Any]]:
|
|
136
|
-
"""按
|
|
136
|
+
"""按 queue_position 升序加载磁盘队列真相。"""
|
|
137
137
|
|
|
138
138
|
# 整表重写 -------------------------------------------------------
|
|
139
139
|
|
|
140
140
|
@abstractmethod
|
|
141
|
-
def save_queue(self,
|
|
141
|
+
def save_queue(self, job_snapshots: list[dict[str, Any]]) -> None:
|
|
142
142
|
"""整表重写队列(测试装配 / replace_queue_atomic 的事务内步骤)。
|
|
143
143
|
|
|
144
144
|
红线:这是「无读基准的整表覆盖」——跨进程并发的 enqueue/commit
|
|
@@ -176,39 +176,45 @@ class AbstractStateBackend(ABC):
|
|
|
176
176
|
@abstractmethod
|
|
177
177
|
def commit_job_success(
|
|
178
178
|
self,
|
|
179
|
-
|
|
180
|
-
|
|
179
|
+
job_uid: str,
|
|
180
|
+
result_metadata: dict,
|
|
181
181
|
*,
|
|
182
|
-
|
|
182
|
+
attempt_id: int | None = None,
|
|
183
|
+
execution_id: str | None = None,
|
|
184
|
+
finished_at: str | None = None,
|
|
185
|
+
spawned_job_snapshots: Sequence[dict[str, Any]] = (),
|
|
183
186
|
cursor_updates: Mapping[str, str | None] | None = None,
|
|
184
187
|
) -> bool:
|
|
185
|
-
"""原子持久化一个成功 job 的 delta
|
|
188
|
+
"""原子持久化一个成功 job 的 delta,并在同一事务中校验与终结对应 attempts 行。
|
|
186
189
|
|
|
187
190
|
单事务效果:
|
|
188
|
-
-
|
|
191
|
+
- attempts:校验 attempt_id / finished_at 非空,对应行存在、job_uid 一致、
|
|
192
|
+
execution_id 一致(传入非空时)、且 outcome == 'running',将其更新为
|
|
193
|
+
outcome='succeeded', finished_at=finished_at, error_message=None;
|
|
194
|
+
- successes:INSERT/REPLACE uid → result_metadata;
|
|
189
195
|
- queue:DELETE 被弹出的 uid;
|
|
190
|
-
- queue:
|
|
191
|
-
- failed:DELETE 同名残行(成功终态唯一,防
|
|
196
|
+
- queue:spawned_job_snapshots 队头插入(保序);
|
|
197
|
+
- failed:DELETE 同名残行(成功终态唯一,防 successes∩failed 并存);
|
|
192
198
|
- cursors:合并 cursor_updates(None 值表示删除游标)。
|
|
193
199
|
|
|
194
|
-
返回 True 成功;返回 False
|
|
195
|
-
|
|
196
|
-
状态,并自行决定是否重入队(崩溃契约)。
|
|
200
|
+
返回 True 成功;返回 False 表示 attempts 校验失败或任一步持久化失败且
|
|
201
|
+
后端保持调用前状态(被弹出的 uid 仍在磁盘队列,attempts 仍保持原状),
|
|
202
|
+
调用方不得更新内存 successes/cursor 状态,并自行决定是否重入队(崩溃契约)。
|
|
197
203
|
"""
|
|
198
204
|
|
|
199
205
|
@abstractmethod
|
|
200
206
|
def commit_job_failure(
|
|
201
207
|
self,
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
208
|
+
job_uid: str,
|
|
209
|
+
failure_metadata: dict,
|
|
210
|
+
payload: dict[str, Any] | None = None,
|
|
205
211
|
) -> bool:
|
|
206
212
|
"""原子持久化一个失败 job 的 delta(写入失败档案)。
|
|
207
213
|
|
|
208
|
-
单事务效果:failed INSERT/REPLACE uid →
|
|
209
|
-
queue DELETE uid;
|
|
210
|
-
记录作废(最终状态唯一),否则磁盘
|
|
211
|
-
``
|
|
214
|
+
单事务效果:failed INSERT/REPLACE uid → failure_metadata;
|
|
215
|
+
queue DELETE uid;successes DELETE 同名行——重跑任务重试耗尽时旧成功
|
|
216
|
+
记录作废(最终状态唯一),否则磁盘 successes∩failed 并存破坏互斥。
|
|
217
|
+
``payload`` 是原始业务输入快照(补跑自足,无需外部反查);
|
|
212
218
|
None 表示本路径无可存快照,保留既有快照不覆盖。
|
|
213
219
|
返回语义与 ``commit_job_success`` 一致:False ⇒ 后端未变、崩溃契约。
|
|
214
220
|
"""
|
|
@@ -216,53 +222,53 @@ class AbstractStateBackend(ABC):
|
|
|
216
222
|
@abstractmethod
|
|
217
223
|
def commit_retry(
|
|
218
224
|
self,
|
|
219
|
-
|
|
220
|
-
|
|
225
|
+
popped_job_uid: str,
|
|
226
|
+
requeued_job_snapshot: dict[str, Any],
|
|
221
227
|
*,
|
|
222
228
|
front: bool = False,
|
|
223
229
|
) -> bool:
|
|
224
|
-
"""原子持久化一次重入队 delta:DELETE
|
|
230
|
+
"""原子持久化一次重入队 delta:DELETE popped_job_uid + 按 front 插入 requeued_job_snapshot。
|
|
225
231
|
|
|
226
|
-
不写
|
|
232
|
+
不写 successes/failed。同 uid 重试是 DELETE+INSERT(一次执行没有独立
|
|
227
233
|
持久身份,身份仍是 uid)。重插不得静默丢弃:requeued uid 撞上删除
|
|
228
234
|
popped 后的既有行冲突时返回 False 走崩溃契约,绝不产出重复队列
|
|
229
235
|
条目却报成功。
|
|
230
236
|
"""
|
|
231
237
|
|
|
232
238
|
@abstractmethod
|
|
233
|
-
def
|
|
239
|
+
def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> bool:
|
|
234
240
|
"""原子批量写失败档案(死锁/级联场景)的 delta。
|
|
235
241
|
|
|
236
|
-
单事务效果:failed INSERT/REPLACE 每个 uid →
|
|
242
|
+
单事务效果:failed INSERT/REPLACE 每个 uid → metadata;
|
|
237
243
|
queue 按 uid 精准 DELETE(剩余条目保持原顺序);
|
|
238
|
-
|
|
244
|
+
successes 批量 DELETE 同名行(与 commit_job_failure 对称的最终状态唯一)。
|
|
239
245
|
任一行失败 ⇒ 整体回滚、返回 False,绝不留下「队列已删、档案未落」
|
|
240
246
|
的半成品失败态。
|
|
241
247
|
"""
|
|
242
248
|
|
|
243
249
|
@abstractmethod
|
|
244
|
-
def commit_skip(self,
|
|
250
|
+
def commit_skip(self, job_uid: str) -> bool:
|
|
245
251
|
"""delta 删除队列中已终态(重复)的 uid。
|
|
246
252
|
|
|
247
|
-
去重命中(uid 已在
|
|
253
|
+
去重命中(uid 已在 successes/failed)时调用——磁盘队列中该 uid 是残留
|
|
248
254
|
条目,直接删除以同步内存/磁盘(内存 = 磁盘 − in-flight)。
|
|
249
|
-
不写
|
|
255
|
+
不写 successes/failed(重复条目不改变任何状态,只是清理)。
|
|
250
256
|
返回 True 成功;False 时 on-disk 队列不变,调用方走崩溃契约。
|
|
251
257
|
"""
|
|
252
258
|
|
|
253
259
|
@abstractmethod
|
|
254
|
-
def append_failed(self,
|
|
260
|
+
def append_failed(self, job_uid: str, metadata: dict[str, Any] | None = None) -> None:
|
|
255
261
|
"""绕过队列直接写一条失败档案记录(带外登记面)。
|
|
256
262
|
|
|
257
|
-
按 uid REPLACE(幂等);不触碰 queue/
|
|
263
|
+
按 uid REPLACE(幂等);不触碰 queue/successes/cursors。持久化失败
|
|
258
264
|
抛异常(不吞)。
|
|
259
265
|
"""
|
|
260
266
|
|
|
261
267
|
# 增量入队 -------------------------------------------------------
|
|
262
268
|
|
|
263
269
|
@abstractmethod
|
|
264
|
-
def enqueue_jobs(self,
|
|
265
|
-
"""批量增量入队:按 front 在队列头/尾插入
|
|
270
|
+
def enqueue_jobs(self, job_snapshots: list[dict[str, Any]], *, front: bool = False) -> list[str]:
|
|
271
|
+
"""批量增量入队:按 front 在队列头/尾插入 job_snapshots(保序),单事务原子。
|
|
266
272
|
|
|
267
273
|
跳过与现有队列重复的 uid(含批次内重复,首个存储),返回实际插入
|
|
268
274
|
的 uid 列表。与 commit_* 的 delta 语义对齐:不做全表重写——运行中
|
|
@@ -274,7 +280,7 @@ class AbstractStateBackend(ABC):
|
|
|
274
280
|
# 定向删除与种子 --------------------------------------------------
|
|
275
281
|
|
|
276
282
|
@abstractmethod
|
|
277
|
-
def delete_queue_uids(self,
|
|
283
|
+
def delete_queue_uids(self, job_uids: list[str]) -> int:
|
|
278
284
|
"""按 uid 定向批量删除队列行(加载期 repair 的差量落盘唯一出口)。
|
|
279
285
|
|
|
280
286
|
与 save_queue 的全表重写相对:只 DELETE 指定 uid 的行,其余行原样
|
|
@@ -285,21 +291,21 @@ class AbstractStateBackend(ABC):
|
|
|
285
291
|
"""
|
|
286
292
|
|
|
287
293
|
@abstractmethod
|
|
288
|
-
def delete_failed(self,
|
|
294
|
+
def delete_failed(self, job_uids: list[str]) -> int:
|
|
289
295
|
"""从失败档案批量删除指定 uid(clear_failures 的后端实现)。
|
|
290
296
|
|
|
291
|
-
返回实际删除行数(连带清除 payload 快照)。不触碰 queue/
|
|
297
|
+
返回实际删除行数(连带清除 payload 快照)。不触碰 queue/successes。
|
|
292
298
|
仅限 run() 之外调用(改变 is_known 判定基础,与 enqueue 同纪律)。
|
|
293
299
|
"""
|
|
294
300
|
|
|
295
301
|
@abstractmethod
|
|
296
|
-
def
|
|
297
|
-
"""从
|
|
302
|
+
def delete_successes(self, job_uids: list[str]) -> int:
|
|
303
|
+
"""从 successes 批量删除指定 uid(clear_history 的后端实现 + commit 路径事务内清理)。
|
|
298
304
|
|
|
299
305
|
两种调用上下文:
|
|
300
306
|
- 运行外管理 API 的批量删除;
|
|
301
|
-
- commit_job_failure /
|
|
302
|
-
(重跑任务重跑失败时
|
|
307
|
+
- commit_job_failure / commit_job_failures 的同一事务内逐 uid 删除
|
|
308
|
+
(重跑任务重跑失败时 successes 旧记录作废,最终状态唯一)。
|
|
303
309
|
|
|
304
310
|
运行中的调用仅限 commit 事务内部(随失败档案写入原子提交,不改变
|
|
305
311
|
进行中的派发判定);独立调用仅限 run 之外(改变 is_known 判定
|
|
@@ -307,13 +313,13 @@ class AbstractStateBackend(ABC):
|
|
|
307
313
|
"""
|
|
308
314
|
|
|
309
315
|
@abstractmethod
|
|
310
|
-
def
|
|
311
|
-
"""把 uid 批量写入
|
|
316
|
+
def seed_successes(self, job_uids: list[str]) -> int:
|
|
317
|
+
"""把 uid 批量写入 successes(meta 为空 dict)——存档迁移标记「已处理」。
|
|
312
318
|
|
|
313
319
|
幂等:已存在的 uid 被覆盖(meta 重置为空)。返回实际写入行数。
|
|
314
|
-
不变式(
|
|
320
|
+
不变式(successes/failed 全局互斥):已在 failed 的 uid 拒绝种子——
|
|
315
321
|
冲突整体拒绝(零写入、抛 ValueError),不静默清除失败档案记录;
|
|
316
|
-
持久层与管理 API(OpsConsole.
|
|
322
|
+
持久层与管理 API(OpsConsole.seed_successes)两层同契约。
|
|
317
323
|
"""
|
|
318
324
|
|
|
319
325
|
@abstractmethod
|
|
@@ -322,8 +328,8 @@ class AbstractStateBackend(ABC):
|
|
|
322
328
|
|
|
323
329
|
入口校验 fail-loud:key 非空 str、value 必须 str——静默 str() 强转
|
|
324
330
|
会让同一非法入参在 sqlite 腿抛异常、memory 腿写数字串(跨后端行为
|
|
325
|
-
分歧),且与内存镜像值型漂移。discovery 的已见判定走
|
|
326
|
-
「已见预填」请用 ``
|
|
331
|
+
分歧),且与内存镜像值型漂移。discovery 的已见判定走 successes/failed,
|
|
332
|
+
「已见预填」请用 ``seed_successes``;本方法服务通用业务 cursor。
|
|
327
333
|
"""
|
|
328
334
|
|
|
329
335
|
# 尝试轨迹(append-only 旁路观测面)--------------------------------
|
|
@@ -334,8 +340,8 @@ class AbstractStateBackend(ABC):
|
|
|
334
340
|
|
|
335
341
|
协议:仅在派发点调用,record 必须是 outcome="running"、无收尾
|
|
336
342
|
时刻/错误的派发即插行(``validate_attempt_dispatch`` 门卫),随行
|
|
337
|
-
落盘 started_at /
|
|
338
|
-
的互斥与 REPLACE 语义,本方法不触碰 queue/
|
|
343
|
+
落盘 started_at / execution_id / run_id。attempts 不参与 successes/failed
|
|
344
|
+
的互斥与 REPLACE 语义,本方法不触碰 queue/successes/failed/cursors;
|
|
339
345
|
持久化失败抛异常(fail-loud,不吞)。
|
|
340
346
|
"""
|
|
341
347
|
|
|
@@ -346,9 +352,9 @@ class AbstractStateBackend(ABC):
|
|
|
346
352
|
*,
|
|
347
353
|
outcome: str,
|
|
348
354
|
finished_at: str,
|
|
349
|
-
|
|
355
|
+
error_message: str | None = None,
|
|
350
356
|
) -> bool:
|
|
351
|
-
"""终态/重试时收尾轨迹行:写 finished_at / outcome /
|
|
357
|
+
"""终态/重试时收尾轨迹行:写 finished_at / outcome / error_message。
|
|
352
358
|
|
|
353
359
|
收尾词汇与 ``AttemptRecord`` 一致(succeeded / failed / requeued /
|
|
354
360
|
skipped),running 是插入侧专属形态(``validate_attempt_finish``
|
|
@@ -362,14 +368,18 @@ class AbstractStateBackend(ABC):
|
|
|
362
368
|
def load_attempts(self, job_uid: str) -> list[AttemptRecord]:
|
|
363
369
|
"""按 job_uid 读取全部尝试轨迹(按轨迹 id 升序);无轨迹返回空列表。"""
|
|
364
370
|
|
|
371
|
+
@abstractmethod
|
|
372
|
+
def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
|
|
373
|
+
"""窄查询指定 job_uid 最新一条 outcome == 'succeeded' 轨迹行的 finished_at;无则返回 None。"""
|
|
374
|
+
|
|
365
375
|
# 元数据 ---------------------------------------------------------
|
|
366
376
|
|
|
367
377
|
@abstractmethod
|
|
368
|
-
def
|
|
378
|
+
def get_engine_metadata(self, key: str) -> str | None:
|
|
369
379
|
"""读取一条框架级元数据(如 fencing 的 last_run_id)。无则返回 None。"""
|
|
370
380
|
|
|
371
381
|
@abstractmethod
|
|
372
|
-
def
|
|
382
|
+
def set_engine_metadata(self, key: str, value: str) -> None:
|
|
373
383
|
"""写入一条框架级元数据(UPSERT 语义)。失败抛异常(不吞)。"""
|
|
374
384
|
|
|
375
385
|
|