vercel-cache 0.7.0__py3-none-any.whl

vercel/cache/__init__.py

@@ -0,0 +1,12 @@
+from .cache_build import RuntimeCacheError
+from .purge import dangerously_delete_by_tag, invalidate_by_tag
+from .runtime_cache import AsyncRuntimeCache, RuntimeCache, get_cache
+
+__all__ = [
+    "RuntimeCache",
+    "RuntimeCacheError",
+    "AsyncRuntimeCache",
+    "get_cache",
+    "invalidate_by_tag",
+    "dangerously_delete_by_tag",
+]

vercel/cache/aio.py

@@ -0,0 +1,19 @@
+from collections.abc import Callable
+
+from .runtime_cache import AsyncRuntimeCache
+
+
+def get_cache(
+    *,
+    key_hash_function: Callable[[str], str] | None = None,
+    namespace: str | None = None,
+    namespace_separator: str | None = None,
+) -> AsyncRuntimeCache:
+    return AsyncRuntimeCache(
+        key_hash_function=key_hash_function,
+        namespace=namespace,
+        namespace_separator=namespace_separator,
+    )
+
+
+__all__ = ["get_cache", "AsyncRuntimeCache"]

vercel/cache/cache_build.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping, Sequence
+
+import httpx
+
+from vercel.internal.telemetry import track
+
+from .types import AsyncCache, Cache
+
+HEADERS_VERCEL_CACHE_STATE = "x-vercel-cache-state"
+HEADERS_VERCEL_REVALIDATE = "x-vercel-revalidate"
+HEADERS_VERCEL_CACHE_TAGS = "x-vercel-cache-tags"
+HEADERS_VERCEL_CACHE_ITEM_NAME = "x-vercel-cache-item-name"
+
+# Use no keep-alive for async clients to avoid lingering background tasks
+ASYNC_CLIENT_LIMITS = httpx.Limits(max_keepalive_connections=0)
+DEFAULT_TIMEOUT = 30.0
+
+
+class RuntimeCacheError(RuntimeError):
+    """Raised when strict Runtime Cache operations fail."""
+
+
+class BuildCache(Cache):
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        headers: Mapping[str, str],
+        on_error: Callable[[Exception], None] | None = None,
+        strict: bool = False,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/") + "/"
+        self._headers = dict(headers)
+        self._on_error = on_error
+        self._strict = strict
+        self._client = httpx.Client(timeout=httpx.Timeout(30.0))
+
+    def get(self, key: str):
+        try:
+            r = self._client.get(self._endpoint + key, headers=self._headers)
+            if r.status_code == 404:
+                # Track cache miss
+                track("cache_get", hit=False)
+                return None
+            if r.status_code == 200:
+                cache_state = r.headers.get(HEADERS_VERCEL_CACHE_STATE)
+                if cache_state and cache_state.lower() != "fresh":
+                    r.close()
+                    # Track cache miss (stale)
+                    track("cache_get", hit=False)
+                    return None
+                # Track cache hit
+                track("cache_get", hit=True)
+                return r.json()
+            raise RuntimeCacheError(f"Failed to get cache: {r.status_code} {r.reason_phrase}")
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            if self._strict:
+                raise
+            return None
+
+    def set(
+        self,
+        key: str,
+        value: object,
+        options: dict | None = None,
+    ) -> None:
+        try:
+            optional_headers: dict[str, str] = {}
+            if options and (ttl := options.get("ttl")):
+                optional_headers[HEADERS_VERCEL_REVALIDATE] = str(ttl)
+            if options and (tags := options.get("tags")):
+                if tags:
+                    optional_headers[HEADERS_VERCEL_CACHE_TAGS] = ",".join(tags)
+            if options and (name := options.get("name")):
+                optional_headers[HEADERS_VERCEL_CACHE_ITEM_NAME] = name
+
+            r = self._client.post(
+                self._endpoint + key,
+                headers={**self._headers, **optional_headers},
+                content=json.dumps(value),
+            )
+            if r.status_code != 200:
+                raise RuntimeCacheError(f"Failed to set cache: {r.status_code} {r.reason_phrase}")
+            # Track telemetry
+            track(
+                "cache_set",
+                ttl_seconds=options.get("ttl") if options else None,
+                has_tags=bool(options and options.get("tags")),
+            )
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            if self._strict:
+                raise
+
+    def delete(self, key: str) -> None:
+        try:
+            r = self._client.delete(self._endpoint + key, headers=self._headers)
+            if r.status_code != 200:
+                raise RuntimeCacheError(
+                    f"Failed to delete cache: {r.status_code} {r.reason_phrase}"
+                )
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            if self._strict:
+                raise
+
+    def expire_tag(self, tag: str | Sequence[str]) -> None:
+        try:
+            tags = ",".join(tag) if isinstance(tag, (list, tuple, set)) else tag
+            r = self._client.post(
+                f"{self._endpoint}revalidate",
+                params={"tags": tags},
+                headers=self._headers,
+            )
+            if r.status_code != 200:
+                raise RuntimeCacheError(
+                    f"Failed to revalidate tag: {r.status_code} {r.reason_phrase}"
+                )
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            if self._strict:
+                raise
+
+    def __contains__(self, key: str) -> bool:
+        try:
+            r = self._client.get(self._endpoint + key, headers=self._headers)
+            try:
+                if r.status_code == 404:
+                    return False
+                if r.status_code == 200:
+                    cache_state = r.headers.get(HEADERS_VERCEL_CACHE_STATE)
+                    # Consider present only when fresh
+                    if cache_state and cache_state.lower() != "fresh":
+                        return False
+                    return True
+                return False
+            finally:
+                # Ensure the response is closed regardless of outcome
+                r.close()
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            return False
+
+    def __getitem__(self, key: str):
+        if key in self:
+            return self.get(key)
+        raise KeyError(key)
+
+
+class AsyncBuildCache(AsyncCache):
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        headers: Mapping[str, str],
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/") + "/"
+        self._headers = dict(headers)
+        self._on_error = on_error
+
+    async def get(self, key: str):
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(DEFAULT_TIMEOUT), limits=ASYNC_CLIENT_LIMITS
+            ) as client:
+                r = await client.get(self._endpoint + key, headers=self._headers)
+                if r.status_code == 404:
+                    await r.aclose()
+                    # Track cache miss
+                    try:
+                        track("cache_get", hit=False)
+                    except Exception:
+                        pass
+                    return None
+                if r.status_code == 200:
+                    cache_state = r.headers.get(HEADERS_VERCEL_CACHE_STATE)
+                    if cache_state and cache_state.lower() != "fresh":
+                        await r.aclose()
+                        # Track cache miss (stale)
+                        try:
+                            track("cache_get", hit=False)
+                        except Exception:
+                            pass
+                        return None
+                    data = r.json()
+                    await r.aclose()
+                    # Track cache hit
+                    try:
+                        track("cache_get", hit=True)
+                    except Exception:
+                        pass
+                    return data
+                await r.aclose()
+                raise RuntimeError(f"Failed to get cache: {r.status_code} {r.reason_phrase}")
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            return None
+
+    async def set(
+        self,
+        key: str,
+        value: object,
+        options: dict | None = None,
+    ) -> None:
+        try:
+            optional_headers: dict[str, str] = {}
+            if options and (ttl := options.get("ttl")):
+                optional_headers[HEADERS_VERCEL_REVALIDATE] = str(ttl)
+            if options and (tags := options.get("tags")):
+                if tags:
+                    optional_headers[HEADERS_VERCEL_CACHE_TAGS] = ",".join(tags)
+            if options and (name := options.get("name")):
+                optional_headers[HEADERS_VERCEL_CACHE_ITEM_NAME] = name
+
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(DEFAULT_TIMEOUT), limits=ASYNC_CLIENT_LIMITS
+            ) as client:
+                r = await client.post(
+                    self._endpoint + key,
+                    headers={**self._headers, **optional_headers},
+                    content=json.dumps(value),
+                )
+                if r.status_code != 200:
+                    await r.aclose()
+                    raise RuntimeError(f"Failed to set cache: {r.status_code} {r.reason_phrase}")
+                await r.aclose()
+            # Track telemetry
+            track(
+                "cache_set",
+                ttl_seconds=options.get("ttl") if options else None,
+                has_tags=bool(options and options.get("tags")),
+            )
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+
+    async def delete(self, key: str) -> None:
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(DEFAULT_TIMEOUT), limits=ASYNC_CLIENT_LIMITS
+            ) as client:
+                r = await client.delete(self._endpoint + key, headers=self._headers)
+                if r.status_code != 200:
+                    await r.aclose()
+                    raise RuntimeError(f"Failed to delete cache: {r.status_code} {r.reason_phrase}")
+                await r.aclose()
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+
+    async def expire_tag(self, tag: str | Sequence[str]) -> None:
+        try:
+            tags = ",".join(tag) if isinstance(tag, (list, tuple, set)) else tag
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(DEFAULT_TIMEOUT), limits=ASYNC_CLIENT_LIMITS
+            ) as client:
+                r = await client.post(
+                    f"{self._endpoint}revalidate",
+                    params={"tags": tags},
+                    headers=self._headers,
+                )
+                if r.status_code != 200:
+                    await r.aclose()
+                    raise RuntimeError(
+                        f"Failed to revalidate tag: {r.status_code} {r.reason_phrase}"
+                    )
+                await r.aclose()
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+
+    async def contains(self, key: str) -> bool:
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(DEFAULT_TIMEOUT), limits=ASYNC_CLIENT_LIMITS
+            ) as client:
+                r = await client.get(self._endpoint + key, headers=self._headers)
+                if r.status_code == 404:
+                    await r.aclose()
+                    return False
+                if r.status_code == 200:
+                    cache_state = r.headers.get(HEADERS_VERCEL_CACHE_STATE)
+                    if cache_state and cache_state.lower() != "fresh":
+                        await r.aclose()
+                        return False
+                    await r.aclose()
+                    return True
+                await r.aclose()
+                return False
+        except Exception as e:
+            if self._on_error:
+                self._on_error(e)
+            return False

