usagerail 0.1.0__tar.gz

usagerail-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# 密钥和本地环境：永远不提交
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+
+# 依赖和构建产物
+node_modules/
+.pnpm-store/
+.next/
+out/
+dist/
+build/
+coverage/
+*.tsbuildinfo
+.turbo/
+.vercel/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+
+# 交叉审查的原始输出（本地留档）
+.review/
+
+# 系统和编辑器
+.DS_Store
+*.log
+.idea/
+.vscode/
+
+# Stripe 沙盒每次运行建的对象 ID（清理用）
+.stripe-runs/

usagerail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UsageRail
+
+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.

usagerail-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: usagerail
+Version: 0.1.0
+Summary: UsageRail SDK for Python: API keys, rate limits, quotas and usage metering inside your API server
+Project-URL: Homepage, https://usagerail.com
+Project-URL: Documentation, https://usagerail.com/docs
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# usagerail
+
+The UsageRail SDK for Python. It checks API keys, applies rate limits and quotas, and counts usage per customer inside your own process, then reports the counts to UsageRail in the background. Requests never pass through us.
+
+It needs Python 3.10 or newer and has no dependencies of its own. Versions start at 0.x, so names may still change between minor versions.
+
+```bash
+pip install usagerail
+```
+
+Get the app key from the console at https://app.usagerail.com. Setup for each framework, options and known limitations are in the docs at https://usagerail.com/docs.
+
+## FastAPI and Starlette
+
+```python
+import os
+
+from fastapi import FastAPI, Request
+from usagerail.fastapi import UsageRailMiddleware
+
+app = FastAPI()
+app.add_middleware(UsageRailMiddleware, app_key=os.environ["USAGERAIL_APP_KEY"], auth="api-key")
+
+
+@app.post("/v1/generate")
+async def generate(request: Request):
+    result = await run_model(await request.json())
+    request.state.usagerail.track(result.tokens)  # optional: count tokens instead of requests
+    return result.body
+```
+
+## Flask
+
+```python
+import os
+
+from flask import Flask, g, request
+from usagerail.flask import UsageRail
+
+app = Flask(__name__)
+UsageRail(app, app_key=os.environ["USAGERAIL_APP_KEY"], auth="api-key")
+
+
+@app.post("/v1/generate")
+def generate():
+    result = run_model(request.json)
+    g.usagerail.track(result.tokens)
+    return result.body
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    # ...
+    "usagerail.django.UsageRailMiddleware",
+]
+USAGERAIL = {"app_key": os.environ["USAGERAIL_APP_KEY"], "auth": "api-key"}
+
+# views.py
+def generate(request):
+    result = run_model(request.body)
+    request.usagerail.track(result.tokens)
+    return JsonResponse(result.body)
+```
+
+## Your own authentication
+
+If your API already has its own keys or logins, pass `auth="custom"` and a `consumer` function. It gets the framework's request and returns your customer's ID, or `None` for anonymous traffic. Return an identity your own code has verified, never a value the caller can set, such as a plain header:
+
+```python
+app.add_middleware(
+    UsageRailMiddleware,
+    app_key=os.environ["USAGERAIL_APP_KEY"],
+    auth="custom",
+    consumer=lambda request: request.user.identity if request.user.is_authenticated else None,
+)
+```
+
+The function runs before your route handlers. In FastAPI that is before `Depends(...)`, so the identity has to come from an authentication middleware that runs first. FastAPI runs the middleware added last first, so call `app.add_middleware()` for your authentication after the line that adds UsageRail. In Django, list UsageRail after `AuthenticationMiddleware` if you want `request.user`. In Flask, register your own `before_request` hook first.
+
+## Good to know before you deploy
+
+- Rejected requests get 401 (unknown or revoked key), 403 (suspended customer), 429 (rate limit or quota), 402 (prepaid credit used up) or 503 (UsageRail unreachable and you chose to refuse). The body is `{"error": "...", "retry_after": 30}`. Pass `on_reject` to send your own response instead.
+- Counts are sent every 60 seconds and once more when the app shuts down. Under uvicorn, FastAPI's lifespan shutdown sends them. Flask and Django send them when the process exits normally, which gunicorn does on SIGTERM; uvicorn re-raises SIGTERM after shutting down, so Django under uvicorn loses the counts it hadn't sent. If a process is killed hard (`kill -9`, out of memory), up to about 10 minutes of unsent counts are lost and never billed.
+- With `gunicorn --preload`, each worker becomes a separate SDK instance after the fork and keeps the key list it inherited.
+- The key list is cached in a private folder in the system temp directory, so a restart doesn't wait for the first download. Pass `snapshot=False` to turn this off.
+- WebSocket connections are not checked or counted.
+- Memory: around 15 MB with 10,000 keys and customers, and at most about 85 MB at the limits: 100,000 keys, 100,000 customers' settings, and the 40,000 customers used most recently. Customers beyond that are fetched again when they come back, which adds one round trip to their next request.
+- Other frameworks can use `usagerail.create_engine()` directly: call `begin()` when a request arrives and `end()` when it finishes.

