syncfm-core 0.1.0__py3-none-any.whl

syncfm_core/__init__.py

@@ -0,0 +1,76 @@
+"""Reusable core package for synchronizing scrobbles."""
+
+from syncfm_core.application import create_sync_service
+from syncfm_core.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    InvalidNetworkResponseError,
+    InvalidSyncRangeError,
+    MissingStartTimestampError,
+    NetworkConnectionError,
+    NetworkError,
+    PersistenceError,
+    ProfileAlreadyExistsError,
+    ProfileNotFoundError,
+    RetryExhaustedError,
+    SecretStorageError,
+    SessionNotFoundError,
+    SyncFMCoreError,
+    SynchronizationError,
+)
+from syncfm_core.models.network_config import NetworkConfig, NetworkType
+from syncfm_core.models.retry_policy import RetryPolicy
+from syncfm_core.models.scrobble import Scrobble, TrackMetadata
+from syncfm_core.models.sync_progress import ProgressCallback, SyncProgress
+from syncfm_core.models.sync_request import SyncRange, SyncRequest
+from syncfm_core.models.sync_result import SyncResult
+from syncfm_core.models.sync_session import SyncPhase, SyncSession
+from syncfm_core.networks.factory import NetworkFactory
+from syncfm_core.profiles import (
+    NetworkProfile,
+    ProfileInput,
+    ProfileService,
+    SecretStorage,
+    create_profile_service,
+    default_profile_path,
+)
+from syncfm_core.services.sync_service import SyncService
+
+__all__ = [
+    "AuthenticationError",
+    "ConfigurationError",
+    "InvalidNetworkResponseError",
+    "InvalidSyncRangeError",
+    "MissingStartTimestampError",
+    "NetworkConfig",
+    "NetworkConnectionError",
+    "NetworkError",
+    "NetworkFactory",
+    "NetworkProfile",
+    "NetworkType",
+    "PersistenceError",
+    "ProfileAlreadyExistsError",
+    "ProfileInput",
+    "ProfileNotFoundError",
+    "ProfileService",
+    "ProgressCallback",
+    "RetryExhaustedError",
+    "RetryPolicy",
+    "Scrobble",
+    "SecretStorage",
+    "SecretStorageError",
+    "SessionNotFoundError",
+    "SyncFMCoreError",
+    "SyncPhase",
+    "SyncProgress",
+    "SyncRange",
+    "SyncRequest",
+    "SyncResult",
+    "SyncService",
+    "SyncSession",
+    "SynchronizationError",
+    "TrackMetadata",
+    "create_profile_service",
+    "create_sync_service",
+    "default_profile_path",
+]

syncfm_core/application.py

