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

volcano_sdk/functions.py

@@ -0,0 +1,277 @@
+"""Serverless function invocation facade."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Protocol, cast
+
+from . import _function_resolution
+from ._function_resolution import FunctionResolution
+from ._transport import TransportResponse, invoke, response_payload
+from .errors import NotFoundError
+from .models import FunctionResponse, JSONValue
+
+if TYPE_CHECKING:
+    from .client import VolcanoClient
+
+_FUNCTION_NAME = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_INVALID_FUNCTION_NAME = (
+    "Function name must be DNS-safe: lowercase letters, numbers, and hyphens; "
+    "1-63 characters"
+)
+_INVALID_FUNCTION_RESPONSE = "Expected a complete function response"
+_INVALID_FUNCTION_PAYLOAD = "Function payload must be a mapping"
+_UNKNOWN_FUNCTION = "Function was not found"
+_HTTP_SUCCESS_MIN = 200
+_HTTP_SUCCESS_MAX = 300
+_HTTP_NOT_FOUND = 404
+# Present only once the platform has dispatched to the function.
+_FUNCTION_INVOKED_HEADER = "X-Volcano-Function-Invoked"
+
+
+class FunctionsTransport(Protocol):
+    """Transport operations required by the functions facade."""
+
+    def resolve_function_for_invocation(
+        self,
+        *,
+        authorization: str,
+        name: str,
+    ) -> TransportResponse:
+        """Resolve a function name to its canonical identifier."""
+        ...
+
+    def invoke_function(
+        self,
+        *,
+        authorization: str,
+        function_id: str,
+        payload: Mapping[str, JSONValue],
+    ) -> TransportResponse:
+        """Invoke a resolved function identifier."""
+        ...
+
+    def invoke_function_url(
+        self,
+        *,
+        authorization: str,
+        invoke_url: str,
+        payload: Mapping[str, JSONValue],
+    ) -> TransportResponse:
+        """Invoke a function at its resolved endpoint."""
+        ...
+
+
+class Functions:
+    """Invoke deployed Volcano functions by name."""
+
+    def __init__(self, client: VolcanoClient) -> None:
+        """Bind function calls to a Volcano client."""
+        self._client = client
+
+    def invoke(
+        self,
+        name: str,
+        payload: Mapping[str, JSONValue] | None = None,
+    ) -> FunctionResponse:
+        """Resolve and invoke a function with an optional JSON object payload."""
+        name = _function_name(name)
+        request_payload = _function_payload(payload)
+        authorization = self._client._function_token()
+        transport = cast("FunctionsTransport", self._client._transport)
+        resolution = self._resolve(transport, authorization, name)
+        response = self._invoke_resolved(
+            transport, authorization, resolution, request_payload
+        )
+        if _stale_mapping(response):
+            # The function was deleted and recreated, so the cached identity no
+            # longer exists. Resolve again before giving up.
+            _function_resolution.forget(
+                self._client._api_base_url(), authorization, name
+            )
+            resolution = self._resolve(transport, authorization, name)
+            response = self._invoke_resolved(
+                transport, authorization, resolution, request_payload
+            )
+        return self._response(response)
+
+    @staticmethod
+    def _invoke_resolved(
+        transport: FunctionsTransport,
+        authorization: str,
+        resolution: FunctionResolution,
+        payload: Mapping[str, JSONValue],
+    ) -> TransportResponse:
+        if resolution.invoke_url is None:
+            response = invoke(
+                transport.invoke_function,
+                authorization=authorization,
+                function_id=resolution.function_id,
+                payload=payload,
+            )
+        else:
+            response = invoke(
+                transport.invoke_function_url,
+                authorization=authorization,
+                invoke_url=resolution.invoke_url,
+                payload=payload,
+            )
+        return cast("TransportResponse", response)
+
+    def _resolve(
+        self,
+        transport: FunctionsTransport,
+        authorization: str,
+        name: str,
+    ) -> FunctionResolution:
+        """Return the function's identity, reusing a live cached resolution."""
+        api_url = self._client._api_base_url()
+        cached = self._cached(api_url, authorization, name)
+        if cached is not None:
+            return cached
+
+        # Hold the name's lock across the round trip so concurrent callers wait
+        # for one resolve instead of each opening their own.
+        with _function_resolution.resolve_lock(api_url, authorization, name):
+            cached = self._cached(api_url, authorization, name)
+            if cached is not None:
+                return cached
+            return self._resolve_uncached(transport, api_url, authorization, name)
+
+    @staticmethod
+    def _cached(
+        api_url: str, authorization: str, name: str
+    ) -> FunctionResolution | None:
+        cached = _function_resolution.lookup(api_url, authorization, name)
+        if cached is None:
+            return None
+        if cached.resolution is None:
+            raise NotFoundError(_UNKNOWN_FUNCTION, status=_HTTP_NOT_FOUND)
+        return cached.resolution
+
+    def _resolve_uncached(
+        self,
+        transport: FunctionsTransport,
+        api_url: str,
+        authorization: str,
+        name: str,
+    ) -> FunctionResolution:
+        resolved = invoke(
+            transport.resolve_function_for_invocation,
+            authorization=authorization,
+            name=name,
+        )
+        if int(resolved.status_code) == _HTTP_NOT_FOUND:
+            _function_resolution.store_missing(api_url, authorization, name)
+        payload = response_payload(resolved, _HTTP_SUCCESS_MIN)
+        resolution = self._resolution(payload, api_url)
+        _function_resolution.store(
+            api_url, authorization, name, resolution, self._cache_ttl(payload)
+        )
+        return resolution
+
+    @staticmethod
+    def _resolution(payload: object, api_url: str) -> FunctionResolution:
+        if not isinstance(payload, Mapping):
+            raise TypeError(_INVALID_FUNCTION_RESPONSE)
+        values = cast("Mapping[str, object]", payload)
+        function_id = values.get("function_id")
+        if not isinstance(function_id, str) or not function_id:
+            raise TypeError(_INVALID_FUNCTION_RESPONSE)
+        # Absent when the deployment serves no public invocation domain, as in
+        # local development; the function is reached through the API instead.
+        return FunctionResolution(
+            function_id=function_id,
+            invoke_url=_function_resolution.valid_invoke_url(
+                values.get("invoke_url"), api_url
+            ),
+        )
+
+    @staticmethod
+    def _cache_ttl(payload: object) -> float:
+        values = cast("Mapping[str, object]", payload)
+        ttl = values.get("cache_ttl_seconds")
+        if not isinstance(ttl, int) or isinstance(ttl, bool) or ttl <= 0:
+            raise TypeError(_INVALID_FUNCTION_RESPONSE)
+        return float(ttl)
+
+    @staticmethod
+    def _response(response: TransportResponse) -> FunctionResponse:
+        status = int(response.status_code)
+        version = _header(response.headers, "X-Volcano-Version")
+        # A non-2xx the platform produced never reached the function, so it is
+        # an SDK error rather than the function's answer. That turns on the
+        # dispatch marker, not on the version stamp, which every response
+        # carries — keying on the stamp would classify every platform failure
+        # as though the function had returned it.
+        dispatched = _header(response.headers, _FUNCTION_INVOKED_HEADER) is not None
+        if not _HTTP_SUCCESS_MIN <= status < _HTTP_SUCCESS_MAX and not dispatched:
+            response_payload(response, _HTTP_SUCCESS_MIN)
+        headers = {} if response.headers is None else dict(response.headers)
+        return FunctionResponse(
+            data=_function_data(response),
+            status=status,
+            headers=headers,
+            version=version,
+        )
+
+
+def _stale_mapping(response: TransportResponse) -> bool:
+    """Report a platform 404, which means the cached function identity is gone.
+
+    A function that answers 404 itself must be returned rather than retried:
+    invoking twice would run the caller's side effects twice. The platform sets
+    X-Volcano-Function-Invoked only after dispatch, so its absence is what
+    separates the two. X-Volcano-Version cannot: the server stamps it on every
+    response, including errors raised before the function is reached.
+    """
+    return (
+        int(response.status_code) == _HTTP_NOT_FOUND
+        and _header(response.headers, _FUNCTION_INVOKED_HEADER) is None
+    )
+
+
+def _function_data(response: TransportResponse) -> JSONValue:
+    if not response.content:
+        return cast("JSONValue", response.payload)
+    text = response.content.decode("utf-8-sig", errors="replace")
+    if not text:
+        return None
+    content_type = (_header(response.headers, "Content-Type") or "").lower()
+    if "application/json" in content_type or text.startswith(("{", "[")):
+        try:
+            return cast(
+                "JSONValue", json.loads(text, parse_constant=_reject_json_constant)
+            )
+        except ValueError:
+            pass
+    return text
+
+
+def _reject_json_constant(value: str) -> None:
+    raise ValueError(value)
+
+
+def _header(headers: Mapping[str, str] | None, name: str) -> str | None:
+    if headers is None:
+        return None
+    for key, value in headers.items():
+        if key.casefold() == name.casefold():
+            return value
+    return None
+
+
+def _function_name(value: object) -> str:
+    if not isinstance(value, str) or _FUNCTION_NAME.fullmatch(value) is None:
+        raise ValueError(_INVALID_FUNCTION_NAME)
+    return value
+
+
+def _function_payload(value: object) -> dict[str, JSONValue]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise TypeError(_INVALID_FUNCTION_PAYLOAD)
+    return dict(cast("Mapping[str, JSONValue]", value))

