pgbulkhead 0.1.0__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.
- pgbulkhead/__init__.py +71 -0
- pgbulkhead/admission.py +235 -0
- pgbulkhead/context.py +114 -0
- pgbulkhead/database.py +144 -0
- pgbulkhead/model.py +154 -0
- pgbulkhead/policy.py +110 -0
- pgbulkhead/pool.py +188 -0
- pgbulkhead/py.typed +0 -0
- pgbulkhead/session.py +159 -0
- pgbulkhead/testing.py +24 -0
- pgbulkhead-0.1.0.dist-info/METADATA +285 -0
- pgbulkhead-0.1.0.dist-info/RECORD +15 -0
- pgbulkhead-0.1.0.dist-info/WHEEL +4 -0
- pgbulkhead-0.1.0.dist-info/licenses/LICENSE +201 -0
- pgbulkhead-0.1.0.dist-info/licenses/NOTICE +4 -0
pgbulkhead/model.py
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
"""The tenancy model: which columns are the walls, and which settings carry them.
|
|
2
|
+
|
|
3
|
+
One :class:`TenancyModel` describes how a table set is isolated:
|
|
4
|
+
|
|
5
|
+
* ``tenant_column`` is the **hard wall**. Every policy requires it to equal the session's
|
|
6
|
+
tenant, and nothing bypasses it.
|
|
7
|
+
* ``workspace_column`` is an optional **soft wall** inside a tenant. With it, reads span the
|
|
8
|
+
session's readable workspaces (the active one plus any granted), and every write is bound
|
|
9
|
+
to the active workspace. Without it (``None``) the model is single-key: read and write are
|
|
10
|
+
both scoped on the tenant alone.
|
|
11
|
+
* ``namespace`` is the prefix of the Postgres custom settings (GUCs) a session binds and the
|
|
12
|
+
policies read: ``<namespace>.<tenant_column>`` and so on. Each setting can be named
|
|
13
|
+
explicitly instead.
|
|
14
|
+
* ``bypass`` lets a privileged session cross the **soft** wall, never the hard one. It is off
|
|
15
|
+
unless you set it; see :class:`GucBypass` and :class:`RoleBypass` for what each costs.
|
|
16
|
+
|
|
17
|
+
Two models that use different settings cannot be confused: each policy reads only its own
|
|
18
|
+
settings, and ``current_setting(name, true)`` is NULL for one that is not bound, so a session
|
|
19
|
+
bound for one model matches no row of a table under another. Mixing models fails closed.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import re
|
|
25
|
+
from dataclasses import dataclass, field
|
|
26
|
+
|
|
27
|
+
__all__ = ["GucBypass", "RoleBypass", "TenancyModel"]
|
|
28
|
+
|
|
29
|
+
_IDENTIFIER = re.compile(r"[a-z_][a-z0-9_]*")
|
|
30
|
+
_SETTING = re.compile(r"[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*")
|
|
31
|
+
#: Postgres truncates identifiers past 63 bytes, so two long names could collide silently.
|
|
32
|
+
_MAX_IDENTIFIER = 63
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def check_identifier(value: str, what: str) -> str:
|
|
36
|
+
"""``value`` if it is a plain lower-case SQL identifier, else :class:`ValueError`.
|
|
37
|
+
|
|
38
|
+
Names are interpolated into DDL, so anything else (quoting, a schema prefix, mixed case
|
|
39
|
+
that Postgres would fold) is refused rather than escaped.
|
|
40
|
+
"""
|
|
41
|
+
if not _IDENTIFIER.fullmatch(value) or len(value) > _MAX_IDENTIFIER:
|
|
42
|
+
raise ValueError(f"{what} must be a lower-case SQL identifier of at most 63 bytes")
|
|
43
|
+
return value
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _check_setting(value: str, what: str) -> str:
|
|
47
|
+
if not _SETTING.fullmatch(value) or len(value) > _MAX_IDENTIFIER:
|
|
48
|
+
raise ValueError(f"{what} must be a custom setting name like 'myapp.tenant_id'")
|
|
49
|
+
return value
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass(frozen=True, slots=True)
|
|
53
|
+
class GucBypass:
|
|
54
|
+
"""Cross the soft wall when a session sets ``setting`` to ``value``.
|
|
55
|
+
|
|
56
|
+
The policies gain ``OR current_setting(setting, true) = value`` on the workspace predicate
|
|
57
|
+
only; the tenant predicate is never gated by it. A session opts in with
|
|
58
|
+
:func:`~pgbulkhead.system_session`.
|
|
59
|
+
|
|
60
|
+
**What it costs.** The app role can set this setting, so any SQL the app role runs can
|
|
61
|
+
take the bypass. That is the same exposure the tenant setting already has (see the threat
|
|
62
|
+
model in the README): it holds against query bugs and against identity taken from
|
|
63
|
+
untrusted input, not against arbitrary SQL in the app role. Use :class:`RoleBypass` when
|
|
64
|
+
the privileged path should not be reachable from the app role at all.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
setting: str | None = None
|
|
68
|
+
value: str = "system"
|
|
69
|
+
|
|
70
|
+
def __post_init__(self) -> None:
|
|
71
|
+
if self.setting is not None:
|
|
72
|
+
_check_setting(self.setting, "GucBypass.setting")
|
|
73
|
+
check_identifier(self.value, "GucBypass.value")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@dataclass(frozen=True, slots=True)
|
|
77
|
+
class RoleBypass:
|
|
78
|
+
"""Cross the soft wall when the session's database role is a member of ``role``.
|
|
79
|
+
|
|
80
|
+
The policies gain ``OR pg_has_role(current_user, role, 'MEMBER')`` on the workspace
|
|
81
|
+
predicate only. A privileged job connects with its own login role (a member of ``role``)
|
|
82
|
+
through its own engine; no setting grants the bypass, so SQL running as the app role cannot
|
|
83
|
+
take it. **Never grant ``role`` to the app role**, or the app role is a member too.
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
role: str
|
|
87
|
+
|
|
88
|
+
def __post_init__(self) -> None:
|
|
89
|
+
check_identifier(self.role, "RoleBypass.role")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@dataclass(frozen=True, slots=True)
|
|
93
|
+
class TenancyModel:
|
|
94
|
+
"""How a set of tables is isolated. See the module docstring."""
|
|
95
|
+
|
|
96
|
+
tenant_column: str = "tenant_id"
|
|
97
|
+
workspace_column: str | None = "workspace_id"
|
|
98
|
+
namespace: str = "pgbulkhead"
|
|
99
|
+
tenant_setting: str | None = None
|
|
100
|
+
workspace_setting: str | None = None
|
|
101
|
+
readable_setting: str | None = None
|
|
102
|
+
#: A setting the session binds the context's scopes to, for policies of your own that read
|
|
103
|
+
#: them. ``None`` binds nothing.
|
|
104
|
+
scopes_setting: str | None = None
|
|
105
|
+
bypass: GucBypass | RoleBypass | None = None
|
|
106
|
+
#: Bind the active workspace as readable whether or not the context lists it. ``False``
|
|
107
|
+
#: binds ``allowed_workspaces`` exactly as given, for a context source that always lists
|
|
108
|
+
#: the active workspace itself.
|
|
109
|
+
active_is_readable: bool = True
|
|
110
|
+
#: Also drop the other shape's policy names when rendering, so switching a table between
|
|
111
|
+
#: the single-key and the per-command shape leaves no stale policy behind. Permissive
|
|
112
|
+
#: policies combine with OR, so a stale one would widen access.
|
|
113
|
+
drop_other_shape: bool = True
|
|
114
|
+
_settings: dict[str, str] = field(init=False, repr=False, compare=False)
|
|
115
|
+
|
|
116
|
+
def __post_init__(self) -> None:
|
|
117
|
+
check_identifier(self.tenant_column, "tenant_column")
|
|
118
|
+
if self.workspace_column is not None:
|
|
119
|
+
check_identifier(self.workspace_column, "workspace_column")
|
|
120
|
+
if self.workspace_column == self.tenant_column:
|
|
121
|
+
raise ValueError("workspace_column must differ from tenant_column")
|
|
122
|
+
check_identifier(self.namespace, "namespace")
|
|
123
|
+
if self.bypass is not None and self.workspace_column is None:
|
|
124
|
+
raise ValueError(
|
|
125
|
+
"a bypass crosses the workspace wall only; a single-key model has none, and "
|
|
126
|
+
"nothing may cross the tenant wall"
|
|
127
|
+
)
|
|
128
|
+
ns = self.namespace
|
|
129
|
+
settings = {"tenant": self.tenant_setting or f"{ns}.{self.tenant_column}"}
|
|
130
|
+
if self.workspace_column is not None:
|
|
131
|
+
settings["workspace"] = self.workspace_setting or f"{ns}.{self.workspace_column}"
|
|
132
|
+
settings["readable"] = self.readable_setting or f"{ns}.allowed_workspaces"
|
|
133
|
+
elif self.workspace_setting or self.readable_setting:
|
|
134
|
+
raise ValueError("a single-key model binds no workspace or readable setting")
|
|
135
|
+
if self.scopes_setting is not None:
|
|
136
|
+
settings["scopes"] = self.scopes_setting
|
|
137
|
+
if isinstance(self.bypass, GucBypass):
|
|
138
|
+
settings["bypass"] = self.bypass.setting or f"{ns}.role"
|
|
139
|
+
for name, value in settings.items():
|
|
140
|
+
_check_setting(value, f"{name} setting")
|
|
141
|
+
# One setting carrying two fields would let the later binding overwrite the earlier,
|
|
142
|
+
# so a policy reading the tenant setting could see the workspace identity.
|
|
143
|
+
if len(set(settings.values())) != len(settings):
|
|
144
|
+
raise ValueError("each resolved setting name must be distinct")
|
|
145
|
+
object.__setattr__(self, "_settings", settings)
|
|
146
|
+
|
|
147
|
+
@property
|
|
148
|
+
def has_workspace(self) -> bool:
|
|
149
|
+
return self.workspace_column is not None
|
|
150
|
+
|
|
151
|
+
def setting(self, name: str) -> str:
|
|
152
|
+
"""The resolved setting name for ``tenant``, ``workspace``, ``readable``, ``scopes``
|
|
153
|
+
or ``bypass``. Raises ``KeyError`` for one the model does not use."""
|
|
154
|
+
return self._settings[name]
|
pgbulkhead/policy.py
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
"""Row-level security policies for a :class:`~pgbulkhead.TenancyModel`, rendered as DDL.
|
|
2
|
+
|
|
3
|
+
Apply them in a migration, once per table. Every rendering enables **and forces** row-level
|
|
4
|
+
security, so the table owner is subject to the policy too, and every predicate reads its
|
|
5
|
+
setting with ``current_setting(name, true)``, which is NULL when the session bound nothing: an
|
|
6
|
+
unscoped session sees no row and can write none. Default deny.
|
|
7
|
+
|
|
8
|
+
**Per-command shape** (a model with a workspace column). Four policies, because one
|
|
9
|
+
``FOR ALL`` policy cannot hold the read/write asymmetry: Postgres applies ``WITH CHECK`` only
|
|
10
|
+
to the new row of an INSERT or UPDATE and never to DELETE, while ``USING`` picks the existing
|
|
11
|
+
rows an UPDATE or DELETE may touch. With a single policy the read predicate would govern those,
|
|
12
|
+
and a read grant on another workspace would let a session delete or relabel its rows.
|
|
13
|
+
|
|
14
|
+
* ``SELECT``: tenant matches, and the workspace is one the session may read.
|
|
15
|
+
* ``INSERT`` / ``UPDATE`` / ``DELETE``: tenant matches, and the workspace is the session's
|
|
16
|
+
active one, on the row selected (``USING``) and on the row written (``WITH CHECK``).
|
|
17
|
+
|
|
18
|
+
**Single-key shape** (no workspace column). One policy scoping read and write on the tenant.
|
|
19
|
+
|
|
20
|
+
The rendering is idempotent: it drops its own policy names first (and, with
|
|
21
|
+
``drop_other_shape``, the other shape's), so it can be re-applied to change a table's policy.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
from .model import GucBypass, RoleBypass, TenancyModel, check_identifier
|
|
27
|
+
|
|
28
|
+
__all__ = ["policy_sql", "policy_statements"]
|
|
29
|
+
|
|
30
|
+
_COMMANDS = ("select", "insert", "update", "delete")
|
|
31
|
+
#: The longest suffix a policy name gets, so the table name leaves room for it.
|
|
32
|
+
_LONGEST_SUFFIX = len("_isolation")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _bypass_predicate(model: TenancyModel) -> str | None:
|
|
36
|
+
bypass = model.bypass
|
|
37
|
+
if isinstance(bypass, GucBypass):
|
|
38
|
+
return f"current_setting('{model.setting('bypass')}', true) = '{bypass.value}'"
|
|
39
|
+
if isinstance(bypass, RoleBypass):
|
|
40
|
+
return f"pg_has_role(current_user, '{bypass.role}', 'MEMBER')"
|
|
41
|
+
return None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def policy_sql(model: TenancyModel, table: str) -> str:
|
|
45
|
+
"""The policy DDL for ``table`` under ``model``, as one string of ``;``-separated
|
|
46
|
+
statements. Use :func:`policy_statements` for a driver that runs one statement at a time.
|
|
47
|
+
"""
|
|
48
|
+
check_identifier(table, "table")
|
|
49
|
+
if len(table) + _LONGEST_SUFFIX > 63:
|
|
50
|
+
raise ValueError("table name is too long to suffix its policy names within 63 bytes")
|
|
51
|
+
tenant = f"{model.tenant_column} = current_setting('{model.setting('tenant')}', true)"
|
|
52
|
+
head = [
|
|
53
|
+
f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY;",
|
|
54
|
+
f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY;",
|
|
55
|
+
]
|
|
56
|
+
if model.workspace_column is None:
|
|
57
|
+
drops = [f"DROP POLICY IF EXISTS {table}_isolation ON {table};"]
|
|
58
|
+
if model.drop_other_shape:
|
|
59
|
+
drops += [f"DROP POLICY IF EXISTS {table}_{cmd} ON {table};" for cmd in _COMMANDS]
|
|
60
|
+
return "\n".join(
|
|
61
|
+
[
|
|
62
|
+
*head,
|
|
63
|
+
*drops,
|
|
64
|
+
f"CREATE POLICY {table}_isolation ON {table}",
|
|
65
|
+
f" USING ({tenant})",
|
|
66
|
+
f" WITH CHECK ({tenant});",
|
|
67
|
+
]
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
ws = model.workspace_column
|
|
71
|
+
readable = (
|
|
72
|
+
f"{ws} = ANY (string_to_array(current_setting('{model.setting('readable')}', true), ','))"
|
|
73
|
+
)
|
|
74
|
+
active = f"{ws} = current_setting('{model.setting('workspace')}', true)"
|
|
75
|
+
bypass = _bypass_predicate(model)
|
|
76
|
+
read_ws = f"({readable} OR {bypass})" if bypass else f"({readable})"
|
|
77
|
+
write_ws = f"({active} OR {bypass})" if bypass else f"({active})"
|
|
78
|
+
read = f"{tenant} AND {read_ws}"
|
|
79
|
+
write = f"{tenant} AND {write_ws}"
|
|
80
|
+
drops = (
|
|
81
|
+
[f"DROP POLICY IF EXISTS {table}_isolation ON {table};"] if model.drop_other_shape else []
|
|
82
|
+
)
|
|
83
|
+
drops += [f"DROP POLICY IF EXISTS {table}_{cmd} ON {table};" for cmd in _COMMANDS]
|
|
84
|
+
return "\n".join(
|
|
85
|
+
[
|
|
86
|
+
*head,
|
|
87
|
+
*drops,
|
|
88
|
+
f"CREATE POLICY {table}_select ON {table}",
|
|
89
|
+
" FOR SELECT",
|
|
90
|
+
f" USING ({read});",
|
|
91
|
+
f"CREATE POLICY {table}_insert ON {table}",
|
|
92
|
+
" FOR INSERT",
|
|
93
|
+
f" WITH CHECK ({write});",
|
|
94
|
+
f"CREATE POLICY {table}_update ON {table}",
|
|
95
|
+
" FOR UPDATE",
|
|
96
|
+
f" USING ({write})",
|
|
97
|
+
f" WITH CHECK ({write});",
|
|
98
|
+
f"CREATE POLICY {table}_delete ON {table}",
|
|
99
|
+
" FOR DELETE",
|
|
100
|
+
f" USING ({write});",
|
|
101
|
+
]
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def policy_statements(model: TenancyModel, table: str) -> list[str]:
|
|
106
|
+
""":func:`policy_sql` split into single statements, without their trailing ``;``.
|
|
107
|
+
|
|
108
|
+
No statement contains a ``;`` of its own, so the split is exact.
|
|
109
|
+
"""
|
|
110
|
+
return [s.strip() for s in policy_sql(model, table).split(";") if s.strip()]
|
pgbulkhead/pool.py
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
"""The connection pool a server builds its engine with, sized together with admission.
|
|
2
|
+
|
|
3
|
+
Every server that owns a database serves many workspaces from one pool per pod. The pool's
|
|
4
|
+
size and the per-workspace admission limit (:mod:`pgbulkhead.admission`) are one
|
|
5
|
+
decision, so they are read, validated and held together in :class:`PoolSettings`:
|
|
6
|
+
|
|
7
|
+
* ``pool_size`` / ``max_overflow`` — the connections the pool keeps open, and the ones it may
|
|
8
|
+
open past that under load. Their sum is the most connections one pod holds.
|
|
9
|
+
* ``pool_timeout_seconds`` — how long a checkout waits for a free connection before the pool
|
|
10
|
+
gives up. A call that gives up here is refused as overloaded, having run nothing.
|
|
11
|
+
* ``workspace_concurrency`` — how many calls one workspace may run at once on the pod.
|
|
12
|
+
* ``workspace_wait_seconds`` — how long a call over that limit waits for a slot before it is
|
|
13
|
+
refused as overloaded.
|
|
14
|
+
|
|
15
|
+
**The rule that ties them:** a call holds its session's connection, and at most one more for a
|
|
16
|
+
write it commits apart from its session (:data:`CONNECTIONS_PER_CALL`). So a workspace at its
|
|
17
|
+
limit holds at most ``CONNECTIONS_PER_CALL × workspace_concurrency`` connections, and that must
|
|
18
|
+
stay below the pool's total, or one workspace could hold every connection and every other
|
|
19
|
+
workspace's call would wait behind it. Settings that break the rule raise
|
|
20
|
+
:class:`PoolConfigError` on construction, which a server does at boot so a value that cannot
|
|
21
|
+
hold fails the rollout rather than a user's call.
|
|
22
|
+
|
|
23
|
+
The default waits sit well under a typical MCP host's tool-call budget (about a minute), so
|
|
24
|
+
an overloaded pod answers with a refusal the agent can retry instead of a call the host
|
|
25
|
+
abandons.
|
|
26
|
+
|
|
27
|
+
Each value is read from ``<PREFIX>_<NAME>`` (:meth:`PoolSettings.from_env`), the prefix being
|
|
28
|
+
the server's own env namespace. Unset, it takes the server's defaults: this module's conservative
|
|
29
|
+
ones unless the server passes its own because its traffic needs more.
|
|
30
|
+
|
|
31
|
+
**The connection budget.** A pod holds at most ``pool_size + max_overflow`` connections, so the
|
|
32
|
+
worst case on one database is::
|
|
33
|
+
|
|
34
|
+
sum over the servers using it of (pool_size + max_overflow) × (replicas + max_surge)
|
|
35
|
+
|
|
36
|
+
where ``max_surge`` is the extra pods a rolling update runs at once (one per server rolling).
|
|
37
|
+
That sum, plus whatever else connects to the database, must stay below its
|
|
38
|
+
``max_connections``. Raising a pool setting or a replica count spends that budget.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
from __future__ import annotations
|
|
42
|
+
|
|
43
|
+
import os
|
|
44
|
+
from collections.abc import Mapping
|
|
45
|
+
from dataclasses import dataclass
|
|
46
|
+
from typing import Any
|
|
47
|
+
|
|
48
|
+
from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
|
|
49
|
+
|
|
50
|
+
__all__ = [
|
|
51
|
+
"CONNECTIONS_PER_CALL",
|
|
52
|
+
"PoolConfigError",
|
|
53
|
+
"PoolSettings",
|
|
54
|
+
"create_pooled_engine",
|
|
55
|
+
]
|
|
56
|
+
|
|
57
|
+
#: The most connections one admitted call holds at once: its session, and one write committed
|
|
58
|
+
#: apart from it.
|
|
59
|
+
CONNECTIONS_PER_CALL = 2
|
|
60
|
+
|
|
61
|
+
# The env suffix of each setting, after the server's prefix and an underscore.
|
|
62
|
+
POOL_SIZE_ENV = "DB_POOL_SIZE"
|
|
63
|
+
MAX_OVERFLOW_ENV = "DB_POOL_MAX_OVERFLOW"
|
|
64
|
+
POOL_TIMEOUT_ENV = "DB_POOL_TIMEOUT_SECONDS"
|
|
65
|
+
WORKSPACE_CONCURRENCY_ENV = "WORKSPACE_CONCURRENCY"
|
|
66
|
+
WORKSPACE_WAIT_ENV = "WORKSPACE_WAIT_SECONDS"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class PoolConfigError(ValueError):
|
|
70
|
+
"""A pool or admission setting is malformed, or the settings together cannot hold."""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass(frozen=True, slots=True)
|
|
74
|
+
class PoolSettings:
|
|
75
|
+
"""One server's pool and per-workspace admission settings, validated on construction.
|
|
76
|
+
|
|
77
|
+
The field defaults are conservative, sized for a server whose peak is a few calls in
|
|
78
|
+
flight, so several servers sharing one database stay well inside its connection budget.
|
|
79
|
+
"""
|
|
80
|
+
|
|
81
|
+
pool_size: int = 5
|
|
82
|
+
max_overflow: int = 5
|
|
83
|
+
pool_timeout_seconds: float = 10.0
|
|
84
|
+
workspace_concurrency: int = 2
|
|
85
|
+
workspace_wait_seconds: float = 15.0
|
|
86
|
+
|
|
87
|
+
def __post_init__(self) -> None:
|
|
88
|
+
if self.pool_size < 1:
|
|
89
|
+
raise PoolConfigError(f"pool_size must be at least 1, got {self.pool_size}")
|
|
90
|
+
if self.max_overflow < 0:
|
|
91
|
+
raise PoolConfigError(f"max_overflow must be at least 0, got {self.max_overflow}")
|
|
92
|
+
if self.workspace_concurrency < 1:
|
|
93
|
+
raise PoolConfigError(
|
|
94
|
+
f"workspace_concurrency must be at least 1, got {self.workspace_concurrency}"
|
|
95
|
+
)
|
|
96
|
+
for name in ("pool_timeout_seconds", "workspace_wait_seconds"):
|
|
97
|
+
if not getattr(self, name) > 0:
|
|
98
|
+
raise PoolConfigError(
|
|
99
|
+
f"{name} must be greater than zero, got {getattr(self, name)}"
|
|
100
|
+
)
|
|
101
|
+
held = CONNECTIONS_PER_CALL * self.workspace_concurrency
|
|
102
|
+
if held >= self.total:
|
|
103
|
+
raise PoolConfigError(
|
|
104
|
+
f"workspace_concurrency={self.workspace_concurrency} lets one workspace hold "
|
|
105
|
+
f"{held} of the pool's {self.total} connections; it must hold fewer, so other "
|
|
106
|
+
"workspaces still get one"
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
@property
|
|
110
|
+
def total(self) -> int:
|
|
111
|
+
"""The most connections the pool holds: ``pool_size + max_overflow``."""
|
|
112
|
+
return self.pool_size + self.max_overflow
|
|
113
|
+
|
|
114
|
+
@classmethod
|
|
115
|
+
def from_env(
|
|
116
|
+
cls,
|
|
117
|
+
prefix: str,
|
|
118
|
+
*,
|
|
119
|
+
defaults: PoolSettings | None = None,
|
|
120
|
+
environ: Mapping[str, str] | None = None,
|
|
121
|
+
) -> PoolSettings:
|
|
122
|
+
"""Read ``<prefix>_DB_POOL_SIZE``, ``…_DB_POOL_MAX_OVERFLOW``,
|
|
123
|
+
``…_DB_POOL_TIMEOUT_SECONDS``, ``…_WORKSPACE_CONCURRENCY`` and
|
|
124
|
+
``…_WORKSPACE_WAIT_SECONDS``; an unset or blank one takes its value from ``defaults``
|
|
125
|
+
(this class's when omitted).
|
|
126
|
+
|
|
127
|
+
Raises :class:`PoolConfigError`, naming the variables, for a value that does not parse
|
|
128
|
+
or settings that cannot hold together.
|
|
129
|
+
"""
|
|
130
|
+
env = os.environ if environ is None else environ
|
|
131
|
+
if defaults is None:
|
|
132
|
+
defaults = cls()
|
|
133
|
+
|
|
134
|
+
def raw(suffix: str) -> tuple[str, str | None]:
|
|
135
|
+
name = f"{prefix}_{suffix}"
|
|
136
|
+
value = env.get(name, "").strip()
|
|
137
|
+
return name, value or None
|
|
138
|
+
|
|
139
|
+
def integer(suffix: str, default: int) -> int:
|
|
140
|
+
name, value = raw(suffix)
|
|
141
|
+
if value is None:
|
|
142
|
+
return default
|
|
143
|
+
try:
|
|
144
|
+
return int(value)
|
|
145
|
+
except ValueError:
|
|
146
|
+
raise PoolConfigError(f"{name} must be an integer, got {value!r}") from None
|
|
147
|
+
|
|
148
|
+
def seconds(suffix: str, default: float) -> float:
|
|
149
|
+
name, value = raw(suffix)
|
|
150
|
+
if value is None:
|
|
151
|
+
return default
|
|
152
|
+
try:
|
|
153
|
+
return float(value)
|
|
154
|
+
except ValueError:
|
|
155
|
+
raise PoolConfigError(
|
|
156
|
+
f"{name} must be a number of seconds, got {value!r}"
|
|
157
|
+
) from None
|
|
158
|
+
|
|
159
|
+
values = {
|
|
160
|
+
"pool_size": integer(POOL_SIZE_ENV, defaults.pool_size),
|
|
161
|
+
"max_overflow": integer(MAX_OVERFLOW_ENV, defaults.max_overflow),
|
|
162
|
+
"pool_timeout_seconds": seconds(POOL_TIMEOUT_ENV, defaults.pool_timeout_seconds),
|
|
163
|
+
"workspace_concurrency": integer(
|
|
164
|
+
WORKSPACE_CONCURRENCY_ENV, defaults.workspace_concurrency
|
|
165
|
+
),
|
|
166
|
+
"workspace_wait_seconds": seconds(WORKSPACE_WAIT_ENV, defaults.workspace_wait_seconds),
|
|
167
|
+
}
|
|
168
|
+
try:
|
|
169
|
+
return cls(**values)
|
|
170
|
+
except PoolConfigError as exc:
|
|
171
|
+
raise PoolConfigError(f"{exc} (read from the {prefix}_* settings)") from None
|
|
172
|
+
|
|
173
|
+
def engine_options(self) -> dict[str, Any]:
|
|
174
|
+
"""The pool keywords for ``create_async_engine``."""
|
|
175
|
+
return {
|
|
176
|
+
"pool_pre_ping": True,
|
|
177
|
+
"pool_size": self.pool_size,
|
|
178
|
+
"max_overflow": self.max_overflow,
|
|
179
|
+
"pool_timeout": self.pool_timeout_seconds,
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def create_pooled_engine(url: str, settings: PoolSettings, **options: Any) -> AsyncEngine:
|
|
184
|
+
"""An async engine whose pool is sized by ``settings``, with ``pool_pre_ping`` on.
|
|
185
|
+
|
|
186
|
+
``options`` pass through to ``create_async_engine`` and may override the pool keywords.
|
|
187
|
+
"""
|
|
188
|
+
return create_async_engine(url, **{**settings.engine_options(), **options})
|
pgbulkhead/py.typed
ADDED
|
File without changes
|
pgbulkhead/session.py
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"""Sessions that bind a context for row-level security, and return their connection when
|
|
2
|
+
cancelled.
|
|
3
|
+
|
|
4
|
+
**Binding.** A session sets the model's settings with ``set_config(name, value, true)`` inside a
|
|
5
|
+
transaction. ``true`` makes each one local to the transaction, so it ends at commit or rollback
|
|
6
|
+
and a pooled connection never carries one request's tenant into the next. Values are bound
|
|
7
|
+
parameters, never interpolated into SQL.
|
|
8
|
+
|
|
9
|
+
**Cancellation.** An MCP call runs under a cancel scope, and a cancelled scope raises again at
|
|
10
|
+
every await inside it. A session left by cancellation (a client that hung up, a host timeout)
|
|
11
|
+
would have its own rollback cancelled too, and SQLAlchemy would then terminate the connection
|
|
12
|
+
instead of returning it: every cancelled call would cost the pool a connection. Each session
|
|
13
|
+
here therefore ends its transaction and returns its connection inside a shielded scope. Each
|
|
14
|
+
cleanup step (the commit or rollback, then the return) is bounded by
|
|
15
|
+
:data:`CLEANUP_TIMEOUT_SECONDS`, so a database that stops answering cannot hold the exit
|
|
16
|
+
forever: past the bound a rollback or return is abandoned and the connection discarded, and a
|
|
17
|
+
commit raises ``TimeoutError``, because its writes may or may not have landed.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
from collections.abc import AsyncGenerator, Iterable
|
|
23
|
+
from contextlib import asynccontextmanager
|
|
24
|
+
|
|
25
|
+
import anyio
|
|
26
|
+
from sqlalchemy import text
|
|
27
|
+
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
|
|
28
|
+
|
|
29
|
+
from .context import SecurityContext
|
|
30
|
+
from .model import GucBypass, TenancyModel
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"CLEANUP_TIMEOUT_SECONDS",
|
|
34
|
+
"bind_context",
|
|
35
|
+
"check_context",
|
|
36
|
+
"scoped_session",
|
|
37
|
+
"system_session",
|
|
38
|
+
"transaction",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
#: How long each cleanup step may run shielded from the caller's cancellation. The two steps
|
|
42
|
+
#: run in turn, so a whole exit is bounded by about twice this.
|
|
43
|
+
CLEANUP_TIMEOUT_SECONDS = 10.0
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@asynccontextmanager
|
|
47
|
+
async def transaction(engine: AsyncEngine) -> AsyncGenerator[AsyncConnection, None]:
|
|
48
|
+
"""``engine.begin()`` with its exit shielded from the caller's cancellation.
|
|
49
|
+
|
|
50
|
+
Commits when the body completes and rolls back when it raises (cancellation included), then
|
|
51
|
+
returns the connection. Binds nothing: use it for work that needs no row-level scope.
|
|
52
|
+
"""
|
|
53
|
+
conn = await engine.connect()
|
|
54
|
+
try:
|
|
55
|
+
trans = await conn.begin()
|
|
56
|
+
try:
|
|
57
|
+
yield conn
|
|
58
|
+
except BaseException:
|
|
59
|
+
if trans.is_active:
|
|
60
|
+
with anyio.move_on_after(CLEANUP_TIMEOUT_SECONDS, shield=True):
|
|
61
|
+
await trans.rollback()
|
|
62
|
+
raise
|
|
63
|
+
if trans.is_active:
|
|
64
|
+
with anyio.fail_after(CLEANUP_TIMEOUT_SECONDS, shield=True):
|
|
65
|
+
await trans.commit()
|
|
66
|
+
finally:
|
|
67
|
+
with anyio.move_on_after(CLEANUP_TIMEOUT_SECONDS, shield=True):
|
|
68
|
+
await conn.close()
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
async def _bind(conn: AsyncConnection, setting: str, value: str) -> None:
|
|
72
|
+
await conn.execute(text(f"SELECT set_config('{setting}', :v, true)"), {"v": value})
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
async def bind_context(conn: AsyncConnection, model: TenancyModel, ctx: SecurityContext) -> None:
|
|
76
|
+
"""Bind ``ctx`` under ``model`` on ``conn``, for a transaction you already manage.
|
|
77
|
+
|
|
78
|
+
Must run inside a transaction: outside one, each ``set_config(.., true)`` ends with its own
|
|
79
|
+
statement and binds nothing. Binds the values as given; :func:`scoped_session` is the
|
|
80
|
+
checked path, which refuses them first when they cannot be bound faithfully (see
|
|
81
|
+
:func:`check_context`).
|
|
82
|
+
|
|
83
|
+
The readable workspaces and the scopes are bound as one comma-joined value, and the policy
|
|
84
|
+
splits it on commas again. A value containing a comma would therefore bind as several, and
|
|
85
|
+
could make a workspace readable that the context never granted. Bind only checked values.
|
|
86
|
+
"""
|
|
87
|
+
await _bind(conn, model.setting("tenant"), ctx.tenant_id)
|
|
88
|
+
if model.has_workspace:
|
|
89
|
+
readable = ctx.readable_workspaces() if model.active_is_readable else ctx.allowed_workspaces
|
|
90
|
+
await _bind(conn, model.setting("workspace"), ctx.workspace_id or "")
|
|
91
|
+
await _bind(conn, model.setting("readable"), ",".join(sorted(readable)))
|
|
92
|
+
if model.scopes_setting is not None:
|
|
93
|
+
await _bind(conn, model.setting("scopes"), ",".join(sorted(ctx.scopes)))
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def check_context(model: TenancyModel, ctx: SecurityContext) -> None:
|
|
97
|
+
"""Raise :class:`ValueError` unless ``ctx`` can be bound under ``model`` faithfully.
|
|
98
|
+
|
|
99
|
+
Refuses an empty tenant, and an empty workspace when the model has one, rather than binding
|
|
100
|
+
a value that matches nothing: an unscoped read should be a deliberate act, not a typo that
|
|
101
|
+
looks like an empty result. Refuses an empty or comma-bearing workspace, read grant or
|
|
102
|
+
scope, because those are bound comma-joined and a comma inside one would split it into
|
|
103
|
+
several on the database side, widening what the session may read.
|
|
104
|
+
"""
|
|
105
|
+
if not ctx.tenant_id:
|
|
106
|
+
raise ValueError("a scoped session requires a non-empty, verified tenant")
|
|
107
|
+
if model.has_workspace:
|
|
108
|
+
if not ctx.workspace_id:
|
|
109
|
+
raise ValueError("this model requires a non-empty, verified workspace")
|
|
110
|
+
_check_items((ctx.workspace_id, *ctx.allowed_workspaces), "workspace")
|
|
111
|
+
if model.scopes_setting is not None:
|
|
112
|
+
_check_items(ctx.scopes, "scope")
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _check_items(values: Iterable[str], what: str) -> None:
|
|
116
|
+
for value in values:
|
|
117
|
+
if not value or "," in value:
|
|
118
|
+
raise ValueError(f"a {what} bound in a list must be non-empty and contain no comma")
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
@asynccontextmanager
|
|
122
|
+
async def scoped_session(
|
|
123
|
+
engine: AsyncEngine, model: TenancyModel, ctx: SecurityContext
|
|
124
|
+
) -> AsyncGenerator[AsyncConnection, None]:
|
|
125
|
+
"""A transaction with ``ctx`` bound under ``model``.
|
|
126
|
+
|
|
127
|
+
Every query inside sees only the context's tenant and, for a model with a workspace, the
|
|
128
|
+
workspaces it may read; every write lands only in its tenant and active workspace. Raises
|
|
129
|
+
:class:`ValueError` for a context :func:`check_context` refuses, before opening anything.
|
|
130
|
+
"""
|
|
131
|
+
check_context(model, ctx)
|
|
132
|
+
async with transaction(engine) as conn:
|
|
133
|
+
await bind_context(conn, model, ctx)
|
|
134
|
+
yield conn
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
@asynccontextmanager
|
|
138
|
+
async def system_session(
|
|
139
|
+
engine: AsyncEngine, model: TenancyModel, tenant_id: str | None = None
|
|
140
|
+
) -> AsyncGenerator[AsyncConnection, None]:
|
|
141
|
+
"""A transaction that crosses the workspace wall through the model's :class:`GucBypass`.
|
|
142
|
+
|
|
143
|
+
With ``tenant_id`` it reads and writes every workspace of that tenant. Without one it binds
|
|
144
|
+
no tenant, so it matches no row until the body binds one itself: the tenant wall holds
|
|
145
|
+
either way. Audit every use. Refused for a model without a ``GucBypass``: a
|
|
146
|
+
:class:`~pgbulkhead.RoleBypass` is taken by connecting as the privileged role, so open a
|
|
147
|
+
:func:`scoped_session` on an engine that connects as that role instead.
|
|
148
|
+
"""
|
|
149
|
+
if not isinstance(model.bypass, GucBypass):
|
|
150
|
+
raise ValueError("system_session needs a model whose bypass is a GucBypass")
|
|
151
|
+
if tenant_id is not None and not tenant_id:
|
|
152
|
+
raise ValueError("system_session requires a non-empty tenant when given one")
|
|
153
|
+
async with transaction(engine) as conn:
|
|
154
|
+
await conn.execute(
|
|
155
|
+
text(f"SELECT set_config('{model.setting('bypass')}', '{model.bypass.value}', true)")
|
|
156
|
+
)
|
|
157
|
+
if tenant_id is not None:
|
|
158
|
+
await _bind(conn, model.setting("tenant"), tenant_id)
|
|
159
|
+
yield conn
|
pgbulkhead/testing.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Test helpers for a server built on :class:`~pgbulkhead.SecuredDatabase`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Generator
|
|
6
|
+
from contextlib import contextmanager
|
|
7
|
+
|
|
8
|
+
from .admission import WorkspaceLimiter
|
|
9
|
+
from .database import SecuredDatabase
|
|
10
|
+
|
|
11
|
+
__all__ = ["use_limiter"]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@contextmanager
|
|
15
|
+
def use_limiter(
|
|
16
|
+
db: SecuredDatabase, limiter: WorkspaceLimiter
|
|
17
|
+
) -> Generator[WorkspaceLimiter, None, None]:
|
|
18
|
+
"""Run ``db``'s sessions under ``limiter`` (a small cap, a short wait) for the block."""
|
|
19
|
+
previous = db._limiter
|
|
20
|
+
db._limiter = limiter
|
|
21
|
+
try:
|
|
22
|
+
yield limiter
|
|
23
|
+
finally:
|
|
24
|
+
db._limiter = previous
|