diff options
| author | Dennis Fink | 2026-11-12 23:34:46 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-12 23:37:08 +0100 |
| commit | 52fc66cb5ff19bf0def001ae50acc1b465a0b977 (patch) | |
| tree | e791fa3e6d9f9b1b6fdf697f821adc84d2a57f0b | |
| parent | b439de2005b70ec3867d589d1f4c63b83441e620 (diff) | |
| download | webmentions-ssg-52fc66cb5ff19bf0def001ae50acc1b465a0b977.tar.gz webmentions-ssg-52fc66cb5ff19bf0def001ae50acc1b465a0b977.zip | |
fix(core): decouple task imports from app initialization
Keep stable lazy task handles that register against the active Huey
backend so modules can be imported before app creation and survive
backend reinitialization.
Separate package metadata and the shared blueprint from application
startup to remove import-order dependencies and keep build-time version
lookup lightweight.
| -rw-r--r-- | pyproject.toml | 2 | ||||
| -rw-r--r-- | tests/tasks/test_extension.py | 61 | ||||
| -rw-r--r-- | tests/tasks/test_notifications.py | 18 | ||||
| -rw-r--r-- | tests/tasks/test_scanner.py | 3 | ||||
| -rw-r--r-- | tests/test_init.py | 25 | ||||
| -rw-r--r-- | tests/test_packaging.py | 8 | ||||
| -rw-r--r-- | webmentions_ssg/__init__.py | 9 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/consumer.py | 25 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/extension.py | 93 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/notifications.py | 8 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/receiver.py | 2 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/scanner.py | 4 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/sender.py | 2 | ||||
| -rw-r--r-- | webmentions_ssg/version.py | 8 | ||||
| -rw-r--r-- | webmentions_ssg/views/__init__.py | 14 | ||||
| -rw-r--r-- | webmentions_ssg/views/admin.py | 2 | ||||
| -rw-r--r-- | webmentions_ssg/views/blueprint.py | 9 | ||||
| -rw-r--r-- | webmentions_ssg/views/endpoint.py | 2 | ||||
| -rw-r--r-- | webmentions_ssg/views/session.py | 2 |
19 files changed, 242 insertions, 55 deletions
diff --git a/pyproject.toml b/pyproject.toml index 34c0527..14c5932 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -81,7 +81,7 @@ requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.version] -path = "webmentions_ssg/__init__.py" +path = "webmentions_ssg/version.py" [tool.hatch.build.targets.wheel] packages = ["webmentions_ssg"] diff --git a/tests/tasks/test_extension.py b/tests/tasks/test_extension.py index 19f1191..a2495e8 100644 --- a/tests/tasks/test_extension.py +++ b/tests/tasks/test_extension.py @@ -8,7 +8,7 @@ from typing import Any import huey as huey_package import pytest -from flask import Flask, has_app_context +from flask import Flask, current_app, has_app_context from huey import crontab from webmentions_ssg.tasks.extension import Huey @@ -94,6 +94,65 @@ def test_task_raises_without_app(app: Flask, periodic: bool) -> None: task.call_local() +@pytest.mark.parametrize("periodic", [False, True], ids=["task", "periodic-task"]) +def test_task_declaration_before_init_and_rebind_after_init(periodic: bool) -> None: + """Imported task handles do not capture the first application backend.""" + queue = Huey() + observed_apps: list[str] = [] + + @task_decorator(queue, periodic) + def identify_app() -> str: + name = current_app.import_name + observed_apps.append(name) + return name + + assert identify_app.__name__ == "identify_app" + with pytest.raises(RuntimeError, match="Huey has not been initialized"): + identify_app.call_local() + + first = Flask("first") + first.config["TESTING"] = True + queue.init_app(first) + assert identify_app.call_local() == "first" + # Huey discards periodic-task results, even in immediate mode. Verify + # execution through a side effect as well as the returned result. + assert identify_app().get() == (None if periodic else "first") + assert observed_apps == ["first", "first"] + + previous_backend = queue.huey + second = Flask("second") + second.config["TESTING"] = True + queue.init_app(second) + + assert queue.huey is not previous_backend + assert identify_app.call_local() == "second" + assert identify_app().get() == (None if periodic else "second") + assert observed_apps == ["first", "first", "second", "second"] + # The new broker must recognize the registered task when deserializing work. + queued = identify_app.s() + restored = queue.huey.deserialize_task(queue.huey.serialize_task(queued)) + assert type(restored) is type(queued) + + +def test_multiple_deferred_tasks_registered_on_initialization() -> None: + queue = Huey() + + @queue.task(retries=2, retry_delay=50) + def first(value: int) -> int: + return value + 1 + + @queue.task() + def second(value: int) -> int: + return first.call_local(value) + 1 + + app = Flask("tasks") + app.config["TESTING"] = True + queue.init_app(app) + + assert second(2).get() == 4 + assert first.call_local(2) == 3 + + def test_getattr_delegates_to_huey(app: Flask) -> None: huey = Huey(app) assert huey.immediate is True diff --git a/tests/tasks/test_notifications.py b/tests/tasks/test_notifications.py index 0254b19..f87fd47 100644 --- a/tests/tasks/test_notifications.py +++ b/tests/tasks/test_notifications.py @@ -9,8 +9,10 @@ from unittest.mock import patch import pytest from flask import Flask +from huey.exceptions import TaskLockedException from webmentions_ssg import db +from webmentions_ssg.extensions import huey from webmentions_ssg.models import ReceivedWebmention @@ -128,3 +130,19 @@ def test_digest_skips_when_no_new_mentions( notifications.send_webmention_digest() send.assert_not_called() + + +def test_digest_lock_uses_current_backend( + notifications: ModuleType, app: Flask +) -> None: + """A digest imported before reinitialization uses the new backend's lock.""" + with app.app_context(): + previous_backend = huey.huey + huey.init_app(app) + assert huey.huey is not previous_backend + + with ( + huey.lock_task("send-webmention-digest"), + pytest.raises(TaskLockedException), + ): + notifications.send_webmention_digest() diff --git a/tests/tasks/test_scanner.py b/tests/tasks/test_scanner.py index d11b3f2..c0b9223 100644 --- a/tests/tasks/test_scanner.py +++ b/tests/tasks/test_scanner.py @@ -42,8 +42,7 @@ def test_manual_scan_retries_when_periodic_scan_holds_lock( app: Flask, scanner_module: ModuleType ) -> None: with app.app_context(): - # Import-time decorators previously captured an old backend here, - # making this test pass or fail depending on module import order. + # A task imported earlier must still use the reinitialized backend. previous_backend = scanner_module.huey.huey scanner_module.huey.init_app(app) assert scanner_module.huey.huey is not previous_backend diff --git a/tests/test_init.py b/tests/test_init.py index 7112654..ccfdfd8 100644 --- a/tests/test_init.py +++ b/tests/test_init.py @@ -4,6 +4,9 @@ """Test application initialization and its public integrations.""" +import subprocess +import sys + from flask import Flask from webmentions_ssg import VERSION, huey @@ -22,3 +25,25 @@ def test_create_app_exposes_version_in_templates(app: Flask) -> None: app.update_template_context(context) assert context["VERSION"] == VERSION + + +def test_importing_views_and_tasks_before_creating_app() -> None: + """Module imports alone must never need an initialized Huey backend.""" + script = """ +from webmentions_ssg import huey +from webmentions_ssg.tasks.scanner import manual_scan_sources +from webmentions_ssg.tasks.receiver import verify_webmention +from webmentions_ssg.tasks.sender import send_webmention +from webmentions_ssg.views import root_page + +assert huey.app is None +assert huey._huey is None +assert manual_scan_sources.__name__ == 'manual_scan_sources' +assert verify_webmention.__name__ == 'verify_webmention' +assert send_webmention.__name__ == 'send_webmention' +assert root_page.name == 'root' +""" + result = subprocess.run( + [sys.executable, "-c", script], capture_output=True, text=True, check=False + ) + assert result.returncode == 0, result.stderr diff --git a/tests/test_packaging.py b/tests/test_packaging.py index 34c0d72..e0b4fb1 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -35,3 +35,11 @@ def test_no_legacy_ratelimit_only_groups() -> None: assert not any( group.startswith("ratelimit-") for group in metadata["dependency-groups"] ) + + +def test_hatch_version_does_not_import_the_flask_package() -> None: + project_root = Path(__file__).resolve().parents[1] + metadata = tomllib.loads((project_root / "pyproject.toml").read_text()) + assert metadata["tool"]["hatch"]["version"]["path"] == ( + "webmentions_ssg/version.py" + ) diff --git a/webmentions_ssg/__init__.py b/webmentions_ssg/__init__.py index 9392e31..83e3f12 100644 --- a/webmentions_ssg/__init__.py +++ b/webmentions_ssg/__init__.py @@ -13,15 +13,14 @@ import coloredlogs from flask import Flask from werkzeug.middleware.proxy_fix import ProxyFix -APP_NAME = "webmentions-ssg" -VERSION = "0.0.2" - from .auth import AUTH from .cli import DB_CLI, MAIL_CLI, USERS_CLI from .config import DefaultConfig, DevelopmentConfig, ProductionConfig, validate_config from .extensions import bootstrap, csrf, db, huey, limiter, mail, migrate from .net import is_http_url -from .views import register_routes +from .version import APP_NAME as APP_NAME +from .version import VERSION +from .views import root_page def create_app(config_class: type[DefaultConfig] | None = None) -> Flask: @@ -126,7 +125,7 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask: app.add_template_filter(is_http_url) - app.register_blueprint(register_routes()) + app.register_blueprint(root_page) app.cli.add_command(USERS_CLI) diff --git a/webmentions_ssg/tasks/consumer.py b/webmentions_ssg/tasks/consumer.py index 047c010..474e775 100644 --- a/webmentions_ssg/tasks/consumer.py +++ b/webmentions_ssg/tasks/consumer.py @@ -6,45 +6,40 @@ from huey import Huey, crontab -from .. import create_app, extensions +from .. import create_app +from ..extensions import huey as queue +from . import notifications, receiver, retention, scanner def create_consumer() -> Huey: """Create and configure the Huey consumer. - The application is initialized, task modules are imported to register their - tasks, and periodic scanner, notification and verification recovery tasks - are registered. + The application is initialized and the periodic scanner, notification, + verification recovery and retention tasks are registered. :return: Configured Huey instance. """ app = create_app() - from . import notifications, receiver, retention, scanner - schedule = crontab(*app.config["SCANNER_SCHEDULE"].split(), strict=True) - extensions.huey.periodic_task(schedule)(scanner.scan_sources) + queue.periodic_task(schedule)(scanner.scan_sources) recovery_schedule = crontab( *app.config["VERIFICATION_REAPER_SCHEDULE"].split(), strict=True ) - extensions.huey.periodic_task(recovery_schedule)(receiver.recover_stale_webmentions) + queue.periodic_task(recovery_schedule)(receiver.recover_stale_webmentions) notification_schedule = crontab( *app.config["NOTIFICATION_SCHEDULE"].split(), strict=True ) - extensions.huey.periodic_task(notification_schedule)( - notifications.send_webmention_digest - ) + queue.periodic_task(notification_schedule)(notifications.send_webmention_digest) retention_schedule = crontab( *app.config["RECEIVED_RETENTION_SCHEDULE"].split(), strict=True ) - extensions.huey.periodic_task(retention_schedule)( - retention.purge_old_received_webmentions - ) + queue.periodic_task(retention_schedule)(retention.purge_old_received_webmentions) - return extensions.huey.huey + return queue.huey huey = create_consumer() diff --git a/webmentions_ssg/tasks/extension.py b/webmentions_ssg/tasks/extension.py index ee9c442..0e031e6 100644 --- a/webmentions_ssg/tasks/extension.py +++ b/webmentions_ssg/tasks/extension.py @@ -4,8 +4,10 @@ """Integrate Huey tasks with Flask application contexts.""" +from __future__ import annotations + from collections.abc import Callable -from functools import wraps +from functools import update_wrapper, wraps from typing import Any, ParamSpec, TypeVar from urllib.parse import urlsplit, urlunsplit @@ -19,6 +21,55 @@ P = ParamSpec("P") R = TypeVar("R") +class _LazyTask: + """Stable public task handle which follows the extension's current backend. + + Huey creates task classes and registers them when its decorator is applied. + Keep that backend-specific TaskWrapper private, so imported task handles can + be used across Flask app factories without referring to an obsolete queue. + """ + + def __init__( + self, + extension: Huey, + func: Callable[..., Any], + args: tuple[Any, ...], + kwargs: dict[str, Any], + *, + periodic: bool, + ) -> None: + self._extension = extension + self._func = func + self._args = args + self._kwargs = kwargs + self._periodic = periodic + self._registered: TaskWrapper | None = None + update_wrapper(self, func) + + def register(self) -> None: + """Bind the original function to the latest initialized backend.""" + 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) + ) + + def _current(self) -> TaskWrapper: + if self._registered is None: + raise RuntimeError( + "Huey has not been initialized. Call huey.init_app(app) first." + ) + return self._registered + + def __call__(self, *args: Any, **kwargs: Any) -> Any: + """Enqueue a task using the active backend.""" + return self._current()(*args, **kwargs) + + def __getattr__(self, name: str) -> Any: + """Delegate Huey task operations (call_local, schedule, s, etc.).""" + return getattr(self._current(), name) + + class Huey: """Provide Flask integration for a Huey instance. @@ -33,6 +84,7 @@ class Huey: """ self.app: Flask | None = None self._huey: BaseHuey | None = None + self._tasks: list[_LazyTask] = [] if app is not None: self.init_app(app) @@ -73,6 +125,11 @@ class Huey: self.app = app self._huey = huey_class(**config, **storage_kwargs) + # 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() + app.extensions["huey"] = self @property @@ -85,7 +142,7 @@ class Huey: if self._huey is None: raise RuntimeError( "Huey has not been initialized. " - "Call huey.init_app(app) before importing tasks." + "Call huey.init_app(app) before using tasks." ) return self._huey @@ -101,25 +158,37 @@ class Huey: return wrapped + def _decorate_task( + 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) + if self._huey is not None: + handle.register() + return handle + def task( self, *task_args: Any, **task_kwargs: Any - ) -> Callable[[Callable[P, object]], TaskWrapper]: - """Return a Huey task decorator with Flask application context.""" + ) -> Callable[[Callable[P, R]], _LazyTask]: + """Declare a task even before :meth:`init_app` has run.""" - def decorator(func: Callable[P, R]) -> TaskWrapper: - return self.huey.task(*task_args, **task_kwargs)(self._in_app_context(func)) + def decorator(func: Callable[P, R]) -> _LazyTask: + return self._decorate_task(func, task_args, task_kwargs, periodic=False) return decorator def periodic_task( self, *task_args: Any, **task_kwargs: Any - ) -> Callable[[Callable[P, object]], TaskWrapper]: - """Return a periodic Huey decorator with Flask application context.""" + ) -> Callable[[Callable[P, R]], _LazyTask]: + """Declare a periodic task against the current or next backend.""" - def decorator(func: Callable[P, R]) -> TaskWrapper: - return self.huey.periodic_task(*task_args, **task_kwargs)( - self._in_app_context(func) - ) + def decorator(func: Callable[P, R]) -> _LazyTask: + return self._decorate_task(func, task_args, task_kwargs, periodic=True) return decorator diff --git a/webmentions_ssg/tasks/notifications.py b/webmentions_ssg/tasks/notifications.py index fe12e93..fc1b475 100644 --- a/webmentions_ssg/tasks/notifications.py +++ b/webmentions_ssg/tasks/notifications.py @@ -14,9 +14,15 @@ from ..extensions import db, huey, mail from ..models import ReceivedStatus, ReceivedWebmention -@huey.lock_task("send-webmention-digest") def send_webmention_digest() -> None: """Send one digest of verified, previously unreported Webmentions.""" + # Resolve the lock against the current Huey backend, not the import-time one. + with huey.lock_task("send-webmention-digest"): + _send_webmention_digest() + + +def _send_webmention_digest() -> None: + """Do the work while the current backend's digest lock is held.""" recipient = current_app.config.get("NOTIFICATION_EMAIL") if not recipient: return diff --git a/webmentions_ssg/tasks/receiver.py b/webmentions_ssg/tasks/receiver.py index 4c4134c..2963dc7 100644 --- a/webmentions_ssg/tasks/receiver.py +++ b/webmentions_ssg/tasks/receiver.py @@ -12,7 +12,6 @@ import httpx import sqlalchemy as sa from flask import current_app -from .. import APP_NAME, VERSION from ..extensions import db, huey from ..models import ReceivedStatus, ReceivedWebmention from ..net import ( @@ -22,6 +21,7 @@ from ..net import ( is_temporary_status, read_limited_body, ) +from ..version import APP_NAME, VERSION from .mentions import html_mentions_target, text_mentions_target diff --git a/webmentions_ssg/tasks/scanner.py b/webmentions_ssg/tasks/scanner.py index 353d538..263b8a5 100644 --- a/webmentions_ssg/tasks/scanner.py +++ b/webmentions_ssg/tasks/scanner.py @@ -110,9 +110,7 @@ def scan_sources() -> None: :raises RuntimeError: If the configured source directory or base URL is invalid. """ - # Resolve the lock at execution time. The global Huey extension can be - # reinitialized by Flask app factories (notably in the test suite), so an - # import-time lock decorator may point at an obsolete storage backend. + # Manual and periodic scans must contend for the current backend's lock. with huey.lock_task("scan-webmention-sources"): scan_sources_task() diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py index 463208d..db99476 100644 --- a/webmentions_ssg/tasks/sender.py +++ b/webmentions_ssg/tasks/sender.py @@ -13,7 +13,6 @@ import sqlalchemy as sa from flask import current_app from huey.exceptions import TaskLockedException -from .. import APP_NAME, VERSION from ..extensions import db, huey from ..models import SentWebmention, SentWebmentionStatus from ..net import ( @@ -23,6 +22,7 @@ from ..net import ( is_http_url, is_temporary_status, ) +from ..version import APP_NAME, VERSION from .discovery import ( PermanentSenderError, TemporarySenderError, diff --git a/webmentions_ssg/version.py b/webmentions_ssg/version.py new file mode 100644 index 0000000..de8ac8c --- /dev/null +++ b/webmentions_ssg/version.py @@ -0,0 +1,8 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Package metadata, kept independent of Flask application initialization.""" + +APP_NAME = "webmentions-ssg" +VERSION = "0.0.2" diff --git a/webmentions_ssg/views/__init__.py b/webmentions_ssg/views/__init__.py index 91966d4..ffe9a27 100644 --- a/webmentions_ssg/views/__init__.py +++ b/webmentions_ssg/views/__init__.py @@ -2,15 +2,9 @@ # # SPDX-License-Identifier: BSD-3-Clause -"""Register all views under the historic root Blueprint.""" +"""Collect and expose the routes for the historic root Blueprint.""" -from flask import Blueprint +from . import admin, endpoint, session +from .blueprint import root_page -root_page = Blueprint("root", __name__) - - -def register_routes() -> Blueprint: - """Import task-backed view handlers after Huey initialization and return the Blueprint.""" - from . import admin, endpoint, session # noqa: F401 - - return root_page +__all__ = ["admin", "endpoint", "root_page", "session"] diff --git a/webmentions_ssg/views/admin.py b/webmentions_ssg/views/admin.py index dadf8dd..e7c5325 100644 --- a/webmentions_ssg/views/admin.py +++ b/webmentions_ssg/views/admin.py @@ -18,7 +18,7 @@ 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 . import root_page +from .blueprint import root_page @root_page.route("/received") diff --git a/webmentions_ssg/views/blueprint.py b/webmentions_ssg/views/blueprint.py new file mode 100644 index 0000000..136d319 --- /dev/null +++ b/webmentions_ssg/views/blueprint.py @@ -0,0 +1,9 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""The shared Blueprint used by all Webmention views.""" + +from flask import Blueprint + +root_page = Blueprint("root", __name__) diff --git a/webmentions_ssg/views/endpoint.py b/webmentions_ssg/views/endpoint.py index 91bb881..95e8731 100644 --- a/webmentions_ssg/views/endpoint.py +++ b/webmentions_ssg/views/endpoint.py @@ -18,7 +18,7 @@ from .. import forms from ..extensions import csrf, db, limiter from ..models import ReceivedWebmention, received_url_digest from ..tasks.receiver import verify_webmention -from . import root_page +from .blueprint import root_page def submit_received(source: str, target: str) -> tuple[uuid.UUID, bool] | None: diff --git a/webmentions_ssg/views/session.py b/webmentions_ssg/views/session.py index e4c462f..b78fd13 100644 --- a/webmentions_ssg/views/session.py +++ b/webmentions_ssg/views/session.py @@ -13,7 +13,7 @@ from .. import forms from ..auth import DUMMY_USER, is_safe_next_url, login_username_limit_key from ..extensions import db, limiter from ..models import User -from . import root_page +from .blueprint import root_page @root_page.route("/") |
