queryapigate 0.47.0__tar.gz → 0.49.0__tar.gz

{queryapigate-0.47.0/queryapigate.egg-info → queryapigate-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.47.0
+Version: 0.49.0
 Summary: Turn SQL into governed REST APIs over MySQL, PostgreSQL, ClickHouse, SQLite, DuckDB, H2, MongoDB, and Parquet/CSV/JSON files - JSON, CSV, Parquet or Excel out, with scoped keys, an admin Console and MCP for AI agents.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
 License-Expression: Apache-2.0

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/__init__.py

@@ -1,5 +1,5 @@
 """QueryAPIGate - expose SQL databases as a REST API."""
-__version__ = "0.47.0"
+__version__ = "0.49.0"
 
 from .app import create_app  # noqa: E402  (app imports __version__)
 

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/alerts.py

@@ -44,13 +44,13 @@ _lock = threading.Lock()
 _refusals: dict[tuple, deque] = {}  # ('key' | 'client', who) -> monotonic times of rate-limit refusals
 
 
-def note_rate_limited(kind, who):
-    """One rate-limit refusal, for the 'keeps hitting its limit' alert: kind 'key' (a key's own rate_limit) or
-    'client' (QUERYAPIGATE_RATE_LIMIT, by address - checked before the caller is known)."""
+def note_rate_limited(kind, who, count=1):
+    """A rate-limit refusal (`count` of them, now), for the 'keeps hitting its limit' alert: kind 'key' (a key's own
+    rate_limit) or 'client' (QUERYAPIGATE_RATE_LIMIT, by address - checked before the caller is known)."""
     now = time.monotonic()
     with _lock:
         times = _refusals.setdefault((kind, who or 'unknown'), deque(maxlen=1000))
-        times.append(now)
+        times.extend([now] * min(count, 1000))
 
 
 # Every kind of alert, the one list: the OpenAPI enum is built from it and tests/test_alerts.py checks API.md's table.

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/app.py

@@ -178,7 +178,8 @@ class _CapturePeer:
     secret names the client's own socket address in X-QAG-Peer, and that address is taken as the real one - so this
     server sees the request as if the client had connected directly, ProxyFix and QUERYAPIGATE_TRUST_PROXY included.
     A peer that isn't an IP address counts as remote, as a Unix socket does. A data plane from another release
-    (X-QAG-Dataplane-Version) is still the data plane, but is given no plan (dataplane.paired()). Its headers are
+    (X-QAG-Dataplane-Version) is still the data plane, but is given no plan (dataplane.paired()). The rate-limit buckets
+    it counted a call in before forwarding it (X-QAG-Rate-Counted, ADR 0032) are taken from it alone. Its headers are
     removed here, so nothing after this layer reads, logs or passes on the secret."""
 
     def __init__(self, app):
@@ -189,10 +190,13 @@ class _CapturePeer:
         peer = environ.pop(dataplane.PEER_ENVIRON, None)
         wanted = environ.pop(dataplane.WANTED_ENVIRON, None)
         version = environ.pop(dataplane.VERSION_ENVIRON, None)
+        rate_counted = environ.pop(dataplane.COUNTED_ENVIRON, None)
         if supplied is not None and dataplane.matches(supplied):
             is_paired = dataplane.paired(version)
             environ['queryapigate.dataplane'] = 'plan' if wanted == '1' and is_paired else True
             environ['queryapigate.dataplane_paired'] = is_paired
+            if rate_counted is not None and is_paired:
+                environ['queryapigate.rate_counted'] = dataplane.counted(rate_counted)
             environ['REMOTE_ADDR'] = peer if dataplane.is_address(peer) else ''
         environ['queryapigate.peer_addr'] = environ.get('REMOTE_ADDR')
         return self.app(environ, start_response)
@@ -475,6 +479,10 @@ def check_rate_limit():
     """Count this request against its client's quota (governance.py); returns a 429 response when it is over."""
     if request.method == 'OPTIONS' or request.endpoint in RATE_LIMIT_EXEMPT:
         return None
+    counted = request.environ.get('queryapigate.rate_counted', {}).get('client')
+    if counted is not None and config.rate_limit() is not None:  # by the data plane, which then forwarded the call
+        g.rate_limit = counted
+        return None
     verdict = governance.check_client_limit(current_app, request.remote_addr)
     if verdict is None:
         return None
@@ -488,6 +496,10 @@ def check_key_rate_limit():
     per-key identity to limit by before then; a no-op for the admin key and the open/no-key case."""
     if request.method == 'OPTIONS' or request.endpoint in RATE_LIMIT_EXEMPT:
         return None
+    counted = request.environ.get('queryapigate.rate_counted', {}).get('key')
+    if counted is not None and getattr(g.get('permission'), 'rate_limit', None) is not None:  # as the client's, above
+        g.key_rate_limit = counted
+        return None
     verdict = governance.check_key_limit(current_app, g.get('permission'))
     if verdict is None:
         return None
@@ -1236,9 +1248,15 @@ def dataplane_runs():
 
     Each run comes with its history entry already JSON (`entry`), and the labels and timings /metrics counts it by: at
     the data plane's rates Python's own work per run - encoding it, and its labels - is what it can't keep up with, so
-    a batch is queued at once (history.record_reported()) and counted once per set of labels."""
+    a batch is queued at once (history.record_reported()) and counted once per set of labels.
+
+    `rate_limited`: the calls it refused itself with a 429 (ADR 0032) - by bucket, caller and method, one duration
+    each - counted as gate()'s own refusals are: in the rejections, the alerts and the request counters. Not runs."""
     report = request.get_json(silent=True) or {}
     runs = report.get('runs') or []
+    for refused in report.get('rate_limited') or []:
+        governance.note_refused(refused['scope'], refused.get('client'), refused.get('workspace'), refused.get('key'),
+                                refused['method'], refused['seconds'])
     broadcaster = current_app.extensions['queryapigate_broadcaster']
     with scope.using(scope.current()):  # resolved once, not by each of a busy batch's few thousand label lookups
         if report.get('recorded'):  # in the run store already: written by the data plane itself (ADR 0029 §4)

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/cli.py

@@ -127,8 +127,6 @@ def _init(args):
     inactive) now that connections are SQLite-backed - no more db_connections.json/saved_sql/ for a new
     install. On a home whose store already has connections, this is a no-op - "already exists - left
     untouched"."""
