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/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