lancedb/python/python/lancedb/remote/__init__.py

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright The LanceDB Authors


from dataclasses import dataclass, field
from datetime import timedelta
from typing import List, Optional

from lancedb import __version__

from .header import HeaderProvider
from .oauth import OAuthConfig, OAuthFlowType

# The API reference renders this module with a single mkdocstrings directive,
# which only picks up names listed here. New public names must be added to this
# list, or they will silently go undocumented.
__all__ = [
    "TimeoutConfig",
    "RetryConfig",
    "TlsConfig",
    "ClientConfig",
    "HeaderProvider",
    "OAuthConfig",
    "OAuthFlowType",
]


@dataclass
class TimeoutConfig:
    """Timeout configuration for remote HTTP client.

    Attributes
    ----------
    timeout: Optional[timedelta]
        The overall timeout for the entire request. This includes connection,
        send, and read time. If the entire request doesn't complete within
        this time, it will fail. Default is None (no overall timeout).
        This can also be set via the environment variable
        `LANCE_CLIENT_TIMEOUT`, as an integer number of seconds.
    connect_timeout: Optional[timedelta]
        The timeout for establishing a connection. Default is 120 seconds (2 minutes).
        This can also be set via the environment variable
        `LANCE_CLIENT_CONNECT_TIMEOUT`, as an integer number of seconds.
    read_timeout: Optional[timedelta]
        The timeout for reading data from the server. Default is 300 seconds
        (5 minutes). This can also be set via the environment variable
        `LANCE_CLIENT_READ_TIMEOUT`, as an integer number of seconds.
    pool_idle_timeout: Optional[timedelta]
        The timeout for keeping idle connections in the connection pool. Default
        is 300 seconds (5 minutes). This can also be set via the environment variable
        `LANCE_CLIENT_CONNECTION_TIMEOUT`, as an integer number of seconds.
    """

    timeout: Optional[timedelta] = None
    connect_timeout: Optional[timedelta] = None
    read_timeout: Optional[timedelta] = None
    pool_idle_timeout: Optional[timedelta] = None

    @staticmethod
    def __to_timedelta(value) -> Optional[timedelta]:
        if value is None:
            return None
        elif isinstance(value, timedelta):
            return value
        elif isinstance(value, (int, float)):
            return timedelta(seconds=value)
        else:
            raise ValueError(
                f"Invalid value for timeout: {value}, must be a timedelta "
                "or number of seconds"
            )

    def __post_init__(self):
        self.timeout = self.__to_timedelta(self.timeout)
        self.connect_timeout = self.__to_timedelta(self.connect_timeout)
        self.read_timeout = self.__to_timedelta(self.read_timeout)
        self.pool_idle_timeout = self.__to_timedelta(self.pool_idle_timeout)


@dataclass
class RetryConfig:
    """Retry configuration for the remote HTTP client.

    Attributes
    ----------
    retries: Optional[int]
        The maximum number of retries for a request. Default is 3. You can also set this
        via the environment variable `LANCE_CLIENT_MAX_RETRIES`.
    connect_retries: Optional[int]
        The maximum number of retries for connection errors. Default is 3. You can also
        set this via the environment variable `LANCE_CLIENT_CONNECT_RETRIES`.
    read_retries: Optional[int]
        The maximum number of retries for read errors. Default is 3. You can also set
        this via the environment variable `LANCE_CLIENT_READ_RETRIES`.
    backoff_factor: Optional[float]
        The backoff factor to apply between retries. Default is 0.25. Between each retry
        the client will wait for the amount of seconds:
        `{backoff factor} * (2 ** ({number of previous retries}))`. So for the default
        of 0.25, the first retry will wait 0.25 seconds, the second retry will wait 0.5
        seconds, the third retry will wait 1 second, etc.

        You can also set this via the environment variable
        `LANCE_CLIENT_RETRY_BACKOFF_FACTOR`.
    backoff_jitter: Optional[float]
        The jitter to apply to the backoff factor, in seconds. Default is 0.25.

        A random value between 0 and `backoff_jitter` will be added to the backoff
        factor in seconds. So for the default of 0.25 seconds, between 0 and 250
        milliseconds will be added to the sleep between each retry.

        You can also set this via the environment variable
        `LANCE_CLIENT_RETRY_BACKOFF_JITTER`.
    statuses: Optional[List[int]
        The HTTP status codes for which to retry the request. Default is
        [429, 500, 502, 503].

        You can also set this via the environment variable
        `LANCE_CLIENT_RETRY_STATUSES`. Use a comma-separated list of integers.
    """

    retries: Optional[int] = None
    connect_retries: Optional[int] = None
    read_retries: Optional[int] = None
    backoff_factor: Optional[float] = None
    backoff_jitter: Optional[float] = None
    statuses: Optional[List[int]] = None


@dataclass
class TlsConfig:
    """TLS/mTLS configuration for the remote HTTP client.

    Attributes
    ----------
    cert_file: Optional[str]
        Path to the client certificate file (PEM format) for mTLS authentication.
    key_file: Optional[str]
        Path to the client private key file (PEM format) for mTLS authentication.
    ssl_ca_cert: Optional[str]
        Path to the CA certificate file (PEM format) for server verification.
    assert_hostname: bool
        Whether to verify the hostname in the server's certificate. Default is True.
        Set to False to disable hostname verification (use with caution).
    """

    cert_file: Optional[str] = None
    key_file: Optional[str] = None
    ssl_ca_cert: Optional[str] = None
    assert_hostname: bool = True


@dataclass
class ClientConfig:
    """Configuration for the LanceDB Cloud HTTP client.

    Attributes
    ----------
    user_agent: str
        User agent string sent with requests.
    retry_config: RetryConfig
        Configuration for retrying failed requests.
    timeout_config: Optional[TimeoutConfig]
        Configuration for request timeouts.
    extra_headers: Optional[dict]
        Additional headers to include in requests.
    id_delimiter: Optional[str]
        The delimiter to use when constructing object identifiers.
    tls_config: Optional[TlsConfig]
        TLS/mTLS configuration for secure connections.
    header_provider: Optional[HeaderProvider]
        Provider for dynamic headers to be added to each request.
    user_id: Optional[str]
        User identifier for tracking purposes. This is sent as the
        `x-lancedb-user-id` header in requests to LanceDB Cloud/Enterprise.

        This can also be set via the `LANCEDB_USER_ID` environment variable.
        Alternatively, set `LANCEDB_USER_ID_ENV_KEY` to specify another
        environment variable that contains the user ID value.
    """

    user_agent: str = f"LanceDB-Python-Client/{__version__}"
    retry_config: RetryConfig = field(default_factory=RetryConfig)
    timeout_config: Optional[TimeoutConfig] = field(default_factory=TimeoutConfig)
    extra_headers: Optional[dict] = None
    id_delimiter: Optional[str] = None
    tls_config: Optional[TlsConfig] = None
    header_provider: Optional["HeaderProvider"] = None
    user_id: Optional[str] = None

    def __post_init__(self):
        if isinstance(self.retry_config, dict):
            self.retry_config = RetryConfig(**self.retry_config)
        if isinstance(self.timeout_config, dict):
            self.timeout_config = TimeoutConfig(**self.timeout_config)
        if isinstance(self.tls_config, dict):
            self.tls_config = TlsConfig(**self.tls_config)