vercel-cache 0.7.0__tar.gz

vercel_cache-0.7.0/.gitignore

@@ -0,0 +1,130 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.benchmarks/
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+.zed/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_cache-0.7.0/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.

vercel_cache-0.7.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,7 @@
+# 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/_vercel_hatch_build.py

@@ -0,0 +1,116 @@
+"""Hatch metadata hook for publish-time workspace dependency bounds."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.requirements import Requirement
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+class WorkspaceDependenciesMetadataHook(MetadataHookInterface):
+    """Generate package dependencies from the repo-owned dependency table."""
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        """Populate dynamic dependencies for Hatchling metadata generation."""
+        pyproject = _load_pyproject(Path(self.root))
+        release = pyproject.get("tool", {}).get("vercel", {}).get("release", {})
+        dependency_table = release.get("dependencies", {})
+        workspace_sources = pyproject.get("tool", {}).get("uv", {}).get("sources", {})
+        workspace_names = {
+            name for name, source in workspace_sources.items() if source.get("workspace") is True
+        }
+        workspace_root = _find_workspace_root(Path(self.root))
+
+        metadata["dependencies"] = [
+            _rewrite_dependency(requirement, workspace_names, workspace_root)
+            for requirement in dependency_table.get("dependencies", [])
+        ]
+
+
+def _load_pyproject(path: Path) -> dict[str, Any]:
+    with (path / "pyproject.toml").open("rb") as fp:
+        return tomllib.load(fp)
+
+
+def _find_workspace_root(start: Path) -> Path | None:
+    for path in [start, *start.parents]:
+        pyproject = path / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+        data = _load_pyproject(path)
+        if "workspace" in data.get("tool", {}).get("uv", {}):
+            return path
+    return None
+
+
+def _rewrite_dependency(
+    requirement: str,
+    workspace_names: set[str],
+    workspace_root: Path | None,
+) -> str:
+    parsed = Requirement(requirement)
+    normalized = parsed.name.lower().replace("_", "-")
+    if normalized not in workspace_names or workspace_root is None:
+        return requirement
+    return _with_lower_bound(parsed, _read_workspace_version(workspace_root, normalized))
+
+
+def _with_lower_bound(requirement: Requirement, version: str) -> str:
+    extras = f"[{','.join(sorted(requirement.extras))}]" if requirement.extras else ""
+    specifiers = [
+        str(specifier) for specifier in requirement.specifier if specifier.operator != ">="
+    ]
+    specifier_text = ",".join([f">={version}", *specifiers])
+    marker = f" ; {requirement.marker}" if requirement.marker else ""
+    return f"{requirement.name}{extras}{specifier_text}{marker}"
+
+
+def _read_workspace_version(workspace_root: Path, package_name: str) -> str:
+    for pattern in ("src/*/pyproject.toml", "integrations/*/pyproject.toml"):
+        for pyproject_path in workspace_root.glob(pattern):
+            version = _version_from_pyproject(pyproject_path, package_name)
+            if version is not None:
+                return version
+    raise RuntimeError(f"unknown workspace dependency {package_name!r}")
+
+
+def _version_from_pyproject(pyproject_path: Path, package_name: str) -> str | None:
+    data = _load_pyproject(pyproject_path.parent)
+    if data.get("project", {}).get("name") != package_name:
+        return None
+    version_path = pyproject_path.parent / data["tool"]["hatch"]["version"]["path"]
+    module = ast.parse(version_path.read_text(encoding="utf-8"), filename=str(version_path))
+    for node in module.body:
+        value = _version_value(node)
+        if value is None:
+            continue
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            return value.value
+    raise RuntimeError(f"could not find __version__ in {version_path}")
+
+
+def _version_value(node: ast.stmt) -> ast.expr | None:
+    if isinstance(node, ast.Assign) and any(
+        isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets
+    ):
+        return node.value
+    if (
+        isinstance(node, ast.AnnAssign)
+        and isinstance(node.target, ast.Name)
+        and node.target.id == "__version__"
+    ):
+        return node.value
+    return None
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the hook class used by Hatchling's custom hook loader."""
+    return WorkspaceDependenciesMetadataHook

vercel_cache-0.7.0/hatch_build.py

@@ -0,0 +1,29 @@
+"""Load the shared Vercel Hatch metadata hook."""
+
+from __future__ import annotations
+
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from types import ModuleType
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the shared workspace dependency metadata hook."""
+    return _load_shared_hook().get_metadata_hook()
+
+
+def _load_shared_hook() -> ModuleType:
+    root = Path(__file__).resolve().parent
+    candidates = [root / "../../scripts/hatch_build.py", root / "_vercel_hatch_build.py"]
+    for candidate in candidates:
+        path = candidate.resolve()
+        if path.exists():
+            spec = spec_from_file_location("_vercel_hatch_build", path)
+            if spec is None or spec.loader is None:
+                raise RuntimeError(f"could not load Hatch hook from {path}")
+            module = module_from_spec(spec)
+            spec.loader.exec_module(module)
+            return module
+    raise RuntimeError("could not find shared Vercel Hatch metadata hook")

vercel_cache-0.7.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vercel-cache"
+dynamic = ["version", "dependencies"]
+description = "Runtime cache helpers for Vercel Python applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSE.*"]
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_build.py"
+
+[tool.vercel.release.dependencies]
+dependencies = [
+    "httpx>=0.27.0,<1",
+    "vercel-headers>=0.6.0",
+    "vercel-internal-telemetry>=0.6.0",
+]
+
+[tool.uv.sources]
+vercel-headers = { workspace = true }
+vercel-internal-telemetry = { workspace = true }
+
+[tool.hatch.version]
+path = "vercel/cache/version.py"
+
+[tool.hatch.build.targets.sdist]
+force-include = { "../../scripts/hatch_build.py" = "/_vercel_hatch_build.py" }
+include = [
+    "/vercel/cache/**/*.py",
+    "/vercel/cache/py.typed",
+    "/README.md",
+    "/pyproject.toml",
+    "/hatch_build.py",
+    "/LICENSE",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+dev-mode-dirs = ["."]
+only-include = [
+    "/vercel/cache",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "--no-header --capture=tee-sys"
+asyncio_mode = "auto"
+
+[tool.poe]
+include = "../../scripts/poe/poe.toml"
+verbosity = -1
+
+[tool.poe.tasks.typecheck]
+cmd = "$MYPY"

vercel_cache-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/vercel/cache/version.py

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