Files
StarPunk/starpunk/routes/webmention.py
T
PhilandClaude Opus 5.5 b7f8e1612c feat: articles at /article/<slug> with slugs from their titles (v2.17.0, ADR-077)
Articles (notes with a title) move from /note/<slug> to /article/<slug>;
the other prefix 301-redirects. New articles take their slug from the
title (mp-slug still wins; notes keep timestamp slugs). A Micropub update
that adds or removes a title answers 201 with the new Location.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:27:31 -07:00

285 lines
8.9 KiB
Python

"""
Webmention routes for StarPunk
Per W3C Webmention Recommendation and ADR-063:
- POST /webmention - Receive webmention notifications
- GET /webmention - Optional endpoint information
References:
- W3C Webmention Specification: https://www.w3.org/TR/webmention/
- ADR-063: Webmention Implementation
"""
from flask import Blueprint, current_app, request, jsonify
from urllib.parse import urldefrag, urlparse
from starpunk.database import get_db
from starpunk.notes import get_note, NoteNotFoundError
from starpunk.rate_limiter import check_rate_limit
bp = Blueprint("webmention", __name__)
def get_client_ip() -> str:
"""
Get client IP address, accounting for reverse proxy.
If TRUSTED_PROXY is enabled, uses X-Forwarded-For header.
Otherwise uses request.remote_addr directly.
"""
if current_app.config.get('TRUSTED_PROXY', False):
forwarded = request.headers.get('X-Forwarded-For')
if forwarded:
# First IP in chain is the client
return forwarded.split(',')[0].strip()
return request.remote_addr or '0.0.0.0'
@bp.before_request
def rate_limit_webmention():
"""
Check rate limits before processing webmention requests.
Per ADR-063 (Decision 10), checks:
1. IP rate limit (60/min by default)
2. Source domain rate limit (10/min by default)
Returns 429 with Retry-After header if rate limited.
"""
# Only rate limit POST requests (the actual webmention submission)
if request.method != 'POST':
return None
# Get client IP
ip = get_client_ip()
# Get source domain from request (if available)
source_domain = None
content_type = request.headers.get("Content-Type", "")
if "application/json" in content_type:
data = request.get_json(silent=True) or {}
source = data.get('source')
else:
source = request.form.get('source')
if source:
try:
source_domain = urlparse(source).netloc
except Exception:
# Invalid URL, domain check will be skipped
# This is acceptable - IP limit still applies
current_app.logger.debug(f"Could not parse source URL for domain extraction: {source}")
# Check rate limits
allowed, error = check_rate_limit(ip, source_domain)
if not allowed:
current_app.logger.warning(
f"Rate limit exceeded - IP: {ip}, Domain: {source_domain or 'N/A'}"
)
return jsonify({
"error": "rate_limit_exceeded",
"error_description": error
}), 429, {'Retry-After': str(current_app.config.get('WEBMENTION_RATE_LIMIT_WINDOW', 60))}
return None
def validate_url(url: str) -> tuple[bool, str | None]:
"""
Validate a URL is well-formed and uses http/https scheme.
Returns:
(is_valid, error_message)
"""
if not url:
return False, "URL is required"
try:
parsed = urlparse(url)
if parsed.scheme not in ('http', 'https'):
return False, "Only http and https URLs are supported"
if not parsed.netloc:
return False, "URL must include a hostname"
if len(url) > 2048:
return False, "URL exceeds maximum length of 2048 characters"
return True, None
except Exception:
return False, "URL is malformed"
def _host_port(url: str) -> tuple[str, int | None]:
parsed = urlparse(url)
default = {'http': 80, 'https': 443}.get(parsed.scheme.lower())
try:
port = parsed.port or default
except ValueError:
port = None
return (parsed.hostname or '').lower(), port
def is_target_on_site(target_url: str) -> bool:
"""
Check if target URL is on this site.
Compares host (case-insensitively) and effective port with SITE_URL.
"""
site_url = current_app.config.get('SITE_URL', '')
return _host_port(site_url) == _host_port(target_url)
def resolve_target_note(target_url: str) -> int | None:
"""
Resolve target URL to a note ID if it points to a note.
Returns:
Note ID if target is a valid note, None otherwise
"""
target_parsed = urlparse(target_url)
# Strip query params and fragments for matching
target_path = target_parsed.path.rstrip('/')
# A note or article URL: /note/{slug} or /article/{slug} (v2.17.0).
# Either prefix finds the post, as the page redirects to the right one.
prefix, _, slug = target_path.lstrip('/').partition('/')
if prefix in ('note', 'article') and '/' not in slug:
if slug:
try:
note = get_note(slug=slug)
# get_note() returns None if not found, or a Note object
if note and note.published:
return note.id
except NoteNotFoundError:
pass
# Homepage or other valid page (not a note)
return None
@bp.route("/webmention", methods=["GET"])
def webmention_info():
"""
Optional endpoint information.
Returns basic information about the webmention endpoint.
"""
return jsonify({
"name": "Webmention endpoint",
"spec": "https://www.w3.org/TR/webmention/"
})
@bp.route("/webmention", methods=["POST"])
def receive_webmention():
"""
Receive webmention notification per W3C spec.
Accepts application/x-www-form-urlencoded (required) and
application/json (optional extension).
Returns:
202 Accepted with JSON body on success
400 Bad Request with error details on failure
"""
# Parse request based on content type
content_type = request.headers.get("Content-Type", "")
if "application/json" in content_type:
data = request.get_json() or {}
source = data.get("source")
target = data.get("target")
else:
# Default to form-encoded (required by W3C spec)
source = request.form.get("source")
target = request.form.get("target")
# Validate required parameters
if not source:
return jsonify({
"error": "invalid_request",
"error_description": "Missing required parameter: source"
}), 400
if not target:
return jsonify({
"error": "invalid_request",
"error_description": "Missing required parameter: target"
}), 400
# Validate source URL
source_valid, source_error = validate_url(source)
if not source_valid:
return jsonify({
"error": "invalid_request",
"error_description": f"Source must be a valid URL"
}), 400
# Validate target URL
target_valid, target_error = validate_url(target)
if not target_valid:
return jsonify({
"error": "invalid_request",
"error_description": f"Target must be a valid URL"
}), 400
# Validate source and target are different
if source == target:
return jsonify({
"error": "invalid_request",
"error_description": "Source and target must be different"
}), 400
# Validate target is on this site
if not is_target_on_site(target):
return jsonify({
"error": "invalid_target",
"error_description": "Target URL is not on this site"
}), 400
# The fragment is ignored (spec 3.2.1) and not stored, so target#a and
# target#b are the same mention
target = urldefrag(target)[0]
# Only published notes accept webmentions (spec 3.2.1: target must be a
# valid resource that accepts them)
target_note_id = resolve_target_note(target)
if target_note_id is None:
return jsonify({
"error": "invalid_target",
"error_description": "Target URL does not accept webmentions"
}), 400
# Insert webmention into database (queued for validation)
# Use INSERT ... ON CONFLICT to handle duplicate webmentions
db = get_db()
try:
db.execute("""
INSERT INTO webmentions (source_url, target_url, target_note_id)
VALUES (?, ?, ?)
ON CONFLICT(source_url, target_url) DO UPDATE SET
validation_status = 'pending',
updated_at = CURRENT_TIMESTAMP
WHERE webmentions.origin = 'webmention'
""", (source, target, target_note_id))
# (A backfed response with the same URLs is StarPunk's own copy of
# what the silo said; a webmention doesn't overwrite it. v2.13.0)
db.commit()
current_app.logger.info(
f"Webmention received: {source} -> {target}"
f"{' (note_id=' + str(target_note_id) + ')' if target_note_id else ''}"
)
return jsonify({
"status": "accepted",
"message": "Webmention queued for verification"
}), 202
except Exception as e:
db.rollback()
current_app.logger.error(f"Failed to queue webmention: {e}")
return jsonify({
"error": "server_error",
"error_description": "Failed to queue webmention"
}), 500