pytest-state-guard 0.1.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.
- pytest_state_guard/__init__.py +4 -0
- pytest_state_guard/executor.py +208 -0
- pytest_state_guard/ledger.py +413 -0
- pytest_state_guard/models.py +220 -0
- pytest_state_guard/owners.py +93 -0
- pytest_state_guard/plugin.py +678 -0
- pytest_state_guard/policy.py +434 -0
- pytest_state_guard/py.typed +0 -0
- pytest_state_guard/reporting.py +138 -0
- pytest_state_guard-0.1.0.dist-info/METADATA +275 -0
- pytest_state_guard-0.1.0.dist-info/RECORD +15 -0
- pytest_state_guard-0.1.0.dist-info/WHEEL +5 -0
- pytest_state_guard-0.1.0.dist-info/entry_points.txt +2 -0
- pytest_state_guard-0.1.0.dist-info/licenses/LICENSE +21 -0
- pytest_state_guard-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import threading
|
|
4
|
+
import uuid
|
|
5
|
+
from concurrent.futures import Future, ThreadPoolExecutor
|
|
6
|
+
from typing import Any, Callable
|
|
7
|
+
|
|
8
|
+
from pytest_state_guard.ledger import Ledger
|
|
9
|
+
from pytest_state_guard.models import CallableState, FutureState
|
|
10
|
+
from pytest_state_guard.owners import (
|
|
11
|
+
OwnerContext,
|
|
12
|
+
execution_context,
|
|
13
|
+
get_current_owner,
|
|
14
|
+
get_current_task_id,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
_PATCH_LOCK = threading.Lock()
|
|
18
|
+
_REAL_ORIGINAL_SUBMIT: Callable[..., Any] = ThreadPoolExecutor.submit
|
|
19
|
+
_ACTIVE_LEDGER: Ledger | None = None
|
|
20
|
+
_IS_PATCHED = False
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _safe_exception_metadata(exc: BaseException) -> tuple[str, str | None]:
|
|
24
|
+
"""Safely extract exception type and message without risking user __str__() failures."""
|
|
25
|
+
exc_type = type(exc).__qualname__
|
|
26
|
+
try:
|
|
27
|
+
msg = str(exc)
|
|
28
|
+
exc_msg = msg if type(msg) is str else None
|
|
29
|
+
except BaseException:
|
|
30
|
+
exc_msg = "<exception formatting raised>"
|
|
31
|
+
return exc_type, exc_msg
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class _CallableWrapper:
|
|
35
|
+
"""Wraps user callable to track execution lifecycle and establish worker context."""
|
|
36
|
+
|
|
37
|
+
def __init__(
|
|
38
|
+
self,
|
|
39
|
+
fn: Callable[..., Any],
|
|
40
|
+
task_id: str,
|
|
41
|
+
owner: OwnerContext,
|
|
42
|
+
ledger: Ledger,
|
|
43
|
+
) -> None:
|
|
44
|
+
self._fn = fn
|
|
45
|
+
self._task_id = task_id
|
|
46
|
+
self._owner = owner
|
|
47
|
+
self._ledger = ledger
|
|
48
|
+
|
|
49
|
+
def __call__(self, *args: Any, **kwargs: Any) -> Any:
|
|
50
|
+
with execution_context(self._owner, self._task_id):
|
|
51
|
+
try:
|
|
52
|
+
self._ledger.commit_callable_started(self._task_id)
|
|
53
|
+
except Exception:
|
|
54
|
+
# Fail-open: do not prevent user work from executing
|
|
55
|
+
pass
|
|
56
|
+
|
|
57
|
+
outcome = CallableState.EXITED_RETURNED
|
|
58
|
+
exc_type: str | None = None
|
|
59
|
+
exc_msg: str | None = None
|
|
60
|
+
|
|
61
|
+
try:
|
|
62
|
+
return self._fn(*args, **kwargs)
|
|
63
|
+
except BaseException as exc:
|
|
64
|
+
outcome = CallableState.EXITED_RAISED
|
|
65
|
+
exc_type, exc_msg = _safe_exception_metadata(exc)
|
|
66
|
+
raise
|
|
67
|
+
finally:
|
|
68
|
+
try:
|
|
69
|
+
self._ledger.commit_callable_exited(
|
|
70
|
+
self._task_id,
|
|
71
|
+
outcome=outcome,
|
|
72
|
+
exception_type=exc_type,
|
|
73
|
+
exception_message=exc_msg,
|
|
74
|
+
)
|
|
75
|
+
except Exception:
|
|
76
|
+
# Do not let instrumentation error mask in-flight user exception
|
|
77
|
+
pass
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class _FutureCallback:
|
|
81
|
+
"""Callback attached to Future to observe settlement."""
|
|
82
|
+
|
|
83
|
+
def __init__(self, task_id: str, ledger: Ledger) -> None:
|
|
84
|
+
self._task_id = task_id
|
|
85
|
+
self._ledger = ledger
|
|
86
|
+
|
|
87
|
+
def __call__(self, future: Future[Any]) -> None:
|
|
88
|
+
try:
|
|
89
|
+
if future.cancelled():
|
|
90
|
+
terminal_state = FutureState.CANCELLED
|
|
91
|
+
else:
|
|
92
|
+
terminal_state = FutureState.FINISHED
|
|
93
|
+
self._ledger.commit_future_done(self._task_id, terminal_state)
|
|
94
|
+
except Exception:
|
|
95
|
+
# Future callback exceptions are isolated; do not affect user Future status
|
|
96
|
+
pass
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _state_guard_submit(
|
|
100
|
+
self: ThreadPoolExecutor,
|
|
101
|
+
fn: Callable[..., Any],
|
|
102
|
+
*args: Any,
|
|
103
|
+
**kwargs: Any,
|
|
104
|
+
) -> Future[Any]:
|
|
105
|
+
"""Intercepts ThreadPoolExecutor.submit to track task lifecycles under active owners."""
|
|
106
|
+
ledger = _ACTIVE_LEDGER
|
|
107
|
+
owner = get_current_owner()
|
|
108
|
+
|
|
109
|
+
# Unowned submission or inactive ledger: minimal overhead direct pass-through
|
|
110
|
+
if ledger is None or owner is None:
|
|
111
|
+
return _REAL_ORIGINAL_SUBMIT(self, fn, *args, **kwargs)
|
|
112
|
+
|
|
113
|
+
# Generate collision-resistant full UUID task ID
|
|
114
|
+
task_id = f"task:{uuid.uuid4().hex}"
|
|
115
|
+
parent_task_id = get_current_task_id()
|
|
116
|
+
|
|
117
|
+
# Step 1: Pre-submission reservation
|
|
118
|
+
try:
|
|
119
|
+
ledger.reserve_task(task_id, owner.owner_id, parent_task_id=parent_task_id)
|
|
120
|
+
except Exception:
|
|
121
|
+
# Fail-open: execute uninstrumented rather than breaking user submission
|
|
122
|
+
return _REAL_ORIGINAL_SUBMIT(self, fn, *args, **kwargs)
|
|
123
|
+
|
|
124
|
+
# Step 2: Wrap user callable
|
|
125
|
+
wrapped_fn = _CallableWrapper(fn, task_id, owner, ledger)
|
|
126
|
+
|
|
127
|
+
# Step 3: Invoke original submit
|
|
128
|
+
try:
|
|
129
|
+
future = _REAL_ORIGINAL_SUBMIT(self, wrapped_fn, *args, **kwargs)
|
|
130
|
+
except BaseException as submit_exc:
|
|
131
|
+
exc_type, exc_msg = _safe_exception_metadata(submit_exc)
|
|
132
|
+
try:
|
|
133
|
+
ledger.commit_submit_raised(
|
|
134
|
+
task_id,
|
|
135
|
+
exception_type=exc_type,
|
|
136
|
+
exception_message=exc_msg,
|
|
137
|
+
)
|
|
138
|
+
except Exception:
|
|
139
|
+
pass
|
|
140
|
+
raise # Re-raise original exception unchanged
|
|
141
|
+
|
|
142
|
+
# Step 4: Record submit returned
|
|
143
|
+
try:
|
|
144
|
+
ledger.commit_submit_returned(task_id)
|
|
145
|
+
except Exception:
|
|
146
|
+
pass
|
|
147
|
+
|
|
148
|
+
# Step 5: Attach done callback
|
|
149
|
+
try:
|
|
150
|
+
future.add_done_callback(_FutureCallback(task_id, ledger))
|
|
151
|
+
except Exception:
|
|
152
|
+
pass
|
|
153
|
+
|
|
154
|
+
return future
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def install_patch(ledger: Ledger) -> None:
|
|
158
|
+
"""Install ThreadPoolExecutor.submit monkeypatch.
|
|
159
|
+
|
|
160
|
+
Thread-safe and idempotent for the same ledger.
|
|
161
|
+
Raises RuntimeError if already patched with a different ledger.
|
|
162
|
+
"""
|
|
163
|
+
global _ACTIVE_LEDGER, _IS_PATCHED
|
|
164
|
+
|
|
165
|
+
with _PATCH_LOCK:
|
|
166
|
+
if _IS_PATCHED:
|
|
167
|
+
if _ACTIVE_LEDGER is ledger:
|
|
168
|
+
return
|
|
169
|
+
raise RuntimeError(
|
|
170
|
+
"State Guard ThreadPoolExecutor patch is already active with a different ledger"
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
ThreadPoolExecutor.submit = _state_guard_submit # type: ignore[method-assign]
|
|
174
|
+
_ACTIVE_LEDGER = ledger
|
|
175
|
+
_IS_PATCHED = True
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def remove_patch() -> None:
|
|
179
|
+
"""Restore original ThreadPoolExecutor.submit.
|
|
180
|
+
|
|
181
|
+
Safely handles foreign wrappers: if ThreadPoolExecutor.submit was wrapped
|
|
182
|
+
by another library after State Guard, leaves the pointer untouched and
|
|
183
|
+
disables interception via _ACTIVE_LEDGER = None.
|
|
184
|
+
"""
|
|
185
|
+
global _ACTIVE_LEDGER, _IS_PATCHED
|
|
186
|
+
|
|
187
|
+
with _PATCH_LOCK:
|
|
188
|
+
if not _IS_PATCHED:
|
|
189
|
+
return
|
|
190
|
+
|
|
191
|
+
# Check if our wrapper is still the top-level method
|
|
192
|
+
if getattr(ThreadPoolExecutor, "submit", None) is _state_guard_submit:
|
|
193
|
+
ThreadPoolExecutor.submit = _REAL_ORIGINAL_SUBMIT # type: ignore[method-assign]
|
|
194
|
+
|
|
195
|
+
_ACTIVE_LEDGER = None
|
|
196
|
+
_IS_PATCHED = False
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def is_patched() -> bool:
|
|
200
|
+
"""Return True if State Guard patch is currently active."""
|
|
201
|
+
with _PATCH_LOCK:
|
|
202
|
+
return _IS_PATCHED
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def get_active_ledger() -> Ledger | None:
|
|
206
|
+
"""Return the active ledger associated with the current patch, if any."""
|
|
207
|
+
with _PATCH_LOCK:
|
|
208
|
+
return _ACTIVE_LEDGER
|
|
@@ -0,0 +1,413 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import dataclasses
|
|
4
|
+
import itertools
|
|
5
|
+
import threading
|
|
6
|
+
import time
|
|
7
|
+
from typing import Any, Mapping
|
|
8
|
+
|
|
9
|
+
from pytest_state_guard.models import (
|
|
10
|
+
CallableState,
|
|
11
|
+
DuplicateEntityError,
|
|
12
|
+
EntityNotFoundError,
|
|
13
|
+
EventRecord,
|
|
14
|
+
EventType,
|
|
15
|
+
FutureState,
|
|
16
|
+
InvalidTransitionError,
|
|
17
|
+
OwnerRecord,
|
|
18
|
+
OwnerState,
|
|
19
|
+
OwnerType,
|
|
20
|
+
SubmissionState,
|
|
21
|
+
TaskRecord,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class Ledger:
|
|
26
|
+
"""Thread-safe synchronized event ledger.
|
|
27
|
+
|
|
28
|
+
Serializes all lifecycle commits under a single non-reentrant lock.
|
|
29
|
+
Maintains an append-only event history alongside immutable point-in-time
|
|
30
|
+
owner and task records.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
def __init__(self) -> None:
|
|
34
|
+
self._lock = threading.Lock()
|
|
35
|
+
self._seq_counter = itertools.count(1)
|
|
36
|
+
self._events: list[EventRecord] = []
|
|
37
|
+
self._owners: dict[str, OwnerRecord] = {}
|
|
38
|
+
self._tasks: dict[str, TaskRecord] = {}
|
|
39
|
+
|
|
40
|
+
# -----------------------------------------------------------------------
|
|
41
|
+
# Internal Locked Helpers
|
|
42
|
+
# -----------------------------------------------------------------------
|
|
43
|
+
|
|
44
|
+
def _commit_event_locked(
|
|
45
|
+
self,
|
|
46
|
+
event_type: EventType,
|
|
47
|
+
owner_id: str,
|
|
48
|
+
task_id: str | None = None,
|
|
49
|
+
details: Mapping[str, Any] | None = None,
|
|
50
|
+
) -> EventRecord:
|
|
51
|
+
"""Allocate seq_id and timestamp, append to history, and return event.
|
|
52
|
+
|
|
53
|
+
MUST be invoked while holding self._lock.
|
|
54
|
+
"""
|
|
55
|
+
ts_ns = time.monotonic_ns()
|
|
56
|
+
seq_id = next(self._seq_counter)
|
|
57
|
+
thread_id = threading.get_ident()
|
|
58
|
+
|
|
59
|
+
event = EventRecord(
|
|
60
|
+
seq_id=seq_id,
|
|
61
|
+
ts_ns=ts_ns,
|
|
62
|
+
event_type=event_type,
|
|
63
|
+
owner_id=owner_id,
|
|
64
|
+
task_id=task_id,
|
|
65
|
+
thread_id=thread_id,
|
|
66
|
+
details=details,
|
|
67
|
+
)
|
|
68
|
+
self._events.append(event)
|
|
69
|
+
return event
|
|
70
|
+
|
|
71
|
+
# -----------------------------------------------------------------------
|
|
72
|
+
# Owner Lifecycle Commits
|
|
73
|
+
# -----------------------------------------------------------------------
|
|
74
|
+
|
|
75
|
+
def create_owner(
|
|
76
|
+
self,
|
|
77
|
+
owner_id: str,
|
|
78
|
+
owner_type: OwnerType,
|
|
79
|
+
nodeid: str,
|
|
80
|
+
fixture_name: str | None = None,
|
|
81
|
+
) -> OwnerRecord:
|
|
82
|
+
"""Register a new active owner."""
|
|
83
|
+
with self._lock:
|
|
84
|
+
if owner_id in self._owners:
|
|
85
|
+
raise DuplicateEntityError(f"Owner '{owner_id}' already exists")
|
|
86
|
+
|
|
87
|
+
ev = self._commit_event_locked(
|
|
88
|
+
event_type=EventType.OWNER_CREATED,
|
|
89
|
+
owner_id=owner_id,
|
|
90
|
+
details={"owner_type": owner_type.value, "nodeid": nodeid},
|
|
91
|
+
)
|
|
92
|
+
owner = OwnerRecord(
|
|
93
|
+
owner_id=owner_id,
|
|
94
|
+
owner_type=owner_type,
|
|
95
|
+
nodeid=nodeid,
|
|
96
|
+
created_seq=ev.seq_id,
|
|
97
|
+
state=OwnerState.ACTIVE,
|
|
98
|
+
fixture_name=fixture_name,
|
|
99
|
+
)
|
|
100
|
+
self._owners[owner_id] = owner
|
|
101
|
+
return owner
|
|
102
|
+
|
|
103
|
+
def finalize_owner(self, owner_id: str) -> OwnerRecord:
|
|
104
|
+
"""Commit owner finalization (irreversible one-way transition)."""
|
|
105
|
+
with self._lock:
|
|
106
|
+
if owner_id not in self._owners:
|
|
107
|
+
raise EntityNotFoundError(f"Owner '{owner_id}' not found")
|
|
108
|
+
|
|
109
|
+
current = self._owners[owner_id]
|
|
110
|
+
if current.state == OwnerState.FINALIZED:
|
|
111
|
+
raise InvalidTransitionError(
|
|
112
|
+
f"Owner '{owner_id}' is already finalized at seq {current.finalized_seq}"
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
ev = self._commit_event_locked(
|
|
116
|
+
event_type=EventType.OWNER_FINALIZED,
|
|
117
|
+
owner_id=owner_id,
|
|
118
|
+
)
|
|
119
|
+
updated = dataclasses.replace(
|
|
120
|
+
current,
|
|
121
|
+
state=OwnerState.FINALIZED,
|
|
122
|
+
finalized_seq=ev.seq_id,
|
|
123
|
+
)
|
|
124
|
+
self._owners[owner_id] = updated
|
|
125
|
+
return updated
|
|
126
|
+
|
|
127
|
+
# -----------------------------------------------------------------------
|
|
128
|
+
# Task Lifecycle Commits
|
|
129
|
+
# -----------------------------------------------------------------------
|
|
130
|
+
|
|
131
|
+
def reserve_task(
|
|
132
|
+
self,
|
|
133
|
+
task_id: str,
|
|
134
|
+
owner_id: str,
|
|
135
|
+
parent_task_id: str | None = None,
|
|
136
|
+
) -> TaskRecord:
|
|
137
|
+
"""Reserve a task identity under an active owner prior to submit()."""
|
|
138
|
+
with self._lock:
|
|
139
|
+
if task_id in self._tasks:
|
|
140
|
+
raise DuplicateEntityError(f"Task '{task_id}' already exists")
|
|
141
|
+
if owner_id not in self._owners:
|
|
142
|
+
raise EntityNotFoundError(f"Owner '{owner_id}' not found")
|
|
143
|
+
if parent_task_id is not None and parent_task_id not in self._tasks:
|
|
144
|
+
raise EntityNotFoundError(f"Parent task '{parent_task_id}' not found")
|
|
145
|
+
|
|
146
|
+
ev = self._commit_event_locked(
|
|
147
|
+
event_type=EventType.TASK_RESERVED,
|
|
148
|
+
owner_id=owner_id,
|
|
149
|
+
task_id=task_id,
|
|
150
|
+
details={"parent_task_id": parent_task_id},
|
|
151
|
+
)
|
|
152
|
+
task = TaskRecord(
|
|
153
|
+
task_id=task_id,
|
|
154
|
+
owner_id=owner_id,
|
|
155
|
+
created_seq=ev.seq_id,
|
|
156
|
+
submission_state=SubmissionState.RESERVED,
|
|
157
|
+
callable_state=CallableState.NOT_STARTED,
|
|
158
|
+
future_state=FutureState.UNKNOWN,
|
|
159
|
+
parent_task_id=parent_task_id,
|
|
160
|
+
)
|
|
161
|
+
self._tasks[task_id] = task
|
|
162
|
+
return task
|
|
163
|
+
|
|
164
|
+
def commit_submit_returned(self, task_id: str) -> TaskRecord:
|
|
165
|
+
"""Commit successful return of ThreadPoolExecutor.submit()."""
|
|
166
|
+
with self._lock:
|
|
167
|
+
if task_id not in self._tasks:
|
|
168
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
169
|
+
|
|
170
|
+
current = self._tasks[task_id]
|
|
171
|
+
if current.submission_state != SubmissionState.RESERVED:
|
|
172
|
+
raise InvalidTransitionError(
|
|
173
|
+
f"Cannot commit SUBMIT_RETURNED from submission state '{current.submission_state}'"
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
ev = self._commit_event_locked(
|
|
177
|
+
event_type=EventType.SUBMIT_RETURNED,
|
|
178
|
+
owner_id=current.owner_id,
|
|
179
|
+
task_id=task_id,
|
|
180
|
+
)
|
|
181
|
+
new_future_state = (
|
|
182
|
+
FutureState.PENDING
|
|
183
|
+
if current.future_state == FutureState.UNKNOWN
|
|
184
|
+
else current.future_state
|
|
185
|
+
)
|
|
186
|
+
updated = dataclasses.replace(
|
|
187
|
+
current,
|
|
188
|
+
submission_state=SubmissionState.SUBMIT_RETURNED,
|
|
189
|
+
future_state=new_future_state,
|
|
190
|
+
)
|
|
191
|
+
self._tasks[task_id] = updated
|
|
192
|
+
return updated
|
|
193
|
+
|
|
194
|
+
def commit_submit_raised(
|
|
195
|
+
self,
|
|
196
|
+
task_id: str,
|
|
197
|
+
exception_type: str | None = None,
|
|
198
|
+
exception_message: str | None = None,
|
|
199
|
+
) -> TaskRecord:
|
|
200
|
+
"""Commit that ThreadPoolExecutor.submit() raised an exception.
|
|
201
|
+
|
|
202
|
+
Transition is to SUBMIT_RAISED_UNVERIFIED because CPython may have enqueued
|
|
203
|
+
the work item before failing to adjust the worker thread count.
|
|
204
|
+
"""
|
|
205
|
+
with self._lock:
|
|
206
|
+
if task_id not in self._tasks:
|
|
207
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
208
|
+
|
|
209
|
+
current = self._tasks[task_id]
|
|
210
|
+
if current.submission_state != SubmissionState.RESERVED:
|
|
211
|
+
raise InvalidTransitionError(
|
|
212
|
+
f"Cannot commit SUBMIT_RAISED from submission state '{current.submission_state}'"
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
ev = self._commit_event_locked(
|
|
216
|
+
event_type=EventType.SUBMIT_RAISED,
|
|
217
|
+
owner_id=current.owner_id,
|
|
218
|
+
task_id=task_id,
|
|
219
|
+
details={"exception_type": exception_type},
|
|
220
|
+
)
|
|
221
|
+
updated = dataclasses.replace(
|
|
222
|
+
current,
|
|
223
|
+
submission_state=SubmissionState.SUBMIT_RAISED_UNVERIFIED,
|
|
224
|
+
exception_type=exception_type,
|
|
225
|
+
exception_message=exception_message,
|
|
226
|
+
)
|
|
227
|
+
self._tasks[task_id] = updated
|
|
228
|
+
return updated
|
|
229
|
+
|
|
230
|
+
def commit_callable_started(self, task_id: str) -> TaskRecord:
|
|
231
|
+
"""Commit that the wrapped callable began execution."""
|
|
232
|
+
with self._lock:
|
|
233
|
+
if task_id not in self._tasks:
|
|
234
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
235
|
+
|
|
236
|
+
current = self._tasks[task_id]
|
|
237
|
+
if current.callable_state != CallableState.NOT_STARTED:
|
|
238
|
+
raise InvalidTransitionError(
|
|
239
|
+
f"Cannot start callable from state '{current.callable_state}'"
|
|
240
|
+
)
|
|
241
|
+
|
|
242
|
+
ev = self._commit_event_locked(
|
|
243
|
+
event_type=EventType.CALLABLE_STARTED,
|
|
244
|
+
owner_id=current.owner_id,
|
|
245
|
+
task_id=task_id,
|
|
246
|
+
)
|
|
247
|
+
# If submit raised but callable executes, record anomaly event
|
|
248
|
+
if current.submission_state == SubmissionState.SUBMIT_RAISED_UNVERIFIED:
|
|
249
|
+
self._commit_event_locked(
|
|
250
|
+
event_type=EventType.EXECUTION_WITHOUT_RETURNED_FUTURE,
|
|
251
|
+
owner_id=current.owner_id,
|
|
252
|
+
task_id=task_id,
|
|
253
|
+
)
|
|
254
|
+
|
|
255
|
+
updated = dataclasses.replace(
|
|
256
|
+
current,
|
|
257
|
+
callable_state=CallableState.RUNNING,
|
|
258
|
+
)
|
|
259
|
+
self._tasks[task_id] = updated
|
|
260
|
+
return updated
|
|
261
|
+
|
|
262
|
+
def commit_callable_exited(
|
|
263
|
+
self,
|
|
264
|
+
task_id: str,
|
|
265
|
+
outcome: CallableState,
|
|
266
|
+
exception_type: str | None = None,
|
|
267
|
+
exception_message: str | None = None,
|
|
268
|
+
) -> TaskRecord:
|
|
269
|
+
"""Commit that the wrapped callable exited (returned or raised)."""
|
|
270
|
+
with self._lock:
|
|
271
|
+
if task_id not in self._tasks:
|
|
272
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
273
|
+
|
|
274
|
+
current = self._tasks[task_id]
|
|
275
|
+
if outcome not in (CallableState.EXITED_RETURNED, CallableState.EXITED_RAISED):
|
|
276
|
+
raise InvalidTransitionError(
|
|
277
|
+
f"Invalid callable exit outcome '{outcome}'; expected EXITED_RETURNED or EXITED_RAISED"
|
|
278
|
+
)
|
|
279
|
+
if current.callable_state != CallableState.RUNNING:
|
|
280
|
+
raise InvalidTransitionError(
|
|
281
|
+
f"Cannot exit callable from state '{current.callable_state}'"
|
|
282
|
+
)
|
|
283
|
+
|
|
284
|
+
ev = self._commit_event_locked(
|
|
285
|
+
event_type=EventType.CALLABLE_EXITED,
|
|
286
|
+
owner_id=current.owner_id,
|
|
287
|
+
task_id=task_id,
|
|
288
|
+
details={"outcome": outcome.value, "exception_type": exception_type},
|
|
289
|
+
)
|
|
290
|
+
updated = dataclasses.replace(
|
|
291
|
+
current,
|
|
292
|
+
callable_state=outcome,
|
|
293
|
+
exception_type=exception_type or current.exception_type,
|
|
294
|
+
exception_message=exception_message or current.exception_message,
|
|
295
|
+
)
|
|
296
|
+
self._tasks[task_id] = updated
|
|
297
|
+
return updated
|
|
298
|
+
|
|
299
|
+
def commit_future_done(
|
|
300
|
+
self,
|
|
301
|
+
task_id: str,
|
|
302
|
+
terminal_state: FutureState,
|
|
303
|
+
) -> TaskRecord:
|
|
304
|
+
"""Commit observation of Future done callback."""
|
|
305
|
+
with self._lock:
|
|
306
|
+
if task_id not in self._tasks:
|
|
307
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
308
|
+
|
|
309
|
+
current = self._tasks[task_id]
|
|
310
|
+
if terminal_state not in (FutureState.FINISHED, FutureState.CANCELLED):
|
|
311
|
+
raise InvalidTransitionError(
|
|
312
|
+
f"Terminal future state must be FINISHED or CANCELLED, got '{terminal_state}'"
|
|
313
|
+
)
|
|
314
|
+
if current.future_state in (FutureState.FINISHED, FutureState.CANCELLED):
|
|
315
|
+
raise InvalidTransitionError(
|
|
316
|
+
f"Task '{task_id}' future is already in terminal state '{current.future_state.value}'; "
|
|
317
|
+
f"cannot transition to '{terminal_state.value}'"
|
|
318
|
+
)
|
|
319
|
+
|
|
320
|
+
ev = self._commit_event_locked(
|
|
321
|
+
event_type=EventType.FUTURE_DONE_CALLBACK_OBSERVED,
|
|
322
|
+
owner_id=current.owner_id,
|
|
323
|
+
task_id=task_id,
|
|
324
|
+
details={"terminal_state": terminal_state.value},
|
|
325
|
+
)
|
|
326
|
+
updated = dataclasses.replace(
|
|
327
|
+
current,
|
|
328
|
+
future_state=terminal_state,
|
|
329
|
+
)
|
|
330
|
+
self._tasks[task_id] = updated
|
|
331
|
+
return updated
|
|
332
|
+
|
|
333
|
+
# -----------------------------------------------------------------------
|
|
334
|
+
# Snapshots and Queries
|
|
335
|
+
# -----------------------------------------------------------------------
|
|
336
|
+
|
|
337
|
+
def get_owner(self, owner_id: str) -> OwnerRecord:
|
|
338
|
+
"""Retrieve an immutable snapshot of an owner record."""
|
|
339
|
+
with self._lock:
|
|
340
|
+
if owner_id not in self._owners:
|
|
341
|
+
raise EntityNotFoundError(f"Owner '{owner_id}' not found")
|
|
342
|
+
return self._owners[owner_id]
|
|
343
|
+
|
|
344
|
+
def get_task(self, task_id: str) -> TaskRecord:
|
|
345
|
+
"""Retrieve an immutable snapshot of a task record."""
|
|
346
|
+
with self._lock:
|
|
347
|
+
if task_id not in self._tasks:
|
|
348
|
+
raise EntityNotFoundError(f"Task '{task_id}' not found")
|
|
349
|
+
return self._tasks[task_id]
|
|
350
|
+
|
|
351
|
+
def get_all_owners(self) -> list[OwnerRecord]:
|
|
352
|
+
"""Return a snapshot list of all owner records."""
|
|
353
|
+
with self._lock:
|
|
354
|
+
return list(self._owners.values())
|
|
355
|
+
|
|
356
|
+
def get_all_tasks(self) -> list[TaskRecord]:
|
|
357
|
+
"""Return a snapshot list of all task records."""
|
|
358
|
+
with self._lock:
|
|
359
|
+
return list(self._tasks.values())
|
|
360
|
+
|
|
361
|
+
def get_tasks_for_owner(self, owner_id: str) -> list[TaskRecord]:
|
|
362
|
+
"""Return a snapshot list of tasks associated with an owner."""
|
|
363
|
+
with self._lock:
|
|
364
|
+
return [t for t in self._tasks.values() if t.owner_id == owner_id]
|
|
365
|
+
|
|
366
|
+
def get_events(self) -> list[EventRecord]:
|
|
367
|
+
"""Return an immutable point-in-time snapshot of the event history."""
|
|
368
|
+
with self._lock:
|
|
369
|
+
return list(self._events)
|
|
370
|
+
|
|
371
|
+
def get_events_for_owner(self, owner_id: str) -> list[EventRecord]:
|
|
372
|
+
"""Return events relevant to a specific owner."""
|
|
373
|
+
with self._lock:
|
|
374
|
+
return [e for e in self._events if e.owner_id == owner_id]
|
|
375
|
+
|
|
376
|
+
def get_events_for_task(self, task_id: str) -> list[EventRecord]:
|
|
377
|
+
"""Return events relevant to a specific task."""
|
|
378
|
+
with self._lock:
|
|
379
|
+
return [e for e in self._events if e.task_id == task_id]
|
|
380
|
+
|
|
381
|
+
def get_owner_snapshot(
|
|
382
|
+
self, owner_id: str
|
|
383
|
+
) -> tuple[OwnerRecord, list[TaskRecord], list[EventRecord]]:
|
|
384
|
+
"""Return a single coherent atomic point-in-time snapshot of an owner, its tasks, and its events.
|
|
385
|
+
|
|
386
|
+
All three collections are captured under a single acquisition of the ledger lock,
|
|
387
|
+
guaranteeing that task and event records correspond to the exact same sequence point.
|
|
388
|
+
The returned lists are freshly copied collections containing immutable records.
|
|
389
|
+
"""
|
|
390
|
+
with self._lock:
|
|
391
|
+
if owner_id not in self._owners:
|
|
392
|
+
raise EntityNotFoundError(f"Owner '{owner_id}' not found")
|
|
393
|
+
owner = self._owners[owner_id]
|
|
394
|
+
tasks = [t for t in self._tasks.values() if t.owner_id == owner_id]
|
|
395
|
+
events = [e for e in self._events if e.owner_id == owner_id]
|
|
396
|
+
return owner, list(tasks), list(events)
|
|
397
|
+
|
|
398
|
+
def get_finalized_session_snapshot(
|
|
399
|
+
self,
|
|
400
|
+
) -> tuple[list[OwnerRecord], list[TaskRecord], list[EventRecord]]:
|
|
401
|
+
"""Return a single coherent atomic point-in-time snapshot of all finalized owners, tasks, and events.
|
|
402
|
+
|
|
403
|
+
All records are captured under a single acquisition of the ledger lock,
|
|
404
|
+
guaranteeing process-wide consistency across all owners and tasks at that sequence point.
|
|
405
|
+
The returned lists are freshly copied collections containing immutable records.
|
|
406
|
+
"""
|
|
407
|
+
with self._lock:
|
|
408
|
+
finalized_owners = [
|
|
409
|
+
o for o in self._owners.values() if o.state == OwnerState.FINALIZED
|
|
410
|
+
]
|
|
411
|
+
tasks = list(self._tasks.values())
|
|
412
|
+
events = list(self._events)
|
|
413
|
+
return list(finalized_owners), list(tasks), list(events)
|