songhive 0.0.8__py3-none-any.whl

songhive/__init__.py

@@ -0,0 +1,11 @@
+from .version import __version__
+
+
+def main():
+    """Songhive application entry point."""
+    from .app import main as _main
+
+    _main()
+
+
+__all__ = ["main", "__version__"]

songhive/__main__.py

@@ -0,0 +1,3 @@
+from songhive import main
+
+main()

songhive/api/__init__.py

@@ -0,0 +1,5 @@
+"""API package."""
+
+# Avoid importing `create_app` at package level: it pulls in all API routes and
+# can create circular imports when `users.tokens` imports
+# `api.middleware.auth.create_access_token` during CLI startup.

songhive/api/_common.py

@@ -0,0 +1,100 @@
+"""Shared helpers used by both FastAPI routes and middleware."""
+
+import ipaddress
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from fastapi import Query, Request, Response
+
+logger = logging.getLogger(__name__)
+
+
+def client_ip(  # pylint: disable=too-many-branches
+    request: Request,
+    *,
+    trusted_hops: Optional[int] = None,
+) -> Optional[str]:
+    """
+    Return the client IP address, honoring common proxy headers.
+
+    The lookup order is:
+
+    1. ``X-Forwarded-For`` if ``trusted_hops`` is configured or the header
+       is present (leftmost valid IP is treated as the originating client).
+    2. ``X-Real-IP``.
+    3. The RFC 7239 ``Forwarded`` header (``for=...`` parameter).
+    4. ``request.client.host``.
+
+    ``trusted_hops`` controls how many entries from the right of the
+    ``X-Forwarded-For`` chain are skipped. A value of ``0`` means the header
+    is not trusted and is ignored. If ``None`` (the default), the header is
+    used without a configured trust depth and the leftmost valid address is
+    returned.
+    """
+    forwarded: Optional[str] = request.headers.get("X-Forwarded-For")
+    if forwarded and trusted_hops != 0:
+        parts = [ip.strip() for ip in forwarded.split(",") if ip.strip()]
+        if trusted_hops is not None and trusted_hops > 0:
+            if len(parts) > trusted_hops:
+                candidate = parts[-(trusted_hops + 1)]
+                if _is_valid_ip(candidate):
+                    return candidate
+        else:
+            for candidate in parts:
+                if _is_valid_ip(candidate):
+                    return candidate
+
+    real_ip: Optional[str] = request.headers.get("X-Real-IP")
+    if real_ip:
+        candidate = real_ip.strip()
+        if _is_valid_ip(candidate):
+            return candidate
+
+    forwarded_rfc: Optional[str] = request.headers.get("Forwarded")
+    if forwarded_rfc:
+        for directive in forwarded_rfc.replace(";", ",").split(","):
+            directive = directive.strip()
+            if directive.lower().startswith("for="):
+                value = directive[4:].strip().strip('"')
+                if value.startswith("["):
+                    value = value.split("]")[0][1:]
+                elif ":" in value:
+                    value = value.rsplit(":", 1)[0]
+                if value and value != "_hidden" and not value.startswith("_") and _is_valid_ip(value):
+                    return value
+
+    if request.client and request.client.host:
+        return request.client.host
+
+    return None
+
+
+def _is_valid_ip(value: str) -> bool:
+    """Return True if ``value`` is a valid IPv4 or IPv6 address."""
+    try:
+        ipaddress.ip_address(value)
+    except ValueError:
+        logger.debug("Ignoring invalid IP address %r", value)
+        return False
+    return True
+
+
+@dataclass
+class Pagination:
+    """Pagination parameters and helper to set the ``X-Total-Count`` header."""
+
+    limit: int
+    offset: int
+
+    def set_total(self, response: Response, total: int) -> None:
+        """Set the ``X-Total-Count`` header on ``response``."""
+        response.headers["X-Total-Count"] = str(total)
+
+
+async def get_pagination(
+    limit: int = Query(20, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+) -> Pagination:
+    """FastAPI dependency that parses ``limit``/``offset`` query params."""
+    return Pagination(limit=limit, offset=offset)

songhive/api/_include.py

@@ -0,0 +1,39 @@
+"""Shared `?include=` query parameter helper."""
+
+from dataclasses import dataclass
+from typing import Optional, Set
+
+from fastapi import Query
+
+
+@dataclass(frozen=True)
+class IncludeQuery:
+    """Parsed and validated `?include=` query parameter."""
+
+    values: Set[str]
+
+    def __contains__(self, item: str) -> bool:
+        return item in self.values
+
+    def has(self, *items: str) -> bool:
+        return any(item in self.values for item in items)
+
+
+def get_include(allowed: Set[str]):
+    """Return a FastAPI dependency that parses a comma-separated `?include=` list."""
+
+    def _parse(
+        include: Optional[str] = Query(
+            None,
+            description=f"Comma-separated relations to include. Allowed: {', '.join(sorted(allowed))}",
+        )
+    ) -> IncludeQuery:
+        values: Set[str] = set()
+        if include:
+            for part in include.split(","):
+                part = part.strip().lower()
+                if part in allowed:
+                    values.add(part)
+        return IncludeQuery(values)
+
+    return _parse

songhive/api/_sorting.py

@@ -0,0 +1,35 @@
+"""Shared sort parameter parsing for list endpoints."""
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Set
+
+from fastapi import Query
+
+
+@dataclass
+class SortParams:
+    """Validated sort parameters for a list request."""
+
+    field: str
+    direction: str
+
+
+def get_sort(
+    allowed: Set[str],
+    default_field: str,
+    default_dir: str = "asc",
+) -> Callable[..., Any]:
+    """
+    Build a FastAPI dependency that parses ``sort_by`` / ``sort_dir`` query
+    parameters and falls back to safe defaults for unknown values.
+    """
+
+    async def _dep(
+        sort_by: Optional[str] = Query(None, description="Field to sort by"),
+        sort_dir: Optional[str] = Query(None, description="Sort direction (asc or desc)"),
+    ) -> SortParams:
+        field = sort_by if sort_by in allowed else default_field
+        direction = sort_dir if sort_dir in ("asc", "desc") else default_dir
+        return SortParams(field=field, direction=direction)
+
+    return _dep

songhive/api/app.py

@@ -0,0 +1,264 @@
+"""
+FastAPI application factory.
+"""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncGenerator, MutableMapping
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from starlette.types import Receive, Send
+
+from ..config.schema import SonghiveConfig
+from ..models.base import get_session, init_db
+from ..services.acl import audit_ownerless_private
+from ..services.redis import close_redis_client, get_redis_client
+from ..services.settings import apply_settings_overrides
+from ..version import __version__
+from .errors import install_error_handlers
+from .routes import (
+    admin,
+    albums,
+    api_tokens,
+    artists,
+    auth,
+    favorites,
+    federation,
+    files,
+    genres,
+    hashtags,
+    history,
+    instance,
+    libraries,
+    playlists,
+    radios,
+    reports,
+    share,
+    share_urls,
+    shares,
+    tracks,
+    users,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _sync_settings_overlay(config: SonghiveConfig) -> tuple[SonghiveConfig, bool]:
+    """
+    Apply DB settings overrides synchronously when no event loop is running.
+
+    ``create_app`` may be called before an asyncio loop exists (e.g. in a
+    worker process or during CLI startup), so this path runs the overlay in a
+    temporary event loop. When a loop is already running, it skips and lets the
+    ``_lifespan`` hook apply the overlay in the real application loop.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        return config, False
+
+    async def _run() -> SonghiveConfig:
+        async with get_session() as session:
+            return await apply_settings_overrides(session, config)
+
+    loop = None
+    try:
+        loop = asyncio.new_event_loop()
+        # ``wait_for`` provides a hard ceiling so a stuck database query cannot
+        # block server startup forever. Avoid ``asyncio.run`` here because it
+        # sets/unsets the current event loop, which can break Tornado's
+        # IOLoop when ``create_app`` is called from an async test context.
+        return loop.run_until_complete(asyncio.wait_for(_run(), timeout=10.0)), True
+    except asyncio.TimeoutError:
+        logger.warning("Settings overlay timed out; using config file/defaults")
+        return config, False
+    except Exception:
+        logger.exception("Failed to apply settings overrides at app creation")
+        return config, False
+    finally:
+        if loop is not None:
+            loop.close()
+
+
+def _setup_static_routes(app: FastAPI):
+    """
+    Serve the built frontend SPA as the default handler.
+
+    API/WebSocket/stream paths are excluded so unknown /api/... /ws/...
+    /stream/... routes still 404. The default is only reached when no API route
+    (or redirect-slashes partial match) matches, so it never shadows API
+    endpoints.
+    """
+    static_dir = Path(__file__).resolve().parent.parent / "static"
+    if (static_dir / "index.html").is_file():
+
+        async def _serve_static(scope: MutableMapping[str, Any], receive: Receive, send: Send) -> None:
+            if scope["type"] != "http":
+                raise HTTPException(status_code=404)
+
+            path = scope["path"].lstrip("/")
+            if path.startswith("api/") or path.startswith("ws/") or path.startswith("stream/"):
+                raise HTTPException(status_code=404)
+
+            # Federation/ActivityPub requests to disabled endpoints should 404,
+            # not receive the SPA HTML shell.
+            for name, value in scope.get("headers", []):
+                if name.lower() == b"accept" and b"application/activity+json" in value:
+                    raise HTTPException(status_code=404)
+
+            requested = (static_dir / path).resolve()
+            static_root = static_dir.resolve()
+            if requested.is_file() and str(requested).startswith(str(static_root)):
+                await FileResponse(requested)(scope, receive, send)
+            else:
+                await FileResponse(static_dir / "index.html")(scope, receive, send)
+
+        app.router.default = _serve_static
+
+
+def create_app(config: SonghiveConfig) -> FastAPI:
+    """
+    Create and configure the FastAPI application.
+
+    :param config: The application configuration.
+    :returns: A configured FastAPI instance.
+    """
+    init_db(config.database.url)
+
+    @asynccontextmanager
+    async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        app.state.redis = get_redis_client(config)
+
+        # If the synchronous overlay in create_app already ran, there is no
+        # need to re-read the same settings here. When it was skipped (because
+        # a loop was already running), this is the first chance to apply DB
+        # settings overrides using the real application loop and Redis.
+        if not getattr(app.state, "_sync_overlay_applied", False):
+            try:
+                async with get_session() as session:
+                    await audit_ownerless_private(session)
+                    app.state.config = await apply_settings_overrides(session, app.state.config)
+            except Exception:
+                logger.exception("Failed to apply settings overrides during startup")
+
+        yield
+        await close_redis_client()
+
+    app = FastAPI(
+        title="Songhive",
+        description="A federated and self-hosted music sharing service",
+        version=__version__,
+        debug=config.server.debug,
+        lifespan=_lifespan,
+    )
+
+    # Store config in app state for dependency injection. The synchronous
+    # overlay above handles the no-event-loop case; _lifespan handles the
+    # rest. Both exist because create_app is called in different contexts.
+    config, sync_overlay_applied = _sync_settings_overlay(config)
+    app.state.config = config
+    app.state._sync_overlay_applied = sync_overlay_applied
+    app.state.storage_service = None
+    app.state.storage_service_config = None
+
+    # CORS middleware
+    allow_credentials = True
+    if "*" in config.server.cors_origins:
+        logger.warning(
+            "Wildcard CORS origin (['*']) cannot be used with credentials; "
+            "disabling allow_credentials. Specify explicit origins to enable credentials."
+        )
+        allow_credentials = False
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=config.server.cors_origins,
+        allow_credentials=allow_credentials,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Register RFC 7807 problem detail exception handlers
+    install_error_handlers(app)
+
+    # Register API routes
+    api_prefix = "/api/v1"
+    app.include_router(auth.router, prefix=api_prefix, tags=["auth"])
+    app.include_router(api_tokens.router, prefix=api_prefix, tags=["api-tokens"])
+    app.include_router(users.router, prefix=api_prefix, tags=["users"])
+    app.include_router(artists.router, prefix=api_prefix, tags=["artists"])
+    app.include_router(albums.router, prefix=api_prefix, tags=["albums"])
+    app.include_router(tracks.router, prefix=api_prefix, tags=["tracks"])
+    app.include_router(playlists.router, prefix=api_prefix, tags=["playlists"])
+    app.include_router(libraries.router, prefix=api_prefix, tags=["libraries"])
+    app.include_router(hashtags.router, prefix=api_prefix, tags=["hashtags"])
+    app.include_router(genres.router, prefix=api_prefix, tags=["genres"])
+    app.include_router(favorites.router, prefix=api_prefix, tags=["favorites"])
+    app.include_router(history.router, prefix=api_prefix, tags=["history"])
+    app.include_router(radios.router, prefix=api_prefix, tags=["radios"])
+    app.include_router(reports.router, prefix=api_prefix, tags=["reports"])
+    app.include_router(reports.admin_router, prefix=api_prefix, tags=["reports"])
+    app.include_router(admin.router, prefix=api_prefix, tags=["admin"])
+    app.include_router(files.router, prefix=api_prefix, tags=["files"])
+    app.include_router(shares.router, prefix=api_prefix, tags=["shares"])
+    app.include_router(share_urls.router, prefix=api_prefix, tags=["share-urls"])
+    app.include_router(share.router, prefix=api_prefix, tags=["share"])
+    app.include_router(instance.v1_router, prefix="/api/v1")
+    app.include_router(instance.v2_router, prefix="/api/v2")
+
+    # Federation routes
+    if config.federation.enabled and config.federation.instance_domain:
+        app.include_router(federation.router)
+        _setup_federation(app, config)
+
+    _setup_static_routes(app)
+
+    return app
+
+
+def _setup_federation(app: FastAPI, config: SonghiveConfig):
+    """Set up ActivityPub federation routes via pubby."""
+    try:
+        from pubby import ActivityPubHandler, ActorConfig
+        from pubby.server.adapters.fastapi import bind_activitypub
+        from pubby.server.adapters.fastapi_mastodon import bind_mastodon_api
+
+        from ..federation.storage import (
+            create_activitypub_storage,
+            get_or_create_private_key,
+        )
+
+        actor_config = ActorConfig(
+            base_url=f"https://{config.federation.instance_domain}",
+            username=config.federation.instance_name.lower().replace(" ", "-"),
+            name=config.federation.instance_name,
+            summary=config.federation.instance_description,
+            actor_path="/ap/actor",
+            type="Application",
+        )
+
+        storage = create_activitypub_storage(config.database.url)
+        private_key_path = get_or_create_private_key(config.federation.private_key_path)
+
+        handler = ActivityPubHandler(
+            storage=storage,
+            actor_config=actor_config,
+            private_key_path=str(private_key_path),
+        )
+        bind_activitypub(app, handler, prefix="/ap")
+        bind_mastodon_api(
+            app,
+            handler,
+            title=config.federation.instance_name,
+            description=config.federation.instance_description,
+            software_name="Songhive",
+            software_version=__version__,
+        )
+    except ImportError:
+        logger.error("Federation is enabled but pubby is not installed")

songhive/api/deps.py

@@ -0,0 +1,209 @@
+"""
+FastAPI dependency injection helpers.
+"""
+
+from typing import AsyncGenerator, Optional
+
+from fastapi import Depends, HTTPException, Request, Security, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from redis.asyncio import Redis
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..config.schema import SonghiveConfig
+from ..models.base import get_session
+from ..models.user import User
+from ..services import acl
+from ..services.auth import get_user_by_id
+from ..services.storage import StorageService
+from ..storage import get_storage
+from ..users.api_tokens import validate_api_token
+from .middleware.auth import decode_access_token, decode_token_payload, extract_token
+
+bearer_scheme = HTTPBearer(
+    auto_error=False,
+    scheme_name="BearerAuth",
+    bearerFormat="JWT",
+    description="JWT access token obtained from /api/v1/auth/login or /api/v1/auth/refresh",
+)
+
+
+def _token_from_credentials_or_request(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials],
+) -> Optional[str]:
+    """Extract the bearer token from resolved credentials or the request header."""
+    if isinstance(credentials, HTTPAuthorizationCredentials):
+        return credentials.credentials
+    return extract_token(request)
+
+
+def get_config(request: Request) -> SonghiveConfig:
+    """Get the application config from the request state."""
+    config: SonghiveConfig = request.app.state.config
+    return config
+
+
+async def get_effective_config(request: Request) -> SonghiveConfig:
+    """Return the effective config as stored in app state."""
+    return get_config(request)
+
+
+def get_redis(request: Request) -> Redis:
+    """Get the shared async Redis client from the request state."""
+    redis: Redis = request.app.state.redis
+    return redis
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """Get a database session via dependency injection."""
+    async with get_session() as session:
+        yield session
+
+
+async def _get_current_user(
+    request: Request,
+    db: AsyncSession,
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(bearer_scheme),
+) -> Optional[User]:
+    """Extract and validate the current user, returning ``None`` on any failure."""
+    token = _token_from_credentials_or_request(request, credentials)
+    if not token:
+        return None
+
+    config = get_config(request)
+
+    # Peek at the payload without enforcing ``exp`` so we can route by token type.
+    payload = decode_token_payload(token, config.auth.secret_key)
+    if payload is None:
+        return None
+
+    # Slow path: API-token JWT (exp enforced at DB row level).
+    if payload.get("token_type") == "api_token":
+        jti = payload.get("jti")
+        if not jti:
+            return None
+        redis = get_redis(request)
+        api_token = await validate_api_token(db, jti, redis=redis)
+        if api_token is None:
+            return None
+        user = await get_user_by_id(db, api_token.user_id)
+        return user if user is not None and user.is_active else None
+
+    # Fast path: short-lived access JWT (PyJWT enforces exp).
+    user_id = decode_access_token(token, config.auth.secret_key)
+    if user_id is not None:
+        user = await get_user_by_id(db, user_id)
+        return user if user is not None and user.is_active else None
+
+    return None
+
+
+async def get_current_user(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(bearer_scheme),
+) -> User:
+    """
+    Extract and validate the current user from the request.
+
+    Returns the User model instance or raises 401 for missing, invalid,
+    inactive, or deleted users.
+    """
+    user = await _get_current_user(request, db, credentials)
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return user
+
+
+async def get_current_user_optional(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(bearer_scheme),
+) -> Optional[User]:
+    """Extract and validate the current user, returning ``None`` when unauthenticated."""
+    return await _get_current_user(request, db, credentials)
+
+
+def _get_share_token(request: Request) -> Optional[str]:
+    """Read a share token from the header, cookie, or query string (legacy)."""
+    token = request.headers.get("X-Share-Token")
+    if token:
+        return token
+    token = request.cookies.get("share_token")
+    if token:
+        return token
+    return request.query_params.get("token")
+
+
+def require_access(item_type: str):
+    """Return a FastAPI dependency that enforces access to ``item_type`` resources."""
+    id_key = acl.ITEM_ID_KEYS.get(item_type)
+    if id_key is None:
+        raise RuntimeError(f"Unknown item type: {item_type!r}")
+
+    async def _dep(
+        request: Request,
+        db: AsyncSession = Depends(get_db),
+        user: Optional[User] = Depends(get_current_user_optional),
+        token: Optional[str] = Depends(_get_share_token),
+    ) -> bool:
+        """Load the requested item and verify the requester may access it."""
+        item_id = request.path_params.get(id_key)
+        if not item_id:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Not found",
+            )
+
+        item = await acl.get_item(db, item_type, item_id)
+        if item is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Not found",
+            )
+
+        if not await acl.can_access(db, user, item_type, item_id, share_token=token):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Access denied",
+            )
+
+        return True
+
+    return _dep
+
+
+def get_storage_service(request: Request) -> StorageService:
+    """
+    Get or create a cached StorageService, recreating it when storage config
+    changes.
+    """
+    config = get_config(request)
+    current = config.storage
+    cached = getattr(request.app.state, "storage_service", None)
+    cached_config = getattr(request.app.state, "storage_service_config", None)
+
+    # Compare against a deep copy so runtime config mutations (e.g. in tests) force a
+    # fresh backend and prevent a cached service from using stale connection state.
+    if cached is not None and cached_config == current:
+        return cached
+
+    backend = get_storage(current)
+    service = StorageService(backend, current)
+    request.app.state.storage_service = service
+    request.app.state.storage_service_config = current.model_copy(deep=True)
+    return service
+
+
+async def require_admin(current_user: User = Depends(get_current_user)):
+    """Require admin privileges."""
+    if not current_user.is_admin:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access required",
+        )
+    return current_user