vercel/cache/cache_in_memory.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from vercel.internal.telemetry import track
+
+from .types import AsyncCache, Cache
+
+
+class InMemoryCache(Cache):
+    def __init__(self) -> None:
+        self._cache: dict[str, dict] = {}
+
+    def get(self, key: str):
+        entry = self._cache.get(key)
+        if not entry:
+            # Track cache miss
+            track("cache_get", hit=False)
+            return None
+        ttl = entry.get("ttl")
+        if (
+            ttl is not None
+            and entry["last_modified"] + ttl * 1000 < __import__("time").time() * 1000
+        ):
+            self.delete(key)
+            # Track cache miss (expired)
+            track("cache_get", hit=False)
+            return None
+        # Track cache hit
+        track("cache_get", hit=True)
+        return entry["value"]
+
+    def set(self, key: str, value: object, options: dict | None = None) -> None:
+        from time import time
+
+        opts = options or {}
+        ttl = opts.get("ttl")
+        tags = set(opts.get("tags", []))
+        self._cache[key] = {
+            "value": value,
+            "tags": tags,
+            "last_modified": int(time() * 1000),
+            "ttl": ttl,
+        }
+        # Track telemetry
+        track("cache_set", ttl_seconds=ttl, has_tags=len(tags) > 0)
+
+    def delete(self, key: str) -> None:
+        self._cache.pop(key, None)
+
+    def expire_tag(self, tag: str | Sequence[str]) -> None:
+        tags = {tag} if isinstance(tag, str) else set(tag)
+        to_delete = []
+        for k, entry in self._cache.items():
+            entry_tags = entry.get("tags", set())
+            if any(t in entry_tags for t in tags):
+                to_delete.append(k)
+        for k in to_delete:
+            self._cache.pop(k, None)
+
+    def __contains__(self, key: str) -> bool:
+        entry = self._cache.get(key)
+        if not entry:
+            return False
+        ttl = entry.get("ttl")
+        if (
+            ttl is not None
+            and entry["last_modified"] + ttl * 1000 < __import__("time").time() * 1000
+        ):
+            # Expired entries should not be considered present
+            self.delete(key)
+            return False
+        return True
+
+    def __getitem__(self, key: str):
+        if key in self:
+            return self.get(key)
+        raise KeyError(key)
+
+
+class AsyncInMemoryCache(AsyncCache):
+    def __init__(self, delegate: InMemoryCache | None = None) -> None:
+        # Reuse the synchronous implementation under the hood and expose async API
+        self.cache = delegate or InMemoryCache()
+
+    async def get(self, key: str):
+        return self.cache.get(key)
+
+    async def set(self, key: str, value: object, options: dict | None = None) -> None:
+        self.cache.set(key, value, options)
+
+    async def delete(self, key: str) -> None:
+        self.cache.delete(key)
+
+    async def expire_tag(self, tag: str | Sequence[str]) -> None:
+        self.cache.expire_tag(tag)
+
+    async def contains(self, key: str) -> bool:
+        return key in self.cache

