diff options
| author | Leitwolf11 | 2026-10-06 22:53:46 +0300 |
|---|---|---|
| committer | Leitwolf11 | 2026-10-06 22:53:46 +0300 |
| commit | 1c986ff99b3c8f349e4a63c0e922276ddf7dc836 (patch) | |
| tree | 33c88e9cbeaa7758365a62c4c12ca9726dad607d /docs | |
| parent | 933244cc0fa149427d22d06be4d226c0a67e8b80 (diff) | |
| download | progmaweb-1c986ff99b3c8f349e4a63c0e922276ddf7dc836.tar.gz | |
Keep accounts and sessions in PostgreSQL
The account API kept everything in the memory of its process, so every
restart and every deployment of the API deleted all accounts and signed
everyone out.
PostgresAccountStore implements IAccountStore on PostgreSQL through Npgsql.
The three uniqueness rules are unique constraints, so two requests that race
for one name, address or Google identity are decided by the database. A
refused account is an ordinary answer, not an exception, and the rules are
reported in the order the in-memory store reports them. A session refers to
its account, and a session of an account that is not stored is refused; the
in-memory store now refuses it as well.
The schema is a list of numbered steps. The service takes the missing ones
when it starts, in one transaction under an advisory lock, and does not
start when the database cannot be reached or is newer than the release.
/health answers 503 while the database does not answer.
ConnectionStrings:Accounts selects PostgreSQL. A production service that is
given no database does not start; keeping accounts in memory there has to
be asked for with Accounts:Store=Memory. Development and the tests keep the
in-memory store by default.
The store gains RemoveExpiredSessionsAsync, and a background service calls
it at the start and once an hour: a session whose token is never presented
again no longer keeps its row for ever.
PostgreSQL keeps a timestamp to the microsecond. The store cuts a moment to
that precision and returns what it stored, and the service uses the
returned account, so the creation time in the registration response equals
the one every later read returns.
Tests. AccountStoreContractTests states the rules once and runs them on
both stores. Further tests cover the schema steps applied concurrently and a
database that is too new, the choice of the store from the configuration,
the removal of expired sessions, and an account with its session surviving
a restart of the service over HTTP. The PostgreSQL tests read their
database from PROGMAWEB_TEST_POSTGRES and work in a schema of their own
each. Without the variable they are skipped; CI starts PostgreSQL 16 for
them, and a test fails the run when the variable is missing there.
Operations. ops/README.md describes the database: the Unix socket with peer
authentication, so that no password exists, the one-time preparation, and
rollback across a schema step. The service unit starts after PostgreSQL.
docs/LIMITATIONS.md no longer lists the in-memory store and now lists the
missing backup and the missing deletion of accounts.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ARCHITECTURE.md | 4 | ||||
| -rw-r--r-- | docs/DEVELOPMENT.md | 16 | ||||
| -rw-r--r-- | docs/LIMITATIONS.md | 23 |
3 files changed, 31 insertions, 12 deletions
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ef5a427..cb4b20f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -90,7 +90,9 @@ step. parameter and the `Accept-Language` header. Each is validated against the list of published locales. - **Nginx and Next.js to the API.** The API trusts forwarded headers only from loopback and reads one proxy hop. A caller that reached the API directly could otherwise forge the client address that the rate limiter uses. -- **API to its store.** The store keeps password hashes and session digests, never passwords or session tokens. +- **API to its store.** The store is a PostgreSQL database on the same host, reached through its Unix socket as the + operating system user of the service, without a password. It keeps password hashes and session digests, never + passwords or session tokens. - **What the browser never receives.** Password hashes, session digests, deployment secrets and internal addresses. The API has no bulk-delete, reset-all or seed-password endpoint. Maintenance of production accounts is an operations diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 022af77..85c4638 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -18,7 +18,7 @@ ```text apps/web Next.js application: pages, components, localization, host routing apps/api ASP.NET Core account API -apps/api-tests xUnit tests of the API, run against the application in memory +apps/api-tests xUnit tests of the API, run against the application in memory and against PostgreSQL docs this documentation and the DocFX project in docs/api ops Nginx, systemd and mail configuration with their runbooks ``` @@ -49,7 +49,14 @@ Open the three surfaces through their development host names: | `http://account.localhost:3000/` | account pages | | `http://viget.localhost:3000/` | ViGet catalogs | -Accounts created locally live in the memory of the API process and are gone when it stops. +Accounts created locally live in the memory of the API process and are gone when it stops. To keep them, point the +API at a PostgreSQL database before it starts; it creates its tables itself: + +```text +ConnectionStrings__Accounts=Host=localhost;Database=progmaweb_accounts;Username=<role> +``` + +Production always uses PostgreSQL; see [Operations](../ops/README.md). Sign-in with Google is optional locally. It needs the identifier and secret of a Google OAuth client in `Authentication__Google__ClientId` and `Authentication__Google__ClientSecret`, set in the environment before the API @@ -84,6 +91,11 @@ themes, a narrow window, and keyboard focus. - **Frontend** (`apps/web/tests`): the list of published locales, the shape of every message tree, language negotiation, cookie attributes, text direction and page metadata. The tests import the TypeScript sources directly and do not start a server. +- **Account store** (`apps/api-tests`): one set of rules, `AccountStoreContractTests`, run against the in-memory + store and against PostgreSQL, so the two cannot drift apart; the schema steps; and an account with its session + surviving a restart of the service. The PostgreSQL tests need the connection string of a database whose user may + create schemas in `PROGMAWEB_TEST_POSTGRES`; each test works in a schema of its own and removes it. Without the + variable they are skipped locally. CI starts PostgreSQL for them and fails when the variable is missing. - **API** (`apps/api-tests`): the endpoints through an in-memory application, including validation, duplicate names and addresses, session cookies, the Google flow and security headers; and the account service on its own. The rate limit has no automated test. diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md index 6d09e7d..648a3df 100644 --- a/docs/LIMITATIONS.md +++ b/docs/LIMITATIONS.md @@ -6,17 +6,22 @@ This page lists what Progmaweb does not do yet, so that nobody has to discover it in production. Each entry says what is missing, what follows from it, and what would close it. -## Accounts are kept in memory +## The account database has no backup yet -The account API registers `InMemoryAccountStore` as its only store. Accounts and sessions live in the memory of the -API process. +Accounts and sessions are kept in PostgreSQL; see [Operations](../ops/README.md). Restarting or redeploying the API no +longer loses them. Nothing copies the database anywhere else yet. -- **Consequence.** Every restart of the API service deletes all accounts and signs everyone out. A deployment that - restarts the API has this effect. -- **In operations.** Do not restart the API unless its code or configuration changed. A release that changes only the - frontend should restart only the frontend service; see [Operations](../ops/README.md). -- **What closes it.** A durable implementation of `IAccountStore`. The interface already states the uniqueness and - session rules such a store must keep. +- **Consequence.** Losing the disk of the host, or dropping the database by mistake, loses every account. +- **What closes it.** A scheduled `pg_dump` of the account database to storage outside the host, and a restore that + has been tried once. + +## Accounts cannot be deleted + +The store has no operation that removes an account, and the API has no endpoint for it. + +- **Consequence.** A request to erase an account has to be carried out by hand in the database, by its operator. +- **What closes it.** A deletion operation in the store with an endpoint or an operator command, and a decision about + what happens to the account name afterwards. ## Email addresses are not verified |