meterbase 0.1.0__py3-none-any.whl

meterbase/__init__.py

@@ -0,0 +1,59 @@
+"""Python SDK for the Meterbase engine."""
+
+from . import types
+from ._async.client import AsyncHold, AsyncMeterbase
+from ._not_given import NOT_GIVEN, NotGiven
+from ._sync.client import Hold, Meterbase
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    CycleChangeRequiresResetError,
+    InvalidIdempotencyKeyError,
+    InvalidRequestError,
+    MeterbaseError,
+    NotFoundError,
+    PeriodSettlingError,
+    PermissionDeniedError,
+    RateLimitError,
+    ReservationMismatchError,
+    ServerError,
+    TooLateError,
+    WebhookVerificationError,
+    error_from_response,
+)
+from .webhooks import WebhookHeaders, verify_webhook
+
+__all__ = [
+    "NOT_GIVEN",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncHold",
+    "AsyncMeterbase",
+    "AuthenticationError",
+    "ConflictError",
+    "CycleChangeRequiresResetError",
+    "Hold",
+    "InvalidIdempotencyKeyError",
+    "InvalidRequestError",
+    "Meterbase",
+    "MeterbaseError",
+    "NotFoundError",
+    "NotGiven",
+    "PeriodSettlingError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ReservationMismatchError",
+    "ServerError",
+    "TooLateError",
+    "WebhookHeaders",
+    "WebhookVerificationError",
+    "__version__",
+    "error_from_response",
+    "types",
+    "verify_webhook",
+]

meterbase/_async/_io.py

@@ -0,0 +1,22 @@
+"""
+What the async client does that the sync one does differently, kept out of the
+code `scripts/unasync.py` turns into the sync client. `_sync/_io.py` is its
+twin, and like this file is written by hand.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable
+from typing import TypeVar
+
+_A = TypeVar("_A")
+_B = TypeVar("_B")
+
+sleep = asyncio.sleep
+
+
+async def both(first: Awaitable[_A], second: Awaitable[_B]) -> tuple[_A, _B]:
+    """Two calls at once, where the sync client makes them one after the
+    other."""
+    return await asyncio.gather(first, second)

meterbase/_async/_transport.py

@@ -0,0 +1,181 @@
+"""
+Everything goes through `request`, so authentication, timeouts, retries and
+error mapping are defined once.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any, TypeVar
+
+import httpx
+
+from .._http import (
+    Body,
+    Query,
+    RequestOptions,
+    backoff,
+    build_url,
+    encode_body,
+    error_from,
+    origin_of,
+    parse_body,
+    request_headers,
+    should_retry,
+)
+from .._models import construct
+from .._time import to_ms
+from ..errors import APIConnectionError, APITimeoutError, MeterbaseError
+from ._io import sleep
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        http_client: httpx.AsyncClient | None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._origin = origin_of(base_url)
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        # A client the caller passed in is theirs to close.
+        self._owns_http = http_client is None
+
+        # How far the engine's clock is ahead of this machine's, in
+        # milliseconds. Idempotency keys are minted here and the engine refuses
+        # one dated more than an hour from its own clock, so without this a
+        # device with a wrong clock would fail every call forever.
+        self._clock_offset_ms = 0.0
+
+    def now_ms(self) -> float:
+        """The engine's clock, as well as this client knows it."""
+        return time.time() * 1000 + self._clock_offset_ms
+
+    def observe_server_time(self, at: datetime) -> None:
+        """Off by up to one round trip, which a window in hours does not
+        notice."""
+        self._clock_offset_ms = to_ms(at) - time.time() * 1000
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        options: RequestOptions,
+        query: Query | None = None,
+        body: Body | None = None,
+        idempotent: bool = False,
+    ) -> Any:
+        """
+        `idempotent` replays a call even though its method is not safe. Only a
+        route that carries an idempotency key may set it, and the key has to be
+        in `body` already: the loop re-sends one body, so a key generated per
+        attempt would count the same usage twice.
+        """
+        # Safe methods, plus the routes that carry an idempotency key and say
+        # so. Any other POST or PATCH could create a second row on a replay.
+        retryable = method in ("GET", "DELETE") or idempotent
+
+        url = build_url(self._base_url, path, query)
+        content = None if body is None else encode_body(body)
+        headers = request_headers(self._api_key, has_body=content is not None)
+
+        last_error: MeterbaseError | None = None
+        for attempt in range(options.max_retries + 1):
+            if attempt > 0:
+                await sleep(backoff(attempt, last_error))
+
+            try:
+                response = await self._send(method, url, headers, content, options)
+            except APIConnectionError as unanswered:
+                # A connection failure proves nothing about whether the server
+                # acted, so it is replayed under the same idempotency rule.
+                if not retryable or attempt >= options.max_retries:
+                    raise
+                last_error = unanswered
+                continue
+
+            if response.is_success:
+                return parse_body(response)
+
+            refused = error_from(response)
+            if (
+                retryable
+                and attempt < options.max_retries
+                and should_retry(response.status_code)
+            ):
+                last_error = refused
+                continue
+            raise refused
+
+        # The loop always returns or raises.
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        content: bytes | None,
+        options: RequestOptions,
+    ) -> httpx.Response:
+        # Neither this nor the loop catches a BaseException — a cancelled task,
+        # a Ctrl-C — so one ends the call where it stands and nothing is sent
+        # after it: a replay would do the work the caller called off, and for
+        # `track` record usage they cancelled.
+        try:
+            return await self._http.request(
+                method,
+                url,
+                headers=headers,
+                content=content,
+                timeout=options.timeout,
+            )
+        except httpx.TimeoutException as error:
+            raise APITimeoutError(
+                f"Request timed out after {options.timeout:g}s."
+            ) from error
+        except httpx.TransportError as error:
+            raise APIConnectionError(f"Could not reach {self._origin}.") from error
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+
+_T = TypeVar("_T")
+
+
+class AsyncRequester:
+    """A transport, and the options its calls run with. `with_options` makes
+    another over the same transport, which shares its connections and its
+    clock."""
+
+    def __init__(self, transport: AsyncTransport, options: RequestOptions) -> None:
+        self.transport = transport
+        self.options = options
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        cast_to: Callable[[dict[str, Any]], _T],
+        *,
+        query: Query | None = None,
+        body: Body | None = None,
+        idempotent: bool = False,
+    ) -> _T:
+        data = await self.transport.request(
+            method,
+            path,
+            options=self.options,
+            query=query,
+            body=body,
+            idempotent=idempotent,
+        )
+        return construct(cast_to, data)