vercel/cache/context.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from vercel.headers import get_headers as _get_headers, set_headers as _set_headers
+
+from .types import PurgeAPI
+
+_cv_wait_until: ContextVar[Callable[[Awaitable[object]], None] | None] = ContextVar(
+    "vercel_wait_until", default=None
+)
+_cv_cache: ContextVar[object | None] = ContextVar("vercel_cache", default=None)
+_cv_async_cache: ContextVar[object | None] = ContextVar("vercel_async_cache", default=None)
+_cv_purge: ContextVar[PurgeAPI | None] = ContextVar("vercel_purge", default=None)
+
+
+class _Unset: ...
+
+
+UNSET = _Unset()
+
+
+@dataclass
+class _ContextSnapshot:
+    wait_until: Callable[[Awaitable[object]], None] | None
+    cache: object | None
+    async_cache: object | None
+    purge: PurgeAPI | None
+    headers: Mapping[str, str] | None
+
+
+def get_context() -> _ContextSnapshot:
+    return _ContextSnapshot(
+        wait_until=_cv_wait_until.get(),
+        cache=_cv_cache.get(),
+        async_cache=_cv_async_cache.get(),
+        purge=_cv_purge.get(),
+        headers=_get_headers(),
+    )
+
+
+def set_context(
+    *,
+    wait_until: Callable[[Awaitable[object]], None] | None | _Unset = UNSET,
+    cache: object | None | _Unset = UNSET,
+    async_cache: object | None | _Unset = UNSET,
+    purge: PurgeAPI | None | _Unset = UNSET,
+    headers: Mapping[str, str] | None | _Unset = UNSET,
+) -> None:
+    if not isinstance(wait_until, _Unset):
+        _cv_wait_until.set(wait_until)
+    if not isinstance(cache, _Unset):
+        _cv_cache.set(cache)
+    if not isinstance(async_cache, _Unset):
+        _cv_async_cache.set(async_cache)
+    if not isinstance(purge, _Unset):
+        _cv_purge.set(purge)
+    if not isinstance(headers, _Unset):
+        _set_headers(headers)
+
+
+def set_headers(headers: Mapping[str, str] | None) -> None:
+    _set_headers(headers)
+
+
+def get_headers() -> Mapping[str, str] | None:
+    return _get_headers()

