requence 0.8.1.dev67__tar.gz → 0.8.1.dev76__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.dev67/requence.egg-info → requence-0.8.1.dev76}/PKG-INFO +1 -1
  2. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/pyproject.toml +1 -1
  3. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/client_properties.py +45 -3
  4. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/__init__.py +83 -22
  5. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/wire.py +12 -0
  6. {requence-0.8.1.dev67 → requence-0.8.1.dev76/requence.egg-info}/PKG-INFO +1 -1
  7. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/tests/test_client_properties.py +108 -16
  8. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/MANIFEST.in +0 -0
  9. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/README.md +0 -0
  10. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/__init__.py +0 -0
  11. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/callbacks/__init__.py +0 -0
  12. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/callbacks/context.py +0 -0
  13. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/callbacks/handler.py +0 -0
  14. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/context.py +0 -0
  15. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/exceptions.py +0 -0
  16. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/__init__.py +0 -0
  17. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/errors.py +0 -0
  18. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/handlers/__init__.py +0 -0
  19. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/handlers/claim_check_handler.py +0 -0
  20. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/handlers/context.py +0 -0
  21. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/handlers/file_handler.py +0 -0
  22. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/handlers/stream_handler.py +0 -0
  23. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/pending_uploads.py +0 -0
  24. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/requence_file.py +0 -0
  25. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/requence_stream.py +0 -0
  26. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/sanitize_log_data.py +0 -0
  27. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/stream_framing.py +0 -0
  28. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/files/transport.py +0 -0
  29. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/internal_types.py +0 -0
  30. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/logger.py +0 -0
  31. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/obfuscase.py +0 -0
  32. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/py.typed +0 -0
  33. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/reachable.py +0 -0
  34. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/requence_callback.py +0 -0
  35. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/requence_file.py +0 -0
  36. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/requence_stream.py +0 -0
  37. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/boundary.py +0 -0
  38. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/callback_growth.py +0 -0
  39. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/cli.py +0 -0
  40. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/durable_callback.py +0 -0
  41. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/surface_handler.py +0 -0
  42. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/transformer.py +0 -0
  43. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/types.py +0 -0
  44. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/ui.py +0 -0
  45. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/service/ui_watch.py +0 -0
  46. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/store.py +0 -0
  47. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/__init__.py +0 -0
  48. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/abort_task.py +0 -0
  49. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/ack_task.py +0 -0
  50. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/cli.py +0 -0
  51. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/get_task.py +0 -0
  52. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/ingress.py +0 -0
  53. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/protect_task.py +0 -0
  54. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/task.py +0 -0
  55. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/task_watcher.py +0 -0
  56. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/types.py +0 -0
  57. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/updates.py +0 -0
  58. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/task/utils.py +0 -0
  59. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/__init__.py +0 -0
  60. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/context.py +0 -0
  61. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/errors.py +0 -0
  62. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/guards.py +0 -0
  63. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/message_handler.py +0 -0
  64. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/transform.py +0 -0
  65. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/value_handler.py +0 -0
  66. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/transformer/walk.py +0 -0
  67. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/utils.py +0 -0
  68. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence/wire_codec.py +0 -0
  69. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence.egg-info/SOURCES.txt +0 -0
  70. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence.egg-info/dependency_links.txt +0 -0
  71. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence.egg-info/entry_points.txt +0 -0
  72. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence.egg-info/requires.txt +0 -0
  73. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/requence.egg-info/top_level.txt +0 -0
  74. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/setup.cfg +0 -0
  75. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/tests/test_logger.py +0 -0
  76. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/tests/test_store_parity.py +0 -0
  77. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/tests/test_wire.py +0 -0
  78. {requence-0.8.1.dev67 → requence-0.8.1.dev76}/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.dev67
3
+ Version: 0.8.1.dev76
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.dev67"
7
+ version = "0.8.1.dev76"
8
8
  description = "Requence Service"
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  authors = [{ name = "Torsten Blindert" }]
@@ -41,6 +41,16 @@ CLIENT_PROPERTY_KEYS = {
41
41
  # Marks a developer's local dev-overlay connection. Only the marker travels,
42
42
  # never the devKey (which is an access-token value).
43
43
  "devOverlay": "requence_dev_overlay",
44
+ # WHICH PROCESS this is. Not a new id: it is the same per-connection uuid the
45
+ # SDK already stamps on every publish (and names its backchannel queue with),
46
+ # announced here so a fleet row and a node run can be joined on it. This SDK
47
+ # mints a fresh one per broker connection, where the TS SDK keeps its id
48
+ # across a reconnect — a deliberate difference, not a bug.
49
+ "connectionId": "requence_connection_id",
50
+ # How many task slots this process has: the consumer prefetch of its DISPATCH
51
+ # channel. The surface-handler and durable-callback channels each get their
52
+ # own budget of the same number, so this is NOT the replica's whole capacity.
53
+ "prefetch": "requence_prefetch",
44
54
  }
