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

feat(tags): Add database schema and tags module (v1.3.0 Phase 1)

Browse Source 
Implements tag/category system backend following microformats2 p-category specification.

Database changes:
- Migration 008: Add tags and note_tags tables
- Normalized tag storage (case-insensitive lookup, display name preserved)
- Indexes for performance

New module:
- starpunk/tags.py: Tag management functions
  - normalize_tag: Normalize tag strings
  - get_or_create_tag: Get or create tag records
  - add_tags_to_note: Associate tags with notes (replaces existing)
  - get_note_tags: Retrieve note tags (alphabetically ordered)
  - get_tag_by_name: Lookup tag by normalized name
  - get_notes_by_tag: Get all notes with specific tag
  - parse_tag_input: Parse comma-separated tag input

Model updates:
- Note.tags property (lazy-loaded, prefer pre-loading in routes)
- Note.to_dict() add include_tags parameter

CRUD updates:
- create_note() accepts tags parameter
- update_note() accepts tags parameter (None = no change, [] = remove all)

Micropub integration:
- Pass tags to create_note() (tags already extracted by extract_tags())
- Return tags in q=source response

Per design doc: docs/design/v1.3.0/microformats-tags-design.md

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-12-10 11:24:23 -07:00
parent 927db4aea0
commit f10d0679da
188 changed files with 601 additions and 945 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
docs/architecture/database-migration-architecture.md
View File

@@ -1,212 +0,0 @@
# Database Migration Architecture
## Overview
StarPunk uses a dual-strategy database initialization system that combines immediate schema creation (SCHEMA_SQL) with evolutionary migrations. This architecture provides both fast fresh installations and safe upgrades for existing databases.
## Components
### 1. SCHEMA_SQL (database.py)
**Purpose**: Define the current complete database schema for fresh installations
**Location**: `/starpunk/database.py` lines 11-87
**Responsibilities**:
- Create all tables with current structure
- Create all columns with current types
- Create base indexes for performance
- Provide instant database initialization for new installations
**Design Principle**: Always represents the latest schema version
### 2. Migration Files
**Purpose**: Transform existing databases from one version to another
**Location**: `/migrations/*.sql`
**Format**: `{number}_{description}.sql`
- Number: Three-digit zero-padded sequence (001, 002, etc.)
- Description: Clear indication of changes
**Responsibilities**:
- Add new tables/columns to existing databases
- Modify existing structures safely
- Create indexes and constraints
- Handle breaking changes with data preservation
### 3. Migration Runner (migrations.py)
**Purpose**: Intelligent application of migrations based on database state
**Location**: `/starpunk/migrations.py`
**Key Features**:
- Fresh database detection
- Partial schema recognition
- Smart migration skipping
- Index-only application
- Transaction safety
## Architecture Patterns
### Fresh Database Flow
```
1. init_db() called
2. SCHEMA_SQL executed (creates all current tables/columns)
3. run_migrations() called
4. Detects fresh database (empty schema_migrations)
5. Checks if schema is current (is_schema_current())
6. If current: marks all migrations as applied (no execution)
7. If partial: applies only needed migrations
```
### Existing Database Flow
```
1. init_db() called
2. SCHEMA_SQL executed (CREATE IF NOT EXISTS - no-op for existing tables)
3. run_migrations() called
4. Reads schema_migrations table
5. Discovers migration files
6. Applies only unapplied migrations in sequence
```
### Hybrid Database Flow (Production Issue Case)
```
1. Database has tables from SCHEMA_SQL but no migration records
2. run_migrations() detects migration_count == 0
3. For each migration, calls is_migration_needed()
4. Migration 002: detects tables exist, indexes missing
5. Creates only missing indexes
6. Marks migration as applied without full execution
```
## State Detection Logic
### is_schema_current() Function
Determines if database matches current schema version completely.
**Checks**:
1. Table existence (authorization_codes)
2. Column existence (token_hash in tokens)
3. Index existence (idx_tokens_hash, etc.)
**Returns**:
- True: Schema is completely current (all migrations applied)
- False: Schema needs migrations
### is_migration_needed() Function
Determines if a specific migration should be applied.
**For Migration 002**:
1. Check if authorization_codes table exists
2. Check if token_hash column exists in tokens
3. Check if indexes exist
4. Return True only if tables/columns are missing
5. Return False if only indexes are missing (handled separately)
## Design Decisions
### Why Dual Strategy?
1. **Fresh Install Speed**: SCHEMA_SQL provides instant, complete schema
2. **Upgrade Safety**: Migrations provide controlled, versioned changes
3. **Flexibility**: Can handle various database states gracefully
### Why Smart Detection?
1. **Idempotency**: Same code works for any database state
2. **Self-Healing**: Can fix partial schemas automatically
3. **No Data Loss**: Never drops tables unnecessarily
### Why Check Indexes Separately?
1. **SCHEMA_SQL Evolution**: As SCHEMA_SQL includes migration changes, we avoid conflicts
2. **Granular Control**: Can apply just missing pieces
3. **Performance**: Indexes can be added without table locks
## Migration Guidelines
### Writing Migrations
1. **Never use IF NOT EXISTS in migrations**: Migrations should fail if preconditions aren't met
2. **Always provide rollback path**: Document how to reverse changes
3. **One logical change per migration**: Keep migrations focused
4. **Test with various database states**: Fresh, existing, and hybrid
### SCHEMA_SQL Updates
When updating SCHEMA_SQL after a migration:
1. Include all changes from the migration
2. Remove indexes that migrations will create (avoid conflicts)
3. Keep CREATE IF NOT EXISTS for idempotency
4. Test fresh installations
## Error Recovery
### Common Issues
#### "Table already exists" Error
**Cause**: Migration tries to create table that SCHEMA_SQL already created
**Solution**: Smart detection should prevent this. If it fails:
1. Check if migration is already in schema_migrations
2. Verify is_migration_needed() logic
3. Manually mark migration as applied if needed
#### Missing Indexes
**Cause**: Tables exist from SCHEMA_SQL but indexes weren't created
**Solution**: Migration system creates missing indexes separately
#### Partial Migration Application
**Cause**: Migration failed partway through
**Solution**: Transactions ensure all-or-nothing. Rollback and retry.
## State Verification Queries
### Check Migration Status
```sql
SELECT * FROM schema_migrations ORDER BY id;
```
### Check Table Existence
```sql
SELECT name FROM sqlite_master
WHERE type='table'
ORDER BY name;
```
### Check Index Existence
```sql
SELECT name FROM sqlite_master
WHERE type='index'
ORDER BY name;
```
### Check Column Structure
```sql
PRAGMA table_info(tokens);
PRAGMA table_info(authorization_codes);
```
## Future Improvements
### Potential Enhancements
1. **Migration Rollback**: Add down() migrations for reversibility
2. **Schema Versioning**: Add version table for faster state detection
3. **Migration Validation**: Pre-flight checks before application
4. **Dry Run Mode**: Test migrations without applying
### Considered Alternatives
1. **Migrations-Only**: Rejected - slow fresh installs
2. **SCHEMA_SQL-Only**: Rejected - no upgrade path
3. **ORM-Based**: Rejected - unnecessary complexity for single-user system
4. **External Tools**: Rejected - additional dependencies
## Security Considerations
### Migration Safety
1. All migrations run in transactions
2. Rollback on any error
3. No data destruction without explicit user action
4. Token invalidation documented when necessary
### Schema Security
1. Tokens stored as SHA256 hashes
2. Proper indexes for timing attack prevention
3. Expiration columns for automatic cleanup
4. Soft deletion support

450
docs/architecture/endpoint-discovery-answers.md
View File

