feat: Micropub update, delete/undelete, drafts, replies (v2.4.0)
Build Container / build (push) Successful in 6s

Update (replace/add/delete) for content, name, category, photo,
in-reply-to, post-status; soft delete with undelete; post-status drafts;
in-reply-to; multipart and remote photos; q=source lists and properties[];
q=category; media scope. Fix media endpoint 404 at the advertised
/micropub/media path. ADR-067.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
PhilandClaude Opus 5.5 committed 2026-10-31 19:53:18 -06:00
1 parent 88088e10e1
commit 0d3a5cd519
8 files changed
+757 -206

No files matched your search

+17
View File
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [2.4.0] - 2026-10-31
### Added
- **Micropub update** (`action=update`, JSON): replace/add/delete for `content`, `name`, `category`, `photo`, `in-reply-to`, `post-status`; edits follow to crossposts (ADR-067)
- **Micropub delete and undelete**: soft delete, restorable; crossposts are removed and re-posted
- **Drafts** via `post-status: draft`; **replies** via `in-reply-to`
- Photos uploaded in a multipart create request; photos hosted elsewhere are downloaded (public addresses only, 20 MB cap)
- `q=source` without `url` lists recent posts (drafts included, `limit`/`offset`); `properties[]` filter; returns photos, syndication links, reply and post status
- `q=category` (tag suggestions, optional `filter`); `q=config` lists supported queries and post types
- Media endpoint accepts the `media` scope
### Fixed
- Media endpoint was advertised at `/micropub/media` but served at `/media` (404 for clients); now both work
- Unsupported Micropub types (e.g. `h=event`) were silently stored as notes; now rejected
## [2.3.3] - 2026-10-31
### Fixed
@@ -0,0 +1,34 @@
# ADR-067: Micropub update, delete, drafts and replies
## Status
Accepted (v2.4.0, 2026-10-31)
## Context
The Micropub endpoint could only create published notes. Apps could not edit
or delete posts, drafts and replies were dropped, and photos sent with the
post or hosted elsewhere were lost.
## Decision
1. **Update** (JSON only, `update` scope). Supported properties are the ones a
note can store: `content`, `name` (the `# Heading` first line),
`category`, `photo`, `in-reply-to`, `post-status`. Anything else is a 400,
not silently ignored. Order: delete, then replace, then add (`add` only for
`category` and `photo`). Success is 204.
2. **Delete is soft** (`delete` scope) so `undelete` can restore the note and
its file from `.trash/`. Crossposts are removed on delete and posted again
on undelete.
3. **Drafts**: `post-status: draft` creates an unpublished note; crossposts
wait until it is published.
4. **Photos**: multipart uploads are saved like media-endpoint uploads; remote
URLs are downloaded only from public IP addresses, up to 20 MB, max 4.
5. **Queries**: `q=source` returns everything create accepts (round-trip);
without `url` it lists recent posts, drafts included, for editing apps.
`q=category` lists tags by use.
## Consequences
- `published` (backdating) can be set on create but not changed by update.
- Likes, reposts and bookmarks remain unsupported (round 2).
+1 -1
View File
@@ -464,5 +464,5 @@ def create_app(config=None):
# Package version (Semantic Versioning 2.0.0)
# See docs/standards/versioning-strategy.md for details
__version__ = "2.3.3"
__version__ = "2.4.0"
__version_info__ = (2, 1, 0)
+417 -160
View File
@@ -10,6 +10,8 @@ Functions:
extract_title: Get the explicit title (name) 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
@@ -29,7 +31,10 @@ from typing import Optional
from flask import Request, current_app, jsonify
from starpunk.models import split_title
from starpunk.notes import create_note, get_note, InvalidNoteDataError, NoteNotFoundError
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
@@ -137,6 +142,8 @@ def normalize_properties(data: dict) -> dict:
# 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
@@ -258,6 +265,46 @@ def extract_published_date(properties: dict) -> Optional[datetime]:
# 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", "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_in_reply_to(properties: dict) -> Optional[str]:
value = _first(properties.get("in-reply-to"))
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("in-reply-to must be an http(s) URL")
return value or None
def extract_photos(properties: dict) -> list[dict[str, str]]:
"""
@@ -265,101 +312,172 @@ def extract_photos(properties: dict) -> list[dict[str, str]]:
Handles both simple URL strings and structured photo objects with alt text.
Args:
properties: Normalized Micropub properties dict
Returns:
List of dicts with 'url' and optional 'alt' keys
Examples:
>>> # Simple URL
>>> extract_photos({'photo': ['https://example.com/photo.jpg']})
[{'url': 'https://example.com/photo.jpg', 'alt': ''}]
>>> # With alt text
>>> extract_photos({'photo': [{'value': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]})
[{'url': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]
"""
photos = properties.get("photo", [])
result = []
for photo in photos:
for photo in properties.get("photo", []):
if isinstance(photo, str):
# Simple URL string
result.append({'url': photo, 'alt': ''})
elif isinstance(photo, dict):
# Structured object with value and alt
url = photo.get('value') or photo.get('url', '')
alt = photo.get('alt', '')
if url:
result.append({'url': url, 'alt': alt})
result.append({'url': url, 'alt': photo.get('alt', '')})
return result
def _attach_photos_to_note(note_id: int, photos: list[dict[str, str]]) -> None:
"""
Attach photos to a note by URL
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
Photos must already exist on this server (uploaded via media endpoint).
External URLs are accepted but stored as-is (no download).
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)
Args:
note_id: ID of the note to attach to
photos: List of dicts with 'url' and 'alt' keys
"""
def _fetch_remote_photo(url: str) -> Optional[int]:
"""Download a photo hosted elsewhere into the media library. Returns media id."""
from urllib.parse import urlparse
import httpx
from starpunk.media import save_media
parsed = urlparse(url)
if parsed.scheme not in ("http", "https") or not parsed.hostname:
return None
if not current_app.config.get("TESTING") and not _public_address(parsed.hostname):
current_app.logger.warning(f"Refusing to fetch photo from non-public address: {url}")
return None
try:
with httpx.stream("GET", url, timeout=20.0, follow_redirects=True) as response:
response.raise_for_status()
data = bytearray()
for chunk in response.iter_bytes():
data += chunk
if len(data) > MAX_REMOTE_PHOTO_BYTES:
raise ValueError("photo too large")
name = parsed.path.rsplit("/", 1)[-1] or "photo.jpg"
return save_media(bytes(data), name)["id"]
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
return _fetch_remote_photo(url)
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 media_id:
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
# Normalize SITE_URL by stripping trailing slash for consistent comparison
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
db = get_db(current_app)
media_ids = []
captions = []
# Log warning if photos are being truncated
if len(photos) > 4:
current_app.logger.warning(
f"Micropub create received {len(photos)} photos, truncating to 4 per ADR-057"
)
for photo in photos[:4]: # Max 4 photos per ADR-057
url = photo['url']
alt = photo.get('alt', '')
# Check if URL is on our server
if url.startswith(site_url) or url.startswith('/media/'):
# Extract path from URL
if url.startswith(site_url):
path = url[len(site_url):]
else:
path = url
# Remove leading /media/ if present
if path.startswith('/media/'):
path = path[7:]
# Look up media by path
row = db.execute(
"SELECT id FROM media WHERE path = ?",
(path,)
).fetchone()
if row:
media_ids.append(row[0])
captions.append(alt)
else:
current_app.logger.warning(f"Photo URL not found in media: {url}")
else:
# External URL - log but don't fail
current_app.logger.info(f"External photo URL ignored: {url}")
if media_ids:
media_ids, captions = _resolve_photos(photos)
if media_ids or not photos:
attach_media_to_note(note_id, media_ids, captions)
def handle_create(data: dict, token_info: dict):
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> 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"):
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
@@ -369,32 +487,24 @@ def handle_create(data: dict, token_info: dict):
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)
Raises:
MicropubError: If scope insufficient or creation fails
"""
# Check scope
if not check_scope("create", token_info.get("scope", "")):
raise MicropubError(
"insufficient_scope", "Token lacks create scope", status_code=403
)
_require_scope(token_info, "create")
_check_type(data)
# Extract mp-slug BEFORE normalizing properties (it's not a property!)
# mp-slug is a Micropub server extension parameter that gets filtered during normalization
# mp-slug and mp-syndicate-to are server commands, not properties
custom_slug = None
if isinstance(data, dict) and 'mp-slug' in data:
# Handle both form-encoded (list) and JSON (could be string or list)
slug_value = data.get('mp-slug')
if isinstance(slug_value, list) and slug_value:
custom_slug = slug_value[0]
elif isinstance(slug_value, str):
custom_slug = slug_value
# mp-syndicate-to is also a server command, not a property (v2.1.0).
# Absent means "all targets"; present means exactly those.
# Absent means "all targets"; present means exactly those (v2.1.0)
requested_targets = None
if isinstance(data, dict):
for key in ("mp-syndicate-to", "mp-syndicate-to[]"):
@@ -404,54 +514,167 @@ def handle_create(data: dict, token_info: dict):
value if isinstance(value, list) else [value]
)
# Normalize and extract properties
try:
properties = normalize_properties(data)
content = extract_content(properties)
title = extract_title(properties)
tags = extract_tags(properties)
published_date = extract_published_date(properties)
photos = extract_photos(properties) # v1.4.0
except MicropubValidationError as e:
raise e
published = extract_post_status(properties)
in_reply_to = extract_in_reply_to(properties)
photos = extract_photos(properties) + _save_uploads(files)
except MicropubError:
raise
except Exception as e:
current_app.logger.error(f"Property extraction failed: {e}")
raise MicropubValidationError(f"Failed to parse request: {str(e)}")
# Create note using existing CRUD
try:
note = create_note(
content=add_title_heading(content, title),
published=True, # Micropub posts are published by default
published=published,
created_at=published_date,
custom_slug=custom_slug,
tags=tags if tags else None # Pass tags to create_note (v1.3.0)
tags=tags if tags else None,
in_reply_to=in_reply_to,
)
# Attach photos if present (v1.4.0)
if photos:
_attach_photos_to_note(note.id, photos)
# Crosspost after photos are attached (v2.1.0)
# Crosspost after photos are attached (v2.1.0); drafts wait until published
from starpunk.syndication import get_targets, resolve_targets, select_targets
if requested_targets is None:
select_targets(note.id, list(get_targets()))
else:
select_targets(note.id, resolve_targets(requested_targets))
permalink = absolute_url_for("public.note", slug=note.slug)
# Return 201 Created with Location header
return "", 201, {"Location": permalink}
return "", 201, {"Location": absolute_url_for("public.note", slug=note.slug)}
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}")
raise MicropubError(
"server_error", "Failed to create post", status_code=500
)
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()):
if not isinstance(values, list):
raise MicropubValidationError(f"Values for {prop} must be an array")
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")
title, body = split_title(note.content)
tags = [t["display_name"] for t in note.tags]
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 == "content":
raise MicropubValidationError("content can't be deleted")
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:
body = extract_content(replace)
if "name" in replace:
title = extract_title(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)
new_content = add_title_heading(body, title)
if new_content != note.content:
changes["content"] = new_content
if {"category"} & touched:
changes["tags"] = tags
try:
if changes:
update_note(id=note.id, **changes)
if "photo" in touched:
_attach_photos_to_note(note.id, photos)
note_changed(note.id)
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)
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:
@@ -461,82 +684,116 @@ def _syndicate_to() -> list:
return [{"uid": t.uid, "name": t.name} for t in get_targets().values()]
def handle_query(args: dict, token_info: dict):
def note_to_mf2(note, wanted: Optional[list] = None) -> dict:
"""
A note as Microformats2 JSON, the inverse of create
A '# Heading' first line is the title, returned as name.
"""
from starpunk.syndication import get_note_syndications
title, content = split_title(note.content)
props = {
"content": [content],
"published": [note.created_at.isoformat()],
"url": [absolute_url_for("public.note", slug=note.slug)],
"post-status": ["published" if note.published else "draft"],
}
if title:
props["name"] = [title]
if note.tags:
props["category"] = [tag["display_name"] for tag in note.tags]
if getattr(note, "in_reply_to", None):
props["in-reply-to"] = [note.in_reply_to]
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 in use, most used first (q=category)"""
from starpunk.database import get_db
rows = get_db(current_app).execute(
"""
SELECT t.display_name, COUNT(nt.note_id) AS uses
FROM tags t LEFT JOIN note_tags nt ON nt.tag_id = t.id
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: Return server configuration
- q=source: Return post source in Microformats2 JSON
- q=syndicate-to: Return syndication targets
- 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 string arguments
token_info: Authenticated token information
Returns:
Tuple of (response, status_code)
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")
if q == "config":
# Return server configuration with media endpoint (v1.4.0)
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
config = {
return jsonify({
"media-endpoint": f"{site_url}/micropub/media",
"syndicate-to": _syndicate_to(),
"q": QUERIES,
"post-types": [
{"type": "note", "name": "Note", "properties": ["content"]},
{"type": "photo", "name": "Photo", "properties": ["photo"]}
{"type": "article", "name": "Article", "properties": ["name", "content"]},
{"type": "photo", "name": "Photo", "properties": ["photo"]},
{"type": "reply", "name": "Reply", "properties": ["in-reply-to", "content"]},
],
}
return jsonify(config), 200
}), 200
elif q == "source":
# Return source of a specific post
if q == "source":
url = args.get("url")
if not url:
return error_response("invalid_request", "No URL provided")
# Extract slug from 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:
# URL format: https://example.com/note/{slug}
slug = url.rstrip("/").split("/")[-1]
note = get_note(slug)
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
# Check if note exists
if note is None:
return error_response("invalid_request", "Post not found")
except NoteNotFoundError:
return error_response("invalid_request", "Post not found")
except Exception as e:
current_app.logger.error(f"Failed to get note source: {e}")
return error_response("server_error", "Failed to retrieve post")
# Convert note to Micropub Microformats2 format. A '# Heading' first
# line is the title, returned as name (mirrors how create stores it).
title, content = split_title(note.content)
mf2 = {
"type": ["h-entry"],
"properties": {
"content": [content],
"published": [note.created_at.isoformat()],
"url": [absolute_url_for("public.note", slug=note.slug)],
},
}
if title:
mf2["properties"]["name"] = [title]
# Add tags if present (v1.3.0)
if note.tags:
mf2["properties"]["category"] = [tag["display_name"] for tag in note.tags]
return jsonify(mf2), 200
elif q == "syndicate-to":
if q == "syndicate-to":
return jsonify({"syndicate-to": _syndicate_to()}), 200
else:
return error_response("invalid_request", f"Unknown query: {q}")
if q == "category":
return jsonify({"categories": _all_categories(args.get("filter") or "")}), 200
return error_response("invalid_request", f"Unknown query: {q}")
+49
View File
@@ -1034,3 +1034,52 @@ def delete_note(
# 6. RETURN (no value)
return None
def undelete_note(slug: str) -> Note:
"""
Restore a soft-deleted note (v2.4.0, Micropub undelete)
Moves the file back from .trash/ and clears deleted_at. Crossposts are
queued again, so a note deleted from them is posted again.
Raises:
NoteNotFoundError: If there is no soft-deleted note with this slug
"""
import shutil
from starpunk.utils import TRASH_DIR_NAME
db = get_db(current_app)
row = db.execute(
"SELECT id, file_path, created_at FROM notes WHERE slug = ? AND deleted_at IS NOT NULL",
(slug,),
).fetchone()
if row is None:
raise NoteNotFoundError(slug)
data_dir = Path(current_app.config["DATA_PATH"])
note_path = data_dir / row["file_path"]
if not note_path.exists():
# delete_note_file put it in .trash/<year>/<month>/<name>
parts = Path(row["file_path"]).parts
candidates = []
if "notes" in parts and len(parts) > parts.index("notes") + 2:
i = parts.index("notes")
candidates.append(data_dir / TRASH_DIR_NAME / parts[i + 1] / parts[i + 2] / note_path.name)
candidates += sorted((data_dir / TRASH_DIR_NAME).glob(f"*/*/{note_path.name}"))
source = next((c for c in candidates if c.exists()), None)
if source is None:
raise NoteSyncError("undelete", f"Trashed file not found for {slug}", "Cannot restore note file")
note_path.parent.mkdir(parents=True, exist_ok=True)
shutil.move(str(source), str(note_path))
db.execute("UPDATE notes SET deleted_at = NULL WHERE id = ?", (row["id"],))
db.commit()
try:
from starpunk.syndication import note_changed
note_changed(row["id"])
except Exception as e:
current_app.logger.warning(f"Failed to queue syndication after undelete: {e}")
return get_note(slug=slug)
+18 -18
View File
@@ -27,6 +27,8 @@ from starpunk.micropub import (
extract_bearer_token,
error_response,
handle_create,
handle_delete,
handle_update,
handle_query,
)
from starpunk.indieauth import verify_access_token, check_scope
@@ -49,8 +51,8 @@ def micropub_endpoint():
POST requests:
Handle action operations (form-encoded or JSON):
- action=create (or no action): Create new post
- action=update: Update existing post (not supported in V1)
- action=delete: Delete post (not supported in V1)
- action=update: Update existing post (JSON; replace/add/delete)
- action=delete / action=undelete: Delete or restore a post
Authentication:
Requires valid bearer token in Authorization header or
@@ -79,7 +81,7 @@ def micropub_endpoint():
# Handle query endpoints (GET requests)
if request.method == "GET":
try:
return handle_query(request.args.to_dict(), token_info)
return handle_query(request.args, token_info)
except MicropubError as e:
return error_response(e.error, e.error_description, e.status_code)
except Exception as e:
@@ -95,23 +97,19 @@ def micropub_endpoint():
data = request.get_json() or {}
action = data.get("action", "create")
else:
# Form-encoded or multipart (V1 only supports form-encoded)
# Form-encoded or multipart (files handled separately)
data = request.form.to_dict(flat=False)
action = data.get("action", ["create"])[0]
# Route to appropriate handler
if action == "create":
return handle_create(data, token_info)
return handle_create(data, token_info, files=request.files)
elif action == "update":
# V1: Update not supported
return error_response(
"invalid_request", "Update action not supported in V1", 400
)
elif action == "delete":
# V1: Delete not supported
return error_response(
"invalid_request", "Delete action not supported in V1", 400
)
if "application/json" not in content_type:
return error_response("invalid_request", "Updates must be sent as JSON", 400)
return handle_update(data, token_info)
elif action in ("delete", "undelete"):
return handle_delete(data, token_info, undelete=(action == "undelete"))
else:
return error_response("invalid_request", f"Unknown action: {action}", 400)
@@ -122,7 +120,8 @@ def micropub_endpoint():
return error_response("server_error", "An unexpected error occurred", 500)
@bp.route('/media', methods=['POST'])
@bp.route('/micropub/media', methods=['POST'])
@bp.route('/media', methods=['POST']) # old path, kept for existing clients
def media_endpoint():
"""
Micropub media endpoint for file uploads
@@ -145,11 +144,12 @@ def media_endpoint():
if not token_info:
return error_response("unauthorized", "Invalid or expired access token", 401)
# Check scope (create scope allows media upload)
if not check_scope("create", token_info.get("scope", "")):
# Check scope: "media", or "create" for older clients
scope = token_info.get("scope", "")
if not (check_scope("media", scope) or check_scope("create", scope)):
return error_response(
"insufficient_scope",
"Token lacks create scope",
"Token lacks media or create scope",
403
)
+15 -27
View File
@@ -372,33 +372,21 @@ def test_micropub_missing_content(client, mock_valid_token):
assert data['error'] == 'invalid_request'
def test_micropub_unsupported_action(client, mock_valid_token):
"""Test unsupported actions (update, delete) return error"""
def test_micropub_update_delete_need_scope(client, mock_valid_token):
"""A create-only token can't update or delete (v2.4.0)"""
with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token):
# Test update
response = client.post(
'/micropub',
json={
'action': 'update',
'url': 'https://example.com/note/123'
},
headers={'Authorization': 'Bearer valid_token'}
)
for action in ('update', 'delete', 'undelete'):
response = client.post(
'/micropub',
json={'action': action, 'url': 'https://example.com/note/123', 'replace': {}},
headers={'Authorization': 'Bearer valid_token'}
)
assert response.status_code == 403, action
assert response.get_json()['error'] == 'insufficient_scope'
def test_micropub_unknown_action(client, mock_valid_token):
with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token):
response = client.post('/micropub', json={'action': 'frobnicate'},
headers={'Authorization': 'Bearer valid_token'})
assert response.status_code == 400
data = response.get_json()
assert 'not supported' in data['error_description']
# Test delete
response = client.post(
'/micropub',
json={
'action': 'delete',
'url': 'https://example.com/note/123'
},
headers={'Authorization': 'Bearer valid_token'}
)
assert response.status_code == 400
data = response.get_json()
assert 'not supported' in data['error_description']
+206
View File
@@ -0,0 +1,206 @@
"""
Micropub round 1 (v2.4.0): update, delete/undelete, drafts, replies,
multipart and remote photos, q=source lists and filters, q=category.
Uses real tokens from StarPunk's own IndieAuth server.
"""
import io
import httpx
import pytest
from PIL import Image
from starpunk import create_app
from starpunk.indieauth import create_access_token
from starpunk.notes import get_note
SITE = "https://blog.example.com"
@pytest.fixture
def app(tmp_path):
data = tmp_path / "data"
return create_app({
"TESTING": True, "SITE_URL": SITE, "ADMIN_ME": "https://example.com",
"SESSION_SECRET": "x", "DATA_PATH": data, "NOTES_PATH": data / "notes",
"DATABASE_PATH": data / "starpunk.db",
})
def auth(app, scope="create update delete media"):
with app.test_request_context():
token = create_access_token("https://quill.example/", scope)["access_token"]
return {"Authorization": f"Bearer {token}"}
@pytest.fixture
def client(app):
return app.test_client()
@pytest.fixture
def h(app):
return auth(app)
def jpeg(color="red"):
buf = io.BytesIO()
Image.new("RGB", (64, 48), color).save(buf, format="JPEG")
return buf.getvalue()
def create(client, h, **props):
body = {"type": ["h-entry"], "properties": {"content": ["Hello"], **props}}
response = client.post("/micropub", json=body, headers=h)
assert response.status_code == 201, response.get_json()
return response.headers["Location"]
def note_at(app, url):
with app.app_context():
return get_note(slug=url.rstrip("/").rsplit("/", 1)[1])
def source(client, h, url, *props):
query = f"/micropub?q=source&url={url}" + "".join(f"&properties[]={p}" for p in props)
return client.get(query, headers=h).get_json()
class TestCreate:
def test_draft(self, app, client, h):
url = create(client, h, **{"post-status": ["draft"]})
assert note_at(app, url).published is False
assert client.get(url.replace(SITE, "")).status_code == 404
def test_reply(self, app, client, h):
url = create(client, h, **{"in-reply-to": ["https://other.example/post/1"]})
assert note_at(app, url).in_reply_to == "https://other.example/post/1"
def test_multipart_photo(self, app, client, h):
response = client.post(
"/micropub",
data={"h": "entry", "content": "With a file", "photo": (io.BytesIO(jpeg()), "pic.jpg")},
headers=h, content_type="multipart/form-data",
)
assert response.status_code == 201
assert "photo" in source(client, h, response.headers["Location"])["properties"]
def test_remote_photo_is_downloaded(self, app, client, h, monkeypatch):
transport = httpx.MockTransport(lambda req: httpx.Response(200, content=jpeg("blue")))
monkeypatch.setattr(httpx, "stream", lambda method, url, **kw: httpx.Client(transport=transport).stream(method, url))
url = create(client, h, photo=[{"value": "https://photos.example/cat.jpg", "alt": "A cat"}])
(photo,) = source(client, h, url)["properties"]["photo"]
assert photo["value"].startswith(f"{SITE}/media/") and photo["alt"] == "A cat"
def test_only_h_entry(self, client, h):
response = client.post("/micropub", data={"h": "event", "content": "x"}, headers=h)
assert response.status_code == 400
class TestUpdate:
def update(self, client, h, url, **ops):
return client.post("/micropub", json={"action": "update", "url": url, **ops}, headers=h)
def test_replace_content_keeps_title(self, app, client, h):
url = create(client, h, name=["My Title"])
assert self.update(client, h, url, replace={"content": ["New body"]}).status_code == 204
props = source(client, h, url)["properties"]
assert props["name"] == ["My Title"] and props["content"] == ["New body"]
def test_replace_and_delete_name(self, app, client, h):
url = create(client, h)
self.update(client, h, url, replace={"name": ["Added"]})
assert note_at(app, url).content.startswith("# Added")
self.update(client, h, url, delete=["name"])
assert "name" not in source(client, h, url)["properties"]
def test_categories(self, app, client, h):
url = create(client, h, category=["one", "two"])
self.update(client, h, url, add={"category": ["three", "One"]})
assert source(client, h, url)["properties"]["category"] == ["one", "three", "two"]
self.update(client, h, url, delete={"category": ["two"]})
assert source(client, h, url)["properties"]["category"] == ["one", "three"]
self.update(client, h, url, delete=["category"])
assert "category" not in source(client, h, url)["properties"]
def test_post_status_and_reply(self, app, client, h):
url = create(client, h)
self.update(client, h, url, replace={"post-status": ["draft"], "in-reply-to": ["https://x.example/a"]})
note = note_at(app, url)
assert note.published is False and note.in_reply_to == "https://x.example/a"
self.update(client, h, url, delete=["in-reply-to", "post-status"])
note = note_at(app, url)
assert note.published is True and not note.in_reply_to
def test_photos(self, app, client, h):
uploaded = client.post("/micropub/media", data={"file": (io.BytesIO(jpeg()), "a.jpg")},
headers=h, content_type="multipart/form-data").headers["Location"]
url = create(client, h)
self.update(client, h, url, add={"photo": [{"value": uploaded, "alt": "Red"}]})
assert source(client, h, url)["properties"]["photo"] == [{"value": uploaded, "alt": "Red"}]
self.update(client, h, url, delete={"photo": [uploaded]})
assert "photo" not in source(client, h, url)["properties"]
def test_unsupported_property(self, client, h):
url = create(client, h)
response = self.update(client, h, url, replace={"published": ["2020-01-01T00:00:00Z"]})
assert response.status_code == 400 and "published" in response.get_json()["error_description"]
def test_unknown_post(self, client, h):
response = self.update(client, h, f"{SITE}/note/nope", replace={"content": ["x"]})
assert response.status_code == 404
def test_form_update_rejected(self, client, h):
url = create(client, h)
assert client.post("/micropub", data={"action": "update", "url": url}, headers=h).status_code == 400
class TestDelete:
def test_delete_and_undelete(self, app, client, h):
url = create(client, h, category=["kept"])
path = url.replace(SITE, "")
assert client.post("/micropub", data={"action": "delete", "url": url}, headers=h).status_code == 204
assert client.get(path).status_code == 404
response = client.post("/micropub", json={"action": "undelete", "url": url}, headers=h)
assert response.status_code == 204
assert client.get(path).status_code == 200
assert source(client, h, url)["properties"]["category"] == ["kept"]
def test_undelete_needs_a_deleted_post(self, client, h):
url = create(client, h)
assert client.post("/micropub", json={"action": "undelete", "url": url}, headers=h).status_code == 404
def test_delete_scope(self, app, client):
h = auth(app, "create")
url = create(client, h)
assert client.post("/micropub", data={"action": "delete", "url": url}, headers=h).status_code == 403
class TestQueries:
def test_source_properties_filter(self, client, h):
url = create(client, h, name=["T"], category=["x"])
data = source(client, h, url, "name", "category")
assert data == {"properties": {"name": ["T"], "category": ["x"]}}
def test_source_list_includes_drafts(self, client, h):
create(client, h, content=["first"])
create(client, h, content=["second"], **{"post-status": ["draft"]})
items = client.get("/micropub?q=source&limit=5", headers=h).get_json()["items"]
assert {i["properties"]["post-status"][0] for i in items} == {"published", "draft"}
def test_category(self, client, h):
create(client, h, category=["IndieWeb", "python"])
create(client, h, category=["IndieWeb"])
assert client.get("/micropub?q=category", headers=h).get_json()["categories"] == ["IndieWeb", "python"]
assert client.get("/micropub?q=category&filter=py", headers=h).get_json()["categories"] == ["python"]
def test_config_lists_queries(self, client, h):
config = client.get("/micropub?q=config", headers=h).get_json()
assert "category" in config["q"] and "media-endpoint" in config
def test_media_scope_alone_can_upload(app, client):
response = client.post("/micropub/media", data={"file": (io.BytesIO(jpeg()), "a.jpg")},
headers=auth(app, "media"), content_type="multipart/form-data")
assert response.status_code == 201