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>
1199 lines
42 KiB
Python
1199 lines
42 KiB
Python
"""
|
|
Notes management for StarPunk
|
|
|
|
This module provides CRUD operations for notes with atomic file+database
|
|
synchronization. All write operations use database transactions to ensure
|
|
files and database records stay in sync.
|
|
|
|
Functions:
|
|
create_note: Create new note with file and database entry
|
|
get_note: Retrieve note by slug or ID
|
|
list_notes: List notes with filtering and pagination
|
|
update_note: Update note content and/or metadata
|
|
delete_note: Delete note (soft or hard delete)
|
|
|
|
Exceptions:
|
|
NoteNotFoundError: Note does not exist
|
|
InvalidNoteDataError: Invalid content or parameters
|
|
NoteSyncError: File/database synchronization failure
|
|
NoteError: Base exception for all note operations
|
|
"""
|
|
|
|
# Standard library imports
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
from typing import Optional
|
|
|
|
# Third-party imports
|
|
from flask import current_app
|
|
|
|
# Local imports
|
|
from starpunk.database import get_db
|
|
from starpunk.models import Note
|
|
from starpunk.utils import (
|
|
generate_slug,
|
|
make_slug_unique,
|
|
generate_note_path,
|
|
ensure_note_directory,
|
|
write_note_file,
|
|
delete_note_file,
|
|
calculate_content_hash,
|
|
validate_note_path,
|
|
validate_slug,
|
|
post_url,
|
|
)
|
|
|
|
|
|
# Custom Exceptions
|
|
|
|
|
|
class NoteError(Exception):
|
|
"""Base exception for note operations"""
|
|
|
|
pass
|
|
|
|
|
|
class NoteNotFoundError(NoteError):
|
|
"""
|
|
Raised when a note cannot be found
|
|
|
|
This exception is raised when attempting to retrieve, update, or delete
|
|
a note that doesn't exist in the database.
|
|
|
|
Attributes:
|
|
identifier: The slug or ID used to search for the note
|
|
message: Human-readable error message
|
|
"""
|
|
|
|
def __init__(self, identifier: str | int, message: Optional[str] = None):
|
|
self.identifier = identifier
|
|
if message is None:
|
|
message = f"Note not found: {identifier}"
|
|
super().__init__(message)
|
|
|
|
|
|
class InvalidNoteDataError(NoteError, ValueError):
|
|
"""
|
|
Raised when note data is invalid
|
|
|
|
This exception is raised when attempting to create or update a note
|
|
with invalid data (empty content, invalid slug, etc.)
|
|
|
|
Attributes:
|
|
field: The field that failed validation
|
|
value: The invalid value
|
|
message: Human-readable error message
|
|
"""
|
|
|
|
def __init__(self, field: str, value: any, message: Optional[str] = None):
|
|
self.field = field
|
|
self.value = value
|
|
if message is None:
|
|
message = f"Invalid {field}: {value}"
|
|
super().__init__(message)
|
|
|
|
|
|
class NoteSyncError(NoteError):
|
|
"""
|
|
Raised when file/database synchronization fails
|
|
|
|
This exception is raised when a file operation and database operation
|
|
cannot be kept in sync (e.g., file written but database insert failed).
|
|
|
|
Attributes:
|
|
operation: The operation that failed ('create', 'update', 'delete')
|
|
details: Additional details about the failure
|
|
message: Human-readable error message
|
|
"""
|
|
|
|
def __init__(self, operation: str, details: str, message: Optional[str] = None):
|
|
self.operation = operation
|
|
self.details = details
|
|
if message is None:
|
|
message = f"Sync error during {operation}: {details}"
|
|
super().__init__(message)
|
|
|
|
|
|
# Helper Functions
|
|
|
|
|
|
def _get_existing_slugs(db) -> set[str]:
|
|
"""
|
|
Query all existing slugs from database
|
|
|
|
Args:
|
|
db: Database connection
|
|
|
|
Returns:
|
|
Set of existing slug strings
|
|
"""
|
|
rows = db.execute("SELECT slug FROM notes").fetchall()
|
|
return {row["slug"] for row in rows}
|
|
|
|
|
|
# Core CRUD Functions
|
|
|
|
|
|
# update_note: leave a field as it is
|
|
UNCHANGED = object()
|
|
|
|
|
|
def create_note(
|
|
content: str,
|
|
published: bool = False,
|
|
created_at: Optional[datetime] = None,
|
|
custom_slug: Optional[str] = None,
|
|
tags: Optional[list[str]] = None,
|
|
in_reply_to: Optional[str] = None,
|
|
like_of: Optional[str] = None,
|
|
repost_of: Optional[str] = None,
|
|
has_media: bool = False,
|
|
bookmark_of: Optional[str] = None,
|
|
content_format: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
summary: Optional[str] = None,
|
|
) -> Note:
|
|
"""
|
|
Create a new note
|
|
|
|
Creates a new note by generating a unique slug, writing the markdown
|
|
content to a file, and inserting a database record. File and database
|
|
operations are atomic - if either fails, both are rolled back.
|
|
|
|
Args:
|
|
content: Markdown content for the note (must not be empty)
|
|
published: Whether the note should be published (default: False)
|
|
created_at: Creation timestamp (default: current UTC time)
|
|
custom_slug: Optional custom slug (from Micropub mp-slug property)
|
|
tags: Optional list of tag display names (v1.3.0)
|
|
in_reply_to: Optional URL being replied to (v1.6.0)
|
|
title: Optional title; a titled note is an article (v2.16.0, ADR-076)
|
|
summary: Optional author-written summary (v2.16.0)
|
|
|
|
Returns:
|
|
Note object with all metadata and content loaded
|
|
|
|
Raises:
|
|
InvalidNoteDataError: If content is empty or whitespace-only
|
|
NoteSyncError: If file write succeeds but database insert fails
|
|
OSError: If file cannot be written (permissions, disk full, etc.)
|
|
ValueError: If configuration is missing or invalid
|
|
|
|
Examples:
|
|
>>> # Create unpublished draft
|
|
>>> note = create_note("Content here.", title="My First Note", published=False)
|
|
>>> print(note.slug)
|
|
'my-first-note'
|
|
|
|
>>> # Create published note
|
|
>>> note = create_note(
|
|
... "Just published this!",
|
|
... published=True
|
|
... )
|
|
>>> print(note.published)
|
|
True
|
|
|
|
>>> # Create with specific timestamp
|
|
>>> from datetime import datetime
|
|
>>> note = create_note(
|
|
... "Backdated note",
|
|
... created_at=datetime(2024, 1, 1, 12, 0, 0)
|
|
... )
|
|
|
|
Transaction Safety:
|
|
1. Validates content (before any changes)
|
|
2. Generates unique slug (database query)
|
|
3. Writes file to disk
|
|
4. Begins database transaction
|
|
5. Inserts database record
|
|
6. If database fails: deletes file, raises NoteSyncError
|
|
7. If successful: commits transaction, returns Note
|
|
|
|
Notes:
|
|
- Slug is generated from first 5 words of content
|
|
- Random suffix added if slug already exists
|
|
- File path follows pattern: data/notes/YYYY/MM/slug.md
|
|
- Content hash calculated and stored for integrity checking
|
|
- created_at and updated_at set to same value initially
|
|
"""
|
|
# 1. VALIDATION (before any changes)
|
|
# Likes and reposts may have no comment (v2.5.0), photo posts no text (v2.6.5)
|
|
# Bookmarks too (v2.9.0)
|
|
if sum(bool(u) for u in (like_of, repost_of, bookmark_of)) > 1:
|
|
raise InvalidNoteDataError(
|
|
"like_of", like_of, "A note can only be one of a like, repost or bookmark"
|
|
)
|
|
content = content or ""
|
|
title = (title or "").strip() or None
|
|
summary = (summary or "").strip() or None
|
|
if not content.strip() and not (like_of or repost_of or bookmark_of or has_media or title):
|
|
raise InvalidNoteDataError(
|
|
"content", content, "Content cannot be empty or whitespace-only"
|
|
)
|
|
|
|
# 2. SETUP
|
|
if created_at is None:
|
|
created_at = datetime.now(timezone.utc).replace(tzinfo=None)
|
|
|
|
updated_at = created_at # Same as created_at for new notes
|
|
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
|
|
# 3. GENERATE OR VALIDATE SLUG
|
|
# Query all existing slugs from database
|
|
db = get_db(current_app)
|
|
existing_slugs = _get_existing_slugs(db)
|
|
|
|
if custom_slug:
|
|
# Use custom slug (from Micropub mp-slug property)
|
|
from starpunk.slug_utils import validate_and_sanitize_custom_slug
|
|
success, slug, error = validate_and_sanitize_custom_slug(custom_slug, existing_slugs)
|
|
if not success:
|
|
raise InvalidNoteDataError("slug", custom_slug, error)
|
|
else:
|
|
# Articles take their slug from the title (v2.17.0); other notes, or a
|
|
# title with nothing usable in it, get a timestamp slug (ADR-062)
|
|
from starpunk.slug_utils import generate_timestamp_slug, generate_title_slug
|
|
slug = (generate_title_slug(title, existing_slugs) if title else None) \
|
|
or generate_timestamp_slug(created_at, existing_slugs)
|
|
|
|
# 4. GENERATE FILE PATH
|
|
note_path = generate_note_path(slug, created_at, data_dir)
|
|
|
|
# Security: Validate path stays within data directory
|
|
if not validate_note_path(note_path, data_dir):
|
|
raise NoteSyncError(
|
|
"create",
|
|
f"Generated path outside data directory: {note_path}",
|
|
"Path validation failed",
|
|
)
|
|
|
|
# 5. CALCULATE CONTENT HASH
|
|
content_hash = calculate_content_hash(content)
|
|
|
|
# 6. WRITE FILE (before database to fail fast on disk issues)
|
|
try:
|
|
ensure_note_directory(note_path)
|
|
write_note_file(note_path, content)
|
|
except OSError as e:
|
|
# File write failed, nothing to clean up
|
|
raise NoteSyncError(
|
|
"create",
|
|
f"Failed to write file: {e}",
|
|
f"Could not write note file: {note_path}",
|
|
)
|
|
|
|
# 7. INSERT DATABASE RECORD (transaction starts here)
|
|
file_path_rel = str(note_path.relative_to(data_dir))
|
|
|
|
try:
|
|
db.execute(
|
|
"""
|
|
INSERT INTO notes (slug, file_path, published, created_at, updated_at, content_hash,
|
|
in_reply_to, like_of, repost_of, bookmark_of, content_format,
|
|
title, summary)
|
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
""",
|
|
(slug, file_path_rel, published, created_at, updated_at, content_hash,
|
|
in_reply_to, like_of, repost_of, bookmark_of, content_format, title, summary),
|
|
)
|
|
db.commit()
|
|
except Exception as e:
|
|
# Database insert failed, delete the file we created
|
|
try:
|
|
note_path.unlink()
|
|
except OSError:
|
|
# Log warning but don't fail - file cleanup is best effort
|
|
current_app.logger.warning(
|
|
f"Failed to clean up file after DB error: {note_path}"
|
|
)
|
|
|
|
# Raise sync error
|
|
raise NoteSyncError(
|
|
"create", f"Database insert failed: {e}", f"Failed to create note: {slug}"
|
|
)
|
|
|
|
# 8. RETRIEVE AND RETURN NOTE OBJECT
|
|
# Get the auto-generated ID
|
|
note_id = db.execute("SELECT last_insert_rowid()").fetchone()[0]
|
|
|
|
# Fetch the complete record
|
|
row = db.execute("SELECT * FROM notes WHERE id = ?", (note_id,)).fetchone()
|
|
|
|
# Create Note object
|
|
note = Note.from_row(row, data_dir)
|
|
|
|
# 9. ADD TAGS (v1.3.0)
|
|
if tags:
|
|
try:
|
|
from starpunk.tags import add_tags_to_note
|
|
add_tags_to_note(note_id, tags)
|
|
except Exception as e:
|
|
# Tag addition failure should not prevent note creation
|
|
current_app.logger.warning(f"Failed to add tags to note {slug}: {e}")
|
|
|
|
# 10. UPDATE FTS INDEX (if available)
|
|
try:
|
|
from starpunk.search import update_fts_index, has_fts_table
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
if has_fts_table(db_path):
|
|
update_fts_index(db, note_id, slug, content, title)
|
|
db.commit()
|
|
except Exception as e:
|
|
# FTS update failure should not prevent note creation
|
|
current_app.logger.warning(f"Failed to update FTS index for note {slug}: {e}")
|
|
|
|
# 11. QUEUE WEBMENTIONS (v1.6.0 Phase 3)
|
|
# Only queue if note is published (not draft)
|
|
if published:
|
|
try:
|
|
from starpunk.webmention_sender import queue_webmentions_for_note
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
site_url = current_app.config["SITE_URL"]
|
|
from starpunk.utils import absolute_url_for
|
|
note_url = post_url(slug, title)
|
|
|
|
# Get rendered HTML from note
|
|
html_content = note.html
|
|
|
|
# Queue webmentions (best-effort, failures logged but don't fail note creation)
|
|
# The reply/like/repost target is notified first (v2.5.0)
|
|
queue_webmentions_for_note(
|
|
db_path=db_path,
|
|
note_id=note_id,
|
|
note_url=note_url,
|
|
content_html=html_content,
|
|
in_reply_to=in_reply_to or like_of or repost_of or bookmark_of
|
|
)
|
|
except Exception as e:
|
|
# Webmention queueing failure should not prevent note creation
|
|
current_app.logger.warning(f"Failed to queue webmentions for note {slug}: {e}")
|
|
|
|
# 12. FETCH REPLY CONTEXT (v1.6.0 Phase 3)
|
|
# Fetch context for the post being replied to, liked or reposted
|
|
context_url = in_reply_to or like_of or repost_of or bookmark_of
|
|
if context_url:
|
|
try:
|
|
from starpunk.reply_context import fetch_reply_context
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
site_url = current_app.config["SITE_URL"]
|
|
|
|
# Fetch context (best-effort, failures logged but don't fail note creation)
|
|
fetch_reply_context(db_path, context_url, site_url)
|
|
except Exception as e:
|
|
# Reply context fetch failure should not prevent note creation
|
|
current_app.logger.warning(f"Failed to fetch reply context for {in_reply_to}: {e}")
|
|
|
|
# A note with photos is announced when they're attached
|
|
# (attach_media_to_note), so subscribers never get it without them
|
|
if not has_media:
|
|
_websub_changed(note)
|
|
return note
|
|
|
|
|
|
def _tag_names(note_id: int) -> list[str]:
|
|
"""A note's tag names, for WebSub tag topics (best effort)"""
|
|
try:
|
|
from starpunk.tags import get_note_tags
|
|
return [t["name"] for t in get_note_tags(note_id)]
|
|
except Exception:
|
|
return []
|
|
|
|
|
|
def _websub_changed(note, was_public: bool = False, old_tags=()) -> None:
|
|
"""Clear cached feeds and queue WebSub deliveries (v2.10.0, best effort)"""
|
|
try:
|
|
from starpunk import websub
|
|
websub.note_changed(note, was_public=was_public, old_tags=old_tags)
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Failed to queue WebSub update for note {note.slug}: {e}")
|
|
|
|
|
|
def get_note(
|
|
slug: Optional[str] = None, id: Optional[int] = None, load_content: bool = True
|
|
) -> Optional[Note]:
|
|
"""
|
|
Get a note by slug or ID
|
|
|
|
Retrieves note metadata from database and optionally loads content
|
|
from file. Exactly one of slug or id must be provided.
|
|
|
|
Args:
|
|
slug: Note slug (unique identifier in URLs)
|
|
id: Note database ID (primary key)
|
|
load_content: Whether to load file content (default: True)
|
|
|
|
Returns:
|
|
Note object with metadata and optionally content, or None if not found
|
|
|
|
Raises:
|
|
ValueError: If both slug and id provided, or neither provided
|
|
OSError: If file cannot be read (when load_content=True)
|
|
FileNotFoundError: If note file doesn't exist (when load_content=True)
|
|
|
|
Examples:
|
|
>>> # Get by slug
|
|
>>> note = get_note(slug="my-first-note")
|
|
>>> if note:
|
|
... print(note.content) # Content loaded
|
|
... else:
|
|
... print("Note not found")
|
|
|
|
>>> # Get by ID
|
|
>>> note = get_note(id=42)
|
|
|
|
>>> # Get metadata only (no file I/O)
|
|
>>> note = get_note(slug="my-note", load_content=False)
|
|
>>> print(note.slug) # Works
|
|
>>> print(note.content) # Will trigger file load on access
|
|
|
|
>>> # Check if note exists
|
|
>>> if get_note(slug="maybe-exists"):
|
|
... print("Note exists")
|
|
|
|
Performance:
|
|
- Metadata retrieval: Single database query, <1ms
|
|
- Content loading: File I/O, typically <5ms for normal notes
|
|
- Use load_content=False for list operations to avoid file I/O
|
|
|
|
Notes:
|
|
- Returns None if note not found (does not raise exception)
|
|
- Content hash verification is optional (logs warning if mismatch)
|
|
- Note.content property will lazy-load if load_content=False
|
|
- Soft-deleted notes (deleted_at != NULL) are excluded
|
|
"""
|
|
# 1. VALIDATE PARAMETERS
|
|
if slug is None and id is None:
|
|
raise ValueError("Must provide either slug or id")
|
|
|
|
if slug is not None and id is not None:
|
|
raise ValueError("Cannot provide both slug and id")
|
|
|
|
# 2. QUERY DATABASE
|
|
db = get_db(current_app)
|
|
|
|
if slug is not None:
|
|
# Query by slug
|
|
row = db.execute(
|
|
"SELECT * FROM notes WHERE slug = ? AND deleted_at IS NULL", (slug,)
|
|
).fetchone()
|
|
else:
|
|
# Query by ID
|
|
row = db.execute(
|
|
"SELECT * FROM notes WHERE id = ? AND deleted_at IS NULL", (id,)
|
|
).fetchone()
|
|
|
|
# 3. CHECK IF FOUND
|
|
if row is None:
|
|
return None
|
|
|
|
# 4. CREATE NOTE OBJECT
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
note = Note.from_row(row, data_dir)
|
|
|
|
# 5. OPTIONALLY LOAD CONTENT
|
|
if load_content:
|
|
# Access content property to trigger load
|
|
try:
|
|
_ = note.content
|
|
except (FileNotFoundError, OSError) as e:
|
|
current_app.logger.warning(
|
|
f"Failed to load content for note {note.slug}: {e}"
|
|
)
|
|
|
|
# 6. OPTIONALLY VERIFY INTEGRITY
|
|
# This is a passive check - log warning but don't fail
|
|
if load_content and note.content_hash:
|
|
try:
|
|
if not note.verify_integrity():
|
|
current_app.logger.warning(
|
|
f"Content hash mismatch for note {note.slug}. "
|
|
f"File may have been modified externally."
|
|
)
|
|
except Exception as e:
|
|
current_app.logger.warning(
|
|
f"Failed to verify integrity for note {note.slug}: {e}"
|
|
)
|
|
|
|
# 7. RETURN NOTE
|
|
return note
|
|
|
|
|
|
def list_notes(
|
|
published_only: bool = False,
|
|
limit: int = 50,
|
|
offset: int = 0,
|
|
order_by: str = "created_at",
|
|
order_dir: str = "DESC",
|
|
likes: Optional[bool] = None,
|
|
) -> list[Note]:
|
|
"""
|
|
List notes with filtering and pagination
|
|
|
|
Retrieves notes from database with optional filtering by published
|
|
status, sorting, and pagination. Does not load file content for
|
|
performance - use note.content to lazy-load when needed.
|
|
|
|
Args:
|
|
published_only: If True, only return published notes (default: False)
|
|
limit: Maximum number of notes to return (default: 50, max: 1000)
|
|
offset: Number of notes to skip for pagination (default: 0)
|
|
order_by: Field to sort by (default: 'created_at')
|
|
order_dir: Sort direction, 'ASC' or 'DESC' (default: 'DESC')
|
|
|
|
Returns:
|
|
List of Note objects with metadata only (content not loaded)
|
|
|
|
Raises:
|
|
ValueError: If order_by is not a valid column name (SQL injection prevention)
|
|
ValueError: If order_dir is not 'ASC' or 'DESC'
|
|
ValueError: If limit exceeds maximum allowed value
|
|
|
|
Examples:
|
|
>>> # List recent published notes
|
|
>>> notes = list_notes(published_only=True, limit=10)
|
|
>>> for note in notes:
|
|
... print(note.slug, note.created_at)
|
|
|
|
>>> # List all notes, oldest first
|
|
>>> notes = list_notes(order_dir='ASC')
|
|
|
|
>>> # Pagination (page 2, 20 per page)
|
|
>>> notes = list_notes(limit=20, offset=20)
|
|
|
|
>>> # List by update time
|
|
>>> notes = list_notes(order_by='updated_at')
|
|
|
|
Performance:
|
|
- Single database query
|
|
- No file I/O (content not loaded)
|
|
- Efficient for large result sets with pagination
|
|
- Typical query time: <10ms for 1000s of notes
|
|
|
|
Pagination Example:
|
|
>>> page = 1
|
|
>>> per_page = 20
|
|
>>> notes = list_notes(
|
|
... published_only=True,
|
|
... limit=per_page,
|
|
... offset=(page - 1) * per_page
|
|
... )
|
|
|
|
Notes:
|
|
- Excludes soft-deleted notes (deleted_at IS NULL)
|
|
- Content is lazy-loaded when accessed via note.content
|
|
- order_by values are validated to prevent SQL injection
|
|
- Default sort is newest first (created_at DESC)
|
|
"""
|
|
# 1. VALIDATE PARAMETERS
|
|
# Prevent SQL injection - validate order_by column
|
|
ALLOWED_ORDER_FIELDS = ["id", "slug", "created_at", "updated_at", "published"]
|
|
if order_by not in ALLOWED_ORDER_FIELDS:
|
|
raise ValueError(
|
|
f"Invalid order_by field: {order_by}. "
|
|
f"Allowed: {', '.join(ALLOWED_ORDER_FIELDS)}"
|
|
)
|
|
|
|
# Validate order direction
|
|
order_dir = order_dir.upper()
|
|
if order_dir not in ["ASC", "DESC"]:
|
|
raise ValueError(f"Invalid order_dir: {order_dir}. Must be 'ASC' or 'DESC'")
|
|
|
|
# Validate limit (prevent excessive queries)
|
|
MAX_LIMIT = 1000
|
|
if limit > MAX_LIMIT:
|
|
raise ValueError(f"Limit {limit} exceeds maximum {MAX_LIMIT}")
|
|
|
|
if limit < 1:
|
|
raise ValueError("Limit must be >= 1")
|
|
|
|
if offset < 0:
|
|
raise ValueError("Offset must be >= 0")
|
|
|
|
# 2. BUILD QUERY
|
|
# Start with base query
|
|
query = "SELECT * FROM notes WHERE deleted_at IS NULL"
|
|
|
|
# Add filters
|
|
params = []
|
|
if published_only:
|
|
query += " AND published = 1"
|
|
# likes: None = all notes, False = leave likes out, True = only likes (v2.5.0)
|
|
if likes is True:
|
|
query += " AND like_of IS NOT NULL"
|
|
elif likes is False:
|
|
query += " AND like_of IS NULL"
|
|
|
|
# Add ordering (safe because order_by validated above)
|
|
query += f" ORDER BY {order_by} {order_dir}"
|
|
|
|
# Add pagination
|
|
query += " LIMIT ? OFFSET ?"
|
|
params.extend([limit, offset])
|
|
|
|
# 3. EXECUTE QUERY
|
|
db = get_db(current_app)
|
|
rows = db.execute(query, params).fetchall()
|
|
|
|
# 4. CREATE NOTE OBJECTS (without loading content)
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
notes = [Note.from_row(row, data_dir) for row in rows]
|
|
|
|
return notes
|
|
|
|
|
|
def update_note(
|
|
slug: Optional[str] = None,
|
|
id: Optional[int] = None,
|
|
content: Optional[str] = None,
|
|
published: Optional[bool] = None,
|
|
tags: Optional[list[str]] = None,
|
|
in_reply_to: Optional[str] = None,
|
|
has_media: bool = False,
|
|
content_format=UNCHANGED,
|
|
title=UNCHANGED,
|
|
summary=UNCHANGED,
|
|
) -> Note:
|
|
"""
|
|
Update a note's content and/or published status
|
|
|
|
content_format (v2.9.0): 'html' or None (Markdown); left alone unless given
|
|
title, summary (v2.16.0): new value, None or "" to remove; left alone unless given
|
|
|
|
Updates note content and/or metadata, maintaining atomic synchronization
|
|
between file and database. At least one of content or published must
|
|
be provided.
|
|
|
|
Args:
|
|
slug: Note slug to update (mutually exclusive with id)
|
|
id: Note ID to update (mutually exclusive with slug)
|
|
content: New markdown content (None = no change)
|
|
published: New published status (None = no change)
|
|
tags: New tags list (None = no change, [] = remove all tags) (v1.3.0)
|
|
in_reply_to: New in-reply-to URL (None = no change) (v1.6.0)
|
|
|
|
Returns:
|
|
Updated Note object with new content and metadata
|
|
|
|
Raises:
|
|
ValueError: If both slug and id provided, or neither provided
|
|
ValueError: If neither content nor published provided (no changes)
|
|
NoteNotFoundError: If note doesn't exist
|
|
InvalidNoteDataError: If content is empty/whitespace (when provided)
|
|
NoteSyncError: If file update succeeds but database update fails
|
|
OSError: If file cannot be written
|
|
|
|
Examples:
|
|
>>> # Update content only
|
|
>>> note = update_note(
|
|
... slug="my-note",
|
|
... content="# Updated content\\n\\nNew text here."
|
|
... )
|
|
|
|
>>> # Publish a draft
|
|
>>> note = update_note(slug="draft-note", published=True)
|
|
|
|
>>> # Update both content and status
|
|
>>> note = update_note(
|
|
... id=42,
|
|
... content="New content",
|
|
... published=True
|
|
... )
|
|
|
|
>>> # Unpublish a note
|
|
>>> note = update_note(slug="old-post", published=False)
|
|
|
|
Transaction Safety:
|
|
1. Validates parameters
|
|
2. Retrieves existing note from database
|
|
3. If content changed: writes new file (old file preserved)
|
|
4. Begins database transaction
|
|
5. Updates database record
|
|
6. If database fails: log error, raise NoteSyncError
|
|
7. If successful: commits transaction, returns updated Note
|
|
|
|
Notes:
|
|
- Slug cannot be changed (use delete + create for that)
|
|
- updated_at is automatically set to current time
|
|
- Content hash recalculated if content changes
|
|
- File is overwritten atomically (temp file + rename)
|
|
- Old file content is lost (no backup by default)
|
|
"""
|
|
# 1. VALIDATE PARAMETERS
|
|
if slug is None and id is None:
|
|
raise ValueError("Must provide either slug or id")
|
|
|
|
if slug is not None and id is not None:
|
|
raise ValueError("Cannot provide both slug and id")
|
|
|
|
if (content is None and published is None and tags is None and in_reply_to is None
|
|
and title is UNCHANGED and summary is UNCHANGED):
|
|
raise ValueError(
|
|
"Must provide at least one of content, published, tags, in_reply_to, title or summary to update"
|
|
)
|
|
if title is not UNCHANGED:
|
|
title = (title or "").strip() or None
|
|
if summary is not UNCHANGED:
|
|
summary = (summary or "").strip() or None
|
|
|
|
# Validate content if provided (checked against the note below for
|
|
# likes/reposts, whose comment may be empty)
|
|
empty_content = content is not None and not content.strip()
|
|
|
|
# 2. GET EXISTING NOTE
|
|
# Phase 6: Load content to get old HTML for webmention URL diffing
|
|
existing_note = get_note(slug=slug, id=id, load_content=True)
|
|
|
|
if existing_note is None:
|
|
identifier = slug if slug is not None else id
|
|
raise NoteNotFoundError(identifier)
|
|
old_tag_names = _tag_names(existing_note.id) # for WebSub tag topics (v2.10.0)
|
|
|
|
new_title = existing_note.title if title is UNCHANGED else title
|
|
if empty_content and not (existing_note.reacts_to or has_media or new_title):
|
|
raise InvalidNoteDataError(
|
|
"content", content, "Content cannot be empty or whitespace-only"
|
|
)
|
|
|
|
# 3. SETUP
|
|
updated_at = datetime.now(timezone.utc).replace(tzinfo=None)
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
note_path = data_dir / existing_note.file_path
|
|
|
|
# Validate path (security check)
|
|
if not validate_note_path(note_path, data_dir):
|
|
raise NoteSyncError(
|
|
"update",
|
|
f"Note file path outside data directory: {note_path}",
|
|
"Path validation failed",
|
|
)
|
|
|
|
# 4. CAPTURE OLD HTML (Phase 6: for webmention URL diffing)
|
|
# Capture old HTML before writing new content
|
|
# Only if note is/was published (unpublished notes don't send webmentions)
|
|
old_html = None
|
|
if existing_note.published:
|
|
try:
|
|
old_html = existing_note.html
|
|
except Exception as e:
|
|
# HTML rendering failed - continue with update, skip old_html
|
|
current_app.logger.warning(f"Failed to render old HTML for note {existing_note.slug}: {e}")
|
|
|
|
# 5. UPDATE FILE (if content changed)
|
|
new_content_hash = existing_note.content_hash
|
|
if content is not None:
|
|
try:
|
|
# Write new content atomically
|
|
write_note_file(note_path, content)
|
|
|
|
# Calculate new hash
|
|
new_content_hash = calculate_content_hash(content)
|
|
except OSError as e:
|
|
raise NoteSyncError(
|
|
"update",
|
|
f"Failed to write file: {e}",
|
|
f"Could not update note file: {note_path}",
|
|
)
|
|
|
|
# 6. UPDATE DATABASE
|
|
db = get_db(current_app)
|
|
|
|
# Build update query based on what changed
|
|
update_fields = ["updated_at = ?"]
|
|
params = [updated_at]
|
|
|
|
if content is not None:
|
|
update_fields.append("content_hash = ?")
|
|
params.append(new_content_hash)
|
|
|
|
if published is not None:
|
|
update_fields.append("published = ?")
|
|
params.append(published)
|
|
|
|
if in_reply_to is not None:
|
|
update_fields.append("in_reply_to = ?")
|
|
params.append(in_reply_to)
|
|
|
|
if content_format is not UNCHANGED:
|
|
update_fields.append("content_format = ?")
|
|
params.append(content_format)
|
|
|
|
if title is not UNCHANGED:
|
|
update_fields.append("title = ?")
|
|
params.append(title)
|
|
|
|
if summary is not UNCHANGED:
|
|
update_fields.append("summary = ?")
|
|
params.append(summary)
|
|
|
|
# Add WHERE clause parameter
|
|
if slug is not None:
|
|
where_clause = "slug = ?"
|
|
params.append(slug)
|
|
else:
|
|
where_clause = "id = ?"
|
|
params.append(id)
|
|
|
|
query = f"UPDATE notes SET {', '.join(update_fields)} WHERE {where_clause}"
|
|
|
|
try:
|
|
db.execute(query, params)
|
|
db.commit()
|
|
except Exception as e:
|
|
# Database update failed
|
|
# File has been updated, but we can't roll that back easily
|
|
# Log error and raise
|
|
current_app.logger.error(
|
|
f"Database update failed for note {existing_note.slug}: {e}"
|
|
)
|
|
raise NoteSyncError(
|
|
"update",
|
|
f"Database update failed: {e}",
|
|
f"Failed to update note: {existing_note.slug}",
|
|
)
|
|
|
|
# 6. UPDATE TAGS (v1.3.0)
|
|
if tags is not None:
|
|
try:
|
|
from starpunk.tags import add_tags_to_note
|
|
add_tags_to_note(existing_note.id, tags)
|
|
except Exception as e:
|
|
# Tag update failure should not prevent note update
|
|
current_app.logger.warning(f"Failed to update tags for note {existing_note.slug}: {e}")
|
|
|
|
# 7. UPDATE FTS INDEX (if available and content or title changed)
|
|
if content is not None or title is not UNCHANGED:
|
|
try:
|
|
from starpunk.search import update_fts_index, has_fts_table
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
if has_fts_table(db_path):
|
|
update_fts_index(db, existing_note.id, existing_note.slug,
|
|
existing_note.content if content is None else content, new_title)
|
|
db.commit()
|
|
except Exception as e:
|
|
# FTS update failure should not prevent note update
|
|
current_app.logger.warning(f"Failed to update FTS index for note {existing_note.slug}: {e}")
|
|
|
|
# 8. QUEUE WEBMENTIONS (v1.6.0 Phase 6)
|
|
# Queue webmentions if:
|
|
# - Note is being unpublished (notify removed URLs)
|
|
# - Note is being published (content changed OR publish status changed)
|
|
# - Note was published and content/in_reply_to changed
|
|
updated_note = get_note(slug=existing_note.slug, load_content=True)
|
|
|
|
# Detect unpublishing (published -> unpublished)
|
|
is_unpublishing = existing_note.published and published is False
|
|
|
|
# Check if content actually changed (Phase 6 optimization)
|
|
content_changed = (new_content_hash != existing_note.content_hash)
|
|
publish_status_changed = (published is not None and published != existing_note.published)
|
|
|
|
# Determine if we should queue webmentions
|
|
should_queue = False
|
|
if is_unpublishing:
|
|
# Unpublishing - queue for ALL previously-linked URLs
|
|
should_queue = True
|
|
elif published is not None and published:
|
|
# Being published now - queue if content changed OR just being published
|
|
should_queue = content_changed or publish_status_changed
|
|
elif existing_note.published and (content_changed or in_reply_to is not None):
|
|
# Was already published and content/reply-to changed
|
|
should_queue = True
|
|
|
|
if should_queue:
|
|
try:
|
|
from starpunk.webmention_sender import queue_webmentions_for_note
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
site_url = current_app.config["SITE_URL"]
|
|
from starpunk.utils import absolute_url_for
|
|
note_url = updated_note.url
|
|
|
|
# Get rendered HTML from updated note (if published)
|
|
html_content = updated_note.html if updated_note.published else None
|
|
|
|
# Determine in_reply_to (use new value if provided, otherwise existing)
|
|
reply_to = (in_reply_to if in_reply_to is not None else updated_note.in_reply_to) or updated_note.reacts_to
|
|
|
|
# Queue webmentions (best-effort)
|
|
# Pass old_html for URL diffing (Phase 6)
|
|
queue_webmentions_for_note(
|
|
db_path=db_path,
|
|
note_id=updated_note.id,
|
|
note_url=note_url,
|
|
content_html=html_content,
|
|
in_reply_to=reply_to,
|
|
old_content_html=old_html # Phase 6: for URL diffing
|
|
)
|
|
except Exception as e:
|
|
# Webmention queueing failure should not prevent note update
|
|
current_app.logger.warning(f"Failed to queue webmentions for note {updated_note.slug}: {e}")
|
|
|
|
# 9. FETCH REPLY CONTEXT (v1.6.0 Phase 3)
|
|
# Fetch context if in_reply_to changed and is set ("" clears it)
|
|
if in_reply_to:
|
|
try:
|
|
from starpunk.reply_context import fetch_reply_context
|
|
db_path = Path(current_app.config["DATABASE_PATH"])
|
|
site_url = current_app.config["SITE_URL"]
|
|
|
|
# Fetch context (best-effort)
|
|
fetch_reply_context(db_path, in_reply_to, site_url)
|
|
except Exception as e:
|
|
# Reply context fetch failure should not prevent note update
|
|
current_app.logger.warning(f"Failed to fetch reply context for {in_reply_to}: {e}")
|
|
|
|
# Crossposts follow the note (v2.1.0, best-effort)
|
|
try:
|
|
from starpunk.syndication import note_changed
|
|
note_changed(updated_note.id)
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Failed to queue syndication update: {e}")
|
|
|
|
_websub_changed(updated_note, was_public=existing_note.published, old_tags=old_tag_names)
|
|
|
|
# 10. RETURN UPDATED NOTE
|
|
return updated_note
|
|
|
|
|
|
def delete_note(
|
|
slug: Optional[str] = None, id: Optional[int] = None, soft: bool = True
|
|
) -> None:
|
|
"""
|
|
Delete a note (soft or hard delete)
|
|
|
|
Deletes a note either by marking it as deleted (soft delete) or by
|
|
permanently removing the file and database record (hard delete).
|
|
|
|
Args:
|
|
slug: Note slug to delete (mutually exclusive with id)
|
|
id: Note ID to delete (mutually exclusive with id)
|
|
soft: If True, soft delete (mark deleted_at); if False, hard delete (default: True)
|
|
|
|
Returns:
|
|
None
|
|
|
|
Raises:
|
|
ValueError: If both slug and id provided, or neither provided
|
|
NoteSyncError: If file deletion succeeds but database update fails
|
|
OSError: If file cannot be deleted
|
|
|
|
Examples:
|
|
>>> # Soft delete (default)
|
|
>>> delete_note(slug="old-note")
|
|
>>> # Note marked as deleted, file remains
|
|
|
|
>>> # Hard delete
|
|
>>> delete_note(slug="spam-note", soft=False)
|
|
>>> # Note and file permanently removed
|
|
|
|
>>> # Delete by ID
|
|
>>> delete_note(id=42, soft=False)
|
|
|
|
Soft Delete:
|
|
- Sets deleted_at timestamp in database
|
|
- File remains on disk (optionally moved to .trash/)
|
|
- Note excluded from normal queries (deleted_at IS NULL)
|
|
- Can be undeleted by clearing deleted_at (future feature)
|
|
|
|
Hard Delete:
|
|
- Removes database record permanently
|
|
- Deletes file from disk
|
|
- Cannot be recovered
|
|
- Use for spam, test data, or confirmed deletions
|
|
|
|
Transaction Safety:
|
|
Soft delete:
|
|
1. Updates database (sets deleted_at)
|
|
2. Optionally moves file to .trash/
|
|
3. If move fails: log warning but succeed (database is source of truth)
|
|
|
|
Hard delete:
|
|
1. Deletes database record
|
|
2. Deletes file from disk
|
|
3. If file delete fails: log warning but succeed (record already gone)
|
|
|
|
Notes:
|
|
- Soft delete is default and recommended
|
|
- Hard delete is permanent and cannot be undone
|
|
- Missing files during hard delete are not errors (idempotent)
|
|
- Deleting already-deleted note returns successfully (idempotent)
|
|
"""
|
|
# 1. VALIDATE PARAMETERS
|
|
if slug is None and id is None:
|
|
raise ValueError("Must provide either slug or id")
|
|
|
|
if slug is not None and id is not None:
|
|
raise ValueError("Cannot provide both slug and id")
|
|
|
|
# 2. GET EXISTING NOTE
|
|
# For soft delete, exclude already soft-deleted notes
|
|
# For hard delete, get note even if soft-deleted
|
|
if soft:
|
|
existing_note = get_note(slug=slug, id=id, load_content=False)
|
|
else:
|
|
# Hard delete: query including soft-deleted notes
|
|
db = get_db(current_app)
|
|
if slug is not None:
|
|
row = db.execute("SELECT * FROM notes WHERE slug = ?", (slug,)).fetchone()
|
|
else:
|
|
row = db.execute("SELECT * FROM notes WHERE id = ?", (id,)).fetchone()
|
|
|
|
if row is None:
|
|
existing_note = None
|
|
else:
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
existing_note = Note.from_row(row, data_dir)
|
|
|
|
# 3. CHECK IF NOTE EXISTS
|
|
if existing_note is None:
|
|
# Note not found - could already be deleted
|
|
# For idempotency, don't raise error - just return
|
|
return
|
|
|
|
# What feeds showed before, for WebSub (v2.10.0)
|
|
was_public = bool(existing_note.published) and not getattr(existing_note, "deleted_at", None)
|
|
deleted_tags = _tag_names(existing_note.id)
|
|
|
|
# 4. SETUP
|
|
data_dir = Path(current_app.config["DATA_PATH"])
|
|
note_path = data_dir / existing_note.file_path
|
|
|
|
# Validate path (security check)
|
|
if not validate_note_path(note_path, data_dir):
|
|
raise NoteSyncError(
|
|
"delete",
|
|
f"Note file path outside data directory: {note_path}",
|
|
"Path validation failed",
|
|
)
|
|
|
|
# Re-send webmentions so receivers learn the post is gone (spec 3.1.5).
|
|
# A hard delete would cascade the queue rows away, so detach them first.
|
|
if existing_note.published:
|
|
try:
|
|
from starpunk.webmention_sender import requeue_previous_webmentions
|
|
requeue_previous_webmentions(
|
|
Path(current_app.config["DATABASE_PATH"]), existing_note.id, detach=not soft
|
|
)
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Failed to queue webmentions for deleted note: {e}")
|
|
|
|
# 5. PERFORM DELETION
|
|
db = get_db(current_app)
|
|
|
|
if soft:
|
|
# SOFT DELETE: Mark as deleted in database
|
|
deleted_at = datetime.now(timezone.utc).replace(tzinfo=None)
|
|
|
|
try:
|
|
db.execute(
|
|
"UPDATE notes SET deleted_at = ? WHERE id = ?",
|
|
(deleted_at, existing_note.id),
|
|
)
|
|
db.commit()
|
|
except Exception as e:
|
|
raise NoteSyncError(
|
|
"delete",
|
|
f"Database update failed: {e}",
|
|
f"Failed to soft delete note: {existing_note.slug}",
|
|
)
|
|
|
|
# Optionally move file to trash (best effort)
|
|
# This is optional and failure is not critical
|
|
try:
|
|
delete_note_file(note_path, soft=True, data_dir=data_dir)
|
|
except Exception as e:
|
|
current_app.logger.warning(
|
|
f"Failed to move file to trash for note {existing_note.slug}: {e}"
|
|
)
|
|
# Don't fail - database update succeeded
|
|
|
|
else:
|
|
# HARD DELETE: Remove from database and filesystem
|
|
try:
|
|
db.execute("DELETE FROM notes WHERE id = ?", (existing_note.id,))
|
|
db.commit()
|
|
except Exception as e:
|
|
raise NoteSyncError(
|
|
"delete",
|
|
f"Database delete failed: {e}",
|
|
f"Failed to delete note: {existing_note.slug}",
|
|
)
|
|
|
|
# Delete file (best effort)
|
|
try:
|
|
delete_note_file(note_path, soft=False)
|
|
except FileNotFoundError:
|
|
# File already gone - that's fine
|
|
current_app.logger.info(
|
|
f"File already deleted for note {existing_note.slug}"
|
|
)
|
|
except Exception as e:
|
|
current_app.logger.warning(
|
|
f"Failed to delete file for note {existing_note.slug}: {e}"
|
|
)
|
|
# Don't fail - database record already deleted
|
|
|
|
# Delete crossposts too (v2.1.0, best-effort)
|
|
try:
|
|
from starpunk.syndication import note_changed
|
|
note_changed(existing_note.id)
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Failed to queue syndication delete: {e}")
|
|
|
|
# Feeds and pages no longer show it (v2.10.0)
|
|
object.__setattr__(existing_note, "published", False)
|
|
_websub_changed(existing_note, was_public=was_public, old_tags=deleted_tags)
|
|
|
|
# 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 find_trashed_file
|
|
|
|
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():
|
|
source = find_trashed_file(data_dir, row["file_path"])
|
|
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}")
|
|
|
|
try:
|
|
from starpunk.webmention_sender import requeue_previous_webmentions
|
|
requeue_previous_webmentions(Path(current_app.config["DATABASE_PATH"]), row["id"])
|
|
except Exception as e:
|
|
current_app.logger.warning(f"Failed to queue webmentions after undelete: {e}")
|
|
|
|
restored = get_note(slug=slug)
|
|
_websub_changed(restored)
|
|
return restored
|