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>
993 lines
37 KiB
Python
993 lines
37 KiB
Python
"""
|
|
Micropub endpoint implementation for StarPunk
|
|
|
|
This module handles Micropub protocol requests, providing a standard IndieWeb
|
|
interface for creating posts via external clients.
|
|
|
|
Functions:
|
|
normalize_properties: Convert form/JSON data to Micropub properties format
|
|
extract_content: Get content from Micropub properties
|
|
extract_title: Get the title (name) from Micropub properties
|
|
extract_summary: Get the author's summary from Micropub properties
|
|
extract_tags: Get category tags from Micropub properties
|
|
handle_create: Process Micropub create action
|
|
handle_update: Process Micropub update action (v2.4.0)
|
|
handle_delete: Process Micropub delete / undelete actions (v2.4.0)
|
|
handle_query: Process Micropub query endpoints
|
|
extract_bearer_token: Get token from Authorization header or form
|
|
|
|
Exceptions:
|
|
MicropubError: Base exception for Micropub operations
|
|
MicropubAuthError: Authentication/authorization errors
|
|
MicropubValidationError: Invalid request data
|
|
|
|
References:
|
|
- W3C Micropub Specification: https://www.w3.org/TR/micropub/
|
|
- IndieAuth Specification: https://www.w3.org/TR/indieauth/
|
|
"""
|
|
|
|
from datetime import datetime, timezone
|
|
from typing import Optional
|
|
|
|
from flask import Request, current_app, jsonify
|
|
|
|
from starpunk.models import split_title
|
|
from starpunk.notes import (
|
|
create_note, delete_note, get_note, list_notes, undelete_note, update_note,
|
|
InvalidNoteDataError, NoteNotFoundError,
|
|
)
|
|
from starpunk.indieauth import check_scope
|
|
from starpunk.utils import absolute_url_for, iso_utc
|
|
|
|
|
|
# Custom Exceptions
|
|
|
|
|
|
class MicropubError(Exception):
|
|
"""Base exception for Micropub operations"""
|
|
|
|
def __init__(self, error: str, error_description: str, status_code: int = 400):
|
|
self.error = error
|
|
self.error_description = error_description
|
|
self.status_code = status_code
|
|
super().__init__(error_description)
|
|
|
|
|
|
class MicropubAuthError(MicropubError):
|
|
"""Authentication or authorization error"""
|
|
|
|
def __init__(self, error_description: str, status_code: int = 401):
|
|
super().__init__("unauthorized", error_description, status_code)
|
|
|
|
|
|
class MicropubValidationError(MicropubError):
|
|
"""Invalid request data"""
|
|
|
|
def __init__(self, error_description: str):
|
|
super().__init__("invalid_request", error_description, 400)
|
|
|
|
|
|
# Response Helpers
|
|
|
|
|
|
def error_response(error: str, error_description: str, status_code: int = 400):
|
|
"""
|
|
Generate OAuth 2.0 compliant error response
|
|
|
|
Args:
|
|
error: Error code (e.g., "invalid_request")
|
|
error_description: Human-readable error description
|
|
status_code: HTTP status code
|
|
|
|
Returns:
|
|
Tuple of (response, status_code)
|
|
"""
|
|
headers = {}
|
|
if status_code == 401:
|
|
# RFC 6750 3: tell the client how to authenticate (v2.9.0)
|
|
challenge = 'Bearer realm="micropub"'
|
|
if error == "unauthorized" and "Invalid" in error_description:
|
|
challenge += ', error="invalid_token"'
|
|
headers["WWW-Authenticate"] = challenge
|
|
return (
|
|
jsonify({"error": error, "error_description": error_description}),
|
|
status_code,
|
|
headers,
|
|
)
|
|
|
|
|
|
# Token Extraction
|
|
|
|
|
|
def extract_bearer_token(request: Request) -> Optional[str]:
|
|
"""
|
|
Extract bearer token from Authorization header or form parameter
|
|
|
|
Micropub spec allows token in either location:
|
|
- Authorization: Bearer <token>
|
|
- access_token form parameter
|
|
|
|
Args:
|
|
request: Flask request object
|
|
|
|
Returns:
|
|
Token string if found, None otherwise
|
|
"""
|
|
# The scheme is case-insensitive (RFC 7235)
|
|
scheme, _, credentials = request.headers.get("Authorization", "").partition(" ")
|
|
header_token = credentials.strip() if scheme.lower() == "bearer" else None
|
|
|
|
body_token = None
|
|
if request.method == "POST":
|
|
body_token = request.form.get("access_token")
|
|
elif request.method == "GET":
|
|
body_token = request.args.get("access_token")
|
|
|
|
# Only one method may be used (RFC 6750 2) (v2.9.0)
|
|
if header_token and body_token:
|
|
raise MicropubValidationError("Send the access token in the header or the body, not both")
|
|
|
|
return header_token or body_token
|
|
|
|
|
|
# Property Normalization
|
|
|
|
|
|
def normalize_properties(data: dict) -> dict:
|
|
"""
|
|
Normalize Micropub properties from both form and JSON formats
|
|
|
|
Handles two input formats:
|
|
- JSON: {"type": ["h-entry"], "properties": {"content": ["value"]}}
|
|
- Form: {content: ["value"], "category[]": ["tag1", "tag2"]}
|
|
|
|
Args:
|
|
data: Raw request data (form dict or JSON dict)
|
|
|
|
Returns:
|
|
Normalized properties dict with all values as lists
|
|
"""
|
|
# JSON format has properties nested. Values MUST be arrays (3.3.2); a
|
|
# bare value is wrapped rather than read character by character.
|
|
# mp-* commands and access_token are not properties (3.2).
|
|
if "properties" in data:
|
|
properties = data["properties"]
|
|
if not isinstance(properties, dict):
|
|
raise MicropubValidationError("properties must be an object")
|
|
return {
|
|
key: value if isinstance(value, list) else [value]
|
|
for key, value in properties.items()
|
|
if not key.startswith("mp-") and key != "access_token"
|
|
}
|
|
|
|
# Form format - convert to properties dict
|
|
properties = {}
|
|
for key, value in data.items():
|
|
if hasattr(value, "filename") or (isinstance(value, list) and value and hasattr(value[0], "filename")):
|
|
continue # uploaded files are handled separately
|
|
# Skip reserved Micropub parameters
|
|
if key.startswith("mp-") or key in ["action", "url", "access_token", "h"]:
|
|
continue
|
|
|
|
# Handle array notation: property[] -> property
|
|
clean_key = key.rstrip("[]")
|
|
|
|
# Ensure value is always a list
|
|
if not isinstance(value, list):
|
|
value = [value]
|
|
|
|
properties[clean_key] = value
|
|
|
|
return properties
|
|
|
|
|
|
# Property Extraction
|
|
|
|
|
|
def extract_content(properties: dict) -> str:
|
|
"""
|
|
Extract content from Micropub properties
|
|
|
|
Args:
|
|
properties: Normalized Micropub properties dict
|
|
|
|
Returns:
|
|
Content string
|
|
|
|
Raises:
|
|
MicropubValidationError: If content is missing or empty
|
|
"""
|
|
content_list = properties.get("content") or properties.get("summary") or []
|
|
|
|
# Handle both plain text and HTML/text objects
|
|
if not content_list:
|
|
raise MicropubValidationError("Content is required")
|
|
|
|
content = content_list[0]
|
|
|
|
# Handle structured content ({"html": "...", "text": "..."}). The HTML is
|
|
# what was written; clients send text as a plain fallback, which loses
|
|
# images, links and headings (v2.16.0; before, text was preferred)
|
|
if isinstance(content, dict):
|
|
content = content.get("html") or content.get("text", "")
|
|
|
|
if not isinstance(content, str) or not content.strip():
|
|
raise MicropubValidationError("Content cannot be empty")
|
|
|
|
return content.strip()
|
|
|
|
|
|
def content_format(properties: dict) -> Optional[str]:
|
|
"""'html' if the content was sent as HTML (returned as such by q=source)"""
|
|
content = _first(properties.get("content"))
|
|
if isinstance(content, dict) and content.get("html"):
|
|
return "html"
|
|
return None
|
|
|
|
|
|
def _has_text(content) -> bool:
|
|
"""Whether a content property has any text. Likes, reposts (v2.5.0) and
|
|
photo posts (v2.6.5) may come without."""
|
|
values = content if isinstance(content, list) else [content]
|
|
return any(
|
|
(c.strip() if isinstance(c, str) else (c.get("text") or c.get("html") or "").strip())
|
|
for c in values if c
|
|
)
|
|
|
|
|
|
def extract_title(properties: dict) -> Optional[str]:
|
|
"""
|
|
Extract the title (Micropub 'name' property), stored in notes.title (ADR-076)
|
|
|
|
Args:
|
|
properties: Normalized Micropub properties dict
|
|
|
|
Returns:
|
|
Title on a single line, or None if no name was sent
|
|
"""
|
|
name = (properties.get("name") or [""])[0]
|
|
if not isinstance(name, str):
|
|
return None
|
|
return " ".join(name.split()) or None
|
|
|
|
|
|
def extract_summary(properties: dict) -> Optional[str]:
|
|
"""The author's summary (Micropub 'summary' property, v2.16.0), as plain text"""
|
|
summary = _first(properties.get("summary"))
|
|
if isinstance(summary, dict):
|
|
summary = summary.get("text") or summary.get("value") or ""
|
|
if not isinstance(summary, str):
|
|
return None
|
|
return summary.strip() or None
|
|
|
|
|
|
def drop_title_heading(content: str, title: Optional[str]) -> str:
|
|
"""Content without a '# heading' first line that only repeats the title"""
|
|
heading, rest = split_title(content)
|
|
if title and heading == title:
|
|
return rest
|
|
return content
|
|
|
|
|
|
def extract_tags(properties: dict) -> list[str]:
|
|
"""
|
|
Extract tags from Micropub category property
|
|
|
|
Args:
|
|
properties: Normalized Micropub properties dict
|
|
|
|
Returns:
|
|
List of tag strings
|
|
"""
|
|
categories = properties.get("category", [])
|
|
# Strings only: person tags (h-card objects) aren't supported and are
|
|
# ignored, as Micropub says to ignore what isn't recognised (3.3.5)
|
|
return [tag.strip() for tag in categories if isinstance(tag, str) and tag.strip()]
|
|
|
|
|
|
def extract_published_date(properties: dict) -> Optional[datetime]:
|
|
"""
|
|
Extract published date from Micropub properties
|
|
|
|
Args:
|
|
properties: Normalized Micropub properties dict
|
|
|
|
Returns:
|
|
Datetime object if published date provided, None otherwise
|
|
"""
|
|
published = _first(properties.get("published"))
|
|
if not published:
|
|
return None
|
|
|
|
try:
|
|
value = datetime.fromisoformat(str(published).strip().replace("Z", "+00:00"))
|
|
except ValueError:
|
|
raise MicropubValidationError(f"published is not an ISO 8601 date: {published}")
|
|
# Stored times are naive UTC, like every other note (v2.9.0)
|
|
if value.tzinfo is not None:
|
|
value = value.astimezone(timezone.utc).replace(tzinfo=None)
|
|
return value
|
|
|
|
|
|
# Action Handlers
|
|
|
|
MAX_PHOTOS = 4 # ADR-057
|
|
MAX_REMOTE_PHOTO_BYTES = 20 * 1024 * 1024
|
|
|
|
# Properties we can store, and so can be updated (v2.4.0)
|
|
UPDATABLE = {"content", "name", "summary", "category", "in-reply-to", "post-status", "photo"}
|
|
|
|
|
|
def _first(value):
|
|
if isinstance(value, list):
|
|
return value[0] if value else None
|
|
return value
|
|
|
|
|
|
def _require_scope(token_info: dict, *scopes: str) -> None:
|
|
granted = token_info.get("scope", "")
|
|
if not any(check_scope(s, granted) for s in scopes):
|
|
raise MicropubError(
|
|
"insufficient_scope", f"Token lacks {' or '.join(scopes)} scope", status_code=403
|
|
)
|
|
|
|
|
|
def extract_post_status(properties: dict) -> bool:
|
|
"""post-status: 'draft' -> unpublished; 'published' or absent -> published"""
|
|
status = _first(properties.get("post-status"))
|
|
if status in (None, "", "published"):
|
|
return True
|
|
if status == "draft":
|
|
return False
|
|
raise MicropubValidationError(f"Unsupported post-status: {status}")
|
|
|
|
|
|
def extract_visibility_draft(properties: dict) -> bool:
|
|
"""
|
|
True if visibility asks for a non-public post (v2.9.0)
|
|
|
|
StarPunk only has public posts and drafts, so private and unlisted posts
|
|
are kept as drafts rather than published.
|
|
"""
|
|
visibility = _first(properties.get("visibility"))
|
|
if visibility in (None, "", "public"):
|
|
return False
|
|
if visibility in ("private", "unlisted"):
|
|
return True
|
|
raise MicropubValidationError(f"Unsupported visibility: {visibility}")
|
|
|
|
|
|
UNSUPPORTED_MEDIA = ("video", "audio")
|
|
|
|
|
|
def extract_url_property(properties: dict, name: str) -> Optional[str]:
|
|
"""A URL property (in-reply-to, like-of, repost-of): string or h-cite"""
|
|
value = _first(properties.get(name))
|
|
if isinstance(value, dict): # h-cite
|
|
value = _first((value.get("properties") or {}).get("url")) or value.get("value")
|
|
value = (value or "").strip() if isinstance(value, str) else ""
|
|
if value and not value.startswith(("http://", "https://")):
|
|
raise MicropubValidationError(f"{name} must be an http(s) URL")
|
|
return value or None
|
|
|
|
|
|
def extract_in_reply_to(properties: dict) -> Optional[str]:
|
|
return extract_url_property(properties, "in-reply-to")
|
|
|
|
|
|
def extract_photos(properties: dict) -> list[dict[str, str]]:
|
|
"""
|
|
Extract photo URLs and alt text from Micropub properties
|
|
|
|
Handles both simple URL strings and structured photo objects with alt text.
|
|
|
|
Examples:
|
|
>>> extract_photos({'photo': ['https://example.com/photo.jpg']})
|
|
[{'url': 'https://example.com/photo.jpg', 'alt': ''}]
|
|
>>> extract_photos({'photo': [{'value': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]})
|
|
[{'url': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]
|
|
"""
|
|
result = []
|
|
for photo in properties.get("photo", []):
|
|
if isinstance(photo, str):
|
|
result.append({'url': photo, 'alt': ''})
|
|
elif isinstance(photo, dict):
|
|
url = photo.get('value') or photo.get('url', '')
|
|
if url:
|
|
result.append({'url': url, 'alt': photo.get('alt', '')})
|
|
return result
|
|
|
|
|
|
def _public_address(host: str) -> bool:
|
|
"""True if every address the host resolves to is public (no SSRF into the LAN)"""
|
|
import ipaddress
|
|
import socket
|
|
|
|
try:
|
|
infos = socket.getaddrinfo(host, None)
|
|
except socket.gaierror:
|
|
return False
|
|
for info in infos:
|
|
ip = ipaddress.ip_address(info[4][0])
|
|
if not ip.is_global:
|
|
return False
|
|
return bool(infos)
|
|
|
|
|
|
def _fetch_remote_photo(url: str) -> Optional[dict]:
|
|
"""
|
|
Download a photo hosted elsewhere into the media library. Returns the
|
|
saved media ({'id', 'path', ...}), or None if it couldn't be fetched.
|
|
|
|
Uses the webmention fetcher (v2.9.0): every redirect is checked against
|
|
private addresses and the connection is pinned to the checked address.
|
|
"""
|
|
from urllib.parse import urlparse
|
|
from starpunk.media import save_media
|
|
from starpunk.webmention_ssrf import safe_get, user_agent
|
|
|
|
try:
|
|
result = safe_get(
|
|
url, headers={"User-Agent": user_agent(current_app.config.get("SITE_URL", ""))},
|
|
max_bytes=MAX_REMOTE_PHOTO_BYTES, timeout=20,
|
|
)
|
|
if result.status_code != 200:
|
|
raise ValueError(f"HTTP {result.status_code}")
|
|
name = urlparse(result.url).path.rsplit("/", 1)[-1] or "photo.jpg"
|
|
return save_media(result.content, name)
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Could not fetch photo {url}: {e}")
|
|
return None
|
|
|
|
|
|
def _media_id_for_url(url: str) -> Optional[int]:
|
|
"""Media id for a photo URL: ours by path, or downloaded if hosted elsewhere"""
|
|
from starpunk.database import get_db
|
|
|
|
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
|
|
if url.startswith(site_url) or url.startswith('/media/'):
|
|
path = url[len(site_url):] if url.startswith(site_url) else url
|
|
if path.startswith('/media/'):
|
|
path = path[len('/media/'):]
|
|
row = get_db(current_app).execute("SELECT id FROM media WHERE path = ?", (path,)).fetchone()
|
|
if row:
|
|
return row[0]
|
|
current_app.logger.warning(f"Photo URL not found in media: {url}")
|
|
return None
|
|
media = _fetch_remote_photo(url)
|
|
return media["id"] if media else None
|
|
|
|
|
|
MAX_INLINE_IMAGES = 20
|
|
|
|
|
|
def localize_inline_images(content: str) -> str:
|
|
"""
|
|
Copy images embedded in the text from other sites into the media library
|
|
and point the text at the copies (v2.16.0), so an article doesn't depend
|
|
on the client's or a CDN's host staying up. Best effort: an image that
|
|
can't be fetched keeps its URL.
|
|
"""
|
|
from html import escape
|
|
from starpunk.syndication import inline_images
|
|
|
|
if not content or "<img" not in content and "![" not in content:
|
|
return content
|
|
site_url = current_app.config.get("SITE_URL", "").rstrip("/")
|
|
remote = [url for url, _ in inline_images(content)
|
|
if url.startswith(("http://", "https://")) and not url.startswith(site_url + "/")]
|
|
for url in list(dict.fromkeys(remote))[:MAX_INLINE_IMAGES]:
|
|
media = _fetch_remote_photo(url)
|
|
if media:
|
|
local = f"{site_url}/media/{media['path']}"
|
|
# As written in Markdown, and as it may be escaped in HTML attributes
|
|
content = content.replace(url, local).replace(escape(url), local)
|
|
return content
|
|
|
|
|
|
def _save_uploads(files) -> list[dict]:
|
|
"""Photos uploaded in a multipart create request -> [{'media_id', 'alt'}]"""
|
|
from starpunk.media import save_media
|
|
|
|
result = []
|
|
for key in ("photo", "photo[]"):
|
|
for upload in (files.getlist(key) if files else []):
|
|
if upload and upload.filename:
|
|
try:
|
|
result.append({"media_id": save_media(upload.read(), upload.filename)["id"], "alt": ""})
|
|
except ValueError as e:
|
|
raise MicropubValidationError(f"Invalid photo {upload.filename}: {e}")
|
|
return result
|
|
|
|
|
|
def _resolve_photos(photos: list[dict]) -> tuple[list[int], list[str]]:
|
|
"""Photo dicts ({'url'|'media_id', 'alt'}) -> (media ids, captions), max 4"""
|
|
if len(photos) > MAX_PHOTOS:
|
|
current_app.logger.warning(
|
|
f"Micropub received {len(photos)} photos, truncating to {MAX_PHOTOS} per ADR-057"
|
|
)
|
|
media_ids, captions = [], []
|
|
for photo in photos:
|
|
if len(media_ids) == MAX_PHOTOS:
|
|
break
|
|
media_id = photo.get("media_id") or _media_id_for_url(photo["url"])
|
|
if not media_id:
|
|
# Don't create or change the post without it (v2.9.0)
|
|
raise MicropubValidationError(f"Could not get photo {photo.get('url')}")
|
|
# The same photo twice is shown once (v2.6.5)
|
|
if media_id not in media_ids:
|
|
media_ids.append(media_id)
|
|
captions.append(photo.get("alt", ""))
|
|
return media_ids, captions
|
|
|
|
|
|
def _attach_photos_to_note(note_id: int, photos: list[dict]) -> None:
|
|
"""Attach photos (by URL or uploaded media id) to a note, replacing any others"""
|
|
from starpunk.media import attach_media_to_note
|
|
|
|
media_ids, captions = _resolve_photos(photos)
|
|
attach_media_to_note(note_id, media_ids, captions)
|
|
|
|
|
|
def _note_photos(note) -> list[dict]:
|
|
"""A note's current photos as Micropub photo dicts"""
|
|
from starpunk.media import get_note_media
|
|
|
|
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
|
|
return [
|
|
{"url": f"{site_url}/media/{m['path']}", "alt": m.get("caption") or "", "media_id": m["id"]}
|
|
for m in get_note_media(note.id)
|
|
]
|
|
|
|
|
|
def _check_type(data: dict) -> None:
|
|
"""Only h-entry is supported"""
|
|
h = _first(data.get("h"))
|
|
kind = _first(data.get("type"))
|
|
if (h and h != "entry") or (kind and kind != "h-entry"):
|
|
raise MicropubValidationError(f"Only h-entry posts are supported (got {h or kind})")
|
|
|
|
|
|
def _note_from_url(url: Optional[str], deleted: bool = False):
|
|
"""Find the note a URL points at (/note/<slug> or /article/<slug> on this site)"""
|
|
from urllib.parse import urlparse
|
|
from starpunk.database import get_db
|
|
|
|
if not url:
|
|
raise MicropubValidationError("No url provided")
|
|
site = urlparse(current_app.config.get("SITE_URL", ""))
|
|
parsed = urlparse(url)
|
|
if parsed.netloc and site.netloc and parsed.netloc != site.netloc:
|
|
raise MicropubValidationError("URL is not on this site")
|
|
parts = [p for p in parsed.path.split("/") if p]
|
|
if len(parts) != 2 or parts[0] not in ("note", "notes", "article", "articles"):
|
|
raise MicropubValidationError("URL is not a post on this site")
|
|
slug = parts[1]
|
|
if deleted:
|
|
row = get_db(current_app).execute(
|
|
"SELECT id FROM notes WHERE slug = ? AND deleted_at IS NOT NULL", (slug,)
|
|
).fetchone()
|
|
if row is None:
|
|
raise MicropubError("not_found", "No deleted post at that URL", 404)
|
|
return slug
|
|
note = get_note(slug=slug)
|
|
if note is None:
|
|
raise MicropubError("not_found", "Post not found", 404)
|
|
return note
|
|
|
|
|
|
def handle_create(data: dict, token_info: dict, files=None):
|
|
"""
|
|
Handle Micropub create action
|
|
|
|
Creates a note using StarPunk's notes.py CRUD functions after
|
|
mapping Micropub properties to StarPunk's note format.
|
|
|
|
Args:
|
|
data: Raw request data (form or JSON)
|
|
token_info: Authenticated token information (me, client_id, scope)
|
|
files: Uploaded files for multipart requests (v2.4.0)
|
|
|
|
Returns:
|
|
Tuple of (response_body, status_code, headers)
|
|
"""
|
|
_require_scope(token_info, "create", "draft")
|
|
# A token with only the draft scope may create drafts (v2.9.0)
|
|
drafts_only = not check_scope("create", token_info.get("scope", ""))
|
|
_check_type(data)
|
|
|
|
# mp-slug and mp-syndicate-to are server commands, not properties. Form
|
|
# posts send them at the top level; JSON clients inside properties too.
|
|
commands = dict(data) if isinstance(data, dict) else {}
|
|
if isinstance(commands.get("properties"), dict):
|
|
commands.update({k: v for k, v in commands["properties"].items() if k.startswith("mp-")})
|
|
|
|
custom_slug = _first(commands.get("mp-slug"))
|
|
if custom_slug is not None and not isinstance(custom_slug, str):
|
|
raise MicropubValidationError("mp-slug must be a string")
|
|
|
|
# Crossposting only to the targets asked for: absent means none (v2.9.0)
|
|
requested_targets = []
|
|
for key in ("mp-syndicate-to", "mp-syndicate-to[]"):
|
|
if key in commands:
|
|
value = commands[key]
|
|
requested_targets += value if isinstance(value, list) else [value]
|
|
|
|
try:
|
|
properties = normalize_properties(data)
|
|
like_of = extract_url_property(properties, "like-of")
|
|
repost_of = extract_url_property(properties, "repost-of")
|
|
bookmark_of = extract_url_property(properties, "bookmark-of")
|
|
if sum(bool(u) for u in (like_of, repost_of, bookmark_of)) > 1:
|
|
raise MicropubValidationError("A post can only be one of a like, repost or bookmark")
|
|
for prop in UNSUPPORTED_MEDIA:
|
|
if properties.get(prop) or (files and (files.getlist(prop) or files.getlist(f"{prop}[]"))):
|
|
raise MicropubValidationError(f"{prop} posts are not supported")
|
|
has_content = _has_text(properties.get("content")) or _has_text(properties.get("summary"))
|
|
photos = extract_photos(properties) + _save_uploads(files)
|
|
title = extract_title(properties)
|
|
# Photo posts may have no text (v2.6.5), nor titled posts (v2.9.0)
|
|
content = (
|
|
extract_content(properties)
|
|
if has_content or not (like_of or repost_of or bookmark_of or photos or title)
|
|
else ""
|
|
)
|
|
content = localize_inline_images(drop_title_heading(content, title))
|
|
# A summary with content is the author's summary; alone it is the
|
|
# content (Post Type Discovery), as extract_content does (v2.16.0)
|
|
summary = extract_summary(properties) if _has_text(properties.get("content")) else None
|
|
tags = extract_tags(properties)
|
|
published_date = extract_published_date(properties)
|
|
published = extract_post_status(properties) and not extract_visibility_draft(properties)
|
|
if drafts_only:
|
|
published = False
|
|
in_reply_to = extract_in_reply_to(properties)
|
|
fmt = content_format(properties) if has_content else None
|
|
# Look up and download photos before the note exists, so a bad photo
|
|
# can't leave a half-made post behind (v2.6.5)
|
|
media_ids, captions = _resolve_photos(photos)
|
|
except MicropubError:
|
|
raise
|
|
except Exception as e:
|
|
current_app.logger.error(f"Property extraction failed: {e}")
|
|
raise MicropubValidationError("Could not read the post's properties")
|
|
|
|
note = None
|
|
try:
|
|
note = create_note(
|
|
content=content,
|
|
title=title,
|
|
summary=summary,
|
|
published=published,
|
|
created_at=published_date,
|
|
custom_slug=custom_slug,
|
|
tags=tags if tags else None,
|
|
in_reply_to=in_reply_to,
|
|
like_of=like_of,
|
|
repost_of=repost_of,
|
|
bookmark_of=bookmark_of,
|
|
has_media=bool(media_ids),
|
|
content_format=fmt,
|
|
)
|
|
|
|
if media_ids:
|
|
from starpunk.media import attach_media_to_note
|
|
attach_media_to_note(note.id, media_ids, captions)
|
|
|
|
# Crosspost after photos are attached (v2.1.0); drafts wait until published
|
|
from starpunk.syndication import resolve_targets, select_targets
|
|
select_targets(note.id, resolve_targets(requested_targets))
|
|
|
|
return "", 201, {"Location": note.url}
|
|
|
|
except InvalidNoteDataError as e:
|
|
raise MicropubValidationError(str(e))
|
|
except MicropubError:
|
|
raise
|
|
except Exception as e:
|
|
current_app.logger.error(f"Failed to create note via Micropub: {e}")
|
|
# The client is told it failed, so don't leave the post up (v2.6.5)
|
|
if note is not None:
|
|
try:
|
|
from starpunk.notes import delete_note
|
|
delete_note(id=note.id, soft=False)
|
|
except Exception as cleanup:
|
|
current_app.logger.error(f"Could not remove failed note {note.slug}: {cleanup}")
|
|
raise MicropubError("server_error", "Failed to create post", status_code=500)
|
|
|
|
|
|
def handle_update(data: dict, token_info: dict):
|
|
"""
|
|
Handle Micropub update action (v2.4.0)
|
|
|
|
JSON body: {"action": "update", "url": ..., "replace": {...},
|
|
"add": {...}, "delete": [...] or {...}}. Edits follow to crossposts.
|
|
"""
|
|
from starpunk.syndication import note_changed
|
|
|
|
_require_scope(token_info, "update")
|
|
note = _note_from_url(_first(data.get("url")))
|
|
|
|
replace = data.get("replace") or {}
|
|
add = data.get("add") or {}
|
|
delete = data.get("delete") or {}
|
|
if not isinstance(replace, dict) or not isinstance(add, dict) or not isinstance(delete, (dict, list)):
|
|
raise MicropubValidationError("replace and add must be objects; delete an object or list")
|
|
for prop, values in list(replace.items()) + list(add.items()) + (
|
|
list(delete.items()) if isinstance(delete, dict) else []):
|
|
if not isinstance(values, list):
|
|
raise MicropubValidationError(f"Values for {prop} must be an array")
|
|
if not (replace or add or delete):
|
|
raise MicropubValidationError("An update needs replace, add or delete")
|
|
touched = set(replace) | set(add) | set(delete)
|
|
unsupported = sorted(touched - UPDATABLE)
|
|
if unsupported:
|
|
raise MicropubValidationError(f"Updating {', '.join(unsupported)} is not supported")
|
|
if set(add) - {"category", "photo"}:
|
|
raise MicropubValidationError("Only category and photo can be added to")
|
|
|
|
from starpunk.tags import get_note_tags
|
|
|
|
title, summary, body = note.title, note.summary, note.content
|
|
tags = [t["display_name"] for t in get_note_tags(note.id, entered_order=True)]
|
|
photos = _note_photos(note)
|
|
changes = {}
|
|
|
|
# Removals first, then replacements, then additions
|
|
if isinstance(delete, list):
|
|
for prop in delete:
|
|
if prop == "name":
|
|
title = None
|
|
elif prop == "summary":
|
|
summary = None
|
|
elif prop == "content":
|
|
body = ""
|
|
elif prop == "category":
|
|
tags = []
|
|
elif prop == "photo":
|
|
photos = []
|
|
elif prop == "in-reply-to":
|
|
changes["in_reply_to"] = ""
|
|
elif prop == "post-status":
|
|
changes["published"] = True
|
|
else:
|
|
for prop, values in delete.items():
|
|
if prop == "category":
|
|
drop = {v.lower() for v in values}
|
|
tags = [t for t in tags if t.lower() not in drop]
|
|
elif prop == "photo":
|
|
drop = {p["url"] for p in extract_photos({"photo": values})}
|
|
photos = [p for p in photos if p["url"] not in drop]
|
|
else:
|
|
raise MicropubValidationError(f"Can't delete individual values of {prop}")
|
|
|
|
if "content" in replace:
|
|
# Empty text is fine if the note keeps its photos; update_note checks (v2.6.5)
|
|
body = localize_inline_images(extract_content(replace)) if _has_text(replace["content"]) else ""
|
|
changes["content_format"] = content_format(replace) if body else None
|
|
if "name" in replace:
|
|
title = extract_title(replace)
|
|
if "summary" in replace:
|
|
summary = extract_summary(replace)
|
|
if "category" in replace:
|
|
tags = extract_tags(replace)
|
|
if "photo" in replace:
|
|
photos = extract_photos(replace)
|
|
if "in-reply-to" in replace:
|
|
changes["in_reply_to"] = extract_in_reply_to(replace) or ""
|
|
if "post-status" in replace:
|
|
changes["published"] = extract_post_status(replace)
|
|
|
|
if "category" in add:
|
|
known = {t.lower() for t in tags}
|
|
tags += [t for t in extract_tags(add) if t.lower() not in known]
|
|
if "photo" in add:
|
|
photos += extract_photos(add)
|
|
|
|
# Text may go only if photos stay, it has a title, or it's a like, repost
|
|
# or bookmark (v2.6.5)
|
|
if not (body or "").strip() and not (photos or title or note.reacts_to):
|
|
raise MicropubValidationError("A post needs text, a title or a photo")
|
|
|
|
# Photos must all resolve before anything changes (v2.9.0)
|
|
if "photo" in touched:
|
|
media_ids, captions = _resolve_photos(photos)
|
|
|
|
if title != note.title:
|
|
changes["title"] = title
|
|
if summary != note.summary:
|
|
changes["summary"] = summary
|
|
body = drop_title_heading(body, title)
|
|
if body != note.content:
|
|
changes["content"] = body
|
|
elif "content_format" in changes and changes["content_format"] == note.content_format:
|
|
del changes["content_format"]
|
|
if {"category"} & touched:
|
|
changes["tags"] = tags
|
|
|
|
try:
|
|
if changes:
|
|
update_note(id=note.id, has_media=bool(photos), **changes)
|
|
if "photo" in touched:
|
|
from starpunk.media import attach_media_to_note
|
|
attach_media_to_note(note.id, media_ids, captions)
|
|
note_changed(note.id) # attach_media_to_note tells WebSub
|
|
except InvalidNoteDataError as e:
|
|
raise MicropubValidationError(str(e))
|
|
except MicropubError:
|
|
raise
|
|
except Exception as e:
|
|
current_app.logger.error(f"Failed to update note via Micropub: {e}")
|
|
raise MicropubError("server_error", "Failed to update post", status_code=500)
|
|
|
|
# Adding or removing a title moves the post between /note/ and /article/:
|
|
# the spec says to answer 201 with the new URL (v2.17.0)
|
|
if bool(title) != bool(note.title):
|
|
from starpunk.utils import post_url
|
|
return "", 201, {"Location": post_url(note.slug, title)}
|
|
return "", 204
|
|
|
|
|
|
def handle_delete(data: dict, token_info: dict, undelete: bool = False):
|
|
"""Handle Micropub delete / undelete (v2.4.0). Deletes are soft so they can be undone."""
|
|
_require_scope(token_info, "delete")
|
|
url = _first(data.get("url"))
|
|
try:
|
|
if undelete:
|
|
undelete_note(_note_from_url(url, deleted=True))
|
|
else:
|
|
delete_note(id=_note_from_url(url).id, soft=True)
|
|
except MicropubError:
|
|
raise
|
|
except Exception as e:
|
|
current_app.logger.error(f"Micropub {'undelete' if undelete else 'delete'} failed: {e}")
|
|
raise MicropubError("server_error", "Failed to change post", status_code=500)
|
|
return "", 204
|
|
|
|
|
|
def _syndicate_to() -> list:
|
|
"""Configured crosspost targets in Micropub syndicate-to form"""
|
|
from starpunk.syndication import get_targets
|
|
|
|
return [{"uid": t.uid, "name": t.name} for t in get_targets().values()]
|
|
|
|
|
|
def note_to_mf2(note, wanted: Optional[list] = None) -> dict:
|
|
"""
|
|
A note as Microformats2 JSON, the inverse of create
|
|
|
|
The title is returned as name and the author's summary as summary.
|
|
"""
|
|
from starpunk.syndication import get_note_syndications
|
|
|
|
content = note.content
|
|
props = {
|
|
# HTML-authored content comes back as HTML (3.7.2, v2.9.0)
|
|
"content": [{"html": content} if note.content_format == "html" else content],
|
|
"published": [iso_utc(note.created_at)],
|
|
"url": [note.url],
|
|
"post-status": ["published" if note.published else "draft"],
|
|
}
|
|
if note.title:
|
|
props["name"] = [note.title]
|
|
if note.summary:
|
|
props["summary"] = [note.summary]
|
|
from starpunk.tags import get_note_tags
|
|
|
|
tags = get_note_tags(note.id, entered_order=True)
|
|
if tags:
|
|
props["category"] = [tag["display_name"] for tag in tags]
|
|
if getattr(note, "in_reply_to", None):
|
|
props["in-reply-to"] = [note.in_reply_to]
|
|
if getattr(note, "like_of", None):
|
|
props["like-of"] = [note.like_of]
|
|
if getattr(note, "repost_of", None):
|
|
props["repost-of"] = [note.repost_of]
|
|
if getattr(note, "bookmark_of", None):
|
|
props["bookmark-of"] = [note.bookmark_of]
|
|
if not content.strip():
|
|
del props["content"] # photo posts, likes, reposts and bookmarks without text
|
|
photos = _note_photos(note)
|
|
if photos:
|
|
props["photo"] = [{"value": p["url"], "alt": p["alt"]} for p in photos]
|
|
synced = [s["remote_url"] for s in get_note_syndications(note.id) if s.get("remote_url")]
|
|
if synced:
|
|
props["syndication"] = synced
|
|
|
|
if wanted:
|
|
return {"properties": {k: v for k, v in props.items() if k in wanted}}
|
|
return {"type": ["h-entry"], "properties": props}
|
|
|
|
|
|
def _all_categories(prefix: str = "") -> list:
|
|
"""Tags on posts that exist (drafts included), most used first (q=category)"""
|
|
from starpunk.database import get_db
|
|
|
|
# Inner joins: tags left behind by edits or soft-deleted posts don't count
|
|
rows = get_db(current_app).execute(
|
|
"""
|
|
SELECT t.display_name, COUNT(*) AS uses
|
|
FROM tags t
|
|
JOIN note_tags nt ON nt.tag_id = t.id
|
|
JOIN notes n ON n.id = nt.note_id AND n.deleted_at IS NULL
|
|
GROUP BY t.id ORDER BY uses DESC, t.display_name
|
|
"""
|
|
).fetchall()
|
|
prefix = prefix.lower()
|
|
return [r["display_name"] for r in rows if not prefix or prefix in r["display_name"].lower()]
|
|
|
|
|
|
QUERIES = ["config", "source", "syndicate-to", "category"]
|
|
|
|
|
|
def handle_query(args, token_info: dict):
|
|
"""
|
|
Handle Micropub query endpoints
|
|
|
|
Supports:
|
|
- q=config: Server configuration
|
|
- q=source&url=...[&properties[]=...]: One post in Microformats2 JSON
|
|
- q=source (no url) [&limit=N&offset=N]: Recent posts, drafts included
|
|
- q=syndicate-to: Crosspost targets
|
|
- q=category[&filter=...]: Tags in use
|
|
|
|
Args:
|
|
args: Query arguments (werkzeug MultiDict or plain dict)
|
|
"""
|
|
def get_list(key):
|
|
if hasattr(args, "getlist"):
|
|
return args.getlist(key) + args.getlist(f"{key}[]")
|
|
value = args.get(key) or args.get(f"{key}[]")
|
|
return value if isinstance(value, list) else ([value] if value else [])
|
|
|
|
q = args.get("q")
|
|
|
|
# Posts (drafts included) and tags are for apps that may post (v2.9.0);
|
|
# config and syndicate-to are fine for any token
|
|
if q in ("source", "category"):
|
|
_require_scope(token_info, "create", "update", "delete", "draft")
|
|
|
|
if q == "config":
|
|
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
|
|
return jsonify({
|
|
"media-endpoint": f"{site_url}/micropub/media",
|
|
"syndicate-to": _syndicate_to(),
|
|
"q": QUERIES,
|
|
"post-types": [
|
|
{"type": "note", "name": "Note", "properties": ["content"]},
|
|
{"type": "article", "name": "Article", "properties": ["name", "content"]},
|
|
{"type": "photo", "name": "Photo", "properties": ["photo"]},
|
|
{"type": "reply", "name": "Reply", "properties": ["in-reply-to", "content"]},
|
|
{"type": "like", "name": "Like", "properties": ["like-of"]},
|
|
{"type": "repost", "name": "Repost", "properties": ["repost-of", "content"]},
|
|
{"type": "bookmark", "name": "Bookmark", "properties": ["bookmark-of", "content"]},
|
|
],
|
|
}), 200
|
|
|
|
if q == "source":
|
|
url = args.get("url")
|
|
wanted = get_list("properties")
|
|
if url:
|
|
try:
|
|
note = _note_from_url(url)
|
|
except MicropubError as e:
|
|
return error_response("invalid_request" if e.status_code == 400 else e.error,
|
|
e.error_description, e.status_code)
|
|
return jsonify(note_to_mf2(note, wanted)), 200
|
|
try:
|
|
limit = max(1, min(int(args.get("limit", 10)), 50))
|
|
offset = max(0, int(args.get("offset", 0)))
|
|
except ValueError:
|
|
return error_response("invalid_request", "limit and offset must be numbers")
|
|
notes = list_notes(published_only=False, limit=limit, offset=offset)
|
|
items = [note_to_mf2(n, wanted) for n in notes]
|
|
return jsonify({"items": items}), 200
|
|
|
|
if q == "syndicate-to":
|
|
return jsonify({"syndicate-to": _syndicate_to()}), 200
|
|
|
|
if q == "category":
|
|
return jsonify({"categories": _all_categories(args.get("filter") or "")}), 200
|
|
|
|
return error_response("invalid_request", f"Unknown query: {q}" if q else "Missing q parameter")
|