vercel/cache/purge.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .context import get_context
+
+
+def invalidate_by_tag(tag: str | list[str]) -> Any:
+    api = get_context().purge
+    if api is None:
+        return None
+    return api.invalidate_by_tag(tag)
+
+
+def dangerously_delete_by_tag(
+    tag: str | list[str],
+    *,
+    revalidation_deadline_seconds: int | None = None,
+) -> Any:
+    api = get_context().purge
+    if api is None:
+        return None
+    return api.dangerously_delete_by_tag(
+        tag,
+        revalidation_deadline_seconds=revalidation_deadline_seconds,
+    )

vercel/cache/runtime_cache.py

@@ -0,0 +1,204 @@
+import json
+import os
+from collections.abc import Callable, Sequence
+from typing import Literal, cast, overload
+
+from .cache_build import AsyncBuildCache, BuildCache
+from .cache_in_memory import AsyncInMemoryCache, InMemoryCache
+from .context import get_context
+from .types import AsyncCache, Cache
+from .utils import create_key_transformer
+
+_in_memory_cache_instance: InMemoryCache | None = None
+_async_in_memory_cache_instance: AsyncInMemoryCache | None = None
+_build_cache_instance: BuildCache | None = None
+_async_build_cache_instance: AsyncBuildCache | None = None
+_warned_cache_unavailable = False
+
+
+class RuntimeCache(Cache):
+    def __init__(
+        self,
+        *,
+        key_hash_function: Callable[[str], str] | None = None,
+        namespace: str | None = None,
+        namespace_separator: str | None = None,
+        strict: bool = False,
+    ) -> None:
+        # Transform keys to match get_cache behavior
+        self._make_key = create_key_transformer(key_hash_function, namespace, namespace_separator)
+        self._strict = strict
+
+    def get(self, key: str):
+        return resolve_cache(sync=True, strict=self._strict).get(self._make_key(key))
+
+    def set(self, key: str, value: object, options: dict | None = None):
+        cache = resolve_cache(sync=True, strict=self._strict)
+        return cache.set(self._make_key(key), value, options)
+
+    def delete(self, key: str):
+        return resolve_cache(sync=True, strict=self._strict).delete(self._make_key(key))
+
+    def expire_tag(self, tag: str | Sequence[str]):
+        # Tag invalidation is not namespaced/hashed by design
+        return resolve_cache(sync=True, strict=self._strict).expire_tag(tag)
+
+    def __contains__(self, key: str) -> bool:
+        # Delegate membership to the underlying cache implementation with transformed key
+        return self._make_key(key) in resolve_cache(sync=True, strict=self._strict)
+
+    def __getitem__(self, key: str):
+        if key in self:
+            return self.get(key)
+        raise KeyError(key)
+
+
+class AsyncRuntimeCache(AsyncCache):
+    def __init__(
+        self,
+        *,
+        key_hash_function: Callable[[str], str] | None = None,
+        namespace: str | None = None,
+        namespace_separator: str | None = None,
+    ) -> None:
+        self._make_key = create_key_transformer(key_hash_function, namespace, namespace_separator)
+
+    async def get(self, key: str):
+        return await resolve_cache(sync=False).get(self._make_key(key))
+
+    async def set(self, key: str, value: object, options: dict | None = None):
+        return await resolve_cache(sync=False).set(self._make_key(key), value, options)
+
+    async def delete(self, key: str):
+        return await resolve_cache(sync=False).delete(self._make_key(key))
+
+    async def expire_tag(self, tag: str | Sequence[str]):
+        return await resolve_cache(sync=False).expire_tag(tag)
+
+    async def contains(self, key: str) -> bool:
+        return await resolve_cache(sync=False).contains(self._make_key(key))
+
+
+@overload
+def get_cache(
+    *,
+    key_hash_function: Callable[[str], str] | None = ...,
+    namespace: str | None = ...,
+    namespace_separator: str | None = ...,
+    sync: Literal[True] = ...,
+) -> RuntimeCache: ...
+
+
+@overload
+def get_cache(
+    *,
+    key_hash_function: Callable[[str], str] | None = ...,
+    namespace: str | None = ...,
+    namespace_separator: str | None = ...,
+    sync: Literal[False],
+) -> AsyncRuntimeCache: ...
+
+
+def get_cache(
+    *,
+    key_hash_function: Callable[[str], str] | None = None,
+    namespace: str | None = None,
+    namespace_separator: str | None = None,
+    sync: bool = True,
+) -> RuntimeCache | AsyncRuntimeCache:
+    if sync:
+        return RuntimeCache(
+            key_hash_function=key_hash_function,
+            namespace=namespace,
+            namespace_separator=namespace_separator,
+        )
+    return AsyncRuntimeCache(
+        key_hash_function=key_hash_function,
+        namespace=namespace,
+        namespace_separator=namespace_separator,
+    )
+
+
+def _get_cache_implementation(
+    debug: bool = False,
+    sync: bool = True,
+    strict: bool = False,
+) -> Cache | AsyncCache:
+    global _in_memory_cache_instance, _async_in_memory_cache_instance
+    global _build_cache_instance, _async_build_cache_instance, _warned_cache_unavailable
+
+    # Prepare a single shared InMemoryCache backing store and an async wrapper over it
+    if _in_memory_cache_instance is None:
+        _in_memory_cache_instance = InMemoryCache()
+    if _async_in_memory_cache_instance is None:
+        _async_in_memory_cache_instance = AsyncInMemoryCache(delegate=_in_memory_cache_instance)
+
+    # Disable build cache via env
+    if os.getenv("RUNTIME_CACHE_DISABLE_BUILD_CACHE") == "true":
+        if debug:
+            print("Using InMemoryCache as build cache is disabled")
+        return _in_memory_cache_instance if sync else _async_in_memory_cache_instance
+
+    endpoint = os.getenv("RUNTIME_CACHE_ENDPOINT")
+    headers = os.getenv("RUNTIME_CACHE_HEADERS")
+
+    if debug:
+        print(
+            "Runtime cache environment variables:",
+            {"RUNTIME_CACHE_ENDPOINT": endpoint, "RUNTIME_CACHE_HEADERS": headers},
+        )
+
+    if not endpoint or not headers:
+        if not _warned_cache_unavailable:
+            print("Runtime Cache unavailable in this environment. Falling back to in-memory cache.")
+            _warned_cache_unavailable = True
+        return _in_memory_cache_instance if sync else _async_in_memory_cache_instance  # type: ignore[return-value]
+
+    # Build cache clients
+    try:
+        parsed_headers = json.loads(headers)
+        if not isinstance(parsed_headers, dict):
+            raise ValueError("RUNTIME_CACHE_HEADERS must be a JSON object")
+    except Exception as e:
+        print("Failed to parse RUNTIME_CACHE_HEADERS:", e)
+        return _in_memory_cache_instance if sync else _async_in_memory_cache_instance  # type: ignore[return-value]
+
+    if sync:
+        if _build_cache_instance is None:
+            _build_cache_instance = BuildCache(
+                endpoint=endpoint,
+                headers=parsed_headers,
+                on_error=lambda e: print(e),
+            )
+        if not strict:
+            return _build_cache_instance
+        return BuildCache(endpoint=endpoint, headers=parsed_headers, strict=True)
+    else:
+        if _async_build_cache_instance is None:
+            _async_build_cache_instance = AsyncBuildCache(
+                endpoint=endpoint,
+                headers=parsed_headers,
+                on_error=lambda e: print(e),
+            )
+        return _async_build_cache_instance
+
+
+@overload
+def resolve_cache(sync: Literal[True] = ..., strict: bool = ...) -> Cache: ...
+
+
+@overload
+def resolve_cache(sync: Literal[False], strict: bool = ...) -> AsyncCache: ...
+
+
+def resolve_cache(sync: bool = True, strict: bool = False) -> Cache | AsyncCache:
+    ctx = get_context()
+    if sync:
+        cache = getattr(ctx, "cache", None)
+        if cache is not None:
+            return cast(Cache, cache)
+    else:
+        cache = getattr(ctx, "async_cache", None)
+        if cache is not None:
+            return cast(AsyncCache, cache)
+    return _get_cache_implementation(os.getenv("SUSPENSE_CACHE_DEBUG") == "true", sync, strict)

