langgraph-api 0.18.0.dev2__py3-none-any.whl → 0.18.0.dev4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. langgraph_api/__init__.py +1 -1
  2. langgraph_api/api/a2a.py +93 -10
  3. langgraph_api/api/event_streaming.py +81 -9
  4. langgraph_api/api/mcp/_calls.py +29 -0
  5. langgraph_api/api/mcp/_constants.py +15 -6
  6. langgraph_api/api/mcp/_handlers.py +146 -196
  7. langgraph_api/api/mcp/_outcome.py +43 -0
  8. langgraph_api/api/mcp/_protocol.py +224 -0
  9. langgraph_api/config/__init__.py +38 -4
  10. langgraph_api/cron_scheduler.py +2 -2
  11. langgraph_api/drain.py +164 -0
  12. langgraph_api/event_streaming/service.py +130 -133
  13. langgraph_api/event_streaming/session.py +11 -6
  14. langgraph_api/executor/__init__.py +9 -0
  15. langgraph_api/executor/__main__.py +343 -0
  16. langgraph_api/feature_flags.py +6 -0
  17. langgraph_api/graph.py +12 -2
  18. langgraph_api/grpc/ops/runs.py +41 -5
  19. langgraph_api/grpc/ops/threads.py +54 -6
  20. langgraph_api/metrics_otlp.py +8 -0
  21. langgraph_api/models/run.py +11 -3
  22. langgraph_api/queue_entrypoint.py +13 -1
  23. langgraph_api/self_hosted_logs.py +3 -1
  24. langgraph_api/self_hosted_metrics.py +1 -1
  25. langgraph_api/stream.py +49 -3
  26. langgraph_api/timing/__init__.py +16 -0
  27. langgraph_api/timing/startup.py +184 -0
  28. langgraph_api/timing/timer.py +16 -2
  29. langgraph_api/utils/headers.py +20 -3
  30. langgraph_api/validation.py +11 -5
  31. langgraph_api/worker.py +146 -13
  32. langgraph_api/worker_runtime.py +124 -4
  33. {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/METADATA +1 -1
  34. {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/RECORD +43 -38
  35. langgraph_grpc_common/proto/__init__.py +4 -4
  36. langgraph_grpc_common/proto/orchestrator_pb2.py +50 -0
  37. langgraph_grpc_common/proto/{runner_pb2.pyi → orchestrator_pb2.pyi} +4 -4
  38. langgraph_grpc_common/proto/orchestrator_pb2_grpc.py +108 -0
  39. langgraph_grpc_common/proto/orchestrator_pb2_grpc.pyi +82 -0
  40. openapi.json +20 -0
  41. langgraph_api/runner/__init__.py +0 -10
  42. langgraph_api/runner/__main__.py +0 -275
  43. langgraph_grpc_common/proto/runner_pb2.py +0 -50
  44. langgraph_grpc_common/proto/runner_pb2_grpc.py +0 -108
  45. langgraph_grpc_common/proto/runner_pb2_grpc.pyi +0 -73
  46. {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/WHEEL +0 -0
  47. {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/entry_points.txt +0 -0
  48. {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,224 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ import re
5
+ from dataclasses import dataclass
6
+ from http import HTTPStatus
7
+ from types import MappingProxyType
8
+ from typing import TYPE_CHECKING, Any, ClassVar
9
+
10
+ from langgraph_api import __version__
11
+ from langgraph_api.api.mcp._constants import (
12
+ ERROR_CODE_HEADER_MISMATCH,
13
+ ERROR_CODE_INVALID_PARAMS,
14
+ ERROR_CODE_METHOD_NOT_FOUND,
15
+ ERROR_CODE_UNSUPPORTED_VERSION,
16
+ PROTOCOL_VERSION,
17
+ SUPPORTED_PROTOCOL_VERSIONS,
18
+ )
19
+
20
+ if TYPE_CHECKING:
21
+ from collections.abc import Mapping
22
+
23
+ from langgraph_api.api.mcp._models import JsonRpcErrorObject, JsonRpcRequest
24
+ from langgraph_api.cache import JsonValue
25
+ from langgraph_api.route import ApiRequest
26
+
27
+ META_PREFIX = "io.modelcontextprotocol/"
28
+ VERSION_KEY = META_PREFIX + "protocolVersion"
29
+ CAPABILITIES_KEY = META_PREFIX + "clientCapabilities"
30
+ NAMED_METHODS = MappingProxyType(
31
+ {"tools/call": "name", "resources/read": "uri", "prompts/get": "name"}
32
+ )
33
+ SERVER_INFO = {"name": "LangGraph", "version": __version__}
34
+ SERVER_CAPABILITIES = {"tools": {"listChanged": False}}
35
+ CACHE_HINTS = MappingProxyType({"ttlMs": 0, "cacheScope": "private"})
36
+ CACHEABLE_METHODS = frozenset({"server/discover", "tools/list"})
37
+ HTTP_WHITESPACE = " \t"
38
+ PLAIN_HEADER_VALUE = re.compile(r"[\x20-\x7e]+")
39
+ BASE64_HEADER_VALUE = re.compile(r"=\?base64\?(?P<encoded>.*)\?=")
40
+
41
+
42
+ class ProtocolError(ValueError):
43
+ def __init__(
44
+ self,
45
+ message: str,
46
+ code: int = ERROR_CODE_INVALID_PARAMS,
47
+ data: JsonValue = None,
48
+ ):
49
+ super().__init__(message)
50
+ self.error: JsonRpcErrorObject = {"code": code, "message": message}
51
+ if data is not None:
52
+ self.error["data"] = data
53
+
54
+
55
+ @dataclass(frozen=True, slots=True)
56
+ class MirroredHeaders:
57
+ protocol_version: str
58
+ method: str
59
+ name: str
60
+
61
+ @classmethod
62
+ def of(cls, headers: Mapping[str, str]) -> MirroredHeaders:
63
+ version, method, name = (
64
+ headers.get(field, "").strip(HTTP_WHITESPACE)
65
+ for field in ("mcp-protocol-version", "mcp-method", "mcp-name")
66
+ )
67
+ return cls(version, method, name)
68
+
69
+
70
+ @dataclass(frozen=True, slots=True)
71
+ class Legacy:
72
+ headers: ClassVar[Mapping[str, str]] = MappingProxyType({})
73
+
74
+ def result(self, method: str, payload: dict[str, Any]) -> dict[str, Any]:
75
+ return payload
76
+
77
+ def http_status(self, error: ProtocolError) -> HTTPStatus:
78
+ return HTTPStatus.OK
79
+
80
+
81
+ @dataclass(frozen=True, slots=True)
82
+ class Modern:
83
+ version: str
84
+ capabilities: dict[str, Any]
85
+ headers: ClassVar[Mapping[str, str]] = MappingProxyType(
86
+ {"Cache-Control": "no-store"}
87
+ )
88
+
89
+ @classmethod
90
+ def of(
91
+ cls, headers: MirroredHeaders, params: dict[str, Any], method: str
92
+ ) -> Modern:
93
+ meta = params.get("_meta")
94
+ if not isinstance(meta, dict):
95
+ raise ProtocolError("Request _meta must be an object")
96
+ version = meta.get(VERSION_KEY)
97
+ capabilities = meta.get(CAPABILITIES_KEY)
98
+ if not isinstance(version, str) or not isinstance(capabilities, dict):
99
+ raise ProtocolError("protocolVersion and clientCapabilities are required")
100
+ _check_capabilities(capabilities)
101
+ _check_headers(headers, params, method, version=version)
102
+ if version != PROTOCOL_VERSION:
103
+ raise ProtocolError(
104
+ "Unsupported protocol version",
105
+ ERROR_CODE_UNSUPPORTED_VERSION,
106
+ {
107
+ "requested": version,
108
+ "supported": sorted(SUPPORTED_PROTOCOL_VERSIONS),
109
+ },
110
+ )
111
+ return cls(version, capabilities)
112
+
113
+ def result(self, method: str, payload: dict[str, Any]) -> dict[str, Any]:
114
+ hints = CACHE_HINTS if method in CACHEABLE_METHODS else {}
115
+ return complete({**payload, **hints})
116
+
117
+ def http_status(self, error: ProtocolError) -> HTTPStatus:
118
+ if error.error["code"] == ERROR_CODE_METHOD_NOT_FOUND:
119
+ return HTTPStatus.NOT_FOUND
120
+ return HTTPStatus.BAD_REQUEST
121
+
122
+
123
+ Era = Legacy | Modern
124
+
125
+
126
+ @dataclass(frozen=True, slots=True)
127
+ class McpCall:
128
+ message: JsonRpcRequest
129
+ era: Era
130
+
131
+ @property
132
+ def id(self) -> str | int:
133
+ return self.message["id"]
134
+
135
+ @property
136
+ def method(self) -> str:
137
+ return self.message["method"]
138
+
139
+ @property
140
+ def params(self) -> dict[str, Any]:
141
+ return params_of(self.message)
142
+
143
+
144
+ def params_of(message: JsonRpcRequest) -> dict[str, Any]:
145
+ match message.get("params", {}):
146
+ case dict() as params:
147
+ return params
148
+ case _:
149
+ raise ProtocolError("params must be an object")
150
+
151
+
152
+ def parse_call(request: ApiRequest, message: JsonRpcRequest) -> McpCall:
153
+ headers = MirroredHeaders.of(request.headers)
154
+ method = message["method"]
155
+ if not is_modern(headers, message.get("params"), method):
156
+ return McpCall(message, Legacy())
157
+ return McpCall(message, Modern.of(headers, params_of(message), method))
158
+
159
+
160
+ def is_modern(headers: MirroredHeaders, params: object, method: str) -> bool:
161
+ meta = params.get("_meta") if isinstance(params, dict) else None
162
+ return (
163
+ (isinstance(meta, dict) and VERSION_KEY in meta)
164
+ or headers.protocol_version == PROTOCOL_VERSION
165
+ or method == "server/discover"
166
+ )
167
+
168
+
169
+ def _decode_header(value: str) -> str:
170
+ if not PLAIN_HEADER_VALUE.fullmatch(value):
171
+ raise ProtocolError("Invalid MCP header", ERROR_CODE_HEADER_MISMATCH)
172
+ if (sentinel := BASE64_HEADER_VALUE.fullmatch(value)) is None:
173
+ return value
174
+ try:
175
+ return base64.b64decode(sentinel["encoded"], validate=True).decode()
176
+ except ValueError:
177
+ raise ProtocolError(
178
+ "Invalid MCP header encoding", ERROR_CODE_HEADER_MISMATCH
179
+ ) from None
180
+
181
+
182
+ def _check_capabilities(capabilities: dict[str, Any]) -> None:
183
+ for name in ("elicitation", "extensions"):
184
+ if name in capabilities and not isinstance(capabilities[name], dict):
185
+ raise ProtocolError(f"{name} capability must be an object")
186
+ for name, value in capabilities.get("elicitation", {}).items():
187
+ if name in {"form", "url"} and not isinstance(value, dict):
188
+ raise ProtocolError(f"elicitation.{name} capability must be an object")
189
+ if any(
190
+ not isinstance(value, dict)
191
+ for value in capabilities.get("extensions", {}).values()
192
+ ):
193
+ raise ProtocolError("Extension capabilities must be objects")
194
+
195
+
196
+ def _check_headers(
197
+ headers: MirroredHeaders, params: dict[str, Any], method: str, *, version: str
198
+ ) -> None:
199
+ if headers.protocol_version != version:
200
+ raise ProtocolError(
201
+ "MCP-Protocol-Version header mismatch", ERROR_CODE_HEADER_MISMATCH
202
+ )
203
+ if headers.method != method:
204
+ raise ProtocolError("Mcp-Method header mismatch", ERROR_CODE_HEADER_MISMATCH)
205
+ field = NAMED_METHODS.get(method)
206
+ if field is None:
207
+ return
208
+ if _decode_header(headers.name) != params.get(field):
209
+ raise ProtocolError("Mcp-Name header mismatch", ERROR_CODE_HEADER_MISMATCH)
210
+
211
+
212
+ def complete(result: dict[str, Any]) -> dict[str, Any]:
213
+ return {
214
+ **result,
215
+ "resultType": result.get("resultType", "complete"),
216
+ "_meta": {**result.get("_meta", {}), META_PREFIX + "serverInfo": SERVER_INFO},
217
+ }
218
+
219
+
220
+ def discover() -> dict[str, Any]:
221
+ return {
222
+ "supportedVersions": sorted(SUPPORTED_PROTOCOL_VERSIONS, reverse=True),
223
+ "capabilities": SERVER_CAPABILITIES,
224
+ }
@@ -4,6 +4,7 @@ from os import environ, getenv
4
4
  from typing import TYPE_CHECKING, Annotated, Literal, TypeVar, cast
5
5
 
6
6
  import structlog
7
+ from langgraph.version import __version__ as langgraph_version
7
8
  from pydantic.functional_validators import AfterValidator
8
9
  from starlette.config import Config
9
10
  from starlette.datastructures import CommaSeparatedStrings
@@ -24,6 +25,7 @@ from langgraph_api.config.schemas import (
24
25
  webhooks_validator,
25
26
  )
26
27
  from langgraph_api.feature_flags import (
28
+ DRAIN_RESUME_SUPPORT,
27
29
  IS_POSTGRES_BACKEND,
28
30
  OMIT_PENDING_SENDS,
29
31
  PREFER_GRPC_CHECKPOINTER,
@@ -398,6 +400,8 @@ if (
398
400
 
399
401
  BG_JOB_HEARTBEAT = 120 # seconds
400
402
  BG_JOB_MAX_RETRIES = env("BG_JOB_MAX_RETRIES", cast=int, default=3)
403
+ # Stops graphs that drain forever. The retry limit only applies to failures.
404
+ BG_JOB_MAX_DRAINS = env("BG_JOB_MAX_DRAINS", cast=int, default=50)
401
405
  BG_JOB_ISOLATED_LOOPS = env("BG_JOB_ISOLATED_LOOPS", cast=bool, default=False)
402
406
  BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS = env(
403
407
  "BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS",
@@ -448,7 +452,7 @@ class DispatchMode(StrEnum):
448
452
  """How background runs are dispatched.
449
453
 
450
454
  single-process: Python queue loop in the API process (default).
451
- multi-process: Go queue worker claims runs and dispatches to Python runners.
455
+ multi-process: Go executor manager claims runs and dispatches to Python executors.
452
456
  """
453
457
 
454
458
  SINGLE_PROCESS = "single-process"
@@ -502,8 +506,36 @@ FF_ASYNC_PUBLISH_QUEUE = env("FF_ASYNC_PUBLISH_QUEUE", cast=bool, default=False)
502
506
  FF_CRONS_ENABLED = env("FF_CRONS_ENABLED", cast=bool, default=True)
503
507
  FF_LOG_DROPPED_EVENTS = env("FF_LOG_DROPPED_EVENTS", cast=bool, default=False)
504
508
  FF_LOG_QUERY_AND_PARAMS = env("FF_LOG_QUERY_AND_PARAMS", cast=bool, default=False)
505
- # Not in public docs: internal feature flag
506
- FF_USE_REDIS_QUEUE = env("FF_USE_REDIS_QUEUE", cast=bool, default=True)
509
+ # Opt-in handling of drained runs: the server's control signalling to the
510
+ # graph and its handling of drained runs, together. On, a Postgres-backed
511
+ # replica that is shutting down also drains its in-flight runs.
512
+ # Off: no control is created or seeded, and GraphDrained lands in the
513
+ # catch-all error branch.
514
+ FF_RESUME_DRAINED_RUNS = env("FF_RESUME_DRAINED_RUNS", cast=bool, default=False)
515
+
516
+
517
+ def _resolve_resume_drained_runs(
518
+ enabled: bool, *, is_postgres: bool, langgraph_supported: bool
519
+ ) -> bool:
520
+ # Only the Postgres runtime re-queues drained runs: on the in-memory
521
+ # runtime a drain still ends the run as an error, flag or not.
522
+ if not (enabled and is_postgres):
523
+ return False
524
+ if not langgraph_supported:
525
+ logger.warning(
526
+ "Ignoring FF_RESUME_DRAINED_RUNS=true: resuming drained runs "
527
+ "requires langgraph>=1.2.15, so drained runs end as errors.",
528
+ langgraph_version=langgraph_version,
529
+ )
530
+ return False
531
+ return True
532
+
533
+
534
+ RESUME_DRAINED_RUNS = _resolve_resume_drained_runs(
535
+ FF_RESUME_DRAINED_RUNS,
536
+ is_postgres=IS_POSTGRES_BACKEND,
537
+ langgraph_supported=DRAIN_RESUME_SUPPORT,
538
+ )
507
539
 
508
540
 
509
541
  # Internal flag intended for testing only
@@ -747,6 +779,7 @@ __all__ = [
747
779
  "API_VARIANT",
748
780
  "BG_JOB_HEARTBEAT",
749
781
  "BG_JOB_ISOLATED_LOOPS",
782
+ "BG_JOB_MAX_DRAINS",
750
783
  "BG_JOB_MAX_RETRIES",
751
784
  "BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS",
752
785
  "BG_JOB_TIMEOUT_SECS",
@@ -776,7 +809,7 @@ __all__ = [
776
809
  "FF_LOG_QUERY_AND_PARAMS",
777
810
  "FF_PYSPY_PROFILING_ENABLED",
778
811
  "FF_PYSPY_PROFILING_MAX_DURATION_SECS",
779
- "FF_USE_REDIS_QUEUE",
812
+ "FF_RESUME_DRAINED_RUNS",
780
813
  "GRPC_CLIENT_HTTP2_INITIAL_WINDOW_SIZE",
781
814
  "GRPC_CLIENT_MAX_RECV_MSG_BYTES",
782
815
  "GRPC_CLIENT_MAX_SEND_MSG_BYTES",
@@ -826,6 +859,7 @@ __all__ = [
826
859
  "REDIS_MAX_CONNECTIONS",
827
860
  "REDIS_URI",
828
861
  "RESUMABLE_STREAM_TTL_SECONDS",
862
+ "RESUME_DRAINED_RUNS",
829
863
  "RUN_STATS_CACHE_SECONDS",
830
864
  "SELF_HOSTED_OBSERVABILITY_SERVICE_NAME",
831
865
  "SERDE",
@@ -82,11 +82,11 @@ async def cron_scheduler():
82
82
  ):
83
83
  logger.debug(f"Scheduling cron run {cron}")
84
84
  try:
85
- cron_id = None
85
+ cron_id = str(cron["cron_id"])
86
86
  if run_payload.get("context"):
87
87
  # Cron persistence and set_auth_ctx_for_run write these into configurable, which create_valid_run rejects next to context.
88
88
  configurable = run_payload["config"]["configurable"]
89
- cron_id = configurable.pop("cron_id", None)
89
+ configurable.pop("cron_id", None)
90
90
  configurable.pop("langgraph_auth_user", None)
91
91
  run = await create_valid_run(
92
92
  conn,
langgraph_api/drain.py ADDED
@@ -0,0 +1,164 @@
1
+ """Cooperative drain support.
2
+
3
+ Draining asks a running graph to stop at the next superstep boundary, save its
4
+ checkpoint, and raise ``GraphDrained`` so the run can be re-queued and resumed
5
+ by another worker. The support (``RunControl`` / ``GraphDrained``) arrived in
6
+ langgraph 1.2; the server also supports older langgraph, so the imports are
7
+ guarded and the placeholders below never match or instantiate anything.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import contextvars
13
+ import threading
14
+ from typing import Any
15
+
16
+ # The control of the run whose top-level graph this context is executing. The
17
+ # server sets it before streaming the graph; asyncio tasks and LangGraph's node
18
+ # executors copy it, while threads a node starts itself don't.
19
+ _TOP_LEVEL_CONTROL: contextvars.ContextVar[Any] = contextvars.ContextVar(
20
+ "langgraph_api_top_level_run_control", default=None
21
+ )
22
+
23
+
24
+ def _in_graph_node() -> bool:
25
+ """Whether the caller runs inside a graph node (and so in any subgraph loop).
26
+
27
+ LangGraph runs node code under a runnable config context whose
28
+ checkpoint_ns names the node; the run's top-level loop has no such context.
29
+ """
30
+ try:
31
+ from langgraph.config import get_config # noqa: PLC0415
32
+
33
+ config = get_config()
34
+ except RuntimeError:
35
+ return False
36
+ return bool((config.get("configurable") or {}).get("checkpoint_ns"))
37
+
38
+
39
+ try:
40
+ from langgraph.errors import GraphDrained
41
+ from langgraph.runtime import RunControl
42
+
43
+ class ServerRunControl(RunControl):
44
+ """A RunControl whose drain request only the run's top-level graph sees.
45
+
46
+ LangGraph hands a run's control to its subgraphs. A drain inside a
47
+ subgraph would, with durability="exit", lose the subgraph's progress.
48
+ The request is visible only where this is provably the run's top-level
49
+ loop: in a context the server marked for this control (see
50
+ mark_top_level) and outside any graph node. So the run drains only at
51
+ a top-level step boundary, after that step's subgraphs have finished,
52
+ and never before its first step.
53
+ Graph code inside a node, and threads a node starts, see no drain
54
+ (drain_requested False, drain_reason None).
55
+ """
56
+
57
+ __slots__ = ("_first_check_done",)
58
+
59
+ def __init__(self) -> None:
60
+ super().__init__()
61
+ self._first_check_done = False
62
+
63
+ def _visible(self) -> bool:
64
+ return _TOP_LEVEL_CONTROL.get() is self and not _in_graph_node()
65
+
66
+ @property
67
+ def drain_requested(self) -> bool:
68
+ if not self._visible():
69
+ return False
70
+ # LangGraph checks once per top-level step boundary, before the
71
+ # step. Only a server drain can be pending at the first check. A
72
+ # run started with a Command has no checkpoint of its own until its
73
+ # first step ends, so if it drained there, its next claim would
74
+ # re-send the Command and LangGraph would apply it again. So a run
75
+ # always completes a step before it drains.
76
+ if not self._first_check_done:
77
+ self._first_check_done = True
78
+ return False
79
+ return RunControl.drain_requested.fget(self)
80
+
81
+ @property
82
+ def drain_reason(self) -> str | None:
83
+ return RunControl.drain_reason.fget(self) if self._visible() else None
84
+
85
+ DRAIN_SUPPORT = True
86
+ except ImportError:
87
+
88
+ class GraphDrained(Exception):
89
+ """Placeholder that is never raised or matched on langgraph < 1.2."""
90
+
91
+ reason: str | None = None
92
+
93
+ class RunControl:
94
+ """Placeholder; new_run_control() never creates one on langgraph < 1.2."""
95
+
96
+ class ServerRunControl(RunControl):
97
+ """Placeholder; new_run_control() never creates one on langgraph < 1.2."""
98
+
99
+ DRAIN_SUPPORT = False
100
+
101
+ # Reason the server passes to request_drain() when its pod is shutting down.
102
+ # Graph code can pass any reason (request_drain() defaults to "shutdown"), so
103
+ # this distinct value is what tells server drains from graph drains in logs.
104
+ SERVER_SHUTDOWN_DRAIN_REASON = "server_shutdown"
105
+
106
+
107
+ def mark_top_level(control: ServerRunControl | None) -> None:
108
+ """Mark the current context as running ``control``'s top-level graph."""
109
+ _TOP_LEVEL_CONTROL.set(control)
110
+
111
+
112
+ def new_run_control() -> ServerRunControl | None:
113
+ """Return a fresh control for a run, or None without drain support."""
114
+ if DRAIN_SUPPORT:
115
+ return ServerRunControl()
116
+ return None
117
+
118
+
119
+ class RunControlRegistry:
120
+ """Controls of the runs a queue drains at shutdown, keyed by run ID.
121
+
122
+ Workers can finish on background threads (isolated loops), so every access
123
+ takes a lock and ``drain_all`` works on a snapshot. Controls are registered
124
+ before the run starts, and removed only by the claim that registered them,
125
+ so a fast-finishing or superseded claim can't leave or remove the wrong
126
+ entry.
127
+ """
128
+
129
+ def __init__(self) -> None:
130
+ self._lock = threading.Lock()
131
+ self._controls: dict[str, ServerRunControl] = {}
132
+
133
+ def add(self, run_id: Any, control: ServerRunControl) -> None:
134
+ """Register a run's control before the run starts."""
135
+ with self._lock:
136
+ self._controls[str(run_id)] = control
137
+
138
+ def release(self, run_id: Any, control: ServerRunControl | None) -> None:
139
+ """Remove a run's control if it is still the one this claim registered."""
140
+ if control is None:
141
+ return
142
+ with self._lock:
143
+ if self._controls.get(str(run_id)) is control:
144
+ del self._controls[str(run_id)]
145
+
146
+ def drain_all(self, reason: str) -> int:
147
+ """Request a drain from every registered run; return how many."""
148
+ with self._lock:
149
+ controls = list(self._controls.values())
150
+ for control in controls:
151
+ control.request_drain(reason)
152
+ return len(controls)
153
+
154
+
155
+ __all__ = [
156
+ "DRAIN_SUPPORT",
157
+ "SERVER_SHUTDOWN_DRAIN_REASON",
158
+ "GraphDrained",
159
+ "RunControl",
160
+ "RunControlRegistry",
161
+ "ServerRunControl",
162
+ "mark_top_level",
163
+ "new_run_control",
164
+ ]