-    home = config.home()
-    home.mkdir(parents=True, exist_ok=True)
     if db.connection().execute('SELECT 1 FROM connections LIMIT 1').fetchone() is not None:
         print(f'{db.describe()} already has connections - left untouched')
         return 0
@@ -903,7 +901,7 @@ def build_parser():
     collection_import.add_argument('--dry-run', action='store_true', help='report what would happen; write nothing')
     collection_import.set_defaults(func=_collection_import)
 
-    config_parser = commands.add_parser('config', help="the server's configuration as a file (ADR 0014, experimental): "
+    config_parser = commands.add_parser('config', help="the server's configuration as a file (ADR 0014): "
                                                        'export it, see what applying one would change, apply it')
     config_parser.set_defaults(func=lambda a: config_parser.print_help() or 2)
     config_actions = config_parser.add_subparsers(dest='action')
@@ -1041,6 +1039,8 @@ def main(argv=None):
         os.environ['QUERYAPIGATE_HOME'] = args.home
     if getattr(args, 'server', None) or getattr(args, 'func', None) is _config_new_key:
         return args.func(args)  # nothing of this home's: no store opened, so none made in a CI checkout
+    if getattr(args, 'func', None) is _init:  # the one command that makes a home: the store below opens inside it
+        config.home().mkdir(parents=True, exist_ok=True)
     try:
         config.check_database_url()
         db.init_schema()

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/dataplane.py

@@ -21,6 +21,11 @@ which is slower but answers as Python does.
 
 Saved queries with `{name}` text placeholders never get a plan: their values are part of the SQL text, so the verdict
 can change from one call to the next.
+
+With Redis (QUERYAPIGATE_REDIS_URL), a key's rate limit and the server-wide QUERYAPIGATE_RATE_LIMIT are counted by the
+data plane too, in the same buckets (ADR 0032): the plan carries the key's limit, and the data plane counts a call
+only once it is going to serve it. A call it forwards after counting says so (X-QAG-Rate-Counted), and is not counted
+again here. Its refusals reach /metrics and the alerts with its runs report.
 """
 import base64
 import hmac
@@ -37,6 +42,7 @@ PEER_HEADER = 'X-QAG-Peer'
 WANTED_HEADER = 'X-QAG-Plan-Wanted'
 VERSION_HEADER = 'X-QAG-Dataplane-Version'  # the data plane's release, sent with its secret
 PLAN_HEADER = 'X-QAG-Plan'
+COUNTED_HEADER = 'X-QAG-Rate-Counted'  # the rate-limit buckets a call the data plane forwards was counted in already
 VERSION = 1
 DIALECTS = ('postgres', 'mysql')  # the two the prototype serves - every other connection is forwarded
 _ROWS = ('api_key', 'saved_query', 'connection')  # what a plan names the digests of, one row set each
@@ -47,6 +53,7 @@ PEER_ENVIRON = 'HTTP_X_QAG_PEER'
 # The data plane asks for a plan only when it would keep one: other calls it forwards keep the metadata cache
 WANTED_ENVIRON = 'HTTP_X_QAG_PLAN_WANTED'
 VERSION_ENVIRON = 'HTTP_X_QAG_DATAPLANE_VERSION'
+COUNTED_ENVIRON = 'HTTP_X_QAG_RATE_COUNTED'
 UNPAIRED = ('This data plane is from another release than this server: it gets no plans and no run store lease '
             'until both are the same release')
 _unpaired_seen: set = set()
@@ -80,11 +87,29 @@ def is_address(peer):
 
 def eligible_caller(permission):
     """A caller the data plane may serve: a scoped API key - not an administrator, a signed-in user or an open server -
-    in the default workspace, with none of the limits that keep their own state (rate limit, quota, ADR 0011's)."""
+    in the default workspace, without the limits that keep state: no quota or max_concurrent, and a rate limit only
+    when Redis holds its bucket, where the data plane counts it too (ADR 0032). Without Redis each process would count
+    its own budget. A query_timeout and max_rows keep none: the plan carries them, and the data plane applies each as
+    limits.py does."""
     return (permission is not None and not permission.admin and permission.claims is None and permission.role is None
             and not permission.claim_binding and permission.workspace == 'default'
-            and permission.rate_limit is None and permission.quota is None and permission.max_concurrent is None
-            and permission.query_timeout is None and permission.max_rows is None)
+            and (permission.rate_limit is None or config.redis_url() is not None)
+            and permission.quota is None and permission.max_concurrent is None)
+
+
+def counted(value):
+    """X-QAG-Rate-Counted (`client=<limit>,<remaining>; key=<limit>,<remaining>`, either or both) as
+    {'client' | 'key': (limit, remaining)}: the buckets the data plane counted this call in before forwarding it, and
+    what they said. {} for a value of any other shape."""
+    found = {}
+    for part in (value or '').split(';'):
+        bucket, _, numbers = part.strip().partition('=')
+        limit, _, remaining = numbers.partition(',')
+        if bucket not in ('client', 'key') or bucket in found or not (limit.isascii() and limit.isdigit()
+                                                                      and remaining.isascii() and remaining.isdigit()):
+            return {}
+        found[bucket] = (int(limit), int(remaining))
+    return found
 
 
 def digests(record):
@@ -161,6 +186,11 @@ def build(record, permission, query_name, number, saved, connection_name, result
             return None
         mask = {'columns': len(masked.traced), 'actions': masked.actions, 'fired': masked.fired}
     return {'v': VERSION, 'rows': rows, 'key': {'workspace': permission.workspace, 'name': permission.name},
+            # (count, period in seconds): counted by the data plane in Redis, in the bucket Python counts it in
+            'rate_limit': list(permission.rate_limit) if permission.rate_limit else None,
+            # the key's own limits (ADR 0011), applied as limits.timeout() and limits.rows() apply them; an int
+            # query_timeout stays one, as min() keeps it
+            'query_timeout': permission.query_timeout, 'max_rows': permission.max_rows,
             'query': {'name': query_name, 'version': number}, 'connection': {'name': connection_name,
             'dialect': dialect}, 'statement': sent, 'search_path': prepared['search_path'], 'mask': mask,
             'expires_in': expires_in,

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/experimental.py

@@ -12,7 +12,8 @@ added - when it meets every one of GRADUATION. Alerts, remote files through Duck
 Console sign-in through SSO in 0.30 (ADR 0017), with the Helm chart; the audit log streamed to a SIEM in 0.32, once
 tested against real receivers (ADR 0019); live events, and secrets from files and Vault, in 0.34 (ADR 0021) - AWS's
 stay, until tested against AWS. The connection types have their own terms (databases.GRADUATION): MongoDB met them
-in 0.37, with streaming exports (ADR 0022).
+in 0.37, with streaming exports (ADR 0022). The ClickHouse run store graduated in 0.49 (ADR 0029), once upgrades from
+each release that had it were tested.
 """
 from typing import Any
 
@@ -75,13 +76,6 @@ FEATURES: dict[str, dict[str, Any]] = {
         'settings': ('QUERYAPIGATE_DATAPLANE_SECRET',),
         'docs': ('documentation/DEPLOYMENT.md', 'A Rust data plane in front of /q/'),
     },
-    'run_store': {
-        'name': 'A ClickHouse run store for history, the event log and usage',
-        'why': 'a prototype (ADR 0029, decided go): its tables, its event ids and how it is switched on may change '
-               'before it graduates',
-        'settings': ('QUERYAPIGATE_RUN_STORE_URL',),
-        'docs': ('documentation/DEPLOYMENT.md', 'A ClickHouse run store (prototype)'),
-    },
 }
 
 DB_TYPES = frozenset(t for f in FEATURES.values() for t in f.get('db_types', ()))

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/governance.py

@@ -13,7 +13,7 @@ process - `queryapigate serve`, `queryapigate mcp`, `queryapigate events` - shar
 import ipaddress
 from dataclasses import dataclass
 
-from . import admins, alerts, apikeys, config, jwtauth, metrics
+from . import admins, alerts, apikeys, config, jwtauth, metrics, ratelimit
 
 OPEN_ACCESS_REMOTE = ('This server has no API key set, so it answers only local clients. Set QUERYAPIGATE_API_KEY '
                       'to allow access from other hosts.')
@@ -98,13 +98,26 @@ def check_key_limit(flask_app, permission):
         return None
     count, period = permission.rate_limit
     allowed, remaining, retry_after = flask_app.extensions['queryapigate_key_limiter'].hit(
-        permission.name, count, period)
+        ratelimit.budget_name(permission), count, period)
     if not allowed:
         metrics.inc_rate_limit_rejection()
         alerts.note_rate_limited('key', (getattr(permission, 'workspace', 'default'), permission.name))
     return Verdict(allowed, count, remaining, retry_after)
 
 
