StarPunk/docs/projectplan/BACKLOG.md

StarPunk Backlog

Last Updated: 2025-12-17

Recently Completed

v1.4.2 - HEIC/MPO Support and Dimension Limit Increase (Complete)

• HEIC/HEIF format detection and conversion to JPEG
• MPO (Multi-Picture Object) format support for iPhone depth photos
• MAX_DIMENSION increased from 4096 to 12000 pixels
• Enhanced debug logging for failed uploads

v1.4.0/v1.4.1 - Media Variants (Complete)

• Image variant generation (thumb, small, medium, large)
• Micropub media endpoint
• Enhanced feed media support with Media RSS

v1.3.0 - Microformats2 Compliance and Tags (Complete)

• Tag/Category system with database schema
• p-category microformats2 markup
• h-feed required properties (name, author, url)
• Author h-card with photo and bio
• u-photo placement outside e-content
• mf2py validation test suite

Priority Levels

• Critical - Items that break existing functionality
• High - Important features or fixes
• Medium - Planned features
• Low - Nice-to-have, deferred indefinitely

---

Critical

No critical items

---

High

MPO Format Test Coverage (Scheduled: v1.5.0)

• Description: MPO conversion code exists but has no test coverage. MPO is advertised in the CHANGELOG but the handling is untested.
• Location: starpunk/media.py lines 163-173
• Source: Developer Review (M1)
• Approach: Add test_mpo_detection_and_conversion() to TestHEICSupport class in tests/test_media_upload.py. Create an MPO test image using Pillow's MPO support.

POSSE

• Native syndication to social networks
• Supported networks:
  • First iteration:
    • Mastodon (and compatible services)
    • Bluesky
  • Second iteration
    • TBD
• Solution should include a configuration UI for setup

---

Medium

Debug File Storage Without Cleanup Mechanism (Scheduled: v1.5.0)

• Description: Failed uploads are saved to data/debug/ directory for analysis, but there is no mechanism to clean up these files. This could consume significant disk space, especially if under attack.
• Location: starpunk/media.py lines 133-137
• Source: Developer Review (M2), Architect Review (Issue 1.2.2)
• Approach:
  1. Add DEBUG_SAVE_FAILED_UPLOADS config option (default: false in production)
  2. Implement automatic cleanup (files older than 7 days)
  3. Add disk space check or size limit (e.g., 100MB max)

Filename Not Sanitized in Debug Path (Security) (Scheduled: v1.5.0)

• Description: The original filename is used directly in the debug file path without sanitization, which could cause path traversal or special character issues.
• Location: starpunk/media.py line 135
• Source: Architect Review (Issue 1.2.3)
• Approach: Sanitize filename before use: safe_filename = "".join(c for c in filename if c.isalnum() or c in "._-")[:50]

N+1 Query Pattern in Feed Generation (Scheduled: v1.5.0 - Partial)

• Description: In _get_cached_notes(), media and tags are loaded per-note in separate queries. For 50 notes, this is 100 additional database queries, degrading performance.
• Location: starpunk/routes/public.py lines 68-74
• Source: Architect Review (Issue 2.2.9)
• Approach: Implement batch loading function get_media_for_notes(note_ids: List[int]) using a single query with WHERE note_id IN (...).
• v1.5.0 Scope: Only _get_cached_notes() will be fixed in v1.5.0. Other N+1 patterns deferred (see Low Priority section).

N+1 Query Patterns - Deferred Locations

• Description: N+1 query patterns exist in multiple locations beyond _get_cached_notes(). These are lower priority due to lower traffic or single-note contexts.
• Deferred Locations:
  1. Admin Edit Page (starpunk/routes/admin.py line 186): Single note context, low impact
  2. Tag Archive Pages (starpunk/routes/public.py lines 243-248, 332): Lower traffic than main feed
  3. Individual Note View (starpunk/routes/public.py lines 282-289): Single note, negligible
  4. Note Model Property (starpunk/models.py lines 380-381): On-demand loading, acceptable
  5. Tag Module (starpunk/tags.py line 197): Internal helper, low volume
• Source: Architect Review, v1.5.0 scoping decision
• Approach: Future optimization if performance issues arise. Consider batch loading patterns established in v1.5.0.
• Priority: Deferred to post-v1.5.0

Transaction Not Atomic in Variant Generation (Scheduled: v1.5.0)

• Description: Files are written to disk before database commit. If the database commit fails, orphaned files remain on disk.
• Location: starpunk/media.py lines 404-440
• Source: Architect Review (Issue 2.2.6)
• Approach: Write variant files to a temporary location first, then move to final location after successful database commit.

