golded-ftn-sqlite 1.0.0__py3-none-any.whl

golded_ftn_sqlite/__init__.py

@@ -0,0 +1,15 @@
+"""SQLite message bases for FTN netmail and echomail."""
+
+from .database import SqliteDatabase
+from .models import AreaDefinition, AreaKind
+from .reader import SqliteReader
+from .writer import SqliteSession, SqliteWriter
+
+__all__ = [
+    "AreaDefinition",
+    "AreaKind",
+    "SqliteDatabase",
+    "SqliteReader",
+    "SqliteSession",
+    "SqliteWriter",
+]

golded_ftn_sqlite/database.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import os
+import sqlite3
+from os import PathLike
+from pathlib import Path
+from typing import Self, cast
+
+from golded_ftn import FtnAddress
+
+from .models import AreaDefinition, AreaKind
+
+APPLICATION_ID = 0x47465453
+SCHEMA_VERSION = 1
+
+_SCHEMA = f"""
+PRAGMA application_id = {APPLICATION_ID};
+PRAGMA user_version = {SCHEMA_VERSION};
+
+CREATE TABLE areas (
+    id INTEGER PRIMARY KEY,
+    code TEXT NOT NULL COLLATE NOCASE UNIQUE,
+    name TEXT NOT NULL,
+    kind TEXT NOT NULL CHECK (kind IN ('netmail', 'echomail')),
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    meta_key TEXT,
+    origin_address TEXT
+        CHECK (
+            origin_address IS NULL
+            OR (origin_address != '' AND origin_address = trim(origin_address))
+        ),
+    next_message_number INTEGER NOT NULL DEFAULT 1
+        CHECK (next_message_number > 0)
+) STRICT;
+
+CREATE TABLE messages (
+    id INTEGER PRIMARY KEY,
+    area_id INTEGER NOT NULL REFERENCES areas(id),
+    msgno INTEGER NOT NULL CHECK (msgno > 0),
+    from_name TEXT NOT NULL,
+    to_name TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    body_text TEXT NOT NULL,
+    posted_at TEXT,
+    external_id TEXT,
+    attributes_raw INTEGER NOT NULL,
+    from_address TEXT
+        CHECK (
+            from_address IS NULL
+            OR (from_address != '' AND from_address = trim(from_address))
+        ),
+    to_address TEXT
+        CHECK (
+            to_address IS NULL
+            OR (to_address != '' AND to_address = trim(to_address))
+        ),
+    reply_to_msgno INTEGER,
+    reply1st_msgno INTEGER,
+    reply_next_msgno INTEGER,
+    source_type TEXT,
+    source_path TEXT,
+    source_id TEXT,
+    source_offset INTEGER,
+    revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
+    deleted_at TEXT,
+    UNIQUE (area_id, msgno),
+    CHECK (
+        source_type IS NOT NULL
+        OR (source_path IS NULL AND source_id IS NULL AND source_offset IS NULL)
+    )
+) STRICT;
+
+CREATE INDEX messages_area_posted
+    ON messages (area_id, posted_at, msgno)
+    WHERE deleted_at IS NULL;
+
+CREATE INDEX messages_external_id
+    ON messages (external_id)
+    WHERE external_id IS NOT NULL AND deleted_at IS NULL;
+
+CREATE TRIGGER messages_netmail_addresses_insert
+BEFORE INSERT ON messages
+WHEN (SELECT kind FROM areas WHERE id = NEW.area_id) = 'netmail'
+    AND (NEW.from_address IS NULL OR NEW.to_address IS NULL)
+BEGIN
+    SELECT RAISE(ABORT, 'netmail requires origin and destination addresses');
+END;
+
+CREATE TRIGGER messages_netmail_addresses_update
+BEFORE UPDATE OF area_id, from_address, to_address ON messages
+WHEN (SELECT kind FROM areas WHERE id = NEW.area_id) = 'netmail'
+    AND (NEW.from_address IS NULL OR NEW.to_address IS NULL)
+BEGIN
+    SELECT RAISE(ABORT, 'netmail requires origin and destination addresses');
+END;
+
+CREATE TABLE control_lines (
+    message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+    position INTEGER NOT NULL CHECK (position >= 0),
+    name TEXT NOT NULL COLLATE NOCASE,
+    value TEXT NOT NULL,
+    raw TEXT NOT NULL,
+    PRIMARY KEY (message_id, position)
+) WITHOUT ROWID, STRICT;
+
+CREATE INDEX control_lines_name
+    ON control_lines (name, message_id);
+
+CREATE TABLE routing_entries (
+    message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+    kind TEXT NOT NULL CHECK (kind IN ('seen_by', 'path')),
+    position INTEGER NOT NULL CHECK (position >= 0),
+    value TEXT NOT NULL,
+    PRIMARY KEY (message_id, kind, position)
+) WITHOUT ROWID, STRICT;
+
+CREATE TABLE reply_list_entries (
+    message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+    position INTEGER NOT NULL CHECK (position >= 0),
+    msgno INTEGER NOT NULL CHECK (msgno > 0),
+    PRIMARY KEY (message_id, position)
+) WITHOUT ROWID, STRICT;
+"""
+
+
+def format_address(address: FtnAddress | None) -> str | None:
+    return None if address is None else str(address)
+
+
+def parse_address(value: str | None) -> FtnAddress | None:
+    return None if value is None else FtnAddress.from_string(value)
+
+
+class SqliteDatabase:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    @classmethod
+    def open(cls, path: str | PathLike[str]) -> Self:
+        database_path = Path(path).resolve()
+        connection = connect_database(database_path, read_only=True)
+        connection.close()
+        return cls(database_path)
+
+    @classmethod
+    def create(
+        cls,
+        path: str | PathLike[str],
+        *,
+        area: AreaDefinition,
+    ) -> Self:
+        database_path = Path(path).resolve()
+        database_path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor = os.open(database_path, os.O_CREAT | os.O_EXCL | os.O_RDWR, 0o600)
+        os.close(descriptor)
+        try:
+            with sqlite3.connect(database_path) as connection:
+                connection.execute("PRAGMA journal_mode = WAL")
+                connection.execute("PRAGMA synchronous = NORMAL")
+                connection.executescript(_SCHEMA)
+                connection.execute(
+                    """
+                    INSERT INTO areas (
+                        code, name, kind, sort_order, meta_key, origin_address
+                    ) VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        area.code,
+                        area.name,
+                        area.kind.value,
+                        area.sort_order,
+                        area.meta_key,
+                        format_address(area.default_origin),
+                    ),
+                )
+        except BaseException:
+            database_path.unlink(missing_ok=True)
+            raise
+        return cls(database_path)
+
+    def add_area(self, area: AreaDefinition) -> None:
+        with sqlite3.connect(self.path) as connection:
+            connection.execute(
+                """
+                INSERT INTO areas (
+                    code, name, kind, sort_order, meta_key, origin_address
+                ) VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    area.code,
+                    area.name,
+                    area.kind.value,
+                    area.sort_order,
+                    area.meta_key,
+                    format_address(area.default_origin),
+                ),
+            )
+
+    def areas(self) -> tuple[AreaDefinition, ...]:
+        with sqlite3.connect(self.path) as connection:
+            rows = connection.execute(
+                """
+                SELECT code, name, kind, sort_order, meta_key, origin_address
+                FROM areas
+                ORDER BY id
+                """
+            ).fetchall()
+        return tuple(
+            AreaDefinition(
+                code=row[0],
+                name=row[1],
+                kind=AreaKind(row[2]),
+                default_origin=parse_address(row[5]),
+                sort_order=row[3],
+                meta_key=row[4],
+            )
+            for row in rows
+        )
+
+
+def connect_database(
+    path: Path, *, read_only: bool, timeout: float = 5.0
+) -> sqlite3.Connection:
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    if read_only:
+        connection = sqlite3.connect(
+            f"{path.resolve().as_uri()}?mode=ro",
+            uri=True,
+            timeout=timeout,
+            isolation_level=None,
+        )
+    else:
+        connection = sqlite3.connect(path, timeout=timeout, isolation_level=None)
+    connection.row_factory = sqlite3.Row
+    connection.execute("PRAGMA foreign_keys = ON")
+    connection.execute(f"PRAGMA busy_timeout = {round(timeout * 1000)}")
+    application_id = connection.execute("PRAGMA application_id").fetchone()[0]
+    schema_version = connection.execute("PRAGMA user_version").fetchone()[0]
+    if application_id != APPLICATION_ID or schema_version != SCHEMA_VERSION:
+        connection.close()
+        raise ValueError("not a supported golded-ftn-sqlite database")
+    return connection
+
+
+def select_area(connection: sqlite3.Connection, area_code: str | None) -> sqlite3.Row:
+    if area_code is not None:
+        row = connection.execute(
+            "SELECT * FROM areas WHERE code = ?", (area_code,)
+        ).fetchone()
+        if row is None:
+            raise KeyError(f"unknown area [{area_code}]")
+        return cast(sqlite3.Row, row)
+    rows = connection.execute("SELECT * FROM areas ORDER BY id LIMIT 2").fetchall()
+    if len(rows) != 1:
+        raise ValueError("area_code is required unless the database has one area")
+    return cast(sqlite3.Row, rows[0])

