volcano-sdk-python 0.6.7__py3-none-any.whl

volcano_sdk/client.py

@@ -0,0 +1,288 @@
+"""Top-level Volcano client."""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import TYPE_CHECKING
+
+from ._transport import GeneratedTransport, Transport
+from .auth import Auth
+from .database import Database
+from .functions import Functions
+from .locks import Locks
+from .logs import Logs
+from .models import (
+    AuthChangeEvent,
+    AuthStateCallback,
+    AuthSubscription,
+    Session,
+)
+from .realtime import CentrifugeFactory, Realtime
+from .storage import Storage
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import TracebackType
+
+_NO_ACTIVE_SESSION = "No active session"
+_NO_SERVICE_KEY = "No service key configured"
+
+
+class _CallbackOutcome:
+    """Capture a callback failure without unwinding dispatcher ownership."""
+
+    def __init__(self) -> None:
+        self.error: BaseException | None = None
+
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(
+        self,
+        _error_type: type[BaseException] | None,
+        error: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> bool:
+        self.error = error
+        return error is not None
+
+
+class VolcanoClient:
+    """Volcano SDK entry point."""
+
+    def __init__(
+        self,
+        *,
+        anon_key: str,
+        api_url: str = "https://api.volcano.dev",
+        service_key: str | None = None,
+        timeout: float = 60.0,
+        _transport: Transport | None = None,
+        _realtime_client_factory: CentrifugeFactory | None = None,
+    ) -> None:
+        """Create a client for a Volcano project."""
+        self._api_url = api_url.rstrip("/")
+        self._anon_key = anon_key
+        self._service_key = service_key
+        self._session_lock = threading.Lock()
+        self._session_generation = 0
+        self._session_lineage = 0
+        self._current_session: Session | None = None
+        self._auth_callbacks: dict[int, AuthStateCallback] = {}
+        self._next_auth_callback_id = 0
+        self._auth_notifications: deque[
+            tuple[
+                tuple[int, ...],
+                AuthChangeEvent,
+                Session | None,
+            ]
+        ] = deque()
+        self._dispatching_auth_notifications = False
+        self._transport: Transport = (
+            _transport
+            if _transport is not None
+            else GeneratedTransport(api_url=self._api_url, timeout=timeout)
+        )
+        self.auth = Auth(self)
+        self.functions = Functions(self)
+        self.logs = Logs(self)
+        self.storage = Storage(self)
+        self.locks = Locks(self)
+        if _realtime_client_factory is None:
+            self.realtime = Realtime(self, api_url=self._api_url)
+        else:
+            self.realtime = Realtime(
+                self,
+                api_url=self._api_url,
+                client_factory=_realtime_client_factory,
+            )
+
+    @property
+    def current_session(self) -> Session | None:
+        """Return the authenticated session, if one exists."""
+        return self._capture_session()[1]
+
+    def database(self, name: str) -> Database:
+        """Create a query facade for a project database."""
+        return Database(self, name)
+
+    def _anon_token(self) -> str:
+        return self._anon_key
+
+    def _api_base_url(self) -> str:
+        return self._api_url
+
+    def _session_token(self) -> str:
+        session = self._capture_session()[1]
+        if session is None:
+            raise RuntimeError(_NO_ACTIVE_SESSION)
+        return session.access_token
+
+    def _service_token(self) -> str:
+        if self._service_key is None:
+            raise RuntimeError(_NO_SERVICE_KEY)
+        return self._service_key
+
+    def _function_token(self) -> str:
+        session = self._capture_session()[1]
+        if session is not None:
+            return session.access_token
+        if self._service_key is not None:
+            return self._service_key
+        return self._anon_key
+
+    def _set_session(
+        self,
+        session: Session,
+        *,
+        event: AuthChangeEvent | None = "SIGNED_IN",
+    ) -> None:
+        with self._session_lock:
+            self._current_session = session
+            self._session_generation += 1
+            self._session_lineage += 1
+            if event is None:
+                return
+            callback_ids = tuple(self._auth_callbacks)
+            dispatch = self._enqueue_auth_state_change(callback_ids, event, session)
+        if dispatch:
+            self._drain_auth_state_changes()
+
+    def _capture_session(self) -> tuple[int, Session | None]:
+        with self._session_lock:
+            return self._session_generation, self._current_session
+
+    def _capture_session_binding(self) -> tuple[int, int, Session | None]:
+        with self._session_lock:
+            return (
+                self._session_generation,
+                self._session_lineage,
+                self._current_session,
+            )
+
+    def _set_session_if_current(
+        self,
+        session: Session,
+        generation: int,
+        *,
+        event: AuthChangeEvent = "SIGNED_IN",
+        notifications: list[Callable[[], None]] | None = None,
+    ) -> bool:
+        with self._session_lock:
+            if generation != self._session_generation:
+                return False
+            self._current_session = session
+            self._session_generation += 1
+            if event != "TOKEN_REFRESHED":
+                self._session_lineage += 1
+            callback_ids = tuple(self._auth_callbacks)
+            dispatch = self._enqueue_auth_state_change(callback_ids, event, session)
+        if dispatch:
+            self._dispatch_or_defer(notifications)
+        return True
+
+    def _clear_session_if_current(
+        self,
+        generation: int,
+        *,
+        event: AuthChangeEvent = "SIGNED_OUT",
+        notifications: list[Callable[[], None]] | None = None,
+    ) -> bool:
+        with self._session_lock:
+            if generation != self._session_generation:
+                return False
+            self._current_session = None
+            self._session_generation += 1
+            self._session_lineage += 1
+            callback_ids = tuple(self._auth_callbacks)
+            dispatch = self._enqueue_auth_state_change(callback_ids, event, None)
+        if dispatch:
+            self._dispatch_or_defer(notifications)
+        return True
+
+    def _dispatch_or_defer(
+        self, notifications: list[Callable[[], None]] | None
+    ) -> None:
+        if notifications is None:
+            self._drain_auth_state_changes()
+        else:
+            notifications.append(self._drain_auth_state_changes)
+
+    def _subscribe_auth_state_change(
+        self,
+        callback: AuthStateCallback,
+    ) -> AuthSubscription:
+        with self._session_lock:
+            callback_id = self._next_auth_callback_id
+            self._next_auth_callback_id += 1
+            self._auth_callbacks[callback_id] = callback
+            current = self._current_session
+            dispatch = self._enqueue_auth_state_change(
+                (callback_id,),
+                "INITIAL_SESSION",
+                current,
+            )
+        if dispatch:
+            self._drain_auth_state_changes()
+        return AuthSubscription(
+            lambda: self._unsubscribe_auth_state_change(callback_id)
+        )
+
+    def _unsubscribe_auth_state_change(self, callback_id: int) -> None:
+        with self._session_lock:
+            self._auth_callbacks.pop(callback_id, None)
+
+    def _enqueue_auth_state_change(
+        self,
+        callback_ids: tuple[int, ...],
+        event: AuthChangeEvent,
+        session: Session | None,
+    ) -> bool:
+        if not callback_ids:
+            return False
+        self._auth_notifications.append((callback_ids, event, session))
+        if self._dispatching_auth_notifications:
+            return False
+        self._dispatching_auth_notifications = True
+        return True
+
+    def _drain_auth_state_changes(self) -> None:
+        failure: BaseException | None = None
+        while True:
+            with self._session_lock:
+                if not self._auth_notifications:
+                    self._dispatching_auth_notifications = False
+                    break
+                callback_ids, event, session = self._auth_notifications.popleft()
+            current_failure = self._notify_auth_state_change(
+                callback_ids,
+                event,
+                session,
+            )
+            if failure is None:
+                failure = current_failure
+        if failure is not None:
+            raise failure
+
+    def _notify_auth_state_change(
+        self,
+        callback_ids: tuple[int, ...],
+        event: AuthChangeEvent,
+        session: Session | None,
+    ) -> BaseException | None:
+        failure: BaseException | None = None
+        for callback_id in callback_ids:
+            with self._session_lock:
+                callback = self._auth_callbacks.get(callback_id)
+            if callback is None:
+                continue
+            outcome = _CallbackOutcome()
+            with outcome:
+                callback(event, session)
+            if outcome.error is None or isinstance(outcome.error, Exception):
+                continue
+            self._unsubscribe_auth_state_change(callback_id)
+            if failure is None:
+                failure = outcome.error
+        return failure

volcano_sdk/connection_string.py

@@ -0,0 +1,70 @@
+"""Postgres connection helpers for Volcano functions."""
+
+import re
+from urllib.parse import quote, unquote
+
+_FULL_ACCESS_APP_NAME = "volcano_full_access"
+_USER_ACCESS_APP_NAME = "volcano_user_access"
+_CONNECTION_URI_PREFIX = re.compile(r"^postgres(?:ql)?://")
+_INVALID_PERCENT_ENCODING = re.compile(r"%(?![0-9A-Fa-f]{2})")
+_REQUIRED_ERROR = (
+    "database_connection_string: base_connection_string (DATABASE_URL) is required"
+)
+_INVALID_ERROR = (
+    "database_connection_string: base_connection_string is not a valid connection URL"
+)
+
+
+def database_connection_string(
+    base_connection_string: str,
+    *,
+    user_id: str | None = None,
+) -> str:
+    """Select full or user-scoped database access for a Volcano function."""
+    if not base_connection_string:
+        raise ValueError(_REQUIRED_ERROR)
+
+    target, query = _connection_parts(base_connection_string)
+    parameters = _query_parameters(query)
+    application_name = quote(_database_application_name(user_id), safe="")
+    parameters.append(f"application_name={application_name}")
+    return f"{target}?{'&'.join(parameters)}"
+
+
+def _connection_parts(value: str) -> tuple[str, str]:
+    prefix = _CONNECTION_URI_PREFIX.match(value)
+    if prefix is None or _INVALID_PERCENT_ENCODING.search(value):
+        raise ValueError(_INVALID_ERROR)
+
+    authority_end = value.find("/", prefix.end())
+    possible_userinfo_end = value.find("@", prefix.end())
+    userinfo_end = (
+        possible_userinfo_end
+        if possible_userinfo_end != -1
+        and (authority_end == -1 or possible_userinfo_end < authority_end)
+        else -1
+    )
+    query_start = value.find("?", max(prefix.end(), userinfo_end + 1))
+    if query_start == -1:
+        return value, ""
+    return value[:query_start], value[query_start + 1 :]
+
+
+def _query_parameters(query: str) -> list[str]:
+    if not query:
+        return []
+    parameters = [
+        parameter
+        for parameter in query.split("&")
+        if unquote(parameter.partition("=")[0]) != "application_name"
+    ]
+    while parameters and not parameters[-1]:
+        parameters.pop()
+    return parameters
+
+
+def _database_application_name(user_id: str | None) -> str:
+    value = "" if user_id is None else str(user_id)
+    if not value:
+        return _FULL_ACCESS_APP_NAME
+    return f"{_USER_ACCESS_APP_NAME}:{value}"

volcano_sdk/database.py

@@ -0,0 +1,281 @@
+"""Database query facade."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any, Protocol, Self, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .auth import Auth
+    from .models import JSONValue
+
+from ._transport import Transport, invoke, response_payload
+
+
+def _snapshot_json(value: JSONValue) -> JSONValue:
+    if isinstance(value, Mapping):
+        return {key: _snapshot_json(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_snapshot_json(item) for item in value]
+    return value
+
+
+def _snapshot_row(values: Mapping[str, JSONValue]) -> dict[str, JSONValue]:
+    return {key: _snapshot_json(value) for key, value in values.items()}
+
+
+def _snapshot_filter_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        mapping = cast("Mapping[object, object]", value)
+        return {key: _snapshot_filter_value(item) for key, item in mapping.items()}
+    if isinstance(value, (list, tuple)):
+        sequence = cast("list[object] | tuple[object, ...]", value)
+        return [_snapshot_filter_value(item) for item in sequence]
+    return value
+
+
+class DatabaseContext(Protocol):
+    """Client capabilities required by database queries."""
+
+    _transport: Transport
+    auth: Auth
+
+    def _session_token(self) -> str: ...
+
+
+class FilterBuilder:
+    """Shared immutable filters for database operations."""
+
+    _filters: tuple[dict[str, Any], ...]
+
+    def _with_filters(self, filters: tuple[dict[str, Any], ...]) -> Self:
+        raise NotImplementedError
+
+    def eq(self, column: str, value: object) -> Self:
+        """Add an equality filter."""
+        return self._filter(column, "eq", value)
+
+    def neq(self, column: str, value: object) -> Self:
+        """Add an inequality filter."""
+        return self._filter(column, "neq", value)
+
+    def gt(self, column: str, value: object) -> Self:
+        """Add a greater-than filter."""
+        return self._filter(column, "gt", value)
+
+    def gte(self, column: str, value: object) -> Self:
+        """Add a greater-than-or-equal filter."""
+        return self._filter(column, "gte", value)
+
+    def lt(self, column: str, value: object) -> Self:
+        """Add a less-than filter."""
+        return self._filter(column, "lt", value)
+
+    def lte(self, column: str, value: object) -> Self:
+        """Add a less-than-or-equal filter."""
+        return self._filter(column, "lte", value)
+
+    def like(self, column: str, pattern: str) -> Self:
+        """Add a case-sensitive pattern filter."""
+        return self._filter(column, "like", pattern)
+
+    def ilike(self, column: str, pattern: str) -> Self:
+        """Add a case-insensitive pattern filter."""
+        return self._filter(column, "ilike", pattern)
+
+    def is_(self, column: str, value: object) -> Self:
+        """Add a null or boolean identity filter."""
+        return self._filter(column, "is", value)
+
+    def in_(self, column: str, values: Sequence[object]) -> Self:
+        """Add a membership filter."""
+        return self._filter(column, "in", list(values))
+
+    def _filter(self, column: str, operator: str, value: object) -> Self:
+        condition = {
+            "column": column,
+            "operator": operator,
+            "value": _snapshot_filter_value(value),
+        }
+        return self._with_filters((*self._filters, condition))
+
+
+@dataclass(frozen=True, slots=True)
+class QueryBuilder(FilterBuilder):
+    """Build and execute an immutable database select query."""
+
+    _client: DatabaseContext
+    _database_name: str
+    _table: str
+    _columns: tuple[str, ...] = ()
+    _filters: tuple[dict[str, Any], ...] = ()
+    _order: tuple[dict[str, Any], ...] = ()
+    _limit: int | None = None
+    _offset: int | None = None
+
+    def select(self, *columns: str) -> QueryBuilder:
+        """Select the requested columns."""
+        return replace(self, _columns=columns)
+
+    def insert(self, values: Mapping[str, JSONValue]) -> InsertBuilder:
+        """Build an insert for this table."""
+        return InsertBuilder(
+            self._client,
+            self._database_name,
+            self._table,
+            _snapshot_row(values),
+        )
+
+    def update(self, values: Mapping[str, JSONValue]) -> UpdateBuilder:
+        """Build a filtered update for this table."""
+        return UpdateBuilder(
+            self._client,
+            self._database_name,
+            self._table,
+            _snapshot_row(values),
+            self._filters,
+        )
+
+    def delete(self) -> DeleteBuilder:
+        """Build a filtered delete for this table."""
+        return DeleteBuilder(
+            self._client,
+            self._database_name,
+            self._table,
+            self._filters,
+        )
+
+    def order(self, column: str, *, ascending: bool = True) -> QueryBuilder:
+        """Add an ordering clause."""
+        clause = {"column": column, "ascending": ascending}
+        return replace(self, _order=(*self._order, clause))
+
+    def limit(self, count: int) -> QueryBuilder:
+        """Limit the number of returned rows."""
+        return replace(self, _limit=count)
+
+    def offset(self, count: int) -> QueryBuilder:
+        """Skip rows before returning results."""
+        return replace(self, _offset=count)
+
+    def _with_filters(self, filters: tuple[dict[str, Any], ...]) -> QueryBuilder:
+        return replace(self, _filters=filters)
+
+    def execute(self) -> list[dict[str, Any]]:
+        """Execute the query and return its rows."""
+        body: dict[str, Any] = {"table": self._table}
+        if self._columns and self._columns != ("*",):
+            body["select"] = list(self._columns)
+        if self._filters:
+            body["filters"] = list(self._filters)
+        if self._order:
+            body["order"] = list(self._order)
+        if self._limit is not None:
+            body["limit"] = self._limit
+        if self._offset is not None:
+            body["offset"] = self._offset
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                self._client._transport.query_database_select,
+                authorization=token,
+                database_name=self._database_name,
+                body=body,
+            )
+        )
+        payload = response_payload(response, 200)
+        return list(payload["data"])
+
+
+@dataclass(frozen=True, slots=True)
+class InsertBuilder:
+    """Build and execute an immutable database insert."""
+
+    _client: DatabaseContext
+    _database_name: str
+    _table: str
+    _values: dict[str, JSONValue]
+
+    def execute(self) -> list[dict[str, Any]]:
+        """Insert one row and return the inserted rows."""
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                self._client._transport.query_database_insert,
+                authorization=token,
+                database_name=self._database_name,
+                body={"table": self._table, "values": _snapshot_row(self._values)},
+            )
+        )
+        payload = response_payload(response, 200)
+        return list(payload["data"])
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateBuilder(FilterBuilder):
+    """Build and execute an immutable filtered database update."""
+
+    _client: DatabaseContext
+    _database_name: str
+    _table: str
+    _values: dict[str, JSONValue]
+    _filters: tuple[dict[str, Any], ...] = ()
+
+    def _with_filters(self, filters: tuple[dict[str, Any], ...]) -> UpdateBuilder:
+        return replace(self, _filters=filters)
+
+    def execute(self) -> list[dict[str, Any]]:
+        """Update matching rows and return them."""
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                self._client._transport.query_database_update,
+                authorization=token,
+                database_name=self._database_name,
+                body={
+                    "table": self._table,
+                    "values": _snapshot_row(self._values),
+                    "filters": list(self._filters),
+                },
+            )
+        )
+        payload = response_payload(response, 200)
+        return list(payload["data"])
+
+
+@dataclass(frozen=True, slots=True)
+class DeleteBuilder(FilterBuilder):
+    """Build and execute an immutable filtered database delete."""
+
+    _client: DatabaseContext
+    _database_name: str
+    _table: str
+    _filters: tuple[dict[str, Any], ...] = ()
+
+    def _with_filters(self, filters: tuple[dict[str, Any], ...]) -> DeleteBuilder:
+        return replace(self, _filters=filters)
+
+    def execute(self) -> list[dict[str, Any]]:
+        """Delete matching rows and return them."""
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                self._client._transport.query_database_delete,
+                authorization=token,
+                database_name=self._database_name,
+                body={"table": self._table, "filters": list(self._filters)},
+            )
+        )
+        payload = response_payload(response, 200)
+        return list(payload["data"])
+
+
+@dataclass(frozen=True, slots=True)
+class Database:
+    """Entry point for queries against one database."""
+
+    _client: DatabaseContext
+    _name: str
+
+    def from_(self, table: str) -> QueryBuilder:
+        """Create a query builder for a table."""
+        return QueryBuilder(self._client, self._name, table)

volcano_sdk/errors.py

@@ -0,0 +1,61 @@
+"""Typed errors raised by the Volcano SDK."""
+
+from __future__ import annotations
+
+
+class VolcanoError(Exception):
+    """Base error containing structured Volcano response details."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        """Create an error from an API or transport failure."""
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+
+class AuthenticationError(VolcanoError):
+    """The supplied credentials are missing or invalid."""
+
+
+class ValidationError(VolcanoError):
+    """The request failed API validation."""
+
+
+class NotFoundError(VolcanoError):
+    """The requested resource does not exist."""
+
+
+class ConflictError(VolcanoError):
+    """The request conflicts with the current resource state."""
+
+
+class SessionChangedError(ConflictError):
+    """An auth operation completed after the client session changed."""
+
+    def __init__(self) -> None:
+        """Create a deterministic stale-auth-operation error."""
+        super().__init__(
+            "Session changed during authentication operation",
+            status=409,
+            code="auth_session_changed",
+        )
+
+
+class RateLimitedError(VolcanoError):
+    """The API rejected the request because of a rate limit."""
+
+
+class ServerError(VolcanoError):
+    """The Volcano API failed to process the request."""
+
+
+class TransportError(VolcanoError):
+    """The request failed before receiving an API response."""