continuum-task-server-sdk 1.5.0__tar.gz → 1.7.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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: continuum-task-server-sdk
3
- Version: 1.5.0
3
+ Version: 1.7.0
4
4
  Summary: Python SDK for the Continuum Task Server
5
5
  Project-URL: Homepage, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python
6
6
  Project-URL: Issues, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python/issues
@@ -77,4 +77,4 @@ __all__ = [
77
77
  "WorkSubscriptionResult",
78
78
  ]
79
79
 
80
- __version__ = "1.4.0"
80
+ __version__ = "1.6.2"
@@ -11,7 +11,7 @@ from uuid import UUID
11
11
  import httpx
12
12
 
13
13
  from ._http import HttpClient, drop_none
14
- from .exceptions import ContinuumError
14
+ from .exceptions import ContinuumError, error_for_status
15
15
  from .models import (
16
16
  Content,
17
17
  QueueDescendantsCancelResult,
@@ -23,6 +23,21 @@ from .models import (
23
23
  )
24
24
 
25
25
 
26
+ def _id_from(body: Any, object_name: str, missing_message: str, bad_id_message: str) -> UUID:
27
+ if isinstance(body, dict) and body.get("status") not in (None, 0):
28
+ status = int(body["status"])
29
+ message = body.get("message")
30
+ raise error_for_status(status, "" if message is None else str(message))
31
+ node = body.get(object_name) if isinstance(body, dict) else None
32
+ raw = node.get("id") if isinstance(node, dict) else None
33
+ if raw is None or raw == "":
34
+ raise ContinuumError(missing_message)
35
+ try:
36
+ return UUID(str(raw))
37
+ except ValueError as ex:
38
+ raise ContinuumError(bad_id_message) from ex
39
+
40
+
26
41
  def _encode_input(data: Any) -> str | None:
27
42
  """Accept dict/list/str/None and return a JSON string (or None)."""
28
43
  if data is None:
@@ -240,8 +255,15 @@ class QueueApi:
240
255
  priority: int | None = None,
241
256
  parent_id: UUID | str | None = None,
242
257
  idempotency_token: str | None = None,
258
+ layer: str | None = None,
259
+ strict_layer: bool | None = None,
260
+ actor_event_id: UUID | str | None = None,
243
261
  ) -> QueueItem:
244
- """Add a queue item. At least one of task_name or task_item_name is required."""
262
+ """Add a queue item. At least one of task_name or task_item_name is required.
263
+
264
+ ``actor_event_id`` is the actor event that started this child. It is omitted
265
+ for an ordinary enqueue.
266
+ """
245
267
  if task_name is None and task_item_name is None:
246
268
  raise ValueError("at least one of task_name or task_item_name is required")
247
269
  body = drop_none(
@@ -252,6 +274,9 @@ class QueueApi:
252
274
  "priority": priority,
253
275
  "inputData": _encode_input(input_data),
254
276
  "idempotencyToken": idempotency_token,
277
+ "layer": layer,
278
+ "strictLayer": strict_layer,
279
+ "actorEventId": str(actor_event_id) if actor_event_id else None,
255
280
  }
256
281
  )
257
282
  return QueueItem.model_validate(self._http.post_json(self._MGMT, body))
@@ -266,9 +291,11 @@ class QueueApi:
266
291
  data, mime = result
267
292
  return Content(data=data, mime_type=mime)
268
293
 
269
- def claim(self, task_name: str) -> QueueItem | None:
294
+ def claim(self, task_name: str, *, layer: str | None = None) -> QueueItem | None:
270
295
  """Claim one OPEN queue item for the given task name. Returns None if none available."""
271
- result = self._http.post_optional(f"{self._QUEUE}/claim", {"taskName": task_name})
296
+ result = self._http.post_optional(
297
+ f"{self._QUEUE}/claim", drop_none({"taskName": task_name, "layer": layer})
298
+ )
272
299
  if result is None:
273
300
  return None
274
301
  return QueueItem.model_validate(result)
@@ -412,6 +439,60 @@ class ContinuumClient:
412
439
  """Attach the secret from task-server registration. Blank clears it."""
413
440
  self._http.set_task_server_token(token)
414
441
 