+def note_refused(scope, client_ip, workspace, key, method, elapsed):
+    """429s the data plane answered itself (ADR 0032), one duration each: counted as check_client_limit() and
+    check_key_limit() count their own - the rejections and the alerts - and in the request counters, as the calls they
+    were. `scope` is 'client' (by `client_ip`, before the caller is known: no key label) or 'key'."""
+    if scope == 'client':
+        who, label = client_ip, '-'
+    else:
+        who, label = (workspace or 'default', key), key or '-'
+    metrics.inc_rate_limit_rejection(len(elapsed))
+    alerts.note_rate_limited(scope, who, len(elapsed))
+    metrics.observe_requests(method, 'api.run_named_query', '429', elapsed, label)
+
+
 def observe(method, endpoint, status, elapsed, key):
     """One finished call in /metrics' request counters and latency histograms. REST passes the HTTP method and its
     route's endpoint; MCP passes method 'MCP' and an 'mcp.*' endpoint, so the two can be told apart."""

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/limits.py

@@ -229,10 +229,11 @@ def acquire(query_timeout=None):
     lease = (query_timeout or LEASE_WITHOUT_TIMEOUT) + LEASE_MARGIN
     token = secrets.token_hex(8)
     store = counter()
-    if not store.acquire(permission.name, maximum, token, lease):
+    name = ratelimit.budget_name(permission)
+    if not store.acquire(name, maximum, token, lease):
         raise ApiError(f'This caller already has {maximum} queries running, its max_concurrent - retry when one '
                        'finishes', 429, code='too_many_concurrent', retry_after=1, max_concurrent=maximum)