usagerail-0.1.0/README.md

@@ -0,0 +1,91 @@
+# usagerail
+
+The UsageRail SDK for Python. It checks API keys, applies rate limits and quotas, and counts usage per customer inside your own process, then reports the counts to UsageRail in the background. Requests never pass through us.
+
+It needs Python 3.10 or newer and has no dependencies of its own. Versions start at 0.x, so names may still change between minor versions.
+
+```bash
+pip install usagerail
+```
+
+Get the app key from the console at https://app.usagerail.com. Setup for each framework, options and known limitations are in the docs at https://usagerail.com/docs.
+
+## FastAPI and Starlette
+
+```python
+import os
+
+from fastapi import FastAPI, Request
+from usagerail.fastapi import UsageRailMiddleware
+
+app = FastAPI()
+app.add_middleware(UsageRailMiddleware, app_key=os.environ["USAGERAIL_APP_KEY"], auth="api-key")
+
+
+@app.post("/v1/generate")
+async def generate(request: Request):
+    result = await run_model(await request.json())
+    request.state.usagerail.track(result.tokens)  # optional: count tokens instead of requests
+    return result.body
+```
+
+## Flask
+
+```python
+import os
+
+from flask import Flask, g, request
+from usagerail.flask import UsageRail
+
+app = Flask(__name__)
+UsageRail(app, app_key=os.environ["USAGERAIL_APP_KEY"], auth="api-key")
+
+
+@app.post("/v1/generate")
+def generate():
+    result = run_model(request.json)
+    g.usagerail.track(result.tokens)
+    return result.body
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    # ...
+    "usagerail.django.UsageRailMiddleware",
+]
+USAGERAIL = {"app_key": os.environ["USAGERAIL_APP_KEY"], "auth": "api-key"}
+
+# views.py
+def generate(request):
+    result = run_model(request.body)
+    request.usagerail.track(result.tokens)
+    return JsonResponse(result.body)
+```
+
+## Your own authentication
+
+If your API already has its own keys or logins, pass `auth="custom"` and a `consumer` function. It gets the framework's request and returns your customer's ID, or `None` for anonymous traffic. Return an identity your own code has verified, never a value the caller can set, such as a plain header:
+
+```python
+app.add_middleware(
+    UsageRailMiddleware,
+    app_key=os.environ["USAGERAIL_APP_KEY"],
+    auth="custom",
+    consumer=lambda request: request.user.identity if request.user.is_authenticated else None,
+)
+```
+
+The function runs before your route handlers. In FastAPI that is before `Depends(...)`, so the identity has to come from an authentication middleware that runs first. FastAPI runs the middleware added last first, so call `app.add_middleware()` for your authentication after the line that adds UsageRail. In Django, list UsageRail after `AuthenticationMiddleware` if you want `request.user`. In Flask, register your own `before_request` hook first.
+
+## Good to know before you deploy
+
+- Rejected requests get 401 (unknown or revoked key), 403 (suspended customer), 429 (rate limit or quota), 402 (prepaid credit used up) or 503 (UsageRail unreachable and you chose to refuse). The body is `{"error": "...", "retry_after": 30}`. Pass `on_reject` to send your own response instead.
+- Counts are sent every 60 seconds and once more when the app shuts down. Under uvicorn, FastAPI's lifespan shutdown sends them. Flask and Django send them when the process exits normally, which gunicorn does on SIGTERM; uvicorn re-raises SIGTERM after shutting down, so Django under uvicorn loses the counts it hadn't sent. If a process is killed hard (`kill -9`, out of memory), up to about 10 minutes of unsent counts are lost and never billed.
+- With `gunicorn --preload`, each worker becomes a separate SDK instance after the fork and keeps the key list it inherited.
+- The key list is cached in a private folder in the system temp directory, so a restart doesn't wait for the first download. Pass `snapshot=False` to turn this off.
+- WebSocket connections are not checked or counted.
+- Memory: around 15 MB with 10,000 keys and customers, and at most about 85 MB at the limits: 100,000 keys, 100,000 customers' settings, and the 40,000 customers used most recently. Customers beyond that are fetched again when they come back, which adds one round trip to their next request.
+- Other frameworks can use `usagerail.create_engine()` directly: call `begin()` when a request arrives and `end()` when it finishes.

