"""Base types for source connectors."""

from __future__ import annotations

import contextlib
from collections.abc import Iterator
from dataclasses import dataclass, field
from pathlib import Path
from typing import Protocol, runtime_checkable


@dataclass
class SourceFile:
    """Metadata about a remote file."""

    uri: str  # canonical URI e.g. s3://bucket/key
    filename: str  # basename, used as source_filename in output
    size_bytes: int | None = None
    etag: str | None = None  # S3 ETag, Azure Content-MD5, GCS generation
    version_id: str | None = None  # S3 VersionId, GCS object generation
    last_modified: str | None = None  # ISO-8601
    content_type: str | None = None
    extra: dict = field(default_factory=dict)


@runtime_checkable
class BaseSource(Protocol):
    """Protocol every source connector must implement."""

    scheme: str

    def list(self, uri: str, glob_pattern: str | None = None) -> Iterator[SourceFile]:
        """Yield SourceFile metadata for all files under uri prefix."""
        ...

    @contextlib.contextmanager
    def fetch(self, source_file: SourceFile, tmp_dir: Path | None = None) -> Iterator[Path]:
        """Download source_file to a temp path and yield it. Cleans up on exit."""
        ...