vercel/cache/types.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Protocol
+
+
+class Cache(Protocol):
+    def delete(self, key: str) -> None: ...
+
+    def get(self, key: str) -> object | None: ...
+
+    def __contains__(self, key: str) -> bool: ...
+
+    def set(
+        self,
+        key: str,
+        value: object,
+        options: dict | None = None,
+    ) -> None: ...
+
+    def expire_tag(self, tag: str | Sequence[str]) -> None: ...
+
+
+class AsyncCache(Protocol):
+    async def delete(self, key: str) -> None: ...
+
+    async def get(self, key: str) -> object | None: ...
+
+    async def set(
+        self,
+        key: str,
+        value: object,
+        options: dict | None = None,
+    ) -> None: ...
+
+    async def expire_tag(self, tag: str | Sequence[str]) -> None: ...
+
+    async def contains(self, key: str) -> bool: ...
+
+
+class PurgeAPI(Protocol):
+    """Protocol for the purge API object."""
+
+    def invalidate_by_tag(self, tag: str | list[str]) -> Any:
+        """Invalidate cache entries by tag."""
+        ...
+
+    def dangerously_delete_by_tag(
+        self,
+        tag: str | list[str],
+        *,
+        revalidation_deadline_seconds: int | None = None,
+    ) -> Any:
+        """Dangerously delete cache entries by tag."""
+        ...
+
+
+class AsyncPurgeAPI(Protocol):
+    async def invalidate_by_tag(self, tag: str | list[str]) -> Any: ...
+
+    async def dangerously_delete_by_tag(
+        self,
+        tag: str | list[str],
+        *,
+        revalidation_deadline_seconds: int | None = None,
+    ) -> Any: ...