@@ -0,0 +1,71 @@
+"""Construct syncfm-core public application services."""
+
+from pathlib import Path
+
+from syncfm_core.models.retry_policy import RetryPolicy
+from syncfm_core.models.sync_progress import ProgressCallback
+from syncfm_core.repositories.database import Database
+from syncfm_core.repositories.queue_repository import SQLiteSyncQueueRepository
+from syncfm_core.repositories.session_repository import SQLiteSyncSessionRepository
+from syncfm_core.repositories.snapshot_repository import (
+    SQLiteScrobbleSnapshotRepository,
+)
+from syncfm_core.services import SyncService
+from syncfm_core.services.comparison_service import ComparisonService
+from syncfm_core.services.metadata_service import MetadataService
+from syncfm_core.services.range_resolver import SyncRangeResolver
+from syncfm_core.services.recovery_service import RecoveryService
+from syncfm_core.services.retry_service import RetryService
+from syncfm_core.services.snapshot_service import SnapshotService
+from syncfm_core.services.submission_service import SubmissionService
+
+
+def create_sync_service(
+    database_path: str | Path,
+    retry_policy: RetryPolicy | None = None,
+    progress_callback: ProgressCallback | None = None,
+) -> SyncService:
+    """Create a fully configured synchronization service.
+
+    Args:
+        database_path: Filesystem path of the SQLite state database.
+        retry_policy: Optional transient-network retry configuration.
+        progress_callback: Optional callback receiving progress updates.
+
+    Returns:
+        Configured central synchronization service.
+    """
+    database = Database(database_path)
+    database.initialize()
+
+    session_repository = SQLiteSyncSessionRepository(database)
+    snapshot_repository = SQLiteScrobbleSnapshotRepository(database)
+    queue_repository = SQLiteSyncQueueRepository(database)
+
+    retry_service = RetryService(
+        retry_policy or RetryPolicy(),
+    )
+
+    return SyncService(
+        session_repository=session_repository,
+        snapshot_repository=snapshot_repository,
+        queue_repository=queue_repository,
+        range_resolver=SyncRangeResolver(),
+        snapshot_service=SnapshotService(
+            snapshot_repository,
+            progress_callback,
+        ),
+        comparison_service=ComparisonService(queue_repository),
+        metadata_service=MetadataService(
+            queue_repository,
+            retry_service,
+            progress_callback,
+        ),
+        submission_service=SubmissionService(
+            queue_repository,
+            retry_service,
+            progress_callback,
+        ),
+        recovery_service=RecoveryService(queue_repository),
+        progress_callback=progress_callback,
+    )

syncfm_core/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line frontend for syncfm-core."""

syncfm_core/cli/app.py

@@ -0,0 +1,101 @@
+"""Typer application providing the syncfm-core command-line interface."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from syncfm_core.cli.commands.discard import discard_command
+from syncfm_core.cli.commands.profile import (
+    add_profile_command,
+    list_profiles_command,
+    remove_profile_command,
+    show_profile_command,
+)
+from syncfm_core.cli.commands.resume import resume_command
+from syncfm_core.cli.commands.status import status_command
+from syncfm_core.cli.commands.sync import sync_command
+from syncfm_core.cli.configuration import default_database_path
+from syncfm_core.cli.context import CLIContext, configure_logging
+from syncfm_core.profiles import default_profile_path
+
+DEFAULT_DATABASE_PATH = default_database_path()
+DEFAULT_PROFILE_PATH = default_profile_path()
+
+app = typer.Typer(
+    name="syncfm",
+    help="Synchronize scrobbles between Last.fm, Libre.fm and GNU.fm networks.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    context_settings={
+        "help_option_names": ["-h", "--help"],
+    },
+)
+
+profile_app = typer.Typer(
+    name="profile",
+    help="Manage reusable network profiles.",
+    no_args_is_help=True,
+)
+
+app.command("sync")(sync_command)
+app.command("resume")(resume_command)
+app.command("status")(status_command)
+app.command("discard")(discard_command)
+
+profile_app.command("add")(add_profile_command)
+profile_app.command("list")(list_profiles_command)
+profile_app.command("show")(show_profile_command)
+profile_app.command("remove")(remove_profile_command)
+
+app.add_typer(profile_app, name="profile")
+
+
+@app.callback()
+def application_callback(
+    context: typer.Context,
+    database_path: Annotated[
+        Path,
+        typer.Option(
+            "--database",
+            envvar="SYNCFM_DATABASE_PATH",
+            dir_okay=False,
+            help="Path to the SQLite state database",
+        ),
+    ] = DEFAULT_DATABASE_PATH,
+    config_path: Annotated[
+        Path,
+        typer.Option(
+            "--config",
+            envvar="SYNCFM_CONFIG_PATH",
+            dir_okay=False,
+            help="Path to the TOML profile configuration file.",
+        ),
+    ] = DEFAULT_PROFILE_PATH,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable diagnostic logging.",
+        ),
+    ] = False,
+) -> None:
+    """Configure the syncfm command-line application."""
+    configure_logging(verbose)
+    context.obj = CLIContext(
+        database_path=database_path,
+        config_path=config_path,
+        console=Console(),
+        error_console=Console(stderr=True),
+    )
+
+
+def main() -> None:
+    """Run the syncfm command-line application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

syncfm_core/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands provided by the syncfm cli."""

