requence 0.8.1.dev72__tar.gz → 0.8.1.dev98__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 (78) hide show
  1. {requence-0.8.1.dev72/requence.egg-info → requence-0.8.1.dev98}/PKG-INFO +1 -1
  2. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/pyproject.toml +1 -1
  3. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/callbacks/handler.py +5 -1
  4. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/requence_callback.py +5 -1
  5. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/__init__.py +97 -5
  6. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/wire.py +25 -0
  7. {requence-0.8.1.dev72 → requence-0.8.1.dev98/requence.egg-info}/PKG-INFO +1 -1
  8. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/MANIFEST.in +0 -0
  9. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/README.md +0 -0
  10. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/__init__.py +0 -0
  11. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/callbacks/__init__.py +0 -0
  12. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/callbacks/context.py +0 -0
  13. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/client_properties.py +0 -0
  14. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/context.py +0 -0
  15. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/exceptions.py +0 -0
  16. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/__init__.py +0 -0
  17. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/errors.py +0 -0
  18. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/handlers/__init__.py +0 -0
  19. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/handlers/claim_check_handler.py +0 -0
  20. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/handlers/context.py +0 -0
  21. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/handlers/file_handler.py +0 -0
  22. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/handlers/stream_handler.py +0 -0
  23. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/pending_uploads.py +0 -0
  24. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/requence_file.py +0 -0
  25. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/requence_stream.py +0 -0
  26. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/sanitize_log_data.py +0 -0
  27. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/stream_framing.py +0 -0
  28. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/files/transport.py +0 -0
  29. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/internal_types.py +0 -0
  30. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/logger.py +0 -0
  31. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/obfuscase.py +0 -0
  32. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/py.typed +0 -0
  33. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/reachable.py +0 -0
  34. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/requence_file.py +0 -0
  35. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/requence_stream.py +0 -0
  36. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/boundary.py +0 -0
  37. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/callback_growth.py +0 -0
  38. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/cli.py +0 -0
  39. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/durable_callback.py +0 -0
  40. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/surface_handler.py +0 -0
  41. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/transformer.py +0 -0
  42. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/types.py +0 -0
  43. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/ui.py +0 -0
  44. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/service/ui_watch.py +0 -0
  45. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/store.py +0 -0
  46. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/__init__.py +0 -0
  47. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/abort_task.py +0 -0
  48. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/ack_task.py +0 -0
  49. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/cli.py +0 -0
  50. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/get_task.py +0 -0
  51. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/ingress.py +0 -0
  52. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/protect_task.py +0 -0
  53. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/task.py +0 -0
  54. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/task_watcher.py +0 -0
  55. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/types.py +0 -0
  56. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/updates.py +0 -0
  57. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/task/utils.py +0 -0
  58. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/__init__.py +0 -0
  59. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/context.py +0 -0
  60. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/errors.py +0 -0
  61. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/guards.py +0 -0
  62. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/message_handler.py +0 -0
  63. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/transform.py +0 -0
  64. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/value_handler.py +0 -0
  65. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/transformer/walk.py +0 -0
  66. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/utils.py +0 -0
  67. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence/wire_codec.py +0 -0
  68. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence.egg-info/SOURCES.txt +0 -0
  69. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence.egg-info/dependency_links.txt +0 -0
  70. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence.egg-info/entry_points.txt +0 -0
  71. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence.egg-info/requires.txt +0 -0
  72. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/requence.egg-info/top_level.txt +0 -0
  73. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/setup.cfg +0 -0
  74. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/tests/test_client_properties.py +0 -0
  75. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/tests/test_logger.py +0 -0
  76. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/tests/test_store_parity.py +0 -0
  77. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/tests/test_wire.py +0 -0
  78. {requence-0.8.1.dev72 → requence-0.8.1.dev98}/tests/test_wire_codec.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: requence
3
- Version: 0.8.1.dev72
3
+ Version: 0.8.1.dev98
4
4
  Summary: Requence Service
