phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0 Releases 48 Tags

RSS Feed
  • v1.0.0-rc.5 a7e0af9c2c
    Compare

    Release 1.0.0-rc.5: Critical Production Fixes

    phil released this 2025-11-25 04:20:56 +01:00 | 85 commits to main since this release

    RELEASE CANDIDATE 5 - CRITICAL HOTFIX
    Architect Rating: EXCELLENT - Approved for immediate deployment

    This release contains two critical production fixes that resolve
    container deployment issues and IndieAuth specification compliance.

    CRITICAL FIXES

    1. Migration Race Condition (CRITICAL)

      • Fixed database migration failures with multiple gunicorn workers
      • Implemented SQLite BEGIN IMMEDIATE transaction locking
      • Added exponential backoff retry logic (10 attempts, 120s max)
      • Workers now coordinate properly during migration
      • Graduated logging (DEBUG -> INFO -> WARNING) based on retries
      • Resolves container startup crashes in production

    2. IndieAuth Endpoint Discovery (CRITICAL)

      • Fixed hardcoded endpoint configuration (violated W3C spec)
      • Implemented dynamic endpoint discovery from profile URL
      • Compliant with W3C IndieAuth Specification Section 4.2
      • Supports HTTP Link headers and HTML link elements
      • Smart caching with 1-hour TTL for endpoints
      • Graceful fallback to expired cache on network failures

    BREAKING CHANGES

    • Removed TOKEN_ENDPOINT configuration variable
      • Endpoints now auto-discovered from ADMIN_ME profile
      • Deprecation warning if TOKEN_ENDPOINT still in environment
      • Migration guide: docs/migration/fix-hardcoded-endpoints.md

    TECHNICAL IMPLEMENTATION

    Migration Race Condition:

    • Database-level locking prevents concurrent migrations
    • Exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s, 60s (max)
    • Total retry window: up to 120 seconds
    • New connection per retry to prevent state issues
    • See: ADR-022, migration-race-condition-fix-implementation.md

    IndieAuth Endpoint Discovery:

    • Discovers authorization_endpoint and token_endpoint
    • Validates endpoints (HTTPS in production, localhost in debug)
    • Token verification cached (5 min TTL, SHA-256 token hash)
    • URL normalization for secure comparison
    • Retry logic with exponential backoff for network errors
    • See: ADR-030-CORRECTED, ADR-031, indieauth-endpoint-discovery.md

    ARCHITECTURE DOCUMENTATION

    New ADRs:

    • ADR-022: Migration Race Condition Fix
    • ADR-030-CORRECTED: IndieAuth Endpoint Discovery Decision
    • ADR-031: Endpoint Discovery Implementation

    New Documentation:

    • docs/architecture/indieauth-endpoint-discovery.md
    • docs/architecture/migration-race-condition-answers.md
    • docs/architecture/migration-fix-quick-reference.md
    • docs/migration/fix-hardcoded-endpoints.md
    • docs/security/indieauth-endpoint-discovery-security.md

    Implementation Reports:

    • docs/reports/2025-11-24-v1.0.0-rc.5-implementation.md
    • docs/reports/migration-race-condition-fix-implementation.md
    • docs/reports/2025-11-24-endpoint-discovery-analysis.md

    TESTING

    New Test Coverage:

    • tests/test_migration_race_condition.py (race condition simulation)
    • tests/test_auth_external.py (endpoint discovery and caching)

    All tests passing with comprehensive coverage of:

    • Concurrent migration attempts
    • Lock acquisition and release
    • Endpoint discovery from various sources
    • Caching behavior and TTL
    • Error handling and fallback scenarios

    DEPLOYMENT NOTES

    This release is safe to deploy immediately:

    1. Migration system handles worker coordination automatically
    2. TOKEN_ENDPOINT removal is backward compatible (shows warning)
    3. Endpoint discovery is automatic from existing ADMIN_ME config
    4. No database schema changes required
    5. All existing functionality preserved

    For upgrade instructions, see:

    • docs/migration/fix-hardcoded-endpoints.md

    WHAT'S NEXT

    This RC5 addresses critical production issues discovered during
    deployment testing. The fixes ensure reliable container deployments
    and full IndieAuth specification compliance.

    Next steps toward v1.0.0:

    • Production deployment validation
    • Performance monitoring of endpoint discovery caching
    • Final integration testing

    Release: v1.0.0-rc.5
    Date: 2025-11-24
    Type: Hotfix (Critical)
    Commits: 4 (from hotfix/migration-race-condition)
    Files Changed: 22 files, +7704/-185 lines
    Architect Approval: EXCELLENT

    Downloads