taskwire 0.3.2__tar.gz → 0.4.0__tar.gz

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.
Files changed (63) hide show
  1. {taskwire-0.3.2 → taskwire-0.4.0}/PKG-INFO +5 -5
  2. taskwire-0.4.0/conformance/exception-names.json +18 -0
  3. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/envelope-cancel.json +1 -1
  4. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/envelope-progress.json +1 -1
  5. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/envelope-snapshot.json +2 -2
  6. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/error-dispatch-failed.json +2 -2
  7. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/register-empty-null-aggregate.json +1 -1
  8. taskwire-0.3.2/conformance/wire/register-v1-with-aggregate.json → taskwire-0.4.0/conformance/wire/register-v2-with-aggregate.json +2 -2
  9. taskwire-0.3.2/conformance/wire/snapshot-v1-wall-clock-rev.json → taskwire-0.4.0/conformance/wire/snapshot-v2-wall-clock-rev.json +1 -1
  10. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/snapshot-waiting-input-uncollected-result.json +1 -1
  11. {taskwire-0.3.2 → taskwire-0.4.0}/pyproject.toml +6 -4
  12. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/__init__.py +25 -1
  13. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/calls.py +24 -32
  14. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/conformance.py +5 -4
  15. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/asgi.py +13 -5
  16. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/celery.py +6 -6
  17. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/muxws.py +6 -6
  18. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/redis_store.py +6 -0
  19. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/schema.py +27 -0
  20. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/viewsets.py +105 -46
  21. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/models.py +78 -2
  22. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/reporter.py +8 -15
  23. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/rest.py +73 -23
  24. {taskwire-0.3.2 → taskwire-0.4.0}/.gitignore +0 -0
  25. {taskwire-0.3.2 → taskwire-0.4.0}/LICENSE +0 -0
  26. {taskwire-0.3.2 → taskwire-0.4.0}/README.md +0 -0
  27. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/README.md +0 -0
  28. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/sequences/.gitkeep +0 -0
  29. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/aggregate-counts.json +0 -0
  30. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/aggregate-waiting-input-dominates.json +0 -0
  31. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/dialog-request-open.json +0 -0
  32. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-percent-absent.json +0 -0
  33. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-percent-null.json +0 -0
  34. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-private.json +0 -0
  35. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-shared-origins.json +0 -0
  36. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-cancelled.json +0 -0
  37. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-done.json +0 -0
  38. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-failed.json +0 -0
  39. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-queued.json +0 -0
  40. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-running.json +0 -0
  41. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/progress-state-waiting-input.json +0 -0
  42. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/result-kind-and-params.json +0 -0
  43. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/result-label-and-value-no-ref.json +0 -0
  44. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/result-ref-with-expires-at.json +0 -0
  45. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/text-key-and-text.json +0 -0
  46. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/text-key-only.json +0 -0
  47. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/text-key-params-and-text.json +0 -0
  48. {taskwire-0.3.2 → taskwire-0.4.0}/conformance/wire/text-text-only.json +0 -0
  49. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/ambient.py +0 -0
  50. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/__init__.py +0 -0
  51. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/fastapi.py +0 -0
  52. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/threads.py +0 -0
  53. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/viewsets_events.py +0 -0
  54. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/contrib/wsgi.py +0 -0
  55. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/decorators.py +0 -0
  56. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/delivery.py +0 -0
  57. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/headers.py +0 -0
  58. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/py.typed +0 -0
  59. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/reader.py +0 -0
  60. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/register.py +0 -0
  61. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/settings.py +0 -0
  62. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/store.py +0 -0
  63. {taskwire-0.3.2 → taskwire-0.4.0}/taskwire/transport.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: taskwire
3
- Version: 0.3.2
3
+ Version: 0.4.0
4
4
  Summary: Progress reporting and awaitable dialogs for long-running server-side operations.
5
5
  Project-URL: Homepage, https://github.com/velis74/taskwire
6
6
  Project-URL: Repository, https://github.com/velis74/taskwire
@@ -30,8 +30,8 @@ Requires-Dist: uvicorn>=0.27; extra == 'demo'
30
30
  Provides-Extra: dev
31
31
  Requires-Dist: celery>=5.3; extra == 'dev'
32
32
  Requires-Dist: coverage; extra == 'dev'
33
- Requires-Dist: dynamicforms-fastapi-viewsets>=0.11.1; extra == 'dev'
34
- Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.11.1; extra == 'dev'
33
+ Requires-Dist: dynamicforms-fastapi-viewsets>=0.12.0; extra == 'dev'
34
+ Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.12.0; extra == 'dev'
35
35
  Requires-Dist: fastapi>=0.100; extra == 'dev'