syncfm_core/cli/commands/common.py

@@ -0,0 +1,45 @@
+"""Shared helpers for network-based CLI commands."""
+
+from functools import partial
+
+from syncfm_core.cli.context import CLIContext, run_core_operation
+from syncfm_core.networks.factory import NetworkFactory
+from syncfm_core.profiles import create_profile_service
+from syncfm_core.protocols.network import MusicNetwork
+
+
+def create_network_pair(
+    context: CLIContext,
+    source_profile: str,
+    target_profile: str,
+) -> tuple[MusicNetwork, MusicNetwork]:
+    """Create source and target networks from named profiles."""
+    profile_service = create_profile_service(context.config_path)
+
+    source_config = run_core_operation(
+        context,
+        partial(
+            profile_service.resolve,
+            source_profile,
+        ),
+    )
+    target_config = run_core_operation(
+        context,
+        partial(
+            profile_service.resolve,
+            target_profile,
+        ),
+    )
+
+    factory = NetworkFactory()
+
+    source_network = run_core_operation(
+        context,
+        partial(factory.create, source_config),
+    )
+    target_network = run_core_operation(
+        context,
+        partial(factory.create, target_config),
+    )
+
+    return source_network, target_network

syncfm_core/cli/commands/discard.py

@@ -0,0 +1,51 @@
+"""Discard an unfinished synchronization session."""
+
+from functools import partial
+from typing import Annotated
+
+import typer
+
+from syncfm_core.application import create_sync_service
+from syncfm_core.cli.context import get_cli_context, run_core_operation
+
+
+def discard_command(
+    context: typer.Context,
+    session_id: Annotated[
+        str,
+        typer.Argument(
+            help="Identifier of the session to discard",
+        ),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Discard without asking for confirmation.",
+        ),
+    ] = False,
+) -> None:
+    """Discard an unfinished synchronization session."""
+    cli_context = get_cli_context(context)
+
+    if not yes:
+        confirmed = typer.confirm(f"Discard synchronization session {session_id!r}?")
+        if not confirmed:
+            raise typer.Abort
+
+    sync_service = run_core_operation(
+        cli_context,
+        partial(
+            create_sync_service,
+            cli_context.database_path,
+        ),
+    )
+    run_core_operation(
+        cli_context,
+        partial(sync_service.discard, session_id),
+    )
+
+    cli_context.console.print(
+        f"[green]Discarded synchronization session {session_id}.[/green]"
+    )

syncfm_core/cli/commands/profile.py