vercel/cache/utils.py

@@ -0,0 +1,27 @@
+from collections.abc import Callable
+
+_DEFAULT_NAMESPACE_SEPARATOR = "$"
+
+
+def default_key_hash_function(key: str) -> str:
+    # Mirror TS defaultKeyHashFunction: djb2 xor variant, 32-bit unsigned hex
+    h = 5381
+    for ch in key:
+        h = ((h * 33) ^ ord(ch)) & 0xFFFFFFFF
+    return format(h, "x")
+
+
+def create_key_transformer(
+    key_fn: Callable[[str], str] | None,
+    ns: str | None,
+    sep: str | None,
+) -> Callable[[str], str]:
+    key_fn = key_fn or default_key_hash_function
+    sep = sep or _DEFAULT_NAMESPACE_SEPARATOR
+
+    def make(key: str) -> str:
+        if not ns:
+            return key_fn(key)
+        return f"{ns}{sep}{key_fn(key)}"
+
+    return make

vercel/cache/version.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

vercel_cache-0.7.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: vercel-cache
+Version: 0.7.0
+Summary: Runtime cache helpers for Vercel Python applications
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: vercel-headers>=0.7.0
+Requires-Dist: vercel-internal-telemetry>=0.7.0
+Description-Content-Type: text/markdown
+
+# Cache
+
+`vercel.cache` exposes runtime cache helpers for Vercel Python applications.
+
+Use `get_cache()` for synchronous code and `vercel.cache.aio.get_cache()` for
+async code. When runtime cache environment variables are unavailable, cache
+operations fall back to an in-memory cache.