golded_ftn_sqlite/models.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from golded_ftn import FtnAddress
+
+
+class AreaKind(StrEnum):
+    NETMAIL = "netmail"
+    ECHOMAIL = "echomail"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AreaDefinition:
+    code: str
+    name: str
+    kind: AreaKind
+    default_origin: FtnAddress | None = None
+    sort_order: int = 0
+    meta_key: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.code or self.code != self.code.strip():
+            raise ValueError(
+                "area code must be non-empty and have no surrounding space"
+            )
+        if not self.name or self.name != self.name.strip():
+            raise ValueError(
+                "area name must be non-empty and have no surrounding space"
+            )

golded_ftn_sqlite/py.typed

@@ -0,0 +1 @@
+

golded_ftn_sqlite/reader.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterable, Iterator
+from datetime import datetime
+from os import PathLike
+from pathlib import Path
+
+from golded_ftn import (
+    ControlLine,
+    MessageControlLines,
+    MessageProvenance,
+    ParsedMessage,
+    ReaderOptions,
+    parse_message,
+)
+
+from .database import connect_database, select_area
+
+
+def _message_from_row(
+    connection: sqlite3.Connection,
+    database_path: Path,
+    area: sqlite3.Row,
+    row: sqlite3.Row,
+) -> ParsedMessage:
+    controls = tuple(
+        ControlLine(name=item["name"], value=item["value"], raw=item["raw"])
+        for item in connection.execute(
+            """
+            SELECT name, value, raw FROM control_lines
+            WHERE message_id = ? ORDER BY position
+            """,
+            (row["id"],),
+        )
+    )
+    routing = {
+        kind: tuple(
+            item["value"]
+            for item in connection.execute(
+                """
+                SELECT value FROM routing_entries
+                WHERE message_id = ? AND kind = ? ORDER BY position
+                """,
+                (row["id"], kind),
+            )
+        )
+        for kind in ("seen_by", "path")
+    }
+    parsed_body = parse_message(row["body_text"])
+    by_name: dict[str, str] = {}
+    for control in controls:
+        by_name.setdefault(control.name.upper(), control.value)
+    provenance = (
+        MessageProvenance(
+            source_type=row["source_type"],
+            source_path=row["source_path"],
+            source_id=row["source_id"],
+            source_offset=row["source_offset"],
+        )
+        if row["source_type"] is not None
+        else MessageProvenance(
+            source_type="sqlite",
+            source_path=str(database_path),
+            source_id=str(row["id"]),
+        )
+    )
+    return ParsedMessage(
+        msgno=row["msgno"],
+        from_name=row["from_name"],
+        to_name=row["to_name"],
+        subject=row["subject"],
+        body_text=row["body_text"],
+        attributes_raw=row["attributes_raw"],
+        posted_at=(
+            datetime.fromisoformat(row["posted_at"])
+            if row["posted_at"] is not None
+            else None
+        ),
+        external_id=row["external_id"],
+        from_address=row["from_address"],
+        to_address=row["to_address"],
+        reply_to_msgno=row["reply_to_msgno"],
+        reply1st_msgno=row["reply1st_msgno"],
+        reply_next_msgno=row["reply_next_msgno"],
+        area_code=area["code"],
+        area_name=area["name"],
+        area_sort_order=area["sort_order"],
+        area_meta_key=area["meta_key"],
+        control_lines=MessageControlLines(
+            kludges=controls,
+            msgid=row["external_id"] or by_name.get("MSGID"),
+            reply=by_name.get("REPLY"),
+            charset=by_name.get("CHRS") or by_name.get("CHARSET"),
+            seen_by=routing["seen_by"],
+            path=routing["path"],
+            tearline=parsed_body.tearline,
+            origin=parsed_body.origin,
+            origin_address=parsed_body.origin_address,
+        ),
+        provenance=provenance,
+    )
+
+
+class SqliteReader:
+    """Read undeleted messages for one area in msgno order.
+
+    Default streaming yields rows from a live cursor. Pass
+    ``ReaderOptions(eager=True)`` to load every message before returning.
+    """
+
+    def __init__(self, area_code: str | None = None) -> None:
+        self.area_code = area_code
+
+    def read(
+        self,
+        path: str | PathLike[str],
+        options: ReaderOptions | None = None,
+    ) -> Iterable[ParsedMessage]:
+        options = options or ReaderOptions()
+        database_path = Path(path).resolve()
+        connection = connect_database(database_path, read_only=True)
+        try:
+            connection.execute("BEGIN")
+            area = select_area(connection, self.area_code)
+            rows = connection.execute(
+                """
+                SELECT * FROM messages
+                WHERE area_id = ? AND deleted_at IS NULL
+                ORDER BY msgno
+                """,
+                (area["id"],),
+            )
+            if options.eager:
+                messages = tuple(
+                    _message_from_row(connection, database_path, area, row)
+                    for row in rows.fetchall()
+                )
+                connection.commit()
+                connection.close()
+                return messages
+            return self._stream(connection, database_path, area, rows)
+        except BaseException:
+            connection.rollback()
+            connection.close()
+            raise
+
+    @staticmethod
+    def _stream(
+        connection: sqlite3.Connection,
+        database_path: Path,
+        area: sqlite3.Row,
+        rows: sqlite3.Cursor,
+    ) -> Iterator[ParsedMessage]:
+        try:
+            for row in rows:
+                yield _message_from_row(connection, database_path, area, row)
+            connection.commit()
+        except BaseException:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()

