tasklite-engine 3.0.0.dev0__py3-none-any.whl → 3.0.0.dev2__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 +42 -18
- tasklite/__main__.py +205 -0
- tasklite/_report.py +562 -0
- tasklite/backend/__init__.py +19 -2
- tasklite/backend/base.py +327 -156
- tasklite/backend/memory.py +261 -339
- tasklite/backend/sqlite_backend.py +416 -488
- tasklite/edit.py +1276 -0
- tasklite/engine/__init__.py +6 -7
- tasklite/engine/_worker_bootstrap.py +221 -0
- tasklite/engine/_worker_runtime.py +229 -0
- tasklite/engine/admission.py +20 -114
- tasklite/engine/authorization.py +989 -0
- tasklite/engine/channel.py +531 -468
- tasklite/engine/completion.py +193 -275
- tasklite/engine/config.py +5 -11
- tasklite/engine/dispatch.py +299 -384
- tasklite/engine/governor.py +134 -69
- tasklite/engine/in_flight.py +20 -88
- tasklite/engine/launcher.py +1173 -0
- tasklite/engine/recovery.py +147 -100
- tasklite/engine/resource.py +50 -103
- tasklite/engine/runtime.py +158 -525
- tasklite/engine/scheduler.py +9 -46
- tasklite/engine/session.py +60 -15
- tasklite/engine/store.py +235 -462
- tasklite/engine/types.py +29 -40
- tasklite/engine/wait.py +8 -0
- tasklite/exceptions.py +0 -1
- tasklite/models/artifact.py +84 -62
- tasklite/models/context.py +37 -30
- tasklite/models/graph.py +114 -0
- tasklite/models/job.py +3 -5
- tasklite/models/records.py +482 -0
- tasklite/models/state.py +19 -125
- tasklite/models/trigger.py +63 -3
- tasklite/pipeline.py +92 -100
- tasklite/resource.py +79 -2
- tasklite/snapshot.py +608 -405
- tasklite/testing.py +424 -11
- tasklite/utils/artifact.py +1091 -179
- tasklite/utils/encoding.py +21 -40
- tasklite/utils/ipc.py +49 -1
- tasklite/utils/lockfile.py +50 -19
- tasklite/wrappers/__init__.py +1 -1
- tasklite/wrappers/discovery.py +13 -16
- tasklite/wrappers/http.py +77 -43
- {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/METADATA +23 -16
- tasklite_engine-3.0.0.dev2.dist-info/RECORD +60 -0
- tasklite/contrib/__init__.py +0 -7
- tasklite/engine/execution_access.py +0 -39
- tasklite/engine/files.py +0 -52
- tasklite/engine/ops.py +0 -25
- tasklite/engine/selection.py +0 -186
- tasklite/hooks.py +0 -49
- tasklite/triggers.py +0 -47
- tasklite_engine-3.0.0.dev0.dist-info/RECORD +0 -58
- {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/WHEEL +0 -0
- {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/licenses/LICENSE +0 -0
- {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/top_level.txt +0 -0
tasklite/backend/base.py
CHANGED
|
@@ -1,17 +1,64 @@
|
|
|
1
1
|
"""当前持久层内部 Interface 与共享入口门卫。
|
|
2
2
|
|
|
3
3
|
队列状态、追加式 Attempt、终态档案、派生 Job 和游标由一次结算原子提交。
|
|
4
|
-
successes 与 failed 按 UID 互斥;Attempt
|
|
4
|
+
successes 与 failed 按 UID 互斥;Attempt 仅作严格 append-only 执行轨迹,
|
|
5
|
+
编号独立于任何状态修整操作且永不可删。
|
|
5
6
|
"""
|
|
6
7
|
from __future__ import annotations
|
|
7
8
|
|
|
8
9
|
import copy
|
|
10
|
+
import os
|
|
9
11
|
from abc import ABC, abstractmethod
|
|
10
|
-
from
|
|
12
|
+
from contextlib import AbstractContextManager
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from typing import Any, Literal, Mapping, Sequence, TypeAlias, cast
|
|
15
|
+
|
|
16
|
+
from ..exceptions import TaskLiteError
|
|
17
|
+
from ..utils.artifact import TargetType
|
|
18
|
+
from ..utils.clock import utc_now_iso
|
|
11
19
|
|
|
12
20
|
|
|
13
21
|
QUEUE_EXECUTION_ID_KEY = "__tasklite_execution_id__"
|
|
14
22
|
|
|
23
|
+
FailureEntry: TypeAlias = (
|
|
24
|
+
tuple[str, dict[str, Any]]
|
|
25
|
+
| tuple[str, dict[str, Any], dict[str, Any] | None]
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class RunningAttemptRecovery:
|
|
31
|
+
"""遗留 running 执行的待补写失败 Attempt 载荷。"""
|
|
32
|
+
|
|
33
|
+
job_uid: str
|
|
34
|
+
attempt_no: int
|
|
35
|
+
execution_id: str
|
|
36
|
+
run_id: str
|
|
37
|
+
started_at: str | None
|
|
38
|
+
settled_at: str
|
|
39
|
+
job_snapshot: dict[str, Any]
|
|
40
|
+
files: dict[str, Any] | None
|
|
41
|
+
result: dict[str, Any]
|
|
42
|
+
error_message: str | None
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class GraphEditCommit:
|
|
47
|
+
"""图修整事务声明式后端提交载荷(O(Δ) 仅含触碰 uid)。
|
|
48
|
+
|
|
49
|
+
- ``queue_writes``: ``uid -> job_snapshot | None``(``None`` 删除;非 ``None`` 写入为 ``pending`` 并排入队尾)
|
|
50
|
+
- ``success_writes``: ``uid -> metadata | None``(``None`` 删除;非 ``None`` 写入 successes)
|
|
51
|
+
- ``failed_writes``: ``uid -> (metadata, payload) | None``(``None`` 删除;非 ``None`` 写入 failed)
|
|
52
|
+
- ``recovery_attempts``: 待补写的遗留 running 失败 Attempt 序列
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
queue_writes: Mapping[str, dict[str, Any] | None] = field(default_factory=dict)
|
|
56
|
+
success_writes: Mapping[str, dict[str, Any] | None] = field(default_factory=dict)
|
|
57
|
+
failed_writes: Mapping[str, tuple[dict[str, Any], dict[str, Any] | None] | None] = field(
|
|
58
|
+
default_factory=dict
|
|
59
|
+
)
|
|
60
|
+
recovery_attempts: tuple[RunningAttemptRecovery, ...] = ()
|
|
61
|
+
|
|
15
62
|
|
|
16
63
|
def queue_snapshot_with_execution_id(
|
|
17
64
|
job_snapshot: Mapping[str, Any], execution_id: str
|
|
@@ -47,14 +94,10 @@ def execution_id_matches_run(execution_id: str, run_id: str) -> bool:
|
|
|
47
94
|
|
|
48
95
|
|
|
49
96
|
def validate_queue_replacement(job_snapshots: Any) -> None:
|
|
50
|
-
"""
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
违约,fail-loud 抛 TypeError。
|
|
55
|
-
不变式:双腿必须在任何写变(DELETE / 赋值)之前调用本校验——None 若
|
|
56
|
-
混过校验,SQLite 腿「DELETE 全表成功 + INSERT 全跳过」会静默清空整条
|
|
57
|
-
队列且事务正常提交,与 Memory 腿抛 TypeError 且队列原状形成行为分叉。
|
|
97
|
+
"""队列快照序列形状校验(用于 ``commit_job_settlement`` 派生作业入队前守卫)。
|
|
98
|
+
|
|
99
|
+
契约:入参必须是 job dict 的 list/tuple;None、非序列或非 dict 元素均属
|
|
100
|
+
契约违约,双后端须在进入任何写事务前调用本校验并 fail-loud 抛 TypeError。
|
|
58
101
|
"""
|
|
59
102
|
if not isinstance(job_snapshots, (list, tuple)):
|
|
60
103
|
raise TypeError(
|
|
@@ -69,15 +112,241 @@ def validate_queue_replacement(job_snapshots: Any) -> None:
|
|
|
69
112
|
)
|
|
70
113
|
|
|
71
114
|
|
|
115
|
+
def normalize_failure_entries(
|
|
116
|
+
entries: Sequence[FailureEntry],
|
|
117
|
+
) -> list[tuple[str, dict[str, Any], dict[str, Any] | None]]:
|
|
118
|
+
"""校验并展开批量失败条目,统一规范为 ``(job_uid, failure_metadata, payload)`` 三元组。"""
|
|
119
|
+
if not isinstance(entries, Sequence) or isinstance(entries, (str, bytes)):
|
|
120
|
+
raise TypeError(f"failure entries must be a sequence, got {type(entries).__name__}")
|
|
121
|
+
normalized: list[tuple[str, dict[str, Any], dict[str, Any] | None]] = []
|
|
122
|
+
for i, item in enumerate(entries):
|
|
123
|
+
if not isinstance(item, tuple) or len(item) not in (2, 3):
|
|
124
|
+
raise TypeError(
|
|
125
|
+
f"failure entry #{i} must be a (job_uid, metadata[, payload]) tuple, "
|
|
126
|
+
f"got {type(item).__name__}"
|
|
127
|
+
)
|
|
128
|
+
job_uid = item[0]
|
|
129
|
+
meta = item[1]
|
|
130
|
+
payload = item[2] if len(item) == 3 else None
|
|
131
|
+
if not isinstance(job_uid, str) or not job_uid:
|
|
132
|
+
raise TypeError(f"failure entry #{i} job_uid must be a non-empty str, got {job_uid!r}")
|
|
133
|
+
if not isinstance(meta, dict):
|
|
134
|
+
raise TypeError(
|
|
135
|
+
f"failure entry #{i} metadata must be a dict, got {type(meta).__name__}"
|
|
136
|
+
)
|
|
137
|
+
if payload is not None and not isinstance(payload, dict):
|
|
138
|
+
raise TypeError(
|
|
139
|
+
f"failure entry #{i} payload must be a dict or None, got {type(payload).__name__}"
|
|
140
|
+
)
|
|
141
|
+
normalized.append((job_uid, meta, payload))
|
|
142
|
+
return normalized
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def validate_cursor_key(key: Any, *, error_type: type[Exception] = TypeError) -> str:
|
|
146
|
+
"""校验游标键必须为非空 str。"""
|
|
147
|
+
if not isinstance(key, str) or not key:
|
|
148
|
+
raise error_type(f"cursor key must be a non-empty str, got {key!r}")
|
|
149
|
+
return key
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def validate_cursor_value(value: Any) -> str | None:
|
|
153
|
+
"""校验游标值必须为 str 或 None。"""
|
|
154
|
+
if value is not None and not isinstance(value, str):
|
|
155
|
+
raise TypeError(f"cursor value must be str or None, got {type(value).__name__}")
|
|
156
|
+
return value
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def validate_mark_job_running_args(
|
|
160
|
+
*, execution_id: Any, run_id: Any, started_at: Any
|
|
161
|
+
) -> None:
|
|
162
|
+
"""校验 ``mark_job_running`` 前置入参(SQLite / Memory 双后端同源调用)。"""
|
|
163
|
+
if not isinstance(execution_id, str) or not execution_id:
|
|
164
|
+
raise ValueError("execution_id must be a non-empty str")
|
|
165
|
+
if not isinstance(run_id, str) or not run_id:
|
|
166
|
+
raise ValueError("run_id must be a non-empty str")
|
|
167
|
+
if not execution_id_matches_run(execution_id, run_id):
|
|
168
|
+
raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
|
|
169
|
+
if not isinstance(started_at, str) or not started_at:
|
|
170
|
+
raise ValueError("started_at must be a non-empty str")
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def validate_mark_job_running_state(
|
|
174
|
+
job_uid: str,
|
|
175
|
+
*,
|
|
176
|
+
present_in_queue: bool,
|
|
177
|
+
queue_status: str | None,
|
|
178
|
+
) -> None:
|
|
179
|
+
"""校验 ``mark_job_running`` 队列行当前状态(必须存在且未处于 running)。"""
|
|
180
|
+
if not present_in_queue:
|
|
181
|
+
raise ValueError(f"Job {job_uid} not found in queue")
|
|
182
|
+
if queue_status == "running":
|
|
183
|
+
raise ValueError(f"Job {job_uid} is already running")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def validate_settlement_args(
|
|
187
|
+
*,
|
|
188
|
+
outcome: Any,
|
|
189
|
+
attempt_no: Any,
|
|
190
|
+
execution_id: Any,
|
|
191
|
+
run_id: Any,
|
|
192
|
+
settled_at: Any,
|
|
193
|
+
started_at: Any,
|
|
194
|
+
cursor_updates: Mapping[str, str | None] | None,
|
|
195
|
+
spawned_job_snapshots: Sequence[dict[str, Any]],
|
|
196
|
+
) -> None:
|
|
197
|
+
"""校验 ``commit_job_settlement`` 前置入参(SQLite / Memory 双后端同源调用)。"""
|
|
198
|
+
if outcome not in ("success", "failure", "retry", "pending"):
|
|
199
|
+
raise ValueError(f"Invalid outcome: {outcome}")
|
|
200
|
+
if not isinstance(attempt_no, int) or isinstance(attempt_no, bool) or attempt_no < 1:
|
|
201
|
+
raise TypeError(f"attempt_no must be int >= 1, got {attempt_no!r}")
|
|
202
|
+
if not isinstance(execution_id, str) or not execution_id:
|
|
203
|
+
raise ValueError(f"execution_id must be non-empty str, got {execution_id!r}")
|
|
204
|
+
if not isinstance(run_id, str) or not run_id:
|
|
205
|
+
raise ValueError(f"run_id must be non-empty str, got {run_id!r}")
|
|
206
|
+
if not execution_id_matches_run(execution_id, run_id):
|
|
207
|
+
raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
|
|
208
|
+
if not isinstance(settled_at, str) or not settled_at:
|
|
209
|
+
raise ValueError(f"settled_at must be non-empty str, got {settled_at!r}")
|
|
210
|
+
if started_at is not None and (not isinstance(started_at, str) or not started_at):
|
|
211
|
+
raise ValueError("started_at must be non-empty str or None")
|
|
212
|
+
if cursor_updates:
|
|
213
|
+
for k, v in cursor_updates.items():
|
|
214
|
+
validate_cursor_key(k, error_type=ValueError)
|
|
215
|
+
validate_cursor_value(v)
|
|
216
|
+
if spawned_job_snapshots:
|
|
217
|
+
validate_queue_replacement(list(spawned_job_snapshots))
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def validate_running_settlement_state(
|
|
221
|
+
job_uid: str,
|
|
222
|
+
*,
|
|
223
|
+
present_in_queue: bool,
|
|
224
|
+
queue_status: str | None,
|
|
225
|
+
queue_run_id: str | None,
|
|
226
|
+
queue_attempt_no: int | None,
|
|
227
|
+
queue_execution_id: str | None,
|
|
228
|
+
run_id: str,
|
|
229
|
+
attempt_no: int,
|
|
230
|
+
execution_id: str,
|
|
231
|
+
already_settled: bool,
|
|
232
|
+
) -> None:
|
|
233
|
+
"""校验待结算执行与队列 running 身份严格匹配且对应 attempt 尚未结算。"""
|
|
234
|
+
if (
|
|
235
|
+
not present_in_queue
|
|
236
|
+
or (queue_status, queue_run_id, queue_attempt_no, queue_execution_id)
|
|
237
|
+
!= ("running", run_id, attempt_no, execution_id)
|
|
238
|
+
):
|
|
239
|
+
raise TaskLiteError(f"Settlement does not match the running execution for {job_uid}")
|
|
240
|
+
if already_settled:
|
|
241
|
+
raise TaskLiteError(f"Execution for {job_uid} attempt {attempt_no} is already settled")
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def normalize_authorization_path(path: str | os.PathLike[str]) -> str:
|
|
245
|
+
"""规范化后端路径授权存储主键。"""
|
|
246
|
+
return os.path.normpath(os.fspath(path))
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def is_valid_authorization_target_type(target_type: Any) -> bool:
|
|
250
|
+
"""判断路径授权目标类型是否为合法的 'file' 或 'directory'。"""
|
|
251
|
+
return target_type in ("file", "directory")
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def validate_authorization_target_type(
|
|
255
|
+
target_type: Any, *, error_type: type[Exception] = ValueError
|
|
256
|
+
) -> TargetType:
|
|
257
|
+
"""校验路径授权目标类型并返回类型收窄结果。"""
|
|
258
|
+
if not is_valid_authorization_target_type(target_type):
|
|
259
|
+
raise error_type(f"target_type must be 'file' or 'directory', got {target_type!r}")
|
|
260
|
+
return cast(TargetType, target_type)
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def resolve_authorized_at(authorized_at: str | None) -> str:
|
|
264
|
+
"""解析路径授权时间戳,缺省回填当前 UTC ISO 串。"""
|
|
265
|
+
return authorized_at if authorized_at is not None else utc_now_iso()
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def validate_graph_edit_commit(commit: Any) -> bool:
|
|
269
|
+
"""校验 GraphEditCommit 前置结构契约;若为空提交返回 False,否则返回 True。
|
|
270
|
+
|
|
271
|
+
SQLite 与 Memory 双后端同源调用,确保类型错误、重复恢复载荷或缺失队列写变
|
|
272
|
+
在进入任何写事务前 fail-loud 拒绝。
|
|
273
|
+
"""
|
|
274
|
+
if not isinstance(commit, GraphEditCommit):
|
|
275
|
+
raise TypeError(f"commit must be a GraphEditCommit, got {type(commit).__name__}")
|
|
276
|
+
if (
|
|
277
|
+
not commit.queue_writes
|
|
278
|
+
and not commit.success_writes
|
|
279
|
+
and not commit.failed_writes
|
|
280
|
+
and not commit.recovery_attempts
|
|
281
|
+
):
|
|
282
|
+
return False
|
|
283
|
+
|
|
284
|
+
seen_recovery: set[str] = set()
|
|
285
|
+
for rec in commit.recovery_attempts:
|
|
286
|
+
if not isinstance(rec, RunningAttemptRecovery):
|
|
287
|
+
raise TypeError(
|
|
288
|
+
f"recovery_attempts items must be RunningAttemptRecovery, got {type(rec).__name__}"
|
|
289
|
+
)
|
|
290
|
+
if rec.job_uid in seen_recovery:
|
|
291
|
+
raise TaskLiteError(
|
|
292
|
+
f"Duplicate recovery attempt for running job {rec.job_uid!r}"
|
|
293
|
+
)
|
|
294
|
+
seen_recovery.add(rec.job_uid)
|
|
295
|
+
if rec.job_uid not in commit.queue_writes:
|
|
296
|
+
raise TaskLiteError(
|
|
297
|
+
f"Recovery attempt for {rec.job_uid!r} must also update or remove its queue row"
|
|
298
|
+
)
|
|
299
|
+
return True
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def validate_recovery_attempt_state(
|
|
303
|
+
rec: RunningAttemptRecovery,
|
|
304
|
+
*,
|
|
305
|
+
present_in_queue: bool,
|
|
306
|
+
queue_status: str | None,
|
|
307
|
+
queue_run_id: str | None,
|
|
308
|
+
queue_attempt_no: int | None,
|
|
309
|
+
queue_execution_id: str | None,
|
|
310
|
+
attempt_sequence: int | None,
|
|
311
|
+
already_settled: bool,
|
|
312
|
+
) -> None:
|
|
313
|
+
"""校验遗留 running 恢复载荷与后端当前执行身份、序号进度及结算态的一致性。"""
|
|
314
|
+
if not present_in_queue:
|
|
315
|
+
raise TaskLiteError(
|
|
316
|
+
f"Recovery target {rec.job_uid!r} is no longer present in queue"
|
|
317
|
+
)
|
|
318
|
+
if (
|
|
319
|
+
queue_status,
|
|
320
|
+
queue_run_id,
|
|
321
|
+
queue_attempt_no,
|
|
322
|
+
queue_execution_id,
|
|
323
|
+
) != ("running", rec.run_id, rec.attempt_no, rec.execution_id):
|
|
324
|
+
raise TaskLiteError(
|
|
325
|
+
f"Recovery attempt does not match the running execution for {rec.job_uid!r}"
|
|
326
|
+
)
|
|
327
|
+
if attempt_sequence is None or attempt_sequence != rec.attempt_no:
|
|
328
|
+
raise TaskLiteError(
|
|
329
|
+
f"Recovery attempt sequence mismatch for {rec.job_uid!r}"
|
|
330
|
+
)
|
|
331
|
+
if already_settled:
|
|
332
|
+
raise TaskLiteError(
|
|
333
|
+
f"Execution for {rec.job_uid!r} attempt {rec.attempt_no} is already settled"
|
|
334
|
+
)
|
|
335
|
+
|
|
336
|
+
|
|
72
337
|
class AbstractStateBackend(ABC):
|
|
73
338
|
"""SQLite 与 Memory 共用的内部持久化 Interface。
|
|
74
339
|
|
|
75
|
-
当前执行只经 commit_job_settlement
|
|
76
|
-
|
|
77
|
-
|
|
340
|
+
当前执行只经 ``commit_job_settlement`` 追加结算;执行前/批量失败与
|
|
341
|
+
候选移除各自原子提交;独占执行权由后端经 ``exclusive_access`` 自治。
|
|
342
|
+
写入故障原样传播,调用方提交成功后才发布内存;历史清理不触碰编号进度。
|
|
78
343
|
"""
|
|
79
344
|
|
|
80
|
-
|
|
345
|
+
# 独占执行权 -----------------------------------------------------
|
|
346
|
+
|
|
347
|
+
@abstractmethod
|
|
348
|
+
def exclusive_access(self) -> AbstractContextManager[None]:
|
|
349
|
+
"""非阻塞取得本后端独占执行权,离开作用域时归还本次取得的锁。"""
|
|
81
350
|
|
|
82
351
|
# 全量加载 -------------------------------------------------------
|
|
83
352
|
|
|
@@ -89,100 +358,20 @@ class AbstractStateBackend(ABC):
|
|
|
89
358
|
def load_failed(self) -> dict[str, dict[str, Any]]:
|
|
90
359
|
"""加载全部失败档案终态(uid → 失败 meta)。"""
|
|
91
360
|
|
|
92
|
-
@abstractmethod
|
|
93
|
-
def load_failure_payloads(self) -> dict[str, dict[str, Any]]:
|
|
94
|
-
"""读取失败档案各 uid 的原始业务 payload 快照(无快照的 uid 不出现)。"""
|
|
95
|
-
|
|
96
361
|
@abstractmethod
|
|
97
362
|
def load_cursors(self) -> dict[str, str]:
|
|
98
363
|
"""加载全部游标(key → value)。"""
|
|
99
364
|
|
|
100
|
-
@abstractmethod
|
|
101
|
-
def load_queue(self) -> list[dict[str, Any]]:
|
|
102
|
-
"""按 queue_position 升序加载磁盘队列真相。"""
|
|
103
|
-
|
|
104
|
-
@abstractmethod
|
|
105
|
-
def load_known_job_snapshot(self, uid: str) -> dict[str, Any] | None:
|
|
106
|
-
"""读取单个已知 Job 的完整配置快照。
|
|
107
|
-
|
|
108
|
-
优先级固定为队列(含 running)、successes、failed、Attempt 历史。
|
|
109
|
-
找不到时返回 None;读取或解码故障必须原样传播。
|
|
110
|
-
"""
|
|
111
|
-
|
|
112
|
-
@abstractmethod
|
|
113
|
-
def load_known_job_snapshots(self) -> dict[str, dict[str, Any]]:
|
|
114
|
-
"""读取全部已知 Job 的完整配置快照映射。
|
|
115
|
-
|
|
116
|
-
同一 UID 按队列(含 running)、successes、failed、Attempt 历史的
|
|
117
|
-
优先级选取。读取或解码故障必须原样传播。
|
|
118
|
-
"""
|
|
119
|
-
|
|
120
|
-
# 整表重写 -------------------------------------------------------
|
|
121
|
-
|
|
122
|
-
@abstractmethod
|
|
123
|
-
def save_queue(self, job_snapshots: list[dict[str, Any]]) -> None:
|
|
124
|
-
"""整表重写队列(测试装配 / replace_queue_atomic 的事务内步骤)。
|
|
125
|
-
|
|
126
|
-
红线:这是「无读基准的整表覆盖」——跨进程并发的 enqueue/commit
|
|
127
|
-
若提交在本方法执行前的任意时刻,其已落盘行会被无条件抹除。进程内
|
|
128
|
-
任何「先读磁盘真相再决定写什么」的合并保存(崩溃恢复路径)严禁
|
|
129
|
-
直接调用本方法,必须走 ``replace_queue_atomic`` 把读-改-写收敛进
|
|
130
|
-
单个写事务。
|
|
131
|
-
|
|
132
|
-
替换集经 ``validate_queue_replacement`` 在写变前校验:None / 非序列 /
|
|
133
|
-
元素非 dict 抛 TypeError,队列保持调用前状态(双腿一致)。
|
|
134
|
-
"""
|
|
135
|
-
|
|
136
|
-
@abstractmethod
|
|
137
|
-
def replace_queue_atomic(
|
|
138
|
-
self,
|
|
139
|
-
compute: Callable[[list[dict[str, Any]]], list[dict[str, Any]]],
|
|
140
|
-
) -> None:
|
|
141
|
-
"""读-改-写收敛的整表替换:磁盘真相读取与写回在单个写事务内完成。
|
|
142
|
-
|
|
143
|
-
``compute`` 在写锁内接收按序排列的磁盘队列快照,返回替换后的完整
|
|
144
|
-
队列。不变式:并发方(跨进程 enqueue / delta commit)要么先于本
|
|
145
|
-
事务提交(其行进入磁盘真相、参与合并,绝不丢失),要么排队等本
|
|
146
|
-
事务提交后再落盘——「读真相 → 计算 → 写回」之间不存在无锁窗口,
|
|
147
|
-
陈旧快照永远无法覆盖窗口期他进程已应答的新写入。
|
|
148
|
-
|
|
149
|
-
``compute`` 必须是纯计算(锁内执行,不得调用任何后端写方法,否则
|
|
150
|
-
跨连接写请求会以写锁互斥死等)。单事务原子:``compute`` 抛异常或
|
|
151
|
-
写失败时整体回滚,磁盘保持调用前状态,异常向外传播。``compute``
|
|
152
|
-
返回的替换集经 ``validate_queue_replacement`` 在写变前校验(None /
|
|
153
|
-
非序列 / 元素非 dict 抛 TypeError,双腿一致,磁盘保持原状)。
|
|
154
|
-
"""
|
|
155
|
-
|
|
156
365
|
# delta 提交 -----------------------------------------------------
|
|
157
366
|
|
|
158
|
-
|
|
159
367
|
@abstractmethod
|
|
160
|
-
def
|
|
161
|
-
|
|
162
|
-
job_uid: str,
|
|
163
|
-
failure_metadata: dict,
|
|
164
|
-
payload: dict[str, Any] | None = None,
|
|
165
|
-
) -> bool:
|
|
166
|
-
"""原子持久化一个失败 job 的 delta(写入失败档案)。
|
|
167
|
-
|
|
168
|
-
单事务效果:failed INSERT/REPLACE uid → failure_metadata;
|
|
169
|
-
queue DELETE uid;successes DELETE 同名行——重跑任务重试耗尽时旧成功
|
|
170
|
-
记录作废(最终状态唯一),否则磁盘 successes∩failed 并存破坏互斥。
|
|
171
|
-
``payload`` 是原始业务输入快照(补跑自足,无需外部反查);
|
|
172
|
-
None 表示本路径无可存快照,保留既有快照不覆盖。
|
|
173
|
-
成功返回 True;写入故障原样传播,失败时后端保持调用前状态。
|
|
174
|
-
"""
|
|
175
|
-
|
|
368
|
+
def commit_job_failures(self, entries: Sequence[FailureEntry]) -> None:
|
|
369
|
+
"""原子批量写失败档案(单条执行前拒绝 / 死锁 / 级联共用单一原语)。
|
|
176
370
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
单事务效果:failed INSERT/REPLACE 每个 uid → metadata;
|
|
182
|
-
queue 按 uid 精准 DELETE(剩余条目保持原顺序);
|
|
183
|
-
successes 批量 DELETE 同名行(与 commit_job_failure 对称的最终状态唯一)。
|
|
184
|
-
任一行失败 ⇒ 整体回滚并原样抛出异常,绝不留下「队列已删、档案未落」
|
|
185
|
-
的半成品失败态。
|
|
371
|
+
每项为 ``(job_uid, failure_metadata)`` 或 ``(job_uid, failure_metadata, payload)``:
|
|
372
|
+
单事务效果为 failed INSERT/REPLACE(``payload=None`` 保留既有快照不覆盖)、
|
|
373
|
+
queue 按 uid 精准 DELETE(剩余条目保持原顺序)、successes 批量 DELETE 同名行
|
|
374
|
+
(维护 ``successes ∩ failed == ∅``)。空序列幂等无操作;任一行失败则整体回滚并上抛。
|
|
186
375
|
"""
|
|
187
376
|
|
|
188
377
|
@abstractmethod
|
|
@@ -193,65 +382,25 @@ class AbstractStateBackend(ABC):
|
|
|
193
382
|
成功无返回值;失败时队列不变,原始异常继续传播。
|
|
194
383
|
"""
|
|
195
384
|
|
|
196
|
-
|
|
197
385
|
# 增量入队 -------------------------------------------------------
|
|
198
386
|
|
|
199
387
|
@abstractmethod
|
|
200
388
|
def enqueue_jobs(self, job_snapshots: list[dict[str, Any]], *, front: bool = False) -> list[str]:
|
|
201
389
|
"""批量增量入队:按 front 在队列头/尾插入 job_snapshots(保序),单事务原子。
|
|
202
390
|
|
|
203
|
-
跳过与现有队列重复的 uid
|
|
204
|
-
|
|
205
|
-
run() 的 delta commit 与该入队并发时,不会因全量 save_queue 覆盖而
|
|
206
|
-
丢失 run() 已提交的变更(写入侧不覆盖,读-改-写窗口仍由
|
|
207
|
-
``replace_queue_atomic`` 收敛)。失败时事务回滚并抛异常(不吞)。
|
|
391
|
+
跳过与现有队列重复的 uid(含批次内重复,首个存储),返回实际插入的 uid 列表;
|
|
392
|
+
不做全表覆盖,失败时事务回滚并原样抛异常。
|
|
208
393
|
"""
|
|
209
394
|
|
|
210
|
-
#
|
|
395
|
+
# 管理写、一致快照与游标 -----------------------------------------
|
|
211
396
|
|
|
212
397
|
@abstractmethod
|
|
213
|
-
def
|
|
214
|
-
"""
|
|
215
|
-
|
|
216
|
-
与 save_queue 的全表重写相对:只 DELETE 指定 uid 的行,其余行原样
|
|
217
|
-
保留。不变式:删除集在调用前确定,不在删除集内的行(含并发进程
|
|
218
|
-
刚入队的新行)无论与本事务先后提交都必然存活——陈旧加载快照永远
|
|
219
|
-
不会覆盖他进程的新写入。单事务原子;失败抛异常(不吞),磁盘保持
|
|
220
|
-
调用前状态(残留行由下次加载重新判定,天然幂等)。返回实际删除行数。
|
|
221
|
-
"""
|
|
398
|
+
def load_consistent_snapshot(self) -> dict[str, Any]:
|
|
399
|
+
"""在单一读事务或单锁内原子捕获一致状态快照(含 queue_jobs/successes/failed/failure_payloads/cursors/attempts/job_sequences)。"""
|
|
222
400
|
|
|
223
401
|
@abstractmethod
|
|
224
|
-
def
|
|
225
|
-
"""
|
|
226
|
-
|
|
227
|
-
返回实际删除行数(连带清除 payload 快照)。不触碰 queue/successes。
|
|
228
|
-
仅限 run() 之外调用(改变 is_known 判定基础,与 enqueue 同纪律)。
|
|
229
|
-
"""
|
|
230
|
-
|
|
231
|
-
@abstractmethod
|
|
232
|
-
def delete_successes(self, job_uids: list[str]) -> int:
|
|
233
|
-
"""从 successes 批量删除指定 uid(clear_history 的后端实现 + commit 路径事务内清理)。
|
|
234
|
-
|
|
235
|
-
两种调用上下文:
|
|
236
|
-
- 运行外管理 API 的批量删除;
|
|
237
|
-
- commit_job_failure / commit_job_failures 的同一事务内逐 uid 删除
|
|
238
|
-
(重跑任务重跑失败时 successes 旧记录作废,最终状态唯一)。
|
|
239
|
-
|
|
240
|
-
运行中的调用仅限 commit 事务内部(随失败档案写入原子提交,不改变
|
|
241
|
-
进行中的派发判定);独立调用仅限 run 之外(改变 is_known 判定
|
|
242
|
-
基础,与 enqueue 同纪律)。
|
|
243
|
-
"""
|
|
244
|
-
|
|
245
|
-
@abstractmethod
|
|
246
|
-
def apply_manual_status(
|
|
247
|
-
self,
|
|
248
|
-
updates: Sequence[tuple[str, str, dict[str, Any], dict[str, Any] | None]],
|
|
249
|
-
) -> None:
|
|
250
|
-
"""批量原子应用人工状态变更 (job_uid, status, snapshot, metadata)。"""
|
|
251
|
-
|
|
252
|
-
@abstractmethod
|
|
253
|
-
def clear_history(self, uid: str, records: set[str]) -> int:
|
|
254
|
-
"""从 successes/failed/attempts 清除指定 job_uid 的记录,返回删除条数。"""
|
|
402
|
+
def commit_graph_edit(self, commit: GraphEditCommit) -> None:
|
|
403
|
+
"""在单一写事务或锁内原子应用声明式图修整变更,绝不删除 attempts 或重置 job_sequences。"""
|
|
255
404
|
|
|
256
405
|
@abstractmethod
|
|
257
406
|
def get_cursor(self, key: str) -> str | None:
|
|
@@ -263,17 +412,12 @@ class AbstractStateBackend(ABC):
|
|
|
263
412
|
|
|
264
413
|
# 尝试轨迹(append-only 旁路观测面)--------------------------------
|
|
265
414
|
|
|
266
|
-
|
|
267
415
|
@abstractmethod
|
|
268
416
|
def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
|
|
269
417
|
"""读取指定 Job 最新一条 success Attempt 的 settled_at;无则返回 None。"""
|
|
270
418
|
|
|
271
419
|
# 元数据 ---------------------------------------------------------
|
|
272
420
|
|
|
273
|
-
@abstractmethod
|
|
274
|
-
def get_engine_metadata(self, key: str) -> str | None:
|
|
275
|
-
"""读取一条框架级元数据(如 fencing 的 last_run_id)。无则返回 None。"""
|
|
276
|
-
|
|
277
421
|
@abstractmethod
|
|
278
422
|
def set_engine_metadata(self, key: str, value: str) -> None:
|
|
279
423
|
"""写入一条框架级元数据(UPSERT 语义)。失败抛异常(不吞)。"""
|
|
@@ -323,14 +467,20 @@ class AbstractStateBackend(ABC):
|
|
|
323
467
|
def load_settled_attempts(self, job_uid: str) -> list[dict[str, Any]]:
|
|
324
468
|
"""按 attempt_no 升序读取指定 job_uid 的全部已结算 Attempt 记录。"""
|
|
325
469
|
|
|
326
|
-
@abstractmethod
|
|
327
|
-
def clear_attempts(self, job_uid: str) -> int:
|
|
328
|
-
"""删除指定 job_uid 的 Attempt 历史(不影响 job_sequences 编号进度)。"""
|
|
329
|
-
|
|
330
470
|
@abstractmethod
|
|
331
471
|
def load_queue_jobs(self, *, status: str | None = None) -> list[dict[str, Any]]:
|
|
332
472
|
"""按 queue_position 升序加载队列行的完整信息,可选按 status 过滤。"""
|
|
333
473
|
|
|
474
|
+
@abstractmethod
|
|
475
|
+
def grant_authorization(
|
|
476
|
+
self,
|
|
477
|
+
path: str,
|
|
478
|
+
target_type: Literal["file", "directory"],
|
|
479
|
+
*,
|
|
480
|
+
authorized_at: str | None = None,
|
|
481
|
+
) -> dict[str, Any]:
|
|
482
|
+
"""原子校验冲突并新增持久化路径授权(重复或父子类型冲突抛 TaskLiteError)。"""
|
|
483
|
+
|
|
334
484
|
@abstractmethod
|
|
335
485
|
def record_authorization(
|
|
336
486
|
self,
|
|
@@ -359,5 +509,26 @@ class AbstractStateBackend(ABC):
|
|
|
359
509
|
|
|
360
510
|
__all__ = [
|
|
361
511
|
"AbstractStateBackend",
|
|
512
|
+
"FailureEntry",
|
|
513
|
+
"GraphEditCommit",
|
|
514
|
+
"QUEUE_EXECUTION_ID_KEY",
|
|
515
|
+
"RunningAttemptRecovery",
|
|
516
|
+
"execution_id_matches_run",
|
|
517
|
+
"is_valid_authorization_target_type",
|
|
518
|
+
"normalize_authorization_path",
|
|
519
|
+
"normalize_failure_entries",
|
|
520
|
+
"public_queue_snapshot",
|
|
521
|
+
"queue_snapshot_execution_id",
|
|
522
|
+
"queue_snapshot_with_execution_id",
|
|
523
|
+
"resolve_authorized_at",
|
|
524
|
+
"validate_authorization_target_type",
|
|
525
|
+
"validate_cursor_key",
|
|
526
|
+
"validate_cursor_value",
|
|
527
|
+
"validate_graph_edit_commit",
|
|
528
|
+
"validate_mark_job_running_args",
|
|
529
|
+
"validate_mark_job_running_state",
|
|
362
530
|
"validate_queue_replacement",
|
|
531
|
+
"validate_recovery_attempt_state",
|
|
532
|
+
"validate_running_settlement_state",
|
|
533
|
+
"validate_settlement_args",
|
|
363
534
|
]
|