-    return Slot(permission.name, token, lease, store)
+    return Slot(name, token, lease, store)
 
 
 def effective(grants):

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/masking.py

@@ -404,7 +404,10 @@ def _store_hash_key():
 def _hash(value, key):
     if value is None:
         return None
-    text = value.decode('utf-8', 'replace') if isinstance(value, (bytes, bytearray)) else str(value)
+    # Binary values as their text, as JSON shows them - a memoryview too, which psycopg2 hands over for bytea: str() of
+    # one is its address, not its value
+    text = bytes(value).decode('utf-8', 'replace') if isinstance(value, (bytes, bytearray, memoryview)) \
+        else str(value)
     return hmac.new(key, text.encode('utf-8'), hashlib.sha256).hexdigest()[:16]
 
 

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/mcp_server.py

@@ -344,7 +344,9 @@ def call_tool_for(flask_app, permission, name, arguments):
             structured = g.agent_write_result
             return {'content': [{'type': 'text', 'text': json.dumps(structured, default=str)}],
                     'structuredContent': structured}
-        structured = {'rows': response.get_json(), 'truncated': response.headers.get('X-Has-More') == 'true'}
+        # REST answers no rows with {"message": "No results returned"}; a tool's rows are a list (its outputSchema)
+        rows = response.get_json() if response.headers.get('X-Row-Count') != '0' else []
+        structured = {'rows': rows, 'truncated': response.headers.get('X-Has-More') == 'true'}
         return _rows_result(structured)
 
 

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/metrics.py

@@ -180,10 +180,10 @@ def dec_active_query():
         _active_queries -= 1
 
 
-def inc_rate_limit_rejection():
+def inc_rate_limit_rejection(count=1):
     global _rate_limit_rejections
     with _lock:
-        _rate_limit_rejections += 1
+        _rate_limit_rejections += count
 
 
 def inc_rate_limit_fallback():

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/ratelimit.py