45
55
 
46
56
  # The name is author-controlled text and the whole client-properties table
@@ -69,19 +79,29 @@ def build_service_client_properties(
69
79
  *,
70
80
  lib_version: str,
71
81
  service_version: str,
82
+ connection_id: str,
83
+ prefetch: int,
72
84
  name: Optional[str] = None,
73
85
  dev_overlay: bool = False,
74
86
  capabilities: Optional[Iterable[str]] = None,
75
87
  ) -> Dict[str, str]:
76
88
  """Build the properties handed to pika on connect (and therefore on every
77
89
  reconnect, since the connection parameters are reused). Absent optional
78
- fields are OMITTED, never sent blank."""
90
+ fields are OMITTED, never sent blank.
91
+
92
+ ``connection_id`` and ``prefetch`` are REQUIRED, mirroring the TS contract:
93
+ both are known at connect time in every SDK, so a forgetful one should fail
94
+ loudly rather than announce a replica nothing can join."""
79
95
  if capabilities is None:
80
96
  capabilities = SERVICE_WIRE_CAPABILITIES
81
97
 
82
98
  properties: Dict[str, str] = {
83
99
  CLIENT_PROPERTY_KEYS["libVersion"]: lib_version,
84
100
  CLIENT_PROPERTY_KEYS["serviceVersion"]: service_version,
101
+ CLIENT_PROPERTY_KEYS["connectionId"]: connection_id,
102
+ # Stringified, like every other value here: the table is flat strings on
103
+ # purpose. The read side (ui/backend) decides whether it is usable.
104
+ CLIENT_PROPERTY_KEYS["prefetch"]: str(prefetch),
85
105
  CLIENT_PROPERTY_KEYS["capabilities"]: ",".join(capabilities)[
86
106
  :MAX_CAPABILITIES_LENGTH
87
107
  ],
@@ -99,7 +119,7 @@ def build_service_client_properties(
99
119
 
100
120
  # ─── The second announcement: per-run identity on the begin message ──────────
101
121
  #
102
- # The same three values as above, sent again on the ``begin`` publish, because
122
+ # Mostly the same values as above, sent again on the ``begin`` publish, because
103
123
  # they answer a DIFFERENT question: the client properties say "can this fleet
104
124
  # decode msgpack?" (live, folded to the minimum, available before dispatch),
105
125
  # these say "which build ran THIS node?" (exact, frozen into the NODE_START
@@ -111,22 +131,44 @@ IDENTITY_HEADER_KEYS = {
111
131
  "libVersion": "libVersion",
112
132
  "name": "serviceName",
113
133
  "capabilities": "capabilities",
134
+ # READ-ONLY, and the only asymmetry in this dict: every other key here is
135
+ # both built and read, but ``build_service_identity_headers`` does NOT emit
136
+ # this one. The base publish header block already stamps ``connectionId`` on
137
+ # EVERY message, begin included, so emitting it again would write the same
138
+ # value twice into one header table. It is listed here so ui/backend's reader
139
+ # picks it up — and so the key-name parity test covers the name.
140
+ "connectionId": "connectionId",
141
+ # Does THIS run occupy one of the consumer's dispatch prefetch slots — i.e.
142
+ # does its message stay unacked while the work runs? Per run, not per
143
+ # replica. Emitted by the builder (unlike ``connectionId``), because it is
144
+ # new.
145
+ "holdsSlot": "holdsSlot",
114
146
  }
115
147
 
116
148
 
117
149
  def build_service_identity_headers(
118
150
  *,
119
151
  lib_version: str,
152
+ holds_slot: bool,
120
153
  name: Optional[str] = None,
121
154
  capabilities: Optional[Iterable[str]] = None,
122
155
  ) -> Dict[str, str]:
123
156
  """Headers the service stamps on its own ``begin`` publish, built from this
