authgebra 0.1.0__py3-none-any.whl

authgebra/_model.py

@@ -0,0 +1,252 @@
+"""JSON model codec shared by generated synchronous and asynchronous operations."""
+
+from __future__ import annotations
+
+import math
+import re
+import uuid
+from collections.abc import Iterator, Mapping
+from dataclasses import fields
+from enum import Enum
+from typing import ClassVar, TypeVar
+
+from .errors import ProtocolError
+from .models import ApiResult, JSONValue as JSONValue
+
+
+class Unset(Enum):
+    """A field absent from JSON; distinct from explicit JSON null."""
+
+    TOKEN = 0
+
+
+UNSET = Unset.TOKEN
+
+
+class StringEnum(str, Enum):
+    """Named wire enum that preserves a newer server's unknown string values."""
+
+    @classmethod
+    def _missing_(cls, value: object) -> StringEnum | None:
+        if not isinstance(value, str):
+            return None
+        member = str.__new__(cls, value)
+        member._name_ = "UNKNOWN"
+        member._value_ = value
+        return member
+
+
+class Model(Mapping[str, object]):
+    """A generated named object; mapping access preserves existing dict consumers."""
+
+    __schema_pointer__: ClassVar[str]
+    __json_fields__: ClassVar[dict[str, str]]
+    __request_model__: ClassVar[bool] = False
+
+    def __getitem__(self, key: str) -> object:
+        name = self.__json_fields__.get(key)
+        if name is None:
+            raise KeyError(key)
+        value: object = getattr(self, name)
+        if isinstance(value, Unset):
+            raise KeyError(key)
+        return value
+
+    def __iter__(self) -> Iterator[str]:
+        return (key for key, name in self.__json_fields__.items() if not isinstance(getattr(self, name), Unset))
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def to_json(self) -> dict[str, JSONValue]:
+        return {key: json_value(self[key]) for key in self}
+
+    @classmethod
+    def from_json(cls: type[M], value: object) -> M:
+        parsed = decode(cls.__schema_pointer__, value, request=cls.__request_model__)
+        if not isinstance(parsed, cls):
+            raise ValueError(f"expected {cls.__name__}")
+        return parsed
+
+
+M = TypeVar("M", bound=Model)
+R = TypeVar("R", bound=ApiResult)
+
+
+def json_value(value: object) -> JSONValue:
+    """Convert only JSON values and named models, without a lossy floating-point hop."""
+    if isinstance(value, Unset):
+        raise ValueError("UNSET is only valid as an omitted object field")
+    if isinstance(value, Enum):
+        return json_value(value.value)
+    if isinstance(value, Model):
+        return value.to_json()
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("JSON numbers must be finite")
+        return value
+    if isinstance(value, Mapping):
+        result: dict[str, JSONValue] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError("JSON object keys must be strings")
+            result[key] = json_value(item)
+        return result
+    if isinstance(value, (list, tuple)):
+        return [json_value(item) for item in value]
+    raise ValueError(f"unsupported JSON value type: {type(value).__name__}")
+
+
+def request_body(value: Model | Mapping[str, object] | None) -> JSONValue:
+    # The legacy dict path remains server-validated; generated model inputs validate locally.
+    if isinstance(value, Model):
+        raw = value.to_json()
+        decode(value.__schema_pointer__, raw, request=True)
+        return raw
+    return json_value(value)
+
+
+def _schema(pointer: str) -> dict[str, object]:
+    from ._generated.models import SCHEMAS
+
+    return SCHEMAS[pointer]
+
+
+def _child(pointer: str, value: object, *, request: bool) -> object:
+    return decode(pointer, value, request=request)
+
+
+def decode(pointer: str, value: object, *, request: bool = False) -> object:
+    """Decode one schema location. Unknown response properties remain forward compatible."""
+    from ._generated.models import MODEL_TYPES, ENUM_TYPES
+
+    schema = _schema(pointer)
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        return decode(ref, value, request=request)
+    for keyword in ("oneOf", "anyOf", "allOf"):
+        arms = schema.get(keyword)
+        if isinstance(arms, list):
+            if keyword == "allOf":
+                if len(arms) != 1:
+                    raise ValueError(f"unsupported allOf at {pointer}")
+                return _child(f"{pointer}/{keyword}/0", value, request=request)
+            successes: list[object] = []
+            for index in range(len(arms)):
+                try:
+                    successes.append(_child(f"{pointer}/{keyword}/{index}", value, request=request))
+                except ValueError:
+                    pass
+            if not successes or (keyword == "oneOf" and len(successes) != 1):
+                raise ValueError(f"value does not match {keyword} at {pointer}")
+            return successes[0]
+    kind = schema.get("type")
+    if isinstance(kind, list):
+        if value is None and "null" in kind:
+            return None
+        kind = next((item for item in kind if item != "null"), None)
+    if value is None:
+        if kind == "null" or kind is None:
+            return None
+        raise ValueError(f"null is not accepted at {pointer}")
+    enum = schema.get("enum")
+    if isinstance(enum, list):
+        if value not in enum and (request or len(enum) == 1):
+            raise ValueError(f"unknown enum value at {pointer}")
+        enum_type = ENUM_TYPES.get(pointer)
+        return enum_type(value) if enum_type is not None else value
+    if kind == "string":
+        if not isinstance(value, str):
+            raise ValueError(f"string required at {pointer}")
+        if request:
+            minimum, maximum = schema.get("minLength"), schema.get("maxLength")
+            if isinstance(minimum, int) and len(value) < minimum:
+                raise ValueError(f"string too short at {pointer}")
+            if isinstance(maximum, int) and len(value) > maximum:
+                raise ValueError(f"string too long at {pointer}")
+            pattern = schema.get("pattern")
+            if isinstance(pattern, str) and re.fullmatch(pattern, value) is None:
+                raise ValueError(f"string pattern mismatch at {pointer}")
+            if schema.get("format") == "uuid":
+                try:
+                    uuid.UUID(value)
+                except ValueError:
+                    raise ValueError(f"UUID required at {pointer}") from None
+        return value
+    if kind in ("integer", "number"):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or (kind == "integer" and not isinstance(value, int)):
+            raise ValueError(f"{kind} required at {pointer}")
+        if isinstance(value, float) and not math.isfinite(value):
+            raise ValueError(f"finite number required at {pointer}")
+        if request:
+            minimum, maximum = schema.get("minimum"), schema.get("maximum")
+            if isinstance(minimum, (int, float)) and value < minimum:
+                raise ValueError(f"number below minimum at {pointer}")
+            if isinstance(maximum, (int, float)) and value > maximum:
+                raise ValueError(f"number above maximum at {pointer}")
+        return value
+    if kind == "boolean":
+        if not isinstance(value, bool):
+            raise ValueError(f"boolean required at {pointer}")
+        return value
+    if kind == "array":
+        if not isinstance(value, (list, tuple)):
+            raise ValueError(f"array required at {pointer}")
+        if request:
+            minimum, maximum = schema.get("minItems"), schema.get("maxItems")
+            if isinstance(minimum, int) and len(value) < minimum:
+                raise ValueError(f"array too short at {pointer}")
+            if isinstance(maximum, int) and len(value) > maximum:
+                raise ValueError(f"array too long at {pointer}")
+            if schema.get("uniqueItems") is True:
+                import json
+                canonical = [json.dumps(json_value(item), sort_keys=True) for item in value]
+                if len(set(canonical)) != len(canonical):
+                    raise ValueError(f"duplicate array items at {pointer}")
+        return [_child(f"{pointer}/items", item, request=request) for item in value]
+    if kind == "object" or "properties" in schema:
+        if not isinstance(value, Mapping):
+            raise ValueError(f"object required at {pointer}")
+        if any(not isinstance(key, str) for key in value):
+            raise ValueError(f"string object keys required at {pointer}")
+        props = schema.get("properties")
+        if isinstance(props, dict):
+            required = schema.get("required", [])
+            if not isinstance(required, list):
+                raise ValueError(f"invalid required metadata at {pointer}")
+            if any(key not in value for key in required):
+                raise ValueError(f"required field absent at {pointer}")
+            if request and schema.get("additionalProperties") is False and any(key not in props for key in value):
+                raise ValueError(f"unknown field at {pointer}")
+            cls = MODEL_TYPES[pointer]
+            params: dict[str, object] = {}
+            for key, name in cls.__json_fields__.items():
+                if key in value:
+                    escaped = key.replace("~", "~0").replace("/", "~1")
+                    params[name] = _child(f"{pointer}/properties/{escaped}", value[key], request=request)
+            return cls(**params)
+        additional = schema.get("additionalProperties")
+        if isinstance(additional, dict):
+            return {key: _child(f"{pointer}/additionalProperties", item, request=request) for key, item in value.items()}
+        return json_value(value)
+    if kind == "null":
+        raise ValueError(f"null required at {pointer}")
+    if kind is None:
+        return json_value(value)
+    raise ValueError(f"unsupported schema type at {pointer}: {kind}")
+
+
+def typed_result(result: ApiResult, cls: type[R], pointer: str) -> R:
+    try:
+        data = decode(pointer, result.data)
+    except ValueError as exc:
+        raise ProtocolError(
+            "malformed_success_body", status=result.info.status,
+            request_id=result.info.request_id, trace_id=result.info.trace_id,
+            excerpt=str(exc),
+        ) from None
+    values = {field.name: getattr(result, field.name) for field in fields(ApiResult)}
+    values["data"] = data
+    return cls(**values)