volcano_sdk/locks.py

@@ -0,0 +1,227 @@
+"""Distributed lock facade."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager, suppress
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol, cast
+from uuid import uuid4
+
+from ._lock_guard import LockGuard, _lease_now
+from ._lock_worker import LockRenewer
+from ._transport import Transport, invoke, response_payload
+from .models import LockLease, LockState
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+_MIN_LOCK_TTL_SECONDS = 5
+_MAX_LOCK_TTL_SECONDS = 7_776_000
+_INVALID_LOCK_TTL = "ttl must be an integer between 5 seconds and 90 days"
+_MISSING_RENEWAL_FAILURE = "lock guard rejected renewal without a failure"
+
+
+class LocksContext(Protocol):
+    """Client capabilities required by distributed locks."""
+
+    _transport: Transport
+
+    def _service_token(self) -> str: ...
+
+
+class LockGetTransport(Protocol):
+    """Transport capability required to inspect a lock."""
+
+    def get_project_lock(
+        self,
+        *,
+        authorization: str,
+        key: str,
+    ) -> object:
+        """Get one project-scoped lock."""
+        ...
+
+
+class LockRenewTransport(Protocol):
+    """Transport capability required to renew a lock."""
+
+    def renew_project_lock(
+        self,
+        *,
+        authorization: str,
+        key: str,
+        ttl: int,
+        token: str,
+    ) -> object:
+        """Renew one project-scoped lock."""
+        ...
+
+
+class LockForceReleaseTransport(Protocol):
+    """Transport capability required to force release a lock."""
+
+    def force_release_project_lock(
+        self,
+        *,
+        authorization: str,
+        key: str,
+    ) -> object:
+        """Force release one project-scoped lock."""
+        ...
+
+
+def _parse_datetime(value: object) -> datetime | None:
+    if value is None:
+        return None
+    return datetime.fromisoformat(str(value))
+
+
+def _validate_ttl(ttl: object) -> None:
+    if (
+        isinstance(ttl, bool)
+        or not isinstance(ttl, int)
+        or not _MIN_LOCK_TTL_SECONDS <= ttl <= _MAX_LOCK_TTL_SECONDS
+    ):
+        raise ValueError(_INVALID_LOCK_TTL)
+
+
+class Locks:
+    """Acquire and release project-scoped distributed locks."""
+
+    def __init__(self, client: LocksContext) -> None:
+        """Create a lock facade backed by a client."""
+        self._client = client
+
+    def get(self, key: str) -> LockState:
+        """Return the current state of a project-scoped lock."""
+        transport = cast("LockGetTransport", self._client._transport)
+        response = invoke(
+            transport.get_project_lock,
+            authorization=self._client._service_token(),
+            key=key,
+        )
+        payload = response_payload(response, 200)
+        return LockState(
+            held=payload["held"],
+            expires_at=_parse_datetime(payload.get("expires_at")),
+            fencing_token=payload.get("fencing_token"),
+        )
+
+    def acquire(self, key: str, *, ttl: int) -> LockLease:
+        """Acquire a lock lease for the requested number of seconds."""
+        _validate_ttl(ttl)
+        token = str(uuid4())
+        response = invoke(
+            self._client._transport.acquire_project_lock,
+            authorization=self._client._service_token(),
+            key=key,
+            ttl=ttl,
+            token=token,
+        )
+        payload = response_payload(response, 201)
+        return LockLease(
+            key=key,
+            token=token,
+            expires_at=_parse_datetime(payload.get("expires_at")),
+            fencing_token=payload.get("fencing_token"),
+        )
+
+    def renew(self, key: str, lease: LockLease, *, ttl: int) -> LockLease:
+        """Renew a lock lease and return its immutable replacement."""
+        _validate_ttl(ttl)
+        transport = cast("LockRenewTransport", self._client._transport)
+        response = invoke(
+            transport.renew_project_lock,
+            authorization=self._client._service_token(),
+            key=key,
+            ttl=ttl,
+            token=lease.token,
+        )
+        payload = response_payload(response, 200)
+        return LockLease(
+            key=key,
+            token=lease.token,
+            expires_at=_parse_datetime(payload.get("expires_at")),
+            fencing_token=payload.get("fencing_token"),
+        )
+
+    def release(self, key: str, lease: LockLease) -> None:
+        """Release a lock lease."""
+        response = invoke(
+            self._client._transport.release_project_lock,
+            authorization=self._client._service_token(),
+            key=key,
+            token=lease.token,
+        )
+        response_payload(response, 204)
+
+    def force_release(self, key: str) -> None:
+        """Release a lock regardless of which token owns it."""
+        transport = cast("LockForceReleaseTransport", self._client._transport)
+        response = invoke(
+            transport.force_release_project_lock,
+            authorization=self._client._service_token(),
+            key=key,
+        )
+        response_payload(response, 204)
+
+    @contextmanager
+    def with_lock(self, key: str, *, ttl: int) -> Generator[LockGuard, None, None]:
+        """Hold and automatically renew a lock for the context's lifetime."""
+        _validate_ttl(ttl)
+        started_at = _lease_now()
+        guard = LockGuard(
+            self.acquire(key, ttl=ttl),
+            ttl=ttl,
+            started_at=started_at,
+        )
+        renewer = LockRenewer(self, key, guard, ttl=ttl)
+        renewer_started = False
+        body_failed = False
+        try:
+            self._prepare_guard(key, guard, ttl=ttl)
+            renewer.start()
+            renewer_started = True
+            yield guard
+        except BaseException:
+            body_failed = True
+            raise
+        finally:
+            try:
+                if renewer_started:
+                    renewer.stop()
+            finally:
+                self._finish_guard(key, guard, body_failed=body_failed)
+
+    def _prepare_guard(self, key: str, guard: LockGuard, *, ttl: int) -> None:
+        if guard.renewal_delay() != 0:
+            return
+        started_at = _lease_now()
+        renewed = self.renew(key, guard.lease, ttl=ttl)
+        if guard.replace_lease(renewed, started_at=started_at):
+            return
+        failure = guard._renewal_failure()
+        if failure is None:
+            raise RuntimeError(_MISSING_RENEWAL_FAILURE)
+        raise failure
+
+    def _finish_guard(
+        self,
+        key: str,
+        guard: LockGuard,
+        *,
+        body_failed: bool,
+    ) -> None:
+        failure = guard._renewal_failure()
+        try:
+            if body_failed or failure is not None:
+                with suppress(Exception):
+                    self.release(key, guard.lease)
+            else:
+                self.release(key, guard.lease)
+        finally:
+            guard._close()
+        if body_failed:
+            return
+        if failure is not None:
+            raise failure