124
- process's own constants — nothing is looked up, so nothing can be stale."""
157
+ process's own constants — nothing is looked up, so nothing can be stale.
158
+
159
+ ``holds_slot`` is ``not (is_generator and mode == 'CONTINUOUS')`` at every
160
+ call site: that one combination acks immediately and frees its slot, every
161
+ other stays unacked until the work is done."""
125
162
  if capabilities is None:
126
163
  capabilities = SERVICE_WIRE_CAPABILITIES
127
164
 
128
165
  headers: Dict[str, str] = {
129
166
  IDENTITY_HEADER_KEYS["libVersion"]: lib_version,
167
+ # ALWAYS sent, breaking this module's "absent optional fields are
168
+ # OMITTED" rule on purpose: omitting False would make it
169
+ # indistinguishable from an SDK too old to report, and those two answers
170
+ # are not the same.
171
+ IDENTITY_HEADER_KEYS["holdsSlot"]: "1" if holds_slot else "0",
130
172
  IDENTITY_HEADER_KEYS["capabilities"]: ",".join(capabilities)[
131
173
  :MAX_CAPABILITIES_LENGTH
132
174
  ],
@@ -25,6 +25,7 @@ from ..wire import (
25
25
  DEFAULT_SURFACE_ID,
26
26
  DURABLE_CALLBACK_QUEUE_ARGUMENTS,
27
27
  MAX_SURFACE_INTERACTION_ERROR_CHARS,
28
+ NODE_RESUME_HEADER,
28
29
  REFERENCE_TAG_KEY,
29
30
  SURFACE_HANDLER_QUEUE_ARGUMENTS,
30
31
  SURFACE_HANDLER_TAG,
@@ -372,16 +373,11 @@ class Service:
372
373
  if heartbeat_interval is not None:
373
374
  parameters.heartbeat = heartbeat_interval
374
375
 
375
- # Who we are, what we run, what we can decode — declared in the AMQP
376
- # connection frame so ui/backend knows it BEFORE the first dispatch. pika
377
- # merges these over its own defaults, and the parameters are reused on
378
- # every reconnect, so the announcement re-lands automatically.
379
- parameters.client_properties = build_service_client_properties(
380
- lib_version=libVersion,
381
- service_version=version,
382
- name=service_config.get("name"),
383
- dev_overlay=dev_overlay is not None,
384
- )
376
+ # The client properties are NOT built here: they carry this connection's
377
+ # own uuid, and `__connection_id` is minted per broker connection (see
378
+ # `__connect_and_consume`), so a table frozen at configure time would
379
+ # announce the id of a connection that no longer exists. It is rebuilt
380
+ # immediately before every connect instead.
385
381
 
386
382
  if not parameters.credentials:
387
383
  raise ValueError("Url connection string needs a username")
@@ -389,8 +385,8 @@ class Service:
389
385
  self.__parameters = parameters
390
386
  self.__version = version
391
387
  # Author-chosen debugging label. Announced twice — in the client
392
- # properties above (fleet view) and on every begin publish (per-run
393
- # identity) — from this one value, so the two can never disagree.
388
+ # properties (fleet view) and on every begin publish (per-run identity)
389
+ # — from this one value, so the two can never disagree.
394
390
  self.__name = service_config.get("name")
395
391
  self.__prefetch = prefetch
396
392
  self.__dev_overlay = dev_overlay
@@ -400,12 +396,16 @@ class Service:
400
396
  f"{self.__base_queue}-dev-overlay-{dev_overlay}" if dev_overlay else self.__base_queue
401
397
  )
402
398
  self.__on_message_callback = on_message_callback
403
- # A property of the HANDLER, decided once: only a generator handler can
404
- # hold a registration past the call that made it. Same rule for render
405
- # props — a function written inline at `context.render` dies when a
406
- # non-generator handler returns, so it is refused rather than published
407
- # (see `__handle_message`).
408
- self.__can_register_callbacks = inspect.isgeneratorfunction(on_message_callback)
399
+ # A property of the HANDLER, decided once. Two independent things are
400
+ # decided by it, so it is held under its own name rather than either of
401
+ # them borrowing the other's: whether a callback registration can outlive
402
+ # the call that made it, and whether a CONTINUOUS run holds a task slot.
403
+ self.__is_generator_handler = inspect.isgeneratorfunction(on_message_callback)
404
+ # Only a generator handler can hold a registration past the call that
405
+ # made it. Same rule for render props — a function written inline at
406
+ # `context.render` dies when a non-generator handler returns, so it is
407
+ # refused rather than published (see `__handle_message`).
408
+ self.__can_register_callbacks = self.__is_generator_handler
409
409
 
410
410
  # The dev session this connection belongs to (#108), or '' outside dev
411
411
  # mode.
@@ -503,9 +503,28 @@ class Service:
503
503
  """Open a connection, (re)declare the topology, and block in
