utils/freedays/freedays/_sync.py

# Copyright (c) 2026 Krzysztof Rudnicki
"""Pushing and pulling the pool, so a day taken on the phone lands on the PC.

Sync is a *separate* operation from every decision in :mod:`freedays._api`.
Nothing that decides whether a gate fires ever waits on this: a gate reads
the last-merged local file and moves on, so an unreachable network makes the
pool stale rather than making a lock hang.

The remote is Firebase RTDB, matching every other app in the fleet, with one
directory per device -- no two devices write the same node, so there is
nothing to conflict and convergence is the CRDT layer's job.
"""

from __future__ import annotations

import logging
from typing import TYPE_CHECKING

from crdt_sync import (
    ConfigError,
    FileSyncStateStore,
    FirebaseAuthError,
    LogCodec,
    RemoteSyncError,
    RevisionTracking,
    SyncTarget,
    dump_log,
    firebase_client_for,
    load_log,
    sync_log,
)

from freedays._api import actor_id, load, save
from freedays._constants import (
    APP_NAME,
    SYNC_FILENAME,
    SYNC_PATH_PREFIX,
)
from freedays._paths import Paths, resolve_paths

if TYPE_CHECKING:
    from crdt_sync import Log, RemoteStore

_logger = logging.getLogger(__name__)


class SyncUnavailableError(Exception):
    """No usable remote right now -- unconfigured, offline, or rejected.

    Deliberately not a subclass of anything in :mod:`freedays._errors`: this
    is never a policy refusal, and callers treat it the way they treat a
    network timeout.
    """


def get_client() -> RemoteStore:
    """Return a signed-in Firebase client, or raise :class:`SyncUnavailableError`.

    ``ConfigError`` subclasses ``Exception`` directly rather than
    ``RemoteSyncError``, so both are caught explicitly -- assuming one covers
    the other has bitten two other apps in this fleet already.
    """
    try:
        return firebase_client_for(APP_NAME)
    except ConfigError as exc:
        msg = f"free-day sync is not configured on this machine: {exc}"
        raise SyncUnavailableError(msg) from exc
    except FirebaseAuthError as exc:
        msg = f"free-day sync credentials were rejected: {exc}"
        raise SyncUnavailableError(msg) from exc


def sync(
    *,
    client: RemoteStore | None = None,
    paths: Paths | None = None,
) -> Log:
    """Run one pull/merge/push tick and persist the merged pool.

    Args:
        client: Override for the remote; ``None`` builds the Firebase one.
        paths: Where the pool, uuid and sync bookkeeping live.

    Returns:
        The merged pool, as pushed.

    Raises:
        SyncUnavailableError: If no remote could be reached or authenticated.
    """
    resolved = resolve_paths(paths)
    target_client = client if client is not None else get_client()
    node = actor_id(resolved)
    local = load(resolved.log)
    state_path = resolved.sync_state
    try:
        merged = sync_log(
            SyncTarget(
                client=target_client,
                device_id=node,
                path_prefix=SYNC_PATH_PREFIX,
            ),
            local,
            LogCodec(
                encode=dump_log,
                decode=load_log,
                filename=SYNC_FILENAME,
                commit_message="freedays: update pool",
            ),
            RevisionTracking(state_store=FileSyncStateStore(state_path)),
        )
    except RemoteSyncError as exc:
        msg = f"free-day sync could not reach the remote: {exc}"
        raise SyncUnavailableError(msg) from exc
    save(merged, resolved.log)
    return merged


def sync_quietly(*, paths: Paths | None = None) -> bool:
    """Sync, swallowing every failure. Returns whether it actually ran.

    For callers on a timer that want a fresher pool but must not fail, and
    must not say anything, when the sync cannot happen.

    The broad catch is deliberate and is the whole point of this function.
    Today ``FirebaseAuthError`` happens to subclass ``RemoteSyncError`` and
    ``requests``' ``JSONDecodeError`` happens to subclass
    ``RequestException``, so the narrow handler above would in fact catch an
    expired refresh token or a malformed payload. But that is an upstream
    class hierarchy, not a promise to this package -- and a background sync
    whose contract is "never fail" must not have that contract hold only by
    coincidence. Anything unexpected is logged with its traceback, so a real
    bug is loud in the journal while the timer stays green.
    """
    try:
        sync(paths=paths)
    except SyncUnavailableError as exc:
        # The expected case -- offline, or not configured yet. Debug level:
        # this is normal on a laptop and must not fill the journal.
        _logger.debug("free-day sync skipped: %s", exc)
        return False
    except Exception:  # pylint: disable=broad-exception-caught
        _logger.exception("free-day sync failed unexpectedly")
        return False
    return True