volcano_sdk/logs.py

@@ -0,0 +1,140 @@
+"""Project runtime log facade."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Protocol, cast
+
+from ._transport import TransportResponse, invoke, response_payload
+from .models import JSONValue, LogActivityResponse, LogSearchResponse, _freeze_json
+
+if TYPE_CHECKING:
+    from .client import VolcanoClient
+
+_INVALID_PROJECT_ID = "project_id must be a non-empty string"
+_INVALID_LOG_REQUEST = "Log request must be a mapping"
+_INVALID_LOG_RESPONSE = "Expected a complete log response"
+
+
+class LogsTransport(Protocol):
+    """Transport operations required by the logs facade."""
+
+    def search_project_logs(
+        self,
+        *,
+        authorization: str,
+        project_id: str,
+        request: Mapping[str, JSONValue],
+    ) -> TransportResponse:
+        """Search a project's retained logs."""
+        ...
+
+    def get_project_log_activity(
+        self,
+        *,
+        authorization: str,
+        project_id: str,
+        request: Mapping[str, JSONValue],
+    ) -> TransportResponse:
+        """Get bucketed log activity for a project."""
+        ...
+
+
+class Logs:
+    """Search retained project logs and activity."""
+
+    def __init__(self, client: VolcanoClient) -> None:
+        """Bind log reads to a Volcano client."""
+        self._client = client
+
+    def search(
+        self,
+        project_id: str,
+        request: Mapping[str, JSONValue],
+    ) -> LogSearchResponse:
+        """Search retained logs for one project resource type."""
+        project_id, request = _log_request(project_id, request)
+        transport = cast("LogsTransport", self._client._transport)
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                transport.search_project_logs,
+                authorization=token,
+                project_id=project_id,
+                request=request,
+            )
+        )
+        return _search_response(response_payload(response, 200))
+
+    def activity(
+        self,
+        project_id: str,
+        request: Mapping[str, JSONValue],
+    ) -> LogActivityResponse:
+        """Get bucketed activity for one project resource type."""
+        project_id, request = _log_request(project_id, request)
+        transport = cast("LogsTransport", self._client._transport)
+        response = self._client.auth._session_request(
+            lambda token: invoke(
+                transport.get_project_log_activity,
+                authorization=token,
+                project_id=project_id,
+                request=request,
+            )
+        )
+        return _activity_response(response_payload(response, 200))
+
+
+def _log_request(
+    project_id: object,
+    request: object,
+) -> tuple[str, Mapping[str, JSONValue]]:
+    if not isinstance(project_id, str) or not project_id.strip():
+        raise ValueError(_INVALID_PROJECT_ID)
+    if not isinstance(request, Mapping):
+        raise TypeError(_INVALID_LOG_REQUEST)
+    snapshot = _freeze_json(cast("Mapping[str, JSONValue]", request))
+    return project_id, cast("Mapping[str, JSONValue]", snapshot)
+
+
+def _response_values(payload: object) -> Mapping[str, object]:
+    if not isinstance(payload, Mapping):
+        raise TypeError(_INVALID_LOG_RESPONSE)
+    return cast("Mapping[str, object]", payload)
+
+
+def _response_data(values: Mapping[str, object]) -> tuple[Mapping[str, JSONValue], ...]:
+    raw_data = values.get("data")
+    if not isinstance(raw_data, list):
+        raise TypeError(_INVALID_LOG_RESPONSE)
+    data = cast("list[object]", raw_data)
+    if any(not isinstance(item, Mapping) for item in data):
+        raise TypeError(_INVALID_LOG_RESPONSE)
+    return tuple(cast("Mapping[str, JSONValue]", item) for item in data)
+
+
+def _search_response(payload: object) -> LogSearchResponse:
+    values = _response_values(payload)
+    limit = values.get("limit")
+    has_more = values.get("has_more")
+    next_cursor = values.get("next_cursor")
+    if (
+        not isinstance(limit, int)
+        or isinstance(limit, bool)
+        or not isinstance(has_more, bool)
+        or (next_cursor is not None and not isinstance(next_cursor, str))
+    ):
+        raise TypeError(_INVALID_LOG_RESPONSE)
+    return LogSearchResponse(
+        data=_response_data(values),
+        limit=limit,
+        has_more=has_more,
+        next_cursor=next_cursor,
+    )
+
+
+def _activity_response(payload: object) -> LogActivityResponse:
+    values = _response_values(payload)
+    total = values.get("total")
+    if not isinstance(total, int) or isinstance(total, bool):
+        raise TypeError(_INVALID_LOG_RESPONSE)
+    return LogActivityResponse(data=_response_data(values), total=total)