meterbase/_async/client.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+import httpx
+
+from .._http import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    RequestOptions,
+    normalize_base_url,
+)
+from .._keys import IDEMPOTENCY_WINDOW_MS, RESERVE_WINDOW_MS, mint, minted_at_ms
+from .._not_given import NOT_GIVEN, NotGiven
+from .._time import parse_instant, to_ms
+from ..errors import MeterbaseError, NotFoundError, TooLateError
+from ..types import CheckResult, ReleaseResult, ReserveResponse, TrackResult, WhoAmI
+from ._transport import AsyncRequester, AsyncTransport
+from .resources.customers import AsyncCustomers
+from .resources.meters import AsyncMeters
+from .resources.plans import AsyncPlans
+
+_T = TypeVar("_T")
+
+logger = logging.getLogger("meterbase")
+
+
+class AsyncMeterbase:
+    """
+    The client every call hangs off. An API key names its own workspace, so
+    there is no workspace to pass.
+
+    `timeout` is in seconds and applies to each attempt rather than to the
+    whole call. `max_retries` counts the attempts after the first. Pass an
+    `http_client` to configure proxies, limits or transports yourself; it
+    stays yours to close.
+    """
+
+    customers: AsyncCustomers
+    meters: AsyncMeters
+    plans: AsyncPlans
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key:
+            raise MeterbaseError(
+                "An API key is required: AsyncMeterbase(api_key='mb_sk_live_…')."
+            )
+
+        options = RequestOptions(timeout=timeout, max_retries=max_retries)
+        transport = AsyncTransport(
+            api_key=api_key,
+            base_url=normalize_base_url(base_url),
+            http_client=http_client,
+        )
+        self._bind(AsyncRequester(transport, options))
+
+    def _bind(self, api: AsyncRequester) -> None:
+        self._api = api
+        self.customers = AsyncCustomers(api)
+        self.meters = AsyncMeters(api)
+        self.plans = AsyncPlans(api)
+
+    def with_options(
+        self,
+        *,
+        timeout: float | NotGiven = NOT_GIVEN,
+        max_retries: int | NotGiven = NOT_GIVEN,
+    ) -> AsyncMeterbase:
+        """
+        This client with other settings, for the calls made through it:
+        `meterbase.with_options(timeout=2).check(...)`. It shares this client's
+        connections, so closing either closes both.
+        """
+        current = self._api.options
+        options = RequestOptions(
+            timeout=current.timeout if isinstance(timeout, NotGiven) else timeout,
+            max_retries=(
+                current.max_retries
+                if isinstance(max_retries, NotGiven)
+                else max_retries
+            ),
+        )
+        derived = type(self).__new__(type(self))
+        derived._bind(AsyncRequester(self._api.transport, options))
+        return derived
+
+    async def check(
+        self,
+        *,
+        customer_id: str,
+        meter_id: str,
+        quantity: int | NotGiven = NOT_GIVEN,
+    ) -> CheckResult:
+        """
+        Asks whether a customer may consume `quantity` of a meter, named by the
+        tenant's own external id and the meter's key: an SDK never holds
+        Meterbase ids. Absence of entitlement is not permission: a customer
+        with no plan and no grant is denied.
+
+        This is the gate, and the only call that ever refuses. Run it before
+        the work; record the work with `track` afterwards.
+
+        Two gates answer it, and `allowed` needs both: the customer's capacity
+        has to cover the quantity, and every rate-limit window in force has to
+        admit it. `reason` names the one that said no. `rate_limits` reports
+        each window whether or not it refused, so a caller can ease off as its
+        headroom closes instead of discovering the ceiling by hitting it.
+        Under a soft cap (`allow_overage`) the capacity admits any quantity, so
+        only a window can refuse.
+
+        `quantity` is what is about to be consumed, `1 … 100000000000`.
+        Omitted, it is 1, which asks whether there is any capacity at all.
+        """
+        return await self._api.request(
+            "POST",
+            "/v1/check",
+            CheckResult,
+            body={
+                "customer_id": customer_id,
+                "meter_id": meter_id,
+                "quantity": quantity,
+            },
+        )
+
+    async def track(
+        self,
+        *,
+        customer_id: str,
+        meter_id: str,
+        quantity: int | NotGiven = NOT_GIVEN,
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> TrackResult:
+        """
+        Records usage that already happened — the tokens were spent, the image
+        was generated — so it never refuses on capacity. A quantity beyond the
+        customer's capacity is recorded, drives `available` to 0, and the next
+        `check` says no, unless the plan's cap is soft. The answer is a
+        receipt, not a verdict.
+
+        `quantity` is an integer, `1 … 100000000000`, and 1 when omitted,
+        which is what a counting meter sends.
+
+        `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
+        call — the SDK's own retries included — replays the original rather
+        than counting the same work twice. The engine keeps that claim for an
+        hour, which is how long a retry stays recognisable. Supply your own
+        when the caller already has an id for the work — a job id, a request
+        id — so a retry from further out replays rather than counts twice.
+        """
+        return await self._keyed(
+            "/v1/usage/track",
+            "idempotency_key",
+            idempotency_key,
+            IDEMPOTENCY_WINDOW_MS,
+            {"customer_id": customer_id, "meter_id": meter_id, "quantity": quantity},
+            TrackResult,
+        )
+
+    async def reserve(
+        self,
+        *,
+        customer_id: str,
+        meter_id: str,
+        quantity: int | NotGiven = NOT_GIVEN,
+        reservation_id: str | NotGiven = NOT_GIVEN,
+        expires_in_seconds: int | NotGiven = NOT_GIVEN,
+    ) -> AsyncHold:
+        """
+        Holds capacity for work that cannot be done twice, or refuses. The same
+        decision `check` makes, and then a hold on the capacity until the work
+        is committed, released, or expires.
+
+        The rule for choosing: can you afford to do the work twice? `check`.
+        No? `reserve`. A reserve costs a transaction where a check costs a
+        cached read, refusals included, so it is not a per-request gate on
+        cheap work.
+
+        Two concurrent reserves for the same customer and meter cannot both be
+        granted the same capacity; that is the whole point, and it is what
+        `check` → work → `track` could never promise.
+
+        `quantity` is what the hold sets aside, `1 … 100000000000`; 1 when
+        omitted. `reservation_id` is the hold's id, and the event's id once a
+        track commits it: a UUIDv7, which the SDK mints when it is omitted. An
+        id is for one reserve and its retries. Once its hold is committed or
+        released the row is gone, so sending the same id again reserves afresh
+        rather than finding anything.
+
+        `expires_in_seconds` is how long the hold counts against the pair
+        before it comes back on its own: `1 … 900`, defaulting to `60`. It is
+        a timeout on your own work, and the field callers get wrong. Too short
+        and the hold evaporates mid-operation, which is worse than no hold at
+        all because you believe you are protected; too long and a crash wedges
+        the customer's capacity until it expires.
+        """
+        return await self._keyed(
+            "/v1/usage/reserve",
+            "reservation_id",
+            reservation_id,
+            RESERVE_WINDOW_MS,
+            {
+                "customer_id": customer_id,
+                "meter_id": meter_id,
+                "quantity": quantity,
+                "expires_in_seconds": expires_in_seconds,
+            },
+            # A retry under the same id finds the hold it already made rather
+            # than making a second one.
+            lambda raw: AsyncHold(
+                raw,
+                client=self,
+                clock=self._api.transport,
+                customer_id=customer_id,
+                meter_id=meter_id,
+                quantity=quantity,
+            ),
+        )
+
+    async def release(self, *, reservation_id: str) -> ReleaseResult:
+        """
+        Gives a hold back: the work did not happen, so nothing is recorded.
+
+        Raises `NotFoundError` when the id names nothing — committed, released
+        already, or never made, which are one absence with one meaning. Prefer
+        `hold.release()`, which treats that as the success it is.
+        """
+        return await self._api.request(
+            "POST",
+            "/v1/usage/release",
+            ReleaseResult,
+            body={"reservation_id": reservation_id},
+        )
+
+    async def whoami(self) -> WhoAmI:
+        """Reports which workspace this key acts for."""
+        return await self._api.request("GET", "/v1/whoami", WhoAmI)
+
+    async def aclose(self) -> None:
+        """Closes the connections this client opened. An `http_client` passed
+        in stays open: it is yours."""
+        await self._api.transport.aclose()
+
+    async def __aenter__(self) -> AsyncMeterbase:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def _keyed(
+        self,
+        path: str,
+        field: str,
+        supplied: str | NotGiven,
+        window_ms: int,
+        body: dict[str, Any],
+        cast_to: Callable[[dict[str, Any]], _T],
+    ) -> _T:
+        """
+        Sends a call that carries a caller-minted UUIDv7, minting one when the
+        caller supplied none and re-minting once if this machine's clock put it
+        outside the engine's window.
+
+        A key the caller supplied is never re-minted: this cannot know whether
+        it names work already recorded, and replacing it could count that work
+        twice.
+        """
+        if not isinstance(supplied, NotGiven):
+            return await self._api.request(
+                "POST", path, cast_to, body={**body, field: supplied}, idempotent=True
+            )
+
+        clock = self._api.transport
+        key = mint(clock.now_ms())
+        started = time.monotonic()
+
+        try:
+            # Fixed before the retry loop is entered: every attempt of this
+            # call carries the same key, which is what makes replaying it safe.
+            return await self._api.request(
+                "POST", path, cast_to, body={**body, field: key}, idempotent=True
+            )
+        except TooLateError as error:
+            # The only failure this can fix by itself: a clock that disagrees
+            # with the engine's.
+            if error.server_time is None:
+                raise
+
+            # Re-minting is safe only if no attempt under the old key can have
+            # landed. The transport retries, so this 422 may have come from a
+            # later attempt while an earlier one succeeded. If the key was
+            # already outside the window when the call began, every attempt
+            # was refused.
+            elapsed_ms = (time.monotonic() - started) * 1000
+            server_at_start = to_ms(error.server_time) - elapsed_ms
+            if abs(server_at_start - minted_at_ms(key)) <= window_ms:
+                raise
+
+            clock.observe_server_time(error.server_time)
+
+        return await self._api.request(
+            "POST",
+            path,
+            cast_to,
+            body={**body, field: mint(clock.now_ms())},
+            idempotent=True,
+        )
+
+
+class AsyncHold(ReserveResponse):
+    """
+    What a reserve answers: everything `check` answers, and a hold on the
+    capacity when `allowed`, with the two calls that close it. `commit` is
+    `track` under the hold's own id; `release` gives the capacity back.
+
+    A refusal holds nothing, so it carries no `reservation_id` and no
+    `expires_at`: `commit` raises and `release` answers `None`.
+    """
+
+    _client: AsyncMeterbase
+    _clock: AsyncTransport
+    _customer_id: str
+    _meter_id: str
+
+    def __init__(
+        self,
+        raw: Mapping[str, Any],
+        *,
+        client: AsyncMeterbase,
+        clock: AsyncTransport,
+        customer_id: str,
+        meter_id: str,
+        quantity: int | NotGiven = NOT_GIVEN,
+    ) -> None:
+        super().__init__(raw)
+        self.__dict__.update(
+            _client=client,
+            _clock=clock,
+            _customer_id=customer_id,
+            _meter_id=meter_id,
+        )
+
+        if not self.allowed:
+            return
+
+        # A grant without them is not a hold this can hand back: `commit`
+        # would have no id to commit under, and the caller would find that out
+        # at the one moment they are relying on it. Louder here.
+        if self.reservation_id is None or self.expires_at is None:
+            raise MeterbaseError(
+                "The engine granted a reservation without an id or an expiry, so "
+                "there is no hold to commit or release. The capacity it set "
+                "aside comes back on its own."
+            )
+        if self.quantity is None:
+            self.__dict__["quantity"] = (
+                1 if isinstance(quantity, NotGiven) else quantity
+            )
+
+    async def commit(self, quantity: int | NotGiven = NOT_GIVEN) -> TrackResult:
+        """
+        Records what the work actually cost and releases the rest. Omit the
+        quantity to record what was held. Going over is allowed: the hold only
+        ever guaranteed what it reserved.
+
+        Warns, on the `meterbase` logger, when it runs after `expires_at`: the
+        hold stopped holding anything at that instant, so the work was no
+        longer protected. The event is still recorded. That warning is the only
+        feedback there is on an `expires_in_seconds` guessed too short.
+
+        Raises `MeterbaseError` on a refusal, which held nothing to commit.
+        """
+        reservation_id = self.reservation_id
+        if not self.allowed or reservation_id is None:
+            raise MeterbaseError(
+                "This reserve was refused, so it holds nothing to commit. Record "
+                "work that ran anyway with track."
+            )
+
+        expires_at = parse_instant(self.expires_at)
+        if expires_at is not None and self._clock.now_ms() > to_ms(expires_at):
+            logger.warning(
+                "Meterbase: committing reservation %s after it expired at %s. The "
+                "event is still recorded, but the capacity was no longer held — "
+                "raise expires_in_seconds for this work.",
+                reservation_id,
+                self.expires_at,
+            )
+
+        return await self._client.track(
+            customer_id=self._customer_id,
+            meter_id=self._meter_id,
+            quantity=quantity,
+            # The hold's own id, so the track commits it rather than recording
+            # a second event beside it.
+            idempotency_key=reservation_id,
+        )
+
+    async def release(self) -> ReleaseResult | None:
+        """
+        Gives the hold back. Nothing is recorded.
+
+        Answers `None` rather than raising when there is nothing left to
+        release — already committed, already released, or refused and so never
+        held. This is the one call meant to run on the failure path, where
+        raising would mask the error the caller is already handling, and
+        "nothing left to release" is the outcome a release wanted anyway.
+        `meterbase.release` raises the 404, as every other call does.
+        """
+        reservation_id = self.reservation_id
+        if not self.allowed or reservation_id is None:
+            return None
+
+        try:
+            return await self._client.release(reservation_id=reservation_id)
+        except NotFoundError:
+            return None