5
5
  Author: Torsten Blindert
6
6
  Requires-Python: >=3.12
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "requence"
7
- version = "0.8.1.dev72"
7
+ version = "0.8.1.dev98"
8
8
  description = "Requence Service"
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  authors = [{ name = "Torsten Blindert" }]
@@ -84,7 +84,11 @@ def _serialize(callback: Any, ctx: TransformContext, path: TransformPath) -> dic
84
84
 
85
85
 
86
86
  def _deserialize(ref: dict, ctx: TransformContext, _path: TransformPath):
87
- def invoke(arg: Any) -> None:
87
+ # ``None`` by default, mirroring the TS handler: a callback that carries no
88
+ # data is declared ``RequenceCallback[None]`` — its schema is ``{type: 'null'}``
89
+ # and the operator validates every invocation against it — so an omitted
90
+ # argument has to arrive AS null rather than be absent.
91
+ def invoke(arg: Any = None) -> None:
88
92
  on_callback_invoke = getattr(ctx, "on_callback_invoke", None)
89
93
  if on_callback_invoke is not None:
90
94
  on_callback_invoke({**ref, "arg": arg})
@@ -10,7 +10,11 @@ class Callback(Generic[T]):
10
10
  self.__result: Optional[Union[T, StopException]] = None
11
11
  self.__callback = callback
12
12
 
13
- def __call__(self, arg: Union[T, StopException]):
13
+ # ``None`` for an omitted argument, mirroring the TS ``createCallback``: a
14
+ # callback that carries no data is declared ``Callback[None]`` and its schema is
15
+ # ``{type: 'null'}``, so calling it with nothing has to mean null rather than a
16
+ # missing value.
17
+ def __call__(self, arg: Union[T, StopException, None] = None):
14
18
  self.__result = arg
15
19
  self.__event.set()
16
20
  if self.__callback and not isinstance(arg, StopException):
@@ -24,7 +24,10 @@ from ..obfuscase import deobfuscate, obfuscate
24
24
  from ..wire import (
25
25
  DEFAULT_SURFACE_ID,
26
26
  DURABLE_CALLBACK_QUEUE_ARGUMENTS,
27
+ DURABLE_CALLBACK_ERROR_HEADER,
28
+ MAX_DURABLE_CALLBACK_ERROR_CHARS,
27
29
  MAX_SURFACE_INTERACTION_ERROR_CHARS,
30
+ NODE_RESUME_HEADER,
28
31
  REFERENCE_TAG_KEY,
29
32
  SURFACE_HANDLER_QUEUE_ARGUMENTS,
30
33
  SURFACE_HANDLER_TAG,
@@ -827,11 +830,15 @@ class Service:
827
830
  headers: dict[str, Any],
828
831
  failure_label: str,
829
832
  announce: Optional[str] = None,
833
+ correlation_id: Optional[str] = None,
830
834
  ):