504
504
  start_consuming until the connection drops (raises) or close() stops it
505
505
  (returns normally)."""
506
+ # Minted BEFORE the connect, because the announcement carries it. This
507
+ # SDK gives every broker connection a fresh id (the TS SDK keeps one
508
+ # across a reconnect) — accepted, not aligned: both give a correct join
509
+ # at any instant, and in-flight work does not survive a reconnect either
510
+ # way, so an id that outlived the connection would buy nothing.
511
+ self.__connection_id = str(uuid4())
512
+
513
+ # Who we are, what we run, what we can decode, WHICH process this is and
514
+ # how many task slots it has — declared in the AMQP connection frame so
515
+ # ui/backend knows it BEFORE the first dispatch. Rebuilt per connect, not
516
+ # once at configure time, precisely because the id above is.
517
+ self.__parameters.client_properties = build_service_client_properties(
518
+ lib_version=libVersion,
519
+ service_version=self.__version,
520
+ connection_id=self.__connection_id,
521
+ prefetch=self.__prefetch,
522
+ name=self.__name,
523
+ dev_overlay=self.__dev_overlay is not None,
524
+ )
525
+
506
526
  connection = pika.BlockingConnection(self.__parameters)
507
527
 
508
- self.__connection_id = str(uuid4())
509
528
  backchannel_queue = f"{self.__base_queue}-backchannel-{self.__connection_id}"
510
529
 
511
530
  channel = connection.channel()
@@ -809,11 +828,15 @@ class Service:
809
828
  headers: dict[str, Any],
810
829
  failure_label: str,
811
830
  announce: Optional[str] = None,
831
+ correlation_id: Optional[str] = None,
812
832
  ):
813
833
  """A publish on the ordinary result exchange that is NOT a result for any
814
- dispatch: no correlation id, no index, no place in the ordered dispatch
815
- buffer. The operator answers these messages' marker headers before it looks
816
- for either.
834
+ dispatch: no index and no place in the ordered dispatch buffer. The operator
835
+ answers these messages' marker headers before it looks for either.
836
+
837
+ ``correlation_id`` is for the one of these that does belong to a message: a
838
+ resume announcement (#271) names the run it re-attached to. The other two
839
+ belong to no message at all and pass none.
817
840
 
818
841
  Always JSON, unlike a reply: there is no dispatch here whose codec could be
819
842
  echoed. Encoded through ``wire_codec`` all the same, so the SDK keeps its one
@@ -831,6 +854,7 @@ class Service:
831
854
  properties=pika.BasicProperties(
832
855
  content_type=content_type,
833
856
  delivery_mode=pika.DeliveryMode.Persistent,
857
+ correlation_id=correlation_id,
834
858
  headers=headers,
835
859
  ),
836
860
  )
@@ -864,6 +888,32 @@ class Service:
864
888
  )
865
889
  )
866
890
 
891
+ def __announce_resume(self, task_id: str, message_id: str):
892
+ """Say that this process has re-attached to a deferred node (#271) — the
893
+ moment the node starts working again.
894
+
895
+ Nobody else can say it. The operator dispatched this message days ago and
896
+ hears nothing when someone picks it up: ``act()`` publishes no ``begin``,
897
+ and there is no ``defer`` on its actor API, so a run defers at most once and
898
+ without this the defer runs to the end of the run. A form deferred three
899
+ days whose handler then spends four minutes building a PDF reported one
900
+ second of work.
901
+
902
+ Carries **no index**, which is why it is a side channel at all: the
903
+ announcement takes no place in the message's ordered output stream, and a
904
+ ``begin`` — the other way to say this — lands on the operator's
905
+ begin-rewind, which resets a deferred message's index space and is what
906
+ keeps a re-attach's render from being discarded as a duplicate."""
907
+ self.__schedule(
908
+ functools.partial(
909
+ self.__publish_side_channel,
910
+ {"messageId": message_id},
911
+ {"taskId": task_id, NODE_RESUME_HEADER: True},
912
+ f"announce the resume of message |{message_id}|",
913
+ correlation_id=message_id,
914
+ )
915
+ )
916
+
867
917
  def __publish_bundle_swap(self, ui: RequenceUI[Any]):
