Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorLeitwolf112026-10-06 22:53:46 +0300
committerLeitwolf112026-10-06 22:53:46 +0300
commit1c986ff99b3c8f349e4a63c0e922276ddf7dc836 (patch)
tree33c88e9cbeaa7758365a62c4c12ca9726dad607d /docs
parent933244cc0fa149427d22d06be4d226c0a67e8b80 (diff)
downloadprogmaweb-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.md4
-rw-r--r--docs/DEVELOPMENT.md16
-rw-r--r--docs/LIMITATIONS.md23
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