# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause import uuid from datetime import UTC, datetime, timedelta from http import HTTPStatus from types import ModuleType from unittest.mock import Mock import pytest import sqlalchemy as sa from flask import Flask from flask.testing import FlaskClient from sqlalchemy.exc import IntegrityError from webmentions_ssg import db from webmentions_ssg.models.received import ReceivedWebmention from .helpers import ( SOURCE_URL, TARGET_URL, create_received_webmention, mock_endpoint_form, ) @pytest.fixture def views_module(app: Flask) -> ModuleType: _ = app from webmentions_ssg.views import endpoint as module return module def test_endpoint_only_accepts_post(client: FlaskClient) -> None: response = client.get("/endpoint") assert response.status_code == HTTPStatus.METHOD_NOT_ALLOWED def test_endpoint_returns_form_errors( client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch ) -> None: errors = {"source": ["Invalid source"]} mock_endpoint_form(views_module, monkeypatch, valid=False, errors=errors) response = client.post("/endpoint") assert response.status_code == HTTPStatus.BAD_REQUEST assert response.get_json() == errors def test_endpoint_explains_disallowed_target_hostname_without_storing_a_mention( app: Flask, client: FlaskClient ) -> None: response = client.post( "/endpoint", data={"source": SOURCE_URL, "target": "https://unconfigured.example/post"}, ) assert response.status_code == HTTPStatus.BAD_REQUEST assert response.get_json() == { "target": ["Target hostname is not in ALLOWED_TARGET_HOSTNAMES."] } with app.app_context(): assert db.session.scalar(sa.select(ReceivedWebmention)) is None def test_endpoint_creates_webmention( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: form = mock_endpoint_form(views_module, monkeypatch, valid=True) verify_webmention = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify_webmention) response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED form.validate_on_submit.assert_called_once_with() with app.app_context(): webmention = db.session.scalar(sa.select(ReceivedWebmention)) assert webmention is not None assert webmention.source == SOURCE_URL assert webmention.target == TARGET_URL assert webmention.status == "received" assert webmention.failure_reason is None identifier = webmention.uuid assert response.headers["Location"].endswith(str(identifier)) verify_webmention.assert_called_once_with(identifier) def test_endpoint_is_idempotent( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: mock_endpoint_form(views_module, monkeypatch, valid=True) verify_webmention = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify_webmention) first_response = client.post("/endpoint") second_response = client.post("/endpoint") assert first_response.status_code == HTTPStatus.CREATED assert second_response.status_code == HTTPStatus.CREATED assert first_response.headers["Location"] == second_response.headers["Location"] with app.app_context(): webmentions = db.session.scalars(sa.select(ReceivedWebmention)).all() assert len(webmentions) == 1 webmention = webmentions[0] assert webmention.source == SOURCE_URL assert webmention.target == TARGET_URL assert webmention.status == "received" assert webmention.failure_reason is None identifier = webmention.uuid verify_webmention.assert_called_once_with(identifier) def test_resending_resets_failure_state( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: mock_endpoint_form(views_module, monkeypatch, valid=True) verify_webmention = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify_webmention) with app.app_context(): existing = ReceivedWebmention( uuid=uuid.uuid7(), source=SOURCE_URL, target=TARGET_URL, status="failed", failure_reason="Previous failure", updated_at=datetime.now(UTC) - timedelta(minutes=11), ) db.session.add(existing) db.session.commit() identifier = existing.uuid response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED with app.app_context(): webmention = db.session.get(ReceivedWebmention, identifier) assert webmention is not None assert webmention.status == "received" assert webmention.failure_reason is None verify_webmention.assert_called_once_with(identifier) def test_status_returns_404_for_unknown_webmention(client: FlaskClient) -> None: response = client.get(f"/status/{uuid.uuid7()}") assert response.status_code == HTTPStatus.NOT_FOUND def test_status_displays_webmention(app: Flask, client: FlaskClient) -> None: identifier = create_received_webmention( app, status="failed", failure_reason="Verification failed" ) response = client.get(f"/status/{identifier}") assert response.status_code == HTTPStatus.OK html = response.get_data(as_text=True) assert SOURCE_URL in html assert TARGET_URL in html assert "failed" in html assert "Verification failed" in html @pytest.mark.parametrize(("age_minutes", "reopened"), [(0, False), (11, True)]) def test_endpoint_recovers_from_concurrent_insert( client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, age_minutes: int, reopened: bool, ) -> None: mock_endpoint_form(views_module, monkeypatch, valid=True) competing_identifier = uuid.uuid7() competing_webmention = ReceivedWebmention( uuid=competing_identifier, source=SOURCE_URL, target=TARGET_URL, status="failed", failure_reason="Competing request failed", updated_at=datetime.now(UTC) - timedelta(minutes=age_minutes), ) initial_result = Mock() initial_result.scalar_one_or_none.return_value = None competing_result = Mock() competing_result.scalar_one_or_none.return_value = competing_webmention update_result = Mock(rowcount=int(reopened)) execute = Mock(side_effect=[initial_result, competing_result, update_result]) add = Mock() rollback = Mock() commit = Mock( side_effect=[ IntegrityError( "INSERT INTO received_webmention ...", {}, Exception("duplicate source/target"), ), None, ] ) verify_webmention = Mock() monkeypatch.setattr(views_module.db.session, "execute", execute) monkeypatch.setattr(views_module.db.session, "add", add) monkeypatch.setattr(views_module.db.session, "rollback", rollback) monkeypatch.setattr(views_module.db.session, "commit", commit) monkeypatch.setattr(views_module, "verify_webmention", verify_webmention) response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED assert response.headers["Location"].endswith(f"/status/{competing_identifier}") assert execute.call_count == 3 assert add.call_count == (2 if reopened else 1) assert rollback.call_count == (1 if reopened else 2) assert commit.call_count == (2 if reopened else 1) if reopened: verify_webmention.assert_called_once_with(competing_identifier) else: verify_webmention.assert_not_called() def test_endpoint_rejects_digest_collision( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: form = mock_endpoint_form(views_module, monkeypatch, valid=True) verify = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify) with app.app_context(): existing = ReceivedWebmention( uuid=uuid.uuid7(), source=SOURCE_URL, target=TARGET_URL ) db.session.add(existing) db.session.commit() digest = existing.source_target_digest form.source.data = "https://source.example/different" monkeypatch.setattr( views_module, "source_target_digest", lambda source, target: digest ) response = client.post("/endpoint") assert response.status_code == HTTPStatus.CONFLICT assert response.get_json() == {"error": "Webmention URL fingerprint conflict"} verify.assert_not_called() with app.app_context(): assert db.session.scalar(sa.select(sa.func.count(ReceivedWebmention.uuid))) == 1 def test_endpoint_rate_limits_requests_per_ip( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: app.config["ENDPOINT_RATE_LIMIT"] = "2/minute" form = mock_endpoint_form(views_module, monkeypatch, valid=True) verify = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify) responses = [] for index in range(3): form.source.data = f"https://source.example/post-{index}" responses.append( client.post("/endpoint", environ_overrides={"REMOTE_ADDR": "192.0.2.10"}) ) assert [r.status_code for r in responses] == [ HTTPStatus.CREATED, HTTPStatus.CREATED, HTTPStatus.TOO_MANY_REQUESTS, ] assert verify.call_count == 2 with app.app_context(): count = db.session.scalar( sa.select(sa.func.count()).select_from(ReceivedWebmention) ) assert count == 2 def test_endpoint_rate_limit_distinguishes_clients_behind_trusted_proxy( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: from werkzeug.middleware.proxy_fix import ProxyFix app.config["ENDPOINT_RATE_LIMIT"] = "1/minute" app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1) form = mock_endpoint_form(views_module, monkeypatch, valid=True) monkeypatch.setattr(views_module, "verify_webmention", Mock()) def attempt(client_ip: str, index: int) -> int: form.source.data = f"https://source.example/proxy-post-{index}" return client.post( "/endpoint", environ_overrides={"REMOTE_ADDR": "192.0.2.200"}, headers={"X-Forwarded-For": client_ip}, ).status_code assert attempt("198.51.100.11", 0) == HTTPStatus.CREATED assert attempt("198.51.100.11", 1) == HTTPStatus.TOO_MANY_REQUESTS assert attempt("198.51.100.12", 2) == HTTPStatus.CREATED def test_endpoint_global_rate_limit( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: app.config["ENDPOINT_GLOBAL_RATE_LIMIT"] = "2/minute" form = mock_endpoint_form(views_module, monkeypatch, valid=True) verify = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify) responses = [] for index in range(3): form.source.data = f"https://source.example/post-{index}" responses.append( client.post( "/endpoint", environ_overrides={"REMOTE_ADDR": f"192.0.2.{index + 1}"} ) ) assert [r.status_code for r in responses] == [ HTTPStatus.CREATED, HTTPStatus.CREATED, HTTPStatus.TOO_MANY_REQUESTS, ] assert verify.call_count == 2 def test_endpoint_recent_duplicate_does_not_reverify( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: mock_endpoint_form(views_module, monkeypatch, valid=True) verify = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify) with app.app_context(): webmention = ReceivedWebmention( uuid=uuid.uuid7(), source=SOURCE_URL, target=TARGET_URL, status="failed", failure_reason="Previous failure", ) db.session.add(webmention) db.session.commit() identifier = webmention.uuid response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED assert response.headers["Location"].endswith(str(identifier)) with app.app_context(): stored = db.session.get(ReceivedWebmention, identifier) assert stored is not None assert stored.status == "failed" assert stored.failure_reason == "Previous failure" verify.assert_not_called() def test_endpoint_reverifies_after_cooldown( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: mock_endpoint_form(views_module, monkeypatch, valid=True) verify = Mock() monkeypatch.setattr(views_module, "verify_webmention", verify) with app.app_context(): webmention = ReceivedWebmention( uuid=uuid.uuid7(), source=SOURCE_URL, target=TARGET_URL, status="failed", failure_reason="Previous failure", recovery_attempts=3, updated_at=datetime.now(UTC) - timedelta(minutes=11), ) db.session.add(webmention) db.session.commit() identifier = webmention.uuid response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED with app.app_context(): stored = db.session.get(ReceivedWebmention, identifier) assert stored is not None assert stored.status == "received" assert stored.failure_reason is None assert stored.recovery_attempts == 0 verify.assert_called_once_with(identifier) def test_endpoint_rejects_request_bodies_over_configured_maximum( app: Flask, client: FlaskClient ) -> None: app.config["MAX_CONTENT_LENGTH"] = 128 response = client.post( "/endpoint", data={"source": SOURCE_URL + "x" * 150, "target": TARGET_URL} ) assert response.status_code == HTTPStatus.CONTENT_TOO_LARGE def test_endpoint_rejects_bad_url_before_inserting_row( app: Flask, client: FlaskClient, monkeypatch: pytest.MonkeyPatch ) -> None: from webmentions_ssg.views import endpoint as views verify_webmention = Mock() monkeypatch.setattr(views, "verify_webmention", verify_webmention) response = client.post( "/endpoint", data={"source": "http://ex☃mple.test/", "target": TARGET_URL} ) assert response.status_code == HTTPStatus.BAD_REQUEST assert "source" in response.get_json() verify_webmention.assert_not_called() with app.app_context(): assert ( db.session.scalar( sa.select(sa.func.count()).select_from(ReceivedWebmention) ) == 0 ) def test_endpoint_records_initial_and_resubmission_events( app: Flask, client: FlaskClient, views_module: ModuleType, monkeypatch: pytest.MonkeyPatch, ) -> None: from webmentions_ssg.models.received import ReceivedWebmentionStatusEvent mock_endpoint_form(views_module, monkeypatch, valid=True) monkeypatch.setattr(views_module, "verify_webmention", Mock()) response = client.post("/endpoint") assert response.status_code == HTTPStatus.CREATED with app.app_context(): mention = db.session.scalar(sa.select(ReceivedWebmention)) assert mention is not None identifier = mention.uuid events = db.session.scalars( sa.select(ReceivedWebmentionStatusEvent).where( ReceivedWebmentionStatusEvent.webmention_uuid == identifier ) ).all() assert [event.action for event in events] == ["Received submission"] mention.status = "failed" mention.failure_reason = "Previous failure" mention.updated_at = datetime.now(UTC) - timedelta(minutes=11) db.session.commit() assert client.post("/endpoint").status_code == HTTPStatus.CREATED with app.app_context(): events = db.session.scalars( sa.select(ReceivedWebmentionStatusEvent) .where(ReceivedWebmentionStatusEvent.webmention_uuid == identifier) .order_by(ReceivedWebmentionStatusEvent.id) ).all() assert [event.action for event in events] == [ "Received submission", "Resubmitted after cooldown", ]