@@ -120,6 +120,15 @@ end
 return {allowed, math.floor(tokens), retry}
 """
 _PREFIX = 'qag:ratelimit:'
+
+
+def budget_name(permission):
+    """What a caller's own budgets - its rate limit's bucket, its max_concurrent slots (limits.py) - are counted
+    under: `<workspace>~<name>`, as quotas count theirs. A name is unique only within its workspace, so two workspaces'
+    keys of one name are two callers; no workspace name has a `~`."""
+    return f"{getattr(permission, 'workspace', None) or 'default'}~{permission.name}"
+
+
 _DEGRADED_FOR = 600  # seconds a Redis failure keeps the "limits are per instance right now" alert up
 _degraded_at = None
 _last_warned = 0.0

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/runstore.py

@@ -1,4 +1,4 @@
-"""The run store (ADR 0029, experimental): run history, the event log and usage rollups in ClickHouse.
+"""The run store (ADR 0029): run history, the event log and usage rollups in ClickHouse.
 
 With QUERYAPIGATE_RUN_STORE_URL set, history.py's writer thread sends its batches here instead of to the metadata
 store, and everything that reads runs or events - GET /api/v1/history, the Console's runs per version, usage

{queryapigate-0.47.0 → queryapigate-0.49.0}/queryapigate/sqltools.py

@@ -270,7 +270,11 @@ def paginate(sql, limit, offset, params=None, dialect=None):
 # Parameters
 # --------------------------------------------------------------------------------------
 
-def _check_value(name, value):
+def _check_value(name, value, dialect=None):
+    if isinstance(value, str) and dialect == 'postgres' and '\x00' in value:
+        # psycopg2 refuses it ("A string literal cannot contain NUL") - the caller's value, not the query, is wrong
+        raise ApiError(f"Parameter '{name}' contains a NUL character, which PostgreSQL text can't hold",
+                       code='param_invalid')
     if value is None or isinstance(value, (bool, str)):
         return
     if isinstance(value, (int, float)) and math.isfinite(value):
@@ -344,7 +348,7 @@ def bind_parameters(sql, params, style, dialect=None):
     if missing:
         raise ApiError(f"No value provided for parameter(s): {', '.join(missing)}", code='param_required')
     for name in set(names):
-        _check_value(name, params[name])
+        _check_value(name, params[name], dialect)
 
     escape = (lambda text: text.replace('%', '%%')) if style in ('format', 'pyformat') else (lambda text: text)
     pieces, position = [], 0

{queryapigate-0.47.0 → queryapigate-0.49.0/queryapigate.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.47.0
+Version: 0.49.0
 Summary: Turn SQL into governed REST APIs over MySQL, PostgreSQL, ClickHouse, SQLite, DuckDB, H2, MongoDB, and Parquet/CSV/JSON files - JSON, CSV, Parquet or Excel out, with scoped keys, an admin Console and MCP for AI agents.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
 License-Expression: Apache-2.0

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_cli.py

@@ -199,5 +199,18 @@ class LegacySettingsTests(unittest.TestCase):
             self.assertEqual(config.api_key(), 'secret')
 
 
+class InitTests(unittest.TestCase):
+    def test_init_makes_a_home_that_doesn_t_exist_yet(self):
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        home = os.path.join(tmp.name, 'new', 'home')
+        out = io.StringIO()
+        with mock.patch.dict(os.environ, {'QUERYAPIGATE_HOME': home}), redirect_stdout(out):
+            self.assertEqual(cli.main(['init']), 0)
+            self.assertTrue(store.read_connections())  # the templates, in the store it made
+        self.assertTrue(os.path.isdir(home))
+        self.assertIn('Created', out.getvalue())
+
+
 if __name__ == '__main__':
     unittest.main()

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_dataplane.py

@@ -115,9 +115,38 @@ class WhoGetsAPlanTests(PlanTestCase):
                                                          **PAIRED})
         self.assertIsNone(res.headers.get(dataplane.PLAN_HEADER))
 
-    def test_never_for_a_key_with_a_rate_limit(self):
+    def test_never_for_a_key_with_a_rate_limit_without_redis(self):
         self.assertIsNone(self.call('/q/by_id?id=1', self.limited)[1])
 
+    def test_with_redis_a_rate_limited_key_gets_one_that_carries_its_limit(self):
+        # Its bucket is in Redis, where the data plane counts it too (ADR 0032): the plan says what the limit is
+        with mock.patch.dict(os.environ, {'QUERYAPIGATE_REDIS_URL': 'redis://127.0.0.1:1/0'}):
+            plan = self.call('/q/by_id?id=1', self.limited)[1]
+            self.assertEqual(plan['rate_limit'], [100, 60])
+            self.assertIsNone(self.call('/q/by_id?id=1', self.plain)[1]['rate_limit'])
+
+    def test_never_for_the_limits_that_keep_their_own_state_with_redis_or_without(self):
+        with mock.patch.dict(os.environ, {'QUERYAPIGATE_REDIS_URL': 'redis://127.0.0.1:1/0'}):
+            for name, grants in (('quota', {'quota': {'calls': 100, 'per': 'day'}}), ('slots', {'max_concurrent': 2})):
+                with self.subTest(name):
+                    key = apikeys.create_key(name, connections=['pg'], **grants)
+                    self.assertIsNone(self.call('/q/by_id?id=1', key)[1])
+
+    def test_a_key_s_own_time_and_row_limits_travel_in_its_plan(self):
+        # They keep no state: the data plane applies each as limits.py does. A whole-number timeout stays an int,
+        # as Python's min() keeps it (its 504 says 5, not 5.0)
+        for name, grants, expected in (('timeout', {'query_timeout': 5}, (5, None)),
+                                       ('fraction', {'query_timeout': 0.5}, (0.5, None)),
+                                       ('rows', {'max_rows': 10}, (None, 10)),
+                                       ('both', {'query_timeout': 2, 'max_rows': 3}, (2, 3))):
+            with self.subTest(name):
+                key = apikeys.create_key(name, connections=['pg'], **grants)
+                plan = self.call('/q/by_id?id=1', key)[1]
+                self.assertEqual((plan['query_timeout'], plan['max_rows']), expected)
+                self.assertIs(type(plan['query_timeout']), type(expected[0]))
+        plain = self.call('/q/by_id?id=1', self.plain)[1]
+        self.assertEqual((plain['query_timeout'], plain['max_rows']), (None, None))
+
     def test_never_on_a_connection_the_prototype_does_not_serve(self):
         self.assertIsNone(self.call('/q/lite_by_id?id=1', self.plain)[1])
 
@@ -179,11 +208,11 @@ class WhoGetsAPlanTests(PlanTestCase):
             dockerfile = f.read()
         rust = re.search(r'^FROM --platform=\$BUILDPLATFORM rust:([\d.]+)-slim-(\w+)@sha256:\w+ AS dataplane$',
                          dockerfile, re.M)
-        python = re.search(r'^FROM python:[\d.]+-slim@sha256:\w+$', dockerfile, re.M)
+        image = re.search(r'^FROM debian:(\w+)-slim@sha256:\w+$', dockerfile, re.M)  # Debian's Python (ADR 0031)
         self.assertIsNotNone(rust, 'the data plane stage: rust:<channel>-slim-<debian>@sha256:..., by digest')
-        self.assertIsNotNone(python)
+        self.assertIsNotNone(image, 'the image: debian:<release>-slim@sha256:..., by digest')
         self.assertEqual(rust.group(1), channel)
-        self.assertEqual(rust.group(2), 'trixie', 'the Debian release python:3.12-slim is on')
+        self.assertEqual(rust.group(2), image.group(1), 'the data plane is built on the Debian release it runs on')
         self.assertNotIn('COPY dataplane/ ', dockerfile)
         self.assertIn('COPY --from=dataplane /queryapigate-dataplane /usr/local/bin/queryapigate-dataplane',
                       dockerfile)
@@ -398,6 +427,57 @@ class ClientAddressTests(unittest.TestCase):
         self.assertEqual(self.get('/catalog', peer='192.0.2.1', **{'X-API-Key': key}).status_code, 401)
 
 
+class CountedByTheDataPlaneTests(PlanTestCase):
+    """A call the data plane forwards after counting it (ADR 0032, section 4): X-QAG-Rate-Counted names the buckets
+    and what they said, and Python counts them no more - but only beside the data plane's secret."""
+
+    def get(self, key, counted, secret=SECRET):
+        headers = {'X-API-Key': key, dataplane.COUNTED_HEADER: counted}
+        if secret:
+            headers.update({dataplane.SECRET_HEADER: secret, **PAIRED})
+        return self.client.get('/q/by_id?id=1', headers=headers)
+
+    def test_the_header_as_the_data_plane_writes_it(self):
+        self.assertEqual(dataplane.counted('client=5,3; key=100,42'), {'client': (5, 3), 'key': (100, 42)})
+        self.assertEqual(dataplane.counted('key=100,0'), {'key': (100, 0)})
+        for odd in ('', 'key=100', 'key=-1,2', 'key=1,2; key=1,2', 'other=1,2', 'key=١,2', 'key=1,2;', None):
+            with self.subTest(odd):
+                self.assertEqual(dataplane.counted(odd), {})
+
+    def test_a_key_s_bucket_counted_by_the_data_plane_is_not_counted_again(self):
+        res = self.get(self.limited, 'key=100,42')
+        self.assertEqual(res.status_code, 200)
+        self.assertEqual((res.headers['X-RateLimit-Key-Limit'], res.headers['X-RateLimit-Key-Remaining']),
+                         ('100', '42'))
+        res = self.get(self.limited, None, secret=None)
+        self.assertEqual(res.headers['X-RateLimit-Key-Remaining'], '99')  # Python's own bucket: one call, this one
+
+    def test_nor_the_client_s(self):
+        with mock.patch.dict(os.environ, {'QUERYAPIGATE_RATE_LIMIT': '5/minute'}):
+            res = self.get(self.limited, 'client=5,0; key=100,7')
+            self.assertEqual(res.status_code, 200)
+            names = ('Limit', 'Remaining', 'Key-Limit', 'Key-Remaining')
+            self.assertEqual([res.headers[f'X-RateLimit-{name}'] for name in names], ['5', '0', '100', '7'])
+            # Only the client's counted there (Redis failed for the key's): Python counts the key's
+            res = self.get(self.limited, 'client=5,4')
+            self.assertEqual((res.headers['X-RateLimit-Remaining'], res.headers['X-RateLimit-Key-Remaining']),
+                             ('4', '99'))
+
+    def test_without_the_secret_python_counts_as_ever(self):
+        remaining = [self.get(self.limited, 'key=100,42', secret=secret).headers['X-RateLimit-Key-Remaining']
+                     for secret in (None, 'wrong')]
+        self.assertEqual(remaining, ['99', '98'])
+
+    def test_never_from_a_data_plane_of_another_release(self):
+        res = self.client.get('/q/by_id?id=1', headers={'X-API-Key': self.limited, dataplane.SECRET_HEADER: SECRET,
+                                                         dataplane.COUNTED_HEADER: 'key=100,50'})
+        self.assertEqual(res.headers['X-RateLimit-Key-Remaining'], '99')
+
+    def test_a_key_without_a_limit_gets_no_limit_headers_from_it(self):
+        res = self.get(self.plain, 'key=100,42')
+        self.assertNotIn('X-RateLimit-Key-Limit', res.headers)
+
+
 class RunReportTests(PlanTestCase):
     """The data plane reports the runs it served (POST /internal/dataplane/runs): each recorded as run_saved() records
     one, and counted in /metrics - and nothing without its secret."""