authgebra/_parse.py

@@ -0,0 +1,158 @@
+"""Typed parsing of the authorization endpoints' ``data`` payloads (shared by sync and async)."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .errors import ProtocolError
+from ._generated import models as api_models
+from .models import (
+    ApiResult,
+    BatchCheckResult,
+    BatchDecision,
+    CheckResult,
+    Decision,
+    ExplainResult,
+    ResourcePage,
+    ResourceRef,
+    RevisionResult,
+)
+
+
+def _bad(result: ApiResult, what: str) -> ProtocolError:
+    return ProtocolError(
+        "malformed_success_body",
+        status=result.info.status,
+        request_id=result.info.request_id,
+        trace_id=result.info.trace_id,
+        excerpt=what,
+    )
+
+
+def _decision(result: ApiResult, value: Any) -> Decision:
+    try:
+        return Decision(value)
+    except ValueError:
+        # Fail closed: an unrecognised decision is never interpreted as allow (or deny).
+        raise ProtocolError(
+            "unknown_decision",
+            status=result.info.status,
+            request_id=result.info.request_id,
+            trace_id=result.info.trace_id,
+        ) from None
+
+
+def _obj(result: ApiResult, value: Any, what: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise _bad(result, what)
+    return value
+
+
+def _str(result: ApiResult, obj: Mapping[str, Any], key: str) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str):
+        raise _bad(result, f"{key} must be a string")
+    return value
+
+
+def _int(result: ApiResult, obj: Mapping[str, Any], key: str) -> int:
+    value = obj.get(key)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _bad(result, f"{key} must be an integer")
+    return value
+
+
+def _policy(result: ApiResult, obj: Mapping[str, Any]) -> api_models.AuthzPolicyRef | None:
+    value = obj.get("matched_policy")
+    if value is None:
+        return None
+    try:
+        return api_models.AuthzPolicyRef.from_json(value)
+    except ValueError:
+        raise _bad(result, "matched_policy") from None
+
+
+def resource_ref(result: ApiResult, value: Any) -> ResourceRef:
+    obj = _obj(result, value, "resource")
+    return ResourceRef(_str(result, obj, "resource_type_code"), _str(result, obj, "external_id"))
+
+
+def check(result: ApiResult) -> CheckResult:
+    data = _obj(result, result.data, "data")
+    return CheckResult(
+        decision=_decision(result, data.get("decision")),
+        reason_code=_str(result, data, "reason_code"),
+        matched_policy=_policy(result, data),
+        info=result.info,
+        meta=result.meta,
+    )
+
+
+def _batch_items(result: ApiResult, value: Any) -> tuple[BatchDecision, ...]:
+    if not isinstance(value, list):
+        raise _bad(result, "decision list expected")
+    items = []
+    for entry in value:
+        obj = _obj(result, entry, "batch item")
+        items.append(
+            BatchDecision(
+                resource=resource_ref(result, obj.get("resource")),
+                reason_code=_str(result, obj, "reason_code"),
+                matched_policy=_policy(result, obj),
+            )
+        )
+    return tuple(items)
+
+
+def batch(result: ApiResult) -> BatchCheckResult:
+    data = _obj(result, result.data, "data")
+    return BatchCheckResult(
+        allowed=_batch_items(result, data.get("allowed")),
+        denied=_batch_items(result, data.get("denied")),
+        info=result.info,
+        meta=result.meta,
+    )
+
+
+def resource_page(result: ApiResult) -> ResourcePage:
+    if not isinstance(result.data, list) or result.page is None:
+        raise _bad(result, "paged list expected")
+    return ResourcePage(
+        items=tuple(resource_ref(result, entry) for entry in result.data),
+        page=result.page,
+        info=result.info,
+        meta=result.meta,
+    )
+
+
+def explain(result: ApiResult) -> ExplainResult:
+    data = _obj(result, result.data, "data")
+    policies = data.get("policies")
+    truncated = data.get("truncated")
+    if not isinstance(policies, list) or not isinstance(truncated, bool):
+        raise _bad(result, "policies/truncated")
+    try:
+        explanations = tuple(api_models.AuthzPolicyExplanation.from_json(policy) for policy in policies)
+    except ValueError:
+        raise _bad(result, "policies") from None
+    return ExplainResult(
+        decision=_decision(result, data.get("decision")),
+        reason_code=_str(result, data, "reason_code"),
+        matched_policy=_policy(result, data),
+        policies=explanations,
+        truncated=truncated,
+        total_steps=_int(result, data, "total_steps"),
+        info=result.info,
+        meta=result.meta,
+    )
+
+
+def revision(result: ApiResult) -> RevisionResult:
+    data = _obj(result, result.data, "data")
+    return RevisionResult(
+        db_revision=_int(result, data, "db_revision"),
+        snapshot_generation=_int(result, data, "snapshot_generation"),
+        status=_str(result, data, "status"),
+        info=result.info,
+        meta=result.meta,
+    )

authgebra/_version.py

@@ -0,0 +1,3 @@
+"""SDK package version (independent of the server API version)."""
+
+__version__ = "0.1.0"

authgebra/aclient.py

@@ -0,0 +1,256 @@
+"""Asynchronous client (``asyncio``)."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import time
+from types import TracebackType
+from typing import Any, AsyncIterator, Mapping
+
+import httpx
+
+from . import _core, _parse
+from ._generated.aio import AsyncAdminClient
+from .client import DEFAULT_MAX_PAGES
+from .config import Config
+from .errors import ApiError, PaginationError, ProtocolError, TransportError
+from .models import (
+    ApiResult,
+    BatchCheckRequest,
+    BatchCheckResult,
+    CheckRequest,
+    CheckResult,
+    ExplainRequest,
+    ExplainResult,
+    ListResourcesRequest,
+    ResourcePage,
+    RevisionResult,
+)
+
+log = logging.getLogger("authgebra")
+
+
+class AsyncAuthorizationClient:
+    """Async twin of :class:`~authgebra.client.AuthorizationClient` (identical semantics)."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._c = client
+
+    async def check(
+        self, request: CheckRequest, *, request_id: str | None = None, traceparent: str | None = None
+    ) -> CheckResult:
+        return _parse.check(await self._post("/api/v1/authz/check", request.to_json(), request_id, traceparent))
+
+    async def batch_check(
+        self, request: BatchCheckRequest, *, request_id: str | None = None, traceparent: str | None = None
+    ) -> BatchCheckResult:
+        return _parse.batch(
+            await self._post("/api/v1/authz/batch-check", request.to_json(), request_id, traceparent)
+        )
+
+    async def explain(
+        self, request: ExplainRequest, *, request_id: str | None = None, traceparent: str | None = None
+    ) -> ExplainResult:
+        return _parse.explain(
+            await self._post("/api/v1/authz/explain", request.to_json(), request_id, traceparent)
+        )
+
+    async def list_resources(
+        self,
+        request: ListResourcesRequest,
+        *,
+        request_id: str | None = None,
+        traceparent: str | None = None,
+    ) -> ResourcePage:
+        return _parse.resource_page(
+            await self._post("/api/v1/authz/list-resources", request.to_json(), request_id, traceparent)
+        )
+
+    async def iter_list_resources(
+        self,
+        request: ListResourcesRequest,
+        *,
+        max_pages: int = DEFAULT_MAX_PAGES,
+        traceparent: str | None = None,
+    ) -> AsyncIterator[ResourcePage]:
+        """Async page iterator: lazy (backpressure), cancellable, bounded, never stitches generations."""
+        if max_pages < 1:
+            raise ValueError("max_pages must be >= 1")
+        trace = _core.resolve_traceparent(self._c.config, traceparent)
+        current = request
+        generation: int | None = None
+        seen: set[str] = set()
+        for _ in range(max_pages):
+            page = await self.list_resources(current, traceparent=trace)
+            gen = page.meta.snapshot_generation if page.meta else None
+            if generation is None:
+                generation = gen
+            elif gen is not None and gen != generation:
+                raise PaginationError(
+                    f"snapshot generation changed during paging ({generation} -> {gen}); restart explicitly"
+                )
+            yield page
+            cursor = page.page.next_cursor
+            if not page.page.has_more or cursor is None:
+                return
+            if cursor in seen:
+                raise PaginationError("server returned a repeated cursor; refusing to loop")
+            seen.add(cursor)
+            current = request.with_cursor(cursor)
+        raise PaginationError(f"page limit of {max_pages} reached while more pages remain")
+
+    async def revision(
+        self, *, request_id: str | None = None, traceparent: str | None = None
+    ) -> RevisionResult:
+        return _parse.revision(
+            await self._c.request(
+                "GET", "/api/v1/authz/revision", request_id=request_id, traceparent=traceparent
+            )
+        )
+
+    async def _post(
+        self, path: str, body: Mapping[str, Any], request_id: str | None, traceparent: str | None
+    ) -> ApiResult:
+        return await self._c.request(
+            "POST", path, json=body, safe=True, request_id=request_id, traceparent=traceparent
+        )
+
+
+class AsyncClient:
+    """Asynchronous Authgebra client; use ``async with``.
+
+    Cancelling the awaiting task cancels the in-flight request; no retry is attempted after a
+    cancellation.
+    """
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._owns_http = config.http_client is None
+        self._http: httpx.AsyncClient = config.http_client or httpx.AsyncClient(
+            verify=config.verify,
+            transport=config.transport,
+            follow_redirects=False,
+            trust_env=False,
+        )
+        self.authorization = AsyncAuthorizationClient(self)
+        self.admin = AsyncAdminClient(self)
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, object] | None = None,
+        json: Any = None,
+        if_match: str | None = None,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        traceparent: str | None = None,
+        safe: bool | None = None,
+        envelope: bool = True,
+    ) -> ApiResult:
+        cfg = self.config
+        is_safe = method.upper() in ("GET", "HEAD") if safe is None else safe
+        body = None if json is None else _core.serialize_json(json)
+        trace = _core.resolve_traceparent(cfg, traceparent)
+        retries_done = 0
+        while True:
+            attempt_trace = trace if trace is None or retries_done == 0 else _core.child_traceparent(trace)
+            prep = _core.prepare(
+                cfg,
+                method,
+                path,
+                query=query,
+                body=body,
+                token=await self._token(),
+                if_match=if_match,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+                traceparent=attempt_trace,
+                safe=is_safe,
+            )
+            try:
+                return _core.interpret(await self._send(prep), envelope=envelope)
+            except (ApiError, TransportError, ProtocolError) as exc:
+                exc.attempts = retries_done + 1
+                if not _core.should_retry(
+                    cfg.retry,
+                    safe=prep.safe,
+                    has_key=prep.has_key,
+                    retries_done=retries_done,
+                    error=exc,
+                ):
+                    raise
+                delay = _core.retry_delay(cfg.retry, retries_done, exc)
+                log.debug("retrying %s %s in %.3fs (attempt %d)", prep.method, path, delay, retries_done + 2)
+                await (cfg.retry.async_sleep or asyncio.sleep)(delay)
+                retries_done += 1
+
+    async def _token(self) -> str | None:
+        provider = self.config.token_provider
+        if provider is None:
+            return None
+        token = provider()
+        if inspect.isawaitable(token):
+            token = await token
+        if token is not None and not isinstance(token, str):
+            raise TypeError("token_provider must return str or None")
+        return token
+
+    async def _send(self, prep: _core.Prepared) -> _core.RawResponse:
+        cfg = self.config
+        try:
+            return await asyncio.wait_for(self._attempt(prep), timeout=cfg.timeout)
+        except asyncio.TimeoutError:
+            raise _core.build_transport_error("timeout", prep, "deadline exceeded") from None
+
+    async def _attempt(self, prep: _core.Prepared) -> _core.RawResponse:
+        cfg = self.config
+        timeout = httpx.Timeout(
+            connect=min(cfg.connect_timeout, cfg.timeout), read=cfg.timeout, write=cfg.timeout, pool=cfg.timeout
+        )
+        try:
+            async with self._http.stream(
+                prep.method,
+                prep.url,
+                params=prep.params or None,
+                content=prep.content,
+                headers=prep.headers,
+                timeout=timeout,
+            ) as response:
+                declared = response.headers.get("content-length")
+                if declared is not None and declared.isdigit() and int(declared) > cfg.max_response_bytes:
+                    raise ProtocolError("response_too_large", status=response.status_code, request_id=prep.request_id)
+                chunks: list[bytes] = []
+                size = 0
+                async for chunk in response.aiter_bytes():
+                    size += len(chunk)
+                    if size > cfg.max_response_bytes:
+                        raise ProtocolError(
+                            "response_too_large", status=response.status_code, request_id=prep.request_id
+                        )
+                    chunks.append(chunk)
+                headers = {name.lower(): value for name, value in response.headers.items()}
+                log.debug("%s %s -> %d", prep.method, prep.url.split("?", 1)[0], response.status_code)
+                return _core.RawResponse(response.status_code, headers, b"".join(chunks))
+        except (ProtocolError, TransportError):
+            raise
+        except httpx.HTTPError as exc:
+            raise _core.transport_error(exc, prep) from exc