442
+ def register_data_subscription(
443
+ self,
444
+ layer: str | None = None,
445
+ strict_layer: bool | None = None,
446
+ subject: str | None = None,
447
+ filter: Any = None,
448
+ delivery_kind: str | None = None,
449
+ actor_instance_id: UUID | str | None = None,
450
+ task_item_id: UUID | str | None = None,
451
+ ) -> UUID:
452
+ """POST /api/data-subscriptions. None arguments are omitted. False is sent."""
453
+ body = drop_none(
454
+ {
455
+ "layer": layer,
456
+ "strictLayer": strict_layer,
457
+ "subject": subject,
458
+ "filter": filter,
459
+ "deliveryKind": delivery_kind,
460
+ "actorInstanceId": None if actor_instance_id is None else str(actor_instance_id),
461
+ "taskItemId": None if task_item_id is None else str(task_item_id),
462
+ }
463
+ )
464
+ return _id_from(
465
+ self._http.post_json("/api/data-subscriptions", body),
466
+ "subscription",
467
+ "registerDataSubscription succeeded without a subscription id",
468
+ "registerDataSubscription subscription id is not a UUID",
469
+ )
470
+
471
+ def insert_ingress_event(
472
+ self,
473
+ task_server_id: UUID | str | None = None,
474
+ source: str | None = None,
475
+ source_message_id: str | None = None,
476
+ address: Any = None,
477
+ payload: Any = None,
478
+ ) -> UUID:
479
+ """POST /api/ingress-events. None arguments are omitted."""
480
+ body = drop_none(
481
+ {
482
+ "taskServerId": None if task_server_id is None else str(task_server_id),
483
+ "source": source,
484
+ "sourceMessageId": source_message_id,
485
+ "address": address,
486
+ "payload": payload,
487
+ }
488
+ )
489
+ return _id_from(
490
+ self._http.post_json("/api/ingress-events", body),
491
+ "event",
492
+ "insertIngressEvent succeeded without an ingress event id",
493
+ "insertIngressEvent event id is not a UUID",
494
+ )
495
+
415
496
  def post_raw(self, path: str, body: Any) -> Any:
416
497
  return self._http.post_json(path, body)
417
498
 
@@ -37,12 +37,14 @@ class TaskServerPresence:
37
37
  instance_id: str | None,
38
38
  labels: dict[str, str] | None,
39
39
  task_names: Callable[[], Iterable[str]],
40
+ layer: str | None = None,
40
41
  ) -> None:
41
42
  self._client = client
42
43
  self._name = name or None
43
44
  self._instance_id = instance_id or str(uuid.uuid4())
44
45
  self._labels = _labels(labels)
45
46
  self._task_names = task_names
47
+ self._layer = layer.strip() if isinstance(layer, str) and layer.strip() else None
46
48
  self._enabled = True
47
49
  self._stopped = threading.Event()
48
50
  self._token: str | None = None
@@ -111,6 +113,7 @@ class TaskServerPresence:
111
113
  "name": self._name,
112
114
  "taskNames": list(self._task_names()),
113
115
  "labels": self._labels,
116
+ "layer": self._layer,
114
117
  }
115
118
  try:
116
119
  payload = self._client.post_raw(_PATH, body) or {}
@@ -97,6 +97,7 @@ class TaskServer:
97
97
  labels: dict[str, str] | None = None,
98
98
  instance_id: str | None = None,
99
99
  presence: bool = True,
100
+ layer: str | None = None,
100
101
  ) -> None:
101
102
  http_transport: httpx.BaseTransport | None = None
102
103
  if isinstance(transport, httpx.BaseTransport):
@@ -134,6 +135,7 @@ class TaskServer:
134
135
  self._base_url = base_url
135
136
  self._api_key = api_key
136
137
  self._active: dict[uuid.UUID, _ActiveClaim] = {}