@@ -410,6 +490,11 @@ class RunReportTests(PlanTestCase):
            'dialect': 'postgres', 'method': 'GET', 'http_status': 200, 'seconds': 0.002, 'query_seconds': 0.001,
            'serialization_seconds': 0.0001}
 
+    def setUp(self):
+        super().setUp()
+        from queryapigate import alerts
+        self.addCleanup(alerts._refusals.clear)  # the refusals reported here are the process's, for its alerts
+
     def report(self, secret=SECRET):
         headers = {dataplane.SECRET_HEADER: secret} if secret else {}
         return self.client.post('/internal/dataplane/runs', json={'runs': [self.RUN]}, headers=headers)
@@ -453,6 +538,46 @@ class RunReportTests(PlanTestCase):
         self.assertEqual(metrics.history_counts().get('dropped', 0) - before, 7)
         self.assertEqual(self.history(), [self.ENTRY])
 
+    def test_the_429s_it_answered_are_counted_as_python_s_own(self):
+        # ADR 0032, section 5: in the rejections, the alerts and the request counters - and none is a run
+        from queryapigate import alerts
+
+        def counts():
+            text = self.client.get('/metrics', headers=ADMIN).get_data(as_text=True)
+            found = []
+            for name in ('queryapigate_rate_limit_rejections_total',
+                         'queryapigate_requests_total{method="GET",endpoint="api.run_named_query",status="429",'
+                         'key="limited"}',
+                         'queryapigate_requests_total{method="POST",endpoint="api.run_named_query",status="429",'
+                         'key="-"}'):
+                match = re.search(re.escape(name) + r' (\d+)', text)
+                found.append(int(match.group(1)) if match else 0)
+            return found
+
+        def refusals(who):
+            with alerts._lock:
+                return len(alerts._refusals.get(who, ()))
+        before, key, client = counts(), refusals(('key', ('default', 'limited'))), refusals(('client', '203.0.113.9'))
+        res = self.client.post('/internal/dataplane/runs', headers={dataplane.SECRET_HEADER: SECRET}, json={
+            'runs': [], 'dropped': 0, 'rate_limited': [
+                {'scope': 'key', 'workspace': 'default', 'key': 'limited', 'method': 'GET', 'seconds': [0.001, 0.002]},
+                {'scope': 'client', 'client': '203.0.113.9', 'method': 'POST', 'seconds': [0.001]}]})
+        self.assertEqual(res.status_code, 204)
+        self.assertEqual([after - was for after, was in zip(counts(), before, strict=True)], [3, 2, 1])
+        self.assertEqual(refusals(('key', ('default', 'limited'))) - key, 2)
+        self.assertEqual(refusals(('client', '203.0.113.9')) - client, 1)
+        self.assertEqual(self.history(), [])
+
+    def test_a_key_that_keeps_getting_them_raises_its_alert(self):
+        from queryapigate import alerts
+        seconds = [0.001] * alerts.RATE_LIMITED_PER_HOUR
+        self.client.post('/internal/dataplane/runs', headers={dataplane.SECRET_HEADER: SECRET}, json={
+            'runs': [], 'rate_limited': [{'scope': 'key', 'workspace': 'default', 'key': 'limited', 'method': 'GET',
+                                          'seconds': seconds}]})
+        raised = [a for a in self.client.get('/api/v1/alerts', headers=ADMIN).get_json()['items']
+                  if a['kind'] == 'key_rate_limited']
+        self.assertEqual([a['id'] for a in raised], ['key_rate_limited:limited'])
+
     def test_its_event_is_the_one_python_writes(self):
         from queryapigate import events
         self.assertEqual(self.report().status_code, 204)

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_db.py

