aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-11-16 08:57:31 +0100
committerDennis Fink2026-11-16 08:57:31 +0100
commiteb404d9a1a328278c92753e65100579e7ad98e48 (patch)
treec29918fd1720adf8a11ab88c129f2aea4951c70d
parent9b00526ab79257b65cedd71595848f09ecf84279 (diff)
downloadwebmentions-ssg-eb404d9a1a328278c92753e65100579e7ad98e48.tar.gz
webmentions-ssg-eb404d9a1a328278c92753e65100579e7ad98e48.zip
refactor(core): organize configuration by subsystem
Group default and example settings into consistent application, security, networking, receiver, scanner, sender, rate-limit, and mail sections. Reorder configuration declarations without changing their values or behavior.
-rw-r--r--contrib/webmentions-ssg.example.cfg175
-rw-r--r--webmentions_ssg/config.py82
2 files changed, 140 insertions, 117 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg
index 33f43af..8dd347b 100644
--- a/contrib/webmentions-ssg.example.cfg
+++ b/contrib/webmentions-ssg.example.cfg
@@ -8,14 +8,14 @@
import logging
# ---------------------------------------------------------------------------
-# Flask / Application
+# Application
# ---------------------------------------------------------------------------
DEBUG = False
BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"
# ---------------------------------------------------------------------------
-# Flask / Security
+# Security and reverse proxy
# ---------------------------------------------------------------------------
# Generate a persistent random key, e.g.:
# python -c 'import secrets; print(secrets.token_urlsafe(32))'
@@ -23,25 +23,26 @@ BOOTSTRAP_SERVE_LOCAL = True
# Production refuses to start without a real, persistent key (>=32 random bytes);
# set the same SECRET_KEY in the web process and every worker.
# Changing this key invalidates all existing signed login sessions.
-# Upgrading to password-bound sessions also requires users to sign in again once.
SECRET_KEY = "REPLACE_WITH_A_LONG_RANDOM_SECRET"
-# When deployed behind a trusted reverse proxy, set this to the EXACT number
-# of trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a
+# When deployed behind a trusted reverse proxy, set this to the EXACT number of
+# trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a
# single nginx instance directly in front of the application; 0 (default)
# ignores forwarded headers. Do not enable this if the backend is reachable
# directly or if the proxy fails to overwrite untrusted forwarded headers.
-# See README.md for an nginx example and multi-proxy caveats.
PROXY_FIX_TRUSTED_HOPS = 0
# ---------------------------------------------------------------------------
-# Database and logging
+# Database
# ---------------------------------------------------------------------------
# SQLite with an absolute file path (four slashes after sqlite:).
# Ensure the service user can write to this directory.
SQLALCHEMY_DATABASE_URI = "sqlite:////var/lib/webmentions-ssg/webmentions-ssg.db"
SQLALCHEMY_TRACK_MODIFICATIONS = False
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
# Ensure the service user can write to the log file / directory.
LOG_FILE = "/var/log/webmentions-ssg.log"
LOG_LEVEL = logging.INFO
@@ -50,34 +51,57 @@ LOG_FILE_MAX_BYTES = 20_000_000
LOG_FILE_BACKUP_COUNT = 10
# ---------------------------------------------------------------------------
-# Receiving Webmentions
+# Background tasks (Huey)
# ---------------------------------------------------------------------------
-# Required: exact hostnames permitted in the 'target' field of an incoming
-# Webmention. Include each hostname you serve; wildcards are not supported.
-ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"}
-
-# Maximum size of an incoming HTTP request body, including form encoding.
-# This global Flask limit also applies to login and administration routes.
-MAX_CONTENT_LENGTH = 64 * 1024
-# Independent UTF-8 byte limit for each URL submitted to /endpoint.
-# Increase cautiously: a longer URL consumes additional storage and network IO.
-MAX_WEBMENTION_URL_BYTES = 8192
-# Delete failed/deleted received Webmentions this many days after their most
-# recent update; verified, pending, and outgoing records are never purged.
-# Deleted status pages return 404; the same pair can be resubmitted afterward.
-RECEIVED_RETENTION_DAYS = 30
-# Daily at 03:00 UTC (Huey's default timezone).
-RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
+# Use a shared, persistent backend for production app and worker processes.
+# Huey messages and results use a restricted JSON serializer; do not configure
+# a pickle serializer in either process. Keep both on the same app version.
+#
+# SECURITY: Only the web app and trusted worker should be able to write to the
+# broker. Redis should bind to loopback or a private network, with protected
+# mode, firewall rules, authentication/dedicated ACLs and TLS when remote. Do
+# not expose Redis to public networks or untrusted tenants: even without
+# pickle, an attacker who can write jobs can invoke registered tasks. For
+# file/SQLite backends, restrict directory and database permissions to the
+# app/worker account. For Postgres, use a dedicated least-privilege role and
+# private/ACL-restricted network access.
+#
+# Production startup refuses the implicit memory:// fallback, as well as
+# blackhole://, since neither can reliably deliver work to a separate process.
+# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089:
+# three slashes for relative paths, four for absolute paths.
+# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue
+# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute
+# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute
+HUEY_URL = "redis://127.0.0.1:6379/0"
+# ---------------------------------------------------------------------------
+# Outbound HTTP requests (shared by receiver and sender)
+# ---------------------------------------------------------------------------
# Defense in depth: restrict the Huey worker service account with outbound
# firewall/network-policy rules that block loopback, RFC1918, link-local, ULA,
# and cloud metadata ranges, including IPv6. The application also pins
# validated DNS IPs, but deployment-level filtering is still necessary.
-# Limits for fetching/verifying incoming sources.
+# Limits for verifying sources and delivering Webmentions.
REQUEST_TIMEOUT_SECONDS = 5.0 # seconds per socket operation (both directions)
REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0 # seconds overall, including DNS, redirects and body
MAX_REDIRECTS = 20 # also used for outgoing requests
+
+# ---------------------------------------------------------------------------
+# Receiver
+# ---------------------------------------------------------------------------
+# Required: exact hostnames permitted in the 'target' field of an incoming
+# Webmention. Include each hostname you serve; wildcards are not supported.
+ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"}
+
+# Maximum size of an incoming HTTP request body, including form encoding. This
+# global Flask limit also applies to login and administration routes.
+MAX_CONTENT_LENGTH = 64 * 1024
+# Independent UTF-8 byte limit for each URL submitted to /endpoint.
+# Increase cautiously: a longer URL consumes additional storage and network IO.
+MAX_WEBMENTION_URL_BYTES = 8192
+# Maximum response body size for fetching an incoming source.
MAX_RECEIVED_SOURCE_BYTES = 1_000_000
# Requeue stuck verifications and lost queued tasks after 15 minutes.
VERIFICATION_STALE_AFTER_SECONDS = 900
@@ -87,6 +111,41 @@ VERIFICATION_MAX_RECOVERIES = 3
# Huey cron expression: every five minutes (in UTC).
VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *"
+# Delete failed/deleted received Webmentions this many days after their most
+# recent update; verified, pending, and outgoing records are never purged.
+# Deleted status pages return 404; the same pair can be resubmitted afterward.
+RECEIVED_RETENTION_DAYS = 30
+# Daily at 03:00 UTC (Huey's default timezone).
+RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
+
+# ---------------------------------------------------------------------------
+# Scanner
+# ---------------------------------------------------------------------------
+# Folder containing generated pages named index.html. Set to None to disable
+# scanning. Its root-level index.html is not scanned.
+SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public"
+
+# Needed for pages without absolute canonical URLs.
+SITE_BASE_URL = "https://example.com/"
+
+# Huey cron expression: minute hour day-of-month month day-of-week.
+SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour
+
+# ---------------------------------------------------------------------------
+# Sender
+# ---------------------------------------------------------------------------
+# Do not send Webmentions to your own site. Glob patterns are supported here.
+IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com")
+MAX_DISCOVERY_TARGET_BYTES = 1_000_000
+
+# Temporary delivery failures use persisted exponential backoff: 1, 2, 4, 8,
+# then 16 hours between attempts with these defaults. After six total attempts
+# for a revision, the failure becomes terminal. A changed source or explicit
+# manual resend starts a fresh retry budget.
+SEND_MAX_ATTEMPTS = 6
+SEND_RETRY_BASE_SECONDS = 3600
+SEND_RETRY_MAX_SECONDS = 86400
+
# ---------------------------------------------------------------------------
# Rate limiting
# ---------------------------------------------------------------------------
@@ -109,76 +168,24 @@ ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour"
ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600
# Limit login POST attempts per client IP, and separately for each submitted
-# username across IPs (case-folded and hashed before being used as a key).
-# Both limits apply to POSTs, even unsuccessful validation attempts. A per-user
+# username across IPs (case-folded and hashed before being used as a key). Both
+# limits apply to POSTs, even unsuccessful validation attempts. A per-user
# bucket can be deliberately exhausted to temporarily deny that account login;
# keep its allowance higher than the per-IP limit and monitor for abuse.
LOGIN_RATE_LIMIT = "5/minute;30/hour"
LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour"
# ---------------------------------------------------------------------------
-# Sending Webmentions from a statically generated site
+# Email digest
# ---------------------------------------------------------------------------
-# Folder containing generated pages named index.html. Set to None to disable
-# scanning. Its root-level index.html is not scanned.
-SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public"
-
-# Needed for pages without absolute canonical URLs.
-SITE_BASE_URL = "https://example.com/"
-
-# Huey cron expression: minute hour day-of-month month day-of-week.
-SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour
-
-# Temporary delivery failures use persisted exponential backoff: 1, 2, 4,
-# 8, then 16 hours between attempts with these defaults. After six total
-# attempts for a revision, the failure becomes terminal. A changed source or
-# explicit manual resend starts a fresh retry budget.
-SEND_MAX_ATTEMPTS = 6
-SEND_RETRY_BASE_SECONDS = 3600
-SEND_RETRY_MAX_SECONDS = 86400
-
-# Do not send Webmentions to your own site. Glob patterns are supported here.
-IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com")
-MAX_DISCOVERY_TARGET_BYTES = 1_000_000
-
-# ---------------------------------------------------------------------------
-# Background tasks (Huey)
-# ---------------------------------------------------------------------------
-# Use a shared, persistent backend for production app and worker processes.
-# Huey messages and results use a restricted JSON serializer; do not configure
-# a pickle serializer in either process. Keep both on the same app version.
-#
-# SECURITY: Only the web app and trusted worker should be able to write to the
-# broker. Redis should bind to loopback or a private network, with protected
-# mode, firewall rules, authentication/dedicated ACLs and TLS when remote.
-# Do not expose Redis to public networks or untrusted tenants: even without
-# pickle, an attacker who can write jobs can invoke registered tasks.
-# For file/SQLite backends, restrict directory and database permissions to
-# the app/worker account. For Postgres, use a dedicated least-privilege role
-# and private/ACL-restricted network access.
-#
-# MIGRATION FROM PICKLE: Drain outstanding jobs on the old trusted deployment
-# first, stop all producers and workers, and clear or migrate old queue,
-# scheduled-task and result data before restarting *both* with JSON.
-# Old pickle payloads cannot be read by the new serializer. Do not deserialize
-# legacy data from any backend that untrusted parties could have modified.
-# Production startup refuses the implicit memory:// fallback, as well as
-# blackhole://, since neither can reliably deliver work to a separate process.
-# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089:
-# three slashes for relative paths, four for absolute paths.
-# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue
-# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute
-# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute
-HUEY_URL = "redis://127.0.0.1:6379/0"
-
-# ---------------------------------------------------------------------------
-# Email notifications for newly verified received Webmentions
-# ---------------------------------------------------------------------------
-# Set DIGEST_EMAIL = None to disable notification emails.
+# Set DIGEST_EMAIL = None to disable notification digest emails.
DIGEST_EMAIL = "admin@example.com"
# Daily notification digest at 08:00 UTC (Huey defaults to UTC).
DIGEST_SCHEDULE = "0 8 * * *"
+# ---------------------------------------------------------------------------
+# Mail (SMTP)
+# ---------------------------------------------------------------------------
# Example SMTP-over-STARTTLS setup; adapt to your mail provider.
MAIL_SERVER = "smtp.example.com"
MAIL_PORT = 587
diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py
index 15667ab..2110a62 100644
--- a/webmentions_ssg/config.py
+++ b/webmentions_ssg/config.py
@@ -13,56 +13,87 @@ MIN_SECRET_KEY_LENGTH = 32
class DefaultConfig:
+ # Application
TESTING = False
DEBUG = False
- # Production must provide a persistent, random key through configuration.
- SECRET_KEY = None
BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"
+
+ # Security and reverse proxy
+ # Production must provide a persistent, random key through configuration.
+ SECRET_KEY = None
# Secure by default; deployment configuration can override these values.
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"
+ # Number of trusted reverse-proxy hops for X-Forwarded-For/Proto.
+ # 0 (default) means forwarded headers are not trusted.
+ PROXY_FIX_TRUSTED_HOPS = 0
+
+ # Database
+ SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db"
+
+ # Logging
LOG_FILE = "/var/log/webmentions-ssg.log"
- LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s"
LOG_LEVEL = logging.INFO
+ LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s"
LOG_FILE_MAX_BYTES = 20_000_000
LOG_FILE_BACKUP_COUNT = 10
- SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db"
+ # Background tasks (Huey)
+ # HUEY_URL is intentionally unset; production must configure a persistent queue.
+
+ # Outbound HTTP requests (shared by receiver and sender)
+ REQUEST_TIMEOUT_SECONDS = 5.0
+ # Absolute wall-clock budget for each verification or delivery attempt.
+ REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0
+ MAX_REDIRECTS = 20
+
+ # Receiver
# Empty by default: no target hostnames are accepted until configured.
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.
MAX_WEBMENTION_URL_BYTES = 8192
- # Purge terminal failed/source-removed received Webmentions after 30 days.
- RECEIVED_RETENTION_DAYS = 30
- RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
- MAX_REDIRECTS = 20
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_SECONDS = 30.0
# Requeue abandoned verification attempts after 15 minutes.
VERIFICATION_STALE_AFTER_SECONDS = 900
# Maximum automatic recoveries of a stale received/verifying row.
VERIFICATION_MAX_RECOVERIES = 3
VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *"
+ # Purge terminal failed/source-removed received Webmentions after 30 days.
+ RECEIVED_RETENTION_DAYS = 30
+ RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
+ # Scanner
SITE_OUTPUT_DIRECTORY = None
SITE_BASE_URL = None
- IGNORED_TARGET_HOSTNAMES = ()
SOURCE_SCAN_SCHEDULE = "0 * * * *"
+
+ # Sender
+ IGNORED_TARGET_HOSTNAMES = ()
+ MAX_DISCOVERY_TARGET_BYTES = 1_000_000
# Total send attempts per source revision (not additional retries).
SEND_MAX_ATTEMPTS = 6
SEND_RETRY_BASE_SECONDS = 3600
SEND_RETRY_MAX_SECONDS = 86400
+ # Rate limiting
+ RATELIMIT_STORAGE_URI = "memory://"
+ RATELIMIT_HEADERS_ENABLED = True
+ ENDPOINT_RATE_LIMIT = "10/minute;100/hour"
+ ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour"
+ ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600
+ LOGIN_RATE_LIMIT = "5/minute;30/hour"
+ # Separate cross-IP limit for each submitted username (hashed in storage).
+ LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour"
+
+ # Email notifications
DIGEST_EMAIL = None
DIGEST_SCHEDULE = "0 8 * * *"
+ # Mail (SMTP)
MAIL_SERVER = "localhost"
MAIL_PORT = 25
MAIL_USE_TLS = False
@@ -71,21 +102,6 @@ class DefaultConfig:
MAIL_PASSWORD = None
MAIL_DEFAULT_SENDER = None
- # Number of trusted reverse-proxy hops for X-Forwarded-For/Proto.
- # 0 (default) means forwarded headers are not trusted.
- PROXY_FIX_TRUSTED_HOPS = 0
-
- RATELIMIT_STORAGE_URI = "memory://"
- RATELIMIT_HEADERS_ENABLED = True
-
- ENDPOINT_RATE_LIMIT = "10/minute;100/hour"
- ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour"
- ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600
-
- LOGIN_RATE_LIMIT = "5/minute;30/hour"
- # Separate cross-IP limit for each submitted username (hashed in storage).
- LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour"
-
class DevelopmentConfig(DefaultConfig):
DEBUG = True
@@ -103,17 +119,17 @@ class ProductionConfig(DefaultConfig):
class TestingConfig(DefaultConfig):
TESTING = True
- SESSION_COOKIE_SECURE = False
-
- SECRET_KEY = "testing-secret-key"
WTF_CSRF_ENABLED = False
- LOG_FILE = "testing/webmentions-ssg-tests.log"
- LOG_LEVEL = logging.DEBUG
+ SECRET_KEY = "testing-secret-key"
+ SESSION_COOKIE_SECURE = False
SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
SQLALCHEMY_TRACK_MODIFICATIONS = False
+ LOG_FILE = "testing/webmentions-ssg-tests.log"
+ LOG_LEVEL = logging.DEBUG
+
HUEY_URL = "memory://"
ALLOWED_TARGET_HOSTNAMES = frozenset({"dennisfink.me"})