138
+ self._layer = layer.strip() if isinstance(layer, str) and layer.strip() else None
137
139
  self._presence = (
138
140
  TaskServerPresence(
139
141
  self._client,
@@ -141,6 +143,7 @@ class TaskServer:
141
143
  instance_id=instance_id,
142
144
  labels=labels,
143
145
  task_names=self._handlers.keys,
146
+ layer=self._layer,
144
147
  )
145
148
  if presence
146
149
  else None
@@ -364,7 +367,8 @@ class TaskServer:
364
367
  ws = self._ensure_websocket()
365
368
  ws.connect()
366
369
  for name in self._handlers:
367
- ws.subscribe_work(name)
370
+ ws.set_layer(self._layer)
371
+ ws.subscribe_work(name, layer=self._layer)
368
372
  logger.info("WebSocket subscribed to work: %s", list(self._handlers))
369
373
  while not self._stop_event.is_set():
370
374
  event = ws.next_event(timeout=0.25)
@@ -654,19 +658,19 @@ class TaskServer:
654
658
 
655
659
  def _claim_http(self, task_name: str) -> QueueItem | None:
656
660
  try:
657
- return self._client.queue.claim(task_name)
661
+ return self._client.queue.claim(task_name, layer=self._layer)
658
662
  except ConflictError:
659
663
  if self._presence is None or not self._presence.reregister():
660
664
  raise
661
- return self._client.queue.claim(task_name)
665
+ return self._client.queue.claim(task_name, layer=self._layer)
662
666
 
663
667
  def _claim_socket(self, ws: ContinuumWebSocketClient, task_name: str) -> QueueItem | None:
664
668
  try:
665
- return ws.claim(task_name)
669
+ return ws.claim(task_name, layer=self._layer)
666
670
  except ConflictError:
667
671
  if self._presence is None or not self._presence.reregister():
668
672
  raise
669
- return ws.claim(task_name)
673
+ return ws.claim(task_name, layer=self._layer)
670
674
 
671
675
  def _drain(self) -> None:
672
676
  if self._executor is None:
@@ -39,6 +39,20 @@ from .models import (
39
39
 
40
40
  logger = logging.getLogger("continuum_task_server")
41
41
 
42
+
43
+ def _reply_id(
44
+ body: dict[str, Any], object_name: str, missing_message: str, bad_id_message: str
45
+ ) -> UUID:
46
+ node = body.get(object_name) if isinstance(body, dict) else None
47
+ raw = node.get("id") if isinstance(node, dict) else None
48
+ if raw is None or raw == "":
49
+ raise ContinuumError(missing_message)
50
+ try:
51
+ return UUID(str(raw))
52
+ except ValueError as ex:
53
+ raise ContinuumError(bad_id_message) from ex
54
+
55
+
42
56
  Connector = Callable[[str, dict[str, str], float], "SocketLike"]
43
57
  EventCallback = Callable[[QueueEvent], None]
44
58
 
@@ -127,6 +141,7 @@ class ContinuumWebSocketClient:
127
141
  self._events_cv = threading.Condition()
128
142
  self._event_callbacks: list[EventCallback] = []
129
143
  self._work_subscriptions: set[str] = set()
144
+ self._layer: str | None = None
130
145
  self._control_subscriptions: set[tuple[str, str | None]] = set()
131
146
  self._wait_subscribers: set[str] = set()
132
147
  self._seen_completed: OrderedDict[str, None] = OrderedDict()
@@ -228,6 +243,9 @@ class ContinuumWebSocketClient:
228
243
  parent_id: UUID | str | None = None,
229
244
  request_id: str | None = None,
230
245
  idempotency_token: str | None = None,
246
+ layer: str | None = None,
247
+ strict_layer: bool | None = None,
248
+ actor_event_id: UUID | str | None = None,
231
249
  ) -> QueueItem:
232
250
  if task_name is None and task_item_name is None:
233
251
  raise ValueError("at least one of task_name or task_item_name is required")
@@ -239,6 +257,9 @@ class ContinuumWebSocketClient:
239
257
  "priority": priority,
240
258
  "inputData": _encode_input(input_data),
241
259
  "idempotencyToken": idempotency_token,
260
+ "layer": layer,
261
+ "strictLayer": strict_layer,
262
+ "actorEventId": str(actor_event_id) if actor_event_id else None,
242
263
  }
243
264
  )
244
265
  payload = self._command("/app/enqueue", body, request_id=request_id, retry=False)
@@ -260,6 +281,9 @@ class ContinuumWebSocketClient:
260
281
  correlation: str | None = None,
261
282
  request_id: str | None = None,
262
283
  idempotency_token: str | None = None,
284
+ layer: str | None = None,
285
+ strict_layer: bool | None = None,
286
+ actor_event_id: UUID | str | None = None,
263
287
  ) -> EnqueueAndSubscribeWaitResult:
264
288
  if task_name is None and task_item_name is None:
265
289
  raise ValueError("at least one of task_name or task_item_name is required")
@@ -277,6 +301,9 @@ class ContinuumWebSocketClient:
277
301
  "mode": mode_value,
278
302
  "correlation": correlation,
279
303
  "idempotencyToken": idempotency_token,
304
+ "layer": layer,
305
+ "strictLayer": strict_layer,
306
+ "actorEventId": str(actor_event_id) if actor_event_id else None,
280
307
  }
281
308
  )
