pyfect-dev 0.1.0__py3-none-any.whl

pyfect/sql/libsql/client.py

@@ -0,0 +1,225 @@
+"""The libSQL client (Effect's ``@effect/sql-libsql`` ``LibsqlClient``): an
+``SqlClient`` with SQLite's SQL on one SDK client.
+
+Statements and transactions take turns: a statement outside a
+transaction holds the client until it is done, and a transaction from its
+``BEGIN`` until it commits or rolls back. ``BeginTransaction`` is ignored:
+transactions begin in ``write`` mode (``BEGIN IMMEDIATE``). Streams are
+not supported.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Never, Unpack, cast
+
+from pyfect._core import Effect
+from pyfect._effect_args import require_effect
+from pyfect._primitives import Restore, uninterruptible_mask
+from pyfect.config import Config, ConfigError, unwrap
+from pyfect.context import Context, Tag
+from pyfect.effect import succeed
+from pyfect.layer import Layer, provide
+from pyfect.layer import effect_context as layer_effect_context
+from pyfect.reactivity import Reactivity
+from pyfect.reactivity import layer as reactivity_layer
+from pyfect.scope import Scope, acquire_release, add_finalizer
+from pyfect.semaphore import Semaphore
+from pyfect.sql import _loop
+from pyfect.sql.client import (
+    ClientFields,
+    SqlClient,
+    SqlClientService,
+    TransactionOptions,
+    make_with_transaction,
+    transaction_connection,
+)
+from pyfect.sql.client import make as make_sql_client
+from pyfect.sql.connection import Connection
+from pyfect.sql.error import SqlError, classify_sqlite_error
+from pyfect.sql.libsql._connection import ClientConnection, OpenTransaction
+from pyfect.sql.libsql._local import LocalClient
+from pyfect.sql.libsql._targets import RemoteTarget, Target
+from pyfect.sql.libsql.config import LibsqlClientConfig, LibsqlLiveConfig
+from pyfect.sql.libsql.sdk import LibsqlSdk, ManagedSdk
+from pyfect.sql.statement import default_transforms, make_compiler_sqlite
+
+
+class LibsqlClientService(SqlClientService):
+    """A libSQL client: an ``SqlClientService``, its config and the SDK
+    client it runs on."""
+
+    __slots__ = ("config", "sdk")
+
+    config: LibsqlClientConfig | LibsqlLiveConfig
+    sdk: LibsqlSdk
+
+    def __init__(
+        self,
+        *,
+        config: LibsqlClientConfig | LibsqlLiveConfig,
+        sdk: LibsqlSdk,
+        **fields: Unpack[ClientFields],
+    ) -> None:
+        super().__init__(**fields)
+        self.config = config
+        self.sdk = sdk
+
+
+class LibsqlClient(Tag[LibsqlClientService], key="@effect/sql-libsql/LibsqlClient"):
+    """The libSQL client service."""
+
+
+def _catch(message: str, operation: str) -> Callable[[BaseException], SqlError]:
+    return lambda cause: SqlError(
+        reason=classify_sqlite_error(cause, message=message, operation=operation)
+    )
+
+
+def _open(target: Target) -> Effect[ManagedSdk]:
+    """The SDK client for ``target``. A local database that cannot be
+    opened is a defect, as ``createClient`` throws in Effect."""
+    if isinstance(target, RemoteTarget):
+        from pyfect.sql.libsql._hrana import RemoteClient
+
+        remote: ManagedSdk = RemoteClient(target)
+        return succeed(remote)
+    opened = _loop.call(
+        lambda: LocalClient.open(target),
+        _catch("Failed to open database", "connect"),
+        waits_for="work",
+    )
+    return opened.map(lambda client: cast("ManagedSdk", client)).or_die()
+
+
+def _close(sdk: ManagedSdk) -> Effect[None]:
+    return _loop.call(sdk.close, _catch("Failed to close", "close"), waits_for="work").or_die()
+
+
+def _sdk(config: LibsqlClientConfig | LibsqlLiveConfig) -> Effect[LibsqlSdk, Never, Scope]:
+    if isinstance(config, LibsqlLiveConfig):
+        return succeed(config.live_client)
+    managed = acquire_release(_open(config.target), lambda sdk, _: _close(sdk))
+    return managed.map(lambda sdk: cast("LibsqlSdk", sdk))
+
+
+def _savepoint(statement: str) -> Callable[[Connection, int], Effect[None, SqlError]]:
+    def run(conn: Connection, depth: int) -> Effect[None, SqlError]:
+        return conn.execute_raw(f"{statement} effect_sql_{depth};", ()).as_void()
+
+    return run
+
+
+def _commit(conn: Connection) -> Effect[None, SqlError]:
+    return cast("OpenTransaction", conn).commit()
+
+
+def _rollback(conn: Connection) -> Effect[None, SqlError]:
+    return cast("OpenTransaction", conn).rollback()
+
+
+def _no_begin(_conn: Connection, _statement: str | None) -> Effect[None, SqlError]:
+    # The transaction began when its connection was acquired.
+    return succeed(None)
+
+
+def make(
+    config: LibsqlClientConfig | LibsqlLiveConfig,
+) -> Effect[LibsqlClientService, Never, Scope | Reactivity]:
+    """A client on ``config``'s database; one it opened closes with the
+    scope."""
+    service = transaction_connection()
+    transform_rows = (
+        None
+        if config.transform_result_names is None
+        else default_transforms(config.transform_result_names).array
+    )
+    span_attributes: list[tuple[str, object]] = [
+        *config.span_attributes.items(),
+        ("db.system.name", "sqlite"),
+    ]
+
+    def build(sdk: LibsqlSdk) -> Effect[LibsqlClientService, Never, Reactivity]:
+        connection = ClientConnection(sdk)
+        semaphore = Semaphore(1)
+        release: Effect[None, Never, Scope] = add_finalizer(lambda _: semaphore.release(1))
+
+        def acquire_transaction(restore: Restore) -> Effect[Connection, SqlError, Scope]:
+            # Runs masked: only the wait for the permit is interruptible, so
+            # a BEGIN the SDK started always ends in a commit or rollback.
+            began: Effect[Connection, SqlError] = connection.begin_transaction()
+            return restore(semaphore.take(1)).and_then(release).and_then(began)
+
+        # Outside a transaction, hold the permit until the statement's scope
+        # closes, so no other fiber can begin a transaction while it runs.
+        lease: Effect[Connection, SqlError, Scope] = uninterruptible_mask(
+            lambda restore: restore(semaphore.take(1)).and_then(release).as_(connection)
+        )
+        with_transaction = make_with_transaction(
+            TransactionOptions(
+                transaction_service=service,
+                span_attributes=tuple(span_attributes),
+                acquire_connection=acquire_transaction,
+                begin=_no_begin,
+                savepoint=_savepoint("SAVEPOINT"),
+                release_savepoint=_savepoint("RELEASE SAVEPOINT"),
+                rollback_savepoint=_savepoint("ROLLBACK TO SAVEPOINT"),
+                commit=_commit,
+                rollback=_rollback,
+            )
+        )
+        client = make_sql_client(
+            driver="libsql",
+            acquirer=lease,
+            compiler=make_compiler_sqlite(config.transform_query_names),
+            transaction_service=service,
+            span_attributes=span_attributes,
+            transform_rows=transform_rows,
+        )
+
+        def service_of(c: SqlClientService) -> LibsqlClientService:
+            fields = c.fields()
+            fields["with_transaction"] = with_transaction
+            return LibsqlClientService(config=config, sdk=sdk, **fields)
+
+        return client.map(service_of)
+
+    return _sdk(config).flat_map(build)
+
+
+def _contexts(client: LibsqlClientService) -> Context[LibsqlClient | SqlClient]:
+    return Context.empty().add(LibsqlClient, client).add(SqlClient, client)
+
+
+def layer_from[E](
+    acquire: Effect[LibsqlClientService, E, Scope | Reactivity],
+) -> Layer[LibsqlClient | SqlClient, E]:
+    """Provides the client ``acquire`` makes as ``LibsqlClient`` and
+    ``SqlClient``, with its own ``Reactivity``."""
+    require_effect(acquire, "acquire")
+    return layer_effect_context(acquire.map(_contexts)).pipe(provide(reactivity_layer))
+
+
+def layer(config: LibsqlClientConfig | LibsqlLiveConfig) -> Layer[LibsqlClient | SqlClient]:
+    """Provides a client (``make``)."""
+    return layer_from(make(config))
+
+
+def layer_config(
+    config: Config[LibsqlClientConfig] | Config[LibsqlLiveConfig] | Mapping[str, Any],
+) -> Layer[LibsqlClient | SqlClient, ConfigError]:
+    """``layer`` with the config read from the ``ConfigProvider``: a
+    ``Config`` of the whole config, or a mapping from ``LibsqlClientConfig``
+    field names to their ``Config`` (Effect's ``Config.Wrap``)::
+
+        libsql.layer_config({"url": fx.config.string("LIBSQL_URL")})
+    """
+    read: Effect[LibsqlClientConfig | LibsqlLiveConfig, ConfigError] = (
+        config
+        if isinstance(config, Config)
+        else unwrap(config).map(lambda fields: LibsqlClientConfig(**fields))
+    )
+    return layer_from(read.flat_map(make))
+
+
+__all__ = ["LibsqlClient", "LibsqlClientService", "layer", "layer_config", "layer_from", "make"]

pyfect/sql/libsql/config.py

@@ -0,0 +1,170 @@
+"""Settings of a libSQL client (Effect's ``LibsqlClientConfig``):
+``LibsqlClientConfig`` opens a database from a URL, ``LibsqlLiveConfig``
+uses a client the caller owns.
+
+URLs are those of ``@libsql/client``, checked when the config is made:
+
+- ``:memory:`` or ``file::memory:`` (``?cache=shared`` / ``private``): an
+  in-memory database
+- ``file:path.db``, ``file:///absolute/path.db``: a local file
+- ``libsql://host``: a server over HTTPS (``?tls=0`` for HTTP, with an
+  explicit port); ``https://`` / ``http://`` as they say. ``wss://`` /
+  ``ws://`` are served over HTTPS / HTTP too, which sqld and Turso accept
+  on the same address.
+- ``?authToken=...`` on a remote URL overrides ``auth_token``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from urllib.parse import parse_qsl, unquote, urlsplit
+
+from pyfect.redacted import Redacted
+from pyfect.redacted import value as redacted_value
+from pyfect.sql.libsql._targets import LocalTarget, RemoteTarget, Target
+from pyfect.sql.libsql.sdk import LibsqlSdk
+
+_MEMORY = ":memory:"
+_REMOTE_SCHEMES = {"http": "http", "https": "https", "ws": "http", "wss": "https"}
+
+
+def _query(query: str) -> list[tuple[str, str]]:
+    return parse_qsl(query, keep_blank_values=True, strict_parsing=bool(query))
+
+
+def _local(path: str, query: str, netloc: str, port: int | None) -> LocalTarget:
+    if path == _MEMORY and not netloc:
+        params: list[str] = []
+        for key, value in _query(query):
+            if key != "cache":
+                raise ValueError(f"Unsupported URL query parameter {key!r}")
+            if value not in ("shared", "private"):
+                raise ValueError(
+                    f'Unknown value for the "cache" query argument: {value!r}. '
+                    'Supported values are: ["shared", "private"]'
+                )
+            params.append(f"{key}={value}")
+        database = "file::memory:" + (f"?{'&'.join(params)}" if params else "")
+        return LocalTarget(database, uri=True, in_memory=True)
+    for key, _value in _query(query):
+        if key not in ("tls", "authToken"):
+            raise ValueError(f"Unsupported URL query parameter {key!r}")
+    host, _, _ = netloc.rpartition("@")[2].partition(":")
+    if host.lower() not in ("", "localhost"):
+        raise ValueError(
+            f"Invalid host in file URL: {host!r}. A file: URL with an absolute path should "
+            'start with one slash ("file:/absolute/path.db") or with three slashes '
+            '("file:///absolute/path.db")'
+        )
+    if port is not None:
+        raise ValueError("File URL cannot have a port")
+    if "@" in netloc:
+        raise ValueError("File URL cannot have username and password")
+    return LocalTarget(unquote(path), uri=False, in_memory=False)
+
+
+def _remote_query(
+    query: str, auth_token: str | None, tls: bool | None
+) -> tuple[str | None, bool | None]:
+    """``tls`` and ``authToken`` as the query sets them."""
+    for key, value in _query(query):
+        if key == "tls":
+            if value not in ("0", "1"):
+                raise ValueError(
+                    f'Unknown value for the "tls" query argument: {value!r}. '
+                    'Supported values are: ["0", "1"]'
+                )
+            tls = value == "1"
+        elif key == "authToken":
+            auth_token = value
+        else:
+            raise ValueError(f"Unsupported URL query parameter {key!r}")
+    return auth_token, tls
+
+
+def _http_scheme(scheme: str, tls: bool | None, port: int | None) -> str:
+    if scheme == "libsql":
+        if tls is not False:
+            return "https"
+        if port is None:
+            raise ValueError('A "libsql:" URL with ?tls=0 must specify an explicit port')
+        return "http"
+    http = _REMOTE_SCHEMES.get(scheme)
+    if http is None:
+        raise ValueError(
+            'The client supports only "libsql:", "wss:", "ws:", "https:", "http:" and "file:" '
+            f"URLs, got {scheme + ':'!r}"
+        )
+    if http == "http" and tls is True:
+        raise ValueError(f'A "{scheme}:" URL cannot opt into TLS by using ?tls=1')
+    if http == "https" and tls is False:
+        raise ValueError(f'A "{scheme}:" URL cannot opt out of TLS by using ?tls=0')
+    return http
+
+
+def parse_target(url: str, auth_token: str | None, tls: bool | None) -> Target:
+    """Where ``url`` points; ``ValueError`` when ``@libsql/client`` would
+    refuse it."""
+    if url == _MEMORY:
+        url = "file::memory:"
+    parts = urlsplit(url)
+    if not parts.scheme:
+        raise ValueError(f"The URL {url!r} has no scheme (use file:, libsql:, https: or http:)")
+    if parts.fragment:
+        raise ValueError(f"URL fragments are not supported: {'#' + parts.fragment!r}")
+    scheme = parts.scheme.lower()
+    if scheme == "file":
+        return _local(parts.path, parts.query, parts.netloc, parts.port)
+    auth_token, tls = _remote_query(parts.query, auth_token, tls)
+    http = _http_scheme(scheme, tls, parts.port)
+    if parts.username is not None or parts.password is not None:
+        raise ValueError(
+            "This client does not support HTTP Basic authentication with a username and "
+            'password. Use auth_token or the "authToken" URL query parameter.'
+        )
+    if not parts.hostname:
+        raise ValueError(f"The URL {url!r} names no host")
+    return RemoteTarget(f"{http}://{parts.netloc}{parts.path.rstrip('/')}", auth_token)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LibsqlClientConfig:
+    """A database to open (Effect's ``LibsqlClientConfig.Full``).
+
+    - ``url``: the database (see the module)
+    - ``auth_token``: the token a remote server wants
+    - ``tls``: ``False`` makes a ``libsql:`` URL use HTTP
+    - ``span_attributes``: added to every statement's span
+    - ``transform_result_names`` / ``transform_query_names``: rename result
+      columns / identifiers (``fx.case`` has the usual ones)
+
+    ``target`` is where the URL points, parsed when the config is made.
+    """
+
+    url: str
+    auth_token: Redacted[str] | None = None
+    tls: bool | None = None
+    span_attributes: Mapping[str, object] = field(default_factory=dict[str, object])
+    transform_result_names: Callable[[str], str] | None = None
+    transform_query_names: Callable[[str], str] | None = None
+    target: Target = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        token = None if self.auth_token is None else redacted_value(self.auth_token)
+        object.__setattr__(self, "target", parse_target(self.url, token, self.tls))
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LibsqlLiveConfig:
+    """A client the caller owns and closes (Effect's
+    ``LibsqlClientConfig.Live``); its coroutines run on pyfect's SQL loop
+    thread."""
+
+    live_client: LibsqlSdk
+    span_attributes: Mapping[str, object] = field(default_factory=dict[str, object])
+    transform_result_names: Callable[[str], str] | None = None
+    transform_query_names: Callable[[str], str] | None = None
+
+
+__all__ = ["LibsqlClientConfig", "LibsqlLiveConfig", "Target", "parse_target"]

pyfect/sql/libsql/migrator.py

@@ -0,0 +1,43 @@
+"""Migrations for libSQL (Effect's ``@effect/sql-libsql``
+``LibsqlMigrator``): ``Migrator``'s runner, without a schema dump."""
+
+from __future__ import annotations
+
+from typing import Never
+
+from pyfect.layer import Layer
+from pyfect.layer import effect_discard as layer_effect_discard
+from pyfect.sql.client import SqlClient
+from pyfect.sql.error import SqlError
+from pyfect.sql.migrator import (
+    Loader,
+    MigrationError,
+    Runner,
+    from_file_system,
+    from_record,
+    make,
+)
+
+run: Runner[Never] = make()
+"""Run the new migrations of ``loader`` (see ``migrator.make``)."""
+
+
+def layer[R = Never](
+    *,
+    loader: Loader[R],
+    schema_directory: str | None = None,
+    table: str = "effect_sql_migrations",
+) -> Layer[Never, MigrationError | SqlError, SqlClient | R]:
+    """Runs the migrations when built."""
+    return layer_effect_discard(run(loader=loader, schema_directory=schema_directory, table=table))
+
+
+__all__ = [
+    "Loader",
+    "MigrationError",
+    "SqlError",
+    "from_file_system",
+    "from_record",
+    "layer",
+    "run",
+]

pyfect/sql/libsql/sdk.py

@@ -0,0 +1,123 @@
+"""What the libSQL client runs statements on (``@libsql/client``'s
+``Client`` and ``Transaction``, the part Effect's driver uses).
+
+``LibsqlSdk`` and ``LibsqlSdkTransaction`` are async: the client awaits
+them on pyfect's SQL loop thread (``pyfect.sql._loop``), so a caller-owned
+client (``LibsqlLiveConfig``) must be usable from that loop. The client
+makes its own for a ``file:`` / ``:memory:`` database (``sqlite3``) or a
+remote server (Hrana over HTTP).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+type Value = int | float | str | bytes | None
+"""A value as libSQL stores it."""
+
+type TransactionMode = Literal["write", "read", "deferred"]
+"""``write`` starts with ``BEGIN IMMEDIATE``, ``read`` with ``BEGIN
+TRANSACTION READONLY`` (a libSQL server's), ``deferred`` with ``BEGIN
+DEFERRED``."""
+
+_BEGIN: dict[TransactionMode, str] = {
+    "write": "BEGIN IMMEDIATE",
+    "read": "BEGIN TRANSACTION READONLY",
+    "deferred": "BEGIN DEFERRED",
+}
+
+
+def begin_statement(mode: TransactionMode) -> str:
+    return _BEGIN[mode]
+
+
+@dataclass(frozen=True, slots=True)
+class ResultSet:
+    """A statement's result (``@libsql/client``'s ``ResultSet``): the rows
+    as values in column order, and for a statement without rows the rows
+    it changed and the last inserted rowid. ``column_types`` are the
+    declared types a remote server reports (empty for a local database:
+    ``sqlite3`` does not expose them)."""
+
+    columns: tuple[str, ...]
+    column_types: tuple[str, ...]
+    rows: tuple[tuple[Value, ...], ...]
+    rows_affected: int
+    last_insert_rowid: int | None
+
+    def records(self) -> list[dict[str, Value]]:
+        """The rows as column name to value; of columns with the same
+        name, the first one's value."""
+        names = self.columns
+        records: list[dict[str, Value]] = []
+        for row in self.rows:
+            record: dict[str, Value] = {}
+            for name, value in zip(names, row, strict=True):
+                record.setdefault(name, value)
+            records.append(record)
+        return records
+
+
+class LibsqlError(Exception):
+    """A failure the libSQL client reports (``@libsql/core``'s
+    ``LibsqlError``): ``code`` is SQLite's primary code name
+    (``"SQLITE_CONSTRAINT"``) or the client's own (``"CLIENT_CLOSED"``,
+    ``"TRANSACTION_CLOSED"``, ``"SERVER_ERROR"``, ...); ``extended_code``
+    and ``raw_code`` are SQLite's extended code name and number, when a
+    local database reports them."""
+
+    message: str
+    code: str
+    extended_code: str | None
+    raw_code: int | None
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        extended_code: str | None = None,
+        raw_code: int | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.message = message
+        self.code = code
+        self.extended_code = extended_code
+        self.raw_code = raw_code
+
+
+class LibsqlSdkTransaction(Protocol):
+    """An open transaction (``@libsql/client``'s ``Transaction``)."""
+
+    async def execute(self, sql: str, args: Sequence[object], /) -> ResultSet: ...
+
+    async def commit(self) -> None: ...
+
+    async def rollback(self) -> None: ...
+
+
+class LibsqlSdk(Protocol):
+    """A libSQL database client (``@libsql/client``'s ``Client``)."""
+
+    async def execute(self, sql: str, args: Sequence[object], /) -> ResultSet: ...
+
+    async def transaction(self, mode: TransactionMode, /) -> LibsqlSdkTransaction: ...
+
+
+class ManagedSdk(LibsqlSdk, Protocol):
+    """A client the libSQL client made, and closes with its scope."""
+
+    async def close(self) -> None: ...
+
+
+__all__ = [
+    "LibsqlError",
+    "LibsqlSdk",
+    "LibsqlSdkTransaction",
+    "ManagedSdk",
+    "ResultSet",
+    "TransactionMode",
+    "Value",
+    "begin_statement",
+]