StarPunk/starpunk/routes/public.py

"""
Public routes for StarPunk

Handles public-facing pages including homepage and note permalinks.
No authentication required for these routes.
"""

import hashlib
from datetime import datetime, timedelta

from flask import Blueprint, abort, render_template, Response, current_app, jsonify

from starpunk.notes import list_notes, get_note
from starpunk.feed import generate_feed

# Create blueprint
bp = Blueprint("public", __name__)

# Simple in-memory cache for RSS feed
# Structure: {'xml': str, 'timestamp': datetime, 'etag': str}
_feed_cache = {"xml": None, "timestamp": None, "etag": None}


@bp.route("/")
def index():
    """
    Homepage displaying recent published notes

    Returns:
        Rendered homepage template with note list

    Template: templates/index.html
    Microformats: h-feed containing h-entry items
    """
    # Get recent published notes (limit 20)
    notes = list_notes(published_only=True, limit=20)

    return render_template("index.html", notes=notes)


@bp.route("/note/<slug>")
def note(slug: str):
    """
    Individual note permalink page

    Args:
        slug: URL-safe note identifier

    Returns:
        Rendered note template with full content

    Raises:
        404: If note not found or not published

    Template: templates/note.html
    Microformats: h-entry
    """
    # Get note by slug
    note_obj = get_note(slug=slug)

    # Return 404 if note doesn't exist or isn't published
    if not note_obj or not note_obj.published:
        abort(404)

    return render_template("note.html", note=note_obj)


@bp.route("/feed.xml")
def feed():
    """
    RSS 2.0 feed of published notes

    Generates standards-compliant RSS 2.0 feed with server-side caching
    and ETag support for conditional requests. Cache duration is
    configurable via FEED_CACHE_SECONDS (default: 300 seconds = 5 minutes).

    Returns:
        XML response with RSS feed

    Headers:
        Content-Type: application/rss+xml; charset=utf-8
        Cache-Control: public, max-age={FEED_CACHE_SECONDS}
        ETag: MD5 hash of feed content

    Caching Strategy:
        - Server-side: In-memory cache for configured duration
        - Client-side: Cache-Control header with max-age
        - Conditional: ETag support for efficient updates

    Examples:
        >>> # First request: generates and caches feed
        >>> response = client.get('/feed.xml')
        >>> response.status_code
        200
        >>> response.headers['Content-Type']
        'application/rss+xml; charset=utf-8'

        >>> # Subsequent requests within cache window: returns cached feed
        >>> response = client.get('/feed.xml')
        >>> response.headers['ETag']
        'abc123...'
    """
    # Get cache duration from config (in seconds)
    cache_seconds = current_app.config.get("FEED_CACHE_SECONDS", 300)
    cache_duration = timedelta(seconds=cache_seconds)
    now = datetime.utcnow()

    # Check if cache is valid
    if _feed_cache["xml"] and _feed_cache["timestamp"]:
        cache_age = now - _feed_cache["timestamp"]
        if cache_age < cache_duration:
            # Cache is still valid, return cached feed
            response = Response(
                _feed_cache["xml"], mimetype="application/rss+xml; charset=utf-8"
            )
            response.headers["Cache-Control"] = f"public, max-age={cache_seconds}"
            response.headers["ETag"] = _feed_cache["etag"]
            return response

    # Cache expired or empty, generate fresh feed
    # Get published notes (limit from config)
    max_items = current_app.config.get("FEED_MAX_ITEMS", 50)
    notes = list_notes(published_only=True, limit=max_items)

    # Generate RSS feed
    feed_xml = generate_feed(
        site_url=current_app.config["SITE_URL"],
        site_name=current_app.config["SITE_NAME"],
        site_description=current_app.config.get("SITE_DESCRIPTION", ""),
        notes=notes,
        limit=max_items,
    )

    # Calculate ETag (MD5 hash of feed content)
    etag = hashlib.md5(feed_xml.encode("utf-8")).hexdigest()

    # Update cache
    _feed_cache["xml"] = feed_xml
    _feed_cache["timestamp"] = now
    _feed_cache["etag"] = etag

    # Return response with appropriate headers
    response = Response(feed_xml, mimetype="application/rss+xml; charset=utf-8")
    response.headers["Cache-Control"] = f"public, max-age={cache_seconds}"
    response.headers["ETag"] = etag

    return response


@bp.route("/.well-known/oauth-authorization-server")
def oauth_client_metadata():
    """
    OAuth Client ID Metadata Document endpoint.

    Returns JSON metadata about this IndieAuth client for authorization
    server discovery. Required by IndieAuth specification section 4.2.

    This endpoint implements the modern IndieAuth (2022+) client discovery
    mechanism using OAuth Client ID Metadata Documents. Authorization servers
    like IndieLogin.com fetch this metadata to verify client registration
    and obtain redirect URIs.

    Returns:
        JSON response with client metadata

    Response Format:
        {
            "issuer": "https://example.com",
            "client_id": "https://example.com",
            "client_name": "Site Name",
            "client_uri": "https://example.com",
            "redirect_uris": ["https://example.com/auth/callback"],
            "grant_types_supported": ["authorization_code"],
            "response_types_supported": ["code"],
            "code_challenge_methods_supported": ["S256"],
            "token_endpoint_auth_methods_supported": ["none"]
        }

    Headers:
        Content-Type: application/json
        Cache-Control: public, max-age=86400 (24 hours)

    References:
        - IndieAuth Spec: https://indieauth.spec.indieweb.org/#client-information-discovery
        - OAuth Client Metadata: https://www.ietf.org/archive/id/draft-parecki-oauth-client-id-metadata-document-00.html
        - ADR-017: OAuth Client ID Metadata Document Implementation

    Examples:
        >>> response = client.get('/.well-known/oauth-authorization-server')
        >>> response.status_code
        200
        >>> data = response.get_json()
        >>> data['client_id']
        'https://example.com'
    """
    # Build metadata document using configuration values
    # client_id MUST exactly match the URL where this document is served
    metadata = {
        "issuer": current_app.config["SITE_URL"],
        "client_id": current_app.config["SITE_URL"],
        "client_name": current_app.config.get("SITE_NAME", "StarPunk"),
        "client_uri": current_app.config["SITE_URL"],
        "redirect_uris": [f"{current_app.config['SITE_URL']}/auth/callback"],
        "grant_types_supported": ["authorization_code"],
        "response_types_supported": ["code"],
        "code_challenge_methods_supported": ["S256"],
        "token_endpoint_auth_methods_supported": ["none"],
    }

    # Create JSON response
    response = jsonify(metadata)

    # Cache for 24 hours (metadata rarely changes)
    response.cache_control.max_age = 86400
    response.cache_control.public = True

    return response