strands-mongodb 0.1.0.dev1__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.
- strands_mongodb/__init__.py +76 -0
- strands_mongodb/_client.py +508 -0
- strands_mongodb/_extras.py +39 -0
- strands_mongodb/_filter.py +221 -0
- strands_mongodb/_indexes.py +1314 -0
- strands_mongodb/_pipeline.py +408 -0
- strands_mongodb/_telemetry.py +254 -0
- strands_mongodb/memory_store.py +1282 -0
- strands_mongodb/py.typed +1 -0
- strands_mongodb/storage.py +693 -0
- strands_mongodb/types.py +236 -0
- strands_mongodb/vector_search.py +216 -0
- strands_mongodb-0.1.0.dev1.dist-info/METADATA +1032 -0
- strands_mongodb-0.1.0.dev1.dist-info/RECORD +17 -0
- strands_mongodb-0.1.0.dev1.dist-info/WHEEL +4 -0
- strands_mongodb-0.1.0.dev1.dist-info/licenses/LICENSE +175 -0
- strands_mongodb-0.1.0.dev1.dist-info/licenses/NOTICE +10 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
"""MongoDB storage and memory backends for the Strands Agents SDK.
|
|
2
|
+
|
|
3
|
+
Two surfaces, each behind its own install extra:
|
|
4
|
+
|
|
5
|
+
- :mod:`strands_mongodb.storage`: ``MongoDBStorage``, implementing the SDK's unified
|
|
6
|
+
``strands.storage.Storage`` protocol. Install with ``pip install 'strands-mongodb[storage]'``.
|
|
7
|
+
- :mod:`strands_mongodb.vector_search`: ``MongoDBVectorSearchStrategy``, Atlas Vector Search behind
|
|
8
|
+
``MongoDBStorage.search``. Same ``storage`` extra.
|
|
9
|
+
- :mod:`strands_mongodb.memory_store`: ``MongoDBMemoryStore``, implementing the SDK's
|
|
10
|
+
``strands.memory.MemoryStore`` protocol. Install with ``pip install 'strands-mongodb[memory]'``.
|
|
11
|
+
|
|
12
|
+
Every class is importable from here and is loaded on first access, not at import time. That way a
|
|
13
|
+
``[storage]``-only install can use ``MongoDBStorage`` without importing the memory module, which would
|
|
14
|
+
fail on ``pymongo_search_utils``.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from importlib import import_module
|
|
20
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
21
|
+
from typing import TYPE_CHECKING, Final
|
|
22
|
+
|
|
23
|
+
if TYPE_CHECKING:
|
|
24
|
+
# Type checkers cannot see through `__getattr__`, so without these the lazy names would type as `object`.
|
|
25
|
+
from strands_mongodb.memory_store import MongoDBMemoryStore
|
|
26
|
+
from strands_mongodb.storage import MongoDBStorage
|
|
27
|
+
from strands_mongodb.vector_search import MongoDBVectorSearchStrategy
|
|
28
|
+
|
|
29
|
+
try:
|
|
30
|
+
__version__ = version("strands-mongodb")
|
|
31
|
+
except PackageNotFoundError:
|
|
32
|
+
# Imported from a source tree that was never installed.
|
|
33
|
+
__version__ = "0.0.0+unknown"
|
|
34
|
+
|
|
35
|
+
__all__ = ["MongoDBMemoryStore", "MongoDBStorage", "MongoDBVectorSearchStrategy", "__version__"]
|
|
36
|
+
|
|
37
|
+
_LAZY: Final[dict[str, str]] = {
|
|
38
|
+
"MongoDBStorage": "strands_mongodb.storage",
|
|
39
|
+
"MongoDBMemoryStore": "strands_mongodb.memory_store",
|
|
40
|
+
"MongoDBVectorSearchStrategy": "strands_mongodb.vector_search",
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def __getattr__(name: str) -> object:
|
|
45
|
+
"""Resolve a backend class on first access, importing only its own module.
|
|
46
|
+
|
|
47
|
+
A module-level ``__getattr__`` (PEP 562) makes a type checker accept any attribute name on this
|
|
48
|
+
module. Returning ``object`` rather than ``Any`` means a misspelled name is still rejected at its
|
|
49
|
+
first real use.
|
|
50
|
+
|
|
51
|
+
Args:
|
|
52
|
+
name: The attribute being looked up.
|
|
53
|
+
|
|
54
|
+
Returns:
|
|
55
|
+
The class named by ``name``.
|
|
56
|
+
|
|
57
|
+
Raises:
|
|
58
|
+
AttributeError: If ``name`` is not a lazily exported class. ``hasattr``, ``inspect``, ``copy``
|
|
59
|
+
and ``pickle`` rely on this exception type when probing for attributes.
|
|
60
|
+
ImportError: If the class's install extra is missing. The message names the extra to install.
|
|
61
|
+
"""
|
|
62
|
+
module_name = _LAZY.get(name)
|
|
63
|
+
if module_name is None:
|
|
64
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
65
|
+
return getattr(import_module(module_name), name)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def __dir__() -> list[str]:
|
|
69
|
+
"""List the lazily exported names alongside the eager ones.
|
|
70
|
+
|
|
71
|
+
Without this, ``dir(strands_mongodb)`` and tab completion omit the classes until they are imported.
|
|
72
|
+
|
|
73
|
+
Returns:
|
|
74
|
+
The module's attribute names, sorted.
|
|
75
|
+
"""
|
|
76
|
+
return sorted({*globals(), *_LAZY})
|
|
@@ -0,0 +1,508 @@
|
|
|
1
|
+
"""Connection resolution, ownership and per-loop locking, shared by both public surfaces.
|
|
2
|
+
|
|
3
|
+
``MongoDBConfig`` is a ``TypedDict``, so it is a plain ``dict`` and cannot hold state. The client built
|
|
4
|
+
from it, the lock guarding its one-time setup and its capability probe therefore live in a module-level
|
|
5
|
+
registry keyed by connection identity. That is what lets any number of stores configured from the same
|
|
6
|
+
deployment share one connection pool per event loop.
|
|
7
|
+
|
|
8
|
+
Private: the registry, the identity scheme and ``_Connection`` may change in any release.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import asyncio
|
|
14
|
+
import hashlib
|
|
15
|
+
import json
|
|
16
|
+
import logging
|
|
17
|
+
import threading
|
|
18
|
+
from dataclasses import dataclass, field
|
|
19
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
20
|
+
from typing import TYPE_CHECKING, Any, Final
|
|
21
|
+
|
|
22
|
+
from strands_mongodb._extras import missing_extra
|
|
23
|
+
|
|
24
|
+
# `storage`, because both surfaces reach this module and `[memory]` is a superset of `[storage]`.
|
|
25
|
+
try:
|
|
26
|
+
from pymongo import AsyncMongoClient
|
|
27
|
+
from pymongo.driver_info import DriverInfo
|
|
28
|
+
except ImportError as error: # pragma: no cover
|
|
29
|
+
missing_extra("storage", error, module=__name__)
|
|
30
|
+
|
|
31
|
+
from strands_mongodb import _telemetry
|
|
32
|
+
|
|
33
|
+
if TYPE_CHECKING:
|
|
34
|
+
from strands_mongodb.types import MongoDBConfig
|
|
35
|
+
|
|
36
|
+
__all__ = ["Capabilities", "close", "resolve"]
|
|
37
|
+
|
|
38
|
+
logger = logging.getLogger(__name__)
|
|
39
|
+
|
|
40
|
+
# The `driver.name` entry server logs and Atlas telemetry group by. Specific to this package: the archived
|
|
41
|
+
# `mongodb_memory` tool in strands-agents-tools reports plain "Strands". Changing it orphans usage data.
|
|
42
|
+
_DRIVER_NAME = "Strands-MongoDB"
|
|
43
|
+
|
|
44
|
+
_MISSING_CONNECTION = (
|
|
45
|
+
"strands_mongodb: a MongoDB connection is required, but neither 'client' nor "
|
|
46
|
+
"'connection_string' was set in the configuration. Set 'connection_string' to a MongoDB URI, or "
|
|
47
|
+
"set 'client' to an AsyncMongoClient you already have."
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
_RETRY_WRITES_DISABLED = (
|
|
51
|
+
"retryWrites is disabled on this MongoDB connection. strands_mongodb relies on the driver's own "
|
|
52
|
+
"retry to replay its idempotent upserts across a primary stepdown, and with retryWrites=false "
|
|
53
|
+
"that replay does not happen: a write interrupted by an election surfaces to the caller instead. "
|
|
54
|
+
"Nothing is corrupted either way. Remove retryWrites=false to restore the behavior this package "
|
|
55
|
+
"was designed around."
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass
|
|
60
|
+
class Capabilities:
|
|
61
|
+
"""What a deployment can do, probed once and cached on its connection.
|
|
62
|
+
|
|
63
|
+
``_Connection.capabilities`` is ``None`` until the probe has run, so "not probed" never shares a value
|
|
64
|
+
with "no search".
|
|
65
|
+
|
|
66
|
+
Attributes:
|
|
67
|
+
search: Whether the deployment runs Atlas Search. This is a property of the deployment, not of a
|
|
68
|
+
collection, so one probe serves every store on the connection.
|
|
69
|
+
no_search_code: The server error code that reported no search, or ``None``. Set only when
|
|
70
|
+
``search`` is ``False``. Cached because ``search()`` names it in every later error, and the
|
|
71
|
+
code differs by server version and build, so nothing else on hand can derive it.
|
|
72
|
+
rank_fusion: Whether the deployment's ``mongod`` is new enough for ``$rankFusion``, the hybrid
|
|
73
|
+
tier. It is probed only where search exists, because hybrid also needs both search tiers.
|
|
74
|
+
The default is ``False`` so a deployment that was never probed is never sent a stage it
|
|
75
|
+
cannot run.
|
|
76
|
+
|
|
77
|
+
Unlike ``search``, this is read from the server version. Atlas Search is a separate process
|
|
78
|
+
whose presence no version predicts, while ``$rankFusion`` is a stage inside the process that
|
|
79
|
+
``buildInfo`` describes.
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
search: bool
|
|
83
|
+
no_search_code: int | None = None
|
|
84
|
+
rank_fusion: bool = False
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass
|
|
88
|
+
class _Connection:
|
|
89
|
+
"""One MongoDB connection and the per-connection state a ``TypedDict`` cannot hold.
|
|
90
|
+
|
|
91
|
+
No field holds the connection string. A dataclass ``__repr__`` covers every field, so a stored URI
|
|
92
|
+
would print its inline password wherever this object is rendered.
|
|
93
|
+
|
|
94
|
+
Attributes:
|
|
95
|
+
client: The shared client, built here or injected by the caller.
|
|
96
|
+
owned: Whether this module built the client. ``False`` for an injected client, which is never
|
|
97
|
+
closed.
|
|
98
|
+
lock: Guards one-time setup, such as index creation, against concurrent stores. Valid only for
|
|
99
|
+
``loop``; read it through :meth:`get_lock`.
|
|
100
|
+
loop: The event loop ``lock`` is usable on, or ``None`` before its first use.
|
|
101
|
+
capabilities: Result of the server capability probe, or ``None`` until it has run.
|
|
102
|
+
binary_keys: ``(database, collection)`` pairs whose default collation was read and found binary.
|
|
103
|
+
A namespace is added only when a collection existed to read it from, because
|
|
104
|
+
``listCollections`` reports an absent collection and an uncollated one identically. Cached on
|
|
105
|
+
the connection because every store over one collection, including each namespaced store,
|
|
106
|
+
shares the answer. A collation cannot be altered in place, so the cache goes stale only if the
|
|
107
|
+
collection is dropped and recreated under the same name while the process runs.
|
|
108
|
+
recheck_attribution: Whether a later ``resolve`` of an injected client should check its driver
|
|
109
|
+
metadata again and re-apply the attribution if it is gone. Cleared for good when an append
|
|
110
|
+
does not become visible, which bounds the re-applying on a driver that ignores it.
|
|
111
|
+
"""
|
|
112
|
+
|
|
113
|
+
# `repr=False` because `AsyncMongoClient.__repr__` renders every non-default option. pymongo redacts
|
|
114
|
+
# the URI password but not `authMechanismProperties` (which can carry `AWS_SESSION_TOKEN`) or
|
|
115
|
+
# `tlsCertificateKeyFilePassword`, and this repr is reached through `repr(_REGISTRY)` as well.
|
|
116
|
+
client: AsyncMongoClient[Any] = field(repr=False)
|
|
117
|
+
owned: bool
|
|
118
|
+
lock: asyncio.Lock = field(default_factory=asyncio.Lock)
|
|
119
|
+
loop: asyncio.AbstractEventLoop | None = None
|
|
120
|
+
capabilities: Capabilities | None = None
|
|
121
|
+
binary_keys: set[tuple[str, str]] = field(default_factory=set)
|
|
122
|
+
recheck_attribution: bool = True
|
|
123
|
+
|
|
124
|
+
def get_lock(self) -> asyncio.Lock:
|
|
125
|
+
"""Return a lock usable on the running event loop, replacing it if the loop changed.
|
|
126
|
+
|
|
127
|
+
A synchronous ``Agent`` runs each invocation on a fresh loop, and an ``asyncio.Lock`` that created
|
|
128
|
+
a waiter future on one loop raises ``RuntimeError`` when awaited on another. The binding happens
|
|
129
|
+
only under contention, so an uncontended lock crosses loops silently until load arrives, and from
|
|
130
|
+
then on every contended acquire on a later loop raises.
|
|
131
|
+
|
|
132
|
+
Replacing the lock is safe because it only guards work scoped to one loop. Any waiters on the old
|
|
133
|
+
lock belong to a loop that has already closed.
|
|
134
|
+
|
|
135
|
+
Returns:
|
|
136
|
+
A lock bound to the running loop, stable for the lifetime of that loop.
|
|
137
|
+
|
|
138
|
+
Raises:
|
|
139
|
+
RuntimeError: If called with no running event loop.
|
|
140
|
+
"""
|
|
141
|
+
running = asyncio.get_running_loop()
|
|
142
|
+
if self.loop is not running:
|
|
143
|
+
self.lock = asyncio.Lock()
|
|
144
|
+
self.loop = running
|
|
145
|
+
return self.lock
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
#: A connection identity paired with the event loop that connection serves. ``None`` means no loop: a
|
|
149
|
+
#: client built by synchronous code that no loop has adopted yet, or an injected client, which is never
|
|
150
|
+
#: split per loop.
|
|
151
|
+
_RegistryKey = tuple[str, asyncio.AbstractEventLoop | None]
|
|
152
|
+
|
|
153
|
+
# Keyed by the digest from `_identity`, never by a connection string, so the keys cannot leak a password.
|
|
154
|
+
# Process-global: every store built from one config shares one pool per event loop.
|
|
155
|
+
_REGISTRY: dict[_RegistryKey, _Connection] = {}
|
|
156
|
+
|
|
157
|
+
_REGISTRY_LOCK: Final = threading.RLock()
|
|
158
|
+
"""Guards every read, mutation and iteration of :data:`_REGISTRY`.
|
|
159
|
+
|
|
160
|
+
A thread lock, not an ``asyncio`` one: ``resolve`` is synchronous (the store constructors call it), and
|
|
161
|
+
threads that each run their own loop, as synchronous ``Agent`` instances do, reach the registry with no
|
|
162
|
+
loop in common.
|
|
163
|
+
|
|
164
|
+
Reentrant because ``resolve`` holds it while calling :func:`_register`, which takes it too. Splitting the
|
|
165
|
+
two to avoid nesting would put a check and its act on either side of a release.
|
|
166
|
+
|
|
167
|
+
Never held across an ``await``. Because it is reentrant, another coroutine on the same thread would
|
|
168
|
+
acquire it while the holder is suspended, so it would exclude nothing on that loop. Meanwhile every other
|
|
169
|
+
thread that reaches the registry would block for the whole wait.
|
|
170
|
+
"""
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _running_loop() -> asyncio.AbstractEventLoop | None:
|
|
174
|
+
"""Return the running event loop, or ``None`` when there is none.
|
|
175
|
+
|
|
176
|
+
``resolve`` is called both from coroutines and from ``MongoDBStorage.__init__`` at module level, where
|
|
177
|
+
no loop is running.
|
|
178
|
+
|
|
179
|
+
Returns:
|
|
180
|
+
The running loop, or ``None`` outside one.
|
|
181
|
+
"""
|
|
182
|
+
try:
|
|
183
|
+
return asyncio.get_running_loop()
|
|
184
|
+
except RuntimeError:
|
|
185
|
+
return None
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def _reap_closed_loops() -> None:
|
|
189
|
+
"""Drop every registry entry whose event loop has closed.
|
|
190
|
+
|
|
191
|
+
Called each time a client is built. It sweeps every identity because such an entry is unusable by
|
|
192
|
+
anyone: pymongo refuses the client from any other loop. Keeping it would leak one entry per loop for the
|
|
193
|
+
life of the process.
|
|
194
|
+
|
|
195
|
+
The client is dropped, not closed, because ``close()`` sends ``endSessions`` on the loop that is gone.
|
|
196
|
+
Its sockets are reachable only from that loop's selector, and their file descriptors are released when
|
|
197
|
+
the object is collected.
|
|
198
|
+
|
|
199
|
+
The snapshot and the removals run under :data:`_REGISTRY_LOCK` because another thread may be writing
|
|
200
|
+
the dict.
|
|
201
|
+
"""
|
|
202
|
+
with _REGISTRY_LOCK:
|
|
203
|
+
for key in [key for key, _ in _REGISTRY.items() if key[1] is not None and key[1].is_closed()]:
|
|
204
|
+
_REGISTRY.pop(key, None)
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def _package_version() -> str:
|
|
208
|
+
"""Return this package's installed version for driver attribution.
|
|
209
|
+
|
|
210
|
+
Returns:
|
|
211
|
+
The installed version, or ``"unknown"`` when the package is not installed as a distribution,
|
|
212
|
+
which happens when it is run straight from a source checkout.
|
|
213
|
+
"""
|
|
214
|
+
try:
|
|
215
|
+
return version("strands-mongodb")
|
|
216
|
+
except PackageNotFoundError: # pragma: no cover - requires an uninstalled source checkout
|
|
217
|
+
return "unknown"
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def _driver_info() -> DriverInfo:
|
|
221
|
+
"""Build the attribution PyMongo appends to its own driver metadata.
|
|
222
|
+
|
|
223
|
+
Returns:
|
|
224
|
+
A ``DriverInfo`` naming this package and its installed version.
|
|
225
|
+
"""
|
|
226
|
+
return DriverInfo(name=_DRIVER_NAME, version=_package_version())
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _identity(config: MongoDBConfig) -> str:
|
|
230
|
+
"""Compute the registry key for a config.
|
|
231
|
+
|
|
232
|
+
Two configs share a client when they would produce the same one. ``database`` is excluded, since one
|
|
233
|
+
client serves any number of databases. ``client_args`` is included, because a client built with
|
|
234
|
+
different timeouts is a different client and a cache hit would otherwise discard the arguments.
|
|
235
|
+
|
|
236
|
+
An injected client keys on its object identity. Two clients built from the same URI can differ in
|
|
237
|
+
credentials, read preference or timeouts, so handing one caller another's client would be wrong.
|
|
238
|
+
|
|
239
|
+
The result is a digest, never the connection string itself. A dict keyed on URIs leaks its keys
|
|
240
|
+
through ``repr``, a ``KeyError`` and any debugger that walks module globals, and a digest cannot be
|
|
241
|
+
reversed into a password.
|
|
242
|
+
|
|
243
|
+
Args:
|
|
244
|
+
config: The configuration to key.
|
|
245
|
+
|
|
246
|
+
Returns:
|
|
247
|
+
An opaque key, stable for the lifetime of the process.
|
|
248
|
+
|
|
249
|
+
Raises:
|
|
250
|
+
ValueError: If neither ``client`` nor ``connection_string`` is set.
|
|
251
|
+
"""
|
|
252
|
+
injected = config.get("client")
|
|
253
|
+
if injected is not None:
|
|
254
|
+
return f"client:{id(injected):x}"
|
|
255
|
+
|
|
256
|
+
connection_string = config.get("connection_string")
|
|
257
|
+
if not connection_string:
|
|
258
|
+
raise ValueError(_MISSING_CONNECTION)
|
|
259
|
+
|
|
260
|
+
# `default=repr` so an unserializable argument (a `ServerApi`, an SSLContext) still produces a key.
|
|
261
|
+
# Distinct objects then key distinctly, which errs toward a second client over sharing the wrong one.
|
|
262
|
+
args = json.dumps(config.get("client_args") or {}, sort_keys=True, default=repr)
|
|
263
|
+
digest = hashlib.sha256(f"{connection_string}\x00{args}".encode()).hexdigest()
|
|
264
|
+
return f"uri:{digest}"
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def _warn_if_retries_disabled(client: AsyncMongoClient[Any]) -> None:
|
|
268
|
+
"""Warn when the resolved client will not retry writes.
|
|
269
|
+
|
|
270
|
+
Reads ``client.options`` rather than parsing the URI, so it catches the setting whether it came from
|
|
271
|
+
the URI, from ``client_args`` or from an injected client.
|
|
272
|
+
|
|
273
|
+
Args:
|
|
274
|
+
client: The client about to be registered.
|
|
275
|
+
"""
|
|
276
|
+
if client.options.retry_writes is False:
|
|
277
|
+
logger.warning(_RETRY_WRITES_DISABLED, extra=_telemetry.event_extra("retry_writes_disabled"))
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
def _already_attributed(client: AsyncMongoClient[Any]) -> bool:
|
|
281
|
+
"""Whether this client's driver metadata already carries this package's exact entry.
|
|
282
|
+
|
|
283
|
+
``driver.name`` and ``driver.version`` are pipe-delimited chains, such as ``PyMongo|c|async|Strands-MongoDB``
|
|
284
|
+
and ``4.17.0|0.1.0``. Per the MongoDB handshake specification, two entries are the same only when the name
|
|
285
|
+
and the version are both equal, compared case-sensitively; a name alone is not enough. Entries are paired
|
|
286
|
+
from the right, because pymongo's own name has more entries than its version.
|
|
287
|
+
|
|
288
|
+
Args:
|
|
289
|
+
client: The client to inspect, read through its public ``options``.
|
|
290
|
+
|
|
291
|
+
Returns:
|
|
292
|
+
Whether an entry with this package's name and version is already in the chains.
|
|
293
|
+
"""
|
|
294
|
+
driver = client.options.pool_options.metadata["driver"]
|
|
295
|
+
ours = _driver_info()
|
|
296
|
+
# `strict=False` on purpose: the two chains differ in length by design.
|
|
297
|
+
pairs = zip(reversed(driver["name"].split("|")), reversed(driver["version"].split("|")), strict=False)
|
|
298
|
+
return any(name == ours.name and version == ours.version for name, version in pairs)
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
def _attribute_injected_client(client: AsyncMongoClient[Any]) -> None:
|
|
302
|
+
"""Attach this package's driver attribution to a client the caller injected, at most once.
|
|
303
|
+
|
|
304
|
+
This inlines ``pymongo_search_utils.append_client_metadata``, which lives in the ``[memory]`` extra,
|
|
305
|
+
while this module must also work under a ``[storage]``-only install.
|
|
306
|
+
|
|
307
|
+
``append_metadata`` is called without probing for it because the pymongo floor, 4.14.0, introduced it.
|
|
308
|
+
On older versions a ``hasattr`` probe would pass anyway, since the client's ``__getattr__`` returns a
|
|
309
|
+
``Database`` of that name.
|
|
310
|
+
|
|
311
|
+
Args:
|
|
312
|
+
client: The injected client to attribute in place.
|
|
313
|
+
"""
|
|
314
|
+
# At most once: closing a store and resolving the same client again reaches this call again. pymongo
|
|
315
|
+
# 4.14.0 does not dedupe the append, so each cycle would grow the handshake until it passes the
|
|
316
|
+
# server's 512-byte client metadata limit and every new connection fails (22 cycles on mongod 8).
|
|
317
|
+
if _already_attributed(client):
|
|
318
|
+
return
|
|
319
|
+
|
|
320
|
+
client.append_metadata(_driver_info())
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
def _reattribute_if_it_was_discarded(connection: _Connection) -> None:
|
|
324
|
+
"""Re-apply an injected client's attribution if the driver discarded it.
|
|
325
|
+
|
|
326
|
+
``append_metadata`` writes into the client's ``ClientOptions``, and resolving a ``mongodb+srv://`` URI
|
|
327
|
+
replaces them on the client's first connection. For an injected SRV client the append lands first and
|
|
328
|
+
is lost (pymongo 4.17.0: ``PyMongo|c|async|Strands-MongoDB`` before, ``PyMongo|c|async`` after). This restores
|
|
329
|
+
the attribution for every pool built afterwards, not for handshakes already sent.
|
|
330
|
+
|
|
331
|
+
Args:
|
|
332
|
+
connection: The registered connection for an injected client.
|
|
333
|
+
"""
|
|
334
|
+
if not connection.recheck_attribution:
|
|
335
|
+
return
|
|
336
|
+
client = connection.client
|
|
337
|
+
if _already_attributed(client):
|
|
338
|
+
# The flag stays set: the loss happens on the first connection, which can come after any resolve.
|
|
339
|
+
return
|
|
340
|
+
|
|
341
|
+
client.append_metadata(_driver_info())
|
|
342
|
+
if _already_attributed(client):
|
|
343
|
+
return
|
|
344
|
+
|
|
345
|
+
# The append did not become visible, so retrying would grow the handshake once per resolve on a driver
|
|
346
|
+
# that appends without deduping. Stop after one attempt.
|
|
347
|
+
connection.recheck_attribution = False
|
|
348
|
+
logger.debug(
|
|
349
|
+
"strands_mongodb: append_metadata did not become visible on the injected client, so the Strands-MongoDB "
|
|
350
|
+
"attribution is left as it is",
|
|
351
|
+
extra=_telemetry.event_extra("attribution_not_visible"),
|
|
352
|
+
)
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def resolve(config: MongoDBConfig) -> _Connection:
|
|
356
|
+
"""Return the shared connection for a config and the running loop, creating it on first use.
|
|
357
|
+
|
|
358
|
+
There is one pool per connection identity per event loop. ``AsyncMongoClient`` binds to the loop of
|
|
359
|
+
its first operation, so one client cannot serve a synchronous ``Agent``, which runs every entry point
|
|
360
|
+
on a loop of its own.
|
|
361
|
+
|
|
362
|
+
Args:
|
|
363
|
+
config: The configuration to resolve. Only the connection fields are read.
|
|
364
|
+
|
|
365
|
+
Returns:
|
|
366
|
+
The registered connection. The same object for every config with the same connection identity
|
|
367
|
+
resolved on the same loop, so callers must not mutate it.
|
|
368
|
+
|
|
369
|
+
Raises:
|
|
370
|
+
ValueError: If neither ``client`` nor ``connection_string`` is set. Raised before any client is
|
|
371
|
+
built, and nothing is registered. pymongo would otherwise read a schemeless string as a
|
|
372
|
+
hostname and fail later with a server-selection timeout against ``localhost``.
|
|
373
|
+
ValueError: If ``AsyncMongoClient`` rejects a malformed connection string or option value. It is
|
|
374
|
+
not wrapped, and nothing is registered.
|
|
375
|
+
pymongo.errors.ConfigurationError: If ``AsyncMongoClient`` rejects an option, such as an unknown
|
|
376
|
+
``client_args`` key. It is not wrapped, and nothing is registered.
|
|
377
|
+
"""
|
|
378
|
+
identity = _identity(config)
|
|
379
|
+
|
|
380
|
+
# One lock over the whole body: every branch is a check followed by an act on process-global state.
|
|
381
|
+
# Nothing here does I/O, since `AsyncMongoClient()` connects lazily. `_identity` runs above the lock so
|
|
382
|
+
# an unusable config is rejected without touching the registry.
|
|
383
|
+
with _REGISTRY_LOCK:
|
|
384
|
+
injected = config.get("client")
|
|
385
|
+
if injected is not None:
|
|
386
|
+
# One slot, keyed on no loop: there is no second copy to build, and an injected client is never
|
|
387
|
+
# closed. Driving it from two loops gets pymongo's own RuntimeError.
|
|
388
|
+
return _register(identity, None, injected, owned=False, attribute=True)
|
|
389
|
+
|
|
390
|
+
running = _running_loop()
|
|
391
|
+
existing = _REGISTRY.get((identity, running))
|
|
392
|
+
if existing is not None:
|
|
393
|
+
# Returning here keeps the retryWrites warning to one line per connection, not one per store.
|
|
394
|
+
return existing
|
|
395
|
+
|
|
396
|
+
if running is not None:
|
|
397
|
+
# Adoption: a client built with no loop running has not bound to a loop, so the first loop
|
|
398
|
+
# that asks takes it over. Building another would leave the first open and never closed in the
|
|
399
|
+
# common case of a store constructed at import time and used on one loop.
|
|
400
|
+
adopted = _REGISTRY.pop((identity, None), None)
|
|
401
|
+
if adopted is not None:
|
|
402
|
+
_REGISTRY[(identity, running)] = adopted
|
|
403
|
+
return adopted
|
|
404
|
+
|
|
405
|
+
_reap_closed_loops()
|
|
406
|
+
|
|
407
|
+
# `driver=` reaches pymongo through `**kwargs`, so nothing type checks it; the tests assert the
|
|
408
|
+
# resulting pool metadata. `appName` is left to the application.
|
|
409
|
+
client: AsyncMongoClient[Any] = AsyncMongoClient(
|
|
410
|
+
config["connection_string"],
|
|
411
|
+
driver=_driver_info(),
|
|
412
|
+
**(config.get("client_args") or {}),
|
|
413
|
+
)
|
|
414
|
+
return _register(identity, running, client, owned=True, attribute=False)
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def _register(
|
|
418
|
+
identity: str,
|
|
419
|
+
loop: asyncio.AbstractEventLoop | None,
|
|
420
|
+
client: AsyncMongoClient[Any],
|
|
421
|
+
*,
|
|
422
|
+
owned: bool,
|
|
423
|
+
attribute: bool,
|
|
424
|
+
) -> _Connection:
|
|
425
|
+
"""Put a client in the registry under one identity and loop, warning at most once about it.
|
|
426
|
+
|
|
427
|
+
Args:
|
|
428
|
+
identity: The connection identity from :func:`_identity`.
|
|
429
|
+
loop: The loop this client serves, or ``None`` for the loop-independent slot.
|
|
430
|
+
client: The client to register.
|
|
431
|
+
owned: Whether this module built it, which decides whether :func:`close` may close it.
|
|
432
|
+
attribute: Whether to attach this package's driver attribution, which only an injected client needs.
|
|
433
|
+
|
|
434
|
+
Returns:
|
|
435
|
+
The registered connection, existing or new.
|
|
436
|
+
"""
|
|
437
|
+
# Takes the lock itself so the check and the insert are one step across threads, which is what keeps
|
|
438
|
+
# the warning to at most once. The lock is reentrant, so nesting under `resolve` is free.
|
|
439
|
+
with _REGISTRY_LOCK:
|
|
440
|
+
existing = _REGISTRY.get((identity, loop))
|
|
441
|
+
if existing is not None:
|
|
442
|
+
if attribute:
|
|
443
|
+
_reattribute_if_it_was_discarded(existing)
|
|
444
|
+
return existing
|
|
445
|
+
if attribute:
|
|
446
|
+
_attribute_injected_client(client)
|
|
447
|
+
_warn_if_retries_disabled(client)
|
|
448
|
+
connection = _Connection(client=client, owned=owned)
|
|
449
|
+
_REGISTRY[(identity, loop)] = connection
|
|
450
|
+
# Runs once per new registry entry (a cache hit returns above and adoption skips this function), so a
|
|
451
|
+
# pool built is an event and a pool reused is not. Safe under the caller's lock: it does no I/O.
|
|
452
|
+
_telemetry.event("strands_mongodb.client.acquired", {"strands_mongodb.client.injected": not owned})
|
|
453
|
+
return connection
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
async def close(config: MongoDBConfig) -> None:
|
|
457
|
+
"""Release the connection for a config, closing the client only if this module built it.
|
|
458
|
+
|
|
459
|
+
An injected client is never closed. It is often shared with other subsystems and the application's
|
|
460
|
+
own queries, and closing it would break them somewhere else, later.
|
|
461
|
+
|
|
462
|
+
Idempotent, and safe on a config that was never resolved, since callers run it from ``finally`` blocks
|
|
463
|
+
and ``atexit`` handlers. Every loop's slot for the identity is released, not only the running loop's, because
|
|
464
|
+
nothing in the public API names a loop.
|
|
465
|
+
|
|
466
|
+
Args:
|
|
467
|
+
config: The configuration whose connection to release.
|
|
468
|
+
"""
|
|
469
|
+
try:
|
|
470
|
+
identity = _identity(config)
|
|
471
|
+
except ValueError:
|
|
472
|
+
# Nothing was ever registered for this config, and a teardown path should not raise.
|
|
473
|
+
return
|
|
474
|
+
|
|
475
|
+
running = asyncio.get_running_loop()
|
|
476
|
+
with _REGISTRY_LOCK:
|
|
477
|
+
# Snapshot under the lock, iterate outside it: the loop body awaits, and the lock is never held
|
|
478
|
+
# across an `await`.
|
|
479
|
+
keys = [key for key in _REGISTRY if key[0] == identity]
|
|
480
|
+
|
|
481
|
+
for key in keys:
|
|
482
|
+
# Popped with a default: during the `await` below, a concurrent `close()` for the same config or a
|
|
483
|
+
# reap in `resolve()` may already have removed the slot.
|
|
484
|
+
with _REGISTRY_LOCK:
|
|
485
|
+
connection = _REGISTRY.pop(key, None)
|
|
486
|
+
if connection is None or not connection.owned:
|
|
487
|
+
continue
|
|
488
|
+
loop = key[1]
|
|
489
|
+
if loop is None or loop is running:
|
|
490
|
+
await connection.client.close()
|
|
491
|
+
elif not loop.is_closed():
|
|
492
|
+
# Another live loop's client must close on that loop, since `endSessions` uses its sockets.
|
|
493
|
+
# Scheduled, not awaited: this loop may be the one that loop is waiting for.
|
|
494
|
+
pending = connection.client.close()
|
|
495
|
+
try:
|
|
496
|
+
asyncio.run_coroutine_threadsafe(pending, loop)
|
|
497
|
+
except RuntimeError:
|
|
498
|
+
# That loop closed between the check and the call. Swallowed so the remaining slots are
|
|
499
|
+
# still released, and the coroutine is closed so it never warns as un-awaited. The client
|
|
500
|
+
# is dropped unclosed, like any closed loop's client.
|
|
501
|
+
pending.close()
|
|
502
|
+
logger.debug(
|
|
503
|
+
"strands_mongodb: an event loop closed while its client was being scheduled for "
|
|
504
|
+
"close; the slot is released and the client is dropped unclosed",
|
|
505
|
+
extra=_telemetry.event_extra("closed_loop_client_dropped"),
|
|
506
|
+
)
|
|
507
|
+
# A closed loop's client is dropped, not closed: `close()` needs the loop its sockets belong to,
|
|
508
|
+
# and pymongo raises a `RuntimeError` there, which is not a `PyMongoError`.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Actionable import errors for surfaces whose install extra is missing."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import NoReturn
|
|
6
|
+
|
|
7
|
+
__all__ = ["missing_extra"]
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def missing_extra(extra: str, error: ImportError, *, module: str) -> NoReturn:
|
|
11
|
+
"""Re-raise an import failure as a message naming the extra that fixes it.
|
|
12
|
+
|
|
13
|
+
A bare ``pip install strands-mongodb`` installs no runtime dependencies, so without this a backend
|
|
14
|
+
imported without its extra fails with a ``ModuleNotFoundError`` that does not say what to install.
|
|
15
|
+
|
|
16
|
+
``module`` is passed rather than derived from ``extra`` because the two names differ:
|
|
17
|
+
``strands_mongodb.memory_store`` needs the ``memory`` extra.
|
|
18
|
+
|
|
19
|
+
Args:
|
|
20
|
+
extra: The extra providing this surface's dependencies: ``storage`` or ``memory``.
|
|
21
|
+
error: The original import failure.
|
|
22
|
+
module: The importing module's ``__name__``.
|
|
23
|
+
|
|
24
|
+
Raises:
|
|
25
|
+
ImportError: Always, chained to ``error``, carrying the pip command that resolves it.
|
|
26
|
+
"""
|
|
27
|
+
raise ImportError(
|
|
28
|
+
f"{module} requires the '{extra}' extra, which is not installed.\n"
|
|
29
|
+
f"\n"
|
|
30
|
+
f" pip install 'strands-mongodb[{extra}]'\n"
|
|
31
|
+
f"\n"
|
|
32
|
+
f"Or install every surface at once:\n"
|
|
33
|
+
f"\n"
|
|
34
|
+
f" pip install 'strands-mongodb[all]'\n"
|
|
35
|
+
f"\n"
|
|
36
|
+
f"Keep the quotes -- zsh and fish expand unquoted brackets as a glob and the command "
|
|
37
|
+
f"fails before pip runs.\n"
|
|
38
|
+
f"Missing module: {error.name or error}"
|
|
39
|
+
) from error
|