# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Initialize the Flask application and its shared extensions.""" import logging import logging.handlers import os from pathlib import Path import coloredlogs from flask import Flask from flask_bootstrap import Bootstrap5 from flask_limiter import Limiter from flask_limiter.util import get_remote_address from flask_mail import Mail from flask_migrate import Migrate from flask_sqlalchemy import SQLAlchemy from flask_wtf.csrf import CSRFProtect from sqlalchemy.orm import DeclarativeBase from webmentions_ssg.config import ( DefaultConfig, DevelopmentConfig, ProductionConfig, normalize_allowed_hostnames, ) from .security import validate_secret_key from .tasks import Huey from .url_security import is_http_url APP_NAME = "webmentions-ssg" VERSION = "0.0.2" class Base(DeclarativeBase): pass CSRF = CSRFProtect() BOOTSTRAP = Bootstrap5() DATABASE = SQLAlchemy(model_class=Base) MIGRATE = Migrate() HUEY = Huey() MAIL = Mail() LIMITER = Limiter(key_func=get_remote_address) def create_app(config_class: type[DefaultConfig] | None = None) -> Flask: """ Create and configure the Flask application. The application configuration is selected based on the development environment unless an explicit configuration class is provided. Logging, extensions, authentication, Huey, blueprints, and CLI commands are then initialized. :param config_class: Configuration class to use, or ``None`` to select the development or production configuration automatically. :return: Configured Flask application. """ development = os.environ.get("WEBMENTIONS_SSG_DEV", "").lower() in { "1", "true", "yes", "on", } if config_class is None: config_class = DevelopmentConfig if development else ProductionConfig app = Flask( __name__, instance_path=str(Path("testing").absolute()) if development else None ) app.config.from_object(config_class) if not app.testing: # Local development may omit its config file; production must not. app.config.from_pyfile(app.config["CONFIG_FILE"], silent=app.debug) app.config.from_prefixed_env(prefix="FLASK") app.config.from_prefixed_env(prefix="WEBMENTIONS_SSG") # A fixed key is convenient only for local debugging. All other # deployments must supply their own persistent, random signing key. using_local_dev_key = ( issubclass(config_class, DevelopmentConfig) and app.debug and app.config.get("SECRET_KEY") == DevelopmentConfig.SECRET_KEY ) if not app.testing and not using_local_dev_key: validate_secret_key(app.config.get("SECRET_KEY")) app.config["ALLOWED_HOSTNAMES"] = normalize_allowed_hostnames( app.config["ALLOWED_HOSTNAMES"] ) for key in ( "MAX_CONTENT_LENGTH", "MAX_WEBMENTION_URL_BYTES", "RECEIVED_RETENTION_DAYS", ): value = app.config[key] if type(value) is not int or value <= 0: raise ValueError(f"{key} must be a positive integer.") if not app.testing and not app.debug and not app.config["ALLOWED_HOSTNAMES"]: raise RuntimeError("Configure ALLOWED_HOSTNAMES before running in production.") if ( not app.testing and not app.debug and app.config["RATELIMIT_STORAGE_URI"] == "memory://" ): raise RuntimeError( "Configure RATELIMIT_STORAGE_URI with shared storage before running in production." ) default_logging_formatter = logging.Formatter(app.config["LOG_FORMAT"]) log_file_handler = logging.handlers.RotatingFileHandler( app.config["LOG_FILE"], maxBytes=app.config["LOGFILE_MAX_BYTES"], backupCount=app.config["LOGFILE_BACKUP_COUNT"], ) log_file_handler.setLevel(app.config["LOG_LEVEL"]) log_file_handler.setFormatter(default_logging_formatter) logging.basicConfig(level=logging.DEBUG, handlers=[logging.NullHandler()]) app.logger.handlers.clear() app.logger.setLevel(app.config["LOG_LEVEL"]) app.logger.addHandler(log_file_handler) werkzeug_logger = logging.getLogger("werkzeug") werkzeug_logger.setLevel(app.config["LOG_LEVEL"]) werkzeug_logger.addHandler(log_file_handler) coloredlogs.install( level=app.config["LOG_LEVEL"], logger=app.logger, fmt=app.config["LOG_FORMAT"] ) coloredlogs.install( level=app.config["LOG_LEVEL"], logger=werkzeug_logger, fmt=app.config["LOG_FORMAT"], ) DATABASE.init_app(app) MIGRATE.init_app( app, db=DATABASE, directory=str(Path(__file__).resolve().parent / "migrations"), command="migrate", ) CSRF.init_app(app) LIMITER.init_app(app) MAIL.init_app(app) from .auth import AUTH AUTH.init_app(app) BOOTSTRAP.init_app(app) HUEY.init_app(app) @app.context_processor def inject_version(): """ Add the application version to the template context. :return: Template context containing the application version. """ return {"VERSION": VERSION} app.add_template_filter(is_http_url) from .views import root_page app.register_blueprint(root_page) from .cli.users import USERS_CLI app.cli.add_command(USERS_CLI) from .cli.mail import MAIL_CLI app.cli.add_command(MAIL_CLI) from .cli.database import DB_CLI app.cli.add_command(DB_CLI) return app