Files
StarPunk/starpunk/__init__.py
T
PhilandClaude Opus 5.5 0640730416 feat: Pin webmention connections; re-send when responses change (v2.7.2)
- Connect to the address that passed the SSRF check (Host header and SNI
  carry the hostname, so TLS still verifies it), closing the DNS rebinding
  gap (spec 4.5). The webmention POST uses the same path.
- Treat a change in the responses a note shows as an update and re-send its
  webmentions (spec 3.1.4), from validation and from admin moderation.
  Unchanged re-validations send nothing, so there is no ping-pong.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 09:01:38 -07:00

464 lines
16 KiB
Python

"""
StarPunk package initialization
Creates and configures the Flask application
"""
import logging
from logging.handlers import RotatingFileHandler
from pathlib import Path
from flask import Flask, g
import uuid
def configure_logging(app):
"""
Configure application logging with RotatingFileHandler and structured logging
Per ADR-054 and developer Q&A Q3:
- Uses RotatingFileHandler (10MB files, keep 10)
- Supports correlation IDs for request tracking
- Uses Flask's app.logger for all logging
Args:
app: Flask application instance
"""
log_level = app.config.get("LOG_LEVEL", "INFO").upper()
# Set Flask logger level
app.logger.setLevel(getattr(logging, log_level, logging.INFO))
# Configure console handler
console_handler = logging.StreamHandler()
# Configure file handler with rotation (10MB per file, keep 10 files)
log_dir = app.config.get("DATA_PATH", Path("./data")) / "logs"
log_dir.mkdir(parents=True, exist_ok=True)
log_file = log_dir / "starpunk.log"
file_handler = RotatingFileHandler(
log_file,
maxBytes=10 * 1024 * 1024, # 10MB
backupCount=10
)
# Format with correlation ID support
if log_level == "DEBUG":
formatter = logging.Formatter(
"[%(asctime)s] %(levelname)s - %(name)s [%(correlation_id)s]: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
)
# Warn if DEBUG enabled in production
if not app.debug and app.config.get("ENV") != "development":
app.logger.warning(
"=" * 70
+ "\n"
+ "WARNING: DEBUG logging enabled in production!\n"
+ "This logs detailed HTTP requests/responses.\n"
+ "Sensitive data is redacted, but consider using INFO level.\n"
+ "Set LOG_LEVEL=INFO in production for normal operation.\n"
+ "=" * 70
)
else:
formatter = logging.Formatter(
"[%(asctime)s] %(levelname)s [%(correlation_id)s]: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S"
)
# Add filter to inject correlation ID BEFORE setting formatters
# This filter must be applied to handlers to work with all loggers
class CorrelationIdFilter(logging.Filter):
def filter(self, record):
# Get correlation ID from Flask's g object, or use fallback
# Handle case where we're outside of request context
if not hasattr(record, 'correlation_id'):
try:
from flask import has_request_context
if has_request_context():
record.correlation_id = getattr(g, 'correlation_id', 'no-request')
else:
record.correlation_id = 'init'
except (RuntimeError, AttributeError):
record.correlation_id = 'init'
return True
correlation_filter = CorrelationIdFilter()
# Apply filter to handlers (not loggers) to ensure all log records have correlation_id
console_handler.addFilter(correlation_filter)
file_handler.addFilter(correlation_filter)
console_handler.setFormatter(formatter)
file_handler.setFormatter(formatter)
# Remove existing handlers and add our configured handlers
app.logger.handlers.clear()
app.logger.addHandler(console_handler)
app.logger.addHandler(file_handler)
# Also apply filter to root logger for any other loggers
root_logger = logging.getLogger()
root_logger.addFilter(correlation_filter)
def add_correlation_id():
"""Generate and store correlation ID for the current request"""
if not hasattr(g, 'correlation_id'):
g.correlation_id = str(uuid.uuid4())
def create_app(config=None):
"""
Application factory for StarPunk
Args:
config: Optional configuration dict to override defaults
Returns:
Configured Flask application instance
"""
app = Flask(__name__, static_folder="../static", template_folder="../templates")
# Load configuration
from starpunk.config import load_config
load_config(app, config)
# Configure logging
configure_logging(app)
# Clean up old debug files (v1.5.0 Phase 2)
from starpunk.media import cleanup_old_debug_files, cleanup_orphaned_temp_files
cleanup_old_debug_files(app)
# Clean up orphaned temp files (v1.5.0 Phase 4)
cleanup_orphaned_temp_files(app)
# Initialize database schema
from starpunk.database import init_db, init_pool
init_db(app)
# Initialize connection pool
init_pool(app)
# Setup HTTP metrics middleware (v1.1.2 Phase 1)
if app.config.get('METRICS_ENABLED', True):
from starpunk.monitoring import setup_http_metrics
setup_http_metrics(app)
app.logger.info("HTTP metrics middleware enabled")
# Initialize feed cache (v1.1.2 Phase 3)
if app.config.get('FEED_CACHE_ENABLED', True):
from starpunk.feeds import configure_cache
max_size = app.config.get('FEED_CACHE_MAX_SIZE', 50)
ttl = app.config.get('FEED_CACHE_SECONDS', 300)
configure_cache(max_size=max_size, ttl=ttl)
app.logger.info(f"Feed cache enabled (max_size={max_size}, ttl={ttl}s)")
# Initialize rate limiters (v1.6.0 Phase 2)
from starpunk.rate_limiter import init_rate_limiters
init_rate_limiters(app)
# Initialize FTS index if needed
from pathlib import Path
from starpunk.search import has_fts_table, rebuild_fts_index
import sqlite3
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 or first run)
try:
conn = sqlite3.connect(db_path)
count = conn.execute("SELECT COUNT(*) FROM notes_fts").fetchone()[0]
conn.close()
if count == 0:
app.logger.info("FTS index is empty, populating from existing notes...")
try:
rebuild_fts_index(db_path, data_path)
app.logger.info("FTS index successfully populated")
except Exception as e:
app.logger.error(f"Failed to populate FTS index: {e}")
except Exception as e:
app.logger.debug(f"FTS index check skipped: {e}")
# Register blueprints
from starpunk.routes import register_routes
register_routes(app)
# Template context processor - Inject author profile (v1.2.0 Phase 2)
from starpunk.utils import absolute_url_for
app.jinja_env.globals["absolute_url_for"] = absolute_url_for
@app.context_processor
def inject_author():
"""
Inject author profile into all templates
Per Q19: Global context processor approach
Makes author data available in all templates for h-card markup
"""
from starpunk.author_discovery import get_author_profile
# Get ADMIN_ME from config (single-user CMS)
me_url = app.config.get('ADMIN_ME')
if me_url:
try:
author = get_author_profile(me_url)
except Exception as e:
app.logger.warning(f"Failed to get author profile in template context: {e}")
author = None
else:
author = None
return {'author': author}
# Template filter - URL to color for facepile (v1.6.0)
@app.template_filter('url_to_color')
def url_to_color_filter(url):
"""
Generate consistent color from URL hash for facepile initials
Per display-moderation.md design: Hash URL to generate deterministic
color for facepile fallback initials.
Args:
url: Author URL or any string
Returns:
CSS color string (hex format)
"""
import hashlib
if not url:
return '#6B7280' # Gray fallback
# Hash the URL to get consistent color
hash_value = int(hashlib.md5(url.encode()).hexdigest()[:6], 16)
# Generate pleasant, readable colors
# Use HSL-style generation for better color distribution
hue = hash_value % 360
saturation = 65 # Medium saturation for readability
lightness = 50 # Medium lightness
# Convert HSL to RGB (simplified)
def hsl_to_rgb(h, s, l):
s = s / 100.0
l = l / 100.0
c = (1 - abs(2 * l - 1)) * s
x = c * (1 - abs((h / 60) % 2 - 1))
m = l - c / 2
if h < 60:
r, g, b = c, x, 0
elif h < 120:
r, g, b = x, c, 0
elif h < 180:
r, g, b = 0, c, x
elif h < 240:
r, g, b = 0, x, c
elif h < 300:
r, g, b = x, 0, c
else:
r, g, b = c, 0, x
return int((r + m) * 255), int((g + m) * 255), int((b + m) * 255)
r, g, b = hsl_to_rgb(hue, saturation, lightness)
return f'#{r:02x}{g:02x}{b:02x}'
# Request middleware - Add correlation ID to each request
@app.before_request
def before_request():
"""Add correlation ID to request context for tracing"""
add_correlation_id()
# Know who is logged in on every page, not just /admin (v2.3.2), so
# the header can say "Admin" instead of "Log in". Only requests that
# carry a session cookie touch the database.
from flask import g, request
token = request.cookies.get("starpunk_session")
if token:
from starpunk.auth import verify_session
try:
info = verify_session(token)
except Exception:
info = None
if info:
g.user = info
g.me = info["me"]
# Response middleware - Add webmention Link header (v1.6.0)
@app.after_request
def add_webmention_headers(response):
"""Add webmention Link header to HTML responses"""
if (app.config.get('WEBMENTION_ENABLED', True) and
response.content_type and
'text/html' in response.content_type):
response.headers.add('Link', '</webmention>; rel="webmention"')
return response
# Register centralized error handlers
from starpunk.errors import register_error_handlers
register_error_handlers(app)
# Start memory monitor thread (v1.1.2 Phase 1)
# Per CQ5: Skip in test mode
if app.config.get('METRICS_ENABLED', True) and not app.config.get('TESTING', False):
from starpunk.monitoring import MemoryMonitor
memory_monitor = MemoryMonitor(interval=app.config.get('METRICS_MEMORY_INTERVAL', 30))
memory_monitor.start()
app.memory_monitor = memory_monitor
app.logger.info(f"Memory monitor started (interval={memory_monitor.interval}s)")
# Register cleanup handler
@app.teardown_appcontext
def cleanup_memory_monitor(error=None):
if hasattr(app, 'memory_monitor') and app.memory_monitor.is_alive():
app.memory_monitor.stop()
# Start webmention worker thread (v1.6.0 Phase 2)
# Per background-worker.md: Skip in test mode
if app.config.get('WEBMENTION_WORKER_ENABLED', True) and not app.config.get('TESTING', False):
from starpunk.webmention_worker import WebmentionWorker
webmention_worker = WebmentionWorker(
app,
db_path=app.config['DATABASE_PATH'],
site_url=app.config['SITE_URL'],
poll_interval=app.config.get('WEBMENTION_POLL_INTERVAL', 10),
error_backoff=app.config.get('WEBMENTION_ERROR_BACKOFF', 60),
batch_size=app.config.get('WEBMENTION_BATCH_SIZE', 5),
auto_approve=app.config.get('WEBMENTION_AUTO_APPROVE', True)
)
webmention_worker.start()
app.webmention_worker = webmention_worker
app.logger.info(
f"Webmention worker started "
f"(poll_interval={webmention_worker.poll_interval}s, "
f"batch_size={webmention_worker.batch_size})"
)
# Start syndication worker when a target is configured (v2.1.0)
from starpunk.syndication import SyndicationWorker, targets_configured
if targets_configured(app.config) and not app.config.get("TESTING", False):
app.syndication_worker = SyndicationWorker(
app, poll_interval=app.config["SYNDICATION_POLL_INTERVAL"]
)
app.syndication_worker.start()
app.logger.info("Syndication worker started")
# Health check endpoint for containers and monitoring
@app.route("/health")
def health_check():
"""
Health check endpoint for containers and monitoring
Per developer Q&A Q10:
- Basic mode (/health): Public, no auth, returns 200 OK for load balancers
- Detailed mode (/health?detailed=true): Requires auth, checks database/disk
Returns:
JSON with status and info (varies by mode)
Response codes:
200: Application healthy
401: Unauthorized (detailed mode without auth)
500: Application unhealthy
Query parameters:
detailed: If 'true', perform detailed checks (requires auth)
"""
from flask import jsonify, request
import os
import shutil
# Check if detailed mode requested
detailed = request.args.get('detailed', '').lower() == 'true'
if detailed:
# Detailed mode requires authentication
if not g.get('me'):
return jsonify({"error": "Authentication required for detailed health check"}), 401
# Perform comprehensive health checks
checks = {}
overall_healthy = True
# Check database connectivity
try:
from starpunk.database import get_db
db = get_db(app)
db.execute("SELECT 1").fetchone()
db.close()
checks['database'] = {'status': 'healthy', 'message': 'Database accessible'}
except Exception as e:
checks['database'] = {'status': 'unhealthy', 'error': str(e)}
overall_healthy = False
# Check filesystem access
try:
data_path = app.config.get("DATA_PATH", "data")
if not os.path.exists(data_path):
raise Exception("Data path not accessible")
checks['filesystem'] = {'status': 'healthy', 'path': data_path}
except Exception as e:
checks['filesystem'] = {'status': 'unhealthy', 'error': str(e)}
overall_healthy = False
# Check disk space
try:
data_path = app.config.get("DATA_PATH", "data")
stat = shutil.disk_usage(data_path)
percent_free = (stat.free / stat.total) * 100
checks['disk'] = {
'status': 'healthy' if percent_free > 10 else 'warning',
'total_gb': round(stat.total / (1024**3), 2),
'free_gb': round(stat.free / (1024**3), 2),
'percent_free': round(percent_free, 2)
}
if percent_free <= 5:
overall_healthy = False
except Exception as e:
checks['disk'] = {'status': 'unhealthy', 'error': str(e)}
overall_healthy = False
return jsonify({
"status": "healthy" if overall_healthy else "unhealthy",
"version": app.config.get("VERSION", __version__),
"environment": app.config.get("ENV", "unknown"),
"checks": checks
}), 200 if overall_healthy else 500
else:
# Basic mode - just return 200 OK (for load balancers)
# No authentication required, minimal checks
response = {
"status": "ok",
"version": app.config.get("VERSION", __version__)
}
# Add webmention worker stats if enabled (v1.6.0 Phase 2)
if hasattr(app, 'webmention_worker'):
try:
response['webmention_worker'] = app.webmention_worker.get_stats()
except Exception as e:
app.logger.debug(f"Failed to get webmention worker stats: {e}")
return jsonify(response), 200
return app
# Package version (Semantic Versioning 2.0.0)
# See docs/standards/versioning-strategy.md for details
__version__ = "2.7.2"
__version_info__ = (2, 7, 2)