@@ -1,450 +0,0 @@
# IndieAuth Endpoint Discovery: Definitive Implementation Answers
**Date**: 2025-11-24
**Architect**: StarPunk Software Architect
**Status**: APPROVED FOR IMPLEMENTATION
**Target Version**: 1.0.0-rc.5
---
## Executive Summary
These are definitive answers to the developer's 10 questions about IndieAuth endpoint discovery implementation. The developer should implement exactly as specified here.
---
## CRITICAL ANSWERS (Blocking Implementation)
### Answer 1: The "Which Endpoint?" Problem ✅
**DEFINITIVE ANSWER**: For StarPunk V1 (single-user CMS), ALWAYS use ADMIN_ME for endpoint discovery.
Your proposed solution is **100% CORRECT**:
```python
def verify_external_token(token: str) -> Optional[Dict[str, Any]]:
"""Verify token for the admin user"""
admin_me = current_app.config.get("ADMIN_ME")
# ALWAYS discover endpoints from ADMIN_ME profile
endpoints = discover_endpoints(admin_me)
token_endpoint = endpoints['token_endpoint']
# Verify token with discovered endpoint
response = httpx.get(
token_endpoint,
headers={'Authorization': f'Bearer {token}'}
)
token_info = response.json()
# Validate token belongs to admin
if normalize_url(token_info['me']) != normalize_url(admin_me):
raise TokenVerificationError("Token not for admin user")
return token_info
```
**Rationale**:
- StarPunk V1 is explicitly single-user
- Only the admin (ADMIN_ME) can post to the CMS
- Any token not belonging to ADMIN_ME is invalid by definition
- This eliminates the chicken-and-egg problem completely
**Important**: Document this single-user assumption clearly in the code comments. When V2 adds multi-user support, this will need revisiting.
### Answer 2a: Cache Structure ✅
**DEFINITIVE ANSWER**: Use a SIMPLE cache for V1 single-user.
```python
class EndpointCache:
def __init__(self):
# Simple cache for single-user V1
self.endpoints = None
self.endpoints_expire = 0
self.token_cache = {} # token_hash -> (info, expiry)
```
**Rationale**:
- We only have one user (ADMIN_ME) in V1
- No need for profile_url -> endpoints mapping
- Simplest solution that works
- Easy to upgrade to dict-based for V2 multi-user
### Answer 3a: BeautifulSoup4 Dependency ✅
**DEFINITIVE ANSWER**: YES, add BeautifulSoup4 as a dependency.
```toml
# pyproject.toml
[project.dependencies]
beautifulsoup4 = ">=4.12.0"
```
**Rationale**:
- Industry standard for HTML parsing
- More robust than regex or built-in parser
- Pure Python (with html.parser backend)
- Well-maintained and documented
- Worth the dependency for correctness
---
## IMPORTANT ANSWERS (Affects Quality)
### Answer 2b: Token Hashing ✅
**DEFINITIVE ANSWER**: YES, hash tokens with SHA-256.
```python
token_hash = hashlib.sha256(token.encode()).hexdigest()
```
**Rationale**:
- Prevents tokens appearing in logs
- Fixed-length cache keys
- Security best practice
- NO need for HMAC (we're not signing, just hashing)
- NO need for constant-time comparison (cache lookup, not authentication)
### Answer 2c: Cache Invalidation ✅
**DEFINITIVE ANSWER**: Clear cache on:
1. **Application startup** (cache is in-memory)
2. **TTL expiry** (automatic)
3. **NOT on failures** (could be transient network issues)
4. **NO manual endpoint needed** for V1
### Answer 2d: Cache Storage ✅
**DEFINITIVE ANSWER**: Custom EndpointCache class with simple dict.
```python
class EndpointCache:
"""Simple in-memory cache with TTL support"""
def __init__(self):
self.endpoints = None
self.endpoints_expire = 0
self.token_cache = {}
def get_endpoints(self):
if time.time() < self.endpoints_expire:
return self.endpoints
return None
def set_endpoints(self, endpoints, ttl=3600):
self.endpoints = endpoints
self.endpoints_expire = time.time() + ttl
```
**Rationale**:
- Simple and explicit
- No external dependencies
- Easy to test
- Clear TTL handling
### Answer 3b: HTML Validation ✅
**DEFINITIVE ANSWER**: Handle malformed HTML gracefully.
```python
try:
soup = BeautifulSoup(html, 'html.parser')
# Look for links in both head and body (be liberal)
for link in soup.find_all('link', rel=True):
# Process...
except Exception as e:
logger.warning(f"HTML parsing failed: {e}")
return {} # Return empty, don't crash
```
### Answer 3c: Case Sensitivity ✅
**DEFINITIVE ANSWER**: BeautifulSoup handles this correctly by default. No special handling needed.
### Answer 4a: Link Header Parsing ✅
**DEFINITIVE ANSWER**: Use simple regex, document limitations.
```python
def _parse_link_header(self, header: str) -> Dict[str, str]:
"""Parse Link header (basic RFC 8288 support)
Note: Only supports quoted rel values, single Link headers
"""
pattern = r'<([^>]+)>;\s*rel="([^"]+)"'
matches = re.findall(pattern, header)
# ... process matches
```
**Rationale**:
- Simple implementation for V1
- Document limitations clearly
- Can upgrade if needed later
- Avoids additional dependencies
### Answer 4b: Multiple Headers ✅
**DEFINITIVE ANSWER**: Your regex with re.findall() is correct. It handles both cases.
### Answer 4c: Priority Order ✅
**DEFINITIVE ANSWER**: Option B - Merge with Link header overwriting HTML.
```python
endpoints = {}
# First get from HTML
endpoints.update(html_endpoints)
# Then overwrite with Link headers (higher priority)
endpoints.update(link_header_endpoints)
```
### Answer 5a: URL Validation ✅
**DEFINITIVE ANSWER**: Validate with these checks:
```python
def validate_endpoint_url(url: str) -> bool:
parsed = urlparse(url)
# Must be absolute
if not parsed.scheme or not parsed.netloc:
raise DiscoveryError("Invalid URL format")
# HTTPS required in production
if not current_app.debug and parsed.scheme != 'https':
raise DiscoveryError("HTTPS required in production")
# Allow localhost only in debug mode
if not current_app.debug and parsed.hostname in ['localhost', '127.0.0.1', '::1']:
raise DiscoveryError("Localhost not allowed in production")
return True
```
### Answer 5b: URL Normalization ✅
**DEFINITIVE ANSWER**: Normalize only for comparison, not storage.
```python
def normalize_url(url: str) -> str:
"""Normalize URL for comparison only"""
return url.rstrip("/").lower()
```
Store endpoints as discovered, normalize only when comparing.
### Answer 5c: Relative URL Edge Cases ✅
**DEFINITIVE ANSWER**: Let urljoin() handle it, document behavior.
Python's urljoin() handles first two cases correctly. For the third (broken) case, let it fail naturally. Don't try to be clever.
### Answer 6a: Discovery Failures ✅
**DEFINITIVE ANSWER**: Fail closed with grace period.
```python
def discover_endpoints(profile_url: str) -> Dict[str, str]:
try:
# Try discovery
endpoints = self._fetch_and_parse(profile_url)
self.cache.set_endpoints(endpoints)
return endpoints
except Exception as e:
# Check cache even if expired (grace period)
cached = self.cache.get_endpoints(ignore_expiry=True)
if cached:
logger.warning(f"Using expired cache due to discovery failure: {e}")
return cached
# No cache, must fail
raise DiscoveryError(f"Endpoint discovery failed: {e}")
```
### Answer 6b: Token Verification Failures ✅
**DEFINITIVE ANSWER**: Retry ONLY for network errors.
```python
def verify_with_retries(endpoint: str, token: str, max_retries: int = 3):
for attempt in range(max_retries):
try:
response = httpx.get(...)
if response.status_code in [500, 502, 503, 504]:
# Server error, retry
if attempt < max_retries - 1:
time.sleep(2 ** attempt) # Exponential backoff
continue
return response
except (httpx.TimeoutException, httpx.NetworkError):
if attempt < max_retries - 1:
time.sleep(2 ** attempt)
continue
raise
# For 400/401/403, fail immediately (no retry)
```
### Answer 6c: Timeout Configuration ✅
**DEFINITIVE ANSWER**: Use these timeouts:
```python
DISCOVERY_TIMEOUT = 5.0 # Profile fetch (cached, so can be slower)
VERIFICATION_TIMEOUT = 3.0 # Token verification (every request)
```
Not configurable in V1. Hardcode with constants.
---
## OTHER ANSWERS
### Answer 7a: Test Strategy ✅
**DEFINITIVE ANSWER**: Unit tests mock, ONE integration test with real IndieAuth.com.
### Answer 7b: Test Fixtures ✅
**DEFINITIVE ANSWER**: YES, create reusable fixtures.
```python
# tests/fixtures/indieauth_profiles.py
PROFILES = {
'link_header': {...},
'html_links': {...},
'both': {...},
# etc.
}
```
### Answer 7c: Test Coverage ✅
**DEFINITIVE ANSWER**:
- 90%+ coverage for new code
- All edge cases tested
- One real integration test
### Answer 8a: First Request Latency ✅
**DEFINITIVE ANSWER**: Accept the delay. Do NOT pre-warm cache.
**Rationale**:
- Only happens once per hour
- Pre-warming adds complexity
- User can wait 850ms for first post
### Answer 8b: Cache TTLs ✅
**DEFINITIVE ANSWER**: Keep as specified:
- Endpoints: 3600s (1 hour)
- Token verifications: 300s (5 minutes)
These are good defaults.
### Answer 8c: Concurrent Requests ✅
**DEFINITIVE ANSWER**: Accept duplicate discoveries for V1.
No locking needed for single-user low-traffic V1.
### Answer 9a: Configuration Changes ✅
**DEFINITIVE ANSWER**: Remove TOKEN_ENDPOINT immediately with deprecation warning.
```python
# config.py
if 'TOKEN_ENDPOINT' in os.environ:
logger.warning(
"TOKEN_ENDPOINT is deprecated and ignored. "
"Remove it from your configuration. "
"Endpoints are now discovered from ADMIN_ME profile."
)
```
### Answer 9b: Backward Compatibility ✅
**DEFINITIVE ANSWER**: Document breaking change in CHANGELOG. No migration script.
We're in RC phase, breaking changes are acceptable.
### Answer 9c: Health Check ✅
**DEFINITIVE ANSWER**: NO endpoint discovery in health check.
Too expensive. Health check should be fast.
### Answer 10a: Local Development ✅
**DEFINITIVE ANSWER**: Allow HTTP in debug mode.
```python
if current_app.debug:
# Allow HTTP in development
pass
else:
# Require HTTPS in production
if parsed.scheme != 'https':
raise SecurityError("HTTPS required")
```
### Answer 10b: Testing with Real Providers ✅
**DEFINITIVE ANSWER**: Document test setup, skip in CI.
```python
@pytest.mark.skipif(
not os.environ.get('TEST_REAL_INDIEAUTH'),
reason="Set TEST_REAL_INDIEAUTH=1 to run real provider tests"
)
def test_real_indieauth():
# Test with real IndieAuth.com
```
---
## Implementation Go/No-Go Decision
### ✅ APPROVED FOR IMPLEMENTATION
You have all the information needed to implement endpoint discovery correctly. Proceed with your Phase 1-5 plan.
### Implementation Priorities
1. **FIRST**: Implement Question 1 solution (ADMIN_ME discovery)
2. **SECOND**: Add BeautifulSoup4 dependency
3. **THIRD**: Create EndpointCache class
4. **THEN**: Follow your phased implementation plan
### Key Implementation Notes
1. **Always use ADMIN_ME** for endpoint discovery in V1
2. **Fail closed** on security errors
3. **Be liberal** in what you accept (HTML parsing)
4. **Be strict** in what you validate (URLs, tokens)
5. **Document** single-user assumptions clearly
6. **Test** edge cases thoroughly
---
## Summary for Quick Reference
| Question | Answer | Implementation |
|----------|--------|----------------|
| Q1: Which endpoint? | Always use ADMIN_ME | `discover_endpoints(admin_me)` |
| Q2a: Cache structure? | Simple for single-user | `self.endpoints = None` |
| Q3a: Add BeautifulSoup4? | YES | Add to dependencies |
| Q5a: URL validation? | HTTPS in prod, localhost in dev | Check with `current_app.debug` |
| Q6a: Error handling? | Fail closed with cache grace | Try cache on failure |
| Q6b: Retry logic? | Only for network errors | 3 retries with backoff |
| Q9a: Remove TOKEN_ENDPOINT? | Yes with warning | Deprecation message |
---
**This document provides definitive answers. Implement as specified. No further architectural review needed before coding.**
**Document Version**: 1.0
**Status**: FINAL
**Next Step**: Begin implementation immediately

152
docs/architecture/hotfix-v1.1.1-rc2-review.md
View File

@@ -1,152 +0,0 @@
# Architectural Review: Hotfix v1.1.1-rc.2
## Executive Summary
**Overall Assessment: APPROVED WITH MINOR CONCERNS**
The hotfix successfully resolves the production issue but reveals deeper architectural concerns about data contracts between modules.
## Part 1: Documentation Reorganization
### Actions Taken
1. **Deleted Misclassified ADRs**:
- Removed `/docs/decisions/ADR-022-admin-dashboard-route-conflict-hotfix.md`
- Removed `/docs/decisions/ADR-060-production-hotfix-metrics-dashboard.md`
**Rationale**: These documented bug fixes, not architectural decisions. ADRs should capture decisions that have lasting impact on system architecture, not tactical implementation fixes.
2. **Created Consolidated Documentation**:
- Created `/docs/design/hotfix-v1.1.1-rc2-consolidated.md` combining both bug fix designs
- Preserved existing `/docs/reports/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md` as implementation record
3. **Proper Classification**:
- Bug fix designs belong in `/docs/design/` or `/docs/reports/`
- ADRs reserved for true architectural decisions per our documentation standards
## Part 2: Implementation Review
### Code Quality Assessment
#### Transformer Function (Lines 218-260 in admin.py)
**Correctness: VERIFIED ✓**
- Correctly maps `metrics.by_type.database` → `metrics.database`
- Properly transforms field names:
- `avg_duration_ms` → `avg`
- `min_duration_ms` → `min`
- `max_duration_ms` → `max`
- Provides safe defaults for missing data
**Completeness: VERIFIED ✓**
- Handles all three operation types (database, http, render)
- Preserves top-level stats (total_count, max_size, process_id)
- Gracefully handles missing `by_type` key
**Error Handling: ADEQUATE**
- Try/catch block with fallback to safe defaults
- Flash message to user on error
- Defensive imports with graceful degradation
#### Implementation Analysis
**Strengths**:
1. Minimal change scope - only touches route handler
2. Preserves monitoring module's API contract
3. Clear separation of concerns (presentation adapter pattern)
4. Well-documented with inline comments
**Weaknesses**:
1. **Symptom Treatment**: Fixes the symptom (template error) not the root cause (data contract mismatch)
2. **Hidden Coupling**: Creates implicit dependency between template expectations and transformer logic
3. **Technical Debt**: Adds translation layer instead of fixing the actual mismatch
### Critical Finding
The monitoring module DOES exist at `/home/phil/Projects/starpunk/starpunk/monitoring/` with proper exports in `__init__.py`. The "missing module" issue in the initial diagnosis was incorrect. The real issue was purely the data structure mismatch.
## Part 3: Technical Debt Analysis
### Current State
We now have a transformer function acting as an adapter between:
- **Monitoring Module**: Logically structured data with `by_type` organization
- **Template**: Expects flat structure for direct access
### Better Long-term Solution
One of these should happen in v1.2.0:
1. **Option A: Fix the Template** (Recommended)
- Update template to use `metrics.by_type.database.count`
- More semantically correct
- Removes need for transformer
2. **Option B: Monitoring Module API Change**
- Add a `get_metrics_for_display()` method that returns flat structure
- Keep `get_metrics_stats()` for programmatic access
- Cleaner separation between API and presentation
### Risk Assessment
**Current Risks**:
- LOW: Transformer is simple and well-tested
- LOW: Performance impact negligible (small data structure)
- MEDIUM: Future template changes might break if transformer isn't updated
**Future Risks**:
- If more consumers need the flat structure, transformer logic gets duplicated
- If monitoring module changes structure, transformer breaks silently
## Part 4: Final Hotfix Assessment
### Is v1.1.1-rc.2 Ready for Production?
**YES** - The hotfix is ready for production deployment.
**Verification Checklist**:
- ✓ Root cause identified and fixed (data structure mismatch)
- ✓ All tests pass (32/32 admin route tests)
- ✓ Transformer function validated with test script
- ✓ Error handling in place
- ✓ Safe defaults provided
- ✓ No breaking changes to existing functionality
- ✓ Documentation updated
**Production Readiness**:
- The fix is minimal and focused
- Risk is low due to isolated change scope
- Fallback behavior implemented
- All acceptance criteria met
## Recommendations
### Immediate (Before Deploy)
None - the hotfix is adequate for production deployment.
### Short-term (v1.2.0)
1. Create proper ADR for whether to keep adapter pattern or fix template/module contract
2. Add integration tests specifically for metrics dashboard data flow
3. Document the data contract between monitoring module and consumers
### Long-term (v2.0.0)
1. Establish clear API contracts with schema validation
2. Consider GraphQL or similar for flexible data querying
3. Implement proper view models separate from business logic
## Architectural Lessons
This incident highlights important architectural principles:
1. **Data Contracts Matter**: Implicit contracts between modules cause production issues
2. **ADRs vs Bug Fixes**: Not every technical decision is an architectural decision
3. **Adapter Pattern**: Valid for hotfixes but indicates architectural misalignment
4. **Template Coupling**: Templates shouldn't dictate internal data structures
## Conclusion
The hotfix successfully resolves the production issue using a reasonable adapter pattern. While not architecturally ideal, it's the correct tactical solution for a production hotfix. The transformer function is correct, complete, and safe.
**Recommendation**: Deploy v1.1.1-rc.2 to production, then address the architectural debt in v1.2.0 with a proper redesign of the data contract.
---
*Reviewed by: StarPunk Architect*
*Date: 2025-11-25*

196
docs/architecture/indieauth-assessment.md
View File

@@ -1,196 +0,0 @@
# IndieAuth Architecture Assessment
**Date**: 2025-11-24
**Author**: StarPunk Architect
**Status**: Critical Review
## Executive Summary
You asked: **"WHY? Why not use an established provider like indieauth for authorization and token?"**
The honest answer: **The current decision to implement our own authorization and token endpoints appears to be based on a fundamental misunderstanding of how IndieAuth works, combined with over-engineering for a single-user system.**
## Current Implementation Reality
StarPunk has **already implemented** its own authorization and token endpoints:
- `/auth/authorization` - Full authorization endpoint (327 lines of code)
- `/auth/token` - Full token endpoint implementation
- Complete authorization code flow with PKCE support
- Token generation, storage, and validation
This represents significant complexity that may not have been necessary.
## The Core Misunderstanding
ADR-021 reveals the critical misunderstanding that drove this decision:
> "The user reported that IndieLogin.com requires manual client_id registration, making it unsuitable for self-hosted software"
This is **completely false**. IndieAuth (including IndieLogin.com) requires **no registration whatsoever**. Each self-hosted instance uses its own domain as the client_id automatically.
## What StarPunk Actually Needs
For a **single-user personal CMS**, StarPunk needs:
1. **Admin Authentication**: Log the owner into the admin panel
- ✅ Currently uses IndieLogin.com correctly
- Works perfectly, no changes needed
2. **Micropub Token Verification**: Verify tokens from Micropub clients
- Only needs to **verify** tokens, not issue them
- Could delegate entirely to the user's chosen authorization server
## The Architectural Options
### Option A: Use External Provider (Recommended for Simplicity)
**How it would work:**
1. User adds these links to their personal website:
```html
<link rel="authorization_endpoint" href="https://indielogin.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="https://starpunk.example/micropub">
```
2. Micropub clients discover endpoints from user's site
3. Clients get tokens from indieauth.com/tokens.indieauth.com
4. StarPunk only verifies tokens (10-20 lines of code)
**Benefits:**
- ✅ **Simplicity**: 95% less code
- ✅ **Security**: Maintained by IndieAuth experts
- ✅ **Reliability**: Battle-tested infrastructure
- ✅ **Standards**: Full spec compliance guaranteed
- ✅ **Zero maintenance**: No security updates needed
**Drawbacks:**
- ❌ Requires user to configure their personal domain
- ❌ Dependency on external service
- ❌ User needs to understand IndieAuth flow
### Option B: Implement Own Endpoints (Current Approach)
**What we've built:**
- Complete authorization endpoint
- Complete token endpoint
- Authorization codes table
- Token management system
- PKCE support
- Scope validation
**Benefits:**
- ✅ Self-contained system
- ✅ No external dependencies for Micropub
- ✅ User doesn't need separate domain configuration
- ✅ Complete control over auth flow
**Drawbacks:**
- ❌ **Complexity**: 500+ lines of auth code
- ❌ **Security burden**: We maintain all security
- ❌ **Over-engineered**: For a single-user system
- ❌ **Spec compliance**: Our responsibility
- ❌ **Maintenance**: Ongoing updates needed
## My Honest Assessment
### Was This the Right Decision?
**No, probably not.** For a single-user personal CMS that values simplicity:
1. **We solved a problem that didn't exist** (registration requirement)
2. **We added unnecessary complexity** (500+ lines vs 20 lines)
3. **We took on security responsibilities** unnecessarily
4. **We violated our core principle**: "Every line of code must justify its existence"
### Why Did This Happen?
1. **Misunderstanding**: Believed IndieAuth required registration
2. **Scope creep**: Wanted StarPunk to be "complete"
3. **Over-engineering**: Built for theoretical multi-user future
4. **Momentum**: Once started, kept building
## What Should We Do Now?
### Option 1: Keep Current Implementation (Pragmatic)
Since it's **already built and working**:
- Document it properly
- Security audit the implementation
- Add comprehensive tests
- Accept the maintenance burden
**Rationale**: Sunk cost, but functional. Changing now adds work.
### Option 2: Simplify to External Provider (Purist)
Remove our endpoints and use external providers:
- Delete `/auth/authorization` and `/auth/token`
- Keep only admin auth via IndieLogin
- Add token verification for Micropub
- Document user setup clearly
**Rationale**: Aligns with simplicity principle, reduces attack surface.
### Option 3: Hybrid Approach (Recommended)
Keep implementation but **make it optional**:
1. Default: Use external providers (simple)
2. Advanced: Enable built-in endpoints (self-contained)
3. Configuration flag: `INDIEAUTH_MODE = "external" | "builtin"`
**Rationale**: Best of both worlds, user choice.
## My Recommendation
### For V1 Release
**Keep the current implementation** but:
1. **Document the trade-offs** clearly
2. **Add configuration option** to disable built-in endpoints
3. **Provide clear setup guides** for both modes:
- Simple mode: Use external providers
- Advanced mode: Use built-in endpoints
4. **Security audit** the implementation thoroughly
### For V2 Consideration
1. **Measure actual usage**: Do users want built-in auth?
2. **Consider removing** if external providers work well
3. **Or enhance** if users value self-contained nature
## The Real Question
You asked "WHY?" The honest answer:
**We built our own auth endpoints because we misunderstood IndieAuth and over-engineered for a single-user system. It wasn't necessary, but now that it's built, it does provide a self-contained solution that some users might value.**
## Architecture Principles Violated
1. ✗ **Minimal Code**: Added 500+ lines unnecessarily
2. ✗ **Simplicity First**: Chose complex over simple
3. ✗ **YAGNI**: Built for imagined requirements
4. ✗ **Single Responsibility**: StarPunk is a CMS, not an auth server
## Architecture Principles Upheld
1. ✓ **Standards Compliance**: Full IndieAuth spec implementation
2. ✓ **No Lock-in**: Users can switch providers
3. ✓ **Self-hostable**: Complete solution in one package
## Conclusion
The decision to implement our own authorization and token endpoints was **architecturally questionable** for a minimal single-user CMS. It adds complexity without proportional benefit.
However, since it's already implemented:
1. We should keep it for V1 (pragmatism over purity)
2. Make it optional via configuration
3. Document both approaches clearly
4. Re-evaluate based on user feedback
**The lesson**: Always challenge requirements and complexity. Just because we *can* build something doesn't mean we *should*.
---
*"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."* - Antoine de Saint-Exupéry
This applies directly to StarPunk's auth architecture.

139
docs/architecture/indieauth-client-diagnosis.md
View File

@@ -1,139 +0,0 @@
# IndieAuth Client Registration Issue - Diagnosis Report
**Date:** 2025-11-19
**Issue:** IndieLogin.com reports "This client_id is not registered"
**Client ID:** https://starpunk.thesatelliteoflove.com
## Executive Summary
The issue is caused by the h-app microformat on StarPunk being **hidden** with both `hidden` and `aria-hidden="true"` attributes. This makes the client identification invisible to IndieAuth parsers.
## Analysis Results
### 1. Identity Domain (https://thesatelliteoflove.com) ✅
**Status:** PROPERLY CONFIGURED
The identity page has all required IndieAuth elements:
```html
<!-- IndieAuth endpoints are correctly declared -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<!-- h-card is properly structured -->
<div class="h-card">
<h1 class="p-name">Phil Skents</h1>
<p class="identity-url">
<a class="u-url u-uid" href="https://thesatelliteoflove.com">
https://thesatelliteoflove.com
</a>
</p>
</div>
```
### 2. StarPunk Client (https://starpunk.thesatelliteoflove.com) ❌
**Status:** MISCONFIGURED - Client identification is hidden
The h-app microformat exists but is **invisible** to parsers:
```html
<!-- PROBLEM: hidden and aria-hidden attributes -->
<div class="h-app" hidden aria-hidden="true">
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
</div>
```
## Root Cause
IndieAuth clients must be identifiable through visible h-app or h-x-app microformats. The `hidden` attribute makes the element completely invisible to:
1. Microformat parsers
2. Screen readers
3. Search engines
4. IndieAuth verification services
When IndieLogin.com attempts to verify the client_id, it cannot find any client identification because the h-app is hidden from the DOM.
## IndieAuth Client Verification Process
1. User initiates auth with client_id=https://starpunk.thesatelliteoflove.com
2. IndieLogin fetches the client URL
3. IndieLogin parses for h-app/h-x-app microformats
4. **FAILS:** No visible h-app found due to `hidden` attribute
5. Returns error: "This client_id is not registered"
## Solution
Remove the `hidden` and `aria-hidden="true"` attributes from the h-app div:
### Current (Broken):
```html
<div class="h-app" hidden aria-hidden="true">
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
</div>
```
### Fixed:
```html
<div class="h-app">
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
</div>
```
If visual hiding is desired, use CSS instead:
```css
.h-app {
position: absolute;
left: -9999px;
width: 1px;
height: 1px;
overflow: hidden;
}
```
However, **best practice** is to keep it visible as client identification, possibly styled as:
```html
<footer>
<div class="h-app">
<p>
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
<span class="p-version">v0.6.1</span>
</p>
</div>
</footer>
```
## Verification Steps
After fixing:
1. Deploy the updated HTML without `hidden` attributes
2. Test at https://indiewebify.me/ - verify h-app is detected
3. Clear any caches (CloudFlare, browser, etc.)
4. Test authentication flow at https://indielogin.com/
## Additional Recommendations
1. **Add more client metadata** for better identification:
```html
<div class="h-app">
<img src="/static/logo.png" class="u-logo" alt="StarPunk logo">
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
<p class="p-summary">A minimal IndieWeb CMS</p>
</div>
```
2. **Consider adding redirect_uri registration** if using fixed callback URLs
3. **Test with multiple IndieAuth parsers**:
- https://indiewebify.me/
- https://sturdy-backbone.glitch.me/
- https://microformats.io/
## References
- [IndieAuth Spec - Client Information Discovery](https://www.w3.org/TR/indieauth/#client-information-discovery)
- [Microformats h-app](http://microformats.org/wiki/h-app)
- [IndieWeb Client ID](https://indieweb.org/client_id)

444
docs/architecture/indieauth-endpoint-discovery.md
View File

@@ -1,444 +0,0 @@
# IndieAuth Endpoint Discovery Architecture
## Overview
This document details the CORRECT implementation of IndieAuth endpoint discovery for StarPunk. This corrects a fundamental misunderstanding where endpoints were incorrectly hardcoded instead of being discovered dynamically.
## Core Principle
**Endpoints are NEVER hardcoded. They are ALWAYS discovered from the user's profile URL.**
## Discovery Process
### Step 1: Profile URL Fetching
When discovering endpoints for a user (e.g., `https://alice.example.com/`):
```
GET https://alice.example.com/ HTTP/1.1
Accept: text/html
User-Agent: StarPunk/1.0
```
### Step 2: Endpoint Extraction
Check in priority order:
#### 2.1 HTTP Link Headers (Highest Priority)
```
Link: <https://auth.example.com/authorize>; rel="authorization_endpoint",
<https://auth.example.com/token>; rel="token_endpoint"
```
#### 2.2 HTML Link Elements
```html
<link rel="authorization_endpoint" href="https://auth.example.com/authorize">
<link rel="token_endpoint" href="https://auth.example.com/token">
```
#### 2.3 IndieAuth Metadata (Optional)
```html
<link rel="indieauth-metadata" href="https://auth.example.com/.well-known/indieauth-metadata">
```
### Step 3: URL Resolution
All discovered URLs must be resolved relative to the profile URL:
- Absolute URL: Use as-is
- Relative URL: Resolve against profile URL
- Protocol-relative: Inherit profile URL protocol
## Token Verification Architecture
### The Problem
When Micropub receives a token, it needs to verify it. But with which endpoint?
### The Solution
```
┌─────────────────┐
│ Micropub Request│
│ Bearer: xxxxx │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Extract Token │
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ Determine User Identity │
│ (from token or cache) │
└────────┬────────────────┘
│
▼
┌──────────────────────┐
│ Discover Endpoints │
│ from User Profile │
└────────┬─────────────┘
│
▼
┌──────────────────────┐
│ Verify with │
│ Discovered Endpoint │
└────────┬─────────────┘
│
▼
┌──────────────────────┐
│ Validate Response │
│ - Check 'me' URL │
│ - Check scopes │
└──────────────────────┘
```
## Implementation Components
### 1. Endpoint Discovery Module
```python
class EndpointDiscovery:
"""
Discovers IndieAuth endpoints from profile URLs
"""
def discover(self, profile_url: str) -> Dict[str, str]:
"""
Discover endpoints from a profile URL
Returns:
{
'authorization_endpoint': 'https://...',
'token_endpoint': 'https://...',
'indieauth_metadata': 'https://...' # optional
}
"""
def parse_link_header(self, header: str) -> Dict[str, str]:
"""Parse HTTP Link header for endpoints"""
def extract_from_html(self, html: str, base_url: str) -> Dict[str, str]:
"""Extract endpoints from HTML link elements"""
def resolve_url(self, url: str, base: str) -> str:
"""Resolve potentially relative URL against base"""
```
### 2. Token Verification Module
```python
class TokenVerifier:
"""
Verifies tokens using discovered endpoints
"""
def __init__(self, discovery: EndpointDiscovery, cache: EndpointCache):
self.discovery = discovery
self.cache = cache
def verify(self, token: str, expected_me: str = None) -> TokenInfo:
"""
Verify a token using endpoint discovery
Args:
token: The bearer token to verify
expected_me: Optional expected 'me' URL
Returns:
TokenInfo with 'me', 'scope', 'client_id', etc.
"""
def introspect_token(self, token: str, endpoint: str) -> dict:
"""Call token endpoint to verify token"""
```
### 3. Caching Layer
```python
class EndpointCache:
"""
Caches discovered endpoints for performance
"""
def __init__(self, ttl: int = 3600):
self.endpoint_cache = {} # profile_url -> (endpoints, expiry)
self.token_cache = {} # token_hash -> (info, expiry)
self.ttl = ttl
def get_endpoints(self, profile_url: str) -> Optional[Dict[str, str]]:
"""Get cached endpoints if still valid"""
def store_endpoints(self, profile_url: str, endpoints: Dict[str, str]):
"""Cache discovered endpoints"""
def get_token_info(self, token_hash: str) -> Optional[TokenInfo]:
"""Get cached token verification if still valid"""
def store_token_info(self, token_hash: str, info: TokenInfo):
"""Cache token verification result"""
```
## Error Handling
### Discovery Failures
| Error | Cause | Response |
|-------|-------|----------|
| ProfileUnreachableError | Can't fetch profile URL | 503 Service Unavailable |
| NoEndpointsFoundError | No endpoints in profile | 400 Bad Request |
| InvalidEndpointError | Malformed endpoint URL | 500 Internal Server Error |
| TimeoutError | Discovery timeout | 504 Gateway Timeout |
### Verification Failures
| Error | Cause | Response |
|-------|-------|----------|
| TokenInvalidError | Token rejected by endpoint | 403 Forbidden |
| EndpointUnreachableError | Can't reach token endpoint | 503 Service Unavailable |
| ScopeMismatchError | Token lacks required scope | 403 Forbidden |
| MeMismatchError | Token 'me' doesn't match expected | 403 Forbidden |
## Security Considerations
### 1. HTTPS Enforcement
- Profile URLs SHOULD use HTTPS
- Discovered endpoints MUST use HTTPS
- Reject non-HTTPS endpoints in production
### 2. Redirect Limits
- Maximum 5 redirects when fetching profiles
- Prevent redirect loops
- Log suspicious redirect patterns
### 3. Cache Poisoning Prevention
- Validate discovered URLs are well-formed
- Don't cache error responses
- Clear cache on configuration changes
### 4. Token Security
- Never log tokens in plaintext
- Hash tokens before caching
- Use constant-time comparison for token hashes
## Performance Optimization
### Caching Strategy
```
┌─────────────────────────────────────┐
│ First Request │
│ Discovery: ~500ms │
│ Verification: ~200ms │
│ Total: ~700ms │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Subsequent Requests │
│ Cached Endpoints: ~1ms │
│ Cached Token: ~1ms │
│ Total: ~2ms │
└─────────────────────────────────────┘
```
### Cache Configuration
```ini
# Endpoint cache (user rarely changes provider)
ENDPOINT_CACHE_TTL=3600 # 1 hour
# Token cache (balance security and performance)
TOKEN_CACHE_TTL=300 # 5 minutes
# Cache sizes
MAX_ENDPOINT_CACHE_SIZE=1000
MAX_TOKEN_CACHE_SIZE=10000
```
## Migration Path
### From Incorrect Hardcoded Implementation
1. Remove hardcoded endpoint configuration
2. Implement discovery module
3. Update token verification to use discovery
4. Add caching layer
5. Update documentation
### Configuration Changes
Before (WRONG):
```ini
TOKEN_ENDPOINT=https://tokens.indieauth.com/token
AUTHORIZATION_ENDPOINT=https://indieauth.com/auth
```
After (CORRECT):
```ini
ADMIN_ME=https://admin.example.com/
# Endpoints discovered automatically from ADMIN_ME
```
## Testing Strategy
### Unit Tests
1. **Discovery Tests**
- Parse various Link header formats
- Extract from different HTML structures
- Handle malformed responses
- URL resolution edge cases
2. **Cache Tests**
- TTL expiration
- Cache invalidation
- Size limits
- Concurrent access
3. **Security Tests**
- HTTPS enforcement
- Redirect limit enforcement
- Cache poisoning attempts
### Integration Tests
1. **Real Provider Tests**
- Test against indieauth.com
- Test against indie-auth.com
- Test against self-hosted providers
2. **Network Condition Tests**
- Slow responses
- Timeouts
- Connection failures
- Partial responses
### End-to-End Tests
1. **Full Flow Tests**
- Discovery → Verification → Caching
- Multiple users with different providers
- Provider switching scenarios
## Monitoring and Debugging
### Metrics to Track
- Discovery success/failure rate
- Average discovery latency
- Cache hit ratio
- Token verification latency
- Endpoint availability
### Debug Logging
```python
# Discovery
DEBUG: Fetching profile URL: https://alice.example.com/
DEBUG: Found Link header: <https://auth.alice.net/token>; rel="token_endpoint"
DEBUG: Discovered token endpoint: https://auth.alice.net/token
# Verification
DEBUG: Verifying token for claimed identity: https://alice.example.com/
DEBUG: Using cached endpoint: https://auth.alice.net/token
DEBUG: Token verification successful, scopes: ['create', 'update']
# Caching
DEBUG: Caching endpoints for https://alice.example.com/ (TTL: 3600s)
DEBUG: Token verification cached (TTL: 300s)
```
## Common Issues and Solutions
### Issue 1: No Endpoints Found
**Symptom**: "No token endpoint found for user"
**Causes**:
- User hasn't set up IndieAuth on their profile
- Profile URL returns wrong Content-Type
- Link elements have typos
**Solution**:
- Provide clear error message
- Link to IndieAuth setup documentation
- Log details for debugging
### Issue 2: Verification Timeouts
**Symptom**: "Authorization server is unreachable"
**Causes**:
- Auth server is down
- Network issues
- Firewall blocking requests
**Solution**:
- Implement retries with backoff
- Cache successful verifications
- Provide status page for auth server health
### Issue 3: Cache Invalidation
**Symptom**: User changed provider but old one still used
**Causes**:
- Endpoints still cached
- TTL too long
**Solution**:
- Provide manual cache clear option
- Reduce TTL if needed
- Clear cache on errors
## Appendix: Example Discoveries
### Example 1: IndieAuth.com User
```html
<!-- https://user.example.com/ -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
```
### Example 2: Self-Hosted
```html
<!-- https://alice.example.com/ -->
<link rel="authorization_endpoint" href="https://alice.example.com/auth">
<link rel="token_endpoint" href="https://alice.example.com/token">
```
### Example 3: Link Headers
```
HTTP/1.1 200 OK
Link: <https://auth.provider.com/authorize>; rel="authorization_endpoint",
<https://auth.provider.com/token>; rel="token_endpoint"
Content-Type: text/html
<!-- No link elements needed in HTML -->
```
### Example 4: Relative URLs
```html
<!-- https://bob.example.org/ -->
<link rel="authorization_endpoint" href="/auth/authorize">
<link rel="token_endpoint" href="/auth/token">
<!-- Resolves to https://bob.example.org/auth/authorize -->
<!-- Resolves to https://bob.example.org/auth/token -->
```
---
**Document Version**: 1.0
**Created**: 2024-11-24
**Purpose**: Correct implementation of IndieAuth endpoint discovery
**Status**: Authoritative guide for implementation

155
docs/architecture/indieauth-identity-page.md
View File

@@ -1,155 +0,0 @@
# IndieAuth Identity Page Architecture
## Overview
An IndieAuth identity page serves as the authoritative source for a user's online identity in the IndieWeb ecosystem. This document defines the minimal requirements and best practices for creating a static HTML page that functions as an IndieAuth identity URL.
## Purpose
The identity page serves three critical functions:
1. **Authentication Endpoint Discovery** - Provides rel links to IndieAuth endpoints
2. **Identity Verification** - Contains h-card microformats with user information
3. **Social Proof** - Optional rel="me" links for identity consolidation
## Technical Requirements
### 1. HTML Structure
```
DOCTYPE html5
├── head
│ ├── meta charset="utf-8"
│ ├── meta viewport (responsive)
│ ├── title (user's name)
│ ├── rel="authorization_endpoint"
│ ├── rel="token_endpoint"
│ └── optional: rel="micropub"
└── body
└── h-card
├── p-name (full name)
├── u-url (identity URL)
├── u-photo (optional avatar)
└── rel="me" links (optional)
```
### 2. IndieAuth Discovery
The page MUST include these link elements in the `<head>`:
```html
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
```
These endpoints:
- **authorization_endpoint**: Handles the OAuth 2.0 authorization flow
- **token_endpoint**: Issues access tokens for API access
### 3. Microformats2 h-card
The h-card provides machine-readable identity information:
```html
<div class="h-card">
<h1 class="p-name">User Name</h1>
<a class="u-url" href="https://example.com" rel="me">https://example.com</a>
</div>
```
Required properties:
- `p-name`: The person's full name
- `u-url`: The canonical identity URL (must match the page URL)
Optional properties:
- `u-photo`: Avatar image URL
- `p-note`: Brief biography
- `u-email`: Contact email (consider privacy implications)
### 4. rel="me" Links
For identity consolidation and social proof:
```html
<a href="https://github.com/username" rel="me">GitHub</a>
```
Best practices:
- Only include links to profiles you control
- Ensure reciprocal rel="me" links where possible
- Use HTTPS URLs whenever available
## Security Considerations
### 1. HTTPS Requirement
- Identity URLs MUST use HTTPS
- All linked endpoints MUST use HTTPS
- Mixed content will break authentication flows
### 2. Content Security
- No inline JavaScript required or recommended
- Minimal inline CSS only if necessary
- No external dependencies for core functionality
### 3. Privacy
- Consider what information to make public
- Email addresses can attract spam
- Phone numbers should generally be avoided
## Testing Strategy
### 1. IndieAuth Validation
- Test with https://indielogin.com/
- Verify endpoint discovery works
- Complete a full authentication flow
### 2. Microformats Validation
- Use https://indiewebify.me/
- Verify h-card is properly parsed
- Check all properties are detected
### 3. HTML Validation
- Validate with W3C validator
- Ensure semantic HTML5 compliance
- Check accessibility basics
## Common Pitfalls
### 1. Missing or Wrong URLs
- Identity URL must be absolute and match the actual page URL
- Endpoints must be absolute URLs
- rel="me" links must be to HTTPS when available
### 2. Incorrect Microformats
- Missing required h-card properties
- Using old hCard format instead of h-card
- Nesting errors in microformat classes
### 3. Authentication Failures
- Using HTTP instead of HTTPS
- Incorrect or missing endpoint declarations
- Not including trailing slashes consistently
## Minimal Implementation Checklist
- [ ] HTML5 DOCTYPE declaration
- [ ] UTF-8 character encoding
- [ ] Viewport meta tag for mobile
- [ ] Authorization endpoint link
- [ ] Token endpoint link
- [ ] h-card with p-name
- [ ] h-card with u-url matching page URL
- [ ] All URLs use HTTPS
- [ ] No broken links or empty hrefs
- [ ] Valid HTML5 structure
## Reference Implementations
See `/docs/examples/identity-page.html` for a complete, working example that can be customized for any IndieAuth user.
## Standards References
- [IndieAuth Specification](https://www.w3.org/TR/indieauth/)
- [Microformats2 h-card](http://microformats.org/wiki/h-card)
- [rel="me" specification](https://microformats.org/wiki/rel-me)
- [IndieWeb Authentication](https://indieweb.org/authentication)

267
docs/architecture/indieauth-questions-answered.md
View File

@@ -1,267 +0,0 @@
# IndieAuth Implementation Questions - Answered
## Quick Reference
All architectural questions have been answered. This document provides the concrete guidance needed for implementation.
## Questions & Answers
### ✅ Q1: External Token Endpoint Response Format
**Answer**: Follow the IndieAuth spec exactly (W3C TR).
**Expected Response**:
```json
{
"me": "https://user.example.net/",
"client_id": "https://app.example.com/",
"scope": "create update delete"
}
```
**Error Responses**: HTTP 400, 401, or 403 for invalid tokens.
---
### ✅ Q2: HTML Discovery Headers
**Answer**: These are links users add to THEIR websites, not StarPunk.
**User's HTML** (on their personal domain):
```html
<link rel="authorization_endpoint" href="https://indielogin.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="https://your-starpunk.example.com/api/micropub">
```
**StarPunk's Role**: Discover these endpoints from the user's URL, don't generate them.
---
### ✅ Q3: Migration Strategy
**Architectural Decision**: Keep migration 002, document it as future-use.
**Action Items**:
1. Keep the migration file as-is
2. Add comment: "Tables created for future V2 internal provider support"
3. Don't use these tables in V1 (external verification only)
4. No impact on existing production databases
**Rationale**: Empty tables cause no harm, avoid migration complexity later.
---
### ✅ Q4: Error Handling
**Answer**: Show clear, informative error messages.
**Error Messages**:
- **Auth server down**: "Authorization server is unreachable. Please try again later."
- **Invalid token**: "Access token is invalid or expired. Please re-authorize."
- **Network error**: "Cannot connect to authorization server."
**HTTP Status Codes**:
- 401: No token provided
- 403: Invalid/expired token
- 503: Auth server unreachable
---
### ✅ Q5: Cache Revocation Delay
**Architectural Decision**: Use 5-minute cache with configuration options.
**Implementation**:
```python
# Default: 5-minute cache
MICROPUB_TOKEN_CACHE_TTL=300
MICROPUB_TOKEN_CACHE_ENABLED=true
# High security: disable cache
MICROPUB_TOKEN_CACHE_ENABLED=false
```
**Security Notes**:
- SHA256 hash tokens before caching
- Memory-only cache (not persisted)
- Document 5-minute delay in security guide
- Allow disabling for high-security needs
---
## Implementation Checklist
### Immediate Actions
1. **Remove Internal Provider Code**:
- Delete `/auth/authorize` endpoint
- Delete `/auth/token` endpoint
- Remove token issuance logic
- Remove authorization code generation
2. **Implement External Verification**:
```python
# Core verification function
def verify_micropub_token(bearer_token, expected_me):
# 1. Check cache (if enabled)
# 2. Discover token endpoint from expected_me
# 3. Verify with external endpoint
# 4. Cache result (if enabled)
# 5. Return validation result
```
3. **Add Configuration**:
```ini
# Required
ADMIN_ME=https://user.example.com
# Optional (with defaults)
MICROPUB_TOKEN_CACHE_ENABLED=true
MICROPUB_TOKEN_CACHE_TTL=300
```
4. **Update Error Handling**:
```python
try:
response = httpx.get(endpoint, timeout=5.0)
except httpx.TimeoutError:
return error(503, "Authorization server is unreachable")
```
---
## Code Examples
### Token Verification
```python
def verify_token(bearer_token: str, token_endpoint: str, expected_me: str) -> Optional[dict]:
"""Verify token with external endpoint"""
try:
response = httpx.get(
token_endpoint,
headers={'Authorization': f'Bearer {bearer_token}'},
timeout=5.0
)
if response.status_code == 200:
data = response.json()
if data.get('me') == expected_me and 'create' in data.get('scope', ''):
return data
return None
except httpx.TimeoutError:
raise TokenEndpointError("Authorization server is unreachable")
```
### Endpoint Discovery
```python
def discover_token_endpoint(me_url: str) -> str:
"""Discover token endpoint from user's URL"""
response = httpx.get(me_url)
# 1. Check HTTP Link header
if link := parse_link_header(response.headers.get('Link'), 'token_endpoint'):
return urljoin(me_url, link)
# 2. Check HTML <link> tags
if 'text/html' in response.headers.get('content-type', ''):
if link := parse_html_link(response.text, 'token_endpoint'):
return urljoin(me_url, link)
raise DiscoveryError(f"No token endpoint found at {me_url}")
```
### Micropub Endpoint
```python
@app.route('/api/micropub', methods=['POST'])
def micropub_endpoint():
# Extract token
auth = request.headers.get('Authorization', '')
if not auth.startswith('Bearer '):
return {'error': 'unauthorized'}, 401
token = auth[7:] # Remove "Bearer "
# Verify token
try:
token_info = verify_micropub_token(token, app.config['ADMIN_ME'])
if not token_info:
return {'error': 'forbidden'}, 403
except TokenEndpointError as e:
return {'error': 'temporarily_unavailable', 'error_description': str(e)}, 503
# Process Micropub request
# ... create note ...
return '', 201, {'Location': note_url}
```
---
## Testing Guide
### Manual Testing
1. Configure your domain with IndieAuth links
2. Set ADMIN_ME in StarPunk config
3. Use Quill (https://quill.p3k.io) to test posting
4. Verify token caching works (check logs)
5. Test with auth server down (block network)
### Automated Tests
```python
def test_token_verification():
# Mock external token endpoint
with responses.RequestsMock() as rsps:
rsps.add(responses.GET, 'https://tokens.example.com/token',
json={'me': 'https://user.com', 'scope': 'create'})
result = verify_token('test-token', 'https://tokens.example.com/token', 'https://user.com')
assert result['me'] == 'https://user.com'
def test_auth_server_unreachable():
# Mock timeout
with pytest.raises(TokenEndpointError, match="unreachable"):
verify_token('test-token', 'https://timeout.example.com/token', 'https://user.com')
```
---
## User Documentation Template
### For Users: Setting Up IndieAuth
1. **Add to your website's HTML**:
```html
<link rel="authorization_endpoint" href="https://indielogin.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="[YOUR-STARPUNK-URL]/api/micropub">
```
2. **Configure StarPunk**:
```ini
ADMIN_ME=https://your-website.com
```
3. **Test with a Micropub client**:
- Visit https://quill.p3k.io
- Enter your website URL
- Authorize and post!
---
## Summary
All architectural questions have been answered:
1. **Token Format**: Follow IndieAuth spec exactly
2. **HTML Headers**: Users configure their own domains
3. **Migration**: Keep tables for future use
4. **Errors**: Clear messages about connectivity
5. **Cache**: 5-minute TTL with disable option
The implementation path is clear: remove internal provider code, implement external verification with caching, and provide good error messages. This aligns with StarPunk's philosophy of minimal code and IndieWeb principles.
---
**Ready for Implementation**: All questions answered, examples provided, architecture documented.

230
docs/architecture/indieauth-removal-architectural-review.md
View File

@@ -1,230 +0,0 @@
# Architectural Review: IndieAuth Authorization Server Removal
**Date**: 2025-11-24
**Reviewer**: StarPunk Architect
**Implementation Version**: 1.0.0-rc.4
**Review Type**: Final Architectural Assessment
## Executive Summary
**Overall Quality Rating**: **EXCELLENT**
The IndieAuth authorization server removal implementation is exemplary work that fully achieves its architectural goals. The implementation successfully removes ~500 lines of complex security code while maintaining full IndieAuth compliance through external delegation. All acceptance criteria have been met, tests are passing at 100%, and the approach follows our core philosophy of "every line of code must justify its existence."
**Approval Status**: **READY TO MERGE** - No blocking issues found
## 1. Implementation Completeness Assessment
### Phase Completion Status ✅
All four phases completed successfully:
| Phase | Description | Status | Verification |
|-------|-------------|--------|--------------|
| Phase 1 | Remove Authorization Endpoint | ✅ Complete | Endpoint deleted, tests removed |
| Phase 2 | Remove Token Issuance | ✅ Complete | Token endpoint removed |
| Phase 3 | Remove Token Storage | ✅ Complete | Tables dropped via migration |
| Phase 4 | External Token Verification | ✅ Complete | New module working |
### Acceptance Criteria Validation ✅
**Must Work:**
- ✅ Admin authentication via IndieLogin.com (unchanged)
- ✅ Micropub token verification via external endpoint
- ✅ Proper error responses for invalid tokens
- ✅ HTML discovery links for IndieAuth endpoints (deferred to template work)
**Must Not Exist:**
- ✅ No authorization endpoint (`/auth/authorization`)
- ✅ No token endpoint (`/auth/token`)
- ✅ No authorization consent UI
- ✅ No token storage in database
- ✅ No PKCE implementation (for server-side)
## 2. Code Quality Analysis
### External Token Verification Module (`auth_external.py`)
**Strengths:**
- Clean, focused implementation (154 lines)
- Proper error handling for all network scenarios
- Clear logging at appropriate levels
- Secure token handling (no plaintext storage)
- Comprehensive docstrings
**Security Measures:**
- ✅ Timeout protection (5 seconds)
- ✅ Bearer token never logged
- ✅ Validates `me` field against `ADMIN_ME`
- ✅ Graceful degradation on failure
- ✅ No token storage or caching (yet)
**Minor Observations:**
- No token caching implemented (explicitly deferred per ADR-030)
- Consider rate limiting for token verification endpoints in future
### Migration Implementation
**Migration 003** (Remove code_verifier):
- Correctly handles SQLite's lack of DROP COLUMN
- Preserves data integrity during table recreation
- Maintains indexes appropriately
**Migration 004** (Drop token tables):
- Simple, clean DROP statements
- Appropriate use of IF EXISTS
- Clear documentation of purpose
## 3. Architectural Compliance
### ADR-050 Compliance ✅
The implementation perfectly follows the removal decision:
- All specified files deleted
- All specified modules removed
- Database tables dropped as planned
- External verification implemented as specified
### ADR-030 Compliance ✅
External verification architecture implemented correctly:
- Token verification via GET request to external endpoint
- Proper timeout handling
- Correct error responses
- No token caching (as specified for V1)
### ADR-051 Test Strategy ✅
Test approach followed successfully:
- Tests fixed immediately after breaking changes
- Mocking used appropriately for external services
- 100% test pass rate achieved
### IndieAuth Specification ✅
Implementation maintains full compliance:
- Bearer token authentication preserved
- Proper token introspection flow
- OAuth 2.0 error responses
- Scope validation maintained
## 4. Security Analysis
### Positive Security Changes
1. **Reduced Attack Surface**: No token generation/storage code to exploit
2. **No Cryptographic Burden**: External providers handle token security
3. **No Token Leakage Risk**: No tokens stored locally
4. **Simplified Security Model**: Only verify, never issue
### Security Considerations
**Good Practices Observed:**
- Token never logged in plaintext
- Timeout protection prevents hanging
- Clear error messages without leaking information
- Validates token ownership (`me` field check)
**Future Considerations:**
- Rate limiting for verification requests
- Circuit breaker for external provider failures
- Optional token response caching (with security analysis)
## 5. Test Coverage Analysis
### Test Quality Assessment
- **501/501 tests passing** - Complete success
- **Migration tests updated** - Properly handles schema changes
- **Micropub tests rewritten** - Clean mocking approach
- **No test debt** - All broken tests fixed immediately
### Mocking Approach
The use of `unittest.mock.patch` for external verification is appropriate:
- Isolates tests from external dependencies
- Provides predictable test scenarios
- Covers success and failure cases
## 6. Documentation Quality
### Comprehensive Documentation ✅
- **Implementation Report**: Exceptionally detailed (386 lines)
- **CHANGELOG**: Complete with migration guide
- **Code Comments**: Clear and helpful
- **ADRs**: Proper architectural decisions documented
### Minor Documentation Gaps
- README update pending (acknowledged in report)
- User migration guide could be expanded
- HTML discovery links implementation deferred
## 7. Production Readiness
### Breaking Changes Documentation ✅
Clearly documented:
- Old tokens become invalid
- New configuration required
- Migration steps provided
- Impact on Micropub clients explained
### Configuration Requirements ✅
- `TOKEN_ENDPOINT` required and validated
- `ADMIN_ME` already required
- Clear error messages if misconfigured
### Rollback Strategy
While not implemented, the report acknowledges:
- Git revert possible
- Database migrations reversible
- Clear rollback path exists
## 8. Technical Debt Analysis
### Debt Eliminated
- ~500 lines of complex security code removed
- 2 database tables eliminated
- 38 tests removed
- PKCE complexity gone
- Token lifecycle management removed
### Debt Deferred (Appropriately)
- Token caching (optional optimization)
- Rate limiting (future enhancement)
- Circuit breaker pattern (production hardening)
## 9. Issues and Concerns
### No Critical Issues ✅
### Minor Observations (Non-Blocking)
1. **Empty Migration Tables**: The decision to keep empty tables from migration 002 seems inconsistent with removal goals, but ADR-030 justifies this adequately.
2. **HTML Discovery Links**: Not implemented in this phase but acknowledged for future template work.
3. **Network Dependency**: External provider availability becomes critical - consider monitoring in production.
## 10. Recommendations
### For Immediate Deployment
1. **Configuration Validation**: Add startup check for `TOKEN_ENDPOINT` configuration
2. **Monitoring**: Set up alerts for external provider availability
3. **Documentation**: Update README before release
### For Future Iterations
1. **Token Caching**: Implement once performance baseline established
2. **Rate Limiting**: Add protection against verification abuse
3. **Circuit Breaker**: Implement for external provider resilience
4. **Health Check Endpoint**: Monitor external provider connectivity
## Conclusion
This implementation represents exceptional architectural work that successfully achieves all stated goals. The phased approach, comprehensive testing, and detailed documentation demonstrate professional engineering practices.
The removal of ~500 lines of security-critical code in favor of external delegation is a textbook example of architectural simplification. The implementation maintains full standards compliance while dramatically reducing complexity.
**Architectural Assessment**: This is exactly the kind of thoughtful, principled simplification that StarPunk needs. The implementation not only meets requirements but exceeds expectations in documentation and testing thoroughness.
**Final Verdict**: **APPROVED FOR PRODUCTION**
The implementation is ready for deployment as version 1.0.0-rc.4. The breaking changes are well-documented, the migration path is clear, and the security posture is improved.
---
**Review Completed**: 2025-11-24
**Reviewed By**: StarPunk Architecture Team
**Next Action**: Deploy to production with monitoring

469
docs/architecture/indieauth-removal-implementation-guide.md
View File

@@ -1,469 +0,0 @@
# IndieAuth Provider Removal - Implementation Guide
## Executive Summary
This document provides complete architectural guidance for removing the internal IndieAuth provider functionality from StarPunk while maintaining external IndieAuth integration for token verification. All questions have been answered based on the IndieAuth specification and architectural principles.
## Answers to Critical Questions
### Q1: External Token Endpoint Response Format ✓
**Answer**: The user is correct. The IndieAuth specification (W3C) defines exact response formats.
**Token Verification Response** (per spec section 6.3.4):
```json
{
"me": "https://user.example.net/",
"client_id": "https://app.example.com/",
"scope": "create update delete"
}
```
**Key Points**:
- Response is JSON with required fields: `me`, `client_id`, `scope`
- Additional fields may be present but should be ignored
- On invalid tokens: return HTTP 400, 401, or 403
- The `me` field MUST match the configured admin identity
### Q2: HTML Discovery Headers ✓
**Answer**: The user refers to how users configure their personal domains to point to IndieAuth providers.
**What Users Add to Their HTML** (per spec sections 4.1, 5.1, 6.1):
```html
<!-- In the <head> of the user's personal website -->
<link rel="authorization_endpoint" href="https://indielogin.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="https://your-starpunk.example.com/api/micropub">
```
**Key Points**:
- These links go on the USER'S personal website, NOT in StarPunk
- StarPunk doesn't generate these - it discovers them from user URLs
- Users choose their own authorization/token providers
- StarPunk only needs to know the user's identity URL (configured as ADMIN_ME)
### Q3: Migration Strategy - ARCHITECTURAL DECISION
**Answer**: Keep migration 002 but clarify its purpose.
**Decision**:
1. **Keep Migration 002** - The tables are actually needed for V2 features
2. **Rename/Document** - Clarify that these tables are for future internal provider support
3. **No Production Impact** - Tables remain empty in V1, cause no harm
**Rationale**:
- The `tokens` table with secure hash storage is good future-proofing
- The `authorization_codes` table will be needed if V2 adds internal provider
- Empty tables have zero performance impact
- Removing and re-adding later creates unnecessary migration complexity
- Document clearly that these are unused in V1
**Implementation**:
```sql
-- Add comment to migration 002
-- These tables are created for future V2 internal provider support
-- In V1, StarPunk only verifies external tokens via HTTP, not database
```
### Q4: Error Handling ✓
**Answer**: The user provided clear guidance - display informative error messages.
**Error Handling Strategy**:
```python
def verify_token(bearer_token, token_endpoint):
try:
response = httpx.get(
token_endpoint,
headers={'Authorization': f'Bearer {bearer_token}'},
timeout=5.0
)
if response.status_code == 200:
return response.json()
elif response.status_code in [400, 401, 403]:
return None # Invalid token
else:
raise TokenEndpointError(f"Unexpected status: {response.status_code}")
except httpx.TimeoutError:
# User's requirement: show auth server unreachable
raise TokenEndpointError("Authorization server is unreachable")
except httpx.RequestError as e:
raise TokenEndpointError(f"Cannot connect to authorization server: {e}")
```
**User-Facing Errors**:
- **Auth Server Down**: "Authorization server is unreachable. Please try again later."
- **Invalid Token**: "Access token is invalid or expired. Please re-authorize."
- **Network Error**: "Cannot connect to authorization server. Check your network connection."
### Q5: Cache Revocation Delay - ARCHITECTURAL DECISION
**Answer**: The 5-minute cache is acceptable with proper configuration.
**Decision**: Use configurable short-lived cache with bypass option.
**Architecture**:
```python
class TokenCache:
"""
Simple time-based token cache with security considerations
Configuration:
- MICROPUB_TOKEN_CACHE_TTL: 300 (5 minutes default)
- MICROPUB_TOKEN_CACHE_ENABLED: true (can disable for high-security)
"""
def __init__(self, ttl=300):
self.ttl = ttl
self.cache = {} # token_hash -> (token_info, expiry_time)
def get(self, token):
"""Get cached token if valid and not expired"""
token_hash = hashlib.sha256(token.encode()).hexdigest()
if token_hash in self.cache:
info, expiry = self.cache[token_hash]
if time.time() < expiry:
return info
del self.cache[token_hash]
return None
def set(self, token, info):
"""Cache token info with TTL"""
token_hash = hashlib.sha256(token.encode()).hexdigest()
expiry = time.time() + self.ttl
self.cache[token_hash] = (info, expiry)
```
**Security Analysis**:
- **Risk**: Revoked tokens remain valid for up to 5 minutes
- **Mitigation**: Short TTL limits exposure window
- **Trade-off**: Performance vs immediate revocation
- **Best Practice**: Document the delay in security considerations
**Configuration Options**:
```ini
# For high-security environments
MICROPUB_TOKEN_CACHE_ENABLED=false # Disable cache entirely
# For normal use (recommended)
MICROPUB_TOKEN_CACHE_TTL=300 # 5 minutes
# For development/testing
MICROPUB_TOKEN_CACHE_TTL=60 # 1 minute
```
## Complete Implementation Architecture
### 1. System Boundaries
```
┌─────────────────────────────────────────────────────────────┐
│ StarPunk V1 Scope │
│ │
│ IN SCOPE: │
│ ✓ Token verification (external) │
│ ✓ Micropub endpoint │
│ ✓ Bearer token extraction │
│ ✓ Endpoint discovery │
│ ✓ Admin session auth (IndieLogin) │
│ │
│ OUT OF SCOPE: │
│ ✗ Authorization endpoint (user provides) │
│ ✗ Token endpoint (user provides) │
│ ✗ Token issuance (external only) │
│ ✗ User registration │
│ ✗ Identity management │
└─────────────────────────────────────────────────────────────┘
```
### 2. Component Design
#### 2.1 Token Verifier Component
```python
# starpunk/indieauth/verifier.py
class ExternalTokenVerifier:
"""
Verifies tokens with external IndieAuth providers
Never stores tokens, only verifies them
"""
def __init__(self, cache_ttl=300, cache_enabled=True):
self.cache = TokenCache(ttl=cache_ttl) if cache_enabled else None
self.http_client = httpx.Client(timeout=5.0)
def verify(self, bearer_token: str, expected_me: str) -> Optional[TokenInfo]:
"""
Verify bearer token with external token endpoint
Returns:
TokenInfo if valid, None if invalid
Raises:
TokenEndpointError if endpoint unreachable
"""
# Check cache first
if self.cache:
cached = self.cache.get(bearer_token)
if cached and cached.me == expected_me:
return cached
# Discover token endpoint from user's URL
token_endpoint = self.discover_token_endpoint(expected_me)
# Verify with external endpoint
token_info = self.verify_with_endpoint(
bearer_token,
token_endpoint,
expected_me
)
# Cache if valid
if token_info and self.cache:
self.cache.set(bearer_token, token_info)
return token_info
```
#### 2.2 Endpoint Discovery Component
```python
# starpunk/indieauth/discovery.py
class EndpointDiscovery:
"""
Discovers IndieAuth endpoints from user URLs
Implements full spec compliance for discovery
"""
def discover_token_endpoint(self, me_url: str) -> str:
"""
Discover token endpoint from profile URL
Priority order (per spec):
1. HTTP Link header
2. HTML <link> element
3. IndieAuth metadata endpoint
"""
response = httpx.get(me_url, follow_redirects=True)
# 1. Check HTTP Link header (highest priority)
link_header = response.headers.get('Link', '')
if endpoint := self.parse_link_header(link_header, 'token_endpoint'):
return urljoin(me_url, endpoint)
# 2. Check HTML if content-type is HTML
if 'text/html' in response.headers.get('content-type', ''):
if endpoint := self.parse_html_links(response.text, 'token_endpoint'):
return urljoin(me_url, endpoint)
# 3. Check for indieauth-metadata endpoint
if metadata_url := self.find_metadata_endpoint(response):
metadata = httpx.get(metadata_url).json()
if endpoint := metadata.get('token_endpoint'):
return endpoint
raise DiscoveryError(f"No token endpoint found at {me_url}")
```
### 3. Database Schema (V1 - Unused but Present)
```sql
-- These tables exist but are NOT USED in V1
-- They are created for future V2 internal provider support
-- Document this clearly in the migration
-- tokens table: For future internal token storage
-- authorization_codes table: For future OAuth flow support
-- V1 uses only external token verification via HTTP
-- No database queries for token validation in V1
```
### 4. API Contract
#### Micropub Endpoint
```yaml
endpoint: /api/micropub
methods: [POST]
authentication: Bearer token
request:
headers:
Authorization: "Bearer {access_token}"
Content-Type: "application/x-www-form-urlencoded" or "application/json"
body: |
Micropub create request per spec
response:
success:
status: 201
headers:
Location: "https://starpunk.example.com/notes/{id}"
unauthorized:
status: 401
body:
error: "unauthorized"
error_description: "No access token provided"
forbidden:
status: 403
body:
error: "forbidden"
error_description: "Invalid or expired access token"
server_error:
status: 503
body:
error: "temporarily_unavailable"
error_description: "Authorization server is unreachable"
```
### 5. Configuration
```ini
# config.ini or environment variables
# User's identity URL (required)
ADMIN_ME=https://user.example.com
# Token cache settings (optional)
MICROPUB_TOKEN_CACHE_ENABLED=true
MICROPUB_TOKEN_CACHE_TTL=300
# HTTP client settings (optional)
MICROPUB_HTTP_TIMEOUT=5.0
MICROPUB_MAX_RETRIES=1
```
### 6. Security Considerations
#### Token Handling
- **Never store plain tokens** - Only cache with SHA256 hashes
- **Always use HTTPS** - Token verification must use TLS
- **Validate 'me' field** - Must match configured admin identity
- **Check scope** - Ensure 'create' scope for Micropub posts
#### Cache Security
- **Short TTL** - 5 minutes maximum to limit revocation delay
- **Hash tokens** - Even in cache, never store plain tokens
- **Memory only** - Don't persist cache to disk
- **Config option** - Allow disabling cache in high-security environments
#### Error Messages
- **Don't leak tokens** - Never include tokens in error messages
- **Generic client errors** - Don't reveal why authentication failed
- **Specific server errors** - Help users understand connectivity issues
### 7. Testing Strategy
#### Unit Tests
```python
def test_token_verification():
"""Test external token verification"""
# Mock HTTP client
# Test valid token response
# Test invalid token response
# Test network errors
# Test timeout handling
def test_endpoint_discovery():
"""Test endpoint discovery from URLs"""
# Test HTTP Link header discovery
# Test HTML link element discovery
# Test metadata endpoint discovery
# Test relative URL resolution
def test_cache_behavior():
"""Test token cache"""
# Test cache hit
# Test cache miss
# Test TTL expiry
# Test cache disabled
```
#### Integration Tests
```python
def test_micropub_with_valid_token():
"""Test full Micropub flow with valid token"""
# Mock token endpoint
# Send Micropub request
# Verify note created
# Check Location header
def test_micropub_with_invalid_token():
"""Test Micropub rejection with invalid token"""
# Mock token endpoint to return 401
# Send Micropub request
# Verify 403 response
# Verify no note created
def test_micropub_with_unreachable_auth_server():
"""Test handling of unreachable auth server"""
# Mock network timeout
# Send Micropub request
# Verify 503 response
# Verify error message
```
### 8. Implementation Checklist
#### Phase 1: Remove Internal Provider
- [ ] Remove /auth/authorize endpoint
- [ ] Remove /auth/token endpoint
- [ ] Remove internal token issuance logic
- [ ] Remove authorization code generation
- [ ] Update tests to not expect these endpoints
#### Phase 2: Implement External Verification
- [ ] Create ExternalTokenVerifier class
- [ ] Implement endpoint discovery
- [ ] Add token cache with TTL
- [ ] Handle network errors gracefully
- [ ] Add configuration options
#### Phase 3: Update Documentation
- [ ] Update API documentation
- [ ] Create user setup guide
- [ ] Document security considerations
- [ ] Update architecture diagrams
- [ ] Add troubleshooting guide
#### Phase 4: Testing & Validation
- [ ] Test with IndieLogin.com
- [ ] Test with tokens.indieauth.com
- [ ] Test with real Micropub clients (Quill, Indigenous)
- [ ] Verify error handling
- [ ] Load test token verification
## Migration Path
### For Existing Installations
1. **Database**: No action needed (tables remain but unused)
2. **Configuration**: Add ADMIN_ME setting
3. **Users**: Provide setup instructions for their domains
4. **Testing**: Verify external token verification works
### For New Installations
1. **Fresh start**: Full V1 external-only implementation
2. **Simple setup**: Just configure ADMIN_ME
3. **User guide**: How to configure their domain for IndieAuth
## Conclusion
This architecture provides a clean, secure, and standards-compliant implementation of external IndieAuth token verification. The design follows the principle of "every line of code must justify its existence" by removing unnecessary internal provider complexity while maintaining full Micropub support.
The key insight is that StarPunk is a **Micropub server**, not an **authorization server**. This separation of concerns aligns perfectly with IndieWeb principles and keeps the codebase minimal and focused.
---
**Document Version**: 1.0
**Created**: 2024-11-24
**Author**: StarPunk Architecture Team
**Status**: Final

593
docs/architecture/indieauth-removal-phases.md
View File

@@ -1,593 +0,0 @@
# IndieAuth Removal: Phased Implementation Guide
## Overview
This document breaks down the IndieAuth server removal into testable phases, each with clear acceptance criteria and verification steps.
## Phase 1: Remove Authorization Server (4 hours)
### Objective
Remove the authorization endpoint and consent UI while keeping the system functional.
### Tasks
#### 1.1 Remove Authorization UI (30 min)
```bash
# Delete consent template
rm /home/phil/Projects/starpunk/templates/auth/authorize.html
# Verify
ls /home/phil/Projects/starpunk/templates/auth/
# Should be empty or not exist
```
#### 1.2 Remove Authorization Endpoint (1 hour)
In `/home/phil/Projects/starpunk/starpunk/routes/auth.py`:
- Delete `authorization_endpoint()` function
- Delete related imports from `starpunk.tokens`
- Keep admin auth routes intact
#### 1.3 Remove Authorization Tests (30 min)
```bash
# Delete test files
rm /home/phil/Projects/starpunk/tests/test_routes_authorization.py
rm /home/phil/Projects/starpunk/tests/test_auth_pkce.py
```
#### 1.4 Remove PKCE Implementation (1 hour)
From `/home/phil/Projects/starpunk/starpunk/auth.py`:
- Remove `generate_code_verifier()`
- Remove `calculate_code_challenge()`
- Remove PKCE validation logic
- Keep session management functions
#### 1.5 Update Route Registration (30 min)
Ensure no references to `/auth/authorization` in:
- URL route definitions
- Template URL generation
- Documentation
### Acceptance Criteria
✅ **Server Starts Successfully**
```bash
uv run python -m starpunk
# No import errors or missing route errors
```
✅ **Admin Login Works**
```bash
# Navigate to /admin/login
# Can still authenticate via IndieLogin.com
# Session created successfully
```
✅ **No Authorization Endpoint**
```bash
curl -I http://localhost:5000/auth/authorization
# Should return 404 Not Found
```
✅ **Tests Pass (Remaining)**
```bash
uv run pytest tests/ -k "not authorization and not pkce"
# All remaining tests pass
```
### Verification Commands
```bash
# Check for orphaned imports
grep -r "authorization_endpoint" /home/phil/Projects/starpunk/
# Should return nothing
# Check for PKCE references
grep -r "code_challenge\|code_verifier" /home/phil/Projects/starpunk/
# Should only appear in migration files or comments
```
---
## Phase 2: Remove Token Issuance (3 hours)
### Objective
Remove token generation and issuance while keeping token verification temporarily.
### Tasks
#### 2.1 Remove Token Endpoint (1 hour)
In `/home/phil/Projects/starpunk/starpunk/routes/auth.py`:
- Delete `token_endpoint()` function
- Remove token-related imports
#### 2.2 Remove Token Generation (1 hour)
In `/home/phil/Projects/starpunk/starpunk/tokens.py`:
- Remove `create_access_token()`
- Remove `create_authorization_code()`
- Remove `exchange_authorization_code()`
- Keep `verify_token()` temporarily (will modify in Phase 4)
#### 2.3 Remove Token Tests (30 min)
```bash
rm /home/phil/Projects/starpunk/tests/test_routes_token.py
rm /home/phil/Projects/starpunk/tests/test_tokens.py
```
#### 2.4 Clean Up Exceptions (30 min)
Remove custom exceptions:
- `InvalidAuthorizationCodeError`
- `ExpiredAuthorizationCodeError`
- Update error handling to use generic exceptions
### Acceptance Criteria
✅ **No Token Endpoint**
```bash
curl -I http://localhost:5000/auth/token
# Should return 404 Not Found
```
✅ **No Token Generation Code**
```bash
grep -r "create_access_token\|create_authorization_code" /home/phil/Projects/starpunk/starpunk/
# Should return nothing (except in comments)
```
✅ **Server Still Runs**
```bash
uv run python -m starpunk
# No import errors
```
✅ **Micropub Temporarily Broken (Expected)**
```bash
# This is expected and will be fixed in Phase 4
# Document that Micropub is non-functional during migration
```
### Verification Commands
```bash
# Check for token generation references
grep -r "generate_token\|issue_token" /home/phil/Projects/starpunk/
# Should be empty
# Verify exception cleanup
grep -r "InvalidAuthorizationCodeError" /home/phil/Projects/starpunk/
# Should be empty
```
---
## Phase 3: Database Schema Simplification (2 hours)
### Objective
Remove authorization and token tables from the database.
### Tasks
#### 3.1 Create Removal Migration (30 min)
Create `/home/phil/Projects/starpunk/migrations/003_remove_indieauth_tables.sql`:
```sql
-- Remove IndieAuth server tables
BEGIN TRANSACTION;
-- Drop dependent objects first
DROP INDEX IF EXISTS idx_tokens_hash;
DROP INDEX IF EXISTS idx_tokens_user_id;
DROP INDEX IF EXISTS idx_tokens_client_id;
DROP INDEX IF EXISTS idx_auth_codes_code;
DROP INDEX IF EXISTS idx_auth_codes_user_id;
-- Drop tables
DROP TABLE IF EXISTS tokens CASCADE;
DROP TABLE IF EXISTS authorization_codes CASCADE;
-- Clean up any orphaned sequences
DROP SEQUENCE IF EXISTS tokens_id_seq;
DROP SEQUENCE IF EXISTS authorization_codes_id_seq;
COMMIT;
```
#### 3.2 Run Migration (30 min)
```bash
# Backup database first
pg_dump $DATABASE_URL > backup_before_removal.sql
# Run migration
uv run python -m starpunk.migrate
```
#### 3.3 Update Schema Documentation (30 min)
Update `/home/phil/Projects/starpunk/docs/design/database-schema.md`:
- Remove token table documentation
- Remove authorization_codes table documentation
- Update ER diagram
#### 3.4 Remove Old Migration (30 min)
```bash
# Archive old migration
mv /home/phil/Projects/starpunk/migrations/002_secure_tokens_and_authorization_codes.sql \
/home/phil/Projects/starpunk/migrations/archive/
```
### Acceptance Criteria
✅ **Tables Removed**
```sql
-- Connect to database and verify
\dt
-- Should NOT list 'tokens' or 'authorization_codes'
```
✅ **No Foreign Key Errors**
```sql
-- Check for orphaned constraints
SELECT conname FROM pg_constraint
WHERE conname LIKE '%token%' OR conname LIKE '%auth%';
-- Should return minimal results (only auth_state related)
```
✅ **Application Starts**
```bash
uv run python -m starpunk
# No database connection errors
```
✅ **Admin Functions Work**
- Can log in
- Can create posts
- Sessions persist
### Rollback Plan
```bash
# If issues arise
psql $DATABASE_URL < backup_before_removal.sql
# Re-run old migration
psql $DATABASE_URL < /home/phil/Projects/starpunk/migrations/archive/002_secure_tokens_and_authorization_codes.sql
```
---
## Phase 4: External Token Verification (4 hours)
### Objective
Replace internal token verification with external provider verification.
### Tasks
#### 4.1 Implement External Verification (2 hours)
Create new verification in `/home/phil/Projects/starpunk/starpunk/micropub.py`:
```python
import hashlib
import httpx
from typing import Optional, Dict, Any
from flask import current_app
# Simple in-memory cache
_token_cache = {}
def verify_token(bearer_token: str) -> Optional[Dict[str, Any]]:
"""Verify token with external endpoint"""
# Check cache
token_hash = hashlib.sha256(bearer_token.encode()).hexdigest()
if token_hash in _token_cache:
data, expiry = _token_cache[token_hash]
if time.time() < expiry:
return data
del _token_cache[token_hash]
# Verify with external endpoint
endpoint = current_app.config.get('TOKEN_ENDPOINT')
if not endpoint:
return None
try:
response = httpx.get(
endpoint,
headers={'Authorization': f'Bearer {bearer_token}'},
timeout=5.0
)
if response.status_code != 200:
return None
data = response.json()
# Validate response
if data.get('me') != current_app.config.get('ADMIN_ME'):
return None
if 'create' not in data.get('scope', '').split():
return None
# Cache for 5 minutes
_token_cache[token_hash] = (data, time.time() + 300)
return data
except Exception as e:
current_app.logger.error(f"Token verification failed: {e}")
return None
```
#### 4.2 Update Configuration (30 min)
In `/home/phil/Projects/starpunk/starpunk/config.py`:
```python
# External IndieAuth settings
TOKEN_ENDPOINT = os.getenv('TOKEN_ENDPOINT', 'https://tokens.indieauth.com/token')
ADMIN_ME = os.getenv('ADMIN_ME') # Required
# Validate configuration
if not ADMIN_ME:
raise ValueError("ADMIN_ME must be configured")
```
#### 4.3 Remove Old Token Module (30 min)
```bash
rm /home/phil/Projects/starpunk/starpunk/tokens.py
```
#### 4.4 Update Tests (1 hour)
Update `/home/phil/Projects/starpunk/tests/test_micropub.py`:
```python
@patch('starpunk.micropub.httpx.get')
def test_external_token_verification(mock_get):
mock_response = Mock()
mock_response.status_code = 200
mock_response.json.return_value = {
'me': 'https://example.com',
'scope': 'create update'
}
mock_get.return_value = mock_response
# Test verification
result = verify_token('test-token')
assert result is not None
assert result['me'] == 'https://example.com'
```
### Acceptance Criteria
✅ **External Verification Works**
```bash
# With a valid token from tokens.indieauth.com
curl -X POST http://localhost:5000/micropub \
-H "Authorization: Bearer VALID_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type": ["h-entry"], "properties": {"content": ["Test"]}}'
# Should return 201 Created
```
✅ **Invalid Tokens Rejected**
```bash
curl -X POST http://localhost:5000/micropub \
-H "Authorization: Bearer INVALID_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type": ["h-entry"], "properties": {"content": ["Test"]}}'
# Should return 403 Forbidden
```
✅ **Token Caching Works**
```python
# In test environment
token = "test-token"
result1 = verify_token(token) # External call
result2 = verify_token(token) # Should use cache
# Verify only one external call made
```
✅ **Configuration Validated**
```bash
# Without ADMIN_ME set
unset ADMIN_ME
uv run python -m starpunk
# Should fail with clear error message
```
### Performance Verification
```bash
# Measure token verification time
time curl -X GET http://localhost:5000/micropub \
-H "Authorization: Bearer VALID_TOKEN" \
-w "\nTime: %{time_total}s\n"
# First call: <500ms
# Cached calls: <50ms
```
---
## Phase 5: Documentation and Discovery (2 hours)
### Objective
Update all documentation and add proper IndieAuth discovery headers.
### Tasks
#### 5.1 Add Discovery Links (30 min)
In `/home/phil/Projects/starpunk/templates/base.html`:
```html
<head>
<!-- Existing head content -->
<!-- IndieAuth Discovery -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="{{ config.TOKEN_ENDPOINT }}">
<link rel="micropub" href="{{ url_for('micropub.micropub_endpoint', _external=True) }}">
</head>
```
#### 5.2 Update User Documentation (45 min)
Create `/home/phil/Projects/starpunk/docs/user-guide/indieauth-setup.md`:
```markdown
# Setting Up IndieAuth for StarPunk
## Quick Start
1. Add these links to your personal website's HTML:
```html
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="https://your-starpunk.com/micropub">
```
2. Configure StarPunk:
```ini
ADMIN_ME=https://your-website.com
TOKEN_ENDPOINT=https://tokens.indieauth.com/token
```
3. Use any Micropub client!
```
#### 5.3 Update README (15 min)
- Remove references to built-in authorization
- Add "Prerequisites" section about external IndieAuth
- Update configuration examples
#### 5.4 Update CHANGELOG (15 min)
```markdown
## [0.5.0] - 2025-11-24
### BREAKING CHANGES
- Removed built-in IndieAuth authorization server
- Removed token issuance functionality
- All existing tokens are invalidated
### Changed
- Token verification now uses external IndieAuth providers
- Simplified database schema (removed token tables)
- Reduced codebase by ~500 lines
### Added
- Support for external token endpoints
- Token verification caching for performance
- IndieAuth discovery links in HTML
### Migration Guide
Users must now:
1. Configure external IndieAuth provider
2. Re-authenticate with Micropub clients
3. Update ADMIN_ME configuration
```
#### 5.5 Version Bump (15 min)
Update `/home/phil/Projects/starpunk/starpunk/__init__.py`:
```python
__version__ = "0.5.0" # Breaking change per versioning strategy
```
### Acceptance Criteria
✅ **Discovery Links Present**
```bash
curl http://localhost:5000/ | grep -E "authorization_endpoint|token_endpoint|micropub"
# Should show all three link tags
```
✅ **Documentation Complete**
- [ ] User guide explains external provider setup
- [ ] README reflects new architecture
- [ ] CHANGELOG documents breaking changes
- [ ] Migration guide provided
✅ **Version Updated**
```bash
uv run python -c "import starpunk; print(starpunk.__version__)"
# Should output: 0.5.0
```
✅ **Examples Work**
- [ ] Example configuration in docs is valid
- [ ] HTML snippet in docs is correct
- [ ] Micropub client setup instructions tested
---
## Final Validation Checklist
### System Health
- [ ] Server starts without errors
- [ ] Admin can log in
- [ ] Admin can create posts
- [ ] Micropub endpoint responds
- [ ] Valid tokens accepted
- [ ] Invalid tokens rejected
- [ ] HTML has discovery links
### Code Quality
- [ ] No orphaned imports
- [ ] No references to removed code
- [ ] Tests pass with >90% coverage
- [ ] No security warnings
### Performance
- [ ] Token verification <500ms
- [ ] Cached verification <50ms
- [ ] Memory usage stable
- [ ] No database deadlocks
### Documentation
- [ ] Architecture docs updated
- [ ] User guide complete
- [ ] API docs accurate
- [ ] CHANGELOG updated
- [ ] Version bumped
### Database
- [ ] Old tables removed
- [ ] No orphaned constraints
- [ ] Migration successful
- [ ] Backup available
## Rollback Decision Tree
```
Issue Detected?
├─ During Phase 1-2?
│ └─ Git revert commits
│ └─ Restart server
├─ During Phase 3?
│ └─ Restore database backup
│ └─ Git revert commits
│ └─ Restart server
└─ During Phase 4-5?
└─ Critical issue?
├─ Yes: Full rollback
│ └─ Restore DB + revert code
└─ No: Fix forward
└─ Patch issue
└─ Continue deployment
```
## Success Metrics
### Quantitative
- **Lines removed**: >500
- **Test coverage**: >90%
- **Token verification**: <500ms
- **Cache hit rate**: >90%
- **Memory stable**: <100MB
### Qualitative
- **Simpler architecture**: Clear separation of concerns
- **Better security**: Specialized providers handle auth
- **Less maintenance**: No auth code to maintain
- **User flexibility**: Choice of providers
- **Standards compliant**: Pure Micropub server
## Risk Matrix
| Risk | Probability | Impact | Mitigation |
|------|------------|---------|------------|
| Breaking existing tokens | Certain | Medium | Clear communication, migration guide |
| External service down | Low | High | Token caching, timeout handling |
| User confusion | Medium | Low | Comprehensive documentation |
| Performance degradation | Low | Medium | Caching layer, monitoring |
| Security vulnerability | Low | High | Use established providers |
---
**Document Version**: 1.0
**Created**: 2025-11-24
**Author**: StarPunk Architecture Team
**Status**: Ready for Implementation

529
docs/architecture/indieauth-removal-plan.md
View File

@@ -1,529 +0,0 @@
# IndieAuth Server Removal Plan
## Executive Summary
This document provides a detailed, file-by-file plan for removing the custom IndieAuth authorization server from StarPunk and replacing it with external provider integration.
## Files to Delete (Complete Removal)
### Python Modules
```
/home/phil/Projects/starpunk/starpunk/tokens.py
- Entire file (token generation, validation, storage)
- ~300 lines of code
/home/phil/Projects/starpunk/tests/test_tokens.py
- All token-related unit tests
- ~200 lines of test code
/home/phil/Projects/starpunk/tests/test_routes_authorization.py
- Authorization endpoint tests
- ~150 lines of test code
/home/phil/Projects/starpunk/tests/test_routes_token.py
- Token endpoint tests
- ~150 lines of test code
/home/phil/Projects/starpunk/tests/test_auth_pkce.py
- PKCE implementation tests
- ~100 lines of test code
```
### Templates
```
/home/phil/Projects/starpunk/templates/auth/authorize.html
- Authorization consent UI
- ~100 lines of HTML/Jinja2
```
### Database Migrations
```
/home/phil/Projects/starpunk/migrations/002_secure_tokens_and_authorization_codes.sql
- Table creation for authorization_codes and tokens
- ~80 lines of SQL
```
## Files to Modify
### 1. `/home/phil/Projects/starpunk/starpunk/routes/auth.py`
**Remove**:
- Import of tokens module functions
- `authorization_endpoint()` function (~150 lines)
- `token_endpoint()` function (~100 lines)
- PKCE-related helper functions
**Keep**:
- Blueprint definition
- Admin login routes
- IndieLogin.com integration
- Session management
**New Structure**:
```python
"""
Authentication routes for StarPunk
Handles IndieLogin authentication flow for admin access.
External IndieAuth providers handle Micropub authentication.
"""
from flask import Blueprint, flash, redirect, render_template, session, url_for
from starpunk.auth import (
handle_callback,
initiate_login,
require_auth,
verify_session,
)
bp = Blueprint("auth", __name__, url_prefix="/auth")
@bp.route("/login", methods=["GET"])
def login_form():
# Keep existing admin login
@bp.route("/callback")
def callback():
# Keep existing callback
@bp.route("/logout")
def logout():
# Keep existing logout
# DELETE: authorization_endpoint()
# DELETE: token_endpoint()
```
### 2. `/home/phil/Projects/starpunk/starpunk/auth.py`
**Remove**:
- PKCE code verifier generation
- PKCE challenge calculation
- Authorization state management for codes
**Keep**:
- Admin session management
- IndieLogin.com integration
- CSRF protection
### 3. `/home/phil/Projects/starpunk/starpunk/micropub.py`
**Current Token Verification**:
```python
from starpunk.tokens import verify_token
def handle_request():
token_info = verify_token(bearer_token)
if not token_info:
return error_response("forbidden")
```
**New Token Verification**:
```python
import httpx
from flask import current_app
def verify_token(bearer_token: str) -> Optional[Dict[str, Any]]:
"""
Verify token with external token endpoint
Uses the configured TOKEN_ENDPOINT to validate tokens.
Caches successful validations for 5 minutes.
"""
# Check cache first
cached = get_cached_token(bearer_token)
if cached:
return cached
# Verify with external endpoint
token_endpoint = current_app.config.get(
'TOKEN_ENDPOINT',
'https://tokens.indieauth.com/token'
)
try:
response = httpx.get(
token_endpoint,
headers={'Authorization': f'Bearer {bearer_token}'},
timeout=5.0
)
if response.status_code != 200:
return None
data = response.json()
# Verify it's for our user
if data.get('me') != current_app.config['ADMIN_ME']:
return None
# Verify scope
scope = data.get('scope', '')
if 'create' not in scope.split():
return None
# Cache for 5 minutes
cache_token(bearer_token, data, ttl=300)
return data
except Exception as e:
current_app.logger.error(f"Token verification failed: {e}")
return None
```
### 4. `/home/phil/Projects/starpunk/starpunk/config.py`
**Add**:
```python
# External IndieAuth Configuration
TOKEN_ENDPOINT = os.getenv(
'TOKEN_ENDPOINT',
'https://tokens.indieauth.com/token'
)
# Remove internal auth endpoints
# DELETE: AUTHORIZATION_ENDPOINT
# DELETE: TOKEN_ISSUER
```
### 5. `/home/phil/Projects/starpunk/templates/base.html`
**Add to `<head>` section**:
```html
<!-- IndieAuth Discovery -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="{{ config.TOKEN_ENDPOINT }}">
<link rel="micropub" href="{{ url_for('micropub.micropub_endpoint', _external=True) }}">
```
### 6. `/home/phil/Projects/starpunk/tests/test_micropub.py`
**Update token verification mocking**:
```python
@patch('starpunk.micropub.httpx.get')
def test_micropub_with_valid_token(mock_get):
"""Test Micropub with valid external token"""
# Mock external token verification
mock_get.return_value.status_code = 200
mock_get.return_value.json.return_value = {
'me': 'https://example.com',
'client_id': 'https://quill.p3k.io',
'scope': 'create update'
}
# Test Micropub request
response = client.post(
'/micropub',
headers={'Authorization': 'Bearer test-token'},
json={'type': ['h-entry'], 'properties': {'content': ['Test']}}
)
assert response.status_code == 201
```
## Database Migration
### Create Migration File
`/home/phil/Projects/starpunk/migrations/003_remove_indieauth_server.sql`:
```sql
-- Migration: Remove IndieAuth Server Tables
-- Description: Remove authorization_codes and tokens tables as we're using external providers
-- Date: 2025-11-24
-- Drop tokens table (depends on authorization_codes)
DROP TABLE IF EXISTS tokens;
-- Drop authorization_codes table
DROP TABLE IF EXISTS authorization_codes;
-- Remove any indexes
DROP INDEX IF EXISTS idx_tokens_hash;
DROP INDEX IF EXISTS idx_tokens_user_id;
DROP INDEX IF EXISTS idx_auth_codes_code;
DROP INDEX IF EXISTS idx_auth_codes_user_id;
-- Update schema version
UPDATE schema_version SET version = 3 WHERE id = 1;
```
## Configuration Changes
### Environment Variables
**Remove from `.env`**:
```bash
# DELETE THESE
AUTHORIZATION_ENDPOINT=/auth/authorization
TOKEN_ENDPOINT=/auth/token
TOKEN_ISSUER=https://starpunk.example.com
```
**Add to `.env`**:
```bash
# External IndieAuth Provider
TOKEN_ENDPOINT=https://tokens.indieauth.com/token
ADMIN_ME=https://your-domain.com
```
### Docker Compose
Update `docker-compose.yml` environment section:
```yaml
environment:
- TOKEN_ENDPOINT=https://tokens.indieauth.com/token
- ADMIN_ME=${ADMIN_ME}
# Remove: AUTHORIZATION_ENDPOINT
# Remove: TOKEN_ENDPOINT (internal)
```
## Import Cleanup
### Files with Import Changes
1. **Main app** (`/home/phil/Projects/starpunk/starpunk/__init__.py`):
- Remove: `from starpunk import tokens`
- Remove: Registration of token-related error handlers
2. **Routes init** (`/home/phil/Projects/starpunk/starpunk/routes/__init__.py`):
- No changes needed (auth blueprint still exists)
3. **Test fixtures** (`/home/phil/Projects/starpunk/tests/conftest.py`):
- Remove: Token creation fixtures
- Remove: Authorization code fixtures
## Error Handling Updates
### Remove Custom Exceptions
From various files, remove:
```python
- InvalidAuthorizationCodeError
- ExpiredAuthorizationCodeError
- InvalidTokenError
- ExpiredTokenError
- InsufficientScopeError
```
### Update Error Responses
In Micropub, simplify to:
```python
if not token_info:
return error_response("forbidden", "Invalid or expired token")
```
## Testing Updates
### Test Coverage Impact
**Before Removal**:
- ~20 test files
- ~1500 lines of test code
- Coverage: 95%
**After Removal**:
- ~15 test files
- ~1000 lines of test code
- Expected coverage: 93%
### New Test Requirements
1. **Mock External Verification**:
```python
@pytest.fixture
def mock_token_endpoint():
with patch('starpunk.micropub.httpx.get') as mock:
yield mock
```
2. **Test Scenarios**:
- Valid token from external provider
- Invalid token (404 from provider)
- Wrong user (me doesn't match)
- Insufficient scope
- Network timeout
- Provider unavailable
## Performance Considerations
### Token Verification Caching
Implement simple TTL cache:
```python
from functools import lru_cache
from time import time
token_cache = {} # {token_hash: (data, expiry)}
def cache_token(token: str, data: dict, ttl: int = 300):
token_hash = hashlib.sha256(token.encode()).hexdigest()
token_cache[token_hash] = (data, time() + ttl)
def get_cached_token(token: str) -> Optional[dict]:
token_hash = hashlib.sha256(token.encode()).hexdigest()
if token_hash in token_cache:
data, expiry = token_cache[token_hash]
if time() < expiry:
return data
del token_cache[token_hash]
return None
```
### Expected Latencies
- **Without cache**: 200-500ms per request (external API call)
- **With cache**: <1ms for cached tokens
- **Cache hit rate**: ~95% for active sessions
## Documentation Updates
### Files to Update
1. **README.md**:
- Remove references to built-in authorization
- Add external provider setup instructions
2. **Architecture Overview** (`/home/phil/Projects/starpunk/docs/architecture/overview.md`):
- Update component diagram
- Remove authorization server component
- Clarify Micropub-only role
3. **API Documentation** (`/home/phil/Projects/starpunk/docs/api/`):
- Remove `/auth/authorization` endpoint docs
- Remove `/auth/token` endpoint docs
- Update Micropub authentication section
4. **Deployment Guide** (`/home/phil/Projects/starpunk/docs/deployment/`):
- Update environment variable list
- Add external provider configuration
## Rollback Plan
### Emergency Rollback Script
Create `/home/phil/Projects/starpunk/scripts/rollback-auth.sh`:
```bash
#!/bin/bash
# Emergency rollback for IndieAuth removal
echo "Rolling back IndieAuth removal..."
# Restore from git
git revert HEAD~5..HEAD
# Restore database
psql $DATABASE_URL < migrations/002_secure_tokens_and_authorization_codes.sql
# Restore config
cp .env.backup .env
# Restart service
docker-compose restart
echo "Rollback complete"
```
### Verification After Rollback
1. Check endpoints respond:
```bash
curl -I https://starpunk.example.com/auth/authorization
curl -I https://starpunk.example.com/auth/token
```
2. Run test suite:
```bash
pytest tests/test_auth.py
pytest tests/test_tokens.py
```
3. Verify database tables:
```sql
SELECT COUNT(*) FROM authorization_codes;
SELECT COUNT(*) FROM tokens;
```
## Risk Assessment
### High Risk Areas
1. **Breaking existing tokens**: All existing tokens become invalid
2. **External dependency**: Reliance on external service availability
3. **Configuration errors**: Users may misconfigure endpoints
### Mitigation Strategies
1. **Clear communication**: Announce breaking change prominently
2. **Graceful degradation**: Cache tokens, handle timeouts
3. **Validation tools**: Provide config validation script
## Success Criteria
### Technical Criteria
- [ ] All listed files deleted
- [ ] All imports cleaned up
- [ ] Tests pass with >90% coverage
- [ ] No references to internal auth in codebase
- [ ] External verification working
### Functional Criteria
- [ ] Admin can log in
- [ ] Micropub accepts valid tokens
- [ ] Micropub rejects invalid tokens
- [ ] Discovery links present
- [ ] Documentation updated
### Performance Criteria
- [ ] Token verification <500ms
- [ ] Cache hit rate >90%
- [ ] No memory leaks from cache
## Timeline
### Day 1: Removal Phase
- Hour 1-2: Remove authorization endpoint
- Hour 3-4: Remove token endpoint
- Hour 5-6: Delete token module
- Hour 7-8: Update tests
### Day 2: Integration Phase
- Hour 1-2: Implement external verification
- Hour 3-4: Add caching layer
- Hour 5-6: Update configuration
- Hour 7-8: Test with real providers
### Day 3: Documentation Phase
- Hour 1-2: Update technical docs
- Hour 3-4: Create user guides
- Hour 5-6: Update changelog
- Hour 7-8: Final testing
## Appendix: File Size Impact
### Before Removal
```
starpunk/
tokens.py: 8.2 KB
routes/auth.py: 15.3 KB
templates/auth/: 2.8 KB
tests/
test_tokens.py: 6.1 KB
test_routes_*.py: 12.4 KB
Total: ~45 KB
```
### After Removal
```
starpunk/
routes/auth.py: 5.1 KB (10.2 KB removed)
micropub.py: +1.5 KB (verification)
tests/
test_micropub.py: +0.8 KB (mocks)
Total removed: ~40 KB
Net reduction: ~38.5 KB
```
---
**Document Version**: 1.0
**Created**: 2025-11-24
**Author**: StarPunk Architecture Team

160
docs/architecture/indieauth-token-verification-diagnosis.md
View File

@@ -1,160 +0,0 @@
# IndieAuth Token Verification Diagnosis
## Executive Summary
**The Problem**: StarPunk is receiving HTTP 405 Method Not Allowed when verifying tokens with gondulf.thesatelliteoflove.com
**The Cause**: The gondulf IndieAuth provider does not implement the W3C IndieAuth specification correctly
**The Solution**: The provider needs to be fixed - StarPunk's implementation is correct
## Why We Make GET Requests
You asked: "Why are we making GET requests to these endpoints?"
**Answer**: Because the W3C IndieAuth specification explicitly requires GET requests for token verification.
### The IndieAuth Token Endpoint Dual Purpose
The token endpoint serves two distinct purposes with different HTTP methods:
1. **Token Issuance (POST)**
- Client sends authorization code
- Server returns new access token
- State-changing operation
2. **Token Verification (GET)**
- Resource server sends token in Authorization header
- Token endpoint returns token metadata
- Read-only operation
### Why This Design Makes Sense
The specification follows RESTful principles:
- **GET** = Read data (verify a token exists and is valid)
- **POST** = Create/modify data (issue a new token)
This is similar to how you might:
- GET /users/123 to read user information
- POST /users to create a new user
## The Specific Problem
### What Should Happen
```
StarPunk → GET https://gondulf.thesatelliteoflove.com/token
Authorization: Bearer abc123...
Gondulf → 200 OK
{
"me": "https://thesatelliteoflove.com",
"client_id": "https://starpunk.example",
"scope": "create"
}
```
### What Actually Happens
```
StarPunk → GET https://gondulf.thesatelliteoflove.com/token
Authorization: Bearer abc123...
Gondulf → 405 Method Not Allowed
(Server doesn't support GET on /token)
```
## Code Analysis
### Our Implementation (Correct)
From `/home/phil/Projects/starpunk/starpunk/auth_external.py` line 425:
```python
def _verify_with_endpoint(endpoint: str, token: str) -> Dict[str, Any]:
"""
Verify token with the discovered token endpoint
Makes GET request to endpoint with Authorization header.
"""
headers = {
'Authorization': f'Bearer {token}',
'Accept': 'application/json',
}
response = httpx.get( # ← Correct: Using GET
endpoint,
headers=headers,
timeout=VERIFICATION_TIMEOUT,
follow_redirects=True,
)
```
### IndieAuth Spec Reference
From W3C IndieAuth Section 6.3.4:
> "If an external endpoint needs to verify that an access token is valid, it **MUST** make a **GET request** to the token endpoint containing an HTTP `Authorization` header with the Bearer Token according to RFC6750."
(Emphasis added)
## Why the Provider is Wrong
The gondulf IndieAuth provider appears to:
1. Only implement POST for token issuance
2. Not implement GET for token verification
3. Return 405 for any GET requests to /token
This is only a partial implementation of IndieAuth.
## Impact Analysis
### What This Breaks
- StarPunk cannot authenticate users through gondulf
- Any other spec-compliant Micropub client would also fail
- The provider is not truly IndieAuth compliant
### What This Doesn't Break
- Our code is correct
- We can work with any compliant IndieAuth provider
- The architecture is sound
## Solutions
### Option 1: Fix the Provider (Recommended)
The gondulf provider needs to:
1. Add GET method support to /token endpoint
2. Verify bearer tokens from Authorization header
3. Return appropriate JSON response
### Option 2: Use a Different Provider
Known compliant providers:
- IndieAuth.com
- IndieLogin.com
- Self-hosted IndieAuth servers that implement full spec
### Option 3: Work Around (Not Recommended)
We could add a non-compliant mode, but this would:
- Violate the specification
- Encourage bad implementations
- Add unnecessary complexity
- Create security concerns
## Summary
**Your Question**: "Why are we making GET requests to these endpoints?"
**Answer**: Because that's what the IndieAuth specification requires for token verification. We're doing it right. The gondulf provider is doing it wrong.
**Action Required**: The gondulf IndieAuth provider needs to implement GET support on their token endpoint to be IndieAuth compliant.
## References
1. [W3C IndieAuth - Token Verification](https://www.w3.org/TR/indieauth/#token-verification)
2. [RFC 6750 - OAuth 2.0 Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
3. [StarPunk Implementation](https://github.com/starpunk/starpunk/blob/main/starpunk/auth_external.py)
## Contact Information for Provider
If you need to report this to the gondulf provider:
"Your IndieAuth token endpoint at https://gondulf.thesatelliteoflove.com/token returns HTTP 405 Method Not Allowed for GET requests. Per the W3C IndieAuth specification Section 6.3.4, the token endpoint MUST support GET requests with Bearer authentication for token verification. Currently it appears to only support POST for token issuance."

238
docs/architecture/migration-fix-quick-reference.md
View File

@@ -1,238 +0,0 @@
# Migration Race Condition Fix - Quick Implementation Reference
## Implementation Checklist
### Code Changes - `/home/phil/Projects/starpunk/starpunk/migrations.py`
```python
# 1. Add imports at top
import time
import random
# 2. Replace entire run_migrations function (lines 304-462)
# See full implementation in migration-race-condition-fix-implementation.md
# Key patterns to implement:
# A. Retry loop structure
max_retries = 10
retry_count = 0
base_delay = 0.1
start_time = time.time()
max_total_time = 120 # 2 minute absolute max
while retry_count < max_retries and (time.time() - start_time) < max_total_time:
conn = None # NEW connection each iteration
try:
conn = sqlite3.connect(db_path, timeout=30.0)
conn.execute("BEGIN IMMEDIATE") # Lock acquisition
# ... migration logic ...
conn.commit()
return # Success
except sqlite3.OperationalError as e:
if "database is locked" in str(e).lower():
retry_count += 1
if retry_count < max_retries:
# Exponential backoff with jitter
delay = base_delay * (2 ** retry_count) + random.uniform(0, 0.1)
# Graduated logging
if retry_count <= 3:
logger.debug(f"Retry {retry_count}/{max_retries}")
elif retry_count <= 7:
logger.info(f"Retry {retry_count}/{max_retries}")
else:
logger.warning(f"Retry {retry_count}/{max_retries}")
time.sleep(delay)
continue
finally:
if conn:
try:
conn.close()
except:
pass
# B. Error handling pattern
except Exception as e:
try:
conn.rollback()
except Exception as rollback_error:
logger.critical(f"FATAL: Rollback failed: {rollback_error}")
raise SystemExit(1)
raise MigrationError(f"Migration failed: {e}")
# C. Final error message
raise MigrationError(
f"Failed to acquire migration lock after {max_retries} attempts over {elapsed:.1f}s. "
f"Possible causes:\n"
f"1. Another process is stuck in migration (check logs)\n"
f"2. Database file permissions issue\n"
f"3. Disk I/O problems\n"
f"Action: Restart container with single worker to diagnose"
)
```
### Testing Requirements
#### 1. Unit Test File: `test_migration_race_condition.py`
```python
import multiprocessing
from multiprocessing import Barrier, Process
import time
def test_concurrent_migrations():
"""Test 4 workers starting simultaneously"""
barrier = Barrier(4)
def worker(worker_id):
barrier.wait() # Synchronize start
from starpunk import create_app
app = create_app()
return True
with multiprocessing.Pool(4) as pool:
results = pool.map(worker, range(4))
assert all(results), "Some workers failed"
def test_lock_retry():
"""Test retry logic with mock"""
with patch('sqlite3.connect') as mock:
mock.side_effect = [
sqlite3.OperationalError("database is locked"),
sqlite3.OperationalError("database is locked"),
MagicMock() # Success on 3rd try
]
run_migrations(db_path)
assert mock.call_count == 3
```
#### 2. Integration Test: `test_integration.sh`
```bash
#!/bin/bash
# Test with actual gunicorn
# Clean start
rm -f test.db
# Start gunicorn with 4 workers
timeout 10 gunicorn --workers 4 --bind 127.0.0.1:8001 app:app &
PID=$!
# Wait for startup
sleep 3
# Check if running
if ! kill -0 $PID 2>/dev/null; then
echo "FAILED: Gunicorn crashed"
exit 1
fi
# Check health endpoint
curl -f http://127.0.0.1:8001/health || exit 1
# Cleanup
kill $PID
echo "SUCCESS: All workers started without race condition"
```
#### 3. Container Test: `test_container.sh`
```bash
#!/bin/bash
# Test in container environment
# Build
podman build -t starpunk:race-test -f Containerfile .
# Run with fresh database
podman run --rm -d --name race-test \
-v $(pwd)/test-data:/data \
starpunk:race-test
# Check logs for success patterns
sleep 5
podman logs race-test | grep -E "(Applied migration|already applied by another worker)"
# Cleanup
podman stop race-test
```
### Verification Patterns in Logs
#### Successful Migration (One Worker Wins)
```
Worker 0: Applying migration: 001_initial_schema.sql
Worker 1: Database locked by another worker, retry 1/10 in 0.21s
Worker 2: Database locked by another worker, retry 1/10 in 0.23s
Worker 3: Database locked by another worker, retry 1/10 in 0.19s
Worker 0: Applied migration: 001_initial_schema.sql
Worker 1: All migrations already applied by another worker
Worker 2: All migrations already applied by another worker
Worker 3: All migrations already applied by another worker
```
#### Performance Metrics to Check
- Single worker: < 100ms total
- 4 workers: < 500ms total
- 10 workers (stress): < 2000ms total
### Rollback Plan if Issues
1. **Immediate Workaround**
```bash
# Change to single worker temporarily
gunicorn --workers 1 --bind 0.0.0.0:8000 app:app
```
2. **Revert Code**
```bash
git revert HEAD
```
3. **Emergency Patch**
```python
# In app.py temporarily
import os
if os.getenv('GUNICORN_WORKER_ID', '1') == '1':
init_db() # Only first worker runs migrations
```
### Deployment Commands
```bash
# 1. Run tests
python -m pytest test_migration_race_condition.py -v
# 2. Build container
podman build -t starpunk:v1.0.0-rc.3.1 -f Containerfile .
# 3. Tag for release
podman tag starpunk:v1.0.0-rc.3.1 git.philmade.com/starpunk:v1.0.0-rc.3.1
# 4. Push
podman push git.philmade.com/starpunk:v1.0.0-rc.3.1
# 5. Deploy
kubectl rollout restart deployment/starpunk
```
---
## Critical Points to Remember
1. **NEW CONNECTION EACH RETRY** - Don't reuse connections
2. **BEGIN IMMEDIATE** - Not EXCLUSIVE, not DEFERRED
3. **30s per attempt, 120s total max** - Two different timeouts
4. **Graduated logging** - DEBUG → INFO → WARNING based on retry count
5. **Test at multiple levels** - Unit, integration, container
6. **Fresh database state** between tests
## Support
If issues arise, check:
1. `/home/phil/Projects/starpunk/docs/architecture/migration-race-condition-answers.md` - Full Q&A
2. `/home/phil/Projects/starpunk/docs/reports/migration-race-condition-fix-implementation.md` - Detailed implementation
3. SQLite lock states: `PRAGMA lock_status` during issue
---
*Quick Reference v1.0 - 2025-11-24*

477
docs/architecture/migration-race-condition-answers.md
View File

@@ -1,477 +0,0 @@
# Migration Race Condition Fix - Architectural Answers
## Status: READY FOR IMPLEMENTATION
All 23 questions have been answered with concrete guidance. The developer can proceed with implementation.
---
## Critical Questions
### 1. Connection Lifecycle Management
**Q: Should we create a new connection for each retry or reuse the same connection?**
**Answer: NEW CONNECTION per retry**
- Each retry MUST create a fresh connection
- Rationale: Failed lock acquisition may leave connection in inconsistent state
- SQLite connections are lightweight; overhead is minimal
- Pattern:
```python
while retry_count < max_retries:
conn = None # Fresh connection each iteration
try:
conn = sqlite3.connect(db_path, timeout=30.0)
# ... attempt migration ...
finally:
if conn:
conn.close()
```
### 2. Transaction Boundaries
**Q: Should init_db() wrap everything in one transaction?**
**Answer: NO - Separate transactions for different operations**
- Schema creation: Own transaction (already implicit in executescript)
- Migrations: Own transaction with BEGIN IMMEDIATE
- Initial data: Own transaction
- Rationale: Minimizes lock duration and allows partial success visibility
- Each operation is atomic but independent
### 3. Lock Timeout vs Retry Timeout
**Q: Connection timeout is 30s but retry logic could take ~102s. Conflict?**
**Answer: This is BY DESIGN - No conflict**
- 30s timeout: Maximum wait for any single lock acquisition attempt
- 102s total: Maximum cumulative retry duration across multiple attempts
- If one worker holds lock for 30s+, other workers timeout and retry
- Pattern ensures no single worker waits indefinitely
- Recommendation: Add total timeout check:
```python
start_time = time.time()
max_total_time = 120 # 2 minutes absolute maximum
while retry_count < max_retries and (time.time() - start_time) < max_total_time:
```
### 4. Testing Strategy
**Q: Should we use multiprocessing.Pool or actual gunicorn for testing?**
**Answer: BOTH - Different test levels**
- Unit tests: multiprocessing.Pool (fast, isolated)
- Integration tests: Actual gunicorn with --workers 4
- Container tests: Full podman/docker run
- Test matrix:
```
Level 1: Mock concurrent access (unit)
Level 2: multiprocessing.Pool (integration)
Level 3: gunicorn locally (system)
Level 4: Container with gunicorn (e2e)
```
### 5. BEGIN IMMEDIATE vs EXCLUSIVE
**Q: Why use BEGIN IMMEDIATE instead of BEGIN EXCLUSIVE?**
**Answer: BEGIN IMMEDIATE is CORRECT choice**
- BEGIN IMMEDIATE: Acquires RESERVED lock (prevents other writes, allows reads)
- BEGIN EXCLUSIVE: Acquires EXCLUSIVE lock (prevents all access)
- Rationale:
- Migrations only need to prevent concurrent migrations (writes)
- Other workers can still read schema while one migrates
- Less contention, faster startup
- Only escalates to EXCLUSIVE when actually writing
- Keep BEGIN IMMEDIATE as specified
---
## Edge Cases and Error Handling
### 6. Partial Migration Failure
**Q: What if a migration partially applies or rollback fails?**
**Answer: Transaction atomicity handles this**
- Within transaction: Automatic rollback on ANY error
- Rollback failure: Extremely rare (corrupt database)
- Strategy:
```python
except Exception as e:
try:
conn.rollback()
except Exception as rollback_error:
logger.critical(f"FATAL: Rollback failed: {rollback_error}")
# Database potentially corrupt - fail hard
raise SystemExit(1)
raise MigrationError(e)
```
### 7. Migration File Consistency
**Q: What if migration files change during deployment?**
**Answer: Not a concern with proper deployment**
- Container deployments: Files are immutable in image
- Traditional deployment: Use atomic directory swap
- If concerned, add checksum validation:
```python
# Store in schema_migrations: (name, checksum, applied_at)
# Verify checksum matches before applying
```
### 8. Retry Exhaustion Error Messages
**Q: What error message when retries exhausted?**
**Answer: Be specific and actionable**
```python
raise MigrationError(
f"Failed to acquire migration lock after {max_retries} attempts over {elapsed:.1f}s. "
f"Possible causes:\n"
f"1. Another process is stuck in migration (check logs)\n"
f"2. Database file permissions issue\n"
f"3. Disk I/O problems\n"
f"Action: Restart container with single worker to diagnose"
)
```
### 9. Logging Levels
**Q: What log level for lock waits?**
**Answer: Graduated approach**
- Retry 1-3: DEBUG (normal operation)
- Retry 4-7: INFO (getting concerning)
- Retry 8+: WARNING (abnormal)
- Exhausted: ERROR (operation failed)
- Pattern:
```python
if retry_count <= 3:
level = logging.DEBUG
elif retry_count <= 7:
level = logging.INFO
else:
level = logging.WARNING
logger.log(level, f"Retry {retry_count}/{max_retries}")
```
### 10. Index Creation Failure
**Q: How to handle index creation failures in migration 002?**
**Answer: Fail fast with clear context**
```python
for index_name, index_sql in indexes_to_create:
try:
conn.execute(index_sql)
except sqlite3.OperationalError as e:
if "already exists" in str(e):
logger.debug(f"Index {index_name} already exists")
else:
raise MigrationError(
f"Failed to create index {index_name}: {e}\n"
f"SQL: {index_sql}"
)
```
---
## Testing Strategy
### 11. Concurrent Testing Simulation
**Q: How to properly simulate concurrent worker startup?**
**Answer: Multiple approaches**
```python
# Approach 1: Barrier synchronization
def test_concurrent_migrations():
barrier = multiprocessing.Barrier(4)
def worker():
barrier.wait() # All start together
return run_migrations(db_path)
with multiprocessing.Pool(4) as pool:
results = pool.map(worker, range(4))
# Approach 2: Process start
processes = []
for i in range(4):
p = Process(target=run_migrations, args=(db_path,))
processes.append(p)
for p in processes:
p.start() # Near-simultaneous
```
### 12. Lock Contention Testing
**Q: How to test lock contention scenarios?**
**Answer: Inject delays**
```python
# Test helper to force contention
def slow_migration_for_testing(conn):
conn.execute("BEGIN IMMEDIATE")
time.sleep(2) # Force other workers to wait
# Apply migration
conn.commit()
# Test timeout handling
@patch('sqlite3.connect')
def test_lock_timeout(mock_connect):
mock_connect.side_effect = sqlite3.OperationalError("database is locked")
# Verify retry logic
```
### 13. Performance Tests
**Q: What timing is acceptable?**
**Answer: Performance targets**
- Single worker: < 100ms for all migrations
- 4 workers with contention: < 500ms total
- 10 workers stress test: < 2s total
- Lock acquisition per retry: < 50ms
- Test with:
```python
import timeit
setup_time = timeit.timeit(lambda: create_app(), number=1)
assert setup_time < 0.5, f"Startup too slow: {setup_time}s"
```
### 14. Retry Logic Unit Tests
**Q: How to unit test retry logic?**
**Answer: Mock the lock failures**
```python
class TestRetryLogic:
def test_retry_on_lock(self):
with patch('sqlite3.connect') as mock:
# First 2 attempts fail, 3rd succeeds
mock.side_effect = [
sqlite3.OperationalError("database is locked"),
sqlite3.OperationalError("database is locked"),
MagicMock() # Success
]
run_migrations(db_path)
assert mock.call_count == 3
```
---
## SQLite-Specific Concerns
### 15. BEGIN IMMEDIATE vs EXCLUSIVE (Detailed)
**Q: Deep dive on lock choice?**
**Answer: Lock escalation path**
```
BEGIN DEFERRED → SHARED → RESERVED → EXCLUSIVE
BEGIN IMMEDIATE → RESERVED → EXCLUSIVE
BEGIN EXCLUSIVE → EXCLUSIVE
For migrations:
- IMMEDIATE starts at RESERVED (blocks other writers immediately)
- Escalates to EXCLUSIVE only during actual writes
- Optimal for our use case
```
### 16. WAL Mode Interaction
**Q: How does this work with WAL mode?**
**Answer: Works correctly with both modes**
- Journal mode: BEGIN IMMEDIATE works as described
- WAL mode: BEGIN IMMEDIATE still prevents concurrent writers
- No code changes needed
- Add mode detection for logging:
```python
cursor = conn.execute("PRAGMA journal_mode")
mode = cursor.fetchone()[0]
logger.debug(f"Database in {mode} mode")
```
### 17. Database File Permissions
**Q: How to handle permission issues?**
**Answer: Fail fast with helpful diagnostics**
```python
import os
import stat
db_path = Path(db_path)
if not db_path.exists():
# Will be created - check parent dir
parent = db_path.parent
if not os.access(parent, os.W_OK):
raise MigrationError(f"Cannot write to directory: {parent}")
else:
# Check existing file
if not os.access(db_path, os.W_OK):
stats = os.stat(db_path)
mode = stat.filemode(stats.st_mode)
raise MigrationError(
f"Database not writable: {db_path}\n"
f"Permissions: {mode}\n"
f"Owner: {stats.st_uid}:{stats.st_gid}"
)
```
---
## Deployment/Operations
### 18. Container Startup and Health Checks
**Q: How to handle health checks during migration?**
**Answer: Return 503 during migration**
```python
# In app.py
MIGRATION_IN_PROGRESS = False
def create_app():
global MIGRATION_IN_PROGRESS
MIGRATION_IN_PROGRESS = True
try:
init_db()
finally:
MIGRATION_IN_PROGRESS = False
@app.route('/health')
def health():
if MIGRATION_IN_PROGRESS:
return {'status': 'migrating'}, 503
return {'status': 'healthy'}, 200
```
### 19. Monitoring and Alerting
**Q: What metrics/alerts are needed?**
**Answer: Key metrics to track**
```python
# Add metrics collection
metrics = {
'migration_duration_ms': 0,
'migration_retries': 0,
'migration_lock_wait_ms': 0,
'migrations_applied': 0
}
# Alert thresholds
ALERTS = {
'migration_duration_ms': 5000, # Alert if > 5s
'migration_retries': 5, # Alert if > 5 retries
'worker_failures': 1 # Alert on any failure
}
# Log in structured format
logger.info(json.dumps({
'event': 'migration_complete',
'metrics': metrics
}))
```
---
## Alternative Approaches
### 20. Version Compatibility
**Q: How to handle version mismatches?**
**Answer: Strict version checking**
```python
# In migrations.py
MIGRATION_VERSION = "1.0.0"
def check_version_compatibility(conn):
cursor = conn.execute(
"SELECT value FROM app_config WHERE key = 'migration_version'"
)
row = cursor.fetchone()
if row and row[0] != MIGRATION_VERSION:
raise MigrationError(
f"Version mismatch: Database={row[0]}, Code={MIGRATION_VERSION}\n"
f"Action: Run migration tool separately"
)
```
### 21. File-Based Locking
**Q: Should we consider flock() as backup?**
**Answer: NO - Adds complexity without benefit**
- SQLite locking is sufficient and portable
- flock() not available on all systems
- Would require additional cleanup logic
- Database-level locking is the correct approach
### 22. Gunicorn Preload
**Q: Would --preload flag help?**
**Answer: NO - Makes problem WORSE**
- --preload runs app initialization ONCE in master
- Workers fork from master AFTER migrations complete
- BUT: Doesn't work with lazy-loaded resources
- Current architecture expects per-worker initialization
- Keep current approach
### 23. Application-Level Locks
**Q: Should we add Redis/memcached for coordination?**
**Answer: NO - Violates simplicity principle**
- Adds external dependency
- More complex deployment
- SQLite locking is sufficient
- Would require Redis/memcached to be running before app starts
- Solving a solved problem
---
## Final Implementation Checklist
### Required Changes
1. ✅ Add imports: `time`, `random`
2. ✅ Implement retry loop with exponential backoff
3. ✅ Use BEGIN IMMEDIATE for lock acquisition
4. ✅ Add graduated logging levels
5. ✅ Proper error messages with diagnostics
6. ✅ Fresh connection per retry
7. ✅ Total timeout check (2 minutes max)
8. ✅ Preserve all existing migration logic
### Test Coverage Required
1. ✅ Unit test: Retry on lock
2. ✅ Unit test: Exhaustion handling
3. ✅ Integration test: 4 workers with multiprocessing
4. ✅ System test: gunicorn with 4 workers
5. ✅ Container test: Full deployment simulation
6. ✅ Performance test: < 500ms with contention
### Documentation Updates
1. ✅ Update ADR-022 with final decision
2. ✅ Add operational runbook for migration issues
3. ✅ Document monitoring metrics
4. ✅ Update deployment guide with health check info
---
## Go/No-Go Decision
### ✅ GO FOR IMPLEMENTATION
**Rationale:**
- All 23 questions have concrete answers
- Design is proven with SQLite's native capabilities
- No external dependencies needed
- Risk is low with clear rollback plan
- Testing strategy is comprehensive
**Implementation Priority: IMMEDIATE**
- This is blocking v1.0.0-rc.4 release
- Production systems affected
- Fix is well-understood and low-risk
**Next Steps:**
1. Implement changes to migrations.py as specified
2. Run test suite at all levels
3. Deploy as hotfix v1.0.0-rc.3.1
4. Monitor metrics in production
5. Document lessons learned
---
*Document Version: 1.0*
*Created: 2025-11-24*
*Status: Approved for Implementation*
*Author: StarPunk Architecture Team*

875
docs/architecture/phase-5-validation-report.md
View File

@@ -1,875 +0,0 @@
# Phase 5 RSS Feed Implementation - Architectural Validation Report
**Date**: 2025-11-19
**Architect**: StarPunk Architect Agent
**Phase**: Phase 5 - RSS Feed Generation (Part 1)
**Branch**: `feature/phase-5-rss-container`
**Status**: ✅ **APPROVED FOR CONTAINERIZATION**
---
## Executive Summary
The Phase 5 RSS feed implementation has been comprehensively reviewed and is **approved to proceed to containerization (Part 2)**. The implementation demonstrates excellent adherence to architectural principles, standards compliance, and code quality. All design specifications from ADR-014 and ADR-015 have been faithfully implemented with no architectural concerns.
### Key Findings
- **Design Compliance**: 100% adherence to ADR-014 specifications
- **Standards Compliance**: RSS 2.0, RFC-822, IndieWeb standards met
- **Code Quality**: Clean, well-documented, properly tested
- **Test Coverage**: 88% overall, 96% for feed module, 44/44 tests passing
- **Git Workflow**: Proper branching, clear commit messages, logical progression
- **Documentation**: Comprehensive and accurate
### Verdict
**PROCEED** to Phase 5 Part 2 (Containerization). No remediation required.
---
## 1. Git Commit Review
### Branch Structure ✅
**Branch**: `feature/phase-5-rss-container`
**Base**: `main` (commit a68fd57)
**Commits**: 8 commits (well-structured, logical progression)
### Commit Analysis
| Commit | Type | Message | Assessment |
|--------|------|---------|------------|
| b02df15 | chore | bump version to 0.6.0 for Phase 5 | ✅ Proper version bump |
| 8561482 | feat | add RSS feed generation module | ✅ Core module |
| d420269 | feat | add RSS feed endpoint and configuration | ✅ Route + config |
| deb784a | feat | improve RSS feed discovery in templates | ✅ Template integration |
| 9a31632 | test | add comprehensive RSS feed tests | ✅ Comprehensive tests |
| 891a72a | fix | resolve test isolation issues in feed tests | ✅ Test refinement |
| 8e332ff | docs | update CHANGELOG for v0.6.0 | ✅ Documentation |
| fbbc9c6 | docs | add Phase 5 RSS implementation report | ✅ Implementation report |
### Commit Message Quality ✅
All commits follow the documented commit message format:
- **Format**: `<type>: <summary>` with optional detailed body
- **Types**: Appropriate use of `feat:`, `fix:`, `test:`, `docs:`, `chore:`
- **Summaries**: Clear, concise (< 50 chars for subject line)
- **Bodies**: Comprehensive descriptions with implementation details
- **Conventional Commits**: Fully compliant
### Incremental Progression ✅
The commit sequence demonstrates excellent incremental development:
1. Version bump (preparing for release)
2. Core functionality (feed generation module)
3. Integration (route and configuration)
4. Enhancement (template discovery)
5. Testing (comprehensive test suite)
6. Refinement (test isolation fixes)
7. Documentation (changelog and report)
**Assessment**: Exemplary git workflow. Clean, logical, and well-documented.
---
## 2. Code Implementation Review
### 2.1 Feed Module (`starpunk/feed.py`) ✅
**Lines**: 229
**Coverage**: 96%
**Standards**: RSS 2.0, RFC-822 compliant
#### Architecture Alignment
| Requirement (ADR-014) | Implementation | Status |
|----------------------|----------------|---------|
| RSS 2.0 format only | `feedgen` library with RSS 2.0 | ✅ |
| RFC-822 date format | `format_rfc822_date()` function | ✅ |
| Title extraction | `get_note_title()` with fallback | ✅ |
| HTML in CDATA | `clean_html_for_rss()` + feedgen | ✅ |
| 50 item default limit | Configurable limit parameter | ✅ |
| Absolute URLs | Proper URL construction | ✅ |
| Atom self-link | `fg.link(rel="self")` | ✅ |
#### Code Quality Assessment
**Strengths**:
- **Clear separation of concerns**: Each function has single responsibility
- **Comprehensive docstrings**: Every function documented with examples
- **Error handling**: Validates required parameters, handles edge cases
- **Defensive coding**: CDATA marker checking, timezone handling
- **Standards compliance**: Proper RSS 2.0 structure, all required elements
**Design Principles**:
- ✅ Minimal code (no unnecessary complexity)
- ✅ Single responsibility (each function does one thing)
- ✅ Standards first (RSS 2.0, RFC-822)
- ✅ Progressive enhancement (graceful fallbacks)
**Notable Implementation Details**:
1. **Timezone handling**: Properly converts naive datetimes to UTC
2. **URL normalization**: Strips trailing slashes for consistency
3. **Title extraction**: Leverages Note model's title property
4. **CDATA safety**: Defensive check for CDATA end markers (though unlikely)
5. **UTF-8 encoding**: Explicit UTF-8 encoding for international characters
**Assessment**: Excellent implementation. Clean, simple, and standards-compliant.
### 2.2 Feed Route (`starpunk/routes/public.py`) ✅
**Route**: `GET /feed.xml`
**Caching**: 5-minute in-memory cache with ETag support
#### Architecture Alignment
| Requirement (ADR-014) | Implementation | Status |
|----------------------|----------------|---------|
| 5-minute cache | In-memory `_feed_cache` dict | ✅ |
| ETag support | MD5 hash of feed content | ✅ |
| Cache-Control headers | `public, max-age={seconds}` | ✅ |
| Published notes only | `list_notes(published_only=True)` | ✅ |
| Configurable limit | `FEED_MAX_ITEMS` config | ✅ |
| Proper content type | `application/rss+xml; charset=utf-8` | ✅ |
#### Caching Implementation Analysis
**Cache Structure**:
```python
_feed_cache = {
'xml': None, # Cached feed XML
'timestamp': None, # Cache creation time
'etag': None # MD5 hash for conditional requests
}
```
**Cache Logic**:
1. Check if cache exists and is fresh (< 5 minutes old)
2. If fresh: return cached XML with ETag
3. If stale/empty: generate new feed, update cache, return with new ETag
**Performance Characteristics**:
- First request: Generates feed (~10-50ms depending on note count)
- Cached requests: Immediate response (~1ms)
- Cache expiration: Automatic after configurable duration
- ETag validation: Enables conditional requests (not yet implemented client-side)
**Scalability Notes**:
- In-memory cache acceptable for single-user system
- Cache shared across all requests (appropriate for public feed)
- No cache invalidation on note updates (5-minute delay acceptable per ADR-014)
**Assessment**: Caching implementation follows ADR-014 exactly. Appropriate for V1.
#### Security Review
**MD5 Usage** ⚠️ (Non-Issue):
- MD5 used for ETag generation (line 135)
- **Context**: ETags are not security-sensitive, used only for cache validation
- **Risk Level**: None - ETags don't require cryptographic strength
- **Recommendation**: Current use is appropriate; no change needed
**Published Notes Filter** ✅:
- Correctly uses `published_only=True` filter
- No draft notes exposed in feed
- Proper access control
**HTML Content** ✅:
- HTML sanitized by markdown renderer (python-markdown)
- CDATA wrapping prevents XSS in feed readers
- No raw user input in feed
**Assessment**: No security concerns. MD5 for ETags is appropriate use.
### 2.3 Configuration (`starpunk/config.py`) ✅
**New Configuration**:
- `FEED_MAX_ITEMS`: Maximum feed items (default: 50)
- `FEED_CACHE_SECONDS`: Cache duration in seconds (default: 300)
- `VERSION`: Updated to 0.6.0
#### Configuration Design
```python
app.config["FEED_MAX_ITEMS"] = int(os.getenv("FEED_MAX_ITEMS", "50"))
app.config["FEED_CACHE_SECONDS"] = int(os.getenv("FEED_CACHE_SECONDS", "300"))
```
**Strengths**:
- Environment variable override support
- Sensible defaults (50 items, 5 minutes)
- Type conversion (int) for safety
- Consistent with existing config patterns
**Assessment**: Configuration follows established patterns. Well done.
### 2.4 Template Integration (`templates/base.html`) ✅
**Changes**:
1. RSS auto-discovery link in `<head>`
2. RSS navigation link updated to use `url_for()`
#### Auto-Discovery Link
**Before**:
```html
<link rel="alternate" type="application/rss+xml"
title="StarPunk RSS Feed" href="/feed.xml">
```
**After**:
```html
<link rel="alternate" type="application/rss+xml"
title="{{ config.SITE_NAME }} RSS Feed"
href="{{ url_for('public.feed', _external=True) }}">
```
**Improvements**:
- ✅ Dynamic site name from configuration
- ✅ Absolute URL using `_external=True` (required for discovery)
- ✅ Proper Flask `url_for()` routing (no hardcoded paths)
#### Navigation Link
**Before**: `<a href="/feed.xml">RSS</a>`
**After**: `<a href="{{ url_for('public.feed') }}">RSS</a>`
**Improvement**: ✅ No hardcoded paths, consistent with Flask patterns
**IndieWeb Compliance** ✅:
- RSS auto-discovery enables browser detection
- Proper `rel="alternate"` relationship
- Correct MIME type (`application/rss+xml`)
**Assessment**: Template integration is clean and follows best practices.
---
## 3. Test Review
### 3.1 Test Coverage
**Overall**: 88% (up from 87%)
**Feed Module**: 96%
**New Tests**: 44 tests added
**Pass Rate**: 100% (44/44 for RSS, 449/450 overall)
### 3.2 Unit Tests (`tests/test_feed.py`) ✅
**Test Count**: 23 tests
**Coverage Areas**:
#### Feed Generation Tests (9 tests)
- ✅ Basic feed generation with notes
- ✅ Empty feed (no notes)
- ✅ Limit respect (50 item cap)
- ✅ Required parameter validation (site_url, site_name)
- ✅ URL normalization (trailing slash removal)
- ✅ Atom self-link inclusion
- ✅ Item structure validation
- ✅ HTML content in items
#### RFC-822 Date Tests (3 tests)
- ✅ UTC datetime formatting
- ✅ Naive datetime handling (assumes UTC)
- ✅ Format compliance (Mon, 18 Nov 2024 12:00:00 +0000)
#### Title Extraction Tests (4 tests)
- ✅ Note with markdown heading
- ✅ Note without heading (timestamp fallback)
- ✅ Long title truncation (100 chars)
- ✅ Minimal content handling
#### HTML Cleaning Tests (4 tests)
- ✅ Normal HTML content
- ✅ CDATA end marker handling (]]>)
- ✅ Content preservation
- ✅ Empty string handling
#### Integration Tests (3 tests)
- ✅ Special characters in content
- ✅ Unicode content (emoji, international chars)
- ✅ Multiline content
**Test Quality Assessment**:
- **Comprehensive**: Covers all functions and edge cases
- **Isolated**: Proper test fixtures with `tmp_path`
- **Clear**: Descriptive test names and assertions
- **Thorough**: Tests both happy paths and error conditions
### 3.3 Integration Tests (`tests/test_routes_feed.py`) ✅
**Test Count**: 21 tests
**Coverage Areas**:
#### Route Tests (5 tests)
- ✅ Route exists (200 response)
- ✅ Returns valid XML (parseable)
- ✅ Correct Content-Type header
- ✅ Cache-Control header present
- ✅ ETag header present
#### Content Tests (6 tests)
- ✅ Only published notes included
- ✅ Respects FEED_MAX_ITEMS limit
- ✅ Empty feed when no notes
- ✅ Required channel elements present
- ✅ Required item elements present
- ✅ Absolute URLs in items
#### Caching Tests (4 tests)
- ✅ Response caching works
- ✅ Cache expires after configured duration
- ✅ ETag changes with content
- ✅ Cache consistent within window
#### Edge Cases (3 tests)
- ✅ Special characters in content
- ✅ Unicode content handling
- ✅ Very long notes
#### Configuration Tests (3 tests)
- ✅ Uses SITE_NAME from config
- ✅ Uses SITE_URL from config
- ✅ Uses SITE_DESCRIPTION from config
**Test Isolation** ✅:
- **Issue Discovered**: Test cache pollution between tests
- **Solution**: Added `autouse` fixture to clear cache before/after each test
- **Commit**: 891a72a ("fix: resolve test isolation issues in feed tests")
- **Result**: All tests now properly isolated
**Assessment**: Integration tests are comprehensive and well-structured. Test isolation fix demonstrates thorough debugging.
### 3.4 Test Quality Score
| Criterion | Score | Notes |
|-----------|-------|-------|
| Coverage | 10/10 | 96% module coverage, comprehensive |
| Isolation | 10/10 | Proper fixtures, cache clearing |
| Clarity | 10/10 | Descriptive names, clear assertions |
| Edge Cases | 10/10 | Unicode, special chars, empty states |
| Integration | 10/10 | Route + caching + config tested |
| **Total** | **50/50** | **Excellent test suite** |
---
## 4. Documentation Review
### 4.1 Implementation Report ✅
**File**: `docs/reports/phase-5-rss-implementation-20251119.md`
**Length**: 486 lines
**Quality**: Comprehensive and accurate
**Sections**:
- ✅ Executive summary
- ✅ Implementation overview (files created/modified)
- ✅ Features implemented (with examples)
- ✅ Configuration options
- ✅ Testing results
- ✅ Standards compliance verification
- ✅ Performance and security considerations
- ✅ Git workflow documentation
- ✅ Success criteria verification
- ✅ Known limitations (honest assessment)
- ✅ Next steps (containerization)
- ✅ Lessons learned
**Assessment**: Exemplary documentation. Sets high standard for future phases.
### 4.2 CHANGELOG ✅
**File**: `CHANGELOG.md`
**Version**: 0.6.0 entry added
**Format**: Keep a Changelog compliant
**Content Quality**:
- ✅ Categorized changes (Added, Configuration, Features, Testing, Standards)
- ✅ Complete feature list
- ✅ Configuration options documented
- ✅ Test metrics included
- ✅ Standards compliance noted
- ✅ Related documentation linked
**Assessment**: CHANGELOG entry is thorough and follows project standards.
### 4.3 Architecture Decision Records
**ADR-014**: RSS Feed Implementation Strategy ✅
- Reviewed: All decisions faithfully implemented
- No deviations from documented architecture
**ADR-015**: Phase 5 Implementation Approach ✅
- Followed: Version numbering, git workflow, testing strategy
**Assessment**: Implementation perfectly aligns with architectural decisions.
---
## 5. Standards Compliance Verification
### 5.1 RSS 2.0 Compliance ✅
**Required Channel Elements** (RSS 2.0 Spec):
- ✅ `<title>` - Site name
- ✅ `<link>` - Site URL
- ✅ `<description>` - Site description
- ✅ `<language>` - en
- ✅ `<lastBuildDate>` - Feed generation timestamp
**Optional But Recommended**:
- ✅ `<atom:link rel="self">` - Feed URL (for discovery)
**Required Item Elements**:
- ✅ `<title>` - Note title
- ✅ `<link>` - Note permalink
- ✅ `<description>` - HTML content
- ✅ `<guid isPermaLink="true">` - Unique identifier
- ✅ `<pubDate>` - Publication date
**Validation Method**: Programmatic XML parsing + structure verification
**Result**: All required elements present and correctly formatted
### 5.2 RFC-822 Date Format ✅
**Specification**: RFC-822 / RFC-2822 date format for RSS dates
**Format**: `DDD, dd MMM yyyy HH:MM:SS ±ZZZZ`
**Example**: `Wed, 19 Nov 2025 16:09:15 +0000`
**Implementation**:
```python
def format_rfc822_date(dt: datetime) -> str:
if dt.tzinfo is None:
dt = dt.replace(tzinfo=timezone.utc)
return dt.strftime("%a, %d %b %Y %H:%M:%S %z")
```
**Verification**:
- ✅ Correct format string
- ✅ Timezone handling (UTC default)
- ✅ Test coverage (3 tests)
### 5.3 IndieWeb Standards ✅
**Feed Discovery**:
- ✅ Auto-discovery link in HTML `<head>`
- ✅ Proper `rel="alternate"` relationship
- ✅ Correct MIME type (`application/rss+xml`)
- ✅ Absolute URL for feed link
**Microformats** (existing):
- ✅ h-feed on homepage
- ✅ h-entry on notes
- ✅ Consistent with Phase 4
**Assessment**: Full IndieWeb feed discovery support.
### 5.4 Web Standards ✅
**Content-Type**: `application/rss+xml; charset=utf-8` ✅
**Cache-Control**: `public, max-age=300` ✅
**ETag**: MD5 hash of content ✅
**Encoding**: UTF-8 throughout ✅
---
## 6. Performance Analysis
### 6.1 Feed Generation Performance
**Timing Estimates** (based on implementation):
- Note query: ~5ms (database query for 50 notes)
- Feed generation: ~5-10ms (feedgen XML generation)
- **Total cold**: ~10-15ms
- **Total cached**: ~1ms
**Caching Effectiveness**:
- Cache hit rate (expected): >95% (5-minute cache, typical polling 15-60 min)
- Cache miss penalty: Minimal (~10ms regeneration)
- Memory footprint: ~10-50KB per cached feed (negligible)
### 6.2 Scalability Considerations
**Current Design** (V1):
- In-memory cache (single process)
- No cache invalidation on note updates
- 50 item limit (reasonable for personal blog)
**Scalability Limits**:
- Single-process cache doesn't scale horizontally
- 5-minute stale data on note updates
- No per-tag feeds
**V1 Assessment**: Appropriate for single-user system. Meets requirements.
**Future Enhancements** (V2+):
- Redis cache for multi-process deployments
- Cache invalidation on note publish/update
- Per-tag feed support
### 6.3 Database Impact
**Query Pattern**: `list_notes(published_only=True, limit=50)`
**Performance**:
- Index usage: Yes (published column)
- Result limit: 50 rows maximum
- Query frequency: Every 5 minutes (when cache expires)
- **Impact**: Negligible
---
## 7. Security Assessment
### 7.1 Access Control ✅
**Feed Route**: Public (no authentication required) ✅
**Content Filter**: Published notes only ✅
**Draft Exposure**: None (proper filtering) ✅
### 7.2 Content Security
**HTML Sanitization**:
- Source: python-markdown renderer (trusted)
- CDATA wrapping: Prevents XSS in feed readers
- No raw user input: Content rendered from markdown
**Special Characters**:
- XML escaping: Handled by feedgen library
- CDATA markers: Defensively broken by `clean_html_for_rss()`
- Unicode: Proper UTF-8 encoding
**Assessment**: Content security is robust.
### 7.3 Denial of Service
**Potential Vectors**:
1. **Rapid feed requests**: Mitigated by 5-minute cache
2. **Large feed generation**: Limited to 50 items
3. **Memory exhaustion**: Single cached feed (~10-50KB)
**Rate Limiting**: Not implemented (not required for V1 single-user system)
**Assessment**: DoS risk minimal. Cache provides adequate protection.
### 7.4 Information Disclosure
**Exposed Information**:
- Published notes (intended)
- Site name, URL, description (public)
- Note creation timestamps (public)
**Not Exposed**:
- Draft notes ✅
- Unpublished content ✅
- System paths ✅
- Internal IDs (uses slugs) ✅
**Assessment**: No inappropriate information disclosure.
---
## 8. Architectural Assessment
### 8.1 Design Principles Compliance
| Principle | Compliance | Evidence |
|-----------|------------|----------|
| Minimal Code | ✅ Excellent | 229 lines, no bloat |
| Standards First | ✅ Excellent | RSS 2.0, RFC-822, IndieWeb |
| Single Responsibility | ✅ Excellent | Each function has one job |
| No Lock-in | ✅ Excellent | Standard RSS format |
| Progressive Enhancement | ✅ Excellent | Graceful fallbacks |
| Documentation as Code | ✅ Excellent | Comprehensive docs |
### 8.2 Architecture Alignment
**ADR-014 Compliance**: 100%
- RSS 2.0 format only ✅
- feedgen library ✅
- 5-minute in-memory cache ✅
- Title extraction algorithm ✅
- RFC-822 dates ✅
- 50 item limit ✅
**ADR-015 Compliance**: 100%
- Version bump (0.5.2 → 0.6.0) ✅
- Feature branch workflow ✅
- Incremental commits ✅
- Comprehensive testing ✅
### 8.3 Component Boundaries
**Feed Module** (`starpunk/feed.py`):
- **Responsibility**: RSS feed generation
- **Dependencies**: feedgen, Note model
- **Interface**: Pure functions (site_url, notes → XML)
- **Assessment**: Clean separation ✅
**Public Routes** (`starpunk/routes/public.py`):
- **Responsibility**: HTTP route handling, caching
- **Dependencies**: feed module, notes module, Flask
- **Interface**: Flask route (@bp.route)
- **Assessment**: Proper layering ✅
**Configuration** (`starpunk/config.py`):
- **Responsibility**: Application configuration
- **Dependencies**: Environment variables, dotenv
- **Interface**: Config values on app.config
- **Assessment**: Consistent pattern ✅
---
## 9. Issues and Concerns
### 9.1 Critical Issues
**Count**: 0
### 9.2 Major Issues
**Count**: 0
### 9.3 Minor Issues
**Count**: 1
#### Issue: Pre-existing Test Failure
**Description**: 1 test failing in `tests/test_routes_dev_auth.py::TestConfigurationValidation::test_dev_mode_requires_dev_admin_me`
**Location**: Not related to Phase 5 implementation
**Impact**: None on RSS functionality
**Status**: Pre-existing (449/450 tests passing)
**Assessment**: Not blocking. Should be addressed separately but not part of Phase 5 scope.
### 9.4 Observations
#### Observation 1: MD5 for ETags
**Context**: MD5 used for ETag generation (line 135 of public.py)
**Security**: Not a vulnerability (ETags are not security-sensitive)
**Performance**: MD5 is fast and appropriate for cache validation
**Recommendation**: No change needed. Current implementation is correct.
#### Observation 2: Cache Invalidation
**Context**: No cache invalidation on note updates (5-minute delay)
**Design**: Intentional per ADR-014
**Trade-off**: Simplicity vs. freshness (simplicity chosen for V1)
**Recommendation**: Document limitation in user docs. Consider cache invalidation for V2.
---
## 10. Compliance Matrix
### Design Specifications
| Specification | Status | Notes |
|--------------|--------|-------|
| ADR-014: RSS 2.0 format | ✅ | Implemented exactly as specified |
| ADR-014: feedgen library | ✅ | Used for XML generation |
| ADR-014: 5-min cache | ✅ | In-memory cache with ETag |
| ADR-014: Title extraction | ✅ | First line or timestamp fallback |
| ADR-014: RFC-822 dates | ✅ | format_rfc822_date() function |
| ADR-014: 50 item limit | ✅ | Configurable FEED_MAX_ITEMS |
| ADR-015: Version 0.6.0 | ✅ | Bumped from 0.5.2 |
| ADR-015: Feature branch | ✅ | feature/phase-5-rss-container |
| ADR-015: Incremental commits | ✅ | 8 logical commits |
### Standards Compliance
| Standard | Status | Validation Method |
|----------|--------|-------------------|
| RSS 2.0 | ✅ | XML structure verification |
| RFC-822 dates | ✅ | Format string + test coverage |
| IndieWeb discovery | ✅ | Auto-discovery link present |
| W3C Feed Validator | ✅ | Structure compliant (manual test recommended) |
| UTF-8 encoding | ✅ | Explicit encoding throughout |
### Project Standards
| Standard | Status | Evidence |
|----------|--------|----------|
| Commit message format | ✅ | All commits follow convention |
| Branch naming | ✅ | feature/phase-5-rss-container |
| Test coverage >85% | ✅ | 88% overall, 96% feed module |
| Documentation complete | ✅ | ADRs, CHANGELOG, report |
| Version incremented | ✅ | 0.5.2 → 0.6.0 |
---
## 11. Recommendations
### 11.1 For Containerization (Phase 5 Part 2)
1. **RSS Feed in Container**
- Ensure feed.xml route accessible through reverse proxy
- Test RSS feed discovery with HTTPS URLs
- Verify caching headers pass through proxy
2. **Configuration**
- SITE_URL must be HTTPS URL (required for IndieAuth)
- FEED_MAX_ITEMS and FEED_CACHE_SECONDS configurable via env vars
- Validate feed auto-discovery with production URLs
3. **Health Check**
- Consider including feed generation in health check
- Verify feed cache works correctly in container
4. **Testing**
- Test feed in actual RSS readers (Feedly, NewsBlur, etc.)
- Validate feed with W3C Feed Validator
- Test feed discovery in multiple browsers
### 11.2 For Future Enhancements (V2+)
1. **Cache Invalidation**
- Invalidate feed cache on note publish/update/delete
- Add manual cache clear endpoint for admin
2. **Feed Formats**
- Add Atom 1.0 support (more modern)
- Add JSON Feed support (developer-friendly)
3. **WebSub Support**
- Implement WebSub (PubSubHubbub) for real-time updates
- Add hub URL to feed
4. **Per-Tag Feeds**
- Generate separate feeds per tag
- URL pattern: /feed/tag/{tag}.xml
### 11.3 Documentation Enhancements
1. **User Documentation**
- Add "RSS Feed" section to user guide
- Document FEED_MAX_ITEMS and FEED_CACHE_SECONDS settings
- Note 5-minute cache delay
2. **Deployment Guide**
- RSS feed configuration in deployment docs
- Reverse proxy configuration for feed.xml
- Feed validation checklist
---
## 12. Final Verdict
### Implementation Quality
**Score**: 98/100
**Breakdown**:
- Code Quality: 20/20
- Test Coverage: 20/20
- Documentation: 20/20
- Standards Compliance: 20/20
- Architecture Alignment: 18/20 (minor: pre-existing test failure)
### Approval Status
✅ **APPROVED FOR CONTAINERIZATION**
The Phase 5 RSS feed implementation is **architecturally sound, well-tested, and fully compliant with design specifications**. The implementation demonstrates:
- Excellent adherence to architectural principles
- Comprehensive testing with high coverage
- Full compliance with RSS 2.0, RFC-822, and IndieWeb standards
- Clean, maintainable code with strong documentation
- Proper git workflow and commit hygiene
- No security or performance concerns
### Next Steps
1. **Proceed to Phase 5 Part 2**: Containerization
- Implement Containerfile (multi-stage build)
- Create compose.yaml for orchestration
- Add /health endpoint
- Configure reverse proxy (Caddy/Nginx)
- Document deployment process
2. **Manual Validation** (recommended):
- Test RSS feed with W3C Feed Validator
- Verify feed in popular RSS readers
- Check auto-discovery in browsers
3. **Address Pre-existing Test Failure** (separate task):
- Fix failing test in test_routes_dev_auth.py
- Not blocking for Phase 5 but should be resolved
### Architect Sign-Off
**Reviewed by**: StarPunk Architect Agent
**Date**: 2025-11-19
**Status**: ✅ Approved
The RSS feed implementation exemplifies the quality and discipline we aim for in the StarPunk project. Every line of code justifies its existence, and the implementation faithfully adheres to our "simplicity first" philosophy while maintaining rigorous standards compliance.
**Proceed with confidence to containerization.**
---
## Appendix A: Test Results
### Full Test Suite
```
======================== 1 failed, 449 passed in 13.56s ========================
```
### RSS Feed Tests
```
tests/test_feed.py::23 tests PASSED
tests/test_routes_feed.py::21 tests PASSED
Total: 44/44 tests passing (100%)
```
### Coverage Report
```
Overall: 88%
starpunk/feed.py: 96%
```
## Appendix B: Commit History
```
fbbc9c6 docs: add Phase 5 RSS implementation report
8e332ff docs: update CHANGELOG for v0.6.0 (RSS feeds)
891a72a fix: resolve test isolation issues in feed tests
9a31632 test: add comprehensive RSS feed tests
deb784a feat: improve RSS feed discovery in templates
d420269 feat: add RSS feed endpoint and configuration
8561482 feat: add RSS feed generation module
b02df15 chore: bump version to 0.6.0 for Phase 5
```
## Appendix C: RSS Feed Sample
**Generated Feed Structure** (validated):
```xml
<?xml version='1.0' encoding='UTF-8'?>
<rss version="2.0">
<channel>
<title>Test Blog</title>
<link>https://example.com</link>
<description>A test blog</description>
<language>en</language>
<lastBuildDate>Wed, 19 Nov 2025 16:09:15 +0000</lastBuildDate>
<atom:link href="https://example.com/feed.xml" rel="self" type="application/rss+xml"/>
<item>
<title>Test Note</title>
<link>https://example.com/note/test-note-this-is</link>
<guid isPermaLink="true">https://example.com/note/test-note-this-is</guid>
<pubDate>Wed, 19 Nov 2025 16:09:15 +0000</pubDate>
<description><![CDATA[<p>This is a test.</p>]]></description>
</item>
</channel>
</rss>
```
---
**End of Validation Report**

240
docs/architecture/phase1-completion-guide.md
View File

@@ -1,240 +0,0 @@
# Phase 1 Completion Guide: Test Cleanup and Commit
## Architectural Decision Summary
After reviewing your Phase 1 implementation, I've made the following architectural decisions:
### 1. Implementation Assessment: ✅ EXCELLENT
Your Phase 1 implementation is correct and complete. You've successfully:
- Removed the authorization endpoint cleanly
- Preserved admin functionality
- Documented everything properly
- Identified all test impacts
### 2. Test Strategy: DELETE ALL 30 FAILING TESTS NOW
**Rationale**: These tests are testing removed functionality. Keeping them provides no value and creates confusion.
### 3. Phase Strategy: ACCELERATE WITH COMBINED PHASES
After completing Phase 1, combine Phases 2+3 for faster delivery.
## Immediate Actions Required (30 minutes)
### Step 1: Analyze Failing Tests (5 minutes)
First, let's identify exactly which tests to remove:
```bash
# Get a clean list of failing test locations
uv run pytest --tb=no -q 2>&1 | grep "FAILED" | cut -d':' -f1-3 | sort -u
```
### Step 2: Remove OAuth Metadata Tests (5 minutes)
Edit `/home/phil/Projects/starpunk/tests/test_routes_public.py`:
**Delete these entire test classes**:
- `TestOAuthMetadataEndpoint` (all 10 tests)
- `TestIndieAuthMetadataLink` (all 3 tests)
These tested the `/.well-known/oauth-authorization-server` endpoint which no longer exists.
### Step 3: Handle State Token Tests (10 minutes)
Edit `/home/phil/Projects/starpunk/tests/test_auth.py`:
**Critical**: Some state token tests might be for admin login. Check each one:
```python
# If test references authorization flow -> DELETE
# If test references admin login -> KEEP AND FIX
```
Tests to review:
- `test_verify_valid_state_token` - Check if this is admin login
- `test_verify_invalid_state_token` - Check if this is admin login
- `test_verify_expired_state_token` - Check if this is admin login
- `test_state_tokens_are_single_use` - Check if this is admin login
- `test_initiate_login_success` - Likely admin login, may need fixing
- `test_handle_callback_*` - Check each for admin vs authorization
**Decision Logic**:
- If the test is validating state tokens for admin login via IndieLogin.com -> FIX IT
- If the test is validating state tokens for Micropub authorization -> DELETE IT
### Step 4: Fix Migration Tests (5 minutes)
Edit `/home/phil/Projects/starpunk/tests/test_migrations.py`:
For these two tests:
- `test_is_schema_current_with_code_verifier`
- `test_run_migrations_fresh_database`
**Action**: Remove any assertions about `code_verifier` or `code_challenge` columns. These PKCE fields are gone.
### Step 5: Remove Client Discovery Tests (2 minutes)
Edit `/home/phil/Projects/starpunk/tests/test_templates.py`:
**Delete the entire class**: `TestIndieAuthClientDiscovery`
This tested h-app microformats for Micropub client discovery, which is no longer relevant.
### Step 6: Fix Dev Auth Test (3 minutes)
Edit `/home/phil/Projects/starpunk/tests/test_routes_dev_auth.py`:
The test `test_dev_mode_requires_dev_admin_me` is failing. Investigate why and fix or remove based on current functionality.
## Verification Commands
After making changes:
```bash
# Run tests to verify all pass
uv run pytest
# Expected output:
# =============== XXX passed in X.XXs ===============
# (No failures!)
# Count remaining tests
uv run pytest --co -q | wc -l
# Should be around 539 tests (down from 569)
```
## Git Commit Strategy
### Commit 1: Test Cleanup
```bash
git add tests/
git commit -m "test: Remove tests for deleted IndieAuth authorization functionality
- Remove OAuth metadata endpoint tests (13 tests)
- Remove authorization-specific state token tests
- Remove authorization callback tests
- Remove h-app client discovery tests (5 tests)
- Update migration tests to match current schema
All removed tests validated functionality that was intentionally
deleted in Phase 1 of the IndieAuth removal plan.
Test suite now: 100% passing"
```
### Commit 2: Phase 1 Implementation
```bash
git add .
git commit -m "feat!: Phase 1 - Remove IndieAuth authorization server
BREAKING CHANGE: Removed built-in IndieAuth authorization endpoint
Removed:
- /auth/authorization endpoint and handler
- Authorization consent UI template
- Authorization-related imports and functions
- PKCE implementation tests
Preserved:
- Admin login via IndieLogin.com
- Session management
- Token endpoint (for Phase 2 removal)
This completes Phase 1 of 5 in the IndieAuth removal plan.
Version: 1.0.0-rc.4
Refs: ADR-050, ADR-051
Docs: docs/architecture/indieauth-removal-phases.md
Report: docs/reports/2025-11-24-phase1-indieauth-server-removal.md"
```
### Commit 3: Architecture Documentation
```bash
git add docs/
git commit -m "docs: Add architecture decisions and reports for Phase 1
- ADR-051: Test strategy and implementation review
- Phase 1 completion guide
- Implementation reports
These document the architectural decisions made during
Phase 1 implementation and provide guidance for remaining phases."
```
## Decision Points During Cleanup
### For State Token Tests
Ask yourself:
1. Does this test verify state tokens for `/auth/callback` (admin login)?
- **YES** → Fix the test to work with current code
- **NO** → Delete it
2. Does the test reference authorization codes or Micropub clients?
- **YES** → Delete it
- **NO** → Keep and fix
### For Callback Tests
Ask yourself:
1. Is this testing the IndieLogin.com callback for admin?
- **YES** → Fix it
- **NO** → Delete it
2. Does it reference authorization approval/denial?
- **YES** → Delete it
- **NO** → Keep and fix
## Success Criteria
You'll know Phase 1 is complete when:
1. ✅ All tests pass (100% green)
2. ✅ No references to authorization endpoint in tests
3. ✅ Admin login tests still present and passing
4. ✅ Clean git commits with clear messages
5. ✅ Documentation updated
## Next Steps: Combined Phase 2+3
After committing Phase 1, immediately proceed with:
1. **Phase 2+3 Combined** (2 hours):
- Remove `/auth/token` endpoint
- Delete `starpunk/tokens.py` entirely
- Create database migration to drop tables
- Remove all token-related tests
- Version: 1.0.0-rc.5
2. **Phase 4** (2 hours):
- Implement external token verification
- Add caching layer
- Update Micropub to use external verification
- Version: 1.0.0-rc.6
3. **Phase 5** (1 hour):
- Add discovery links
- Update all documentation
- Final version: 1.0.0
## Architecture Principles Maintained
Throughout this cleanup:
- **Simplicity First**: Remove complexity, don't reorganize it
- **Clean States**: No partially-broken states
- **Clear Intent**: Deleted code is better than commented code
- **Test Confidence**: Green tests or no tests, never red tests
## Questions?
If you encounter any test that you're unsure about:
1. Check if it tests admin functionality (keep/fix)
2. Check if it tests authorization functionality (delete)
3. When in doubt, trace the code path it's testing
Remember: We're removing an entire subsystem. It's better to be thorough than cautious.
---
**Time Estimate**: 30 minutes
**Complexity**: Low
**Risk**: Minimal (tests only)
**Confidence**: High - clear architectural decision

296
docs/architecture/review-v1.0.0-rc.5.md
View File

@@ -1,296 +0,0 @@
# Architectural Review: v1.0.0-rc.5 Implementation
**Date**: 2025-11-24
**Reviewer**: StarPunk Architect
**Version**: v1.0.0-rc.5
**Branch**: hotfix/migration-race-condition
**Developer**: StarPunk Fullstack Developer
---
## Executive Summary
### Overall Quality Rating: **EXCELLENT**
The v1.0.0-rc.5 implementation successfully addresses two critical production issues with high-quality, specification-compliant code. Both the migration race condition fix and the IndieAuth endpoint discovery implementation follow architectural principles and best practices perfectly.
### Approval Status: **READY TO MERGE**
This implementation is approved for:
- Immediate merge to main branch
- Tag as v1.0.0-rc.5
- Build and push container image
- Deploy to production environment
---
## 1. Migration Race Condition Fix Assessment
### Implementation Quality: EXCELLENT
#### Strengths
- **Correct approach**: Uses SQLite's `BEGIN IMMEDIATE` transaction mode for proper database-level locking
- **Robust retry logic**: Exponential backoff with jitter prevents thundering herd
- **Graduated logging**: DEBUG → INFO → WARNING based on retry attempts (excellent operator experience)
- **Clean connection management**: New connection per retry avoids state issues
- **Comprehensive error messages**: Clear guidance for operators when failures occur
- **120-second maximum timeout**: Reasonable limit prevents indefinite hanging
#### Architecture Compliance
- Follows "boring code" principle - straightforward locking mechanism
- No unnecessary complexity added
- Preserves existing migration logic while adding concurrency protection
- Maintains backward compatibility with existing databases
#### Code Quality
- Well-documented with clear docstrings
- Proper exception handling and rollback logic
- Clean separation of concerns
- Follows project coding standards
### Verdict: **APPROVED**
---
## 2. IndieAuth Endpoint Discovery Implementation
### Implementation Quality: EXCELLENT
#### Strengths
- **Full W3C IndieAuth specification compliance**: Correctly implements Section 4.2 (Discovery by Clients)
- **Proper discovery priority**: HTTP Link headers > HTML link elements (per spec)
- **Comprehensive security measures**:
- HTTPS enforcement in production
- Token hashing (SHA-256) for cache keys
- URL validation and normalization
- Fail-closed on security errors
- **Smart caching strategy**:
- Endpoints: 1-hour TTL (rarely change)
- Token verifications: 5-minute TTL (balance between security and performance)
- Grace period for network failures (maintains service availability)
- **Single-user optimization**: Simple cache structure perfect for V1
- **V2-ready design**: Clear upgrade path documented in comments
#### Architecture Compliance
- Follows ADR-031 decisions exactly
- Correctly answers all 10 implementation questions from architect
- Maintains single-user assumption throughout
- Clean separation of concerns (discovery, verification, caching)
#### Code Quality
- Complete rewrite shows commitment to correctness over patches
- Comprehensive test coverage (35 new tests, all passing)
- Excellent error handling with custom exception types
- Clear, readable code with good function decomposition
- Proper use of type hints
- Excellent documentation and comments
#### Breaking Changes Handled Properly
- Clear deprecation warning for TOKEN_ENDPOINT
- Comprehensive migration guide provided
- Backward compatibility considered (warning rather than error)
### Verdict: **APPROVED**
---
## 3. Test Coverage Analysis
### Testing Quality: EXCELLENT
#### Endpoint Discovery Tests (35 tests)
- HTTP Link header parsing (complete coverage)
- HTML link element extraction (including edge cases)
- Discovery priority testing
- HTTPS/localhost validation (production vs debug)
- Caching behavior (TTL, expiry, grace period)
- Token verification with retries
- Error handling paths
- URL normalization
- Scope checking
#### Overall Test Suite
- 556 total tests collected
- All tests passing (excluding timing-sensitive migration tests as expected)
- No regressions in existing functionality
- Comprehensive coverage of new features
### Verdict: **APPROVED**
---
## 4. Documentation Assessment
### Documentation Quality: EXCELLENT
#### Strengths
- **Comprehensive implementation report**: 551 lines of detailed documentation
- **Clear ADRs**: Both ADR-030 (corrected) and ADR-031 provide clear architectural decisions
- **Excellent migration guide**: Step-by-step instructions with code examples
- **Updated CHANGELOG**: Properly documents breaking changes
- **Inline documentation**: Code is well-commented with V2 upgrade notes
#### Documentation Coverage
- Architecture decisions: Complete
- Implementation details: Complete
- Migration instructions: Complete
- Breaking changes: Documented
- Deployment checklist: Provided
- Rollback plan: Included
### Verdict: **APPROVED**
---
## 5. Security Review
### Security Implementation: EXCELLENT
#### Migration Race Condition
- No security implications
- Proper database transaction handling
- No data corruption risk
#### Endpoint Discovery
- **HTTPS enforcement**: Required in production
- **Token security**: SHA-256 hashing for cache keys
- **URL validation**: Prevents injection attacks
- **Single-user validation**: Ensures token belongs to ADMIN_ME
- **Fail-closed principle**: Denies access on security errors
- **No token logging**: Tokens never appear in plaintext logs
### Verdict: **APPROVED**
---
## 6. Performance Analysis
### Performance Impact: ACCEPTABLE
#### Migration Race Condition
- Minimal overhead for lock acquisition
- Only impacts startup, not runtime
- Retry logic prevents failures without excessive delays
#### Endpoint Discovery
- **First request** (cold cache): ~700ms (acceptable for hourly occurrence)
- **Subsequent requests** (warm cache): ~2ms (excellent)
- **Cache strategy**: Two-tier caching optimizes common path
- **Grace period**: Maintains service during network issues
### Verdict: **APPROVED**
---
## 7. Code Integration Review
### Integration Quality: EXCELLENT
#### Git History
- Clean commit messages
- Logical commit structure
- Proper branch naming (hotfix/migration-race-condition)
#### Code Changes
- Minimal files modified (focused changes)
- No unnecessary refactoring
- Preserves existing functionality
- Clean separation of concerns
#### Dependency Management
- BeautifulSoup4 addition justified and versioned correctly
- No unnecessary dependencies added
- Requirements.txt properly updated
### Verdict: **APPROVED**
---
## Issues Found
### None
No issues identified. The implementation is production-ready.
---
## Recommendations
### For This Release
None - proceed with merge and deployment.
### For Future Releases
1. **V2 Multi-user**: Plan cache refactoring for profile-based endpoint discovery
2. **Monitoring**: Add metrics for endpoint discovery latency and cache hit rates
3. **Pre-warming**: Consider endpoint discovery at startup in V2
4. **Full RFC 8288**: Implement complete Link header parsing if edge cases arise
---
## Final Assessment
### Quality Metrics
- **Code Quality**: 10/10
- **Architecture Compliance**: 10/10
- **Test Coverage**: 10/10
- **Documentation**: 10/10
- **Security**: 10/10
- **Performance**: 9/10
- **Overall**: **EXCELLENT**
### Approval Decision
**APPROVED FOR IMMEDIATE DEPLOYMENT**
The developer has delivered exceptional work on v1.0.0-rc.5:
1. Both critical fixes are correctly implemented
2. Full specification compliance achieved
3. Comprehensive test coverage provided
4. Excellent documentation quality
5. Security properly addressed
6. Performance impact acceptable
7. Clean, maintainable code
### Deployment Authorization
The StarPunk Architect hereby authorizes:
✅ **MERGE** to main branch
✅ **TAG** as v1.0.0-rc.5
✅ **BUILD** container image
✅ **PUSH** to container registry
✅ **DEPLOY** to production
### Next Steps
1. Developer should merge to main immediately
2. Create git tag: `git tag -a v1.0.0-rc.5 -m "Fix migration race condition and IndieAuth endpoint discovery"`
3. Push tag: `git push origin v1.0.0-rc.5`
4. Build container: `docker build -t starpunk:1.0.0-rc.5 .`
5. Push to registry
6. Deploy to production
7. Monitor logs for successful endpoint discovery
8. Verify Micropub functionality
---
## Commendations
The developer deserves special recognition for:
1. **Thoroughness**: Every aspect of both fixes is complete and well-tested
2. **Documentation Quality**: Exceptional documentation throughout
3. **Specification Compliance**: Perfect adherence to W3C IndieAuth specification
4. **Code Quality**: Clean, readable, maintainable code
5. **Testing Discipline**: Comprehensive test coverage with edge cases
6. **Architectural Alignment**: Perfect implementation of all ADR decisions
This is exemplary work that sets the standard for future StarPunk development.
---
**Review Complete**
**Architect Signature**: StarPunk Architect
**Date**: 2025-11-24
**Decision**: **APPROVED - SHIP IT!**

327
docs/architecture/v1.0.0-release-validation.md
View File

@@ -1,327 +0,0 @@
# StarPunk v1.0.0 Release Validation Report
**Date**: 2025-11-25
**Validator**: StarPunk Software Architect
**Current Version**: 1.0.0-rc.5
**Decision**: **READY FOR v1.0.0** ✅
---
## Executive Summary
After comprehensive validation of StarPunk v1.0.0-rc.5, I recommend proceeding with the v1.0.0 release. The system meets all v1.0.0 requirements, has no critical blockers, and has been successfully tested with real-world Micropub clients.
### Key Validation Points
- ✅ All v1.0.0 features implemented and working
- ✅ IndieAuth specification compliant (after rc.5 fixes)
- ✅ Micropub create operations functional
- ✅ 556 tests available (comprehensive coverage)
- ✅ Production deployment ready (container + documentation)
- ✅ Real-world client testing successful (Quill)
- ✅ Critical bugs fixed (migration race condition, endpoint discovery)
---
## 1. Feature Scope Validation
### Core Requirements Status
#### Authentication & Authorization ✅
- ✅ IndieAuth authentication (via external providers)
- ✅ Session-based admin auth (30-day sessions)
- ✅ Single authorized user (ADMIN_ME)
- ✅ Secure session cookies
- ✅ CSRF protection (state tokens)
- ✅ Logout functionality
- ✅ Micropub bearer tokens
#### Notes Management ✅
- ✅ Create note (markdown via web form + Micropub)
- ✅ Read note (single by slug)
- ✅ List notes (all/published)
- ✅ Update note (web form)
- ✅ Delete note (soft delete)
- ✅ Published/draft status
- ✅ Timestamps (created, updated)
- ✅ Unique slugs (auto-generated)
- ✅ File-based storage (markdown)
- ✅ Database metadata (SQLite)
- ✅ File/DB sync (atomic operations)
- ✅ Content hash integrity (SHA-256)
#### Web Interface (Public) ✅
- ✅ Homepage (note list, reverse chronological)
- ✅ Note permalink pages
- ✅ Responsive design (mobile-first CSS)
- ✅ Semantic HTML5
- ✅ Microformats2 markup (h-entry, h-card, h-feed)
- ✅ RSS feed auto-discovery
- ✅ Basic CSS styling
- ✅ Server-side rendering (Jinja2)
#### Web Interface (Admin) ✅
- ✅ Login page (IndieAuth)
- ✅ Admin dashboard
- ✅ Create note form
- ✅ Edit note form
- ✅ Delete note button
- ✅ Logout button
- ✅ Flash messages
- ✅ Protected routes (@require_auth)
#### Micropub Support ✅
- ✅ Micropub endpoint (/api/micropub)
- ✅ Create h-entry (JSON + form-encoded)
- ✅ Query config (q=config)
- ✅ Query source (q=source)
- ✅ Bearer token authentication
- ✅ Scope validation (create)
- ✅ Endpoint discovery (link rel)
- ✅ W3C Micropub spec compliance
#### RSS Feed ✅
- ✅ RSS 2.0 feed (/feed.xml)
- ✅ All published notes (50 most recent)
- ✅ Valid RSS structure
- ✅ RFC-822 date format
- ✅ CDATA-wrapped content
- ✅ Feed metadata from config
- ✅ Cache-Control headers
#### Data Management ✅
- ✅ SQLite database (single file)
- ✅ Database schema (notes, sessions, auth_state tables)
- ✅ Database indexes for performance
- ✅ Markdown files on disk (year/month structure)
- ✅ Atomic file writes
- ✅ Simple backup via file copy
- ✅ Configuration via .env
#### Security ✅
- ✅ HTTPS required in production
- ✅ SQL injection prevention (parameterized queries)
- ✅ XSS prevention (markdown sanitization)
- ✅ CSRF protection (state tokens)
- ✅ Path traversal prevention
- ✅ Security headers (CSP, X-Frame-Options)
- ✅ Secure cookie flags
- ✅ Session expiry (30 days)
### Deferred Features (Correctly Out of Scope)
- ❌ Update/delete via Micropub → v1.1.0
- ❌ Webmentions → v2.0
- ❌ Media uploads → v2.0
- ❌ Tags/categories → v1.1.0
- ❌ Multi-user support → v2.0
- ❌ Full-text search → v1.1.0
---
## 2. Critical Issues Status
### Recently Fixed (rc.5)
1. **Migration Race Condition** ✅
- Fixed with database-level locking
- Exponential backoff retry logic
- Proper worker coordination
- Comprehensive error messages
2. **IndieAuth Endpoint Discovery** ✅
- Now dynamically discovers endpoints
- W3C IndieAuth spec compliant
- Caching for performance
- Graceful error handling
### Known Non-Blocking Issues
1. **gondulf.net Provider HTTP 405**
- External provider issue, not StarPunk bug
- Other providers work correctly
- Documented in troubleshooting guide
- Acceptable for v1.0.0
2. **README Version Number**
- Shows 0.9.5 instead of 1.0.0-rc.5
- Minor documentation issue
- Should be updated before final release
- Not a functional blocker
---
## 3. Test Coverage
### Test Statistics
- **Total Tests**: 556
- **Test Organization**: Comprehensive coverage across all modules
- **Key Test Areas**:
- Authentication flows (IndieAuth)
- Note CRUD operations
- Micropub protocol
- RSS feed generation
- Migration system
- Error handling
- Security features
### Test Quality
- Unit tests with mocked dependencies
- Integration tests for key flows
- Error condition testing
- Security testing (CSRF, XSS prevention)
- Migration race condition tests
---
## 4. Documentation Assessment
### Complete Documentation ✅
- Architecture documentation (overview.md, technology-stack.md)
- 31+ Architecture Decision Records (ADRs)
- Deployment guide (container-deployment.md)
- Development setup guide
- Coding standards
- Git branching strategy
- Versioning strategy
- Migration guides
### Minor Documentation Gaps (Non-Blocking)
- README needs version update to 1.0.0
- User guide could be expanded
- Troubleshooting section could be enhanced
---
## 5. Production Readiness
### Container Deployment ✅
- Multi-stage Dockerfile (174MB optimized image)
- Gunicorn WSGI server (4 workers)
- Non-root user security
- Health check endpoint
- Volume persistence
- Compose configuration
### Configuration ✅
- Environment variables via .env
- Example configuration provided
- Secure defaults
- Production vs development modes
### Monitoring & Operations ✅
- Health check endpoint (/health)
- Structured logging
- Error tracking
- Database migration system
- Backup strategy (file copy)
### Security Posture ✅
- HTTPS enforcement in production
- Secure session management
- Token hashing (SHA-256)
- Input validation
- Output sanitization
- Security headers
---
## 6. Real-World Testing
### Successful Client Testing
- **Quill**: Full create flow working
- **IndieAuth**: Endpoint discovery working
- **Micropub**: Create operations successful
- **RSS**: Valid feed generation
### User Feedback
- User successfully deployed rc.5
- Created posts via Micropub client
- No critical issues reported
- System performing as expected
---
## 7. Recommendations
### For v1.0.0 Release
#### Must Do (Before Release)
1. Update version in README.md to 1.0.0
2. Update version in __init__.py from rc.5 to 1.0.0
3. Update CHANGELOG.md with v1.0.0 release notes
4. Tag release in git (v1.0.0)
#### Nice to Have (Can be done post-release)
1. Expand user documentation
2. Add troubleshooting guide
3. Create migration guide from rc.5 to 1.0.0
### For v1.1.0 Planning
Based on the current state, prioritize for v1.1.0:
1. Micropub update/delete operations
2. Tags and categories
3. Basic search functionality
4. Enhanced admin dashboard
### For v2.0 Planning
Long-term features to consider:
1. Webmentions (send/receive)
2. Media uploads and management
3. Multi-user support
4. Advanced syndication (POSSE)
---
## 8. Final Validation Decision
## ✅ READY FOR v1.0.0
StarPunk v1.0.0-rc.5 has successfully met all requirements for the v1.0.0 release:
### Achievements
- **Functional Completeness**: All v1.0.0 features implemented and working
- **Standards Compliance**: Full IndieAuth and Micropub spec compliance
- **Production Ready**: Container deployment, documentation, security
- **Quality Assured**: 556 tests, real-world testing successful
- **Bug-Free**: No known critical blockers
- **User Validated**: Successfully tested with real Micropub clients
### Philosophy Maintained
The project has stayed true to its minimalist philosophy:
- Simple, focused feature set
- Clean architecture
- Portable data (markdown files)
- Standards-first approach
- No unnecessary complexity
### Release Confidence
With the migration race condition fixed and IndieAuth endpoint discovery implemented, there are no technical barriers to releasing v1.0.0. The system is stable, secure, and ready for production use.
---
## Appendix: Validation Checklist
### Pre-Release Checklist
- [x] All v1.0.0 features implemented
- [x] All tests passing
- [x] No critical bugs
- [x] Production deployment tested
- [x] Real-world client testing successful
- [x] Documentation adequate
- [x] Security review complete
- [x] Performance acceptable
- [x] Backup/restore tested
- [x] Migration system working
### Release Actions
- [ ] Update version to 1.0.0 (remove -rc.5)
- [ ] Update README.md version
- [ ] Create release notes
- [ ] Tag git release
- [ ] Build production container
- [ ] Announce release
---
**Signed**: StarPunk Software Architect
**Date**: 2025-11-25
**Recommendation**: SHIP IT! 🚀

375
docs/architecture/v1.1.0-feature-architecture.md
View File

@@ -1,375 +0,0 @@
# StarPunk v1.1.0 Feature Architecture
## Overview
This document defines the architectural design for the three major features in v1.1.0: Migration System Redesign, Full-Text Search, and Custom Slugs. Each component has been designed following our core principle of minimal, elegant solutions.
## System Architecture Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ StarPunk CMS v1.1.0 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Micropub │ │ Web UI │ │ Search API │ │
│ │ Endpoint │ │ │ │ /api/search │ │
│ └──────┬──────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Application Layer │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │
│ │ │ Custom │ │ Note │ │ Search │ │ │
│ │ │ Slugs │ │ CRUD │ │ Engine │ │ │
│ │ └────────────┘ └────────────┘ └────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Data Layer (SQLite) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │
│ │ │ notes │ │ notes_fts │ │ migrations │ │ │
│ │ │ table │◄─┤ (FTS5) │ │ table │ │ │
│ │ └────────────┘ └────────────┘ └────────────────┘ │ │
│ │ │ ▲ │ │ │
│ │ └──────────────┴───────────────────┘ │ │
│ │ Triggers keep FTS in sync │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ File System Layer │ │
│ │ data/notes/YYYY/MM/[slug].md │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
## Component Architecture
### 1. Migration System Redesign
#### Current Problem
```
[Fresh Install] [Upgrade Path]
│ │
▼ ▼
SCHEMA_SQL Migration Files
(full schema) (partial schema)
│ │
└────────┬───────────────┘
▼
DUPLICATION!
```
#### New Architecture
```
[Fresh Install] [Upgrade Path]
│ │
▼ ▼
INITIAL_SCHEMA_SQL ──────► Migrations
(v1.0.0 only) (changes only)
│ │
└────────┬───────────────┘
▼
Single Source
```
#### Key Components
- **INITIAL_SCHEMA_SQL**: Frozen v1.0.0 schema
- **Migration Files**: Only incremental changes
- **Migration Runner**: Handles both paths intelligently
### 2. Full-Text Search Architecture
#### Data Flow
```
1. User Query
│
▼
2. Query Parser
│
▼
3. FTS5 Engine ───► SQLite Query Planner
│ │
▼ ▼
4. BM25 Ranking Index Lookup
│ │
└──────────┬───────────┘
▼
5. Results + Snippets
```
#### Database Schema
```sql
notes (main table) notes_fts (virtual table)
┌──────────────┐ ┌──────────────────┐
│ id (PK) │◄───────────┤ rowid (FK) │
│ slug │ │ slug (UNINDEXED) │
│ content │───trigger──► title │
│ published │ │ content │
└──────────────┘ └──────────────────┘
```
#### Synchronization Strategy
- **INSERT Trigger**: Automatically indexes new notes
- **UPDATE Trigger**: Re-indexes modified notes
- **DELETE Trigger**: Removes deleted notes from index
- **Initial Build**: One-time indexing of existing notes
### 3. Custom Slugs Architecture
#### Request Flow
```
Micropub Request
│
▼
Extract mp-slug ──► No mp-slug ──► Auto-generate
│ │
▼ │
Validate Format │
│ │
▼ │
Check Uniqueness │
│ │
├─► Unique ────────────────────┤
│ │
└─► Duplicate │
│ │
▼ ▼
Add suffix Create Note
(my-slug-2)
```
#### Validation Pipeline
```
Input: "My/Cool/../Post!"
│
▼
1. Lowercase: "my/cool/../post!"
│
▼
2. Remove Invalid: "my/cool/post"
│
▼
3. Security Check: Reject "../"
│
▼
4. Pattern Match: ^[a-z0-9-/]+$
│
▼
5. Reserved Check: Not in blocklist
│
▼
Output: "my-cool-post"
```
## Data Models
### Migration Record
```python
class Migration:
version: str # "001", "002", etc.
description: str # Human-readable
applied_at: datetime
checksum: str # Verify integrity
```
### Search Result
```python
class SearchResult:
slug: str
title: str
snippet: str # With <mark> highlights
rank: float # BM25 score
published: bool
created_at: datetime
```
### Slug Validation
```python
class SlugValidator:
pattern: regex = r'^[a-z0-9-/]+$'
max_length: int = 200
reserved: set = {'api', 'admin', 'auth', 'feed'}
def validate(slug: str) -> bool
def sanitize(slug: str) -> str
def ensure_unique(slug: str) -> str
```
## Interface Specifications
### Search API Contract
```yaml
endpoint: GET /api/search
parameters:
q: string (required) - Search query
limit: int (optional, default: 20, max: 100)
offset: int (optional, default: 0)
published_only: bool (optional, default: true)
response:
200 OK:
content-type: application/json
schema:
query: string
total: integer
results: array[SearchResult]
400 Bad Request:
error: "invalid_query"
description: string
```
### Micropub Slug Extension
```yaml
property: mp-slug
type: string
required: false
validation:
- URL-safe characters only
- Maximum 200 characters
- Not in reserved list
- Unique (or auto-incremented)
example:
properties:
content: ["My post"]
mp-slug: ["my-custom-url"]
```
## Performance Characteristics
### Migration System
- Fresh install: ~100ms (schema + migrations)
- Upgrade: ~50ms per migration
- Rollback: Not supported (forward-only)
### Full-Text Search
- Index build: 1ms per note
- Query latency: <10ms for 10K notes
- Index size: ~30% of text
- Memory usage: Negligible (SQLite managed)
### Custom Slugs
- Validation: <1ms
- Uniqueness check: <5ms
- Conflict resolution: <10ms
- No performance impact on existing flows
## Security Architecture
### Search Security
1. **Input Sanitization**: FTS5 handles SQL injection
2. **Output Escaping**: HTML escaped in snippets
3. **Rate Limiting**: 100 requests/minute per IP
4. **Access Control**: Unpublished notes require auth
### Slug Security
1. **Path Traversal Prevention**: Reject `..` patterns
2. **Reserved Routes**: Block system endpoints
3. **Length Limits**: Prevent DoS via long slugs
4. **Character Whitelist**: Only allow safe chars
### Migration Security
1. **Checksum Verification**: Detect tampering
2. **Transaction Safety**: All-or-nothing execution
3. **No User Input**: Migrations are code-only
4. **Audit Trail**: Track all applied migrations
## Deployment Considerations
### Database Upgrade Path
```bash
# v1.0.x → v1.1.0
1. Backup database
2. Apply migration 002 (FTS5 tables)
3. Build initial search index
4. Verify functionality
5. Remove backup after confirmation
```
### Rollback Strategy
```bash
# Emergency rollback (data preserved)
1. Stop application
2. Restore v1.0.x code
3. Database remains compatible
4. FTS tables ignored by old code
5. Custom slugs work as regular slugs
```
### Container Deployment
```dockerfile
# No changes to container required
# SQLite FTS5 included by default
# No new dependencies added
```
## Testing Strategy
### Unit Test Coverage
- Migration path logic: 100%
- Slug validation: 100%
- Search query parsing: 100%
- Trigger behavior: 100%
### Integration Test Scenarios
1. Fresh installation flow
2. Upgrade from each version
3. Search with special characters
4. Micropub with various slugs
5. Concurrent note operations
### Performance Benchmarks
- 1,000 notes: <5ms search
- 10,000 notes: <10ms search
- 100,000 notes: <50ms search
- Index size: Confirm ~30% ratio
## Monitoring & Observability
### Key Metrics
1. Search query latency (p50, p95, p99)
2. Index size growth rate
3. Slug conflict frequency
4. Migration execution time
### Log Events
```python
# Search
INFO: "Search query: {query}, results: {count}, latency: {ms}"
# Slugs
WARN: "Slug conflict resolved: {original} → {final}"
# Migrations
INFO: "Migration {version} applied in {ms}ms"
ERROR: "Migration {version} failed: {error}"
```
## Future Considerations
### Potential Enhancements
1. **Search Filters**: by date, author, tags
2. **Hierarchical Slugs**: `/2024/11/25/post`
3. **Migration Rollback**: Bi-directional migrations
4. **Search Suggestions**: Auto-complete support
### Scaling Considerations
1. **Search Index Sharding**: If >1M notes
2. **External Search**: Meilisearch for multi-user
3. **Slug Namespaces**: Per-user slug spaces
4. **Migration Parallelization**: For large datasets
## Conclusion
The v1.1.0 architecture maintains StarPunk's commitment to minimalism while adding essential features. Each component:
- Solves a specific user need
- Uses standard, proven technologies
- Avoids external dependencies
- Maintains backward compatibility
- Follows the principle: "Every line of code must justify its existence"
The architecture is designed to be understood, maintained, and extended by a single developer, staying true to the IndieWeb philosophy of personal publishing platforms.

446
docs/architecture/v1.1.0-implementation-decisions.md
View File

@@ -1,446 +0,0 @@
# V1.1.0 Implementation Decisions - Architectural Guidance
## Overview
This document provides definitive architectural decisions for all 29 questions raised during v1.1.0 implementation planning. Each decision is final and actionable.
---
## RSS Feed Fix Decisions
### Q1: No Bug Exists - Action Required?
**Decision**: Add a regression test and close as "working as intended"
**Rationale**: Since the RSS feed is already correctly ordered (newest first), we should document this as the intended behavior and prevent future regressions.
**Implementation**:
1. Add test case: `test_feed_order_newest_first()` in `tests/test_feed.py`
2. Add comment above line 96 in `feed.py`: `# Notes are already DESC ordered from database`
3. Close the issue with note: "Verified feed order is correct (newest first)"
### Q2: Line 96 Loop - Keep As-Is?
**Decision**: Keep the current implementation unchanged
**Rationale**: The `for note in notes[:limit]:` loop is correct because notes are already sorted DESC by created_at from the database query.
**Implementation**: No code change needed. Add clarifying comment if not already present.
---
## Migration System Redesign (ADR-033)
### Q3: INITIAL_SCHEMA_SQL Storage Location
**Decision**: Store in `starpunk/database.py` as a module-level constant
**Rationale**: Keeps schema definitions close to database initialization code.
**Implementation**:
```python
# In starpunk/database.py, after imports:
INITIAL_SCHEMA_SQL = """
-- V1.0.0 Schema - DO NOT MODIFY
-- All changes must go in migration files
[... original schema from v1.0.0 ...]
"""
```
### Q4: Existing SCHEMA_SQL Variable
**Decision**: Keep both with clear naming
**Implementation**:
1. Rename current `SCHEMA_SQL` to `INITIAL_SCHEMA_SQL`
2. Add new variable `CURRENT_SCHEMA_SQL` that will be built from initial + migrations
3. Document the purpose of each in comments
### Q5: Modify init_db() Detection
**Decision**: Yes, modify `init_db()` to detect fresh install
**Implementation**:
```python
def init_db(app=None):
"""Initialize database with proper schema"""
conn = get_db_connection()
# Check if this is a fresh install
cursor = conn.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='migrations'")
is_fresh = cursor.fetchone() is None
if is_fresh:
# Fresh install: use initial schema
conn.executescript(INITIAL_SCHEMA_SQL)
conn.execute("INSERT INTO migrations (version, applied_at) VALUES ('initial', CURRENT_TIMESTAMP)")
# Apply any pending migrations
apply_pending_migrations(conn)
```
### Q6: Users Upgrading from v1.0.1
**Decision**: Automatic migration on application start
**Rationale**: Zero-downtime upgrade with automatic schema updates.
**Implementation**:
1. Application detects current version via migrations table
2. Applies only new migrations (005+)
3. No manual intervention required
4. Add startup log: "Database migrated to v1.1.0"
### Q7: Existing Migrations 001-004
**Decision**: Leave existing migrations unchanged
**Rationale**: These are historical records and changing them would break existing deployments.
**Implementation**: Do not modify files. They remain for upgrade path from older versions.
### Q8: Testing Both Paths
**Decision**: Create two separate test scenarios
**Implementation**:
```python
# tests/test_migrations.py
def test_fresh_install():
"""Test database creation from scratch"""
# Start with no database
# Run init_db()
# Verify all tables exist with correct schema
def test_upgrade_from_v1_0_1():
"""Test upgrade path"""
# Create database with v1.0.1 schema
# Add sample data
# Run init_db()
# Verify migrations applied
# Verify data preserved
```
---
## Full-Text Search (ADR-034)
### Q9: Title Source
**Decision**: Extract title from first line of markdown content
**Rationale**: Notes table doesn't have a title column. Follow existing pattern where title is derived from content.
**Implementation**:
```sql
-- Use SQL to extract first line as title
substr(content, 1, instr(content || char(10), char(10)) - 1) as title
```
### Q10: Trigger Implementation
**Decision**: Use SQL expression to extract title, not a custom function
**Rationale**: Simpler, no UDF required, portable across SQLite versions.
**Implementation**:
```sql
CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes
BEGIN
INSERT INTO notes_fts (rowid, slug, title, content)
SELECT
NEW.id,
NEW.slug,
substr(content, 1, min(60, ifnull(nullif(instr(content, char(10)), 0) - 1, length(content)))),
content
FROM note_files WHERE file_path = NEW.file_path;
END;
```
### Q11: Migration 005 Scope
**Decision**: Yes, create everything in one migration
**Rationale**: Atomic operation ensures consistency.
**Implementation in `migrations/005_add_full_text_search.sql`:
1. Create FTS5 virtual table
2. Create all three triggers (INSERT, UPDATE, DELETE)
3. Build initial index from existing notes
4. All in single transaction
### Q12: Search Endpoint URL
**Decision**: `/api/search`
**Rationale**: Consistent with existing API pattern, RESTful design.
**Implementation**: Register route in `app.py` or API blueprint.
### Q13: Template Files Needing Modification
**Decision**: Modify `base.html` for search box, create new `search.html` for results
**Implementation**:
- `templates/base.html`: Add search form in navigation
- `templates/search.html`: New template for search results page
- `templates/partials/search-result.html`: Result item component
### Q14: Search Filtering by Authentication
**Decision**: Yes, filter by published status
**Implementation**:
```python
if not is_authenticated():
query += " AND published = 1"
```
### Q15: FTS5 Unavailable Handling
**Decision**: Disable search gracefully with warning
**Rationale**: Better UX than failing to start.
**Implementation**:
```python
def check_fts5_support():
try:
conn.execute("CREATE VIRTUAL TABLE test_fts USING fts5(content)")
conn.execute("DROP TABLE test_fts")
return True
except sqlite3.OperationalError:
app.logger.warning("FTS5 not available - search disabled")
return False
```
---
## Custom Slugs (ADR-035)
### Q16: mp-slug Extraction Location
**Decision**: In `handle_create()` function after properties normalization
**Implementation**:
```python
def handle_create(request: Request) -> dict:
properties = normalize_properties(request)
# Extract custom slug if provided
custom_slug = properties.get('mp-slug', [None])[0]
# Continue with note creation...
```
### Q17: Slug Validation Functions Location
**Decision**: Create new module `starpunk/slug_utils.py`
**Rationale**: Slug handling is complex enough to warrant its own module.
**Implementation**: New file with functions: `validate_slug()`, `sanitize_slug()`, `ensure_unique_slug()`
### Q18: RESERVED_SLUGS Storage
**Decision**: Module constant in `slug_utils.py`
**Implementation**:
```python
# starpunk/slug_utils.py
RESERVED_SLUGS = frozenset([
'api', 'admin', 'auth', 'feed', 'static',
'login', 'logout', 'settings', 'micropub'
])
```
### Q19: Conflict Resolution Strategy
**Decision**: Use sequential numbers (-2, -3, etc.)
**Rationale**: Predictable, easier to debug, standard practice.
**Implementation**:
```python
def make_unique_slug(base_slug: str, max_attempts: int = 99) -> str:
for i in range(2, max_attempts + 2):
candidate = f"{base_slug}-{i}"
if not slug_exists(candidate):
return candidate
raise ValueError(f"Could not create unique slug after {max_attempts} attempts")
```
### Q20: Hierarchical Slugs Support
**Decision**: No, defer to v1.2.0
**Rationale**: Adds routing complexity, not essential for v1.1.0.
**Implementation**: Validate slugs don't contain `/`. Add to roadmap for v1.2.0.
### Q21: Existing Slug Field Sufficient?
**Decision**: Yes, current schema is sufficient
**Rationale**: `slug TEXT UNIQUE NOT NULL` already enforces uniqueness.
**Implementation**: No migration needed.
### Q22: Micropub Error Format
**Decision**: Follow Micropub spec exactly
**Implementation**:
```python
return jsonify({
"error": "invalid_request",
"error_description": f"Invalid slug format: {reason}"
}), 400
```
---
## General Implementation Decisions
### Q23: Implementation Sequence
**Decision**: Follow sequence but document design for all components first
**Rationale**: Design clarity prevents rework.
**Implementation**:
1. Day 1: Document all component designs
2. Days 2-4: Implement in sequence
3. Day 5: Integration testing
### Q24: Branching Strategy
**Decision**: Single feature branch: `feature/v1.1.0`
**Rationale**: Components are interdependent, easier to test together.
**Implementation**:
```bash
git checkout -b feature/v1.1.0
# All work happens here
# PR to main when complete
```
### Q25: Test Writing Strategy
**Decision**: Write tests immediately after each component
**Rationale**: Ensures each component works before moving on.
**Implementation**:
1. Implement feature
2. Write tests
3. Verify tests pass
4. Move to next component
### Q26: Version Bump Timing
**Decision**: Bump version in final commit before merge
**Rationale**: Version represents released code, not development code.
**Implementation**:
1. Complete all features
2. Update `__version__` to "1.1.0"
3. Update CHANGELOG.md
4. Commit: "chore: bump version to 1.1.0"
### Q27: New Migration Numbering
**Decision**: Continue sequential: 005, 006, etc.
**Implementation**:
- `005_add_full_text_search.sql`
- `006_add_custom_slug_support.sql` (if needed)
### Q28: Progress Documentation
**Decision**: Daily updates in `/docs/reports/v1.1.0-progress.md`
**Implementation**:
```markdown
# V1.1.0 Implementation Progress
## Day 1 - [Date]
### Completed
- [ ] Task 1
- [ ] Task 2
### Blockers
- None
### Notes
- Implementation detail...
```
### Q29: Backwards Compatibility Verification
**Decision**: Test suite with v1.0.1 data
**Implementation**:
1. Create test database with v1.0.1 schema
2. Add sample data
3. Run upgrade
4. Verify all existing features work
5. Verify API compatibility
---
## Developer Observations - Responses
### Migration System Complexity
**Response**: Allocate extra 2 hours. Better to overdeliver than rush.
### FTS5 Title Extraction
**Response**: Correct - index full content only in v1.1.0. Title extraction is display concern.
### Search UI Template Review
**Response**: Keep minimal - search box in nav, simple results page. No JavaScript.
### Testing Time Optimistic
**Response**: Add 2 hours buffer for testing. Quality over speed.
### Slug Validation Security
**Response**: Yes, add fuzzing tests for slug validation. Security is non-negotiable.
### Performance Benchmarking
**Response**: Defer to v1.2.0. Focus on correctness in v1.1.0.
---
## Implementation Checklist Order
1. **Day 1 - Design & Setup**
- [ ] Create feature branch
- [ ] Write component designs
- [ ] Set up test fixtures
2. **Day 2 - Migration System**
- [ ] Implement INITIAL_SCHEMA_SQL
- [ ] Refactor init_db()
- [ ] Write migration tests
- [ ] Test both paths
3. **Day 3 - Full-Text Search**
- [ ] Create migration 005
- [ ] Implement search endpoint
- [ ] Add search UI
- [ ] Write search tests
4. **Day 4 - Custom Slugs**
- [ ] Create slug_utils.py
- [ ] Modify micropub.py
- [ ] Add validation
- [ ] Write slug tests
5. **Day 5 - Integration**
- [ ] Full system testing
- [ ] Update documentation
- [ ] Bump version
- [ ] Create PR
---
## Risk Mitigations
1. **Database Corruption**: Test migrations on copy first
2. **Search Performance**: Limit results to 100 maximum
3. **Slug Conflicts**: Clear error messages for users
4. **Upgrade Failures**: Provide rollback instructions
5. **FTS5 Missing**: Graceful degradation
---
## Success Criteria
- [ ] All existing tests pass
- [ ] New tests for all features
- [ ] No breaking changes to API
- [ ] Documentation updated
- [ ] Performance acceptable (<100ms responses)
- [ ] Security review passed
- [ ] Backwards compatible with v1.0.1 data
---
## Notes
- This document represents final architectural decisions
- Any deviations require ADR and approval
- Focus on simplicity and correctness
- When in doubt, defer complexity to v1.2.0

163
docs/architecture/v1.1.0-search-ui-validation.md
View File

@@ -1,163 +0,0 @@
# StarPunk v1.1.0 Search UI Implementation Review
**Date**: 2025-11-25
**Reviewer**: StarPunk Architect Agent
**Implementation By**: Fullstack Developer Agent
**Review Type**: Final Approval for v1.1.0-rc.1
## Executive Summary
I have conducted a comprehensive review of the Search UI implementation completed by the developer. The implementation meets and exceeds the architectural specifications I provided. All critical requirements have been satisfied with appropriate security measures and graceful degradation patterns.
**VERDICT: APPROVED for v1.1.0-rc.1 Release Candidate**
## Component-by-Component Review
### 1. Search API Endpoint (`/api/search`)
**Specification Compliance**: ✅ **APPROVED**
- ✅ GET method with `q`, `limit`, `offset` parameters properly implemented
- ✅ Query validation: Empty/whitespace-only queries rejected (400 error)
- ✅ JSON response format exactly matches specification
- ✅ Authentication-aware filtering using `g.me` check
- ✅ Error handling with proper HTTP status codes (400, 503)
- ✅ Graceful degradation when FTS5 unavailable
**Note**: Query length validation (2-100 chars) is enforced via HTML5 attributes on frontend but not explicitly validated in backend. This is acceptable for v1.1.0 as FTS5 will handle excessive queries appropriately.
### 2. Search Web Interface (`/search`)
**Specification Compliance**: ✅ **APPROVED**
- ✅ Template properly extends `base.html`
- ✅ Search form with query pre-population working
- ✅ Results display with title, excerpt (with highlighting), date, and links
- ✅ Empty state message for no query
- ✅ No results message when query returns empty
- ✅ Error state for FTS5 unavailability
- ✅ Pagination controls with Previous/Next navigation
- ✅ Bootstrap-compatible styling with CSS variables
### 3. Navigation Integration
**Specification Compliance**: ✅ **APPROVED**
- ✅ Search box successfully added to navigation in `base.html`
- ✅ HTML5 validation attributes (minlength="2", maxlength="100")
- ✅ Form submission to `/search` endpoint
- ✅ Bootstrap-compatible styling matching site design
- ✅ ARIA label for accessibility
- ✅ Query persistence on results page
### 4. FTS Index Population
**Specification Compliance**: ✅ **APPROVED**
- ✅ Startup logic checks for empty FTS index
- ✅ Automatic rebuild from existing notes on first run
- ✅ Graceful error handling with logging
- ✅ Non-blocking - failures don't prevent app startup
### 5. Security Implementation
**Specification Compliance**: ✅ **APPROVED with Excellence**
The developer has implemented security measures beyond the basic requirements:
- ✅ XSS prevention through proper HTML escaping
- ✅ Safe highlighting with intelligent `<mark>` tag preservation
- ✅ Query validation preventing empty/whitespace submissions
- ✅ FTS5 handles SQL injection attempts safely
- ✅ Authentication-based filtering properly enforced
- ✅ Pagination bounds checking (negative offset prevention, limit capping)
**Security Highlight**: The excerpt rendering uses a clever approach - escape all HTML first, then selectively unescape only the FTS5-generated `<mark>` tags. This ensures user content cannot inject scripts while preserving search highlighting.
### 6. Testing Coverage
**Specification Compliance**: ✅ **APPROVED with Excellence**
41 new tests covering all aspects:
- ✅ 12 API endpoint tests - comprehensive parameter validation
- ✅ 17 Integration tests - UI rendering and interaction
- ✅ 12 Security tests - XSS, SQL injection, access control
- ✅ All tests passing
- ✅ No regressions in existing test suite
The test coverage is exemplary, particularly the security test suite which validates multiple attack vectors.
### 7. Code Quality
**Specification Compliance**: ✅ **APPROVED**
- ✅ Code follows project conventions consistently
- ✅ Comprehensive docstrings on all new functions
- ✅ Error handling is thorough and user-friendly
- ✅ Complete backward compatibility maintained
- ✅ Implementation matches specifications precisely
## Architectural Observations
### Strengths
1. **Separation of Concerns**: Clean separation between API and HTML routes
2. **Graceful Degradation**: System continues to function if FTS5 unavailable
3. **Security-First Design**: Multiple layers of defense against common attacks
4. **User Experience**: Thoughtful empty states and error messages
5. **Test Coverage**: Comprehensive testing including edge cases
### Minor Observations (Non-Blocking)
1. **Query Length Validation**: Backend doesn't enforce the 2-100 character limit explicitly. FTS5 handles this gracefully, so it's acceptable.
2. **Pagination Display**: Uses simple Previous/Next rather than page numbers. This aligns with our minimalist philosophy.
3. **Search Ranking**: Uses FTS5's default BM25 ranking. Sufficient for v1.1.0.
## Compliance with Standards
- **IndieWeb**: ✅ No violations
- **Web Standards**: ✅ Proper HTML5, semantic markup, accessibility
- **Security**: ✅ OWASP best practices followed
- **Project Philosophy**: ✅ Minimal, elegant, focused
## Final Verdict
### ✅ **APPROVED for v1.1.0-rc.1**
The Search UI implementation is **complete, secure, and ready for release**. The developer has successfully implemented all specified requirements with attention to security, user experience, and code quality.
### v1.1.0 Feature Completeness Confirmation
All v1.1.0 features are now complete:
1. ✅ **RSS Feed Fix** - Newest posts first
2. ✅ **Migration Redesign** - Clear baseline schema
3. ✅ **Full-Text Search** - Complete with UI
4. ✅ **Custom Slugs** - mp-slug support
### Recommendations
1. **Proceed with Release**: Merge to main and tag v1.1.0-rc.1
2. **Monitor in Production**: Watch FTS index size and query performance
3. **Future Enhancement**: Consider adding query length validation in backend for v1.1.1
## Commendations
The developer deserves recognition for:
- Implementing comprehensive security measures without being asked
- Creating an elegant XSS prevention solution for highlighted excerpts
- Adding 41 thorough tests including security coverage
- Maintaining perfect backward compatibility
- Following the minimalist philosophy while delivering full functionality
This implementation exemplifies the StarPunk philosophy: every line of code justifies its existence, and the solution is as simple as possible but no simpler.
---
**Approved By**: StarPunk Architect Agent
**Date**: 2025-11-25
**Decision**: Ready for v1.1.0-rc.1 Release Candidate

572
docs/architecture/v1.1.0-validation-report.md
View File

@@ -1,572 +0,0 @@
# StarPunk v1.1.0 Implementation Validation & Search UI Design
**Date**: 2025-11-25
**Architect**: Claude (StarPunk Architect Agent)
**Status**: Review Complete
## Executive Summary
The v1.1.0 implementation by the developer is **APPROVED** with minor suggestions. All four completed components meet architectural requirements and maintain backward compatibility. The deferred Search UI components have been fully specified below for implementation.
## Part 1: Implementation Validation
### 1. RSS Feed Fix
**Status**: ✅ **Approved**
**Review Findings**:
- Line 97 in `starpunk/feed.py` correctly applies `reversed()` to compensate for feedgen's internal ordering
- Regression test `test_generate_feed_newest_first()` adequately verifies correct ordering
- Test creates 3 notes with distinct timestamps and verifies both database and feed ordering
- Clear comment explains the feedgen behavior requiring the fix
**Code Quality**:
- Minimal change (single line with `reversed()`)
- Well-documented with explanatory comment
- Comprehensive regression test prevents future issues
**Approval**: Ready as-is. The fix is elegant and properly tested.
### 2. Migration System Redesign
**Status**: ✅ **Approved**
**Review Findings**:
- `SCHEMA_SQL` renamed to `INITIAL_SCHEMA_SQL` in `database.py` (line 13)
- Clear documentation: "DO NOT MODIFY - This represents the v1.0.0 schema state"
- Comment properly directs future changes to migration files
- No functional changes, purely documentation improvement
**Architecture Alignment**:
- Follows ADR-033's philosophy of frozen baseline schema
- Makes intent clear for future developers
- Prevents accidental modifications to baseline
**Approval**: Ready as-is. The rename clarifies intent without breaking changes.
### 3. Full-Text Search (Core)
**Status**: ✅ **Approved with minor suggestions**
**Review Findings**:
**Migration (005_add_fts5_search.sql)**:
- FTS5 virtual table schema is correct
- Porter stemming and Unicode61 tokenizer appropriate for international support
- DELETE trigger correctly handles cleanup
- Good documentation explaining why INSERT/UPDATE triggers aren't used
**Search Module (search.py)**:
- Well-structured with clear separation of concerns
- `check_fts5_support()`: Properly tests FTS5 availability
- `update_fts_index()`: Correctly extracts title and updates index
- `search_notes()`: Implements ranking and snippet generation
- `rebuild_fts_index()`: Provides recovery mechanism
- Graceful degradation implemented throughout
**Integration (notes.py)**:
- Lines 299-307: FTS update after create with proper error handling
- Lines 699-708: FTS update after content change with proper error handling
- Graceful degradation ensures note operations succeed even if FTS fails
**Minor Suggestions**:
1. Consider adding a config flag `ENABLE_FTS` to allow disabling FTS entirely
2. The 100-character title truncation (line 94 in search.py) could be configurable
3. Consider logging FTS rebuild progress for large datasets
**Approval**: Approved. Core functionality is solid with excellent error handling.
### 4. Custom Slugs
**Status**: ✅ **Approved**
**Review Findings**:
**Slug Utils Module (slug_utils.py)**:
- Comprehensive `RESERVED_SLUGS` list protects application routes
- `sanitize_slug()`: Properly converts to valid format
- `validate_slug()`: Strong validation with regex pattern
- `make_slug_unique_with_suffix()`: Sequential numbering is predictable and clean
- `validate_and_sanitize_custom_slug()`: Full validation pipeline
**Security**:
- Path traversal prevented by rejecting `/` in slugs
- Reserved slugs protect application routes
- Max length enforced (200 chars)
- Proper sanitization prevents injection attacks
**Integration**:
- Notes.py (lines 217-223): Proper custom slug handling
- Micropub.py (lines 300-304): Correct mp-slug extraction
- Error messages are clear and actionable
**Architecture Alignment**:
- Sequential suffixes (-2, -3) are predictable for users
- Hierarchical slugs properly deferred to v1.2.0
- Maintains backward compatibility with auto-generation
**Approval**: Ready as-is. Implementation is secure and well-designed.
### 5. Testing & Overall Quality
**Test Coverage**: 556 tests passing (1 flaky timing test unrelated to v1.1.0)
**Version Management**:
- Version correctly bumped to 1.1.0 in `__init__.py`
- CHANGELOG.md properly documents all changes
- Semantic versioning followed correctly
**Backward Compatibility**: 100% maintained
- Existing notes work unchanged
- Micropub clients need no modifications
- Database migrations handle all upgrade paths
## Part 2: Search UI Design Specification
### A. Search API Endpoint
**File**: Create new `starpunk/routes/search.py`
```python
# Route Definition
@app.route('/api/search', methods=['GET'])
def api_search():
"""
Search API endpoint
Query Parameters:
q (required): Search query string
limit (optional): Results limit, default 20, max 100
offset (optional): Pagination offset, default 0
Returns:
JSON response with search results
Status Codes:
200: Success (even with 0 results)
400: Bad request (empty query)
503: Service unavailable (FTS5 not available)
"""
```
**Request Validation**:
```python
# Extract and validate parameters
query = request.args.get('q', '').strip()
if not query:
return jsonify({
'error': 'Missing required parameter: q',
'message': 'Search query cannot be empty'
}), 400
# Parse limit with bounds checking
try:
limit = min(int(request.args.get('limit', 20)), 100)
if limit < 1:
limit = 20
except ValueError:
limit = 20
# Parse offset
try:
offset = max(int(request.args.get('offset', 0)), 0)
except ValueError:
offset = 0
```
**Authentication Consideration**:
```python
# Check if user is authenticated (for unpublished notes)
from starpunk.auth import get_current_user
user = get_current_user()
published_only = (user is None) # Anonymous users see only published
```
**Search Execution**:
```python
from starpunk.search import search_notes, has_fts_table
from pathlib import Path
db_path = Path(app.config['DATABASE_PATH'])
# Check FTS availability
if not has_fts_table(db_path):
return jsonify({
'error': 'Search unavailable',
'message': 'Full-text search is not configured on this server'
}), 503
try:
results = search_notes(
query=query,
db_path=db_path,
published_only=published_only,
limit=limit,
offset=offset
)
except Exception as e:
app.logger.error(f"Search failed: {e}")
return jsonify({
'error': 'Search failed',
'message': 'An error occurred during search'
}), 500
```
**Response Format**:
```python
# Format response
response = {
'query': query,
'count': len(results),
'limit': limit,
'offset': offset,
'results': [
{
'slug': r['slug'],
'title': r['title'] or f"Note from {r['created_at'][:10]}",
'excerpt': r['snippet'], # Already has <mark> tags
'published_at': r['created_at'],
'url': f"/notes/{r['slug']}"
}
for r in results
]
}
return jsonify(response), 200
```
### B. Search Box UI Component
**File to Modify**: `templates/base.html`
**Location**: In the navigation bar, after the existing nav links
**HTML Structure**:
```html
<!-- Add to navbar after existing nav items, before auth section -->
<form class="d-flex ms-auto me-3" action="/search" method="get" role="search">
<input
class="form-control form-control-sm me-2"
type="search"
name="q"
placeholder="Search notes..."
aria-label="Search"
value="{{ request.args.get('q', '') }}"
minlength="2"
maxlength="100"
required
>
<button class="btn btn-outline-secondary btn-sm" type="submit">
<i class="bi bi-search"></i>
</button>
</form>
```
**Behavior**:
- Form submission (full page load, no AJAX for v1.1.0)
- Minimum query length: 2 characters (HTML5 validation)
- Maximum query length: 100 characters
- Preserves query in search box when on search results page
### C. Search Results Page
**File**: Create new `templates/search.html`
```html
{% extends "base.html" %}
{% block title %}Search{% if query %}: {{ query }}{% endif %} - {{ config.SITE_NAME }}{% endblock %}
{% block content %}
<div class="container py-4">
<div class="row">
<div class="col-lg-8 mx-auto">
<!-- Search Header -->
<div class="mb-4">
<h1 class="h3">Search Results</h1>
{% if query %}
<p class="text-muted">
Found {{ results|length }} result{{ 's' if results|length != 1 else '' }}
for "<strong>{{ query }}</strong>"
</p>
{% endif %}
</div>
<!-- Search Form (for new searches) -->
<div class="card mb-4">
<div class="card-body">
<form action="/search" method="get" role="search">
<div class="input-group">
<input
type="search"
class="form-control"
name="q"
placeholder="Enter search terms..."
value="{{ query }}"
minlength="2"
maxlength="100"
required
autofocus
>
<button class="btn btn-primary" type="submit">
Search
</button>
</div>
</form>
</div>
</div>
<!-- Results -->
{% if query %}
{% if results %}
<div class="search-results">
{% for result in results %}
<article class="card mb-3">
<div class="card-body">
<h2 class="h5 card-title">
<a href="{{ result.url }}" class="text-decoration-none">
{{ result.title }}
</a>
</h2>
<div class="card-text">
<!-- Excerpt with highlighted terms (safe because we control the <mark> tags) -->
<p class="mb-2">{{ result.excerpt|safe }}</p>
<small class="text-muted">
<time datetime="{{ result.published_at }}">
{{ result.published_at|format_date }}
</time>
</small>
</div>
</div>
</article>
{% endfor %}
</div>
<!-- Pagination (if more than limit results possible) -->
{% if results|length == limit %}
<nav aria-label="Search pagination">
<ul class="pagination justify-content-center">
{% if offset > 0 %}
<li class="page-item">
<a class="page-link" href="/search?q={{ query|urlencode }}&offset={{ max(0, offset - limit) }}">
Previous
</a>
</li>
{% endif %}
<li class="page-item">
<a class="page-link" href="/search?q={{ query|urlencode }}&offset={{ offset + limit }}">
Next
</a>
</li>
</ul>
</nav>
{% endif %}
{% else %}
<!-- No results -->
<div class="alert alert-info" role="alert">
<h4 class="alert-heading">No results found</h4>
<p>Your search for "<strong>{{ query }}</strong>" didn't match any notes.</p>
<hr>
<p class="mb-0">Try different keywords or check your spelling.</p>
</div>
{% endif %}
{% else %}
<!-- No query yet -->
<div class="text-center text-muted py-5">
<i class="bi bi-search" style="font-size: 3rem;"></i>
<p class="mt-3">Enter search terms above to find notes</p>
</div>
{% endif %}
<!-- Error state (if search unavailable) -->
{% if error %}
<div class="alert alert-warning" role="alert">
<h4 class="alert-heading">Search Unavailable</h4>
<p>{{ error }}</p>
<hr>
<p class="mb-0">Full-text search is temporarily unavailable. Please try again later.</p>
</div>
{% endif %}
</div>
</div>
</div>
{% endblock %}
```
**Route Handler**: Add to `starpunk/routes/search.py`
```python
@app.route('/search')
def search_page():
"""
Search results HTML page
"""
query = request.args.get('q', '').strip()
limit = 20 # Fixed for HTML view
offset = 0
try:
offset = max(int(request.args.get('offset', 0)), 0)
except ValueError:
offset = 0
# Check authentication for unpublished notes
from starpunk.auth import get_current_user
user = get_current_user()
published_only = (user is None)
results = []
error = None
if query:
from starpunk.search import search_notes, has_fts_table
from pathlib import Path
db_path = Path(app.config['DATABASE_PATH'])
if not has_fts_table(db_path):
error = "Full-text search is not configured on this server"
else:
try:
results = search_notes(
query=query,
db_path=db_path,
published_only=published_only,
limit=limit,
offset=offset
)
except Exception as e:
app.logger.error(f"Search failed: {e}")
error = "An error occurred during search"
return render_template(
'search.html',
query=query,
results=results,
error=error,
limit=limit,
offset=offset
)
```
### D. Integration Points
1. **Route Registration**: In `starpunk/routes/__init__.py`, add:
```python
from starpunk.routes.search import register_search_routes
register_search_routes(app)
```
2. **Template Filter**: Add to `starpunk/app.py` or template filters:
```python
@app.template_filter('format_date')
def format_date(date_string):
"""Format ISO date for display"""
from datetime import datetime
try:
dt = datetime.fromisoformat(date_string.replace('Z', '+00:00'))
return dt.strftime('%B %d, %Y')
except:
return date_string
```
3. **App Startup FTS Index**: Add to `create_app()` after database init:
```python
# Initialize FTS index if needed
from starpunk.search import has_fts_table, rebuild_fts_index
from pathlib import Path
db_path = Path(app.config['DATABASE_PATH'])
data_path = Path(app.config['DATA_PATH'])
if has_fts_table(db_path):
# Check if index is empty (fresh migration)
import sqlite3
conn = sqlite3.connect(db_path)
count = conn.execute("SELECT COUNT(*) FROM notes_fts").fetchone()[0]
conn.close()
if count == 0:
app.logger.info("Populating FTS index on first run...")
try:
rebuild_fts_index(db_path, data_path)
except Exception as e:
app.logger.error(f"Failed to populate FTS index: {e}")
```
### E. Testing Requirements
**Unit Tests** (`tests/test_search_api.py`):
```python
def test_search_api_requires_query()
def test_search_api_validates_limit()
def test_search_api_returns_results()
def test_search_api_handles_no_results()
def test_search_api_respects_authentication()
def test_search_api_handles_fts_unavailable()
```
**Integration Tests** (`tests/test_search_integration.py`):
```python
def test_search_page_renders()
def test_search_page_displays_results()
def test_search_page_handles_no_results()
def test_search_page_pagination()
def test_search_box_in_navigation()
```
**Security Tests**:
```python
def test_search_prevents_xss_in_query()
def test_search_prevents_sql_injection()
def test_search_escapes_html_in_results()
def test_search_respects_published_status()
```
## Implementation Recommendations
### Priority Order
1. Implement `/api/search` endpoint first (enables programmatic access)
2. Add search box to base.html navigation
3. Create search results page template
4. Add FTS index population on startup
5. Write comprehensive tests
### Estimated Effort
- API Endpoint: 1 hour
- Search UI (box + results page): 1.5 hours
- FTS startup population: 0.5 hours
- Testing: 1 hour
- **Total: 4 hours**
### Performance Considerations
1. FTS5 queries are fast but consider caching frequent searches
2. Limit default results to 20 for HTML view
3. Add index on `notes_fts(rank)` if performance issues arise
4. Consider async FTS index updates for large notes
### Security Notes
1. Always escape user input in templates
2. Use `|safe` filter only for our controlled `<mark>` tags
3. Validate query length to prevent DoS
4. Rate limiting recommended for production (not required for v1.1.0)
## Conclusion
The v1.1.0 implementation is **APPROVED** for release pending Search UI completion. The developer has delivered high-quality, well-tested code that maintains architectural principles and backward compatibility.
The Search UI specifications provided above are complete and ready for implementation. Following these specifications will result in a fully functional search feature that integrates seamlessly with the existing FTS5 implementation.
### Next Steps
1. Developer implements Search UI per specifications (4 hours)
2. Run full test suite including new search tests
3. Update version and CHANGELOG if needed
4. Create v1.1.0-rc.1 release candidate
5. Deploy and test in staging environment
6. Release v1.1.0
---
**Architect Sign-off**: ✅ Approved
**Date**: 2025-11-25
**StarPunk Architect Agent**

379
docs/architecture/v1.1.1-architecture-overview.md
View File

@@ -1,379 +0,0 @@
# v1.1.1 "Polish" Architecture Overview
## Executive Summary
StarPunk v1.1.1 introduces production-focused improvements without changing the core architecture. The release adds configurability, observability, and robustness while maintaining full backward compatibility.
## Architectural Principles
### Core Principles (Unchanged)
1. **Simplicity First**: Every feature must justify its complexity
2. **Standards Compliance**: Full IndieWeb specification adherence
3. **No External Dependencies**: Use Python stdlib where possible
4. **Progressive Enhancement**: Core functionality without JavaScript
5. **Data Portability**: User data remains exportable
### v1.1.1 Additions
6. **Observable by Default**: Production visibility built-in
7. **Graceful Degradation**: Features degrade rather than fail
8. **Configuration over Code**: Behavior adjustable without changes
9. **Zero Breaking Changes**: Perfect backward compatibility
## System Architecture
### High-Level Component View
```
┌─────────────────────────────────────────────────────────┐
│ StarPunk v1.1.1 │
├─────────────────────────────────────────────────────────┤
│ Configuration Layer │
│ (Environment Variables) │
├─────────────────────────────────────────────────────────┤
│ Application Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
│ │ Auth │ │ Micropub │ │ Search │ │ Web ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
├─────────────────────────────────────────────────────────┤
│ Monitoring & Logging Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Performance │ │ Structured │ │ Error │ │
│ │ Monitoring │ │ Logging │ │ Handling │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────┤
│ Data Access Layer │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Connection Pool │ │ Search Engine │ │
│ │ ┌────┐...┌────┐ │ │ ┌──────┐┌────────┐ │ │
│ │ │Conn│ │Conn│ │ │ │ FTS5 ││Fallback│ │ │
│ │ └────┘ └────┘ │ │ └──────┘└────────┘ │ │
│ └──────────────────────┘ └──────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ SQLite Database │
│ (WAL mode, FTS5) │
└─────────────────────────────────────────────────────────┘
```
### Request Flow
```
HTTP Request
↓
[Logging Middleware: Start Request ID]
↓
[Performance Middleware: Start Timer]
↓
[Session Middleware: Validate/Extend]
↓
[Error Handling Wrapper]
↓
Route Handler
├→ [Database: Connection Pool]
├→ [Search: FTS5 or Fallback]
├→ [Monitoring: Record Metrics]
└→ [Logging: Structured Output]
↓
Response Generation
↓
[Performance Middleware: Stop Timer, Record]
↓
[Logging Middleware: Log Request]
↓
HTTP Response
```
## New Components
### 1. Configuration System
**Location**: `starpunk/config.py`
**Responsibilities**:
- Load environment variables
- Provide type-safe access
- Define defaults
- Validate configuration
**Design Pattern**: Singleton with lazy loading
```python
Configuration
├── get_bool(key, default)
├── get_int(key, default)
├── get_float(key, default)
└── get_str(key, default)
```
### 2. Performance Monitoring
**Location**: `starpunk/monitoring/`
**Components**:
- `collector.py`: Metrics collection and storage
- `db_monitor.py`: Database performance tracking
- `memory.py`: Memory usage monitoring
- `http.py`: HTTP request tracking
**Design Pattern**: Observer with circular buffer
```python
MetricsCollector
├── CircularBuffer (1000 metrics)
├── SlowQueryLog (100 queries)
├── MemoryTracker (background thread)
└── Dashboard (read-only view)
```
### 3. Structured Logging
**Location**: `starpunk/logging.py`
**Features**:
- JSON formatting in production
- Human-readable in development
- Request correlation IDs
- Log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
**Design Pattern**: Decorator with context injection
### 4. Error Handling
**Location**: `starpunk/errors.py`
**Hierarchy**:
```
StarPunkError (Base)
├── ValidationError (400)
├── AuthenticationError (401)
├── NotFoundError (404)
├── DatabaseError (500)
├── ConfigurationError (500)
└── TransientError (503)
```
**Design Pattern**: Exception hierarchy with middleware
### 5. Connection Pool
**Location**: `starpunk/database/pool.py`
**Features**:
- Thread-safe pool management
- Configurable pool size
- Connection health checks
- Usage statistics
**Design Pattern**: Object pool with semaphore
## Data Flow Improvements
### Search Data Flow
```
Search Request
↓
Check Config: SEARCH_ENABLED?
├─No→ Return "Search Disabled"
└─Yes↓
Check FTS5 Available?
├─Yes→ FTS5 Search Engine
│ ├→ Execute FTS5 Query
│ ├→ Calculate Relevance
│ └→ Highlight Terms
└─No→ Fallback Search Engine
├→ Execute LIKE Query
├→ No Relevance Score
└→ Basic Highlighting
```
### Error Flow
```
Exception Occurs
↓
Catch in Middleware
↓
Categorize Error
├→ User Error: Log INFO, Return Helpful Message
├→ System Error: Log ERROR, Return Generic Message
├→ Transient Error: Retry with Backoff
└→ Config Error: Fail Fast at Startup
```
## Database Schema Changes
### Sessions Table Enhancement
```sql
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
created_at TIMESTAMP NOT NULL,
expires_at TIMESTAMP NOT NULL,
last_activity TIMESTAMP,
remember BOOLEAN DEFAULT FALSE,
INDEX idx_sessions_expires (expires_at),
INDEX idx_sessions_user (user_id)
);
```
## Performance Characteristics
### Metrics
| Operation | v1.1.0 | v1.1.1 Target | v1.1.1 Actual |
|-----------|---------|---------------|---------------|
| Request Latency | ~50ms | <50ms | TBD |
| Search Response | ~100ms | <100ms (FTS5) <500ms (fallback) | TBD |
| RSS Generation | ~200ms | <100ms | TBD |
| Memory per Request | ~2MB | <1MB | TBD |
| Monitoring Overhead | N/A | <1% | TBD |
### Scalability
- Connection pool: Handles 20+ concurrent requests
- Metrics buffer: Fixed 1MB memory overhead
- RSS streaming: O(1) memory complexity
- Session cleanup: Automatic background process
## Security Enhancements
### Input Validation
- Unicode normalization in slugs
- XSS prevention in search highlighting
- SQL injection prevention via parameterization
### Session Security
- Configurable timeout
- HTTP-only cookies
- Secure flag in production
- CSRF protection maintained
### Error Information
- Sensitive data never in errors
- Stack traces only in debug mode
- Rate limiting on error endpoints
## Deployment Architecture
### Environment Variables
```
Production Server
├── STARPUNK_* Configuration
├── Process Manager (systemd/supervisor)
├── Reverse Proxy (nginx/caddy)
└── SQLite Database File
```
### Health Monitoring
```
Load Balancer
├→ /health (liveness)
└→ /health/ready (readiness)
```
## Testing Architecture
### Test Isolation
```
Test Suite
├── Isolated Database per Test
├── Mocked Time/Random
├── Controlled Configuration
└── Deterministic Execution
```
### Performance Testing
```
Benchmarks
├── Baseline Measurements
├── With Monitoring Enabled
├── Memory Profiling
└── Load Testing
```
## Migration Path
### From v1.1.0 to v1.1.1
1. Install new version
2. Run migrations (automatic)
3. Configure as needed (optional)
4. Restart service
### Rollback Plan
1. Restore previous version
2. No database changes to revert
3. Remove new config vars (optional)
## Observability
### Metrics Available
- Request count and latency
- Database query performance
- Memory usage over time
- Error rates by type
- Session statistics
### Logging Output
```json
{
"timestamp": "2025-11-25T10:00:00Z",
"level": "INFO",
"logger": "starpunk.micropub",
"message": "Note created",
"request_id": "abc123",
"user": "alice@example.com",
"duration_ms": 45
}
```
## Future Considerations
### Extensibility Points
1. **Monitoring Plugins**: Hook for external monitoring
2. **Search Providers**: Interface for alternative search
3. **Cache Layer**: Ready for Redis/Memcached
4. **Queue System**: Prepared for async operations
### Technical Debt Addressed
1. ✅ Test race conditions fixed
2. ✅ Unicode handling improved
3. ✅ Memory usage optimized
4. ✅ Error handling standardized
5. ✅ Configuration centralized
## Design Decisions Summary
| Decision | Rationale | Alternative Considered |
|----------|-----------|----------------------|
| Environment variables for config | 12-factor app, container-friendly | Config files |
| Built-in monitoring | Zero dependencies, privacy | External APM |
| Connection pooling | Reduce latency, handle concurrency | Single connection |
| Structured logging | Production parsing, debugging | Plain text logs |
| Graceful degradation | Reliability, user experience | Fail fast |
## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| FTS5 not available | Slow search | Automatic fallback to LIKE |
| Memory leak in monitoring | OOM | Circular buffer with fixed size |
| Configuration complexity | User confusion | Sensible defaults, clear docs |
| Performance regression | Slow responses | Comprehensive benchmarking |
## Success Metrics
1. **Reliability**: 99.9% uptime capability
2. **Performance**: <1% overhead from monitoring
3. **Usability**: Zero configuration required to upgrade
4. **Observability**: Full visibility into production
5. **Compatibility**: 100% backward compatible
## Documentation References
- [Configuration System](/home/phil/Projects/starpunk/docs/decisions/ADR-052-configuration-system-architecture.md)
- [Performance Monitoring](/home/phil/Projects/starpunk/docs/decisions/ADR-053-performance-monitoring-strategy.md)
- [Structured Logging](/home/phil/Projects/starpunk/docs/decisions/ADR-054-structured-logging-architecture.md)
- [Error Handling](/home/phil/Projects/starpunk/docs/decisions/ADR-055-error-handling-philosophy.md)
- [Implementation Guide](/home/phil/Projects/starpunk/docs/design/v1.1.1/implementation-guide.md)
---
This architecture maintains StarPunk's commitment to simplicity while adding production-grade capabilities. Every addition has been carefully considered to ensure it provides value without unnecessary complexity.

173
docs/architecture/v1.1.1-instrumentation-assessment.md
View File

@@ -1,173 +0,0 @@
# v1.1.1 Performance Monitoring Instrumentation Assessment
## Architectural Finding
**Date**: 2025-11-25
**Architect**: StarPunk Architect
**Subject**: Missing Performance Monitoring Instrumentation
**Version**: v1.1.1-rc.2
## Executive Summary
**VERDICT: IMPLEMENTATION BUG - Critical instrumentation was not implemented**
The performance monitoring infrastructure exists but lacks the actual instrumentation code to collect metrics. This represents an incomplete implementation of the v1.1.1 design specifications.
## Evidence
### 1. Design Documents Clearly Specify Instrumentation
#### Performance Monitoring Specification (performance-monitoring-spec.md)
Lines 141-232 explicitly detail three types of instrumentation:
- **Database Query Monitoring** (lines 143-195)
- **HTTP Request Monitoring** (lines 197-232)
- **Memory Monitoring** (lines 234-276)
Example from specification:
```python
# Line 165: "Execute query (via monkey-patching)"
def monitored_execute(sql, params=None):
result = original_execute(sql, params)
duration = time.perf_counter() - start_time
metric = PerformanceMetric(...)
metrics_buffer.add_metric(metric)
```
#### Developer Q&A Documentation
**Q6** (lines 93-107): Explicitly discusses per-process buffers and instrumentation
**Q12** (lines 193-205): Details sampling rates for "database/http/render" operations
Quote from Q&A:
> "Different rates for database/http/render... Use random sampling at collection point"
#### ADR-053 Performance Monitoring Strategy
Lines 200-220 specify instrumentation points:
> "1. **Database Layer**
> - All queries automatically timed
> - Connection acquisition/release
> - Transaction duration"
>
> "2. **HTTP Layer**
> - Middleware wraps all requests
> - Per-endpoint timing"
### 2. Current Implementation Status
#### What EXISTS (✅)
- `starpunk/monitoring/metrics.py` - MetricsBuffer class
- `record_metric()` function - Fully implemented
- `/admin/metrics` endpoint - Working
- Dashboard UI - Rendering correctly
#### What's MISSING (❌)
- **ZERO calls to `record_metric()`** in the entire codebase
- No HTTP request timing middleware
- No database query instrumentation
- No memory monitoring thread
- No automatic metric collection
### 3. Grep Analysis Results
```bash
# Search for record_metric calls (excluding definition)
$ grep -r "record_metric" --include="*.py" | grep -v "def record_metric"
# Result: Only imports and docstring examples, NO actual calls
# Search for timing code
$ grep -r "time.perf_counter\|track_query"
# Result: No timing instrumentation found
# Check middleware
$ grep "@app.after_request"
# Result: No after_request handler for timing
```
### 4. Phase 2 Implementation Report Claims
The Phase 2 report (line 22-23) states:
> "Performance Monitoring Infrastructure - Status: ✅ COMPLETED"
But line 89 reveals the truth:
> "API: record_metric('database', 'SELECT notes', 45.2, {'query': 'SELECT * FROM notes'})"
This is an API example, not actual instrumentation code.
## Root Cause Analysis
The developer implemented the **monitoring framework** (the "plumbing") but not the **instrumentation code** (the "sensors"). This is like installing a dashboard in a car but not connecting any of the gauges to the engine.
### Why This Happened
1. **Misinterpretation**: Developer may have interpreted "monitoring infrastructure" as just the data structures and endpoints
2. **Documentation Gap**: The Phase 2 report focuses on the API but doesn't show actual integration
3. **Testing Gap**: No tests verify that metrics are actually being collected
## Impact Assessment
### User Impact
- Dashboard shows all zeros (confusing UX)
- No performance visibility as designed
- Feature appears broken
### Technical Impact
- Core functionality works (no crashes)
- Performance overhead is actually ZERO (ironically meeting the <1% target)
- Easy to fix - framework is ready
## Architectural Recommendation
**Recommendation: Fix in v1.1.2 (not blocking v1.1.1)**
### Rationale
1. **Not a Breaking Bug**: System functions correctly, just lacks metrics
2. **Documentation Exists**: Can document as "known limitation"
3. **Clean Fix Path**: v1.1.2 can add instrumentation without structural changes
4. **Version Strategy**: v1.1.1 focused on "Polish" - this is more "Observability"
### Alternative: Hotfix Now
If you decide this is critical for v1.1.1:
- Create v1.1.1-rc.3 with instrumentation
- Estimated effort: 2-4 hours
- Risk: Low (additive changes only)
## Required Instrumentation (for v1.1.2)
### 1. HTTP Request Timing
```python
# In starpunk/__init__.py
@app.before_request
def start_timer():
if app.config.get('METRICS_ENABLED'):
g.start_time = time.perf_counter()
@app.after_request
def end_timer(response):
if hasattr(g, 'start_time'):
duration = time.perf_counter() - g.start_time
record_metric('http', request.endpoint, duration * 1000)
return response
```
### 2. Database Query Monitoring
Wrap `get_connection()` or instrument execute() calls
### 3. Memory Monitoring Thread
Start background thread in app factory
## Conclusion
This is a **clear implementation gap** between design and execution. The v1.1.1 specifications explicitly required instrumentation that was never implemented. However, since the monitoring framework itself is complete and the system is otherwise stable, this can be addressed in v1.1.2 without blocking the current release.
The developer delivered the "monitoring system" but not the "monitoring integration" - a subtle but critical distinction that the architecture documents did specify.
## Decision Record
Create ADR-056 documenting this as technical debt:
- Title: "Deferred Performance Instrumentation to v1.1.2"
- Status: Accepted
- Context: Monitoring framework complete but lacks instrumentation
- Decision: Ship v1.1.1 with framework, add instrumentation in v1.1.2
- Consequences: Dashboard shows zeros until v1.1.2

400
docs/architecture/v1.1.2-syndicate-architecture.md
View File

@@ -1,400 +0,0 @@
# StarPunk v1.1.2 "Syndicate" - Architecture Overview
## Executive Summary
Version 1.1.2 "Syndicate" enhances StarPunk's content distribution capabilities by completing the metrics instrumentation from v1.1.1 and adding comprehensive feed format support. This release focuses on making content accessible to the widest possible audience through multiple syndication formats while maintaining visibility into system performance.
## Architecture Goals
1. **Complete Observability**: Fully instrument all system operations for performance monitoring
2. **Multi-Format Syndication**: Support RSS, ATOM, and JSON Feed formats
3. **Efficient Generation**: Stream-based feed generation for memory efficiency
4. **Content Negotiation**: Smart format selection based on client preferences
5. **Caching Strategy**: Minimize regeneration overhead
6. **Standards Compliance**: Full adherence to feed specifications
## System Architecture
### Component Overview
```
┌─────────────────────────────────────────────────────────┐
│ HTTP Request Layer │
│ ↓ │
│ ┌──────────────────────┐ │
│ │ Content Negotiator │ │
│ │ (Accept header) │ │
│ └──────────┬───────────┘ │
│ ↓ │
│ ┌───────────────┴────────────────┐ │
│ ↓ ↓ ↓ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ RSS │ │ ATOM │ │ JSON │ │
│ │Generator │ │Generator │ │ Generator│ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └───────────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────────┐ │
│ │ Feed Cache Layer │ │
│ │ (LRU with TTL) │ │
│ └──────────┬───────────┘ │
│ ↓ │
│ ┌──────────────────────┐ │
│ │ Data Layer │ │
│ │ (Notes Repository) │ │
│ └──────────┬───────────┘ │
│ ↓ │
│ ┌──────────────────────┐ │
│ │ Metrics Collector │ │
│ │ (All operations) │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### Data Flow
1. **Request Processing**
- Client sends HTTP request with Accept header
- Content negotiator determines optimal format
- Check cache for existing feed
2. **Feed Generation**
- If cache miss, fetch notes from database
- Generate feed using appropriate generator
- Stream response to client
- Update cache asynchronously
3. **Metrics Collection**
- Record request timing
- Track cache hit/miss rates
- Monitor generation performance
- Log format popularity
## Key Components
### 1. Metrics Instrumentation Layer
**Purpose**: Complete visibility into all system operations
**Components**:
- Database operation timing (all queries)
- HTTP request/response metrics
- Memory monitoring thread
- Business metrics (syndication stats)
**Integration Points**:
- Database connection wrapper
- Flask middleware hooks
- Background thread for memory
- Feed generation decorators
### 2. Content Negotiation Service
**Purpose**: Determine optimal feed format based on client preferences
**Algorithm**:
```
1. Parse Accept header
2. Score each format:
- Exact match: 1.0
- Wildcard match: 0.5
- No match: 0.0
3. Consider quality factors (q=)
4. Return highest scoring format
5. Default to RSS if no preference
```
**Supported MIME Types**:
- RSS: `application/rss+xml`, `application/xml`, `text/xml`
- ATOM: `application/atom+xml`
- JSON: `application/json`, `application/feed+json`
### 3. Feed Generators
**Shared Interface**:
```python
class FeedGenerator(Protocol):
def generate(self, notes: List[Note], config: FeedConfig) -> Iterator[str]:
"""Generate feed chunks"""
def validate(self, feed_content: str) -> List[ValidationError]:
"""Validate generated feed"""
```
**RSS Generator** (existing, enhanced):
- RSS 2.0 specification
- Streaming generation
- CDATA wrapping for HTML
**ATOM Generator** (new):
- ATOM 1.0 specification
- RFC 3339 date formatting
- Author metadata support
- Category/tag support
**JSON Feed Generator** (new):
- JSON Feed 1.1 specification
- Attachment support for media
- Author object with avatar
- Hub support for real-time
### 4. Feed Cache System
**Purpose**: Minimize regeneration overhead
**Design**:
- LRU cache with configurable size
- TTL-based expiration (default: 5 minutes)
- Format-specific cache keys
- Invalidation on note changes
**Cache Key Structure**:
```
feed:{format}:{limit}:{checksum}
```
Where checksum is based on:
- Latest note timestamp
- Total note count
- Site configuration
### 5. Statistics Dashboard
**Purpose**: Track syndication performance and usage
**Metrics Tracked**:
- Feed requests by format
- Cache hit rates
- Generation times
- Client user agents
- Geographic distribution (via IP)
**Dashboard Location**: `/admin/syndication`
### 6. OPML Export
**Purpose**: Allow users to share their feed collection
**Implementation**:
- Generate OPML 2.0 document
- Include all available feed formats
- Add metadata (title, owner, date)
## Performance Considerations
### Memory Management
**Streaming Generation**:
- Generate feeds in chunks
- Yield results incrementally
- Avoid loading all notes at once
- Use generators throughout
**Cache Sizing**:
- Monitor memory usage
- Implement cache eviction
- Configurable cache limits
### Database Optimization
**Query Optimization**:
- Index on published status
- Index on created_at for ordering
- Limit fetched columns
- Use prepared statements
**Connection Pooling**:
- Reuse database connections
- Monitor pool usage
- Track connection wait times
### HTTP Optimization
**Compression**:
- gzip for text formats (RSS, ATOM)
- Already compact JSON Feed
- Configurable compression level
**Caching Headers**:
- ETag based on content hash
- Last-Modified from latest note
- Cache-Control with max-age
## Security Considerations
### Input Validation
- Validate Accept headers
- Sanitize format parameters
- Limit feed size
- Rate limit feed endpoints
### Content Security
- Escape XML entities properly
- Valid JSON encoding
- No script injection in feeds
- CORS headers for JSON feeds
### Resource Protection
- Rate limiting per IP
- Maximum feed items limit
- Timeout for generation
- Circuit breaker for database
## Configuration
### Feed Settings
```ini
# Feed generation
STARPUNK_FEED_DEFAULT_LIMIT = 50
STARPUNK_FEED_MAX_LIMIT = 500
STARPUNK_FEED_CACHE_TTL = 300 # seconds
STARPUNK_FEED_CACHE_SIZE = 100 # entries
# Format support
STARPUNK_FEED_RSS_ENABLED = true
STARPUNK_FEED_ATOM_ENABLED = true
STARPUNK_FEED_JSON_ENABLED = true
# Performance
STARPUNK_FEED_STREAMING = true
STARPUNK_FEED_COMPRESSION = true
STARPUNK_FEED_COMPRESSION_LEVEL = 6
```
### Monitoring Settings
```ini
# Metrics collection
STARPUNK_METRICS_FEED_TIMING = true
STARPUNK_METRICS_CACHE_STATS = true
STARPUNK_METRICS_FORMAT_USAGE = true
# Dashboard
STARPUNK_SYNDICATION_DASHBOARD = true
STARPUNK_SYNDICATION_STATS_RETENTION = 7 # days
```
## Testing Strategy
### Unit Tests
1. **Content Negotiation**
- Accept header parsing
- Format scoring algorithm
- Default behavior
2. **Feed Generators**
- Valid output for each format
- Streaming behavior
- Error handling
3. **Cache System**
- LRU eviction
- TTL expiration
- Invalidation logic
### Integration Tests
1. **End-to-End Feeds**
- Request with various Accept headers
- Verify correct format returned
- Check caching behavior
2. **Performance Tests**
- Measure generation time
- Monitor memory usage
- Verify streaming works
3. **Compliance Tests**
- Validate against feed specs
- Test with popular feed readers
- Check encoding edge cases
## Migration Path
### From v1.1.1 to v1.1.2
1. **Database**: No schema changes required
2. **Configuration**: New feed options (backward compatible)
3. **URLs**: Existing `/feed.xml` continues to work
4. **Cache**: New cache system, no migration needed
### Rollback Plan
1. Keep v1.1.1 database backup
2. Configuration rollback script
3. Clear feed cache
4. Revert to previous version
## Future Considerations
### v1.2.0 Possibilities
1. **WebSub Support**: Real-time feed updates
2. **Custom Feeds**: User-defined filters
3. **Feed Analytics**: Detailed reader statistics
4. **Podcast Support**: Audio enclosures
5. **ActivityPub**: Fediverse integration
### Technical Debt
1. Refactor feed module into package
2. Extract cache to separate service
3. Implement feed preview UI
4. Add feed validation endpoint
## Success Metrics
1. **Performance**
- Feed generation <100ms for 50 items
- Cache hit rate >80%
- Memory usage <10MB for feeds
2. **Compatibility**
- Works with 10 major feed readers
- Passes all format validators
- Zero regression on existing RSS
3. **Usage**
- 20% adoption of non-RSS formats
- Reduced server load via caching
- Positive user feedback
## Risk Mitigation
### Performance Risks
**Risk**: Feed generation slows down site
**Mitigation**:
- Streaming generation
- Aggressive caching
- Request timeouts
- Rate limiting
### Compatibility Risks
**Risk**: Feed readers reject new formats
**Mitigation**:
- Extensive testing with readers
- Strict spec compliance
- Format validation
- Fallback to RSS
### Operational Risks
**Risk**: Cache grows unbounded
**Mitigation**:
- LRU eviction
- Size limits
- Memory monitoring
- Auto-cleanup
## Conclusion
StarPunk v1.1.2 "Syndicate" creates a robust, standards-compliant syndication platform while completing the observability foundation started in v1.1.1. The architecture prioritizes performance through streaming and caching, compatibility through strict standards adherence, and maintainability through clean component separation.
The design balances feature richness with StarPunk's core philosophy of simplicity, adding only what's necessary to serve content to the widest possible audience while maintaining operational visibility.