831
835
  """A publish on the ordinary result exchange that is NOT a result for any
832
- dispatch: no correlation id, no index, no place in the ordered dispatch
833
- buffer. The operator answers these messages' marker headers before it looks
834
- for either.
836
+ dispatch: no index and no place in the ordered dispatch buffer. The operator
837
+ answers these messages' marker headers before it looks for either.
838
+
839
+ ``correlation_id`` is for the one of these that does belong to a message: a
840
+ resume announcement (#271) names the run it re-attached to. The other two
841
+ belong to no message at all and pass none.
835
842
 
836
843
  Always JSON, unlike a reply: there is no dispatch here whose codec could be
837
844
  echoed. Encoded through ``wire_codec`` all the same, so the SDK keeps its one
@@ -849,6 +856,7 @@ class Service:
849
856
  properties=pika.BasicProperties(
850
857
  content_type=content_type,
851
858
  delivery_mode=pika.DeliveryMode.Persistent,
859
+ correlation_id=correlation_id,
852
860
  headers=headers,
853
861
  ),
854
862
  )
@@ -882,6 +890,76 @@ class Service:
882
890
  )
883
891
  )
884
892
 
893
+ def __report_callback_failure(self, raw: Any, error: BaseException):
894
+ """Say on the RUN that this process could not run a durable callback.
895
+
896
+ The counterpart of the operator's report for an invocation nobody consumed:
897
+ this one WAS consumed and could not be run — an unknown declaration name, or
898
+ a handler that threw. Only the consuming instance can see either.
899
+
900
+ Until this existed it said so in one process's stdout and nowhere a template
901
+ author looks, which made a failed ``mail.delete()`` indistinguishable from a
902
+ delete that did nothing. There is no request left to fail — the graph called
903
+ the callback and moved on, and the invocation is acked either way because a
904
+ requeue would rerun a side-effecting callback forever — so a statement on
905
+ the emitting node of that run is the only feedback the call has left.
906
+
907
+ Carries no correlation id and no index, like every other side-channel report:
908
+ the handler was not running for a dispatch, so it has no message to be a
909
+ result FOR."""
910
+ if not is_durable_callback_invocation(raw):
911
+ # Nowhere to put a statement about an invocation that cannot say which
912
+ # run and which node it was for. The throw itself is logged by the
913
+ # caller.
914
+ logger.error(
915
+ "Requence: cannot report a failed durable callback — the "
916
+ "invocation names no task and node"
917
+ )
918
+ return
919
+
920
+ name = raw["name"]
921
+ self.__schedule(
922
+ functools.partial(
923
+ self.__publish_side_channel,
924
+ {
925
+ "nodeId": raw["nodeId"],
926
+ "name": name,
927
+ # Cut at the source as well as in the update schema, as a
928
+ # surface report is. The MESSAGE, not the traceback — the
929
+ # traceback is for this process's own log.
930
+ "message": str(error)[:MAX_DURABLE_CALLBACK_ERROR_CHARS],
931
+ },
932
+ {"taskId": raw["taskId"], DURABLE_CALLBACK_ERROR_HEADER: True},
933
+ f"report the failed durable callback |{name}|",
934
+ )
935
+ )
936
+
937
+ def __announce_resume(self, task_id: str, message_id: str):
938
+ """Say that this process has re-attached to a deferred node (#271) — the
939
+ moment the node starts working again.
940
+
941
+ Nobody else can say it. The operator dispatched this message days ago and
942
+ hears nothing when someone picks it up: ``act()`` publishes no ``begin``,
943
+ and there is no ``defer`` on its actor API, so a run defers at most once and
944
+ without this the defer runs to the end of the run. A form deferred three
945
+ days whose handler then spends four minutes building a PDF reported one
946
+ second of work.
947
+
948
+ Carries **no index**, which is why it is a side channel at all: the
949
+ announcement takes no place in the message's ordered output stream, and a
950
+ ``begin`` — the other way to say this — lands on the operator's
951
+ begin-rewind, which resets a deferred message's index space and is what
952
+ keeps a re-attach's render from being discarded as a duplicate."""
953
+ self.__schedule(
954
+ functools.partial(
955
+ self.__publish_side_channel,
956
+ {"messageId": message_id},
957
+ {"taskId": task_id, NODE_RESUME_HEADER: True},
958
+ f"announce the resume of message |{message_id}|",
959
+ correlation_id=message_id,
960
+ )
961
+ )
962
+
885
963
  def __publish_bundle_swap(self, ui: RequenceUI[Any]):
886
964
  """The dev loop (#108): a rebuilt component is a **bundle swap**, not a
887
965
  render.
@@ -1064,10 +1142,19 @@ class Service:
1064
1142
  logger.warn("skipping callback ack: channel/connection closed")
1065
1143
 
1066
1144
  def __handle_durable_callback_invocation(self, body: bytes, content_type: str | None, delivery_tag: int, generation: int):
1145
+ # Held outside the try so the report below can still name the run and the
1146
+ # node when the failure came from the handler — the one thing a bare
1147
+ # ``except`` around the decode could not do.
1148
+ raw: Any = None
1067
1149
  try:
1068
- self.__run_durable_callback_invocation(decode_wire_body(body, content_type))
1069
- except Exception:
1150
+ raw = decode_wire_body(body, content_type)
1151
+ self.__run_durable_callback_invocation(raw)
1152
+ except Exception as error:
1153
+ # The traceback goes to this process's log, where whoever wrote the
1154
+ # handler is looking; the message goes on the run, where whoever wrote
1155
+ # the template is.
1070
1156
  logger.error("Requence: durable callback threw:", traceback.format_exc())
1157
+ self.__report_callback_failure(raw, error)
1071
1158
  finally:
1072
1159
  # Acked either way, and in a `finally` for the reason the handler
1073
1160
  # queue's is: a requeue would rerun a side-effecting callback forever,
@@ -1981,6 +2068,11 @@ class Service:
1981
2068
  "render": render
1982
2069
  }
1983
2070
 
2071
+ # Before the actor, so the row that closes the defer segment sits ahead of
2072
+ # everything the actor publishes — including work it does before its first
2073
+ # send, which is the whole stretch this exists to make measurable.
2074
+ self.__announce_resume(task_id, message_id)
2075
+
1984
2076
  result = actor(api)
1985
2077
 
1986
2078
  if inspect.isgenerator(result):
@@ -287,6 +287,19 @@ def is_durable_callback_invocation(data: Any) -> bool:
287
287
  )
288
288
 
289
289
 
290
+ # The header a durable callback FAILURE report is stamped with. The counterpart of
291
+ # the invocation header above, which covers one nobody consumed: this covers one
292
+ # that was consumed and could not be run — an unknown declaration name, or a
293
+ # handler that threw. Only the consuming instance can see either, and without this
294
+ # it says so in its own stdout and nowhere a template author looks.
295
+ DURABLE_CALLBACK_ERROR_HEADER: Final = "durableCallbackError"
296
+
297
+ # How long a reported durable callback failure may be. The same cut, for the same
298
+ # reason, as a surface interaction failure's: a thrown error's message is author
299
+ # text of no bounded length, and its first characters are where the cause is.
300
+ MAX_DURABLE_CALLBACK_ERROR_CHARS: Final = 500
301
+
302
+
290
303
  # ── Surfaces (mirrors packages/helpers/src/utils/{surfaceHandler,serviceRender,
291
304
  # uiRebuild}.ts) ─────────────────────────────────────────────────────────────
292
305
 
@@ -354,6 +367,18 @@ MAX_SURFACE_INTERACTION_ERROR_CHARS: Final = 500
354
367
  # dispatch buffer.
355
368
  UI_REBUILD_HEADER: Final = "uiRebuild"
356
369
 
370
+ # Marks a service message as ``act()`` announcing that it has re-attached to a
371
+ # deferred node (#271). Answered before a result is looked for, for the one reason
372
+ # the two headers above share: it carries **no index**, so it has no place in the
373
+ # ordered dispatch buffer. Unlike them it does belong to a message of the
374
+ # operator's — that is the whole of what it says — so it travels with a correlation
375
+ # id as well as the id in its body.
376
+ #
377
+ # Nothing else says a deferred run picked up again: ``act()`` publishes no
378
+ # ``begin``, and there is no ``defer`` on its actor API, so without this the defer
379
+ # runs to the end of the run and the work after it is invisible.
380
+ NODE_RESUME_HEADER: Final = "nodeResume"
381
+
357
382
 
358
383
  def service_handler_queue_name(dispatch_queue: str) -> str:
359
384
  """The per-version **handler queue**: where a durable invocation waits until
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: requence
3
- Version: 0.8.1.dev72
3
+ Version: 0.8.1.dev98
4
4
  Summary: Requence Service
5
5
  Author: Torsten Blindert
6
6
  Requires-Python: >=3.12
File without changes
File without changes