@@ -15,7 +15,7 @@ from unittest import mock
 
 from queryapigate import config, db, events, history
 from queryapigate.store import now as store_now
-from tests import TEST_DATABASE_URL
+from tests import TEST_DATABASE_URL, TEST_RUN_STORE_URL
 from tests.helpers import save_query, write_connections
 
 sqlite_only = unittest.skipIf(TEST_DATABASE_URL, 'inspects the SQLite file itself')
@@ -316,6 +316,7 @@ class PostgresDbTests(unittest.TestCase):
         self.assertIs(db.connection(), parent)
         self.assertEqual(parent.execute('SELECT 1').fetchone()[0], 1)  # the parent's is still usable
 
+    @unittest.skipIf(TEST_RUN_STORE_URL, 'a run store keeps history by time, not by count')
     def test_concurrent_history_writes_are_all_recorded_then_trimmed(self):
         """Runs recorded from many threads at once (queued, then batched by history.py, whose writes skip the
         store-wide lock on Postgres) must all land, and the per-version cap must still hold afterwards."""
@@ -456,6 +457,7 @@ class MigrateToPostgresTests(unittest.TestCase):
             db.close()
         return snapshot
 
+    @unittest.skipIf(TEST_RUN_STORE_URL, "the SQLite store's runs are in the run store, which the copy leaves there")
     def test_copies_everything_and_the_api_sees_the_same_store(self):
         before = os.path.getmtime(self.sqlite_path), os.path.getsize(self.sqlite_path)
         copied = db.migrate_sqlite_to_postgres(self.sqlite_path)
