# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause import logging from collections.abc import Iterator from pathlib import Path from unittest.mock import patch from uuid import UUID import pytest import sqlalchemy as sa from alembic.script import ScriptDirectory from flask import Flask from flask_migrate import downgrade as migrate_downgrade from flask_migrate import upgrade as migrate_upgrade from sqlalchemy import inspect from sqlalchemy.exc import IntegrityError from webmentions_ssg import create_app, db, migrate from webmentions_ssg.config import TestingConfig from webmentions_ssg.models import ReceivedWebmention, ReceivedWebmentionStatus, User def test_cli_groups_are_registered(app: Flask) -> None: commands = app.cli.commands assert {"users", "mail"}.issubset(commands) @pytest.fixture def database_app(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Flask]: monkeypatch.chdir(tmp_path) class DatabaseTestingConfig(TestingConfig): LOG_FILE = str(tmp_path / "database-cli.log") SQLALCHEMY_DATABASE_URI = f"sqlite:///{tmp_path / 'database.sqlite'}" app = create_app(DatabaseTestingConfig) yield app with app.app_context(): db.session.remove() db.engine.dispose() def _script_directory() -> ScriptDirectory: """Open the migration scripts configured for this application. :returns: Configured Alembic script directory for the application. """ return ScriptDirectory(str(migrate.directory)) def _head_revision(app: Flask) -> str: with app.app_context(): revision = _script_directory().get_current_head() assert revision is not None, "Expected a migration head" return revision def _database_revision(app: Flask) -> str: with app.app_context(), db.engine.connect() as connection: return connection.execute( sa.text("SELECT version_num FROM alembic_version") ).scalar_one() def test_database_commands_are_registered_without_hiding_flask_migrate( database_app: Flask, ) -> None: runner = database_app.test_cli_runner() result = runner.invoke(args=["db", "--help"]) assert result.exit_code == 0, result.output assert "create-db" in result.output assert "upgrade" in result.output result = runner.invoke(args=["migrate", "--help"]) assert result.exit_code == 0, result.output assert "downgrade" in result.output assert "revision" in result.output def test_create_db_builds_schema_and_records_latest_migration( database_app: Flask, ) -> None: result = database_app.test_cli_runner().invoke(args=["db", "create-db"]) assert result.exit_code == 0, result.output assert "Database created" in result.output assert _database_revision(database_app) == _head_revision(database_app) with database_app.app_context(): inspector = inspect(db.engine) table_names = set(inspector.get_table_names()) columns = { column["name"] for column in inspector.get_columns("sent_webmentions") } received_columns = { column["name"] for column in inspector.get_columns("received_webmentions") } received_indexes = { index["name"] for index in inspector.get_indexes("received_webmentions") } assert { "alembic_version", "users", "received_webmentions", "source_documents", } <= table_names assert "sources" not in table_names assert { "source_uuid", "linked", "webmention_endpoint", "endpoint_response_status", } <= columns assert "source_target_digest" in received_columns assert {"attempt_count", "next_retry_at"} <= columns assert "recovery_attempts" in received_columns assert "ix_received_webmentions_status_updated_at" in received_indexes def test_create_db_refuses_existing_database_without_modifying_it( database_app: Flask, ) -> None: runner = database_app.test_cli_runner() assert runner.invoke(args=["db", "create-db"]).exit_code == 0 revision_before = _database_revision(database_app) result = runner.invoke(args=["db", "create-db"]) assert result.exit_code != 0 assert "already contains tables" in result.output assert _database_revision(database_app) == revision_before def test_create_db_refuses_unversioned_existing_tables(database_app: Flask) -> None: with database_app.app_context(), db.engine.begin() as connection: connection.execute(sa.text("CREATE TABLE legacy_data (id INTEGER PRIMARY KEY)")) result = database_app.test_cli_runner().invoke(args=["db", "create-db"]) assert result.exit_code != 0 assert "already contains tables" in result.output with database_app.app_context(): assert "legacy_data" in inspect(db.engine).get_table_names() assert "alembic_version" not in inspect(db.engine).get_table_names() def test_upgrade_requires_an_initialized_database(database_app: Flask) -> None: result = database_app.test_cli_runner().invoke(args=["db", "upgrade"]) assert result.exit_code != 0 assert "flask db create-db" in result.output def test_upgrade_refuses_unversioned_existing_database(database_app: Flask) -> None: with database_app.app_context(), db.engine.begin() as connection: connection.execute(sa.text("CREATE TABLE legacy_data (id INTEGER PRIMARY KEY)")) result = database_app.test_cli_runner().invoke(args=["db", "upgrade"]) assert result.exit_code != 0 assert "No Flask-Migrate revision table" in result.output with database_app.app_context(): assert "legacy_data" in inspect(db.engine).get_table_names() def test_upgrade_applies_pending_migrations_and_preserves_data( database_app: Flask, ) -> None: # Start with the first migration, as if this were an older deployment. with database_app.app_context(): base_revision = _script_directory().get_base() assert base_revision is not None assert base_revision != _head_revision(database_app) migrate_upgrade(revision=base_revision) with db.engine.begin() as connection: connection.execute( sa.text( "INSERT INTO users (username, password_hash) " "VALUES (:username, :password_hash)" ), {"username": "existing-user", "password_hash": "existing-hash"}, ) result = database_app.test_cli_runner().invoke(args=["db", "upgrade"]) assert result.exit_code == 0, result.output assert "Database upgraded" in result.output assert _database_revision(database_app) == _head_revision(database_app) with database_app.app_context(), db.engine.connect() as connection: assert ( connection.execute( sa.text("SELECT password_hash FROM users WHERE username = :username"), {"username": "existing-user"}, ).scalar_one() == "existing-hash" ) assert "sent_webmentions" in inspect(connection).get_table_names() def test_upgrade_is_safe_to_run_when_already_current(database_app: Flask) -> None: runner = database_app.test_cli_runner() assert runner.invoke(args=["db", "create-db"]).exit_code == 0 result = runner.invoke(args=["db", "upgrade"]) assert result.exit_code == 0, result.output assert _database_revision(database_app) == _head_revision(database_app) def test_create_db_does_not_report_success_when_migration_fails( database_app: Flask, monkeypatch: pytest.MonkeyPatch ) -> None: import webmentions_ssg.cli as database_cli def fail_upgrade() -> None: raise RuntimeError("simulated migration failure") monkeypatch.setattr(database_cli, "migrate_upgrade", fail_upgrade) result = database_app.test_cli_runner().invoke(args=["db", "create-db"]) assert result.exit_code != 0 assert isinstance(result.exception, RuntimeError) assert "Database created" not in result.output def test_create_db_preserves_logging( database_app: Flask, caplog: pytest.LogCaptureFixture ) -> None: with caplog.at_level(logging.WARNING): result = database_app.test_cli_runner().invoke(args=["db", "create-db"]) assert result.exit_code == 0, result.output database_app.logger.warning("Logging still works after migration") assert "Logging still works after migration" in caplog.text def test_upgrade_backfills_portable_digest_for_existing_received_rows( database_app: Flask, ) -> None: """Upgrade a pre-fingerprint SQLite database without losing historical rows. :param database_app: Flask application connected to the legacy SQLite schema. """ from webmentions_ssg.models import source_target_digest with database_app.app_context(): migrate_upgrade(revision="c0272f25ce17") with db.engine.begin() as connection: connection.execute( sa.text( "INSERT INTO received_webmentions " "(uuid, source, target, status, updated_at) " "VALUES (:uuid, :source, :target, :status, :updated_at)" ), { "uuid": "0" * 31 + "1", "source": "https://source.example/old", "target": "https://dennisfink.me/target", "status": "verified", "updated_at": "2026-01-01 00:00:00", }, ) migrate_upgrade() with db.engine.connect() as connection: result = connection.execute( sa.text( "SELECT source, target, status, source_target_digest " "FROM received_webmentions" ) ).one() assert result.status == "verified" recovery_attempts = connection.execute( sa.text("SELECT recovery_attempts FROM received_webmentions") ).scalar_one() assert recovery_attempts == 0 assert result.source_target_digest == source_target_digest( result.source, result.target ) constraints = inspect(connection).get_unique_constraints( "received_webmentions" ) assert any( constraint["column_names"] == ["source_target_digest"] for constraint in constraints ) def test_upgrade_converts_received_status_without_losing_rows( database_app: Flask, ) -> None: """Verify that status rows survive conversion to the non-native Enum. :param database_app: Flask application connected to the legacy SQLite schema. """ identifier = "0" * 31 + "1" with database_app.app_context(): migrate_upgrade(revision="e62b1a7c4d90") with db.engine.begin() as connection: connection.execute( sa.text( "INSERT INTO received_webmentions " "(uuid, source, target, url_digest, status, updated_at) " "VALUES (:uuid, :source, :target, :url_digest, :status, :updated_at)" ), { "uuid": identifier, "source": "https://source.example/old", "target": "https://dennisfink.me/target", "url_digest": "0" * 64, "status": "verifying", "updated_at": "2026-01-01 00:00:00", }, ) migrate_upgrade() with db.engine.connect() as connection: columns = { column["name"]: column for column in inspect(connection).get_columns("received_webmentions") } assert isinstance(columns["status"]["type"], sa.String) assert columns["status"]["type"].length == len("source_removed") assert ( connection.execute( sa.text("SELECT status FROM received_webmentions") ).scalar_one() == "verifying" ) mention = db.session.get(ReceivedWebmention, UUID(hex=identifier)) assert mention is not None assert mention.status is ReceivedWebmentionStatus.VERIFYING def test_name_migration_round_trips_existing_webmention_rows( database_app: Flask, ) -> None: """Keep persisted statuses, UUID foreign keys and unique constraints intact.""" source_uuid = "0" * 31 + "1" sent_uuid = "0" * 31 + "2" received_uuid = "0" * 31 + "3" with database_app.app_context(): migrate_upgrade(revision="7c38bb1a935e") with db.engine.begin() as connection: connection.execute( sa.text( "INSERT INTO sources " "(uuid, path, url, content_hash, revision, " "last_seen_at, revised_at) " "VALUES (:uuid, 'post/index.html', 'https://site.example/post', " ":hash, 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)" ), {"uuid": source_uuid, "hash": "0" * 32}, ) connection.execute( sa.text( "INSERT INTO sent_webmentions " "(uuid, source_id, target, target_digest, active, desired_revision, " "status, endpoint, response_status, attempt_count) " "VALUES (:uuid, :source_id, 'https://target.example/', :digest, " "1, 1, 'unsupported', 'https://target.example/webmention', 202, 0)" ), {"uuid": sent_uuid, "source_id": source_uuid, "digest": "1" * 64}, ) connection.execute( sa.text( "INSERT INTO received_webmentions " "(uuid, source, target, url_digest, status, updated_at) " "VALUES (:uuid, 'https://source.example/', " "'https://site.example/', :digest, 'deleted', CURRENT_TIMESTAMP)" ), {"uuid": received_uuid, "digest": "2" * 64}, ) migrate_upgrade() with db.engine.connect() as connection: inspector = inspect(connection) assert "source_documents" in inspector.get_table_names() assert "sources" not in inspector.get_table_names() assert ( connection.execute( sa.text("SELECT status FROM received_webmentions") ).scalar_one() == "source_removed" ) sent_row = connection.execute( sa.text( "SELECT source_uuid, status, linked, webmention_endpoint, " "endpoint_response_status FROM sent_webmentions" ) ).one() assert sent_row == ( source_uuid, "no_endpoint", 1, "https://target.example/webmention", 202, ) assert any( constraint["column_names"] == ["source_target_digest"] for constraint in inspector.get_unique_constraints( "received_webmentions" ) ) assert any( constraint["column_names"] == ["source_uuid", "target_digest"] for constraint in inspector.get_unique_constraints("sent_webmentions") ) assert any( foreign_key["constrained_columns"] == ["source_uuid"] and foreign_key["referred_table"] == "source_documents" for foreign_key in inspector.get_foreign_keys("sent_webmentions") ) migrate_downgrade(revision="7c38bb1a935e") with db.engine.connect() as connection: inspector = inspect(connection) assert "sources" in inspector.get_table_names() assert ( connection.execute( sa.text("SELECT status FROM received_webmentions") ).scalar_one() == "deleted" ) assert ( connection.execute( sa.text("SELECT status FROM sent_webmentions") ).scalar_one() == "unsupported" ) assert any( foreign_key["constrained_columns"] == ["source_id"] and foreign_key["referred_table"] == "sources" for foreign_key in inspector.get_foreign_keys("sent_webmentions") ) def test_mail_cli_sends_to_configured_notification_email(app: Flask) -> None: app.config.update( DIGEST_EMAIL="owner@example.com", MAIL_DEFAULT_SENDER="sender@example.com" ) with patch("webmentions_ssg.mail.send") as send: result = app.test_cli_runner().invoke(args=["mail", "test"]) assert result.exit_code == 0, result.output send.assert_called_once() message = send.call_args.args[0] assert message.sender == "sender@example.com" assert message.recipients == ["owner@example.com"] assert "test email" in message.subject.lower() assert "outgoing mail configuration" in message.body assert "Test email sent to owner@example.com." in result.output def test_mail_cli_overrides_configured_recipient(app: Flask) -> None: app.config.update( DIGEST_EMAIL="owner@example.com", MAIL_DEFAULT_SENDER="sender@example.com" ) with patch("webmentions_ssg.mail.send") as send: result = app.test_cli_runner().invoke( args=["mail", "test", "--to", "other@example.com"] ) assert result.exit_code == 0, result.output send.assert_called_once() assert send.call_args.args[0].recipients == ["other@example.com"] def test_mail_cli_requires_recipient(app: Flask) -> None: app.config.update(DIGEST_EMAIL=None, MAIL_DEFAULT_SENDER="sender@example.com") with patch("webmentions_ssg.mail.send") as send: result = app.test_cli_runner().invoke(args=["mail", "test"]) assert result.exit_code != 0 assert "Set DIGEST_EMAIL or pass --to" in result.output send.assert_not_called() def test_mail_cli_requires_default_sender(app: Flask) -> None: app.config.update(DIGEST_EMAIL="owner@example.com", MAIL_DEFAULT_SENDER=None) with patch("webmentions_ssg.mail.send") as send: result = app.test_cli_runner().invoke(args=["mail", "test"]) assert result.exit_code != 0 assert "MAIL_DEFAULT_SENDER is not configured" in result.output send.assert_not_called() def test_mail_cli_reports_smtp_failure(app: Flask) -> None: app.config.update( DIGEST_EMAIL="owner@example.com", MAIL_DEFAULT_SENDER="sender@example.com" ) with patch( "webmentions_ssg.mail.send", side_effect=ConnectionError("SMTP unavailable") ) as send: result = app.test_cli_runner().invoke(args=["mail", "test"]) assert result.exit_code != 0 assert "Could not send test email: SMTP unavailable" in result.output send.assert_called_once() def _add_user(app: Flask, username: str, password: str = "original") -> None: """Persist a user using the same model as the CLI. :param app: Flask application in which to create the user. :param username: Username to persist. :param password: Plain-text password for the test user. """ with app.app_context(): db.session.add(User(username=username, password=password)) db.session.commit() def _get_user(app: Flask, username: str) -> User | None: with app.app_context(): return db.session.scalar(sa.select(User).where(User.username == username)) def test_users_cli_help_lists_management_commands(app: Flask) -> None: result = app.test_cli_runner().invoke(args=["users", "--help"]) assert result.exit_code == 0, result.output for command in ("create", "list", "set-password", "delete"): assert command in result.output def test_users_cli_create_with_prompts_hashes_password(app: Flask) -> None: result = app.test_cli_runner().invoke( args=["users", "create"], input="alice\nmy new secret passphrase\nmy new secret passphrase\n", ) assert result.exit_code == 0, result.output assert "Created user 'alice'." in result.output assert "my new secret passphrase" not in result.output user = _get_user(app, "alice") assert user is not None assert user.check_password("my new secret passphrase") assert user.password_hash != "my new secret passphrase" def test_users_cli_create_with_username_option(app: Flask) -> None: result = app.test_cli_runner().invoke( args=["users", "create", "--username", "alice"], input="my new secret passphrase\nmy new secret passphrase\n", ) assert result.exit_code == 0, result.output assert _get_user(app, "alice") is not None def test_users_cli_create_rejects_duplicate(app: Flask) -> None: _add_user(app, "alice") result = app.test_cli_runner().invoke( args=[ "users", "create", "--username", "alice", "--password", "a stronger duplicate password", ] ) assert result.exit_code != 0 assert "User 'alice' already exists." in result.output user = _get_user(app, "alice") assert user is not None assert user.check_password("original") @pytest.mark.parametrize("username", ["", " "]) def test_users_cli_create_rejects_invalid_username(app: Flask, username: str) -> None: result = app.test_cli_runner().invoke( args=[ "users", "create", "--username", username, "--password", "a strong password for testing", ] ) assert result.exit_code != 0 assert "Username must not" in result.output def test_users_cli_create_rejects_empty_password(app: Flask) -> None: result = app.test_cli_runner().invoke( args=["users", "create", "--username", "alice", "--password", ""] ) assert result.exit_code != 0 assert "Password must not be empty." in result.output assert _get_user(app, "alice") is None def test_users_cli_list_empty(app: Flask) -> None: result = app.test_cli_runner().invoke(args=["users", "list"]) assert result.exit_code == 0, result.output assert "No users found." in result.output def test_users_cli_list_is_sorted_and_excludes_passwords(app: Flask) -> None: _add_user(app, "zoe") _add_user(app, "alice") result = app.test_cli_runner().invoke(args=["users", "list"]) assert result.exit_code == 0, result.output lines = result.output.splitlines() assert lines[0] == "ID\tUSERNAME" assert lines[1].endswith("\talice") assert lines[2].endswith("\tzoe") assert "original" not in result.output def test_users_cli_set_password_updates_hash(app: Flask) -> None: _add_user(app, "alice") old_hash = _get_user(app, "alice").password_hash # type: ignore[union-attr] result = app.test_cli_runner().invoke( args=["users", "set-password", "alice"], input="a long replacement passphrase\na long replacement passphrase\n", ) assert result.exit_code == 0, result.output assert "Updated password for user 'alice'." in result.output assert "a long replacement passphrase" not in result.output user = _get_user(app, "alice") assert user is not None assert user.password_hash != old_hash assert not user.check_password("original") assert user.check_password("a long replacement passphrase") def test_users_cli_set_password_missing_user(app: Flask) -> None: result = app.test_cli_runner().invoke( args=[ "users", "set-password", "missing", "--password", "a long replacement passphrase", ] ) assert result.exit_code != 0 assert "User 'missing' does not exist." in result.output def test_users_cli_set_password_rejects_empty_password(app: Flask) -> None: _add_user(app, "alice") result = app.test_cli_runner().invoke( args=["users", "set-password", "alice", "--password", ""] ) assert result.exit_code != 0 assert "Password must not be empty." in result.output user = _get_user(app, "alice") assert user is not None assert user.check_password("original") def test_users_cli_delete_with_confirmation(app: Flask) -> None: _add_user(app, "alice") result = app.test_cli_runner().invoke( args=["users", "delete", "alice"], input="y\n" ) assert result.exit_code == 0, result.output assert "Delete user 'alice'?" in result.output assert "Deleted user 'alice'." in result.output assert _get_user(app, "alice") is None def test_users_cli_delete_confirmation_rejected(app: Flask) -> None: _add_user(app, "alice") result = app.test_cli_runner().invoke( args=["users", "delete", "alice"], input="n\n" ) assert result.exit_code != 0 assert "Aborted" in result.output assert _get_user(app, "alice") is not None def test_users_cli_delete_yes_only_deletes_target(app: Flask) -> None: _add_user(app, "alice") _add_user(app, "bob") result = app.test_cli_runner().invoke(args=["users", "delete", "alice", "--yes"]) assert result.exit_code == 0, result.output assert "Deleted user 'alice'." in result.output assert _get_user(app, "alice") is None assert _get_user(app, "bob") is not None def test_users_cli_delete_missing_user(app: Flask) -> None: result = app.test_cli_runner().invoke(args=["users", "delete", "missing", "-y"]) assert result.exit_code != 0 assert "User 'missing' does not exist." in result.output def test_users_cli_delete_missing_blank_username(app: Flask) -> None: result = app.test_cli_runner().invoke(args=["users", "delete", " ", "--yes"]) assert result.exit_code != 0 assert "User ' ' does not exist." in result.output def test_users_cli_can_manage_legacy_whitespace_username(app: Flask) -> None: _add_user(app, " alice ") reset = app.test_cli_runner().invoke( args=[ "users", "set-password", " alice ", "--password", "a long replacement passphrase", ] ) assert reset.exit_code == 0, reset.output user = _get_user(app, " alice ") assert user is not None assert user.check_password("a long replacement passphrase") deleted = app.test_cli_runner().invoke(args=["users", "delete", " alice ", "--yes"]) assert deleted.exit_code == 0, deleted.output assert _get_user(app, " alice ") is None def test_users_cli_create_rolls_back_on_duplicate_race(app: Flask) -> None: database_error = IntegrityError("INSERT", {}, Exception("duplicate")) with app.app_context(): with ( patch.object(db.session, "commit", side_effect=database_error), patch.object(db.session, "rollback") as rollback, ): result = app.test_cli_runner().invoke( args=[ "users", "create", "--username", "alice", "--password", "a long secret for testing", ] ) rollback.assert_called_once() assert result.exit_code != 0 assert "User 'alice' already exists." in result.output @pytest.mark.parametrize( ("password", "error"), [ ("short", "at least 8 characters"), ("good passphrase with\tab", "control characters"), ("good passphrase with\x80c1", "control characters"), ], ) @pytest.mark.parametrize("operation", ["create", "set-password"]) def test_users_cli_enforces_password_policy( app: Flask, password: str, error: str, operation: str ) -> None: _add_user(app, "existing") if operation == "create": command = ["users", "create", "--username", "new"] else: command = ["users", "set-password", "existing"] result = app.test_cli_runner().invoke(args=[*command, "--password", password]) assert result.exit_code != 0 assert error in result.output assert _get_user(app, "new") is None existing = _get_user(app, "existing") assert existing is not None and existing.check_password("original") def test_users_cli_accepts_long_unicode_passphrase(app: Flask) -> None: passphrase = "🦊 several words of my passphrase 🪁" result = app.test_cli_runner().invoke( args=["users", "create", "--username", "alice", "--password", passphrase] ) assert result.exit_code == 0, result.output user = _get_user(app, "alice") assert user is not None and user.check_password(passphrase) @pytest.mark.parametrize("passphrase", ["12345678", " " * 8, "🦊" + "a" * 1025]) def test_users_cli_accepts_minimum_whitespace_and_unbounded_passwords( app: Flask, passphrase: str ) -> None: result = app.test_cli_runner().invoke( args=["users", "create", "--username", "alice", "--password", passphrase] ) assert result.exit_code == 0, result.output user = _get_user(app, "alice") assert user is not None and user.check_password(passphrase)