282
309
  payload = self._command(
@@ -289,10 +316,16 @@ class ContinuumWebSocketClient:
289
316
  self._wait_subscribers.add(subscriber_id)
290
317
  return result
291
318
 
292
- def claim(self, task_name: str, *, request_id: str | None = None) -> QueueItem | None:
319
+ def set_layer(self, layer: str | None) -> None:
320
+ self._layer = layer.strip() if isinstance(layer, str) and layer.strip() else None
321
+
322
+ def claim(
323
+ self, task_name: str, *, request_id: str | None = None, layer: str | None = None
324
+ ) -> QueueItem | None:
325
+ chosen = layer if layer else self._layer
293
326
  payload = self._command(
294
327
  "/app/claim",
295
- {"taskName": task_name},
328
+ drop_none({"taskName": task_name, "layer": chosen}),
296
329
  request_id=request_id,
297
330
  retry=False,
298
331
  )
@@ -343,11 +376,12 @@ class ContinuumWebSocketClient:
343
376
  return QueueItem.model_validate(payload["item"])
344
377
 
345
378
  def subscribe_work(
346
- self, task_name: str, *, request_id: str | None = None
379
+ self, task_name: str, *, request_id: str | None = None, layer: str | None = None
347
380
  ) -> WorkSubscriptionResult:
381
+ chosen = layer if layer else self._layer
348
382
  payload = self._command(
349
383
  "/app/subscribeWork",
350
- {"taskName": task_name},
384
+ drop_none({"taskName": task_name, "layer": chosen}),
351
385
  request_id=request_id,
352
386
  retry=True,
353
387
  )
@@ -485,6 +519,76 @@ class ContinuumWebSocketClient:
485
519
  )
486
520
  return EventAckResult.model_validate(payload)
487
521
 
522
+ def register_data_subscription(
523
+ self,
524
+ layer: str | None = None,
525
+ strict_layer: bool | None = None,
526
+ subject: str | None = None,
527
+ filter: Any = None,
528
+ delivery_kind: str | None = None,
529
+ actor_instance_id: UUID | str | None = None,
530
+ task_item_id: UUID | str | None = None,
531
+ *,
532
+ request_id: str | None = None,
533
+ ) -> UUID:
534
+ """Send /app/registerDataSubscription. None arguments are omitted. False is sent."""
535
+ body = drop_none(
536
+ {
537
+ "layer": layer,
538
+ "strictLayer": strict_layer,
539
+ "subject": subject,
540
+ "filter": filter,
541
+ "deliveryKind": delivery_kind,
542
+ "actorInstanceId": None if actor_instance_id is None else str(actor_instance_id),
543
+ "taskItemId": None if task_item_id is None else str(task_item_id),
544
+ }
545
+ )
546
+ payload = self._command(
547
+ "/app/registerDataSubscription",
548
+ body,
549
+ request_id=request_id,
550
+ retry=False,
551
+ )
552
+ return _reply_id(
553
+ payload,
554
+ "subscription",
555
+ "registerDataSubscription succeeded without a subscription id",
556
+ "registerDataSubscription subscription id is not a UUID",
557
+ )
558
+
559
+ def insert_ingress_event(
560
+ self,
561
+ task_server_id: UUID | str | None = None,
562
+ source: str | None = None,
563
+ source_message_id: str | None = None,
564
+ address: Any = None,
565
+ payload: Any = None,
566
+ *,
567
+ request_id: str | None = None,
568
+ ) -> UUID:
569
+ """Send /app/insertIngressEvent. None arguments are omitted."""
570
+ body = drop_none(
571
+ {
572
+ "taskServerId": None if task_server_id is None else str(task_server_id),
573
+ "source": source,
574
+ "sourceMessageId": source_message_id,
575
+ "address": address,
576
+ "payload": payload,
577
+ }
578
+ )
579
+ reply = self._command(
580
+ "/app/insertIngressEvent",
581
+ body,
582
+ request_id=request_id,
583
+ retry=False,
584
+ )
585
+ return _reply_id(
586
+ reply,
587
+ "event",
588
+ "insertIngressEvent succeeded without an ingress event id",
589
+ "insertIngressEvent event id is not a UUID",
590
+ )
591
+
488
592
  def _command(
489
593
  self,
490
594
  destination: str,
@@ -695,7 +799,9 @@ class ContinuumWebSocketClient:
695
799
  controls = list(self._control_subscriptions)
696
800
  for task_name in work:
697
801
  try:
698
- self._command_inline("/app/subscribeWork", {"taskName": task_name})
802
+ self._command_inline(
803
+ "/app/subscribeWork", drop_none({"taskName": task_name, "layer": self._layer})
804
+ )
699
805
  except ContinuumError:
700
806
  logger.error("Failed to restore work subscription %s", task_name, exc_info=True)
701
807
  for subscriber_id in waits:
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "continuum-task-server-sdk"
7
- version = "1.5.0"
7
+ version = "1.7.0"
8
8
  description = "Python SDK for the Continuum Task Server"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"