usagerail-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usagerail"
+version = "0.1.0"
+description = "UsageRail SDK for Python: API keys, rate limits, quotas and usage metering inside your API server"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+# 运行时不依赖任何第三方包：适配器只在用到时才导入对应的框架
+dependencies = []
+classifiers = [
+    "Framework :: Django",
+    "Framework :: FastAPI",
+    "Framework :: Flask",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://usagerail.com"
+Documentation = "https://usagerail.com/docs"
+
+[dependency-groups]
+dev = [
+    "pytest==9.1.1",
+    "mypy==2.4.0",
+    "fastapi==0.142.2",
+    "starlette==1.7.0",
+    # Starlette 1.2 起 TestClient 用 httpx2，用 httpx 会警告
+    "httpx2==2.13.1",
+    "flask==3.1.3",
+    "werkzeug==3.1.9",
+    "django==6.1.1; python_version >= '3.12'",
+]
+
+[tool.uv]
+# 只装发布满两周的版本（和 pnpm 的 minimumReleaseAge 同一条规矩），间接依赖也算
+exclude-newer = "14 days"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usagerail"]
+
+# sdist 和 Node 包一样只放装包用得到的：实现笔记（NOTES.md）、测试、基准不发出去（D47）。
+# pyproject.toml、README、LICENSE hatchling 会自己带上
+[tool.hatch.build.targets.sdist]
+include = ["src/usagerail"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src"]
+python_version = "3.10"
+strict = true
+# Django 不带类型标注（要另装 django-stubs），只查我们自己的代码
+[[tool.mypy.overrides]]
+module = ["django.*"]
+ignore_missing_imports = true

usagerail-0.1.0/src/usagerail/__init__.py

@@ -0,0 +1,43 @@
+"""UsageRail 的 Python SDK：在你自己的 API 服务里发 key、限流、管额度、计量（PRD 5.1）。
+
+FastAPI / Starlette 用 usagerail.asgi，Flask 用 usagerail.flask，Django 用 usagerail.django。
+自己接别的框架时用 create_engine：begin() 拿到结论，请求结束调 end()。
+"""
+
+from .engine import (
+    MAX_TRACK_UNITS,
+    Admission,
+    ConsumerIdentity,
+    Decision,
+    Engine,
+    Pending,
+    Rejection,
+    RejectionCode,
+    RequestHandle,
+    create_engine,
+    read_api_key,
+    rejection_body,
+)
+from .key_store import SnapshotStore
+from .snapshot import FileSnapshotStore
+from .transport import HttpTransport, Transport, TransportError
+
+__all__ = [
+    "MAX_TRACK_UNITS",
+    "Admission",
+    "ConsumerIdentity",
+    "Decision",
+    "Engine",
+    "FileSnapshotStore",
+    "HttpTransport",
+    "Pending",
+    "Rejection",
+    "RejectionCode",
+    "RequestHandle",
+    "SnapshotStore",
+    "Transport",
+    "TransportError",
+    "create_engine",
+    "read_api_key",
+    "rejection_body",
+]

usagerail-0.1.0/src/usagerail/_adapters.py

@@ -0,0 +1,14 @@
+"""三个框架适配器共用的一点东西。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .engine import Engine, create_engine
+from .snapshot import FileSnapshotStore
+
+
+def engine_for(app_key: str, auth: str, snapshot: bool, options: dict[str, Any]) -> Engine[Any]:
+    """key 快照只对用我们 key 的应用有意义，默认落盘到本地临时目录（PRD 5.3）"""
+    store = FileSnapshotStore(app_key) if snapshot and auth == "api-key" and app_key else None
+    return create_engine(app_key=app_key, auth=auth, snapshot_store=store, **options)

usagerail-0.1.0/src/usagerail/_futures.py

@@ -0,0 +1,100 @@
+"""把 concurrent.futures.Future 当成 Node 的 Promise 用的几个小工具。
+
+引擎里走网络的地方（远程校验、领租约、同步、上报）都返回 Future：Flask、Django 的线程里阻塞等它，
+FastAPI 里 await 它。等的时候不占线程，几百个请求同时等租约也不会把线程池耗光（PRD「最多多等 300 毫秒」）。
+回调在完成它的那个线程里跑，已经完成的 Future 加回调会当场跑，所以引擎的状态一律在锁里改。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import Future, InvalidStateError
+from typing import Any, Callable, Generator, Generic, TypeVar
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+def resolved(value: T) -> Future[T]:
+    future: Future[T] = Future()
+    future.set_result(value)
+    return future
+
+
+def settle(future: Future[T], value: T) -> None:
+    """已经有结果的不再改（超时和完成同时到时，先到的算）"""
+    try:
+        future.set_result(value)
+    except InvalidStateError:
+        pass
+
+
+def fail(future: Future[Any], error: BaseException) -> None:
+    try:
+        future.set_exception(error)
+    except InvalidStateError:
+        pass
+
+
+def error_of(future: Future[Any]) -> BaseException | None:
+    """已经完成的 Future 的异常；取消的当作出错"""
+    if future.cancelled():
+        return RuntimeError("cancelled")
+    return future.exception()
+
+
+def then(
+    future: Future[T],
+    on_value: Callable[[T], U | Future[U]],
+    on_error: Callable[[BaseException], U | Future[U]] | None = None,
+) -> Future[U]:
+    """Promise.then：回调可以返回值，也可以返回 Future（会展开）"""
+    out: Future[U] = Future()
+
+    def run(callback: Callable[[Any], U | Future[U]], argument: Any) -> None:
+        try:
+            result = callback(argument)
+        except BaseException as error:  # noqa: BLE001 - 原样交给下一环
+            fail(out, error)
+            return
+        if isinstance(result, Future):
+            result.add_done_callback(lambda inner: _copy(inner, out))
+        else:
+            settle(out, result)
+
+    def done(completed: Future[T]) -> None:
+        error = error_of(completed)
+        if error is None:
+            run(on_value, completed.result())
+        elif on_error is not None:
+            run(on_error, error)
+        else:
+            fail(out, error)
+
+    future.add_done_callback(done)
+    return out
+
+
+def _copy(source: Future[Any], target: Future[Any]) -> None:
+    error = error_of(source)
+    if error is None:
+        settle(target, source.result())
+    else:
+        fail(target, error)
+
+
+class Pending(Generic[T]):
+    """还要等服务端的结论。WSGI 里 .result() 阻塞等；ASGI 里直接 await"""
+
+    __slots__ = ("future",)
+
+    def __init__(self, future: Future[T]) -> None:
+        self.future = future
+
+    def result(self, timeout: float | None = None) -> T:
+        return self.future.result(timeout)
+
+    def __await__(self) -> Generator[Any, None, T]:
+        # shield：等的一方被取消（客户端走了）不能连带取消底下的 Future。引擎还会给它结论（比如领到的租约），
+        # 取消了结论就没处放，预留一直挂着；调用方自己决定被取消以后怎么收尾
+        return asyncio.shield(asyncio.wrap_future(self.future)).__await__()

usagerail-0.1.0/src/usagerail/_time.py

@@ -0,0 +1,24 @@
+"""ISO 8601 时间和毫秒时间戳之间的换算，格式和 JavaScript 的 Date 一致（服务端和 Node SDK 用的就是它）。"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def parse_iso_ms(value: object) -> float | None:
+    """读不懂的返回 None。没带时区的按 UTC 算（服务端总是带 Z）"""
+    if not isinstance(value, str) or not value:
+        return None
+    text = value[:-1] + "+00:00" if value.endswith(("Z", "z")) else value
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp() * 1000
+
+
+def iso_from_ms(ms: float) -> str:
+    """2026-10-20T12:00:10.000Z，和 new Date(ms).toISOString() 一样"""
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")

usagerail-0.1.0/src/usagerail/clock.py

@@ -0,0 +1,95 @@
+"""时钟。SDK 里所有「现在」都从这里取，测试注入假时钟，不用真的等（docs/decisions.md D4）。"""
+
+from __future__ import annotations
+
+import heapq
+import itertools
+import os
+import threading
+import time
+from typing import Callable, Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> float:
+        """墙上时间（毫秒）：分钟归属、key 过期、周期边界。这些要和服务端、Stripe 的时间对得上"""
+        ...
+
+    def monotonic(self) -> float:
+        """单调时间（毫秒）：租约本地有效期、令牌桶、退避、各种缓存时长。机器改时间、NTP 校时都不影响（PRD 5.5）"""
+        ...
+
+    def set_timer(self, callback: Callable[[], None], delay_ms: float) -> Callable[[], None]:
+        """定时器，返回取消函数。后台的同步、上报、续租都走它，测试里由假时钟推进"""
+        ...
+
+
+class _Timer:
+    __slots__ = ("callback", "cancelled")
+
+    def __init__(self, callback: Callable[[], None]) -> None:
+        self.callback = callback
+        self.cancelled = False
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+
+class SystemClock:
+    """所有定时器共用一个后台线程，按到期时间排队跑，不是一个定时器一个线程：等租约的请求每个都有一个定时器。
+    线程是 daemon 的，不拖住进程退出（同 Node 的 unref）。回调要快，走网络的事交给 transport 的线程。"""
+
+    def __init__(self) -> None:
+        self._reset()
+        # gunicorn --preload 这类先建好应用再 fork 的：子进程里没有父进程的线程，锁也可能停在被持有的状态。
+        # 子进程重新来过；父进程排着的定时器属于父进程的引擎，引擎自己会在子进程里重新排（engine.py）
+        # Windows 没有 fork，也没有这个函数
+        if hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=self._reset)
+
+    def _reset(self) -> None:
+        self._condition = threading.Condition()
+        self._queue: list[tuple[float, int, _Timer]] = []
+        self._order = itertools.count()
+        self._thread: threading.Thread | None = None
+
+    def now(self) -> float:
+        return time.time() * 1000
+
+    def monotonic(self) -> float:
+        return time.monotonic() * 1000
+
+    def set_timer(self, callback: Callable[[], None], delay_ms: float) -> Callable[[], None]:
+        timer = _Timer(callback)
+        due = time.monotonic() + max(0.0, delay_ms) / 1000
+        with self._condition:
+            heapq.heappush(self._queue, (due, next(self._order), timer))
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(target=self._run, name="usagerail-timers", daemon=True)
+                self._thread.start()
+            self._condition.notify()
+        return timer.cancel
+
+    def _run(self) -> None:
+        while True:
+            with self._condition:
+                while True:
+                    while self._queue and self._queue[0][2].cancelled:
+                        heapq.heappop(self._queue)
+                    if not self._queue:
+                        self._condition.wait()
+                        continue
+                    wait = self._queue[0][0] - time.monotonic()
+                    if wait <= 0:
+                        timer = heapq.heappop(self._queue)[2]
+                        break
+                    self._condition.wait(wait)
+            if timer.cancelled:
+                continue
+            try:
+                timer.callback()
+            except Exception:  # noqa: BLE001 - 回调出错不能让定时器线程死掉，引擎自己会打警告
+                pass
+
+
+system_clock = SystemClock()