rowstile for Python
pip install --pre rowstile (--pre: the newest pre-release) installs the rowstile command (rowstile init, dev, migrate, review; also python -m rowstile) and the SDK for Python apps. Extras bring the integrations' dependencies: rowstile[fastapi], [sqlalchemy], [psycopg], [asyncpg], [django] (a preview: it may change in any release). Python 3.11 or newer.
The SDK for Python apps on a rowstile policy: every transaction signs in as whoever the request or the job acts for, refused writes become a 403 with the database's reason, rows the user can't see a 404, and the app refuses to start on a connection that skips row-level security. It holds no rowstile logic: it calls the authz.* functions the policy made, and translates their answers.
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine
from rowstile.fastapi import Rowstile
engine = create_async_engine("postgresql+asyncpg://app@db/app")
app = FastAPI()
Rowstile(app, engine, user=current_user) # current_user(request): its user's id, or None; before adding routes| module | what |
|---|---|
rowstile | acting_as(who), job(who) (a decorator, or a with block for the user a job's argument names; inside it the database's refusals are raised as Refused and NotFound, which pickle and Celery's results give back whole: preview, for Celery's and RQ's workers), Principal, Refused, NotFound, refusal(exc), error_code(exc) (rowstile's code for any database error: AZ709), not_signed_in(exc) (whether it is the not-signed-in error, AZ701: a query in a transaction nobody signed in to; a login refused, AZ703, settings changed by hand, AZ702, and Postgres's own refusal to connect, with no code, have its SQLSTATE, 28000, but are not it), verdict(table, command, key, lines, who, named) (what each driver's expect() raises for an update or delete that changed nothing, from authz.explain_rule's answer; named is the table as the policy names it, public.notes for a model that says notes, so the refusal names it as a refused insert does), act_as_sql() |
rowstile.fastapi | Rowstile(app, engine, user=...): the request's principal, 403/404 problem bodies (and 404 for what a call names that isn't there, 400 for a missing or wrong argument, 401 for a call that needs someone signed in or a login refused, 409 for a move inside itself, and for an ORM update the rules allow of a row that changed since it was read), the start-up check; .mount_scim("/scim/v2") on it answers an identity provider's SCIM requests there, each passed to authz.scim (their bearer token alone says who asks: user(request) isn't asked); on psycopg or asyncpg without SQLAlchemy, Rowstile(app, None, user=...), which needs no SQLAlchemy installed (the fastapi extra brings it, for the engine: such an app installs fastapi and rowstile[psycopg]) |
rowstile.sqlalchemy | install(engine) (sync or async; SQLModel too; one principal a transaction: a statement in it while the code acts for anyone else is a RuntimeError), ids(type, perm) for where, perms_of() for a list's buttons, can() (Queries[ObjectType, Permission]() has the three taking only the generated client's names, so a misspelled one doesn't type-check), expect() for Core updates and deletes, why_stale() for the ORM's StaleDataError, scim() and scim_sync() (an identity provider's SCIM request passed to authz.scim, in a transaction of its own that signs nobody in: for a route on another framework than FastAPI) |
rowstile.psycopg | transaction(conn, who), atransaction(aconn, who) (one principal a transaction: inside a block, one for the same principal is a savepoint, one for anyone else a RuntimeError; a statement inside a block runs as the block's principal), expect(), aexpect(), problems(conn) (the start-up check: what is wrong with the app's connection) and connection_check(conn) (its rows) |
rowstile.asyncpg | transaction(conn, who) (as psycopg's), expect(), problems(conn), connection_check(conn) |
rowstile.django | a preview: it may change in any release. "rowstile.django" in INSTALLED_APPS (every transaction on Django's Postgres connections signs in as whoever the code acts for: an atomic block when it begins, a query outside one in a transaction of its own; psycopg 3; one principal a transaction: a statement in it while the code acts for anyone else is a RuntimeError), Middleware (each request acts for ROWSTILE_USER(request), else request.user; 403/404 problem bodies and each code's answer, as rowstile.fastapi's; the start-up check of ROWSTILE_CHECK_DATABASES), save(instance) (an update, never Django's insert after a refused one: NotFound or Refused), expect() for a queryset's update() and delete(), ids(), can(), perms_of(), Queries[ObjectType, Permission](), check(); rowstile.django.testing.database_per_worker(url) for pytest-django's django_db_setup |
rowstile.alembic | include_name, include_object: autogenerate leaves rowstile's objects alone, and a model of a masked view that says so (info={"rowstile": True} on its table) |
rowstile.testing | pytest fixtures, loaded once the package is installed: as_user, assert_refused, assert_not_found (awaited, with an async function: a test that never awaits it fails), authz_owner_url, authz_app_url; database_per_worker(url): a copy of the migrated test database for each pytest-xdist worker |
Who a transaction acts for: 42 or "42" (a user), ("service", 3) (another principal type of the policy), or None (nobody: only what anyone may see; None given to a call is nobody too, whoever the code around it acts for). A plain id is always a user's, whatever it holds: "service:3" is the user with that id, so an id from outside (a username, an identity provider's subject) can't name a service. Principal.parse(text) reads back what str() wrote, for text your own code wrote (a job's argument): str() writes a user whose id holds : or is nobody as user:<id> (user:service:3), so every principal reads back as itself. The audit trail and created_by name who acted the same way, so Principal.parse reads them too. Every transaction signs in, even when nobody is signed in, and nothing uses a session-level SET, so pools and poolers in transaction mode are safe; behind one that keeps no prepared statements, turn the driver's off (Behind a pooler).
With FastAPI: user(request) runs in a middleware that Rowstile(...) adds, so give it the session or the token to read from the request itself. What a middleware of yours puts on request.state is there only if that middleware was added after Rowstile(...) (Starlette runs the one added last first); added before, it hasn't run yet. user may raise an HTTPException. The start-up check runs whether or not the app has a lifespan. WebSockets are not signed in: use rowstile.acting_as() in the endpoint. An engine in AUTOCOMMIT can't be signed in (the sign-in lasts a transaction): its queries fail with NotSignedIn.
Policy changes ship as migrations for your tool (rowstile migrate, with tool = "alembic" in rowstile.toml). The types and permissions of your policy are generated names (rowstile client py), so a misspelled permission doesn't type-check.
integrations/fastapi/ is the conformance suite: a small FastAPI app on SQLAlchemy (async, asyncpg) and Alembic, and the checks every supported stack passes (integrations/fastapi/test.sh). integrations/django/ is the Django module's: a small Django app on psycopg 3, Django's migrations and pytest-django (Django).