golded_ftn_sqlite/writer.py

@@ -0,0 +1,510 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from datetime import UTC, datetime
+from os import PathLike
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+from golded_ftn import (
+    ConflictError,
+    MessageIdentity,
+    MessagePatch,
+    OutgoingMessage,
+    RevisionToken,
+    SessionMessage,
+    Unset,
+    WriterError,
+    WriteResult,
+    WriterOptions,
+)
+
+from .database import connect_database, format_address, parse_address, select_area
+from .reader import _message_from_row
+
+
+def _identity(path: Path, area_code: str, msgno: int) -> MessageIdentity:
+    return MessageIdentity(
+        format="sqlite",
+        base=f"{path}#{area_code}",
+        msgno=msgno,
+    )
+
+
+def _revision(
+    connection: sqlite3.Connection,
+    row: sqlite3.Row,
+    identity: MessageIdentity,
+) -> RevisionToken:
+    revision = int(row["revision"])
+    message_id = int(row["id"])
+    related = (
+        tuple(
+            tuple(item)
+            for item in connection.execute(
+                """
+                SELECT position, name, value, raw FROM control_lines
+                WHERE message_id = ? ORDER BY position
+                """,
+                (message_id,),
+            )
+        ),
+        tuple(
+            tuple(item)
+            for item in connection.execute(
+                """
+                SELECT kind, position, value FROM routing_entries
+                WHERE message_id = ? ORDER BY kind, position
+                """,
+                (message_id,),
+            )
+        ),
+        tuple(
+            tuple(item)
+            for item in connection.execute(
+                """
+                SELECT position, msgno FROM reply_list_entries
+                WHERE message_id = ? ORDER BY position
+                """,
+                (message_id,),
+            )
+        ),
+    )
+    digest = hashlib.sha256(
+        json.dumps(
+            (tuple(row), related), ensure_ascii=False, separators=(",", ":")
+        ).encode()
+    ).hexdigest()
+    return RevisionToken(
+        identity=identity,
+        location=(message_id, revision),
+        digest=digest,
+    )
+
+
+class SqliteWriter:
+    def __init__(self, area_code: str | None = None) -> None:
+        self.area_code = area_code
+
+    def open(
+        self,
+        path: str | PathLike[str],
+        options: WriterOptions | None = None,
+    ) -> SqliteSession:
+        return SqliteSession(
+            Path(path).resolve(), self.area_code, options or WriterOptions()
+        )
+
+
+class SqliteSession:
+    def __init__(
+        self, path: Path, area_code: str | None, options: WriterOptions
+    ) -> None:
+        self.path = path
+        self.area_code = area_code
+        self._connection = connect_database(
+            path, read_only=False, timeout=options.lock_timeout
+        )
+        self._closed = False
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if not self._closed:
+            self._connection.close()
+            self._closed = True
+
+    def append(self, message: OutgoingMessage) -> WriteResult:
+        if self._closed:
+            raise WriterError("SQLite session is closed")
+        connection = self._connection
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            area = select_area(connection, self.area_code)
+            default_origin = parse_address(area["origin_address"])
+            from_address = message.from_address or default_origin
+            if area["kind"] == "netmail":
+                if from_address is None:
+                    raise ValueError("netmail requires an origin address")
+                if message.to_address is None:
+                    raise ValueError("netmail requires a destination address")
+            msgno = int(area["next_message_number"])
+            cursor = connection.execute(
+                """
+                INSERT INTO messages (
+                    area_id, msgno, from_name, to_name, subject, body_text,
+                    posted_at, external_id, attributes_raw,
+                    from_address, to_address,
+                    reply_to_msgno, reply1st_msgno, reply_next_msgno,
+                    source_type, source_path, source_id, source_offset
+                ) VALUES (
+                    ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+                )
+                """,
+                (
+                    area["id"],
+                    msgno,
+                    message.from_name,
+                    message.to_name,
+                    message.subject,
+                    message.body_text,
+                    message.posted_at.isoformat() if message.posted_at else None,
+                    message.external_id,
+                    message.attributes_raw if message.attributes_raw is not None else 0,
+                    format_address(from_address),
+                    format_address(message.to_address),
+                    message.reply_to_msgno,
+                    message.reply1st_msgno,
+                    message.reply_next_msgno,
+                    message.provenance.source_type if message.provenance else None,
+                    message.provenance.source_path if message.provenance else None,
+                    message.provenance.source_id if message.provenance else None,
+                    message.provenance.source_offset if message.provenance else None,
+                ),
+            )
+            if cursor.lastrowid is None:
+                raise WriterError("SQLite did not return a message row ID")
+            message_id = cursor.lastrowid
+            connection.executemany(
+                """
+                INSERT INTO control_lines (message_id, position, name, value, raw)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    (message_id, position, line.name, line.value, line.raw)
+                    for position, line in enumerate(message.control_lines)
+                ),
+            )
+            connection.executemany(
+                """
+                INSERT INTO routing_entries (message_id, kind, position, value)
+                VALUES (?, 'seen_by', ?, ?)
+                """,
+                (
+                    (message_id, position, value)
+                    for position, value in enumerate(message.routing_seen_by)
+                ),
+            )
+            connection.executemany(
+                """
+                INSERT INTO routing_entries (message_id, kind, position, value)
+                VALUES (?, 'path', ?, ?)
+                """,
+                (
+                    (message_id, position, value)
+                    for position, value in enumerate(message.routing_path)
+                ),
+            )
+            connection.executemany(
+                """
+                INSERT INTO reply_list_entries (message_id, position, msgno)
+                VALUES (?, ?, ?)
+                """,
+                (
+                    (message_id, position, value)
+                    for position, value in enumerate(message.reply_list)
+                ),
+            )
+            connection.execute(
+                "UPDATE areas SET next_message_number = ? WHERE id = ?",
+                (msgno + 1, area["id"]),
+            )
+            stored = connection.execute(
+                "SELECT * FROM messages WHERE id = ?", (message_id,)
+            ).fetchone()
+            assert stored is not None
+            identity = _identity(self.path, area["code"], msgno)
+            revision = _revision(connection, stored, identity)
+            connection.commit()
+            return WriteResult(
+                identity=identity,
+                revision=revision,
+            )
+        except BaseException:
+            connection.rollback()
+            raise
+
+    def read(self, msgno: int) -> SessionMessage:
+        if self._closed:
+            raise WriterError("SQLite session is closed")
+        connection = self._connection
+        try:
+            connection.execute("BEGIN")
+            area = select_area(connection, self.area_code)
+            row = connection.execute(
+                """
+                SELECT * FROM messages
+                WHERE area_id = ? AND msgno = ? AND deleted_at IS NULL
+                """,
+                (area["id"], msgno),
+            ).fetchone()
+            if row is None:
+                raise ConflictError("SQLite message is missing")
+            identity = _identity(self.path, area["code"], msgno)
+            result = SessionMessage(
+                message=_message_from_row(connection, self.path, area, row),
+                identity=identity,
+                revision=_revision(connection, row, identity),
+            )
+            connection.commit()
+            return result
+        except BaseException:
+            connection.rollback()
+            raise
+
+    def update(
+        self,
+        identity: MessageIdentity,
+        patch: MessagePatch,
+        expected_revision: RevisionToken,
+    ) -> WriteResult:
+        if self._closed:
+            raise WriterError("SQLite session is closed")
+        connection = self._connection
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            area = select_area(connection, self.area_code)
+            row = connection.execute(
+                """
+                SELECT * FROM messages
+                WHERE area_id = ? AND msgno = ? AND deleted_at IS NULL
+                """,
+                (area["id"], identity.msgno),
+            ).fetchone()
+            if row is None:
+                raise ConflictError("SQLite message is missing")
+            actual_identity = _identity(self.path, area["code"], identity.msgno)
+            actual_revision = _revision(connection, row, actual_identity)
+            if (
+                identity != actual_identity
+                or expected_revision.identity != actual_identity
+                or expected_revision != actual_revision
+            ):
+                raise ConflictError("SQLite message revision changed")
+            from_name = (
+                row["from_name"]
+                if isinstance(patch.from_name, Unset)
+                else patch.from_name
+            )
+            to_name = (
+                row["to_name"] if isinstance(patch.to_name, Unset) else patch.to_name
+            )
+            subject = (
+                row["subject"] if isinstance(patch.subject, Unset) else patch.subject
+            )
+            body_text = (
+                row["body_text"]
+                if isinstance(patch.body_text, Unset)
+                else patch.body_text
+            )
+            if None in (from_name, to_name, subject, body_text):
+                raise ValueError("names, subject and body_text cannot be None")
+            external_id = (
+                row["external_id"]
+                if isinstance(patch.external_id, Unset)
+                else patch.external_id
+            )
+            from_address = (
+                parse_address(row["from_address"])
+                if isinstance(patch.from_address, Unset)
+                else patch.from_address
+            )
+            to_address = (
+                parse_address(row["to_address"])
+                if isinstance(patch.to_address, Unset)
+                else patch.to_address
+            )
+            if isinstance(patch.posted_at, Unset):
+                posted_at = row["posted_at"]
+            elif patch.posted_at is None:
+                posted_at = None
+            else:
+                posted_at = patch.posted_at.isoformat()
+            attributes_raw = (
+                row["attributes_raw"]
+                if isinstance(patch.attributes_raw, Unset)
+                else patch.attributes_raw
+            )
+            if attributes_raw is None:
+                raise ValueError("attributes_raw cannot be None")
+            reply_to_msgno = (
+                row["reply_to_msgno"]
+                if isinstance(patch.reply_to_msgno, Unset)
+                else patch.reply_to_msgno
+            )
+            reply1st_msgno = (
+                row["reply1st_msgno"]
+                if isinstance(patch.reply1st_msgno, Unset)
+                else patch.reply1st_msgno
+            )
+            reply_next_msgno = (
+                row["reply_next_msgno"]
+                if isinstance(patch.reply_next_msgno, Unset)
+                else patch.reply_next_msgno
+            )
+            if isinstance(patch.provenance, Unset):
+                provenance_values = (
+                    row["source_type"],
+                    row["source_path"],
+                    row["source_id"],
+                    row["source_offset"],
+                )
+            elif patch.provenance is None:
+                provenance_values = (None, None, None, None)
+            else:
+                provenance_values = (
+                    patch.provenance.source_type,
+                    patch.provenance.source_path,
+                    patch.provenance.source_id,
+                    patch.provenance.source_offset,
+                )
+            if area["kind"] == "netmail":
+                if from_address is None:
+                    raise ValueError("netmail requires an origin address")
+                if to_address is None:
+                    raise ValueError("netmail requires a destination address")
+            connection.execute(
+                """
+                UPDATE messages SET
+                    from_name = ?, to_name = ?, subject = ?, body_text = ?,
+                    posted_at = ?, external_id = ?, attributes_raw = ?,
+                    from_address = ?, to_address = ?,
+                    reply_to_msgno = ?, reply1st_msgno = ?, reply_next_msgno = ?,
+                    source_type = ?, source_path = ?, source_id = ?, source_offset = ?,
+                    revision = revision + 1
+                WHERE id = ?
+                """,
+                (
+                    from_name,
+                    to_name,
+                    subject,
+                    body_text,
+                    posted_at,
+                    external_id,
+                    attributes_raw,
+                    format_address(from_address),
+                    format_address(to_address),
+                    reply_to_msgno,
+                    reply1st_msgno,
+                    reply_next_msgno,
+                    *provenance_values,
+                    row["id"],
+                ),
+            )
+            if not isinstance(patch.control_lines, Unset):
+                connection.execute(
+                    "DELETE FROM control_lines WHERE message_id = ?", (row["id"],)
+                )
+                connection.executemany(
+                    """
+                    INSERT INTO control_lines
+                        (message_id, position, name, value, raw)
+                    VALUES (?, ?, ?, ?, ?)
+                    """,
+                    (
+                        (row["id"], position, line.name, line.value, line.raw)
+                        for position, line in enumerate(patch.control_lines or ())
+                    ),
+                )
+            for kind, values in (
+                ("seen_by", patch.routing_seen_by),
+                ("path", patch.routing_path),
+            ):
+                if isinstance(values, Unset):
+                    continue
+                connection.execute(
+                    "DELETE FROM routing_entries WHERE message_id = ? AND kind = ?",
+                    (row["id"], kind),
+                )
+                connection.executemany(
+                    """
+                    INSERT INTO routing_entries (message_id, kind, position, value)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (
+                        (row["id"], kind, position, value)
+                        for position, value in enumerate(values or ())
+                    ),
+                )
+            if not isinstance(patch.reply_list, Unset):
+                connection.execute(
+                    "DELETE FROM reply_list_entries WHERE message_id = ?",
+                    (row["id"],),
+                )
+                connection.executemany(
+                    """
+                    INSERT INTO reply_list_entries (message_id, position, msgno)
+                    VALUES (?, ?, ?)
+                    """,
+                    (
+                        (row["id"], position, msgno)
+                        for position, msgno in enumerate(patch.reply_list or ())
+                    ),
+                )
+            stored = connection.execute(
+                "SELECT * FROM messages WHERE id = ?", (row["id"],)
+            ).fetchone()
+            assert stored is not None
+            revision = _revision(connection, stored, actual_identity)
+            connection.commit()
+            return WriteResult(
+                identity=actual_identity,
+                revision=revision,
+            )
+        except BaseException:
+            connection.rollback()
+            raise
+
+    def delete(
+        self,
+        identity: MessageIdentity,
+        expected_revision: RevisionToken,
+    ) -> MessageIdentity:
+        if self._closed:
+            raise WriterError("SQLite session is closed")
+        connection = self._connection
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            area = select_area(connection, self.area_code)
+            row = connection.execute(
+                """
+                SELECT * FROM messages
+                WHERE area_id = ? AND msgno = ? AND deleted_at IS NULL
+                """,
+                (area["id"], identity.msgno),
+            ).fetchone()
+            if row is None:
+                raise ConflictError("SQLite message is missing")
+            actual_identity = _identity(self.path, area["code"], identity.msgno)
+            actual_revision = _revision(connection, row, actual_identity)
+            if (
+                identity != actual_identity
+                or expected_revision.identity != actual_identity
+                or expected_revision != actual_revision
+            ):
+                raise ConflictError("SQLite message revision changed")
+            connection.execute(
+                """
+                UPDATE messages
+                SET deleted_at = ?, revision = revision + 1
+                WHERE id = ?
+                """,
+                (datetime.now(UTC).isoformat(), row["id"]),
+            )
+            connection.commit()
+            return actual_identity
+        except BaseException:
+            connection.rollback()
+            raise

