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.
@@ -0,0 +1,221 @@
1
+ """Caller-filter validation and scope composition, shared by the search paths.
2
+
3
+ Three guards and one composer, all pure functions over plain mappings. Nothing here imports pymongo or
4
+ does I/O, so the security guards can be tested without a deployment.
5
+
6
+ The guards are separate because they answer different questions with different remedies: what a key
7
+ is (a string with no leading ``$``), what a value does (no regex), and whether the index declared the
8
+ field. One combined pass would give one message for three unrelated problems.
9
+
10
+ Private module: the validated filter shape is a promise, these signatures are not.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import copy
16
+ import re
17
+
18
+ # Imported at runtime, not under ``TYPE_CHECKING``: the guards' ``isinstance`` checks need ``Mapping``.
19
+ from collections.abc import Mapping
20
+ from typing import TYPE_CHECKING, Any
21
+
22
+ if TYPE_CHECKING:
23
+ from collections.abc import Collection, Iterable
24
+
25
+ __all__ = ["compose", "validate"]
26
+
27
+ # Fields the vector index always declares filterable, before `filter_fields`. `_indexes` builds the
28
+ # declared set from this, and `validate` takes that set as an argument rather than reading this.
29
+ BAKED_IN_FILTER_FIELDS = ("scope", "store_name")
30
+
31
+ # `bson.Regex`, matched by name so this module needs no pymongo import. The MRO is walked so a subclass
32
+ # cannot slip past. In pymongo 4.x the class is `bson.regex.Regex`.
33
+ _REGEX_TYPE_NAMES = frozenset({"bson.regex.Regex"})
34
+
35
+
36
+ def _reject_operator_keys(value: Any) -> None:
37
+ """Raise if any key at any depth is ``$``-prefixed or not a string.
38
+
39
+ Walks every mapping, list and tuple, which are the only containers bson encodes. A dict inside a list
40
+ is an equality operand to ``$match`` and cannot act as operators, but that is the server's guarantee,
41
+ not this function's, so lists are walked too.
42
+
43
+ Only keys are checked: a key is what MQL dispatches on, and a value is data (the string ``"$where"``
44
+ as a value is just a string). The one value that is not data is a regex, which
45
+ :func:`_reject_regex_values` refuses. Values are checked as the Python objects passed in, so a custom
46
+ codec on the client that encodes some other type as a subdocument is outside this guard.
47
+
48
+ Recursion is on ``collections.abc.Mapping``, not ``dict``. bson encodes any mapping as a
49
+ subdocument, so ``{"tier": UserDict({"$ne": "gold"})}`` would otherwise pass this guard and reach
50
+ the server as ``{"tier": {"$ne": "gold"}}``, matching every document whose tier is not gold.
51
+
52
+ Args:
53
+ value: A filter, or any value reached while walking one.
54
+
55
+ Raises:
56
+ ValueError: Naming the offending key.
57
+ """
58
+ if isinstance(value, Mapping):
59
+ for key, nested in value.items():
60
+ if not isinstance(key, str) or key.startswith("$"):
61
+ raise ValueError(
62
+ f"strands_mongodb: invalid filter key {key!r}. MongoDB operator keys and "
63
+ f"non-string keys are not allowed anywhere in a filter, at any depth. A filter is "
64
+ f"a mapping of field path to exact value, such as {{'metadata.tier': 'gold'}}."
65
+ )
66
+ _reject_operator_keys(nested)
67
+ elif isinstance(value, (list, tuple)):
68
+ for item in value:
69
+ _reject_operator_keys(item)
70
+
71
+
72
+ def _reject_regex_values(value: Any) -> None:
73
+ """Raise if any value at any depth is a regex.
74
+
75
+ A filter maps field paths to exact values. Given a regex, ``$match`` and ``$eq`` pattern-match
76
+ instead of comparing: ``{"tier": re.compile("^gol")}`` matches a document whose tier is ``"gold"``.
77
+ The operator guard cannot catch this because there is no ``$`` key. Pattern filters are refused
78
+ rather than supported, because their cost and reach depend on the pattern rather than on what a
79
+ reader sees.
80
+
81
+ Both ``re.Pattern`` and ``bson.Regex`` are refused, since both reach the server as a BSON regex.
82
+ Lists and tuples are walked as in the operator guard.
83
+
84
+ Args:
85
+ value: A filter, or any value reached while walking one.
86
+
87
+ Raises:
88
+ ValueError: Naming the field path that carries the regex, when there is one to name.
89
+ """
90
+ if isinstance(value, Mapping):
91
+ for key, nested in value.items():
92
+ if _is_regex(nested):
93
+ raise ValueError(
94
+ f"strands_mongodb: invalid filter value for {key!r}: a regular expression. A filter "
95
+ f"is a mapping of field path to exact value, and a regex is matched as a pattern "
96
+ f"rather than compared, so it would select documents this filter does not name. Pass "
97
+ f"the literal value to match, such as {{{key!r}: 'gold'}}."
98
+ )
99
+ _reject_regex_values(nested)
100
+ elif isinstance(value, (list, tuple)):
101
+ for item in value:
102
+ if _is_regex(item):
103
+ raise ValueError(
104
+ "strands_mongodb: invalid filter value: a regular expression inside a list. A filter "
105
+ "is a mapping of field path to exact value, at any depth, and a regex is matched as a "
106
+ "pattern rather than compared."
107
+ )
108
+ _reject_regex_values(item)
109
+
110
+
111
+ def _is_regex(value: Any) -> bool:
112
+ """Return whether a value would reach the server as a BSON regex.
113
+
114
+ Args:
115
+ value: Any value found in a filter.
116
+
117
+ Returns:
118
+ ``True`` for a compiled ``re.Pattern`` and for ``bson.Regex`` or any subclass of it.
119
+ """
120
+ if isinstance(value, re.Pattern):
121
+ return True
122
+ return any(f"{cls.__module__}.{cls.__qualname__}" in _REGEX_TYPE_NAMES for cls in type(value).__mro__)
123
+
124
+
125
+ def _reject_undeclared_fields(caller_filter: Mapping[str, Any], declared: Collection[str]) -> None:
126
+ """Raise if the filter names a path the index did not declare filterable.
127
+
128
+ mongot rejects such a filter itself (code 8, ``Path 'x' needs to be indexed as filter``, seen on
129
+ 8.3.8; not verified on Atlas proper). This guard still runs first so the error names the config key
130
+ to edit, the index rebuild it needs, and what is filterable now, without a round trip.
131
+
132
+ Checking top-level keys only is exact: the operator guard has already rejected ``$and`` and ``$or``,
133
+ so no field path can sit below the top level, and a dict value is exact subdocument equality on the
134
+ key above it.
135
+
136
+ Args:
137
+ caller_filter: A filter that has already passed the operator guard.
138
+ declared: Every path the index declares filterable: ``scope``, ``store_name`` and the config's
139
+ ``filter_fields``. Passed in so the index definition stays the single authority.
140
+
141
+ Raises:
142
+ ValueError: Naming every undeclared path, not only the first, and naming what is available.
143
+ """
144
+ undeclared = sorted(set(caller_filter) - set(declared))
145
+ if not undeclared:
146
+ return
147
+
148
+ available = ", ".join(sorted(declared)) or "none"
149
+ raise ValueError(
150
+ f"strands_mongodb: filter field(s) {', '.join(repr(field) for field in undeclared)} are not "
151
+ f"declared filterable on this index, and the server rejects a filter over an undeclared path. "
152
+ f"Filterable here: {available}. Add the field to 'filter_fields' in MongoDBConfig and recreate "
153
+ f"the index to filter on it."
154
+ )
155
+
156
+
157
+ def validate(caller_filter: Mapping[str, Any], *, declared_fields: Iterable[str]) -> None:
158
+ """Check a caller-supplied filter against all three guards.
159
+
160
+ A valid filter is a mapping from declared field paths to exact values. In detail:
161
+
162
+ * Every key, at any depth (inside nested mappings, lists and tuples), is a string that does not
163
+ start with ``$``. So no operators: no ``$and``, ``$or``, ``$ne``, ``$in``, ``$where``, ``$expr``.
164
+ * No value, at any depth, is a regex (``re.Pattern`` or ``bson.Regex``).
165
+ * Every top-level key is in ``declared_fields``. Dotted paths such as ``"metadata.tier"`` are allowed
166
+ when declared exactly so.
167
+
168
+ The order is part of the contract: operator keys, then regex values, then undeclared fields.
169
+ ``{"$where": ...}`` is both forbidden and undeclared, and a caller told to declare ``$where`` in
170
+ ``filter_fields`` might try to. An operator key is the more serious problem, so it is reported
171
+ before a regex.
172
+
173
+ Args:
174
+ caller_filter: The filter as the caller supplied it. Not modified.
175
+ declared_fields: Paths the index declares filterable.
176
+
177
+ Raises:
178
+ ValueError: From any guard, naming what was wrong.
179
+ """
180
+ _reject_operator_keys(caller_filter)
181
+ _reject_regex_values(caller_filter)
182
+ _reject_undeclared_fields(caller_filter, tuple(declared_fields))
183
+
184
+
185
+ def compose(
186
+ *caller_filters: Mapping[str, Any] | None,
187
+ scope: str,
188
+ store_name: str,
189
+ ) -> dict[str, Any]:
190
+ """Compose caller filters with the scope predicate as a conjunction.
191
+
192
+ ``$and`` rather than a merged dict: ``{**scope_predicate, **caller_filter}`` would let a caller's
193
+ ``scope`` key overwrite the store's. Under ``$and`` a caller term can only narrow, and a
194
+ contradictory one (``{"scope": "tenant-b"}`` against ``tenant-a``) matches nothing.
195
+
196
+ Variadic because a memory store has two caller filters: the one configured on the store and the one
197
+ on a single ``MongoDBSearchQuery``. Each stays its own term, since merging them would need a ``$and``
198
+ that :func:`validate` rejects.
199
+
200
+ Does not validate. Callers run :func:`validate` first.
201
+
202
+ Args:
203
+ *caller_filters: Caller filters, already validated, in the order they should appear.
204
+ ``None`` and ``{}`` both add no term.
205
+ scope: This store's scope. Never taken from caller input; an absent scope resolves to a sentinel
206
+ upstream, never to unfiltered.
207
+ store_name: This store's name, isolating it from other stores in the same collection.
208
+
209
+ Returns:
210
+ A ``$and`` predicate with the scope term first, then the store term, then every non-empty caller
211
+ filter. Deep-copied, so the caller's dicts and the returned predicate share no structure.
212
+ """
213
+ terms: list[dict[str, Any]] = [
214
+ {"scope": {"$eq": scope}},
215
+ {"store_name": {"$eq": store_name}},
216
+ ]
217
+ for caller_filter in caller_filters:
218
+ if caller_filter:
219
+ # Deep, so mutating a nested value after composing cannot alter a query already in flight.
220
+ terms.append(copy.deepcopy(dict(caller_filter)))
221
+ return {"$and": terms}