868
918
  """The dev loop (#108): a rebuilt component is a **bundle swap**, not a
869
919
  render.
@@ -1558,6 +1608,12 @@ class Service:
1558
1608
  **build_service_identity_headers(
1559
1609
  lib_version=libVersion,
1560
1610
  name=self.__name,
1611
+ # Read the ack decision below: a CONTINUOUS generator acks
1612
+ # straight away and frees its slot, so its run holds none.
1613
+ # Every other combination stays unacked until the work is
1614
+ # done. ui/backend cannot derive this — it knows the mode
1615
+ # from the node but not whether the author wrote a generator.
1616
+ holds_slot=not (self.__is_generator_handler and mode == 'CONTINUOUS'),
1561
1617
  ),
1562
1618
  })
1563
1619
 
@@ -1957,6 +2013,11 @@ class Service:
1957
2013
  "render": render
1958
2014
  }
1959
2015
 
2016
+ # Before the actor, so the row that closes the defer segment sits ahead of
2017
+ # everything the actor publishes — including work it does before its first
2018
+ # send, which is the whole stretch this exists to make measurable.
2019
+ self.__announce_resume(task_id, message_id)
2020
+
1960
2021
  result = actor(api)
1961
2022
 
1962
2023
  if inspect.isgenerator(result):
@@ -354,6 +354,18 @@ MAX_SURFACE_INTERACTION_ERROR_CHARS: Final = 500
354
354
  # dispatch buffer.
355
355
  UI_REBUILD_HEADER: Final = "uiRebuild"
356
356
 
357
+ # Marks a service message as ``act()`` announcing that it has re-attached to a
358
+ # deferred node (#271). Answered before a result is looked for, for the one reason
359
+ # the two headers above share: it carries **no index**, so it has no place in the
360
+ # ordered dispatch buffer. Unlike them it does belong to a message of the
361
+ # operator's — that is the whole of what it says — so it travels with a correlation
362
+ # id as well as the id in its body.
363
+ #
364
+ # Nothing else says a deferred run picked up again: ``act()`` publishes no
365
+ # ``begin``, and there is no ``defer`` on its actor API, so without this the defer
366
+ # runs to the end of the run and the work after it is invisible.
367
+ NODE_RESUME_HEADER: Final = "nodeResume"
368
+
357
369
 
358
370
  def service_handler_queue_name(dispatch_queue: str) -> str:
359
371
  """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.dev67
3
+ Version: 0.8.1.dev76
4
4
  Summary: Requence Service
5
5
  Author: Torsten Blindert
6
6
  Requires-Python: >=3.12
@@ -27,6 +27,10 @@ from requence.client_properties import (
27
27
  unsupported_capability_message,
28
28
  )
29
29
 