36
36
  Requires-Dist: httpx; extra == 'dev'
37
37
  Requires-Dist: hypothesis; extra == 'dev'
@@ -46,12 +46,12 @@ Requires-Dist: uvicorn>=0.27; extra == 'dev'
46
46
  Provides-Extra: fastapi
47
47
  Requires-Dist: fastapi>=0.100; extra == 'fastapi'
48
48
  Provides-Extra: muxws
49
- Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.11.1; extra == 'muxws'
49
+ Requires-Dist: dynamicforms-fastapi-viewsets[muxws]>=0.12.0; extra == 'muxws'
50
50
  Requires-Dist: muxws>=0.4.1; extra == 'muxws'
51
51
  Provides-Extra: redis
52
52
  Requires-Dist: redis>=5.0; extra == 'redis'
53
53
  Provides-Extra: viewsets
54
- Requires-Dist: dynamicforms-fastapi-viewsets>=0.11.1; extra == 'viewsets'
54
+ Requires-Dist: dynamicforms-fastapi-viewsets>=0.12.0; extra == 'viewsets'
55
55
  Description-Content-Type: text/markdown
56
56
 
57
57
  # <img src="taskwire-icon.svg" alt="" width="40" height="40" style="vertical-align: middle"> taskwire
@@ -0,0 +1,18 @@
1
+ {
2
+ "cases": [
3
+ ["ValueError", "value_error"],
4
+ ["KeyError", "key_error"],
5
+ ["HTTPError", "http_error"],
6
+ ["HTTPServerError", "http_server_error"],
7
+ ["IOError", "io_error"],
8
+ ["SoftTimeLimitExceeded", "soft_time_limit_exceeded"],
9
+ ["OAuth2Error", "o_auth2_error"],
10
+ ["Error2FA", "error2_fa"],
11
+ ["URLParseError", "url_parse_error"],
12
+ ["already_snake", "already_snake"],
13
+ ["_PrivateError", "private_error"],
14
+ ["Weird$Name", "weird_name"],
15
+ ["X", "x"],
16
+ ["", "error"]
17
+ ]
18
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "kind": "envelope",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
6
6
  "rev": 1786439700135,
7
7
  "kind": "cancel",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "kind": "envelope",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
6
6
  "rev": 1786439700123,
7
7
  "kind": "progress",
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "kind": "envelope",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
6
6
  "rev": 1786439700123,
7
7
  "kind": "snapshot",
8
8
  "body": {
9
- "v": 1,
9
+ "v": 2,
10
10
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
11
11
  "rev": 1786439700123,
12
12
  "progress": {
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "kind": "error",
3
3
  "document": {
4
- "code": "dispatch_failed",
4
+ "code": "taskwire.dispatch_failed",
5
5
  "message": {
6
- "key": "taskwire.error.dispatch_failed",
6
+ "key": "taskwire.dispatch_failed",
7
7
  "text": "Could not dispatch the task"
8
8
  },
9
9
  "retryable": true
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "kind": "register",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "operations": [],
6
6
  "aggregate": null,
7
7
  "server_time": "2026-08-11T09:15:04.317Z",
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "kind": "register",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "operations": [
6
6
  {
7
7
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
8
8
  "snapshot": {
9
- "v": 1,
9
+ "v": 2,
10
10
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
11
11
  "rev": 1786439700123,
12
12
  "progress": {
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "kind": "snapshot",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "token": "6b1f1c9e-0f2a-4a7d-9c2e-5f5b6a7c8d90",
6
6
  "rev": 1786439700123,
7
7
  "progress": {
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "kind": "snapshot",
3
3
  "document": {
4
- "v": 1,
4
+ "v": 2,
5
5
  "token": "b3c4d5e6-7f80-4912-a3b4-c5d6e7f80912",
6
6
  "rev": 1786439700934,
7
7
  "progress": {
@@ -30,19 +30,21 @@ dependencies = [] # DELIBERATE: core has no runtime dependency of any kind (TW
30
30
  redis = ["redis>=5.0"]
31
31
  celery = ["celery>=5.3", "nest_asyncio>=1.6"]
32
32
  fastapi = ["fastapi>=0.100"]
33
- # >=0.11.1: the execution hook and the Idempotency-Key helpers; a muxws command that runs to the end
34
- # of its action when its stream ends early (TW-CALL-*); delivery filters that run on poll as on push,
33
+ # >=0.12.0: namespaced error codes (`fastapi-viewsets.<code>`), which `TaskwireMiddleware` forwards
34
+ # verbatim, and one error body for every viewset route. From earlier releases: the execution hook
35
+ # and the Idempotency-Key helpers; a muxws command that runs to the end of its action when its
36
+ # stream ends early (TW-CALL-*); delivery filters that run on poll as on push,
35
37
  # which `contrib/viewsets_events.py` relies on for the display decision (TW-EVT-004); and an executor
36
38
  # that reports its outcomes in its own terms - `ActionInterruptedError`, `ActionOutcomeUnknownError`,
37
39
  # `Middleware.executor_started()` and `Middleware.on_transition()` - so that `contrib/viewsets.py`
38
40
  # imports no Celery (TW-CALL-101, TW-CALL-105), and that reports a process exit to `on_transition()`
39
41
  # in every pool.
40
- viewsets = ["dynamicforms-fastapi-viewsets>=0.11.1"]
42
+ viewsets = ["dynamicforms-fastapi-viewsets>=0.12.0"]
41
43
  # The socket carries the six request/response calls as viewset commands (TW-REST-004), so the muxws
42
44
  # extra needs the viewset layer's muxws half as well as muxws itself. >=0.4.1: `Peer.close()` sends
43
45
  # every queued frame before closing the socket, so the `goaway` of `goaway_if_stale` (TW-WS-007)
44
46
  # reaches the client.
45
- muxws = ["muxws>=0.4.1", "dynamicforms-fastapi-viewsets[muxws]>=0.11.1"]
47
+ muxws = ["muxws>=0.4.1", "dynamicforms-fastapi-viewsets[muxws]>=0.12.0"]
46
48
  demo = ["uvicorn>=0.27"]
47
49
  # Everything the test suite, the linters and the demo need.
48
50
  dev = [
@@ -12,7 +12,7 @@ outside. Nothing in the core imports a framework, a driver or a UI library (TW-C
12
12
 
13
13
  from __future__ import annotations
14
14
 
15
- __version__ = "0.3.2"
15
+ __version__ = "0.4.0"
16
16
 
17
17
  from .ambient import ask, current_reporter, progress
18
18
  from .calls import Call, call_token, end_call, execute_call, hand_off, receive_call
@@ -29,14 +29,24 @@ from .headers import CONNECTION_HEADER, TOKEN_HEADER
29
29
  from .models import (
30
30
  Aggregate,
31
31
  Button,
32
+ CANCELLED,
33
+ DIALOG_TIMEOUT,
32
34
  DialogAnswer,
33
35
  DialogReply,
34
36
  DialogRequest,
35
37
  DialogState,
38
+ DISPATCH_FAILED,
36
39
  Envelope,
37
40
  EnvelopeKind,
38
41
  Error,
42
+ ERROR_NAMESPACE,
43
+ ERROR_NAMESPACE_FASTAPI_VIEWSETS,
44
+ exception_name,
45
+ FAILED,
46
+ HTTP_STATUS,
39
47
  Input,
48
+ INTERRUPTED,
49
+ NOT_EXECUTED,
40
50
  OperationSummary,
41
51
  Progress,
42
52
  ProgressState,
@@ -46,6 +56,8 @@ from .models import (
46
56
  Snapshot,
47
57
  t,
48
58
  Text,
59
+ UNHANDLED_EXCEPTION,
60
+ unhandled_exception_error,
49
61
  )
50
62
  from .reader import check_taskwire_readers, start_taskwire_reader, stop_taskwire_reader
51
63
  from .register import aggregate, build_register
@@ -87,6 +99,18 @@ __all__ = [
87
99
  "Envelope",
88
100
  "EnvelopeKind",
89
101
  "Error",
102
+ "ERROR_NAMESPACE",
103
+ "CANCELLED",
104
+ "DIALOG_TIMEOUT",
105
+ "DISPATCH_FAILED",
106
+ "FAILED",
107
+ "HTTP_STATUS",
108
+ "INTERRUPTED",
109
+ "NOT_EXECUTED",
110
+ "UNHANDLED_EXCEPTION",
111
+ "exception_name",
112
+ "unhandled_exception_error",
113
+ "ERROR_NAMESPACE_FASTAPI_VIEWSETS",
90
114
  "InertReporter",
91
115
  "Input",
92
116
  "LocalTransport",
@@ -38,7 +38,17 @@ from dataclasses import dataclass
38
38
  from typing import Any
39
39
 
40
40
  from .headers import TOKEN_HEADER
41
- from .models import DialogState, Error, ProgressState, Text
41
+ from .models import (
42
+ DIALOG_TIMEOUT,
43
+ DialogState,
44
+ DISPATCH_FAILED,
45
+ Error,
46
+ HTTP_STATUS,
47
+ INTERRUPTED,
48
+ NOT_EXECUTED,
49
+ ProgressState,
50
+ Text,
51
+ )
42
52
  from .reporter import mark_failed, mark_queued, operation, OperationScope, Reporter
43
53
  from .rest import _is_uuid
44
54
  from .settings import configured
@@ -52,50 +62,32 @@ IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
52
62
  SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
53
63
  """Methods whose `Idempotency-Key` does not make a call tracked (TW-CALL-002)."""
54
64
 
55
- NOT_EXECUTED = "not_executed"
56
- """A tracked call ended before anything executed it. `retryable: false` (TW-CALL-005)."""
57
-
58
- DISPATCH_FAILED = "dispatch_failed"
59
- """The work could not be handed to the process that executes it. `retryable: true` (TW-CALL-005,
60
- TW-CELERY-004)."""
61
-
62
- DIALOG_TIMEOUT = "dialog_timeout"
63
- """An execution limit ended the work while it held an open question. `retryable: true` (TW-DLG-006)."""
64
-
65
- INTERRUPTED = "interrupted"
66
- """The executor ended the work after it started, with no open question: a time limit, a termination, the
67
- loss of the executing process. `message.params.reason` names which when the executor says. `retryable:
68
- true` (TW-CALL-008)."""
69
-
70
- HTTP_STATUS = "http_status"
71
- """The call was answered with an error status and no exception (TW-CALL-006)."""
72
-
73
65
 
74
66
  def status_error(status: int) -> Error | None:
75
67
  """The error of a call answered with HTTP `status`, or None below 400 (TW-CALL-006).
76
68
 
77
- `http_status` with `params={"status": status}`, `retryable: true` for 502, 503 and 504.
69
+ `taskwire.http_status` with `params={"status": status}`, `retryable: true` for 502, 503 and 504.
78
70
  """
79
71
  if status < 400:
80
72
  return None
81
73
  return Error(
82
74
  code=HTTP_STATUS,
83
- message=Text(key="taskwire.http_status", params={"status": status}, text=f"HTTP {status}"),
75
+ message=Text(key=HTTP_STATUS, params={"status": status}, text=f"HTTP {status}"),
84
76
  retryable=status in (502, 503, 504),
85
77
  )
86
78
 
87
79
 
88
80
  def dialog_timeout_error() -> Error:
89
81
  """The error of work an execution limit ended while it held an open question (TW-DLG-006)."""
90
- return Error(code=DIALOG_TIMEOUT, message=Text(key="taskwire.dialog_timeout"), retryable=True)
82
+ return Error(code=DIALOG_TIMEOUT, message=Text(key=DIALOG_TIMEOUT), retryable=True)
91
83
 
92
84
 
93
85
  def interrupted_error(reason: str | None = None) -> Error:
94
- """The error of work the executor ended after it started (TW-CALL-008): `interrupted`, with
86
+ """The error of work the executor ended after it started (TW-CALL-008): `taskwire.interrupted`, with
95
87
  `message.params.reason` when `reason` is given."""
96
88
  return Error(
97
89
  code=INTERRUPTED,
98
- message=Text(key="taskwire.interrupted", params={"reason": reason} if reason is not None else None),
90
+ message=Text(key=INTERRUPTED, params={"reason": reason} if reason is not None else None),
99
91
  retryable=True,
100
92
  )
101
93
 
@@ -248,9 +240,9 @@ class CallReceipt:
248
240
  if snapshot is None or ProgressState(snapshot.progress.state) is not ProgressState.QUEUED:
249
241
  return
250
242
  if exc is not None and isinstance(exc, self._dispatch_errors):
251
- error = Error(code=DISPATCH_FAILED, message=Text(key="taskwire.dispatch_failed"), retryable=True)
243
+ error = Error(code=DISPATCH_FAILED, message=Text(key=DISPATCH_FAILED), retryable=True)
252
244
  else:
253
- error = Error(code=NOT_EXECUTED, message=Text(key="taskwire.not_executed"), retryable=False)
245
+ error = Error(code=NOT_EXECUTED, message=Text(key=NOT_EXECUTED), retryable=False)
254
246
  await mark_failed(call.token, session=call.session, error=error)
255
247
  except Exception: # noqa: BLE001 - reporting never replaces the call's own outcome
256
248
  logger.warning("taskwire: could not end the unexecuted operation %s", call.token, exc_info=True)
@@ -294,9 +286,9 @@ def receive_call(
294
286
  Entry drops a terminal document under the token, since the call executes anew, and writes `queued`
295
287
  with `call.result_kind` and `call.connection`; an existing non-terminal document is left as it is.
296
288
  Exit writes `failed` when the operation is still `queued` and `execute_call()` was not entered for
297
- the call in this context: `dispatch_failed` (`retryable: true`) when the exception leaving the block
289
+ the call in this context: `taskwire.dispatch_failed` (`retryable: true`) when the exception leaving the block
298
290
  is one of `dispatch_errors`, nothing when it is one of `pending_errors` (the work may still execute
299
- elsewhere, and `active_ttl` expires the document otherwise), and `not_executed` (`retryable: false`)
291
+ elsewhere, and `active_ttl` expires the document otherwise), and `taskwire.not_executed` (`retryable: false`)
300
292
  in every other case, a clean exit included.
301
293
 
302
294
  `call=None` and a store-less configuration make it a no-op, and so does a block nested in one
@@ -345,7 +337,7 @@ class CallExecution:
345
337
  if exc is not None and isinstance(exc, self._timeout_errors) and reporter.asking:
346
338
  reporter.name_error(
347
339
  DIALOG_TIMEOUT,
348
- Text(key="taskwire.dialog_timeout"),
340
+ Text(key=DIALOG_TIMEOUT),
349
341
  True, # noqa: FBT003 - positional to match `name_error(code, message, retryable)`
350
342
  )
351
343
  return scope
@@ -413,7 +405,7 @@ def execute_call(call: Call | None, *, timeout_errors: tuple[type[BaseException]
413
405
  to `running`, binds the ambient reporter and writes exactly one terminal state on exit (TW-API-001),
414
406
  and marks the call started for the `receive_call()` block around it. When an exception in
415
407
  `timeout_errors` ends the block while the operation holds an open question, the terminal error is
416
- `dialog_timeout` with `retryable: true` (TW-DLG-006).
408
+ `taskwire.dialog_timeout` with `retryable: true` (TW-DLG-006).
417
409
 
418
410
  Yields None, and reports nothing, for `call=None` and inside another `execute_call()` block: work
419
411
  the executing call does on its own behalf belongs to its operation. A store failure on entry leaves
@@ -467,7 +459,7 @@ def hand_off() -> Iterator[dict[str, str]]:
467
459
 
468
460
  Yields `Call.carried()` of the call `execute_call()` is executing in this context, `{}` outside
469
461
  one. A block that exits cleanly leaves the terminal write to the receiving process: the
470
- `execute_call()` exit writes no state. An exception leaving the block names `dispatch_failed`
462
+ `execute_call()` exit writes no state. An exception leaving the block names `taskwire.dispatch_failed`
471
463
  (`retryable: true`) as the operation's error, and the `execute_call()` exit writes it.
472
464
 
473
465
  ```python
@@ -484,7 +476,7 @@ def hand_off() -> Iterator[dict[str, str]]:
484
476
  except BaseException:
485
477
  execution._reporter.name_error(
486
478
  DISPATCH_FAILED,
487
- Text(key="taskwire.dispatch_failed"),
479
+ Text(key=DISPATCH_FAILED),
488
480
  True, # noqa: FBT003 - positional to match `name_error(code, message, retryable)`
489
481
  )
490
482
  raise
@@ -30,6 +30,7 @@ from .models import (
30
30
  DialogReply,
31
31
  DialogRequest,
32
32
  DialogState,
33
+ DISPATCH_FAILED,
33
34
  Envelope,
34
35
  EnvelopeKind,
35
36
  Error,
@@ -342,7 +343,7 @@ async def test_terminal_commit_leaves_the_register_and_stays_readable(make_store
342
343
  assert listed == ["ending", "running"], listed
343
344
 
344
345
  failing = _progress(state=ProgressState.FAILED)
345
- failing.error = Error(code="import_failed", message=Text(text="boom"), retryable=False)
346
+ failing.error = Error(code="acme.import_failed", message=Text(text="boom"), retryable=False)
346
347
  await store.commit(ending, failing, 60)
347
348
 
348
349
  listed = sorted(snapshot.token for snapshot in await store.list_operations(NS))
@@ -352,7 +353,7 @@ async def test_terminal_commit_leaves_the_register_and_stays_readable(make_store
352
353
  assert tombstone is not None, "the terminal document is readable at its own address"
353
354
  assert ProgressState(tombstone.progress.state) is ProgressState.FAILED
354
355
  assert tombstone.progress.error is not None
355
- assert tombstone.progress.error.code == "import_failed"
356
+ assert tombstone.progress.error.code == "acme.import_failed"
356
357
 
357
358
 
358
359
  async def test_terminal_document_can_still_be_dropped(make_store: StoreFactory) -> None:
@@ -370,13 +371,13 @@ async def test_error_survives_a_round_trip(make_store: StoreFactory) -> None:
370
371
  store = make_store()
371
372
  k = make_key(NS, "failing")
372
373
  progress = _progress(state=ProgressState.FAILED)
373
- progress.error = Error(code="dispatch_failed", message=Text(key="taskwire.dispatch_failed"), retryable=True)
374
+ progress.error = Error(code=DISPATCH_FAILED, message=Text(key=DISPATCH_FAILED), retryable=True)
374
375
  await store.commit(k, progress, 60)
375
376
 
376
377
  snapshot = await store.snapshot(k)
377
378
  assert snapshot is not None
378
379
  assert snapshot.progress.error is not None
379
- assert snapshot.progress.error.code == "dispatch_failed"
380
+ assert snapshot.progress.error.code == DISPATCH_FAILED
380
381
  assert snapshot.progress.error.retryable is True
381
382
  assert "Traceback" not in str(snapshot.progress.error.message.to_dict())
382
383
 
@@ -17,7 +17,15 @@ from typing import Any
17
17
  from ..calls import Call, call_token, execute_call, receive_call, status_error
18
18
  from ..delivery import Client
19
19
  from ..headers import CONNECTION_HEADER_BYTES as CONNECTION_HEADER
20
- from ..rest import collect_result, dismiss_result, get_operations, get_snapshot, reply_to_dialog, request_cancel
20
+ from ..rest import (
21
+ collect_result,
22
+ dismiss_result,
23
+ get_operations,
24
+ get_snapshot,
25
+ NOT_FOUND,
26
+ reply_to_dialog,
27
+ request_cancel,
28
+ )
21
29
  from ..settings import configured, settings
22
30
 
23
31
 
@@ -54,7 +62,7 @@ def app(prefix: str | None = None) -> Callable[..., Any]:
54
62
  )
55
63
 
56
64
  if not path.startswith(mount):
57
- status, payload = 404, {"detail": "not_found"}
65
+ status, payload = 404, {"detail": NOT_FOUND}
58
66
  elif scope["method"] == "POST":
59
67
  rest = path[len(mount) :].strip("/").split("/")
60
68
  if len(rest) == 3 and rest[1] == "dialogs":
@@ -66,9 +74,9 @@ def app(prefix: str | None = None) -> Callable[..., Any]:
66
74
  elif len(rest) == 2 and rest[1] == "dismiss":
67
75
  status, payload = await dismiss_result(client, rest[0])
68
76
  else:
69
- status, payload = 404, {"detail": "not_found"}
77
+ status, payload = 404, {"detail": NOT_FOUND}
70
78
  elif scope["method"] != "GET":
71
- status, payload = 404, {"detail": "not_found"}
79
+ status, payload = 404, {"detail": NOT_FOUND}
72
80
  else:
73
81
  rest = path[len(mount) :].strip("/")
74
82
  # The register is the collection and lives at the collection's own URL (TW-REST-004), so
@@ -116,7 +124,7 @@ def track_calls(
116
124
  namespace resolver returns one: `session_resolver`, else the configured one, called with the ASGI
117
125
  scope. The request runs inside `receive_call()` and `execute_call()`, so the application reports
118
126
  through `taskwire.progress` and hands work to another process with `taskwire.calls.hand_off()`.
119
- A response status of 400 or more ends the operation `failed` with `http_status`. `result_kind`,
127
+ A response status of 400 or more ends the operation `failed` with `taskwire.http_status`. `result_kind`,
120
128
  called with the scope, fixes the operation's result kind; without it the operation is private.
121
129
  Requests under `exclude_prefix` (default: `settings.rest_prefix`, taskwire's own endpoints) and
122
130
  every other scope type pass through untouched.
@@ -6,7 +6,7 @@ Imports Celery; nothing in `taskwire/` outside `contrib` may (TW-CORE-006).
6
6
 
7
7
  **In a Celery deployment the worker owns the terminal write of an operation it runs**
8
8
  (TW-CELERY-004, TW-INV-009). The web side writes `queued`, and `failed` only when the broker did not
9
- accept the task: `dispatch_failed` with `retryable: true`, because an unreachable broker is transient
9
+ accept the task: `taskwire.dispatch_failed` with `retryable: true`, because an unreachable broker is transient
10
10
  and a frontend may legitimately offer a retry.
11
11
 
12
12
  The web side must **not** open `operation()` for a task it dispatches (TW-CELERY-005): the block would
@@ -25,7 +25,7 @@ Either way the task body is a `taskwire_task`.
25
25
 
26
26
  A dialog has no deadline (TW-DLG-005), so **an unanswered question holds its worker until Celery's
27
27
  own execution timeout kills the task** (TW-CELERY-010). At that point this module writes `failed`
28
- with `code: "dialog_timeout"` and `retryable: true`, and withdraws the operation's open dialogs.
28
+ with `code: "taskwire.dialog_timeout"` and `retryable: true`, and withdraws the operation's open dialogs.
29
29
 
30
30
  What you can do about it today, none of which is a solution:
31
31
 
@@ -114,12 +114,12 @@ def taskwire_task(
114
114
  #
115
115
  # Named rather than committed: the exception is on its way out of `operation()`,
116
116
  # whose exit makes the one terminal write this operation gets (TW-API-001). When
117
- # it is not a question, nothing is named and the exception's own class is what
118
- # the exit derives the code from, as it does for every other failure.
117
+ # it is not a question, nothing is named and the exit writes
118
+ # `taskwire.unhandled_exception` with the exception's class, as for every other failure.
119
119
  if reporter.asking:
120
120
  reporter.name_error(
121
121
  DIALOG_TIMEOUT,
122
- Text(key="taskwire.dialog_timeout"),
122
+ Text(key=DIALOG_TIMEOUT),
123
123
  True, # noqa: FBT003 - positional to match `name_error(code, message, retryable)`
124
124
  )
125
125
  raise
@@ -165,7 +165,7 @@ async def dispatch(
165
165
  await mark_failed(
166
166
  token,
167
167
  session=session,
168
- error=Error(code=DISPATCH_FAILED, message=Text(key="taskwire.dispatch_failed"), retryable=True),
168
+ error=Error(code=DISPATCH_FAILED, message=Text(key=DISPATCH_FAILED), retryable=True),
169
169
  )
170
170
  raise broker_failure
171
171
 
@@ -46,7 +46,7 @@ from ..delivery import ( # noqa: F401 - CONNECTION_TAG is re-exported
46
46
  OperationRef,
47
47
  OVERRIDES_TAG,
48
48
  )
49
- from ..models import Envelope, EnvelopeKind, Progress
49
+ from ..models import Envelope, EnvelopeKind, Progress, WIRE_VERSION
50
50
  from ..reader import unwatch_namespace, watch_namespace
51
51
  from ..settings import configured, settings
52
52
  from ..transport import TaskwireTransport
@@ -168,7 +168,7 @@ def handle_watch(peer: Any, message: dict[str, Any]) -> dict[str, Any]:
168
168
  `false` suppresses, `true` revives, absent defers to `push_filter`, and `{}` returns everything
169
169
  to the predicate. Idempotent and last-writer-wins **per connection**.
170
170
 
171
- Answers `{"v": 1, "status": int, "connection": str}` (TW-DEL-022): status `0` accepted, `1`
171
+ Answers `{"v": WIRE_VERSION, "status": int, "connection": str}` (TW-DEL-022): status `0` accepted, `1`
172
172
  rejected for exceeding `max_overrides`, `2` malformed. A rejected declaration still carries the
173
173
  connection id, since the socket is unchanged - and a client may send `{"overrides": {}}` purely
174
174
  to obtain that id, which is what a reconnecting client does (TW-REG-020). An empty declaration is
@@ -184,15 +184,15 @@ def handle_watch(peer: Any, message: dict[str, Any]) -> dict[str, Any]:
184
184
  if not isinstance(declared, dict) or not all(
185
185
  isinstance(token, str) and isinstance(value, bool) for token, value in declared.items()
186
186
  ):
187
- return {"v": 1, "status": 2, "connection": identity}
187
+ return {"v": WIRE_VERSION, "status": 2, "connection": identity}
188
188
 
189
189
  if len(declared) > settings.max_overrides:
190
190
  # TW-DEL-008: rejected rather than truncated, leaving the previous map in force. A truncated
191
191
  # map is one the user asked for and did not get, with no way to tell which half survived.
192
- return {"v": 1, "status": 1, "connection": identity}
192
+ return {"v": WIRE_VERSION, "status": 1, "connection": identity}
193
193
 
194
194
  peer.tags[OVERRIDES_TAG] = dict(declared)
195
- return {"v": 1, "status": 0, "connection": identity}
195
+ return {"v": WIRE_VERSION, "status": 0, "connection": identity}
196
196
 
197
197
 
198
198
  def prune_override(peers: list[Any], token: str) -> None:
@@ -269,7 +269,7 @@ async def serve_peer(peer: Any, session: str) -> StreamHandler:
269
269
 
270
270
  # TW-CORE-007: the wire vocabulary is closed. An unknown kind is answered rather than
271
271
  # ignored, so a client learns immediately instead of waiting on a stream nobody will end.
272
- await stream.reply({"v": 1, "status": 2, "detail": f"unknown kind {kind!r}"})
272
+ await stream.reply({"v": WIRE_VERSION, "status": 2, "detail": f"unknown kind {kind!r}"})
273
273
 
274
274
  # TW-BP-004: this process now holds a connection for `session`, so its reader subscribes to that
275
275
  # namespace's channel. A no-op in a single-process deployment, and the difference between a
@@ -250,6 +250,7 @@ class _Scripts:
250
250
 
251
251
  def __init__(self, client: Any) -> None:
252
252
  self.redis = client
253
+ self.closer: asyncio.Task | None = None
253
254
  self.commit = client.register_script(_COMMIT)
254
255
  self.put_dialog = client.register_script(_PUT_DIALOG)
255
256
  self.resolve_dialog = client.register_script(_RESOLVE_DIALOG)
@@ -295,6 +296,9 @@ class RedisStore(TaskwireStore):
295
296
  closer = loop.create_task(self._close_with_loop(loop, bound), name="RedisStore: close with the loop")
296
297
  # A loop that ends without cancelling its tasks destroys this one without a warning.
297
298
  closer._log_destroy_pending = False # type: ignore[attr-defined]
299
+ # A loop holds its tasks weakly. Unreferenced, this task and the future it waits on are garbage
300
+ # that a collection destroys while the loop runs, which forgets the client without closing it.
301
+ bound.closer = closer
298
302
  return bound
299
303
 
300
304
  async def _close_with_loop(self, loop: asyncio.AbstractEventLoop, bound: _Scripts) -> None:
@@ -597,6 +601,8 @@ class RedisStore(TaskwireStore):
597
601
  with self._lock:
598
602
  bound = self._per_loop.pop(asyncio.get_running_loop(), None)
599
603
  if bound is not None:
604
+ if bound.closer is not None:
605
+ bound.closer.cancel()
600
606
  await bound.redis.aclose()
601
607
 
602
608
 
@@ -189,6 +189,33 @@ class Register(BaseModel):
189
189
  poll_after_ms: int = 5000
190
190
 
191
191
 
192
+ class ErrorBody(BaseModel):
193
+ """The body of every error answer of the six endpoints, as `taskwire.rest` builds it."""
194
+
195
+ detail: str = Field(
196
+ description="What went wrong: `taskwire.not_found`, `taskwire.already_terminal`, "
197
+ "`taskwire.holds_an_uncollected_result`, `taskwire.no_uncollected_result`, `taskwire.already_answered` "
198
+ "or `taskwire.cancelled`; for a `422`, English text naming the problem."
199
+ )
200
+ code: str | None = Field(
201
+ default=None,
202
+ description="`taskwire.invalid_reply` on the `422` of a dialog reply; absent otherwise.",
203
+ examples=["taskwire.invalid_reply"],
204
+ )
205
+ params: dict[str, Any] | None = Field(
206
+ default=None,
207
+ description="On the `422` of a dialog reply, what failed: `reason` (`button_required`, `unknown_button`, "
208
+ "`values_not_an_object`, `input_required`, `unknown_input_type`, `wrong_input_type`) and, where it applies, "
209
+ "`button`, `input`, `type` and `expected`.",
210
+ examples=[{"reason": "unknown_button", "button": "maybe"}],
211
+ )
212
+ dialog: DialogRequest | None = Field(
213
+ default=None,
214
+ description="The dialog in its settled state, with the winning reply, on the `409` and `410` of a "
215
+ "dialog reply (TW-DLG-010).",
216
+ )
217
+
218
+
192
219
  class Accepted(BaseModel):
193
220
  """TW-CANCEL-003: a cancel request is an **acknowledgement**, never a completion.
194
221