@@ -467,6 +469,7 @@ class MigrateToPostgresTests(unittest.TestCase):
         self.assertEqual((os.path.getmtime(self.sqlite_path), os.path.getsize(self.sqlite_path)), before)
         self.assertEqual(copied['events'], 3)
 
+    @unittest.skipIf(TEST_RUN_STORE_URL, "the SQLite store's events are in the run store, which the copy leaves there")
     def test_event_ids_and_their_sequence_come_across(self):
         """An id handed out and since swept is not handed out again: the sequence is SQLite's, not MAX(id)."""
         source = sqlite3.connect(self.sqlite_path)

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_events_server.py

@@ -247,6 +247,7 @@ class DeliveryTests(EventServerTestCase):
         self.assertTrue(stream.nothing_more())
 
     @unittest.skipUnless(TEST_DATABASE_URL, 'set QUERYAPIGATE_TEST_DATABASE_URL to run')
+    @unittest.skipIf(TEST_RUN_STORE_URL, "the metadata store's NOTIFY: with a run store, the events server tails it")
     def test_postgres_notify_delivers_without_waiting_for_the_poll(self):
         self.start_server(poll_interval=30)  # only a NOTIFY can wake this one in time
         stream = self.open('admin')

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_experimental.py

@@ -80,7 +80,8 @@ class MarkedEverywhereTests(unittest.TestCase):
                                      ('documentation/MCP.md', 'Sign-in for AI clients (OAuth)', '0.30'),
                                      ('documentation/MCP.md', 'Write tools: agents that write, approved by a person',
                                       '0.30'),
-                                     ('documentation/DEPLOYMENT.md', 'Kubernetes (Helm)', '0.30')):
+                                     ('documentation/DEPLOYMENT.md', 'Kubernetes (Helm)', '0.30'),
+                                     ('documentation/DEPLOYMENT.md', 'A ClickHouse run store', '0.49')):
             with self.subTest(heading=heading):
                 text = read(path)
                 match = re.search(rf'^#+ {re.escape(heading)}\n+(.+)', text, re.M)

{queryapigate-0.47.0 → queryapigate-0.49.0}/tests/test_history.py

@@ -239,6 +239,7 @@ class RetentionTests(HistoryTestCase):
             self.assertEqual(self.stored(), 2)
 
     @unittest.skipUnless(TEST_DATABASE_URL, 'several instances only share a PostgreSQL store')
+    @unittest.skipIf(TEST_RUN_STORE_URL, "a run store's TTL, not a sweep, keeps its retention")
     def test_while_another_instance_sweeps_this_one_skips(self):
         with mock.patch.dict(os.environ, {'QUERYAPIGATE_HISTORY_RETENTION_DAYS': '7'}):
             now = datetime(2026, 3, 1, 12, 0, 0)