30
+ # One connection's own uuid — the value both announcements carry, and the join
31
+ # key between a fleet row and a node run.
32
+ CONNECTION_ID = "b1a2c3d4-0b1e-4f26-9b1b-2c3d4e5f6071"
33
+
30
34
  TS_CONTRACT = (
31
35
  Path(__file__).resolve().parents[2]
32
36
  / "packages"
@@ -114,30 +118,74 @@ class TestParityWithTheTsContract:
114
118
 
115
119
 
116
120
  class TestBuildServiceClientProperties:
117
- def test_declares_lib_version_service_version_and_capabilities(self):
121
+ def test_declares_lib_version_service_version_identity_slots_and_capabilities(self):
118
122
  assert build_service_client_properties(
119
- lib_version="python@1.2.3", service_version="v1"
123
+ lib_version="python@1.2.3",
124
+ service_version="v1",
125
+ connection_id=CONNECTION_ID,
126
+ prefetch=4,
120
127
  ) == {
121
128
  "requence_lib_version": "python@1.2.3",
122
129
  "requence_service_version": "v1",
130
+ "requence_connection_id": CONNECTION_ID,
131
+ "requence_prefetch": "4",
123
132
  "requence_capabilities": "wire:json1,wire:msgpack1",
124
133
  }
125
134
 
135
+ def test_announces_the_connection_id_the_sdk_already_publishes_with(self):
136
+ # NOT a second uuid: the same value that names the backchannel queue and
137
+ # rides on every publish, so a fleet row and a node run join on it.
138
+ properties = build_service_client_properties(
139
+ lib_version="python@1.2.3",
140
+ service_version="v1",
141
+ connection_id=CONNECTION_ID,
142
+ prefetch=1,
143
+ )
144
+ assert properties["requence_connection_id"] == CONNECTION_ID
145
+
146
+ def test_announces_the_prefetch_as_a_flat_string(self):
147
+ properties = build_service_client_properties(
148
+ lib_version="python@1.2.3",
149
+ service_version="v1",
150
+ connection_id=CONNECTION_ID,
151
+ prefetch=12,
152
+ )
153
+ assert properties["requence_prefetch"] == "12"
154
+
155
+ def test_the_connection_id_and_prefetch_are_required(self):
156
+ # Both are known at connect time, so a forgetful SDK should fail loudly
157
+ # rather than announce a replica nothing can join.
158
+ with pytest.raises(TypeError):
159
+ build_service_client_properties(
160
+ lib_version="python@1.2.3", service_version="v1"
161
+ )
162
+
126
163
  def test_omits_the_name_when_it_is_not_set(self):
127
164
  properties = build_service_client_properties(
128
- lib_version="python@1.2.3", service_version="v1"
165
+ lib_version="python@1.2.3",
166
+ service_version="v1",
167
+ connection_id=CONNECTION_ID,
168
+ prefetch=4,
129
169
  )
130
170
  assert "requence_name" not in properties
131
171
 
132
172
  def test_omits_a_blank_name(self):
133
173
  properties = build_service_client_properties(
134
- lib_version="python@1.2.3", service_version="v1", name=" "
174
+ lib_version="python@1.2.3",
175
+ service_version="v1",
176
+ connection_id=CONNECTION_ID,
177
+ prefetch=4,
178
+ name=" ",
135
179
  )
136
180
  assert "requence_name" not in properties
137
181
 
138
182
  def test_publishes_a_trimmed_name(self):
139
183
  properties = build_service_client_properties(
140
- lib_version="python@1.2.3", service_version="v1", name=" eu-west worker "
184
+ lib_version="python@1.2.3",
185
+ service_version="v1",
186
+ connection_id=CONNECTION_ID,
187
+ prefetch=4,
188
+ name=" eu-west worker ",
141
189
  )
142
190
  assert properties["requence_name"] == "eu-west worker"
143
191
 
@@ -145,25 +193,38 @@ class TestBuildServiceClientProperties:
145
193
  properties = build_service_client_properties(
146
194
  lib_version="python@1.2.3",
147
195
  service_version="v1",
196
+ connection_id=CONNECTION_ID,
197
+ prefetch=4,
148
198
  name="x" * (MAX_SERVICE_NAME_LENGTH + 50),
149
199
  )
150
200
  assert len(properties["requence_name"]) == MAX_SERVICE_NAME_LENGTH
151
201
 
152
202
  def test_strips_control_characters_from_the_name(self):
153
203
  properties = build_service_client_properties(
154
- lib_version="python@1.2.3", service_version="v1", name="a\u0000b c"
204
+ lib_version="python@1.2.3",
205
+ service_version="v1",
206
+ connection_id=CONNECTION_ID,
207
+ prefetch=4,
208
+ name="a\u0000b c",
155
209
  )
156
210
  assert properties["requence_name"] == "ab c"
157
211
 
158
212
  def test_marks_a_dev_overlay_without_leaking_the_dev_key(self):
159
213
  properties = build_service_client_properties(
160
- lib_version="python@1.2.3", service_version="v1", dev_overlay=True
214
+ lib_version="python@1.2.3",
215
+ service_version="v1",
216
+ connection_id=CONNECTION_ID,
217
+ prefetch=4,
218
+ dev_overlay=True,
161
219
  )
162
220
  assert properties["requence_dev_overlay"] == "1"
163
221
 
164
222
  def test_omits_the_dev_overlay_marker_for_a_normal_replica(self):
165
223
  properties = build_service_client_properties(
166
- lib_version="python@1.2.3", service_version="v1"
224
+ lib_version="python@1.2.3",
225
+ service_version="v1",
226
+ connection_id=CONNECTION_ID,
227
+ prefetch=4,
167
228
  )
168
229
  assert "requence_dev_overlay" not in properties
169
230
 
@@ -176,6 +237,8 @@ class TestBuildServiceClientProperties:
176
237
  properties = build_service_client_properties(
177
238
  lib_version="python@1.2.3",
178
239
  service_version="v1",
240
+ connection_id=CONNECTION_ID,
241
+ prefetch=4,
179
242
  name="label",
180
243
  dev_overlay=True,
181
244
  )
@@ -184,43 +247,72 @@ class TestBuildServiceClientProperties:
184
247
 
185
248
  class TestBuildServiceIdentityHeaders:
186
249
  def test_stamps_lib_version_and_capabilities(self):
187
- assert build_service_identity_headers(lib_version="python@0.8.0") == {
250
+ assert build_service_identity_headers(
251
+ lib_version="python@0.8.0", holds_slot=True
252
+ ) == {
188
253
  "libVersion": "python@0.8.0",
254
+ "holdsSlot": "1",
189
255
  "capabilities": "wire:json1,wire:msgpack1",
190
256
  }
191
257
 
258
+ def test_sends_the_slot_flag_even_when_the_run_holds_none(self):
259
+ # Breaks the module's "absent optional fields are OMITTED" rule on
260
+ # purpose: omitting would make "holds no slot" and "too old to report"
261
+ # the same value, and those must stay distinguishable.
262
+ headers = build_service_identity_headers(
263
+ lib_version="python@0.8.0", holds_slot=False
264
+ )
265
+ assert headers["holdsSlot"] == "0"
266
+
267
+ def test_never_emits_the_connection_id(self):
268
+ # The one read-only key in IDENTITY_HEADER_KEYS: the base publish header
269
+ # block already stamps `connectionId` on EVERY message, begin included.
270
+ headers = build_service_identity_headers(
271
+ lib_version="python@0.8.0", holds_slot=True
272
+ )
273
+ assert "connectionId" not in headers
274
+
275
+ def test_the_slot_flag_is_required(self):
276
+ with pytest.raises(TypeError):
277
+ build_service_identity_headers(lib_version="python@0.8.0")
278
+
192
279
  def test_omits_the_name_when_it_is_not_set(self):
193
280
  assert "serviceName" not in build_service_identity_headers(
194
- lib_version="python@0.8.0"
281
+ lib_version="python@0.8.0", holds_slot=True
195
282
  )
196
283
 
197
284
  def test_announces_a_name(self):
198
285
  headers = build_service_identity_headers(
199
- lib_version="python@0.8.0", name="batch-box"
286
+ lib_version="python@0.8.0", holds_slot=True, name="batch-box"
200
287
  )
201
288
  assert headers["serviceName"] == "batch-box"
202
289
 
203
290
  def test_caps_and_sanitizes_the_name(self):
204
291
  headers = build_service_identity_headers(
205
292
  lib_version="python@0.8.0",
293
+ holds_slot=True,
206
294
  name=" " + "q" * (MAX_SERVICE_NAME_LENGTH + 20) + " ",
207
295
  )
208
296
  assert len(headers["serviceName"]) == MAX_SERVICE_NAME_LENGTH
209
297
 
210
298
  def test_emits_only_flat_strings(self):
211
299
  headers = build_service_identity_headers(
212
- lib_version="python@0.8.0", name="batch-box"
300
+ lib_version="python@0.8.0", holds_slot=False, name="batch-box"
213
301
  )
214
302
  assert all(isinstance(value, str) for value in headers.values())
215
303
 
216
304
  def test_matches_what_the_connection_announces(self):
217
- # Same three values, one source of truth per process — the two
218
- # announcements can never disagree.
305
+ # The values both announcements carry, from one source of truth per
306
+ # process — the two can never disagree.
219
307
  properties = build_service_client_properties(
220
- lib_version="python@0.8.0", service_version="v1", name="batch-box"
308
+ lib_version="python@0.8.0",
309
+ service_version="v1",
310
+ connection_id=CONNECTION_ID,
311
+ prefetch=4,
312
+ name="batch-box",
221
313
  )
222
314
  headers = build_service_identity_headers(
223
- lib_version="python@0.8.0", name="batch-box"
315
+ lib_version="python@0.8.0", holds_slot=True, name="batch-box"
224
316
  )
225
317
  assert headers["libVersion"] == properties["requence_lib_version"]
226
318
  assert headers["serviceName"] == properties["requence_name"]
File without changes
File without changes