Rate Limiting on Upload Endpoints

• Description: No rate limiting exists on media upload endpoints, making them vulnerable to abuse.
• Location: /admin/new (admin.py), /media (micropub.py)
• Source: Architect Review (Security Assessment)
• Approach: Implement Flask-Limiter or similar rate limiting middleware for upload routes.

Default Slug Change (Scheduled: v1.5.0)

• The default slug should be a date time stamp
• YYYYMMDDHHMMSS
• Edge case, if the slug would somehow be a duplicate append a "-x" e.g. -1

Tag Enhancements (v1.3.0 Follow-up)

• Tag pagination on archive pages (when note count exceeds threshold)
• Tag autocomplete in admin interface
• Tag-filtered feeds (e.g., /feed.rss?tag=python, /tags/python/feed.rss)
• Fix: Empty tag field in admin should remove all tags (currently may leave unchanged)

Tag-Filtered Feeds

• Filter feeds by tag (e.g., /feed.rss?tag=python)
• Dedicated tag feed URLs (e.g., /tags/python/feed.rss)
• Support all three formats (RSS, Atom, JSON Feed)
• Cache management for filtered feeds

Webmentions

• Receive endpoint
• Send on publish
• Display received mentions
• Moderation interface

Reply Contexts

• In-reply-to support
• Like/repost posts
• Bookmark posts

Media Uploads Enhancements

• File management interface
• Thumbnail generation
• CDN integration (optional)

Photo Posts

• Instagram-like photo notes
• Gallery views
• EXIF data preservation

Audio/Podcast Support

• Podcast RSS with iTunes namespace
• Audio duration extraction
• Episode metadata support
• Apple/Google podcast compatibility
• See: ADR-059

Video Support

• Video upload handling
• Poster image generation
• Video in Media RSS feeds
• HTML5 video embedding

---

Low

HEIC/MPO Conversion Quality Not Configurable

• Description: HEIC and MPO to JPEG conversion uses hardcoded quality=95. Users with different quality/size tradeoff preferences cannot adjust this.
• Location: starpunk/media.py line 157
• Source: Developer Review (M3)
• Approach: Add HEIC_CONVERSION_QUALITY config variable with 95 as default.

MAX_DIMENSION Not Configurable

• Description: MAX_DIMENSION = 12000 is a hardcoded constant. Cannot adjust limit without code change.
• Location: starpunk/media.py line 41
• Source: Developer Review (M4)
• Approach: Make configurable via config variable, keeping 12000 as default.

Animated WebP Not Detected

• Description: Animated GIF detection exists but animated WebP is not handled, potentially bypassing animated image size checks.
• Location: starpunk/media.py (validate_image function)
• Source: Architect Review (Issue 2.2.2)
• Approach: Add animated WebP detection similar to existing GIF handling.

Caption Not Escaped in RSS HTML

• Description: In RSS generation, caption is used directly in alt attribute without HTML escaping. Could break markup if caption contains " or other special characters.
• Location: starpunk/feeds/rss.py line 136
• Source: Architect Review (Issue 2.2.10)
• Approach: Use html.escape() for caption when generating HTML content.

Incomplete MPO Documentation

• Description: Code comment says "extract primary image" but doesn't explain the multi-frame nature of MPO files (contain multiple images for 3D or depth maps).
• Location: starpunk/media.py lines 163-165
• Source: Developer Review (M5)
• Approach: Enhance inline comment to document that MPO files contain multiple frames and only the primary frame is extracted.

Module Docstring Stale

• Description: Module docstring still states "4096x4096 max dimensions" but MAX_DIMENSION was updated to 12000 in v1.4.2.
• Location: starpunk/media.py lines 1-12
• Source: Architect Review (Issue 1.2.1)
• Approach: Update docstring to reflect current 12000px limit.

Flaky Migration Race Condition Tests

• Improve test_migration_race_condition.py::TestGraduatedLogging::test_debug_level_for_early_retries
• Test expects DEBUG retry messages but passes when migration succeeds without retries
• May need to mock or force retry conditions for reliable testing

Deferred Indefinitely

• Static Site Generation - Conflicts with dynamic Micropub
• Multi-language UI - Low priority for single-user system
• Advanced Analytics - Privacy concerns, use external tools
• Comments System - Use Webmentions instead
• WYSIWYG Editor - Markdown is sufficient
• Mobile App - Web interface is mobile-friendly