vercel_cache-0.7.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+vercel/cache/__init__.py,sha256=dFyvI06ZlFo0UU7sRgLkhFw5r-j3hRSF3chW3Yitans,337
+vercel/cache/aio.py,sha256=c4WdnoujC_7J4DFMnO5yxZAjEou2DE79Mqn-Bm2VeQQ,474
+vercel/cache/cache_build.py,sha256=GK_ERyv0JUfS26Zjf0C6xBjxPGwoDz8cp3DeF0S8CwU,11282
+vercel/cache/cache_in_memory.py,sha256=SuFF8atNBLa34Sq_hfx-UsgGD1-3XGDZ7JYEUNH8k5A,3053
+vercel/cache/context.py,sha256=jJ2PSqHjIuSk3M28LHemOkavzckS96iXHcmHQlYHt58,2007
+vercel/cache/purge.py,sha256=ynd0ojiOGj2rS9jiKb_9ENW1Wu7zGClhM68QgfFeR-w,585
+vercel/cache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vercel/cache/runtime_cache.py,sha256=3_fD3RtpLDHnwEyYJOc83JbRs7x7QNmRqsscv-8zsMc,7258
+vercel/cache/types.py,sha256=ZKvT4ugXpsWJD6ryH53HxTxGILl1WjpxYSa1_L1oSZI,1562
+vercel/cache/utils.py,sha256=UubbjcwMLtWF9TsH0OfIFM5lutCwHFf3FyoApHzFXuQ,679
+vercel/cache/version.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
+vercel_cache-0.7.0.dist-info/METADATA,sha256=4m2OXQ9rOj6ny2TfM-BjlPs6BZpDYI8VUbKWlUGEm_A,631
+vercel_cache-0.7.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+vercel_cache-0.7.0.dist-info/licenses/LICENSE,sha256=ZhFC5TwxPSu14bBV9cCjkAFFD_G14nuJ3EvH3ppjUso,1069
+vercel_cache-0.7.0.dist-info/RECORD,,

vercel_cache-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vercel_cache-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.