@@ -0,0 +1,191 @@
+"""Manage reusable network profiles."""
+
+import os
+from functools import partial
+from typing import Annotated
+
+import typer
+
+from syncfm_core import NetworkType
+from syncfm_core.cli.context import get_cli_context, run_core_operation
+from syncfm_core.cli.presenters import present_profile, present_profiles
+from syncfm_core.profiles import (
+    ProfileInput,
+    SecretStorage,
+    create_profile_service,
+)
+
+
+def add_profile_command(
+    context: typer.Context,
+    name: Annotated[
+        str,
+        typer.Argument(help="Unique lowercase profile name."),
+    ],
+    type: Annotated[
+        NetworkType,
+        typer.Option("--type", help="Music network type."),
+    ],
+    username: Annotated[
+        str,
+        typer.Option("--username", help="Network username."),
+    ],
+    api_key: Annotated[
+        str,
+        typer.Option("--api-key", "--api_key", help="Network API key."),
+    ],
+    hostname: Annotated[
+        str | None, typer.Option("--hostname", help="GNU.fm instance hostname.")
+    ] = None,
+    proxy: Annotated[
+        str | None,
+        typer.Option(
+            "--proxy", help="Proxy URL; scheme-less values default to socks5."
+        ),
+    ] = None,
+    secret_storage: Annotated[
+        SecretStorage,
+        typer.Option(
+            "--secret-storage",
+            "--secret_storage",
+            help="Where sensitive credentials should be stored.",
+        ),
+    ] = SecretStorage.KEYRING,
+    use_session_key: Annotated[
+        bool,
+        typer.Option(
+            "--use-session-key",
+            help="Prompt for a session key instead of a password.",
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Replace an existing profile."),
+    ] = False,
+) -> None:
+    """Create or replace a network profile."""
+    cli_context = get_cli_context(context)
+    profile_service = create_profile_service(cli_context.config_path)
+
+    api_secret = _secret_input(
+        "SYNCFM_PROFILE_API_SECRET",
+        "API secret",
+    )
+
+    credential_name = (
+        "SYNCFM_PROFILE_SESSION_KEY" if use_session_key else "SYNCFM_PROFILE_PASSWORD"
+    )
+
+    credential_prompt = "Session key" if use_session_key else "Password"
+
+    credential = _secret_input(
+        credential_name,
+        credential_prompt,
+    )
+
+    profile_input = ProfileInput(
+        name=name,
+        type=type,
+        username=username,
+        api_key=api_key,
+        api_secret=api_secret,
+        password=None if use_session_key else credential,
+        session_key=credential if use_session_key else None,
+        hostname=hostname,
+        proxy=proxy,
+        secret_storage=secret_storage,
+    )
+
+    run_core_operation(
+        cli_context,
+        partial(
+            profile_service.save,
+            profile_input,
+            replace=force,
+        ),
+    )
+
+    cli_context.console.print(f"[green]Saved network profile {name!r}.[/green]")
+
+
+def list_profiles_command(context: typer.Context) -> None:
+    """Display all network profiles."""
+    cli_context = get_cli_context(context)
+    profile_service = create_profile_service(cli_context.config_path)
+
+    profiles = run_core_operation(
+        cli_context,
+        profile_service.list,
+    )
+    present_profiles(cli_context.console, profiles)
+
+
+def show_profile_command(
+    context: typer.Context,
+    name: Annotated[
+        str,
+        typer.Argument(help="Name of the profile to display."),
+    ],
+) -> None:
+    """Display one network profile without showing credentials."""
+    cli_context = get_cli_context(context)
+    profile_service = create_profile_service(cli_context.config_path)
+
+    profile = run_core_operation(
+        cli_context,
+        partial(profile_service.get, name),
+    )
+
+    present_profile(cli_context.console, profile)
+
+
+def remove_profile_command(
+    context: typer.Context,
+    name: Annotated[
+        str,
+        typer.Argument(help="Name of the profile to remove."),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Remove without asking for confirmation.",
+        ),
+    ] = False,
+) -> None:
+    """Remove a network profile and its stored credentials."""
+    cli_context = get_cli_context(context)
+    profile_service = create_profile_service(cli_context.config_path)
+
+    run_core_operation(
+        cli_context,
+        partial(profile_service.get, name),
+    )
+
+    if not yes and not typer.confirm(f"Remove network profile {name!r}?"):
+        raise typer.Abort
+
+    run_core_operation(
+        cli_context,
+        partial(profile_service.remove, name),
+    )
+
+    cli_context.console.print(f"[green]Removed network profile {name!r}.[/green]")
+
+
+def _secret_input(
+    environment_variable: str,
+    prompt: str,
+) -> str:
+    """Read a secret from the environment or an interactive prompt."""
+    environment_value = os.environ.get(environment_variable)
+
+    if environment_value:
+        return environment_value
+
+    return typer.prompt(
+        prompt,
+        hide_input=True,
+        confirmation_prompt=False,
+    )

syncfm_core/cli/commands/resume.py

