aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg
diff options
context:
space:
mode:
authorDennis Fink2026-11-15 20:42:20 +0100
committerDennis Fink2026-11-15 20:42:20 +0100
commit509d93b2976e353d29441a7a7b7e78ca466dc4fd (patch)
tree753e637aefabd4293f808addbf9c310eaf0aa552 /webmentions_ssg
parentc74feda222745ab7cca8993df83d9ea5f9d07e5b (diff)
downloadwebmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.tar.gz
webmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.zip
refactor(core)!: standardize application terminology
Rename configuration keys, task helpers, forms, network utilities, and view endpoints to make their responsibilities and domains more explicit. Align source-management routes and templates with the new terminology and rename the target-matching module and related task abstractions consistently. BREAKING CHANGE: configuration keys have been renamed and sent-source routes move from `/sent` to `/sources`, with corresponding blueprint endpoint changes.
Diffstat (limited to 'webmentions_ssg')
-rw-r--r--webmentions_ssg/__init__.py21
-rw-r--r--webmentions_ssg/auth.py12
-rw-r--r--webmentions_ssg/cli.py28
-rw-r--r--webmentions_ssg/config.py40
-rw-r--r--webmentions_ssg/forms.py30
-rw-r--r--webmentions_ssg/net.py62
-rw-r--r--webmentions_ssg/tasks/consumer.py6
-rw-r--r--webmentions_ssg/tasks/discovery.py62
-rw-r--r--webmentions_ssg/tasks/extension.py58
-rw-r--r--webmentions_ssg/tasks/json_serializer.py2
-rw-r--r--webmentions_ssg/tasks/notifications.py6
-rw-r--r--webmentions_ssg/tasks/receiver.py72
-rw-r--r--webmentions_ssg/tasks/scanner.py48
-rw-r--r--webmentions_ssg/tasks/sender.py78
-rw-r--r--webmentions_ssg/tasks/source_parser.py53
-rw-r--r--webmentions_ssg/tasks/target_matching.py (renamed from webmentions_ssg/tasks/mentions.py)0
-rw-r--r--webmentions_ssg/templates/base.html15
-rw-r--r--webmentions_ssg/templates/received.html4
-rw-r--r--webmentions_ssg/templates/sent.html4
-rw-r--r--webmentions_ssg/templates/sent_source.html4
-rw-r--r--webmentions_ssg/views/__init__.py6
-rw-r--r--webmentions_ssg/views/admin.py78
-rw-r--r--webmentions_ssg/views/blueprint.py2
-rw-r--r--webmentions_ssg/views/endpoint.py38
-rw-r--r--webmentions_ssg/views/session.py22
25 files changed, 401 insertions, 350 deletions
diff --git a/webmentions_ssg/__init__.py b/webmentions_ssg/__init__.py
index 223f35d..8e87485 100644
--- a/webmentions_ssg/__init__.py
+++ b/webmentions_ssg/__init__.py
@@ -13,14 +13,19 @@ import coloredlogs
from flask import Flask
from werkzeug.middleware.proxy_fix import ProxyFix
-from .auth import AUTH
+from .auth import login_manager
from .cli import DB_CLI, MAIL_CLI, USERS_CLI
-from .config import DefaultConfig, DevelopmentConfig, ProductionConfig, validate_config
+from .config import (
+ DefaultConfig,
+ DevelopmentConfig,
+ ProductionConfig,
+ validated_config_overrides,
+)
from .extensions import bootstrap, csrf, db, huey, limiter, mail, migrate
from .net import is_http_url
from .version import APP_NAME as APP_NAME
from .version import VERSION
-from .views import root_page
+from .views import webmentions_bp
def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
@@ -61,7 +66,7 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
app.config.from_prefixed_env(prefix="FLASK")
app.config.from_prefixed_env(prefix="WEBMENTIONS_SSG")
- app.config.update(validate_config(app.config, config_class=config_class))
+ app.config.update(validated_config_overrides(app.config, config_class=config_class))
if proxy_hops := app.config["PROXY_FIX_TRUSTED_HOPS"]:
# Do not trust forwarded host, port, or URL prefixes.
@@ -75,8 +80,8 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
log_file_handler = logging.handlers.RotatingFileHandler(
app.config["LOG_FILE"],
- maxBytes=app.config["LOGFILE_MAX_BYTES"],
- backupCount=app.config["LOGFILE_BACKUP_COUNT"],
+ maxBytes=app.config["LOG_FILE_MAX_BYTES"],
+ backupCount=app.config["LOG_FILE_BACKUP_COUNT"],
)
log_file_handler.setLevel(app.config["LOG_LEVEL"])
log_file_handler.setFormatter(default_logging_formatter)
@@ -111,7 +116,7 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
limiter.init_app(app)
mail.init_app(app)
- AUTH.init_app(app)
+ login_manager.init_app(app)
bootstrap.init_app(app)
huey.init_app(app)
@@ -125,7 +130,7 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
app.add_template_filter(is_http_url)
- app.register_blueprint(root_page)
+ app.register_blueprint(webmentions_bp)
app.cli.add_command(USERS_CLI)
diff --git a/webmentions_ssg/auth.py b/webmentions_ssg/auth.py
index 08abaa1..ce4960d 100644
--- a/webmentions_ssg/auth.py
+++ b/webmentions_ssg/auth.py
@@ -19,9 +19,9 @@ from .extensions import db
from .models import User
from .validation import is_control_character
-AUTH = LoginManager()
+login_manager = LoginManager()
-AUTH.login_view = "root.login" # pyright: ignore[reportAttributeAccessIssue]
+login_manager.login_view = "webmentions.login" # pyright: ignore[reportAttributeAccessIssue]
MIN_PASSWORD_LENGTH = 8
@@ -38,7 +38,7 @@ def dummy_password_hash() -> str:
return generate_password_hash(secrets.token_urlsafe())
-def validate_password(password: str) -> None:
+def validate_new_password(password: str) -> None:
"""Validate newly chosen passwords without arbitrary composition rules.
Allow Unicode, whitespace-only passwords, and arbitrarily long passphrases,
@@ -58,8 +58,8 @@ def validate_password(password: str) -> None:
raise ValueError("Password must not contain control characters.")
-@AUTH.user_loader
-def load_user(session_id: object) -> User | None:
+@login_manager.user_loader
+def load_user_from_session_id(session_id: object) -> User | None:
"""Load a user from the database by identifier.
:param session_id: Database ID and password-hash fingerprint stored in the session.
@@ -78,7 +78,7 @@ def load_user(session_id: object) -> User | None:
return user
-def login_username_limit_key() -> str:
+def login_username_rate_limit_key() -> str:
"""Group usernames across IPs without exposing plaintext to rate-limit storage.
:returns: Hashed username rate-limit key, or an IP-specific key if no username was
diff --git a/webmentions_ssg/cli.py b/webmentions_ssg/cli.py
index 5c2d534..225a39f 100644
--- a/webmentions_ssg/cli.py
+++ b/webmentions_ssg/cli.py
@@ -13,14 +13,14 @@ from flask_migrate import upgrade as migrate_upgrade
from sqlalchemy import inspect
from sqlalchemy.exc import IntegrityError
-from .auth import validate_password
+from .auth import validate_new_password
from .extensions import db, mail
from .models import User
USERS_CLI = AppGroup("users", help="Manage users.")
-def _require_user(username: str):
+def _get_user_or_fail(username: str):
"""Return a user by username or report a CLI-friendly error.
:param username: Username to look up in the database.
@@ -48,7 +48,7 @@ def create_user(username: str, password: str) -> None:
raise click.ClickException("Username must not be empty.")
try:
- validate_password(password)
+ validate_new_password(password)
except ValueError as exc:
raise click.ClickException(str(exc)) from exc
@@ -89,11 +89,11 @@ def set_user_password(username: str, password: str) -> None:
:raises click.ClickException: If the account is missing or the password is invalid.
"""
try:
- validate_password(password)
+ validate_new_password(password)
except ValueError as exc:
raise click.ClickException(str(exc)) from exc
- user = _require_user(username)
+ user = _get_user_or_fail(username)
user.password = password
db.session.commit()
click.echo(f"Updated password for user {username!r}.")
@@ -109,7 +109,7 @@ def delete_user(username: str, yes: bool) -> None:
:param yes: Whether to skip the confirmation prompt.
:raises click.ClickException: If the account does not exist.
"""
- user = _require_user(username)
+ user = _get_user_or_fail(username)
if not yes:
click.confirm(f"Delete user {username!r}?", abort=True)
@@ -122,19 +122,17 @@ MAIL_CLI = AppGroup("mail", help="Handle mail")
@MAIL_CLI.command("test", help="Send an email to test the SMTP configuration")
-@click.option(
- "--to", "recipient", help="Recipient address (defaults to NOTIFICATION_EMAIL)."
-)
+@click.option("--to", "recipient", help="Recipient address (defaults to DIGEST_EMAIL).")
def send_test_mail(recipient: str | None) -> None:
"""Send a test email using the configured SMTP server.
- :param recipient: Optional recipient overriding NOTIFICATION_EMAIL.
+ :param recipient: Optional recipient overriding DIGEST_EMAIL.
:raises click.ClickException: If configuration is missing or sending fails.
"""
- recipient = recipient or current_app.config.get("NOTIFICATION_EMAIL")
+ recipient = recipient or current_app.config.get("DIGEST_EMAIL")
if not recipient:
raise click.ClickException(
- "No recipient specified. Set NOTIFICATION_EMAIL or pass --to."
+ "No recipient specified. Set DIGEST_EMAIL or pass --to."
)
sender = current_app.config.get("MAIL_DEFAULT_SENDER")
@@ -162,7 +160,7 @@ def send_test_mail(recipient: str | None) -> None:
DB_CLI = AppGroup("db", help="Handle database")
-def _table_names() -> set[str]:
+def _existing_table_names() -> set[str]:
"""Return existing table names without modifying the database schema.
:returns: Names of tables in the configured database.
@@ -179,7 +177,7 @@ def create_db() -> None:
:raises click.ClickException: If the database already contains tables.
"""
- if _table_names():
+ if _existing_table_names():
raise click.ClickException(
"The database already contains tables. "
"Use 'flask db upgrade' for an existing migrated database."
@@ -198,7 +196,7 @@ def upgrade_db() -> None:
:raises click.ClickException: If the database has no Alembic revision table.
"""
- if "alembic_version" not in _table_names():
+ if "alembic_version" not in _existing_table_names():
raise click.ClickException(
"No Flask-Migrate revision table found. "
"For a new, empty database run 'flask db create-db'. "
diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py
index 6e6b4bf..7d09e7e 100644
--- a/webmentions_ssg/config.py
+++ b/webmentions_ssg/config.py
@@ -26,12 +26,12 @@ class DefaultConfig:
LOG_FILE = "/var/log/webmentions-ssg.log"
LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s"
LOG_LEVEL = logging.INFO
- LOGFILE_MAX_BYTES = 20_000_000
- LOGFILE_BACKUP_COUNT = 10
+ LOG_FILE_MAX_BYTES = 20_000_000
+ LOG_FILE_BACKUP_COUNT = 10
SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db"
# Empty by default: no target hostnames are accepted until configured.
- ALLOWED_HOSTNAMES = frozenset()
+ ALLOWED_TARGET_HOSTNAMES = frozenset()
# Cap incoming HTTP request bodies (also applies to other Flask routes).
MAX_CONTENT_LENGTH = 64 * 1024
# Independent UTF-8 byte limit for each submitted source/target URL.
@@ -40,28 +40,28 @@ class DefaultConfig:
RECEIVED_RETENTION_DAYS = 30
RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
MAX_REDIRECTS = 20
- MAX_SOURCE_BYTES = 1_000_000
- MAX_TARGET_BYTES = 1_000_000
- REQUEST_TIMEOUT = 5.0
+ MAX_RECEIVED_SOURCE_BYTES = 1_000_000
+ MAX_DISCOVERY_TARGET_BYTES = 1_000_000
+ REQUEST_TIMEOUT_SECONDS = 5.0
# Absolute wall-clock budget for each verification or delivery attempt.
- REQUEST_TOTAL_TIMEOUT = 30.0
+ REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0
# Requeue abandoned verification attempts after 15 minutes.
- VERIFICATION_TIMEOUT_SECONDS = 900
+ VERIFICATION_STALE_AFTER_SECONDS = 900
# Maximum automatic recoveries of a stale received/verifying row.
VERIFICATION_MAX_RECOVERIES = 3
- VERIFICATION_REAPER_SCHEDULE = "*/5 * * * *"
+ VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *"
- SOURCE_DIRECTORY = None
- SOURCE_BASE_URL = None
- IGNORED_HOSTNAMES = ()
- SCANNER_SCHEDULE = "0 * * * *"
+ SITE_OUTPUT_DIRECTORY = None
+ SITE_BASE_URL = None
+ IGNORED_TARGET_HOSTNAMES = ()
+ SOURCE_SCAN_SCHEDULE = "0 * * * *"
# Total send attempts per source revision (not additional retries).
SEND_MAX_ATTEMPTS = 6
SEND_RETRY_BASE_SECONDS = 3600
SEND_RETRY_MAX_SECONDS = 86400
- NOTIFICATION_EMAIL = None
- NOTIFICATION_SCHEDULE = "0 8 * * *"
+ DIGEST_EMAIL = None
+ DIGEST_SCHEDULE = "0 8 * * *"
MAIL_SERVER = "localhost"
MAIL_PORT = 25
@@ -116,7 +116,7 @@ class TestingConfig(DefaultConfig):
HUEY_URL = "memory://"
- ALLOWED_HOSTNAMES = frozenset({"dennisfink.me"})
+ ALLOWED_TARGET_HOSTNAMES = frozenset({"dennisfink.me"})
def normalize_hostnames(value: object) -> set[str]:
@@ -177,7 +177,7 @@ def validate_secret_key(value: object) -> str | bytes:
return value
-def validate_config(
+def validated_config_overrides(
config: Config, *, config_class: type[DefaultConfig]
) -> dict[str, object]:
"""Validate runtime configuration and return normalized values.
@@ -194,7 +194,7 @@ def validate_config(
unsafe.
"""
normalized: dict[str, object] = {}
- for key in ("ALLOWED_HOSTNAMES", "IGNORED_HOSTNAMES"):
+ for key in ("ALLOWED_TARGET_HOSTNAMES", "IGNORED_TARGET_HOSTNAMES"):
try:
normalized[key] = normalize_hostnames(config[key])
except (TypeError, ValueError) as exc:
@@ -221,9 +221,9 @@ def validate_config(
normalized["SECRET_KEY"] = validate_secret_key(config.get("SECRET_KEY"))
if not config["DEBUG"] and not config["TESTING"]:
- if not normalized["ALLOWED_HOSTNAMES"]:
+ if not normalized["ALLOWED_TARGET_HOSTNAMES"]:
raise RuntimeError(
- "Configure ALLOWED_HOSTNAMES before running in production."
+ "Configure ALLOWED_TARGET_HOSTNAMES before running in production."
)
if config["RATELIMIT_STORAGE_URI"] == "memory://":
raise RuntimeError(
diff --git a/webmentions_ssg/forms.py b/webmentions_ssg/forms.py
index e3dcdc0..c8ad0ba 100644
--- a/webmentions_ssg/forms.py
+++ b/webmentions_ssg/forms.py
@@ -13,11 +13,11 @@ from wtforms import Field, PasswordField, StringField, SubmitField, ValidationEr
from wtforms.form import BaseForm
from wtforms.validators import InputRequired, StopValidation
-from .net import hostname_of, is_public_address
+from .net import is_public_address, normalized_hostname
from .validation import is_control_character
-class URLMaxBytes:
+class MaxURLBytes:
"""Check the UTF-8 byte length of a submitted URL using the current config."""
def __init__(
@@ -43,7 +43,7 @@ class URLMaxBytes:
)
-class HTTPURL:
+class StrictHTTPURL:
"""Require an HTTP(S) URL that httpx can parse without rewriting whitespace.
httpx automatically percent-encodes some whitespace. Reject it instead of
@@ -75,7 +75,7 @@ class HTTPURL:
)
-class AllowedHostname:
+class AllowedTargetHostname:
"""Validate that a URL uses an allowed hostname.
:param message: Optional validation error message.
@@ -95,8 +95,11 @@ class AllowedHostname:
:param field: Field containing the URL to validate.
:raises ValidationError: If the URL hostname is not configured as allowed.
"""
- hostname = hostname_of(field.data)
- if hostname is not None and hostname in current_app.config["ALLOWED_HOSTNAMES"]:
+ hostname = normalized_hostname(field.data)
+ if (
+ hostname is not None
+ and hostname in current_app.config["ALLOWED_TARGET_HOSTNAMES"]
+ ):
return
raise ValidationError(self.message or field.gettext("Invalid input."))
@@ -105,7 +108,7 @@ class PublicIPLiteral:
"""Reject non-public IP literals without performing DNS in the web worker."""
def __call__(self, form: BaseForm, field: Field) -> None:
- hostname = hostname_of(field.data)
+ hostname = normalized_hostname(field.data)
if hostname is None:
raise ValidationError(field.gettext("Invalid input."))
@@ -126,7 +129,7 @@ class LoginForm(FlaskForm):
submit = SubmitField("Sign In")
-class EndpointForm(FlaskForm):
+class WebmentionSubmissionForm(FlaskForm):
"""Form for receiving a Webmention.
The source must be a public HTTP or HTTPS URL distinct from the target.
@@ -135,11 +138,16 @@ class EndpointForm(FlaskForm):
source = StringField(
"source",
- validators=[InputRequired(), URLMaxBytes(), HTTPURL(), PublicIPLiteral()],
+ validators=[InputRequired(), MaxURLBytes(), StrictHTTPURL(), PublicIPLiteral()],
)
target = StringField(
"target",
- validators=[InputRequired(), URLMaxBytes(), HTTPURL(), AllowedHostname()],
+ validators=[
+ InputRequired(),
+ MaxURLBytes(),
+ StrictHTTPURL(),
+ AllowedTargetHostname(),
+ ],
)
def validate_source(self, field: Field) -> None:
@@ -152,7 +160,7 @@ class EndpointForm(FlaskForm):
raise ValidationError(field.gettext("Field must not be equal to target."))
-class AdminActionForm(FlaskForm):
+class ConfirmActionForm(FlaskForm):
"""Form for confirming an administrative action."""
submit = SubmitField("Confirm")
diff --git a/webmentions_ssg/net.py b/webmentions_ssg/net.py
index 262434a..b827180 100644
--- a/webmentions_ssg/net.py
+++ b/webmentions_ssg/net.py
@@ -21,7 +21,7 @@ from httpcore._backends.sync import SyncStream
NAT64_PREFIX = ipaddress.IPv6Network("64:ff9b::/96")
IPV4_COMPATIBLE_PREFIX = ipaddress.IPv6Network("::/96")
-NETWORK_CONNECT_TIMOUT_ERROR = 599
+NETWORK_CONNECT_TIMEOUT_ERROR = 599
class AddressResolutionError(Exception):
@@ -36,16 +36,18 @@ class ResponseTooLargeError(ValueError):
"""A response body exceeds its configured size limit."""
-class NetworkDeadline:
+class RequestDeadline:
"""One monotonic deadline shared by DNS, TCP, TLS, and response streaming."""
def __init__(self, seconds: float) -> None:
if seconds <= 0:
- raise ValueError("REQUEST_TOTAL_TIMEOUT must be greater than zero")
- self.expires = time.monotonic() + seconds
+ raise ValueError("REQUEST_TOTAL_TIMEOUT_SECONDS must be greater than zero")
+ self.expires_at = time.monotonic() + seconds
- def timeout(self, original: float | None, error: type[Exception]) -> float:
- remaining = self.expires - time.monotonic()
+ def remaining_timeout(
+ self, original: float | None, error: type[Exception]
+ ) -> float:
+ remaining = self.expires_at - time.monotonic()
if remaining <= 0:
raise error("Overall HTTP request deadline exceeded")
return min(remaining, original) if original is not None else remaining
@@ -54,18 +56,20 @@ class NetworkDeadline:
class DeadlineStream(httpcore.NetworkStream):
"""Clip every read/write/TLS operation to the remaining overall deadline."""
- def __init__(self, stream: httpcore.NetworkStream, deadline: NetworkDeadline):
+ def __init__(self, stream: httpcore.NetworkStream, deadline: RequestDeadline):
self._stream = stream
self._deadline = deadline
def read(self, max_bytes: int, timeout: float | None = None) -> bytes:
return self._stream.read(
- max_bytes, timeout=self._deadline.timeout(timeout, httpcore.ReadTimeout)
+ max_bytes,
+ timeout=self._deadline.remaining_timeout(timeout, httpcore.ReadTimeout),
)
def write(self, buffer: bytes, timeout: float | None = None) -> None:
self._stream.write(
- buffer, timeout=self._deadline.timeout(timeout, httpcore.WriteTimeout)
+ buffer,
+ timeout=self._deadline.remaining_timeout(timeout, httpcore.WriteTimeout),
)
def start_tls(
@@ -78,7 +82,9 @@ class DeadlineStream(httpcore.NetworkStream):
self._stream.start_tls(
ssl_context,
server_hostname=server_hostname,
- timeout=self._deadline.timeout(timeout, httpcore.ConnectTimeout),
+ timeout=self._deadline.remaining_timeout(
+ timeout, httpcore.ConnectTimeout
+ ),
),
self._deadline,
)
@@ -93,10 +99,10 @@ class DeadlineStream(httpcore.NetworkStream):
class PublicNetworkBackend(httpcore.SyncBackend):
"""Resolve and validate in the TCP connection operation, never in a hook."""
- def __init__(self, deadline: NetworkDeadline):
+ def __init__(self, deadline: RequestDeadline):
self._deadline = deadline
- def _connect_one(
+ def _connect_to_address(
self,
address: str,
port: int,
@@ -115,7 +121,9 @@ class PublicNetworkBackend(httpcore.SyncBackend):
with ExitStack() as cleanup:
sock = socket.socket(family, socket.SOCK_STREAM)
cleanup.callback(sock.close)
- sock.settimeout(self._deadline.timeout(timeout, httpcore.ConnectTimeout))
+ sock.settimeout(
+ self._deadline.remaining_timeout(timeout, httpcore.ConnectTimeout)
+ )
if local_address is not None:
sock.bind((local_address, 0))
@@ -143,13 +151,13 @@ class PublicNetworkBackend(httpcore.SyncBackend):
) -> httpcore.NetworkStream:
# No second lookup of `host` is permitted. Even a DNS response that
# changes immediately after this check cannot change the socket peer.
- dns_timeout = self._deadline.timeout(timeout, httpcore.ConnectTimeout)
- addresses = public_addresses(host, lifetime=dns_timeout)
+ dns_timeout = self._deadline.remaining_timeout(timeout, httpcore.ConnectTimeout)
+ addresses = resolve_public_addresses(host, lifetime=dns_timeout)
last_error: httpcore.ConnectError | httpcore.ConnectTimeout | None = None
for address in addresses:
try:
- return self._connect_one(
+ return self._connect_to_address(
address, port, timeout, local_address, socket_options
)
except OSError as exc:
@@ -174,11 +182,13 @@ class PublicHTTPTransport(httpx.HTTPTransport):
def __init__(self, total_timeout: float):
self._pool = httpcore.ConnectionPool(
ssl_context=httpx.create_ssl_context(verify=True, trust_env=False),
- network_backend=PublicNetworkBackend(NetworkDeadline(total_timeout)),
+ network_backend=PublicNetworkBackend(RequestDeadline(total_timeout)),
)
-def build_client(user_agent: str, *, accept: str | None = None) -> httpx.Client:
+def build_public_http_client(
+ user_agent: str, *, accept: str | None = None
+) -> httpx.Client:
"""Return the hardened HTTP client shared by receiver and sender.
:param user_agent: User-Agent header sent with each request.
@@ -192,11 +202,13 @@ def build_client(user_agent: str, *, accept: str | None = None) -> httpx.Client:
return httpx.Client(
headers=headers,
- timeout=httpx.Timeout(current_app.config["REQUEST_TIMEOUT"]),
+ timeout=httpx.Timeout(current_app.config["REQUEST_TIMEOUT_SECONDS"]),
follow_redirects=True,
max_redirects=current_app.config["MAX_REDIRECTS"],
trust_env=False,
- transport=PublicHTTPTransport(current_app.config["REQUEST_TOTAL_TIMEOUT"]),
+ transport=PublicHTTPTransport(
+ current_app.config["REQUEST_TOTAL_TIMEOUT_SECONDS"]
+ ),
)
@@ -237,7 +249,7 @@ def resolve_hostname(
) from exc
-def public_addresses(
+def resolve_public_addresses(
hostname: str, *, lifetime: float | None = None
) -> tuple[str, ...]:
"""Resolve *once* and return only checked, globally routable IP addresses.
@@ -267,7 +279,7 @@ def public_addresses(
return tuple(str(address) for address in addresses)
-def hostname_of(url: str) -> str | None:
+def normalized_hostname(url: str) -> str | None:
"""Return a normalized URL hostname, or None for malformed URLs.
:param url: URL from which to extract a hostname.
@@ -280,7 +292,7 @@ def hostname_of(url: str) -> str | None:
return hostname.rstrip(".") if hostname is not None else None
-def content_type_of(headers: Mapping[str, str]) -> str:
+def media_type_of(headers: Mapping[str, str]) -> str:
"""Return a normalized media type without Content-Type parameters.
:param headers: HTTP response headers to inspect.
@@ -330,7 +342,7 @@ def read_limited_body(response: httpx.Response, max_bytes: int, *, label: str) -
return bytes(body)
-def is_temporary_status(status: int) -> bool:
+def is_retryable_status(status: int) -> bool:
"""Return whether an HTTP status is normally retryable.
:param status: HTTP response status code to classify.
@@ -343,5 +355,5 @@ def is_temporary_status(status: int) -> bool:
HTTPStatus.TOO_EARLY,
HTTPStatus.TOO_MANY_REQUESTS,
}
- or HTTPStatus.INTERNAL_SERVER_ERROR <= status <= NETWORK_CONNECT_TIMOUT_ERROR
+ or HTTPStatus.INTERNAL_SERVER_ERROR <= status <= NETWORK_CONNECT_TIMEOUT_ERROR
)
diff --git a/webmentions_ssg/tasks/consumer.py b/webmentions_ssg/tasks/consumer.py
index 13334bc..c24a883 100644
--- a/webmentions_ssg/tasks/consumer.py
+++ b/webmentions_ssg/tasks/consumer.py
@@ -22,9 +22,9 @@ def create_consumer() -> Huey:
app = create_app()
for config_key, task in (
- ("SCANNER_SCHEDULE", scanner.scan_sources),
- ("VERIFICATION_REAPER_SCHEDULE", receiver.recover_stale_webmentions),
- ("NOTIFICATION_SCHEDULE", notifications.send_webmention_digest),
+ ("SOURCE_SCAN_SCHEDULE", scanner.scan_sources),
+ ("VERIFICATION_RECOVERY_SCHEDULE", receiver.recover_stale_verifications),
+ ("DIGEST_SCHEDULE", notifications.send_webmention_digest),
("RECEIVED_RETENTION_SCHEDULE", retention.purge_old_received_webmentions),
):
schedule = crontab(*app.config[config_key].split(), strict=True)
diff --git a/webmentions_ssg/tasks/discovery.py b/webmentions_ssg/tasks/discovery.py
index 6d01e53..c683cb0 100644
--- a/webmentions_ssg/tasks/discovery.py
+++ b/webmentions_ssg/tasks/discovery.py
@@ -14,48 +14,48 @@ from flask import current_app
from ..net import (
ResponseTooLargeError,
- content_type_of,
is_http_url,
- is_temporary_status,
+ is_retryable_status,
+ media_type_of,
read_limited_body,
)
-LINK_SPLIT = re.compile(r",\s*(?=<)")
+LINK_HEADER_SPLIT = re.compile(r",\s*(?=<)")
DISCOVERY_HEADERS = {"Accept": "text/html, application/xhtml+xml;q=0.9"}
-class SenderError(Exception):
+class DeliveryError(Exception):
"""A Webmention cannot be sent."""
-class TemporarySenderError(SenderError):
+class RetryableDeliveryError(DeliveryError):
"""A Webmention send failed for a potentially temporary reason."""
-class PermanentSenderError(SenderError):
+class PermanentDeliveryError(DeliveryError):
"""A Webmention send failed permanently for this source revision."""
-def resolve_endpoint(response: httpx.Response, href: str) -> str:
+def resolve_endpoint_url(response: httpx.Response, href: str) -> str:
"""Resolve and validate a discovered Webmention endpoint.
:param response: Response from which the endpoint was discovered.
:param href: Endpoint reference to resolve.
:returns: Absolute Webmention endpoint URL.
- :raises PermanentSenderError: If the resolved endpoint is not an HTTP or HTTPS URL.
+ :raises PermanentDeliveryError: If the resolved endpoint is not an HTTP or HTTPS URL.
"""
try:
endpoint = urljoin(str(response.url), href.strip())
except ValueError as exc:
- raise PermanentSenderError(f"Invalid Webmention endpoint: {href!r}") from exc
+ raise PermanentDeliveryError(f"Invalid Webmention endpoint: {href!r}") from exc
if not is_http_url(endpoint):
- raise PermanentSenderError(f"Invalid Webmention endpoint: {endpoint!r}")
+ raise PermanentDeliveryError(f"Invalid Webmention endpoint: {endpoint!r}")
return endpoint
-def parse_link_value(value: str) -> tuple[str, set[str]] | None:
+def parse_link_header_value(value: str) -> tuple[str, set[str]] | None:
"""Parse a Link header value into its target and relations.
:param value: Link header value to parse.
@@ -84,7 +84,7 @@ def parse_link_value(value: str) -> tuple[str, set[str]] | None:
return href, relations
-def endpoint_from_headers(response: httpx.Response) -> str | None:
+def find_endpoint_in_headers(response: httpx.Response) -> str | None:
"""Find a Webmention endpoint in the response Link headers.
:param response: HTTP response whose headers should be inspected.
@@ -92,22 +92,22 @@ def endpoint_from_headers(response: httpx.Response) -> str | None:
Invalid candidates are ignored.
"""
for header in response.headers.get_list("Link"):
- for value in LINK_SPLIT.split(header):
- if (link := parse_link_value(value)) is None:
+ for value in LINK_HEADER_SPLIT.split(header):
+ if (link := parse_link_header_value(value)) is None:
continue
href, relations = link
if "webmention" in relations:
try:
- return resolve_endpoint(response, href)
- except PermanentSenderError:
+ return resolve_endpoint_url(response, href)
+ except PermanentDeliveryError:
continue
return None
-def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
+def find_endpoint_in_html(response: httpx.Response, body: bytes) -> str | None:
"""Find a Webmention endpoint in an HTML document.
``link`` and ``a`` elements are inspected in document order.
@@ -123,8 +123,8 @@ def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
'link[rel~="webmention" i][href], a[rel~="webmention" i][href]'
):
try:
- return resolve_endpoint(response, str(element["href"]))
- except PermanentSenderError:
+ return resolve_endpoint_url(response, str(element["href"]))
+ except PermanentDeliveryError:
continue
return None
@@ -135,14 +135,14 @@ def read_target_body(response: httpx.Response) -> bytes:
:param response: HTTP response to read with the configured target-size limit.
:returns: Response body, provided it is within the target-size limit.
- :raises PermanentSenderError: If the target document is too large.
+ :raises PermanentDeliveryError: If the target document is too large.
"""
try:
return read_limited_body(
- response, current_app.config["MAX_TARGET_BYTES"], label="Target"
+ response, current_app.config["MAX_DISCOVERY_TARGET_BYTES"], label="Target"
)
except ResponseTooLargeError as exc:
- raise PermanentSenderError(str(exc)) from exc
+ raise PermanentDeliveryError(str(exc)) from exc
def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | None:
@@ -155,8 +155,8 @@ def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | Non
:param client: HTTP client to use for discovery requests.
:param target: Target URL whose Webmention endpoint should be discovered.
:returns: Discovered Webmention endpoint, or ``None`` if none is advertised.
- :raises TemporarySenderError: If the target returns a temporary HTTP failure.
- :raises PermanentSenderError: If GET returns a permanent HTTP failure.
+ :raises RetryableDeliveryError: If the target returns a temporary HTTP failure.
+ :raises PermanentDeliveryError: If GET returns a permanent HTTP failure.
"""
try:
head_response = client.head(target, headers=DISCOVERY_HEADERS)
@@ -165,25 +165,25 @@ def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | Non
# or drop it even when fetching the document with GET would succeed.
pass
else:
- if endpoint := endpoint_from_headers(head_response):
+ if endpoint := find_endpoint_in_headers(head_response):
return endpoint
with client.stream("GET", target, headers=DISCOVERY_HEADERS) as response:
- if endpoint := endpoint_from_headers(response):
+ if endpoint := find_endpoint_in_headers(response):
return endpoint
- if is_temporary_status(response.status_code):
- raise TemporarySenderError(f"Target returned HTTP {response.status_code}")
+ if is_retryable_status(response.status_code):
+ raise RetryableDeliveryError(f"Target returned HTTP {response.status_code}")
if not response.is_success:
- raise PermanentSenderError(f"Target returned HTTP {response.status_code}")
+ raise PermanentDeliveryError(f"Target returned HTTP {response.status_code}")
- media_type = content_type_of(response.headers)
+ media_type = media_type_of(response.headers)
if media_type not in {"text/html", "application/xhtml+xml"}:
return None
- return endpoint_from_html(response, read_target_body(response))
+ return find_endpoint_in_html(response, read_target_body(response))
def post_webmention(
diff --git a/webmentions_ssg/tasks/extension.py b/webmentions_ssg/tasks/extension.py
index 58e0036..faed364 100644
--- a/webmentions_ssg/tasks/extension.py
+++ b/webmentions_ssg/tasks/extension.py
@@ -15,10 +15,12 @@ from flask import Flask
from huey import Huey as BaseHuey
from huey.api import TaskWrapper
-from .json_serializer import JSONSerializer
+from .json_serializer import TaggedJSONSerializer
-def _redis_backend(parsed: SplitResult) -> tuple[type[BaseHuey], dict[str, Any]]:
+def _redis_class_and_options(
+ parsed: SplitResult,
+) -> tuple[type[BaseHuey], dict[str, Any]]:
"""Select a Redis Huey flavour while retaining the underlying URL scheme.
:param parsed: Parsed Redis backend URL, including any flavour suffix.
@@ -47,7 +49,9 @@ def _redis_backend(parsed: SplitResult) -> tuple[type[BaseHuey], dict[str, Any]]
return backends[flavour], {"url": fixed_url}
-def _path_backend(url: str, scheme: str) -> tuple[type[BaseHuey], dict[str, Any]]:
+def _file_class_and_options(
+ url: str, scheme: str
+) -> tuple[type[BaseHuey], dict[str, Any]]:
"""Extract a relative or absolute SQLite/file storage path.
:param url: Backend URL containing the storage filename or path.
@@ -86,7 +90,7 @@ def _path_backend(url: str, scheme: str) -> tuple[type[BaseHuey], dict[str, Any]
return backend, {option: path}
-class _LazyTask:
+class _DeferredTask:
"""Stable public task handle which follows the extension's current backend.
Huey creates task classes and registers them when its decorator is applied.
@@ -111,7 +115,7 @@ class _LazyTask:
self._registered: TaskWrapper | None = None
update_wrapper(self, func)
- def register(self) -> None:
+ def bind(self) -> None:
"""Bind the original function to the latest initialized backend.
Register the task decorator again so its stable handle uses the currently
@@ -120,10 +124,10 @@ class _LazyTask:
backend = self._extension.huey
decorator = backend.periodic_task if self._periodic else backend.task
self._registered = decorator(*self._args, **self._kwargs)(
- self._extension._in_app_context(self._func)
+ self._extension._with_app_context(self._func)
)
- def _current(self) -> TaskWrapper:
+ def _bound_task(self) -> TaskWrapper:
if self._registered is None:
raise RuntimeError(
"Huey has not been initialized. Call huey.init_app(app) first."
@@ -137,7 +141,7 @@ class _LazyTask:
:param kwargs: Keyword arguments passed to the queued task.
:returns: Result of enqueueing the task on the current backend.
"""
- return self._current()(*args, **kwargs)
+ return self._bound_task()(*args, **kwargs)
def __getattr__(self, name: str) -> Any:
"""Delegate Huey task operations (call_local, schedule, s, etc.).
@@ -145,7 +149,7 @@ class _LazyTask:
:param name: Huey task attribute to delegate.
:returns: Requested attribute of the currently bound Huey task.
"""
- return getattr(self._current(), name)
+ return getattr(self._bound_task(), name)
class Huey:
@@ -162,7 +166,7 @@ class Huey:
"""
self.app: Flask | None = None
self._huey: BaseHuey | None = None
- self._tasks: list[_LazyTask] = []
+ self._task_handles: list[_DeferredTask] = []
if app is not None:
self.init_app(app)
@@ -192,7 +196,7 @@ class Huey:
raise RuntimeError(
"HUEY.serializer cannot be overridden; JSON is required."
)
- config["serializer"] = JSONSerializer(
+ config["serializer"] = TaggedJSONSerializer(
compression=config.pop("compression", False),
use_zlib=config.pop("use_zlib", False),
)
@@ -205,8 +209,8 @@ class Huey:
# Import order is immaterial: tasks declared before initialization are
# registered now, and previously imported handles follow this backend.
- for task in self._tasks:
- task.register()
+ for task in self._task_handles:
+ task.bind()
app.extensions["huey"] = self
@@ -224,7 +228,7 @@ class Huey:
)
return self._huey
- def _in_app_context[**P, R](self, func: Callable[P, R]) -> Callable[P, R]:
+ def _with_app_context[**P, R](self, func: Callable[P, R]) -> Callable[P, R]:
"""Return a task wrapper that executes with the configured Flask app.
:param func: Task function to wrap in a Flask application context.
@@ -241,23 +245,23 @@ class Huey:
return wrapped
- def _decorate_task[**P, R](
+ def _register_task[**P, R](
self,
func: Callable[P, R],
task_args: tuple[Any, ...],
task_kwargs: dict[str, Any],
*,
periodic: bool,
- ) -> _LazyTask:
- handle = _LazyTask(self, func, task_args, task_kwargs, periodic=periodic)
- self._tasks.append(handle)
+ ) -> _DeferredTask:
+ handle = _DeferredTask(self, func, task_args, task_kwargs, periodic=periodic)
+ self._task_handles.append(handle)
if self._huey is not None:
- handle.register()
+ handle.bind()
return handle
def task[**P, R](
self, *task_args: Any, **task_kwargs: Any
- ) -> Callable[[Callable[P, R]], _LazyTask]:
+ ) -> Callable[[Callable[P, R]], _DeferredTask]:
"""Declare a task even before :meth:`init_app` has run.
:param task_args: Positional arguments for the Huey task decorator.
@@ -265,14 +269,14 @@ class Huey:
:returns: Decorator that registers and returns a lazily bound task.
"""
- def decorator(func: Callable[P, R]) -> _LazyTask:
- return self._decorate_task(func, task_args, task_kwargs, periodic=False)
+ def decorator(func: Callable[P, R]) -> _DeferredTask:
+ return self._register_task(func, task_args, task_kwargs, periodic=False)
return decorator
def periodic_task[**P, R](
self, *task_args: Any, **task_kwargs: Any
- ) -> Callable[[Callable[P, R]], _LazyTask]:
+ ) -> Callable[[Callable[P, R]], _DeferredTask]:
"""Declare a periodic task against the current or next backend.
:param task_args: Positional arguments for the Huey periodic-task decorator.
@@ -280,8 +284,8 @@ class Huey:
:returns: Decorator that registers and returns a lazily bound periodic task.
"""
- def decorator(func: Callable[P, R]) -> _LazyTask:
- return self._decorate_task(func, task_args, task_kwargs, periodic=True)
+ def decorator(func: Callable[P, R]) -> _DeferredTask:
+ return self._register_task(func, task_args, task_kwargs, periodic=True)
return decorator
@@ -309,9 +313,9 @@ class Huey:
scheme = parsed.scheme.lower()
if scheme.partition("+")[0] in {"redis", "rediss"}:
- return _redis_backend(parsed)
+ return _redis_class_and_options(parsed)
if scheme in {"sqlite", "file"}:
- return _path_backend(url, scheme)
+ return _file_class_and_options(url, scheme)
if scheme in {"postgres", "postgresql"}:
from huey import PostgresHuey
diff --git a/webmentions_ssg/tasks/json_serializer.py b/webmentions_ssg/tasks/json_serializer.py
index 7e51358..804cfee 100644
--- a/webmentions_ssg/tasks/json_serializer.py
+++ b/webmentions_ssg/tasks/json_serializer.py
@@ -14,7 +14,7 @@ from huey.serializer import Serializer
from huey.utils import SKIPPED, Error
-class JSONSerializer(Serializer):
+class TaggedJSONSerializer(Serializer):
"""A deliberately restricted, non-pickle serializer for our Huey tasks.
JSON has no native UUID, datetime, tuple or Huey message representation.
diff --git a/webmentions_ssg/tasks/notifications.py b/webmentions_ssg/tasks/notifications.py
index b1762d5..eb540de 100644
--- a/webmentions_ssg/tasks/notifications.py
+++ b/webmentions_ssg/tasks/notifications.py
@@ -22,16 +22,16 @@ def send_webmention_digest() -> None:
"""
# Resolve the lock against the current Huey backend, not the import-time one.
with huey.lock_task("send-webmention-digest"):
- _send_webmention_digest()
+ _send_digest_locked()
-def _send_webmention_digest() -> None:
+def _send_digest_locked() -> None:
"""Do the work while the current backend's digest lock is held.
Collect verified mentions, send the configured message, and persist notification
timestamps.
"""
- recipient = current_app.config.get("NOTIFICATION_EMAIL")
+ recipient = current_app.config.get("DIGEST_EMAIL")
if not recipient:
return
diff --git a/webmentions_ssg/tasks/receiver.py b/webmentions_ssg/tasks/receiver.py
index eb228b3..313a8e4 100644
--- a/webmentions_ssg/tasks/receiver.py
+++ b/webmentions_ssg/tasks/receiver.py
@@ -20,13 +20,13 @@ from ..net import (
AddressResolutionError,
ResponseTooLargeError,
UnsafeAddressError,
- build_client,
- content_type_of,
- is_temporary_status,
+ build_public_http_client,
+ is_retryable_status,
+ media_type_of,
read_limited_body,
)
from ..version import APP_NAME, VERSION
-from .mentions import html_mentions_target, text_mentions_target
+from .target_matching import html_mentions_target, text_mentions_target
class VerificationError(Exception):
@@ -37,14 +37,14 @@ class SourceGoneError(VerificationError):
"""The source explicitly reports that it has been removed."""
-class TemporaryFetchError(Exception):
+class RetryableFetchError(Exception):
"""Fetching the source may succeed when retried later."""
RECOVERY_EXHAUSTED_REASON = "Verification recovery limit reached"
-def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
+def fetch_source_document(source_url: str) -> tuple[httpx.Response, bytes]:
"""Fetch a webmention source document.
The request follows redirects while enforcing the configured timeout,
@@ -53,13 +53,13 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
:param source_url: URL of the source document.
:returns: HTTP response and response body.
:raises SourceGoneError: If the source returns HTTP 410.
- :raises TemporaryFetchError: If the source returns a temporary HTTP error.
+ :raises RetryableFetchError: If the source returns a temporary HTTP error.
:raises VerificationError: If the source returns another unsuccessful HTTP status or
exceeds the configured maximum response size.
"""
try:
with (
- build_client(
+ build_public_http_client(
f"{APP_NAME}/{VERSION} ReceivedWebmention",
accept="text/html, application/xhtml+xml;q=0.9, text/plain;q=0.8",
) as client,
@@ -69,8 +69,8 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
pass
elif response.status_code == HTTPStatus.GONE:
raise SourceGoneError("Source returned HTTP 410")
- elif is_temporary_status(response.status_code):
- raise TemporaryFetchError(
+ elif is_retryable_status(response.status_code):
+ raise RetryableFetchError(
f"Source returned HTTP {response.status_code}"
)
else:
@@ -78,7 +78,9 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
try:
return response, read_limited_body(
- response, current_app.config["MAX_SOURCE_BYTES"], label="Source"
+ response,
+ current_app.config["MAX_RECEIVED_SOURCE_BYTES"],
+ label="Source",
)
except ResponseTooLargeError as exc:
raise VerificationError(str(exc)) from exc
@@ -86,7 +88,7 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
except UnsafeAddressError as exc:
raise VerificationError("Source resolves to a non-public address") from exc
except AddressResolutionError as exc:
- raise TemporaryFetchError("Source hostname could not be resolved") from exc
+ raise RetryableFetchError("Source hostname could not be resolved") from exc
def source_mentions_target(source_url: str, target_url: str) -> bool:
@@ -100,11 +102,11 @@ def source_mentions_target(source_url: str, target_url: str) -> bool:
:returns: Whether the source mentions the target URL.
:raises VerificationError: If the source has an unsupported or missing content type.
:raises SourceGoneError: If the source explicitly reports that it is gone.
- :raises TemporaryFetchError: If fetching the source fails temporarily.
+ :raises RetryableFetchError: If fetching the source fails temporarily.
"""
- response, body = fetch_source(source_url)
+ response, body = fetch_source_document(source_url)
- media_type = content_type_of(response.headers)
+ media_type = media_type_of(response.headers)
match media_type:
case "text/html" | "application/xhtml+xml":
@@ -127,13 +129,13 @@ def source_mentions_target(source_url: str, target_url: str) -> bool:
class VerificationClaim:
"""Source and lease version for one atomically claimed verification."""
- identifier: uuid.UUID
+ webmention_uuid: uuid.UUID
source: str
target: str
- started_at: datetime
+ lease_started_at: datetime
-def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
+def claim_for_verification(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
"""Claim an eligible row, returning its source, target, and lease version.
:param webmention_uuid: Identifier of the received Webmention to claim.
@@ -157,10 +159,10 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
return None
claim = VerificationClaim(
- identifier=webmention_uuid,
+ webmention_uuid=webmention_uuid,
source=webmention.source,
target=webmention.target,
- started_at=datetime.now(UTC),
+ lease_started_at=datetime.now(UTC),
)
changed = db.session.execute(
sa.update(ReceivedWebmention)
@@ -172,7 +174,7 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
.values(
status=ReceivedStatus.VERIFYING,
failure_reason=None,
- updated_at=claim.started_at,
+ updated_at=claim.lease_started_at,
)
)
@@ -184,12 +186,14 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
return claim
-def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
+def determine_verification_outcome(
+ claim: VerificationClaim,
+) -> tuple[ReceivedStatus, str | None]:
"""Map verification results and permanent errors to a final status/reason.
:param claim: Claim containing the source and target URLs to verify.
:returns: Final verification status and optional reason.
- :raises TemporaryFetchError: If the source fetch fails transiently and should be
+ :raises RetryableFetchError: If the source fetch fails transiently and should be
retried.
:raises httpx.RequestError: If a transient HTTP request error should be retried.
"""
@@ -199,12 +203,12 @@ def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
return ReceivedStatus.DELETED, str(exc)
except VerificationError as exc:
return ReceivedStatus.FAILED, str(exc)
- except TemporaryFetchError, httpx.RequestError:
+ except RetryableFetchError, httpx.RequestError:
raise # These errors must be persisted and then retried by Huey.
except Exception as exc:
# InvalidURL is not a RequestError; unexpected source errors are terminal.
current_app.logger.exception(
- "Unexpected error verifying ReceivedWebmention %s", claim.identifier
+ "Unexpected error verifying ReceivedWebmention %s", claim.webmention_uuid
)
return ReceivedStatus.FAILED, str(exc) or type(exc).__name__
@@ -226,9 +230,9 @@ def release_claim(
changed = db.session.execute(
sa.update(ReceivedWebmention)
.where(
- ReceivedWebmention.uuid == claim.identifier,
+ ReceivedWebmention.uuid == claim.webmention_uuid,
ReceivedWebmention.status == ReceivedStatus.VERIFYING,
- ReceivedWebmention.updated_at == claim.started_at,
+ ReceivedWebmention.updated_at == claim.lease_started_at,
)
.values(status=status, failure_reason=reason, updated_at=datetime.now(UTC))
)
@@ -246,15 +250,15 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None:
lease.
:param webmention_uuid: Identifier of the received webmention to verify.
- :raises TemporaryFetchError: If fetching the source fails temporarily.
+ :raises RetryableFetchError: If fetching the source fails temporarily.
:raises httpx.RequestError: If an HTTP request fails while fetching.
"""
- if (claim := claim_eligible_row(webmention_uuid)) is None:
+ if (claim := claim_for_verification(webmention_uuid)) is None:
return
try:
- status, reason = check_source(claim)
- except (TemporaryFetchError, httpx.RequestError) as exc:
+ status, reason = determine_verification_outcome(claim)
+ except (RetryableFetchError, httpx.RequestError) as exc:
release_claim(
claim, ReceivedStatus.FAILED, str(exc) or "Source could not be fetched"
)
@@ -263,7 +267,7 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None:
release_claim(claim, status, reason)
-def recover_stale_webmentions() -> int:
+def recover_stale_verifications() -> int:
"""Requeue verification attempts that were abandoned or lost from the queue.
Recover both stale ``verifying`` rows (workers that died) and stale
@@ -280,7 +284,9 @@ def recover_stale_webmentions() -> int:
:returns: Number of webmentions requeued.
"""
now = datetime.now(UTC)
- cutoff = now - timedelta(seconds=current_app.config["VERIFICATION_TIMEOUT_SECONDS"])
+ cutoff = now - timedelta(
+ seconds=current_app.config["VERIFICATION_STALE_AFTER_SECONDS"]
+ )
stale = db.session.execute(
sa.select(
diff --git a/webmentions_ssg/tasks/scanner.py b/webmentions_ssg/tasks/scanner.py
index 13d2ceb..034b2cf 100644
--- a/webmentions_ssg/tasks/scanner.py
+++ b/webmentions_ssg/tasks/scanner.py
@@ -20,15 +20,15 @@ from .sender import send_webmention
from .source_parser import ScannedSource, SourceScanError, scan_source_file
-def create_source(scanned: ScannedSource, scan_time: datetime) -> Source:
- """Create a source model from a newly discovered document.
+def build_source(scanned: ScannedSource, scan_time: datetime) -> Source:
+ """Build a source model from a newly discovered document.
- A sent Webmention is created for each discovered target at the initial source
+ A sent Webmention is built for each discovered target at the initial source
revision.
:param scanned: Scanned source data.
:param scan_time: Time at which the source was discovered.
- :returns: Newly created source model.
+ :returns: Newly built source model.
"""
source = Source(
path=scanned.path,
@@ -48,7 +48,7 @@ def create_source(scanned: ScannedSource, scan_time: datetime) -> Source:
return source
-def update_source(
+def apply_scan_to_source(
source: Source, scanned: ScannedSource, scan_time: datetime
) -> Source:
"""Update an existing source from newly scanned data.
@@ -113,24 +113,24 @@ def scan_sources() -> None:
"""
# Manual and periodic scans must contend for the current backend's lock.
with huey.lock_task("scan-webmention-sources"):
- _scan_locked()
+ _scan_and_enqueue()
@dataclass(frozen=True)
-class ScanResult:
+class TreeScanResult:
"""Count and discovered paths from a traversal of the source tree."""
scanned_count: int
seen_paths: frozenset[str]
-def scan_tree(
+def reconcile_source_tree(
root: Path,
base_url: str | None,
sources_by_path: dict[str, Source],
paths_by_url: dict[str, str],
scan_time: datetime,
-) -> ScanResult:
+) -> TreeScanResult:
"""Reconcile found pages and return the paths seen, even on parse failures.
:param root: Root of the generated static-site output tree.
@@ -157,7 +157,7 @@ def scan_tree(
index_path,
root=root,
base_url=base_url,
- ignored_hostnames=current_app.config["IGNORED_HOSTNAMES"],
+ ignored_hostnames=current_app.config["IGNORED_TARGET_HOSTNAMES"],
)
except (OSError, SourceScanError) as exc:
current_app.logger.warning("Could not scan source %s: %s", index_path, exc)
@@ -182,10 +182,10 @@ def scan_tree(
try:
if (source := sources_by_path.get(scanned.path)) is None:
- source = create_source(scanned, scan_time)
+ source = build_source(scanned, scan_time)
db.session.add(source)
else:
- source = update_source(source, scanned, scan_time)
+ source = apply_scan_to_source(source, scanned, scan_time)
sources_by_path[source.path] = source
paths_by_url[source.url] = source.path
@@ -193,10 +193,10 @@ def scan_tree(
except SourceScanError as exc:
current_app.logger.warning("Could not scan source %s: %s", index_path, exc)
- return ScanResult(scanned_count, frozenset(seen_paths))
+ return TreeScanResult(scanned_count, frozenset(seen_paths))
-def mark_missing(
+def mark_missing_sources_deleted(
sources_by_path: dict[str, Source], seen_paths: frozenset[str], scan_time: datetime
) -> int:
"""Mark absent, previously active sources deleted and return their count.
@@ -225,7 +225,7 @@ def mark_missing(
return marked
-def queue_pending(scan_time: datetime) -> int:
+def enqueue_due_sends(scan_time: datetime) -> int:
"""Enqueue due Webmentions and return the number of tasks submitted.
:param scan_time: Current scan timestamp used to evaluate retry deadlines.
@@ -249,7 +249,7 @@ def queue_pending(scan_time: datetime) -> int:
return queued
-def _scan_locked() -> None:
+def _scan_and_enqueue() -> None:
"""Scan sources while the caller holds the shared scan lock.
Reconcile the generated source tree, persist changes, and enqueue eligible outgoing
@@ -257,7 +257,7 @@ def _scan_locked() -> None:
:raises RuntimeError: If the source directory or configured base URL is invalid.
"""
- directory = current_app.config.get("SOURCE_DIRECTORY")
+ directory = current_app.config.get("SITE_OUTPUT_DIRECTORY")
if directory is None:
return
@@ -265,9 +265,9 @@ def _scan_locked() -> None:
if not root.is_dir():
raise RuntimeError(f"Source directory is not a directory: {root}")
- if (base_url := current_app.config.get("SOURCE_BASE_URL")) is not None:
+ if (base_url := current_app.config.get("SITE_BASE_URL")) is not None:
if not is_http_url(base_url):
- raise RuntimeError("SOURCE_BASE_URL must be an absolute HTTP or HTTPS URL")
+ raise RuntimeError("SITE_BASE_URL must be an absolute HTTP or HTTPS URL")
base_url = f"{base_url.rstrip('/')}/"
sources_by_path = {
@@ -281,7 +281,9 @@ def _scan_locked() -> None:
# take ownership merely by appearing earlier in the traversal.
paths_by_url = {source.url: source.path for source in sources_by_path.values()}
scan_time = datetime.now(UTC)
- scan = scan_tree(root, base_url, sources_by_path, paths_by_url, scan_time)
+ scan = reconcile_source_tree(
+ root, base_url, sources_by_path, paths_by_url, scan_time
+ )
if scan.scanned_count == 0:
current_app.logger.warning(
@@ -290,9 +292,11 @@ def _scan_locked() -> None:
)
return
- missing_count = mark_missing(sources_by_path, scan.seen_paths, scan_time)
+ missing_count = mark_missing_sources_deleted(
+ sources_by_path, scan.seen_paths, scan_time
+ )
db.session.commit()
- pending_count = queue_pending(scan_time)
+ pending_count = enqueue_due_sends(scan_time)
current_app.logger.info(
"Webmention source scan complete: %d sources scanned, "
diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py
index cf8ab9d..c33cf06 100644
--- a/webmentions_ssg/tasks/sender.py
+++ b/webmentions_ssg/tasks/sender.py
@@ -19,20 +19,20 @@ from ..models import SentWebmention, SentWebmentionStatus
from ..net import (
AddressResolutionError,
UnsafeAddressError,
- build_client,
+ build_public_http_client,
is_http_url,
- is_temporary_status,
+ is_retryable_status,
)
from ..version import APP_NAME, VERSION
from .discovery import (
- PermanentSenderError,
- TemporarySenderError,
+ PermanentDeliveryError,
+ RetryableDeliveryError,
discover_webmention_endpoint,
post_webmention,
)
-def attempt_is_current(webmention: SentWebmention, revision: int) -> bool:
+def revision_still_pending(webmention: SentWebmention, revision: int) -> bool:
"""Check whether a send attempt still represents the desired revision.
The Webmention is refreshed from the database before comparing its desired
@@ -47,7 +47,7 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool:
return webmention.desired_revision == revision and webmention.pending
-def retry_delay(attempt: int) -> timedelta:
+def backoff_delay(attempt: int) -> timedelta:
"""Calculate the capped exponential delay after a numbered send attempt.
:param attempt: One-based send attempt number.
@@ -76,7 +76,7 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None:
# The pending/retry checks must happen *under* this lock.
try:
with huey.lock_task(f"send-webmention-{webmention_uuid}"):
- _send_locked(webmention_uuid)
+ _process_send_locked(webmention_uuid)
except TaskLockedException:
# Another worker is already sending this Webmention. The active worker
# owns its result; a later scan will requeue it if it remains pending.
@@ -84,12 +84,12 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None:
@dataclass(frozen=True)
-class SendAttempt:
+class ClaimedSendAttempt:
"""Claimed source revision and retry budget for one send."""
- identifier: uuid.UUID
+ webmention_uuid: uuid.UUID
revision: int
- number: int
+ attempt_number: int
max_attempts: int
source: str
target: str
@@ -112,7 +112,7 @@ class DeliveryResult:
temporary_failure: bool = False
-def is_due(webmention: SentWebmention, now: datetime) -> bool:
+def is_ready_to_send(webmention: SentWebmention, now: datetime) -> bool:
"""Return whether an unprocessed Webmention has reached its retry deadline.
:param webmention: Outgoing Webmention whose retry eligibility is checked.
@@ -130,7 +130,9 @@ def is_due(webmention: SentWebmention, now: datetime) -> bool:
return aware_deadline <= now
-def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | None:
+def reserve_send_attempt(
+ webmention: SentWebmention, now: datetime
+) -> ClaimedSendAttempt | None:
"""Atomically reserve one send attempt, or finish an exhausted revision.
An attempt's next retry deadline is persisted *before* the HTTP request so
@@ -172,10 +174,10 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
db.session.commit()
return None
- attempt = SendAttempt(
- identifier=webmention.uuid,
+ attempt = ClaimedSendAttempt(
+ webmention_uuid=webmention.uuid,
revision=revision,
- number=webmention.attempt_count + 1,
+ attempt_number=webmention.attempt_count + 1,
max_attempts=max_attempts,
source=webmention.source.url,
target=webmention.target,
@@ -183,9 +185,9 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
changed = db.session.execute(
sa.update(SentWebmention)
.where(
- SentWebmention.uuid == attempt.identifier,
+ SentWebmention.uuid == attempt.webmention_uuid,
SentWebmention.desired_revision == revision,
- SentWebmention.attempt_count == attempt.number - 1,
+ SentWebmention.attempt_count == attempt.attempt_number - 1,
SentWebmention.pending,
sa.or_(
SentWebmention.next_retry_at.is_(None),
@@ -193,9 +195,9 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
),
)
.values(
- attempt_count=attempt.number,
+ attempt_count=attempt.attempt_number,
last_attempted_at=now,
- next_retry_at=now + retry_delay(attempt.number),
+ next_retry_at=now + backoff_delay(attempt.attempt_number),
endpoint=None,
response_status=None,
status_url=None,
@@ -211,7 +213,7 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
return attempt
-def deliver_webmention(
+def attempt_delivery(
source: str, target: str, *, webmention_uuid: uuid.UUID
) -> DeliveryResult:
"""Discover and POST a Webmention, returning an outcome without DB writes.
@@ -227,9 +229,9 @@ def deliver_webmention(
try:
if not is_http_url(target):
- raise PermanentSenderError(f"Invalid target URL: {target!r}")
+ raise PermanentDeliveryError(f"Invalid target URL: {target!r}")
- with build_client(f"{APP_NAME}/{VERSION} SentWebmention") as client:
+ with build_public_http_client(f"{APP_NAME}/{VERSION} SentWebmention") as client:
endpoint = discover_webmention_endpoint(client, target)
if endpoint is None:
@@ -243,9 +245,9 @@ def deliver_webmention(
)
if not 200 <= response_status <= 299:
message = f"Webmention endpoint returned HTTP {response_status}"
- if is_temporary_status(response_status):
- raise TemporarySenderError(message)
- raise PermanentSenderError(message)
+ if is_retryable_status(response_status):
+ raise RetryableDeliveryError(message)
+ raise PermanentDeliveryError(message)
return DeliveryResult(
status=SentWebmentionStatus.SENT,
@@ -254,7 +256,7 @@ def deliver_webmention(
status_url=status_url,
)
except (
- PermanentSenderError,
+ PermanentDeliveryError,
UnsafeAddressError,
httpx.InvalidURL,
httpx.UnsupportedProtocol,
@@ -267,7 +269,7 @@ def deliver_webmention(
endpoint=endpoint,
response_status=response_status,
)
- except (TemporarySenderError, AddressResolutionError, httpx.RequestError) as exc:
+ except (RetryableDeliveryError, AddressResolutionError, httpx.RequestError) as exc:
return DeliveryResult(
status=SentWebmentionStatus.FAILED,
reason=str(exc) or "Webmention request failed",
@@ -289,9 +291,9 @@ def deliver_webmention(
)
-def record_outcome(
+def record_delivery_outcome(
webmention: SentWebmention,
- attempt: SendAttempt,
+ attempt: ClaimedSendAttempt,
result: DeliveryResult,
*,
terminal: bool,
@@ -305,7 +307,7 @@ def record_outcome(
:returns: ``True`` if the outcome was recorded for the current revision.
"""
# A scanner may have reopened or superseded the revision during I/O.
- if not attempt_is_current(webmention, attempt.revision):
+ if not revision_still_pending(webmention, attempt.revision):
return False
webmention.status = result.status
@@ -330,7 +332,7 @@ def record_outcome(
return True
-def _send_locked(webmention_uuid: uuid.UUID) -> bool:
+def _process_send_locked(webmention_uuid: uuid.UUID) -> bool:
"""Process a due Webmention while holding its per-UUID task lock.
:param webmention_uuid: Identifier of the outgoing Webmention being processed.
@@ -344,18 +346,18 @@ def _send_locked(webmention_uuid: uuid.UUID) -> bool:
return False
now = datetime.now(UTC)
- if not is_due(webmention, now):
+ if not is_ready_to_send(webmention, now):
return False
- if (attempt := claim_attempt(webmention, now)) is None:
+ if (attempt := reserve_send_attempt(webmention, now)) is None:
return False
- result = deliver_webmention(
+ result = attempt_delivery(
attempt.source, attempt.target, webmention_uuid=webmention_uuid
)
- terminal = result.terminal or attempt.number >= attempt.max_attempts
+ terminal = result.terminal or attempt.attempt_number >= attempt.max_attempts
- if not record_outcome(webmention, attempt, result, terminal=terminal):
+ if not record_delivery_outcome(webmention, attempt, result, terminal=terminal):
return False
if result.temporary_failure and not terminal:
@@ -363,13 +365,13 @@ def _send_locked(webmention_uuid: uuid.UUID) -> bool:
current_app.logger.info(
"Webmention %s send attempt %d failed; will retry",
webmention_uuid,
- attempt.number,
+ attempt.attempt_number,
)
elif result.temporary_failure:
current_app.logger.warning(
"Webmention %s exhausted %d send attempts: %s",
webmention_uuid,
- attempt.number,
+ attempt.attempt_number,
result.reason,
)
diff --git a/webmentions_ssg/tasks/source_parser.py b/webmentions_ssg/tasks/source_parser.py
index 31d0c98..e063525 100644
--- a/webmentions_ssg/tasks/source_parser.py
+++ b/webmentions_ssg/tasks/source_parser.py
@@ -18,11 +18,11 @@ import xxhash
from bs4 import BeautifulSoup, Tag
from bs4.element import NavigableString, PageElement
-from ..net import hostname_of, is_http_url
+from ..net import is_http_url, normalized_hostname
REACTION_PROPERTIES = ("in-reply-to", "like-of", "repost-of", "bookmark-of")
-CONTENT_BLOCK_TAGS = frozenset(
+BLOCK_LEVEL_TAGS = frozenset(
{
"address",
"article",
@@ -83,7 +83,7 @@ def source_url_for_path(relative_path: Path, base_url: str) -> str:
return urljoin(base_url, f"{quote(directory, safe='/')}/")
-def canonical_url(
+def declared_canonical_url(
document: BeautifulSoup, *, relative_path: Path, base_url: str | None
) -> str | None:
"""Return the canonical URL declared by a source document.
@@ -111,7 +111,7 @@ def canonical_url(
if base_url is None:
raise SourceScanError(
"Document contains a relative canonical URL, but "
- "SOURCE_BASE_URL is not configured"
+ "SITE_BASE_URL is not configured"
)
resolved = urljoin(source_url_for_path(relative_path, base_url), href)
@@ -124,7 +124,7 @@ def canonical_url(
return resolved
-def property_urls(entry: dict[str, Any], property_name: str) -> Iterator[str]:
+def mf2_string_values(entry: dict[str, Any], property_name: str) -> Iterator[str]:
"""Yield URL values from a microformats property.
:param entry: Parsed microformats entry.
@@ -144,7 +144,7 @@ def property_urls(entry: dict[str, Any], property_name: str) -> Iterator[str]:
yield from (value for value in values if isinstance(value, str))
-def parse_entry(element: Tag, base_url: str) -> dict[str, Any]:
+def parse_h_entry(element: Tag, base_url: str) -> dict[str, Any]:
"""Parse and validate an h-entry with mf2py.
:param element: HTML element containing the h-entry.
@@ -175,7 +175,7 @@ def parse_entry(element: Tag, base_url: str) -> dict[str, Any]:
return entry
-def primary_entry(
+def find_primary_h_entry(
document: BeautifulSoup, source_url: str
) -> tuple[Tag, dict[str, Any]]:
"""Return and validate the primary h-entry of a source document.
@@ -195,9 +195,9 @@ def primary_entry(
raise SourceScanError(f"Expected exactly one h-entry, found {len(entries)}")
entry_element = entries[0]
- mf2_entry = parse_entry(entry_element, source_url)
+ mf2_entry = parse_h_entry(entry_element, source_url)
- urls = tuple(property_urls(mf2_entry, "url"))
+ urls = tuple(mf2_string_values(mf2_entry, "url"))
if source_url not in urls:
raise SourceScanError(
@@ -207,15 +207,15 @@ def primary_entry(
return entry_element, mf2_entry
-def content_element(entry: Tag) -> Tag:
+def find_e_content(entry_element: Tag) -> Tag:
"""Return the e-content element of an h-entry.
- :param entry: HTML element containing the h-entry.
+ :param entry_element: HTML element containing the h-entry.
:returns: The h-entry's e-content element.
:raises SourceScanError: If the h-entry does not contain exactly one e-content
element.
"""
- contents = entry.find_all(class_="e-content")
+ contents = entry_element.find_all(class_="e-content")
if len(contents) != 1:
raise SourceScanError(f"Expected exactly one e-content, found {len(contents)}")
@@ -223,7 +223,7 @@ def content_element(entry: Tag) -> Tag:
return contents[0]
-def normalize_target(value: str, *, base_url: str, source_url: str) -> str | None:
+def normalize_target_url(value: str, *, base_url: str, source_url: str) -> str | None:
"""Resolve and validate a possible Webmention target URL.
Empty values, non-HTTP URLs, and URLs referring to the source itself are
@@ -249,7 +249,7 @@ def normalize_target(value: str, *, base_url: str, source_url: str) -> str | Non
return target
-def iter_targets(
+def iter_outgoing_targets(
content: Tag,
mf2_entry: dict[str, Any],
*,
@@ -277,18 +277,19 @@ def iter_targets(
)
reactions = chain.from_iterable(
- property_urls(mf2_entry, property_name) for property_name in REACTION_PROPERTIES
+ mf2_string_values(mf2_entry, property_name)
+ for property_name in REACTION_PROPERTIES
)
for value in chain(hrefs, reactions):
- target = normalize_target(value, base_url=base_url, source_url=source_url)
+ target = normalize_target_url(value, base_url=base_url, source_url=source_url)
if target is not None:
- hostname = hostname_of(target) or ""
+ hostname = normalized_hostname(target) or ""
if not any(fnmatchcase(hostname, pattern) for pattern in ignored_hostnames):
yield target
-def normalized_content(content: Tag) -> str:
+def stable_content_text(content: Tag) -> str:
"""Extract stable reader-facing content without generated HTML attributes.
:param content: Parsed e-content element to normalize.
@@ -312,7 +313,7 @@ def normalized_content(content: Tag) -> str:
return f" [image:{node.get('src', '')!s}:{node.get('alt', '')!s}] "
text = "".join(extract(child) for child in node.children)
- return f" {text} " if node.name in CONTENT_BLOCK_TAGS else text
+ return f" {text} " if node.name in BLOCK_LEVEL_TAGS else text
return " ".join(extract(content).split())
@@ -346,22 +347,24 @@ def scan_source_file(
relative_path = path.relative_to(root)
document = BeautifulSoup(resolved_path.read_bytes(), "html5lib")
- source_url = canonical_url(document, relative_path=relative_path, base_url=base_url)
+ source_url = declared_canonical_url(
+ document, relative_path=relative_path, base_url=base_url
+ )
if source_url is None:
if base_url is None:
raise SourceScanError(
- "Document has no canonical URL and SOURCE_BASE_URL is not configured"
+ "Document has no canonical URL and SITE_BASE_URL is not configured"
)
source_url = source_url_for_path(relative_path, base_url)
- entry_element, mf2_entry = primary_entry(document, source_url)
+ entry_element, mf2_entry = find_primary_h_entry(document, source_url)
- content = content_element(entry_element)
+ content = find_e_content(entry_element)
targets = frozenset(
- iter_targets(
+ iter_outgoing_targets(
content,
mf2_entry,
base_url=source_url,
@@ -370,7 +373,7 @@ def scan_source_file(
)
)
- stable_content = normalized_content(content)
+ stable_content = stable_content_text(content)
fingerprint = json.dumps(
{"content": stable_content, "targets": sorted(targets)},
ensure_ascii=False,
diff --git a/webmentions_ssg/tasks/mentions.py b/webmentions_ssg/tasks/target_matching.py
index 4c3918b..4c3918b 100644
--- a/webmentions_ssg/tasks/mentions.py
+++ b/webmentions_ssg/tasks/target_matching.py
diff --git a/webmentions_ssg/templates/base.html b/webmentions_ssg/templates/base.html
index 19412ed..69e5215 100644
--- a/webmentions_ssg/templates/base.html
+++ b/webmentions_ssg/templates/base.html
@@ -32,7 +32,8 @@ SPDX-License-Identifier: BSD-3-Clause
<header>
<nav class="navbar bg-primary py-1">
<div class="container-fluid px-3">
- <a class="navbar-brand fs-6 mb-0" href="{{ url_for('root.index') }}">
+ <a class="navbar-brand fs-6 mb-0"
+ href="{{ url_for('webmentions.index') }}">
<img src="{{ url_for('static', filename='images/logo.svg') }}"
width="30"
height="30"
@@ -42,11 +43,13 @@ SPDX-License-Identifier: BSD-3-Clause
</a>
{% if current_user.is_authenticated %}
<div class="navbar-nav flex-row gap-3">
- <a class="nav-link{% if request.endpoint == 'root.received' %} active{% endif %}"
- href='{{ url_for("root.received") }}'>Received</a>
- <a class="nav-link{% if request.endpoint == 'root.sent' %} active{% endif %}"
- href='{{ url_for("root.sent") }}'>Sent</a>
- <form action="{{ url_for('root.logout') }}" method="post" class="m-0">
+ <a class="nav-link{% if request.endpoint == 'webmentions.received_list' %} active{% endif %}"
+ href='{{ url_for("webmentions.received_list") }}'>Received</a>
+ <a class="nav-link{% if request.endpoint == 'webmentions.source_list' %} active{% endif %}"
+ href='{{ url_for("webmentions.source_list") }}'>Sent</a>
+ <form action="{{ url_for('webmentions.logout') }}"
+ method="post"
+ class="m-0">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="nav-link border-0 bg-transparent">Logout</button>
</form>
diff --git a/webmentions_ssg/templates/received.html b/webmentions_ssg/templates/received.html
index 3dbb896..f00a5f9 100644
--- a/webmentions_ssg/templates/received.html
+++ b/webmentions_ssg/templates/received.html
@@ -79,7 +79,7 @@ SPDX-License-Identifier: BSD-3-Clause
class="btn btn-sm btn-primary"
data-bs-toggle="modal"
data-bs-target="#confirmation-modal"
- data-action="{{ url_for('root.reverify_received_webmention', identifier=webmention.uuid, page=webmentions.page) }}"
+ data-action="{{ url_for('webmentions.reverify_received_webmention', webmention_uuid=webmention.uuid, page=webmentions.page) }}"
data-title="Reverify webmention?"
data-message="The webmention will be fetched and verified again."
data-confirm-label="Reverify"
@@ -88,7 +88,7 @@ SPDX-License-Identifier: BSD-3-Clause
class="btn btn-sm btn-danger"
data-bs-toggle="modal"
data-bs-target="#confirmation-modal"
- data-action="{{ url_for('root.delete_received_webmention', identifier=webmention.uuid, page=webmentions.page) }}"
+ data-action="{{ url_for('webmentions.delete_received_webmention', webmention_uuid=webmention.uuid, page=webmentions.page) }}"
data-title="Delete webmention?"
data-message="This permanently deletes the webmention and cannot be undone."
data-confirm-label="Delete"
diff --git a/webmentions_ssg/templates/sent.html b/webmentions_ssg/templates/sent.html
index c9662b9..2b0fbe4 100644
--- a/webmentions_ssg/templates/sent.html
+++ b/webmentions_ssg/templates/sent.html
@@ -16,7 +16,7 @@ SPDX-License-Identifier: BSD-3-Clause
class="btn btn-sm btn-primary"
data-bs-toggle="modal"
data-bs-target="#confirmation-modal"
- data-action="{{ url_for('root.rescan_sent_sources') }}"
+ data-action="{{ url_for('webmentions.rescan_sources') }}"
data-title="Rescan sources?"
data-message="All sources will be scanned again for changes and webmentions."
data-confirm-label="Rescan"
@@ -49,7 +49,7 @@ SPDX-License-Identifier: BSD-3-Clause
{% endif %}
<tr class="{{ row_class }}">
<td class="text-nowrap">
- <a href="{{ url_for('root.sent_source', source_identifier=source.uuid) }}">{{ source.path }}</a>
+ <a href="{{ url_for('webmentions.source_detail', source_uuid=source.uuid) }}">{{ source.path }}</a>
</td>
<td class="text-break">
<a href="{{ source.url }}">{{ source.url }}</a>
diff --git a/webmentions_ssg/templates/sent_source.html b/webmentions_ssg/templates/sent_source.html
index 974c7b3..31d5c81 100644
--- a/webmentions_ssg/templates/sent_source.html
+++ b/webmentions_ssg/templates/sent_source.html
@@ -26,7 +26,7 @@ SPDX-License-Identifier: BSD-3-Clause
{% block content %}
<div class="mb-3">
- <a href="{{ url_for('root.sent') }}">← Back to sources</a>
+ <a href="{{ url_for('webmentions.source_list') }}">← Back to sources</a>
</div>
<div class="d-flex justify-content-between align-items-start mb-3">
<h1 class="mb-0">Source Details</h1>
@@ -191,7 +191,7 @@ SPDX-License-Identifier: BSD-3-Clause
class="btn btn-sm btn-primary"
data-bs-toggle="modal"
data-bs-target="#confirmation-modal"
- data-action="{{ url_for('root.resend_sent_webmention', source_identifier=source.uuid, webmention_identifier=webmention.uuid) }}"
+ data-action="{{ url_for('webmentions.resend_webmention', source_uuid=source.uuid, webmention_uuid=webmention.uuid) }}"
data-title="Resend Webmention?"
data-message="This Webmention will be queued again for delivery to {{ webmention.target }}."
data-confirm-label="Resend"
diff --git a/webmentions_ssg/views/__init__.py b/webmentions_ssg/views/__init__.py
index ffe9a27..7f091f0 100644
--- a/webmentions_ssg/views/__init__.py
+++ b/webmentions_ssg/views/__init__.py
@@ -2,9 +2,9 @@
#
# SPDX-License-Identifier: BSD-3-Clause
-"""Collect and expose the routes for the historic root Blueprint."""
+"""Collect and expose the routes for the blueprint."""
from . import admin, endpoint, session
-from .blueprint import root_page
+from .blueprint import webmentions_bp
-__all__ = ["admin", "endpoint", "root_page", "session"]
+__all__ = ["admin", "endpoint", "session", "webmentions_bp"]
diff --git a/webmentions_ssg/views/admin.py b/webmentions_ssg/views/admin.py
index 2ccd92a..9b7c418 100644
--- a/webmentions_ssg/views/admin.py
+++ b/webmentions_ssg/views/admin.py
@@ -19,12 +19,12 @@ from ..models import ReceivedWebmention, SentWebmention, Source
from ..tasks.receiver import verify_webmention
from ..tasks.scanner import manual_scan_sources
from ..tasks.sender import send_webmention
-from .blueprint import root_page
+from .blueprint import webmentions_bp
-@root_page.route("/received")
+@webmentions_bp.route("/received")
@login_required
-def received() -> ResponseReturnValue:
+def received_list() -> ResponseReturnValue:
"""Display received Webmentions.
:returns: Rendered page containing the paginated received Webmentions.
@@ -38,22 +38,22 @@ def received() -> ResponseReturnValue:
"received.html",
title="Received Webmentions",
webmentions=webmentions,
- action_form=forms.AdminActionForm(),
+ action_form=forms.ConfirmActionForm(),
)
-@root_page.post("/received/<uuid:identifier>/delete")
+@webmentions_bp.post("/received/<uuid:webmention_uuid>/delete")
@login_required
-def delete_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
+def delete_received_webmention(webmention_uuid: uuid.UUID) -> ResponseReturnValue:
"""Delete a received Webmention.
- :param identifier: Identifier of the Webmention to delete.
+ :param webmention_uuid: UUID of the Webmention to delete.
:returns: Redirect response to the received Webmentions view.
"""
- if not forms.AdminActionForm().validate_on_submit():
+ if not forms.ConfirmActionForm().validate_on_submit():
abort(HTTPStatus.BAD_REQUEST)
- webmention = db.get_or_404(ReceivedWebmention, identifier)
+ webmention = db.get_or_404(ReceivedWebmention, webmention_uuid)
db.session.delete(webmention)
db.session.commit()
@@ -61,41 +61,41 @@ def delete_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
flash(f"Webmention {webmention.uuid} deleted.", "success")
return redirect(
- url_for("root.received", page=request.args.get("page", 1, type=int))
+ url_for("webmentions.received_list", page=request.args.get("page", 1, type=int))
)
-@root_page.post("/received/<uuid:identifier>/reverify")
+@webmentions_bp.post("/received/<uuid:webmention_uuid>/reverify")
@login_required
-def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
+def reverify_received_webmention(webmention_uuid: uuid.UUID) -> ResponseReturnValue:
"""Queue a received Webmention for reverification.
The Webmention status is reset before a new verification task is queued.
- :param identifier: Identifier of the Webmention to reverify.
+ :param webmention_uuid: UUID of the Webmention to reverify.
:returns: Redirect response to the received Webmentions view.
"""
- if not forms.AdminActionForm().validate_on_submit():
+ if not forms.ConfirmActionForm().validate_on_submit():
abort(HTTPStatus.BAD_REQUEST)
- webmention = db.get_or_404(ReceivedWebmention, identifier)
+ webmention = db.get_or_404(ReceivedWebmention, webmention_uuid)
webmention.reset_for_verification()
db.session.commit()
- verify_webmention(identifier)
+ verify_webmention(webmention_uuid)
flash(f"Webmention {webmention.uuid} queued for reverification.", "success")
return redirect(
- url_for("root.received", page=request.args.get("page", 1, type=int))
+ url_for("webmentions.received_list", page=request.args.get("page", 1, type=int))
)
-@root_page.route("/sent")
+@webmentions_bp.route("/sources")
@login_required
-def sent() -> ResponseReturnValue:
+def source_list() -> ResponseReturnValue:
"""Display sources with sent Webmentions.
:returns: Rendered page containing the paginated source list.
@@ -110,35 +110,35 @@ def sent() -> ResponseReturnValue:
"sent.html",
title="Sent Webmentions",
sources=sources,
- action_form=forms.AdminActionForm(),
+ action_form=forms.ConfirmActionForm(),
)
-@root_page.post("/sent/rescan")
+@webmentions_bp.post("/sources/rescan")
@login_required
-def rescan_sent_sources() -> ResponseReturnValue:
+def rescan_sources() -> ResponseReturnValue:
"""Queue a manual scan of sent Webmention sources.
:returns: Redirect response to the sent Webmentions view.
"""
- if not forms.AdminActionForm().validate_on_submit():
+ if not forms.ConfirmActionForm().validate_on_submit():
abort(HTTPStatus.BAD_REQUEST)
manual_scan_sources()
flash("Source rescan queued.", "success")
- return redirect(url_for("root.sent"))
+ return redirect(url_for("webmentions.source_list"))
-@root_page.route("/sent/<uuid:source_identifier>")
+@webmentions_bp.route("/sources/<uuid:source_uuid>")
@login_required
-def sent_source(source_identifier: uuid.UUID) -> ResponseReturnValue:
+def source_detail(source_uuid: uuid.UUID) -> ResponseReturnValue:
"""Display the sent Webmentions associated with a source.
- :param source_identifier: Identifier of the source to display.
+ :param source_uuid: UUID of the source to display.
:returns: Rendered source details page.
"""
- source = db.get_or_404(Source, source_identifier)
+ source = db.get_or_404(Source, source_uuid)
webmentions = db.paginate(
sa.select(SentWebmention)
@@ -152,14 +152,14 @@ def sent_source(source_identifier: uuid.UUID) -> ResponseReturnValue:
title="Sent Webmentions",
source=source,
webmentions=webmentions,
- action_form=forms.AdminActionForm(),
+ action_form=forms.ConfirmActionForm(),
)
-@root_page.post("/sent/<uuid:source_identifier>/<uuid:webmention_identifier>/resend")
+@webmentions_bp.post("/sources/<uuid:source_uuid>/<uuid:webmention_uuid>/resend")
@login_required
-def resend_sent_webmention(
- source_identifier: uuid.UUID, webmention_identifier: uuid.UUID
+def resend_webmention(
+ source_uuid: uuid.UUID, webmention_uuid: uuid.UUID
) -> ResponseReturnValue:
"""Queue an outgoing Webmention to be sent again.
@@ -168,16 +168,16 @@ def resend_sent_webmention(
successful-send fields are preserved, while result fields from the previous
attempt are cleared.
- :param source_identifier: Identifier of the source owning the Webmention.
- :param webmention_identifier: Identifier of the sent Webmention to resend.
+ :param source_uuid: UUID of the source owning the Webmention.
+ :param webmention_uuid: UUID of the sent Webmention to resend.
:returns: Redirect response to the source details view.
"""
- if not forms.AdminActionForm().validate_on_submit():
+ if not forms.ConfirmActionForm().validate_on_submit():
abort(HTTPStatus.BAD_REQUEST)
- webmention = db.get_or_404(SentWebmention, webmention_identifier)
+ webmention = db.get_or_404(SentWebmention, webmention_uuid)
- if webmention.source_id != source_identifier:
+ if webmention.source_id != source_uuid:
abort(HTTPStatus.NOT_FOUND)
# Requeue the existing desired revision instead of inventing a new source
@@ -187,8 +187,8 @@ def resend_sent_webmention(
db.session.commit()
- send_webmention(webmention_identifier)
+ send_webmention(webmention_uuid)
flash(f"Webmention {webmention.uuid} queued for resend.", "success")
- return redirect(url_for("root.sent_source", source_identifier=source_identifier))
+ return redirect(url_for("webmentions.source_detail", source_uuid=source_uuid))
diff --git a/webmentions_ssg/views/blueprint.py b/webmentions_ssg/views/blueprint.py
index 136d319..6d1e404 100644
--- a/webmentions_ssg/views/blueprint.py
+++ b/webmentions_ssg/views/blueprint.py
@@ -6,4 +6,4 @@
from flask import Blueprint
-root_page = Blueprint("root", __name__)
+webmentions_bp = Blueprint("webmentions", __name__)
diff --git a/webmentions_ssg/views/endpoint.py b/webmentions_ssg/views/endpoint.py
index 06740e5..be2a9ab 100644
--- a/webmentions_ssg/views/endpoint.py
+++ b/webmentions_ssg/views/endpoint.py
@@ -19,14 +19,14 @@ from ..db_helpers import rows_affected
from ..extensions import csrf, db, limiter
from ..models import ReceivedWebmention, received_url_digest
from ..tasks.receiver import verify_webmention
-from .blueprint import root_page
+from .blueprint import webmentions_bp
class UrlDigestCollisionError(Exception):
"""The URL digest already belongs to a different source/target pair."""
-def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention | None:
+def find_received_webmention(source: str, target: str) -> ReceivedWebmention | None:
"""Return the matching Webmention, or raise on a SHA-256 collision.
:param source: Exact source URL to look up.
@@ -50,7 +50,9 @@ def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention |
return webmention
-def insert_webmention(source: str, target: str) -> ReceivedWebmention | None:
+def try_insert_received_webmention(
+ source: str, target: str
+) -> ReceivedWebmention | None:
"""Insert and return a Webmention, or None if another request won the race.
Use an atomic insert and treat uniqueness conflicts as concurrent submissions.
@@ -71,7 +73,7 @@ def insert_webmention(source: str, target: str) -> ReceivedWebmention | None:
return webmention
-def reopen_if_cooled_down(webmention: ReceivedWebmention) -> bool:
+def reopen_if_cooldown_elapsed(webmention: ReceivedWebmention) -> bool:
"""Atomically reopen an old Webmention and return whether it was reopened.
Only a terminal Webmention beyond the cooldown interval can be reset.
@@ -97,7 +99,7 @@ def reopen_if_cooled_down(webmention: ReceivedWebmention) -> bool:
return rows_affected(result) == 1
-def submit_received(source: str, target: str) -> tuple[uuid.UUID, bool] | None:
+def record_submission(source: str, target: str) -> tuple[uuid.UUID, bool] | None:
"""Return (identifier, enqueue flag), or None on a digest conflict.
A new submission is committed before it can be queued for verification.
@@ -110,26 +112,28 @@ def submit_received(source: str, target: str) -> tuple[uuid.UUID, bool] | None:
:returns: Webmention identifier and enqueue flag, or ``None`` on a digest collision.
"""
try:
- if (webmention := find_webmention_by_digest(source, target)) is None:
- if (webmention := insert_webmention(source, target)) is not None:
+ if (webmention := find_received_webmention(source, target)) is None:
+ if (
+ webmention := try_insert_received_webmention(source, target)
+ ) is not None:
return webmention.uuid, True
# A concurrent insert won: look up its row after rolling back.
- if (webmention := find_webmention_by_digest(source, target)) is None:
+ if (webmention := find_received_webmention(source, target)) is None:
return None
- return webmention.uuid, reopen_if_cooled_down(webmention)
+ return webmention.uuid, reopen_if_cooldown_elapsed(webmention)
except UrlDigestCollisionError:
return None
-@root_page.post("/endpoint")
+@webmentions_bp.post("/endpoint")
@limiter.limit(
lambda: current_app.config["ENDPOINT_GLOBAL_RATE_LIMIT"],
key_func=lambda: "all-clients",
)
@limiter.limit(lambda: current_app.config["ENDPOINT_RATE_LIMIT"])
@csrf.exempt
-def endpoint() -> ResponseReturnValue:
+def receive_webmention() -> ResponseReturnValue:
"""Receive and queue a Webmention for verification.
Existing Webmentions with the same source and target are reset for
@@ -139,7 +143,7 @@ def endpoint() -> ResponseReturnValue:
:returns: HTTP 201 response with the Webmention status URL in the ``Location``
header, or validation errors with HTTP 400.
"""
- form = forms.EndpointForm(meta={"csrf": False})
+ form = forms.WebmentionSubmissionForm(meta={"csrf": False})
if not form.validate_on_submit():
return form.errors, HTTPStatus.BAD_REQUEST
@@ -147,7 +151,7 @@ def endpoint() -> ResponseReturnValue:
source = cast(str, form.source.data)
target = cast(str, form.target.data)
- result = submit_received(source, target)
+ result = record_submission(source, target)
if result is None:
return {"error": "Webmention URL fingerprint conflict"}, HTTPStatus.CONFLICT
@@ -157,13 +161,15 @@ def endpoint() -> ResponseReturnValue:
if should_verify:
verify_webmention(identifier)
- status_url = url_for("root.status", identifier=str(identifier), _external=True)
+ status_url = url_for(
+ "webmentions.webmention_status", identifier=str(identifier), _external=True
+ )
return Response(status=HTTPStatus.CREATED, headers={"Location": status_url})
-@root_page.route("/status/<uuid:identifier>")
-def status(identifier: uuid.UUID) -> ResponseReturnValue:
+@webmentions_bp.route("/status/<uuid:identifier>")
+def webmention_status(identifier: uuid.UUID) -> ResponseReturnValue:
"""Display the verification status of a received Webmention.
:param identifier: Identifier of the Webmention to display.
diff --git a/webmentions_ssg/views/session.py b/webmentions_ssg/views/session.py
index 371997d..d9cec7f 100644
--- a/webmentions_ssg/views/session.py
+++ b/webmentions_ssg/views/session.py
@@ -11,25 +11,25 @@ from flask_login import current_user, login_required, login_user, logout_user
from werkzeug.security import check_password_hash
from .. import forms
-from ..auth import dummy_password_hash, is_safe_next_url, login_username_limit_key
+from ..auth import dummy_password_hash, is_safe_next_url, login_username_rate_limit_key
from ..extensions import db, limiter
from ..models import User
-from .blueprint import root_page
+from .blueprint import webmentions_bp
-@root_page.route("/")
+@webmentions_bp.route("/")
def index() -> ResponseReturnValue:
"""Redirect to the received Webmentions view.
:returns: Redirect response to the received Webmentions view.
"""
- return redirect(url_for("root.received"))
+ return redirect(url_for("webmentions.received_list"))
-@root_page.route("/login", methods=["GET", "POST"])
+@webmentions_bp.route("/login", methods=["GET", "POST"])
@limiter.limit(
lambda: current_app.config["LOGIN_USERNAME_RATE_LIMIT"],
- key_func=login_username_limit_key,
+ key_func=login_username_rate_limit_key,
methods=["POST"],
error_message="Too many login attempts. Please try again later.",
)
@@ -48,7 +48,7 @@ def login() -> ResponseReturnValue:
:returns: Rendered login page or redirect response.
"""
if current_user.is_authenticated:
- return redirect(url_for("root.index"))
+ return redirect(url_for("webmentions.index"))
form = forms.LoginForm()
@@ -61,18 +61,18 @@ def login() -> ResponseReturnValue:
password_ok = check_password_hash(password_hash, form.password.data or "")
if user is None or not password_ok:
flash("Invalid username or password", "danger")
- return redirect(url_for("root.login"))
+ return redirect(url_for("webmentions.login"))
login_user(user)
next_url = request.args.get("next")
if not next_url or not is_safe_next_url(next_url):
- next_url = url_for("root.index")
+ next_url = url_for("webmentions.index")
return redirect(next_url)
return render_template("login.html", form=form)
-@root_page.route("/logout", methods=("POST",))
+@webmentions_bp.route("/logout", methods=("POST",))
@login_required
def logout() -> ResponseReturnValue:
"""End the current user's login session.
@@ -80,4 +80,4 @@ def logout() -> ResponseReturnValue:
:returns: Redirect response to the application index.
"""
logout_user()
- return redirect(url_for("root.index"))
+ return redirect(url_for("webmentions.index"))