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>
285 lines
8.9 KiB
Python
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
|