@@ -0,0 +1,117 @@
+"""Resume an unfinished synchronization operation."""
+
+from functools import partial
+from typing import Annotated
+
+import typer
+
+from syncfm_core.application import create_sync_service
+from syncfm_core.cli.commands.common import create_network_pair
+from syncfm_core.cli.context import get_cli_context, run_core_operation
+from syncfm_core.cli.presenters import RichProgressPresenter, present_result
+from syncfm_core.exceptions import ConfigurationError
+from syncfm_core.models.sync_session import SyncSession
+
+
+def _resolve_profile_names(
+    session: SyncSession,
+    source_profile: str | None,
+    target_profile: str | None,
+) -> tuple[str, str]:
+    """Resolve stored profile names, with a fallback for legacy sessions."""
+    if session.source_profile is not None and session.target_profile is not None:
+        if source_profile is not None and source_profile != session.source_profile:
+            raise ConfigurationError(
+                "--source does not match the profile stored for this session."
+            )
+        if target_profile is not None and target_profile != session.target_profile:
+            raise ConfigurationError(
+                "--target does not match the profile stored for this session."
+            )
+        return session.source_profile, session.target_profile
+
+    if source_profile is None or target_profile is None:
+        raise ConfigurationError(
+            "This session predates stored profile references. Supply both "
+            "--source and --target once; later resumes will need only the "
+            "session ID."
+        )
+
+    return source_profile, target_profile
+
+
+def resume_command(
+    context: typer.Context,
+    session_id: Annotated[
+        str,
+        typer.Argument(
+            help="Identifier of the synchronization session.",
+        ),
+    ],
+    source_profile: Annotated[
+        str | None,
+        typer.Option(
+            "--source",
+            envvar="SYNCFM_SOURCE_PROFILE",
+            help="Original source profile for a legacy session.",
+        ),
+    ] = None,
+    target_profile: Annotated[
+        str | None,
+        typer.Option(
+            "--target",
+            envvar="SYNCFM_TARGET_PROFILE",
+            help="Original target profile for a legacy session.",
+        ),
+    ] = None,
+) -> None:
+    """Resume an unfinished synchronization session."""
+    cli_context = get_cli_context(context)
+    progress_presenter = RichProgressPresenter(cli_context.console)
+
+    sync_service = run_core_operation(
+        cli_context,
+        partial(
+            create_sync_service,
+            cli_context.database_path,
+            progress_callback=progress_presenter,
+        ),
+    )
+
+    session = run_core_operation(
+        cli_context,
+        partial(sync_service.get_session, session_id),
+    )
+    resolved_source_profile, resolved_target_profile = run_core_operation(
+        cli_context,
+        partial(
+            _resolve_profile_names,
+            session,
+            source_profile,
+            target_profile,
+        ),
+    )
+    progress_presenter.configure(
+        source_label=resolved_source_profile,
+        target_label=resolved_target_profile,
+    )
+    source_network, target_network = create_network_pair(
+        cli_context,
+        resolved_source_profile,
+        resolved_target_profile,
+    )
+
+    with progress_presenter:
+        result = run_core_operation(
+            cli_context,
+            partial(
+                sync_service.resume,
+                session_id,
+                source_network,
+                target_network,
+                source_profile=resolved_source_profile,
+                target_profile=resolved_target_profile,
+            ),
+        )
+
+    present_result(cli_context.console, result)

syncfm_core/cli/commands/status.py

@@ -0,0 +1,26 @@
+"""Display unfinished synchronization sessions."""
+
+from functools import partial
+
+import typer
+
+from syncfm_core.application import create_sync_service
+from syncfm_core.cli.context import get_cli_context, run_core_operation
+from syncfm_core.cli.presenters import present_sessions
+
+
+def status_command(context: typer.Context) -> None:
+    """Display unfinished synchronization sessions."""
+    cli_context = get_cli_context(context)
+    sync_service = run_core_operation(
+        cli_context,
+        partial(
+            create_sync_service,
+            cli_context.database_path,
+        ),
+    )
+    sessions = run_core_operation(
+        cli_context,
+        sync_service.get_pending_sessions,
+    )
+    present_sessions(cli_context.console, sessions)