minimost.common

Shared path helpers and per-user database initialisation.

This module provides two things:

Path resolution — a single DB_DIR constant and user_db_path() so every other module refers to the same on-disk location without duplicating the path logic.
Schema bootstrap — init_user_db() creates (or opens) a user’s SQLite database and ensures the messages table exists with the full column set.

Module-level attributes

DB_DIRpathlib.Path: Absolute path to the users/ directory that stores all per-user SQLite database files. The directory is created lazily by init_user_db() the first time it is called.

minimost.common.user_db_path(username: str) → Path[source]

Return the absolute filesystem path for a user’s SQLite database.

The path follows the pattern <project_root>/users/<username>.db. This function does not create the file or its parent directory — use init_user_db() for that.

Parameters:: username (str) – The account username. Must be a valid filename component (alphanumeric, hyphens, and underscores).
Returns:: Absolute path to the user’s .db file.
Return type:: pathlib.Path

Example:

path = user_db_path("alice")
# e.g. PosixPath('/srv/minimost/users/alice.db')

minimost.common.init_user_db(username: str)[source]

Create the per-user SQLite database and ensure the schema is current.

This function is idempotent: calling it multiple times on the same username is safe because the CREATE TABLE IF NOT EXISTS guard prevents duplicate table creation.

What it does:

Creates the users/ directory if it does not already exist.
Opens (or creates) users/<username>.db with SQLite.
Enables WAL (Write-Ahead Logging) journal mode for better concurrency under simultaneous reads from multiple Gunicorn workers.
Creates the messages table if it is absent.

Messages table schema:

Column	Type	Description
`id`	INTEGER PK	Auto-increment primary key.
`channel`	TEXT	Public channel name (e.g. `"general"`) or DM identifier (e.g. `"dm:alice:bob"`).
`sender`	TEXT	Username of the message author.
`content`	TEXT	Message body text. `NULL` for image-only messages.
`content_type`	TEXT	Always `'text'` for the current version; reserved for future media types.
`filename`	TEXT	Uploaded image filename stored in `uploads/`. `NULL` for text-only messages.
`ts`	REAL	Unix timestamp (seconds, floating-point) at which the message was sent. Used as the primary ordering key and as the cross-user identity token for edits, deletes, and reactions.
`edited`	INTEGER	Boolean flag (0/1) — `1` when the message body has been modified after initial send.
`edited_ts`	REAL	Unix timestamp of the most recent edit.
`read`	INTEGER	Per-user read flag (0/1). The sender’s copy is always inserted as `read=1`; recipients start at `0`.
`deleted`	INTEGER	Soft-delete flag (0/1). Deleted messages are retained in the database so that tombstones can be propagated to clients that have already cached the message.
`deleted_ts`	REAL	Unix timestamp when the message was deleted.
`reply_to_id`	INTEGER FK	Foreign key to `messages.id` — the parent message that this message is replying to, or `NULL`.
`reactions`	TEXT	Legacy JSON column; reactions are now stored in the shared `presence.db::message_reactions` table. Kept for schema compatibility.
`reactions_ts`	REAL	Unix timestamp updated whenever a reaction is toggled. The polling query uses this to detect reaction changes without re-fetching the whole message list.
`mentions`	TEXT	Reserved for future `@mention` tracking.
`metadata`	TEXT	Reserved for future structured metadata.
`client_msg_id`	TEXT	Client-generated deduplication token (not currently enforced server-side).
`expires_ts`	REAL	Unix timestamp after which the associated upload file may be deleted by `minimost.clean`.

Parameters:: username (str) – Account username whose database should be initialised.
Returns:: None

Messages Table Schema

The messages table created by minimost.common.init_user_db() has the following columns:

Column	Type	Description
`id`	INTEGER PK	Auto-increment primary key (differs across per-user databases).
`channel`	TEXT NOT NULL	Public channel name or DM identifier (`"dm:user1:user2"`).
`sender`	TEXT NOT NULL	Username of the message author.
`content`	TEXT	Message text body. `NULL` for image-only messages.
`content_type`	TEXT	Always `'text'`. Reserved for future media types.
`filename`	TEXT	UUID-based image filename. `NULL` for text-only messages.
`ts`	REAL NOT NULL	Unix timestamp (seconds, floating-point). Shared across all user copies of the same message.
`edited`	INTEGER (0/1)	Whether this message has been edited.
`edited_ts`	REAL	Timestamp of the most recent edit.
`read`	INTEGER (0/1)	Per-user read flag. Sender’s copy is inserted as `read=0`; seeds from `minimost.auth._seed_channel_history()` are `read=1`.
`deleted`	INTEGER (0/1)	Soft-delete flag.
`deleted_ts`	REAL	Timestamp of deletion.
`reply_to_id`	INTEGER FK	Foreign key to `messages.id` for threaded replies.
`reactions`	TEXT	Legacy column (unused). Reactions are in `presence.db`.
`reactions_ts`	REAL	Updated when a reaction is toggled; triggers polling pickup.
`mentions`	TEXT	Reserved for future `@mention` tracking.
`metadata`	TEXT	Reserved for future structured metadata.
`client_msg_id`	TEXT	Client-generated deduplication token.
`expires_ts`	REAL	Expiry timestamp for the associated upload file.