ratelimitly 2.0.0__tar.gz

ratelimitly-2.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: ratelimitly
+Version: 2.0.0
+Summary: Official Python client library for RateLimitly high-performance rate limiting.
+Author-email: RateLimitly Team <support@ratelimitly.com>
+License: MIT
+Project-URL: Homepage, https://ratelimitly.com
+Project-URL: Repository, https://github.com/ratelimitly-com/rl-python-client
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=3.4
+Requires-Dist: dnspython>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+
+# RateLimitly Python client
+
+`ratelimitly` is the official Python client for [RateLimitly](https://ratelimitly.com/), a distributed admission-control service. An application asks whether it may begin work that consumes rate-limited resources. The decision can also depend on recent latency observations for services used by that work.
+
+The library exposes two independent operations:
+
+- A **resource request** atomically asks to consume quantities from zero or more rate buckets, subject to zero or more latency guards. A successful decision represents consumption of every requested quantity and authorizes the work to proceed.
+- A **latency report** contributes measured service latencies to one or more trackers. It does not request resources or make an admission decision.
+
+An empty resource request succeeds locally. A guard-only request is sent to RateLimitly and evaluated normally.
+
+## Installation
+
+```bash
+pip install ratelimitly
+```
+
+## Request one token
+
+In English, this request means: “Give me one token from the `checkout` bucket whose definition is 100 tokens per 1,000 ms.”
+
+```python
+from ratelimitly import (
+    RCLIENT_OK,
+    RateLimitlyClient,
+    ResourceRequest,
+    r_client_derive_bucket_id,
+)
+
+window_size_ms = 1_000
+rate_limit = 100
+
+resource = ResourceRequest(
+    bucket_id=r_client_derive_bucket_id(
+        "checkout",          # Exact application-defined bucket name.
+        window_size_ms,      # Bucket window in milliseconds.
+        rate_limit,          # Tokens available per window.
+    ),
+    window_size_ms=window_size_ms,
+    rate_limit=rate_limit,
+    tokens_requested=1,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status, result = client.check_rate_limit([resource])
+
+if status != RCLIENT_OK:
+    print(f"No decision: client status {status}")
+elif result.success:
+    print("Granted; perform the protected work")
+else:
+    print("Denied; do not perform the protected work")
+```
+
+`RCLIENT_OK` means a valid RateLimitly decision was received; it does not mean the request was granted. Check `result.success` for the admission decision.
+
+## Report one measured latency
+
+In English: “Add a 25 ms observation to the `inventory-backend` tracker defined by these storage settings.”
+
+```python
+from ratelimitly import (
+    RateLimitlyClient,
+    ServiceLatencyReport,
+    r_client_derive_latency_tracker_id,
+)
+
+ttl_ms = 10_000
+max_samples = 100
+min_sample_threshold = 5
+
+tracker_id = r_client_derive_latency_tracker_id(
+    "inventory-backend",    # Exact application-defined tracker name.
+    ttl_ms,                  # Maximum sample lifetime.
+    max_samples,             # Samples considered by the tracker.
+    min_sample_threshold,    # Warm-up samples before guards take effect.
+)
+
+report = ServiceLatencyReport(
+    latency_tracker_id=tracker_id,
+    observed_latency_ms=25,
+    ttl_ms=ttl_ms,
+    max_samples=max_samples,
+    min_sample_threshold=min_sample_threshold,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status = client.report_latency([report])
+```
+
+Measure the service operation, not the RateLimitly request. Reports are independent of resource requests and may be sent by a different process.
+
+## Add a latency guard
+
+This request asks for the same token only when the tracker’s current latency is below 50 ms:
+
+```python
+from ratelimitly import LatencyGuard
+
+guard = LatencyGuard(
+    latency_tracker_id=tracker_id,       # Same tracker definition as the report.
+    threshold_ms=50,                     # Admission requires current latency < 50 ms.
+    ttl_ms=ttl_ms,
+    max_samples=max_samples,
+    min_sample_threshold=min_sample_threshold,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status, result = client.check_rate_limit(
+        resources=[resource],
+        guards=[guard],
+    )
+```
+
+## Canonical IDs must agree across clients
+
+Bucket IDs include the exact bucket-name bytes, `window_size_ms`, and `rate_limit`. Latency-tracker IDs include the exact tracker-name bytes, `ttl_ms`, `max_samples`, and `min_sample_threshold`; a guard threshold is deliberately not part of the tracker ID.
+
+The Python helpers implement the same domain-separated binary preimage,
+little-endian integer encoding, BLAKE2s-256 digest, and 16-byte truncation as
+the coordinated wire-v2 C client. Do not replace them with hashing of formatted
+text, and do not use `hashlib.blake2s(..., digest_size=16)`: digest length is a
+BLAKE2 parameter, so that produces a different ID.
+
+See [API reference](docs/api.md#canonical-content-defined-identifiers) for the exact formula and cross-client known-answer vectors.
+
+## High-availability policy
+
+The default policy matches `rl-c-client`: `unit_ms=20`, one replay, a fixed one-unit round duration, one final receive-only unit, and completion delivery enabled. Its deduplication TTL and maximum decision horizon are 60 ms. The initial transmission goes to every discovered r-server, and the oldest known server’s response wins when it arrives within the first round.
+
+See [configuration](docs/configuration.md) for the complete parametrized policy and [architecture](docs/architecture.md) for wire and selection semantics.
+
+## API layers
+
+`RateLimitlyClient` is blocking. `AsyncRateLimitlyClient` provides the same serialized state machine through `asyncio`. A client preserves DNS results and UDP sockets across calls; call `close()` or use the context-manager forms to release them.
+
+The client returns the same status-code family as the C library. It does not choose an application fail-open or fail-closed policy: the caller decides what to do when no RateLimitly decision is available.
+
+## Documentation
+
+- [API reference](docs/api.md)
+- [Configuration and request policy](docs/configuration.md)
+- [Architecture, wire format, and conformance](docs/architecture.md)
+
+## License
+
+MIT

ratelimitly-2.0.0/README.md

@@ -0,0 +1,147 @@
+# RateLimitly Python client
+
+`ratelimitly` is the official Python client for [RateLimitly](https://ratelimitly.com/), a distributed admission-control service. An application asks whether it may begin work that consumes rate-limited resources. The decision can also depend on recent latency observations for services used by that work.
+
+The library exposes two independent operations:
+
+- A **resource request** atomically asks to consume quantities from zero or more rate buckets, subject to zero or more latency guards. A successful decision represents consumption of every requested quantity and authorizes the work to proceed.
+- A **latency report** contributes measured service latencies to one or more trackers. It does not request resources or make an admission decision.
+
+An empty resource request succeeds locally. A guard-only request is sent to RateLimitly and evaluated normally.
+
+## Installation
+
+```bash
+pip install ratelimitly
+```
+
+## Request one token
+
+In English, this request means: “Give me one token from the `checkout` bucket whose definition is 100 tokens per 1,000 ms.”
+
+```python
+from ratelimitly import (
+    RCLIENT_OK,
+    RateLimitlyClient,
+    ResourceRequest,
+    r_client_derive_bucket_id,
+)
+
+window_size_ms = 1_000
+rate_limit = 100
+
+resource = ResourceRequest(
+    bucket_id=r_client_derive_bucket_id(
+        "checkout",          # Exact application-defined bucket name.
+        window_size_ms,      # Bucket window in milliseconds.
+        rate_limit,          # Tokens available per window.
+    ),
+    window_size_ms=window_size_ms,
+    rate_limit=rate_limit,
+    tokens_requested=1,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status, result = client.check_rate_limit([resource])
+
+if status != RCLIENT_OK:
+    print(f"No decision: client status {status}")
+elif result.success:
+    print("Granted; perform the protected work")
+else:
+    print("Denied; do not perform the protected work")
+```
+
+`RCLIENT_OK` means a valid RateLimitly decision was received; it does not mean the request was granted. Check `result.success` for the admission decision.
+
+## Report one measured latency
+
+In English: “Add a 25 ms observation to the `inventory-backend` tracker defined by these storage settings.”
+
+```python
+from ratelimitly import (
+    RateLimitlyClient,
+    ServiceLatencyReport,
+    r_client_derive_latency_tracker_id,
+)
+
+ttl_ms = 10_000
+max_samples = 100
+min_sample_threshold = 5
+
+tracker_id = r_client_derive_latency_tracker_id(
+    "inventory-backend",    # Exact application-defined tracker name.
+    ttl_ms,                  # Maximum sample lifetime.
+    max_samples,             # Samples considered by the tracker.
+    min_sample_threshold,    # Warm-up samples before guards take effect.
+)
+
+report = ServiceLatencyReport(
+    latency_tracker_id=tracker_id,
+    observed_latency_ms=25,
+    ttl_ms=ttl_ms,
+    max_samples=max_samples,
+    min_sample_threshold=min_sample_threshold,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status = client.report_latency([report])
+```
+
+Measure the service operation, not the RateLimitly request. Reports are independent of resource requests and may be sent by a different process.
+
+## Add a latency guard
+
+This request asks for the same token only when the tracker’s current latency is below 50 ms:
+
+```python
+from ratelimitly import LatencyGuard
+
+guard = LatencyGuard(
+    latency_tracker_id=tracker_id,       # Same tracker definition as the report.
+    threshold_ms=50,                     # Admission requires current latency < 50 ms.
+    ttl_ms=ttl_ms,
+    max_samples=max_samples,
+    min_sample_threshold=min_sample_threshold,
+)
+
+with RateLimitlyClient("rl-aes1...") as client:
+    status, result = client.check_rate_limit(
+        resources=[resource],
+        guards=[guard],
+    )
+```
+
+## Canonical IDs must agree across clients
+
+Bucket IDs include the exact bucket-name bytes, `window_size_ms`, and `rate_limit`. Latency-tracker IDs include the exact tracker-name bytes, `ttl_ms`, `max_samples`, and `min_sample_threshold`; a guard threshold is deliberately not part of the tracker ID.
+
+The Python helpers implement the same domain-separated binary preimage,
+little-endian integer encoding, BLAKE2s-256 digest, and 16-byte truncation as
+the coordinated wire-v2 C client. Do not replace them with hashing of formatted
+text, and do not use `hashlib.blake2s(..., digest_size=16)`: digest length is a
+BLAKE2 parameter, so that produces a different ID.
+
+See [API reference](docs/api.md#canonical-content-defined-identifiers) for the exact formula and cross-client known-answer vectors.
+
+## High-availability policy
+
+The default policy matches `rl-c-client`: `unit_ms=20`, one replay, a fixed one-unit round duration, one final receive-only unit, and completion delivery enabled. Its deduplication TTL and maximum decision horizon are 60 ms. The initial transmission goes to every discovered r-server, and the oldest known server’s response wins when it arrives within the first round.
+
+See [configuration](docs/configuration.md) for the complete parametrized policy and [architecture](docs/architecture.md) for wire and selection semantics.
+
+## API layers
+
+`RateLimitlyClient` is blocking. `AsyncRateLimitlyClient` provides the same serialized state machine through `asyncio`. A client preserves DNS results and UDP sockets across calls; call `close()` or use the context-manager forms to release them.
+
+The client returns the same status-code family as the C library. It does not choose an application fail-open or fail-closed policy: the caller decides what to do when no RateLimitly decision is available.
+
+## Documentation
+
+- [API reference](docs/api.md)
+- [Configuration and request policy](docs/configuration.md)
+- [Architecture, wire format, and conformance](docs/architecture.md)
+
+## License
+
+MIT

ratelimitly-2.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ratelimitly"
+version = "2.0.0"
+description = "Official Python client library for RateLimitly high-performance rate limiting."
+readme = "README.md"
+authors = [
+    { name = "RateLimitly Team", email = "support@ratelimitly.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "cryptography>=3.4",
+    "dnspython>=2.0.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://ratelimitly.com"
+Repository = "https://github.com/ratelimitly-com/rl-python-client"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.20.0",
+]

ratelimitly-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ratelimitly-2.0.0/setup.py

@@ -0,0 +1,6 @@
+"""Compatibility entry point; package metadata lives in pyproject.toml."""
+
+from setuptools import setup
+
+
+setup()

ratelimitly-2.0.0/src/ratelimitly/__init__.py

@@ -0,0 +1,63 @@
+"""RateLimitly low-level Python client library."""
+
+from .auth import parse_auth_key, AuthKeyInfo
+from .policy import (
+    RequestPolicy,
+    Schedule,
+    FixedSchedule,
+    LinearSchedule,
+    ExponentialSchedule,
+    default_request_policy,
+)
+from .types import (
+    ResourceRequest,
+    LatencyGuard,
+    ServiceLatencyReport,
+    GuardResult,
+    ResourceResult,
+    RateLimitResult,
+    RCLIENT_OK,
+    RCLIENT_ERR_IO,
+    RCLIENT_ERR_TIMEOUT,
+    RCLIENT_ERR_PROTOCOL,
+    RCLIENT_ERR_AUTH,
+    RCLIENT_ERR_DNS,
+    RCLIENT_ERR_CONFIG,
+    RCLIENT_ERR_NOMEM,
+)
+from .protocol import (
+    r_client_derive_bucket_id,
+    r_client_derive_latency_tracker_id,
+)
+from .client import RateLimitlyClient, AsyncRateLimitlyClient
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "RateLimitlyClient",
+    "AsyncRateLimitlyClient",
+    "ResourceRequest",
+    "LatencyGuard",
+    "ServiceLatencyReport",
+    "GuardResult",
+    "ResourceResult",
+    "RateLimitResult",
+    "RCLIENT_OK",
+    "RCLIENT_ERR_IO",
+    "RCLIENT_ERR_TIMEOUT",
+    "RCLIENT_ERR_PROTOCOL",
+    "RCLIENT_ERR_AUTH",
+    "RCLIENT_ERR_DNS",
+    "RCLIENT_ERR_CONFIG",
+    "RCLIENT_ERR_NOMEM",
+    "RequestPolicy",
+    "Schedule",
+    "FixedSchedule",
+    "LinearSchedule",
+    "ExponentialSchedule",
+    "default_request_policy",
+    "parse_auth_key",
+    "AuthKeyInfo",
+    "r_client_derive_bucket_id",
+    "r_client_derive_latency_tracker_id",
+]

ratelimitly-2.0.0/src/ratelimitly/auth.py

@@ -0,0 +1,165 @@
+"""Bech32 authentication key parser for RateLimitly credentials."""
+
+from dataclasses import dataclass
+from typing import List, Literal, Tuple
+
+BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+BECH32_REV = {c: i for i, c in enumerate(BECH32_CHARSET)}
+TENANT_KEY_FORMAT_VERSION = 1
+
+
+@dataclass(frozen=True)
+class AuthKeyInfo:
+    auth_type: Literal["aes", "cookie"]
+    format_version: int
+    key_id: int
+    secret: bytes
+    rate_buckets_max: int
+    latency_services_max: int
+    metrics_labels_max: int
+    latency_buffer_size_max: int
+    dedup_ttl_ms_max: int
+    rate_window_size_ms_max: int
+
+    @property
+    def default_dns_srv(self) -> str:
+        """Constructs default tenant SRV domain string: c-${key_id}.p0.ratelimitly.com"""
+        return f"c-{self.key_id}.p0.ratelimitly.com"
+
+
+def _bech32_polymod(values: List[int]) -> int:
+    generators = (0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3)
+    checksum = 1
+    for value in values:
+        top = checksum >> 25
+        checksum = ((checksum & 0x1FFFFFF) << 5) ^ value
+        for index, generator in enumerate(generators):
+            if (top >> index) & 1:
+                checksum ^= generator
+    return checksum
+
+
+def _bech32_hrp_expand(hrp: str) -> List[int]:
+    return [ord(char) >> 5 for char in hrp] + [0] + [ord(char) & 31 for char in hrp]
+
+
+def _bech32_decode(bech_str: str) -> Tuple[str, List[int]]:
+    """Decodes a Bech32 string into HRP and 5-bit data values."""
+    if not bech_str or any(ord(char) < 33 or ord(char) > 126 for char in bech_str):
+        raise ValueError("Invalid Bech32 length")
+    if bech_str.lower() != bech_str and bech_str.upper() != bech_str:
+        raise ValueError("Mixed case Bech32 string")
+
+    bech_str = bech_str.lower()
+    pos = bech_str.rfind("1")
+    if pos < 1 or pos + 7 > len(bech_str):
+        raise ValueError("Invalid separator position in Bech32 string")
+
+    hrp = bech_str[:pos]
+    data = []
+    for c in bech_str[pos + 1:]:
+        if c not in BECH32_REV:
+            raise ValueError(f"Invalid character in Bech32 string: '{c}'")
+        data.append(BECH32_REV[c])
+
+    if _bech32_polymod(_bech32_hrp_expand(hrp) + data) != 1:
+        raise ValueError("Invalid Bech32 checksum")
+
+    return hrp, data
+
+
+def _convertbits(data: List[int], frombits: int, tobits: int, pad: bool = True) -> bytes:
+    """Converts a bit array from one representation to another (5-bit to 8-bit)."""
+    acc = 0
+    bits = 0
+    ret = bytearray()
+    maxv = (1 << tobits) - 1
+    max_acc = (1 << (frombits + tobits - 1)) - 1
+    for value in data:
+        if value < 0 or (value >> frombits):
+            raise ValueError("Invalid bit value")
+        acc = ((acc << frombits) | value) & max_acc
+        bits += frombits
+        while bits >= tobits:
+            bits -= tobits
+            ret.append((acc >> bits) & maxv)
+    if pad:
+        if bits:
+            ret.append((acc << (tobits - bits)) & maxv)
+    elif bits >= frombits or ((acc << (tobits - bits)) & maxv):
+        raise ValueError("Invalid padding in bit conversion")
+    return bytes(ret)
+
+
+def _decode_quota_word(word: int) -> Tuple[int, int, int, int, int, int]:
+    rate_exp = word & 0x1F
+    latency_exp = (word >> 5) & 0x1F
+    labels_exp = (word >> 10) & 0x1F
+    buffer_exp = (word >> 15) & 0x0F
+    dedup_units = (word >> 19) & 0xFF
+    window_exp = (word >> 27) & 0x1F
+
+    if rate_exp > 24:
+        raise ValueError("Invalid packed rate_buckets_max quota")
+    if latency_exp > 24:
+        raise ValueError("Invalid packed latency_services_max quota")
+    if not 1 <= dedup_units <= 200:
+        raise ValueError("Invalid packed dedup_ttl_ms_max quota")
+
+    return (
+        1 << rate_exp,
+        1 << latency_exp,
+        1 << labels_exp,
+        1 << buffer_exp,
+        dedup_units * 10,
+        0xFFFFFFFF if window_exp == 31 else 1 << window_exp,
+    )
+
+
+def parse_auth_key(key_str: str) -> AuthKeyInfo:
+    """
+    Parses a RateLimitly Bech32 authentication key (rl-aes1... or rl-cookie1...).
+
+    Extracts:
+    - Auth Type ('aes' or 'cookie')
+    - Key ID (uint64)
+    - Secret payload bytes (32 bytes)
+    """
+    if not isinstance(key_str, str):
+        raise TypeError("Authentication key must be a string")
+
+    hrp, data_5bit = _bech32_decode(key_str)
+    if hrp == "rl-aes":
+        auth_type = "aes"
+    elif hrp == "rl-cookie":
+        auth_type = "cookie"
+    else:
+        raise ValueError("Invalid auth key HRP; expected 'rl-aes' or 'rl-cookie'")
+
+    # Remove 6-character checksum at the end
+    payload_5bit = data_5bit[:-6]
+    raw_bytes = _convertbits(payload_5bit, 5, 8, pad=False)
+
+    if len(raw_bytes) != 45:
+        raise ValueError(f"Invalid auth key payload length: {len(raw_bytes)} bytes (expected 45)")
+
+    format_version = raw_bytes[0]
+    if format_version != TENANT_KEY_FORMAT_VERSION:
+        raise ValueError(f"Unsupported auth key format version: {format_version}")
+
+    key_id = int.from_bytes(raw_bytes[1:9], byteorder="little")
+    secret = raw_bytes[9:41]
+    quotas = _decode_quota_word(int.from_bytes(raw_bytes[41:45], byteorder="little"))
+
+    return AuthKeyInfo(
+        auth_type=auth_type,
+        format_version=format_version,
+        key_id=key_id,
+        secret=secret,
+        rate_buckets_max=quotas[0],
+        latency_services_max=quotas[1],
+        metrics_labels_max=quotas[2],
+        latency_buffer_size_max=quotas[3],
+        dedup_ttl_ms_max=quotas[4],
+        rate_window_size_ms_max=quotas[5],
+    )