golded_ftn_sqlite-1.0.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: golded-ftn-sqlite
+Version: 1.0.0
+Summary: Transactional SQLite message bases for FTN netmail and echomail
+Project-URL: Repository, https://github.com/golded-dev/golded-ftn-sqlite-python
+Project-URL: Issues, https://github.com/golded-dev/golded-ftn-sqlite-python/issues
+Project-URL: Changelog, https://github.com/golded-dev/golded-ftn-sqlite-python/blob/main/CHANGELOG.md
+Author: GoldED.dev contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: golded-ftn<2,>=1.4.0
+Description-Content-Type: text/markdown
+
+# golded-ftn-sqlite
+
+Repository: [`golded-ftn-sqlite-python`](https://github.com/golded-dev/golded-ftn-sqlite-python).
+Install version 1.0.0 with Python 3.12 or newer:
+
+```sh
+python -m pip install golded-ftn-sqlite==1.0.0
+```
+
+`golded-ftn-sqlite` stores FTN netmail and echomail in SQLite through the
+[`golded-ftn`](https://github.com/golded-dev/golded-ftn-python) message models.
+It requires Python 3.12 or newer.
+
+The format supports several areas in one database. The ordinary layout is still
+one database file per area: it maps cleanly to GoldED configuration, keeps backup
+and recovery local, and limits the blast radius when a disk has opinions.
+
+## Pipe with ftnt
+
+`ftnt` treats export envelopes as write input for every format, including SQLite:
+
+```sh
+ftnt create ./general.sqlite3 --format sqlite --area-code FIDO.GENERAL
+ftnt export ./general --format jam |
+  ftnt write ./general.sqlite3 --format sqlite --jsonl
+```
+
+## Use it
+
+```python
+from golded_ftn import FtnAddress, OutgoingMessage
+from golded_ftn_sqlite import (
+    AreaDefinition,
+    AreaKind,
+    SqliteDatabase,
+    SqliteReader,
+    SqliteWriter,
+)
+
+path = "fido-general.sqlite3"
+SqliteDatabase.create(
+    path,
+    area=AreaDefinition(
+        code="FIDO.GENERAL",
+        name="FidoNet General",
+        kind=AreaKind.ECHOMAIL,
+        default_origin=FtnAddress(zone=2, net=230, node=0),
+    ),
+)
+
+with SqliteWriter().open(path) as session:
+    result = session.append(
+        OutgoingMessage(
+            from_name="Alice",
+            to_name="All",
+            subject="Hello",
+            body_text="Stored transactionally.",
+        )
+    )
+    stored = session.read(result.identity.msgno)
+
+messages = tuple(SqliteReader().read(path))
+```
+
+When a database contains several areas, pass the area code to `SqliteReader` and
+`SqliteWriter`. Omitting it is allowed only for a single-area database. Message
+numbers are monotonic and local to each area.
+
+Netmail requires origin and destination addresses. The origin may come from the
+area's `default_origin`; the destination is always explicit. Echomail keeps ordered
+control lines, repeated unknown kludges, `SEEN-BY`, `PATH`, reply links and import
+provenance.
+
+Writer sessions provide `read`, `append`, `update` and soft `delete`. Updates and
+deletes require a revision token. The token covers the message row and its ordered
+control, routing and reply-list rows, including changes made by another SQLite
+client.
+
+## SQLite format
+
+Schema version 1 uses SQLite application ID `0x47465453` (`GFTS`), strict tables,
+foreign keys and WAL journaling. The schema is a public format contract:
+[docs/schema.md](docs/schema.md) documents identification, DDL, column semantics,
+allocation, soft delete, concurrency and backup so other packages or applications
+can implement the same database without this Python code.
+
+Do not copy an open WAL database as a lone `.sqlite3` file. Use SQLite's backup API
+or close/checkpoint it first.
+
+## Development
+
+```sh
+uv sync --python 3.14
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run python -m mypy.stubtest golded_ftn_sqlite
+uv build
+uv run twine check dist/*
+uv run python scripts/verify_distribution.py
+```
+

golded_ftn_sqlite-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+golded_ftn_sqlite/__init__.py,sha256=VvxVd-MmlJ9otYAl8-2OkrOvt3xI1DCVt7eCM5PUSJY,357
+golded_ftn_sqlite/database.py,sha256=4el8OCOITB1RHulX08fsNLBzFyqMb58zQYigr-C1CWM,8532
+golded_ftn_sqlite/models.py,sha256=FWNcvS6dgGxFStuCsUwVVvaR09hllSckK2HYxQFfK3g,827
+golded_ftn_sqlite/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+golded_ftn_sqlite/reader.py,sha256=qlTmSF8Cs-PVdSDPo6g-zH8nSanXyfd1C5sVOxIL0qw,5092
+golded_ftn_sqlite/writer.py,sha256=BwV_wzFuxd5lJnuUWelP5hHbAgYDI4q2VgIO3NFlw5U,18759
+golded_ftn_sqlite-1.0.0.dist-info/METADATA,sha256=6-zishzsePO-kpPsPtvJcq3YE66Jj7sDy5nq1jkp_e0,4064
+golded_ftn_sqlite-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+golded_ftn_sqlite-1.0.0.dist-info/licenses/LICENSE,sha256=MEbLGdaXThJPkf6b701rRnfChrYlR9AVpnpXRpbprk4,1080
+golded_ftn_sqlite-1.0.0.dist-info/RECORD,,

golded_ftn_sqlite-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

golded_ftn_sqlite-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoldED.dev contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.