zae-limiter 0.1.0__py3-none-any.whl

zae_limiter/schema.py

@@ -0,0 +1,163 @@
+"""DynamoDB schema definitions and key builders."""
+
+from typing import Any
+
+# Table and index names
+DEFAULT_TABLE_NAME = "rate_limits"
+GSI1_NAME = "GSI1"  # For parent -> children lookups
+GSI2_NAME = "GSI2"  # For resource aggregation
+
+# Key prefixes
+ENTITY_PREFIX = "ENTITY#"
+PARENT_PREFIX = "PARENT#"
+CHILD_PREFIX = "CHILD#"
+RESOURCE_PREFIX = "RESOURCE#"
+SYSTEM_PREFIX = "SYSTEM#"
+
+# Sort key prefixes
+SK_META = "#META"
+SK_BUCKET = "#BUCKET#"
+SK_LIMIT = "#LIMIT#"
+SK_RESOURCE = "#RESOURCE#"
+SK_USAGE = "#USAGE#"
+SK_VERSION = "#VERSION"
+
+# Special resource for default limits
+DEFAULT_RESOURCE = "_default_"
+
+
+def pk_entity(entity_id: str) -> str:
+    """Build partition key for an entity."""
+    return f"{ENTITY_PREFIX}{entity_id}"
+
+
+def pk_system() -> str:
+    """Build partition key for system records (e.g., version)."""
+    return SYSTEM_PREFIX
+
+
+def sk_version() -> str:
+    """Build sort key for version record."""
+    return SK_VERSION
+
+
+def sk_meta() -> str:
+    """Build sort key for entity metadata."""
+    return SK_META
+
+
+def sk_bucket(resource: str, limit_name: str) -> str:
+    """Build sort key for a bucket."""
+    return f"{SK_BUCKET}{resource}#{limit_name}"
+
+
+def sk_limit(resource: str, limit_name: str) -> str:
+    """Build sort key for a limit config."""
+    return f"{SK_LIMIT}{resource}#{limit_name}"
+
+
+def sk_limit_prefix(resource: str) -> str:
+    """Build sort key prefix for querying limits by resource."""
+    return f"{SK_LIMIT}{resource}#"
+
+
+def sk_resource(resource: str) -> str:
+    """Build sort key for resource access tracking."""
+    return f"{SK_RESOURCE}{resource}"
+
+
+def sk_usage(resource: str, window_key: str) -> str:
+    """Build sort key for usage snapshot."""
+    return f"{SK_USAGE}{resource}#{window_key}"
+
+
+def gsi1_pk_parent(parent_id: str) -> str:
+    """Build GSI1 partition key for parent lookup."""
+    return f"{PARENT_PREFIX}{parent_id}"
+
+
+def gsi1_sk_child(entity_id: str) -> str:
+    """Build GSI1 sort key for child entry."""
+    return f"{CHILD_PREFIX}{entity_id}"
+
+
+def gsi2_pk_resource(resource: str) -> str:
+    """Build GSI2 partition key for resource aggregation."""
+    return f"{RESOURCE_PREFIX}{resource}"
+
+
+def gsi2_sk_bucket(entity_id: str, limit_name: str) -> str:
+    """Build GSI2 sort key for bucket entry."""
+    return f"BUCKET#{entity_id}#{limit_name}"
+
+
+def gsi2_sk_access(entity_id: str) -> str:
+    """Build GSI2 sort key for access tracking entry."""
+    return f"ACCESS#{entity_id}"
+
+
+def gsi2_sk_usage(window_key: str, entity_id: str) -> str:
+    """Build GSI2 sort key for usage snapshot entry."""
+    return f"USAGE#{window_key}#{entity_id}"
+
+
+def parse_bucket_sk(sk: str) -> tuple[str, str]:
+    """Parse resource and limit_name from bucket sort key."""
+    # SK format: #BUCKET#{resource}#{limit_name}
+    if not sk.startswith(SK_BUCKET):
+        raise ValueError(f"Invalid bucket SK: {sk}")
+    parts = sk[len(SK_BUCKET) :].split("#", 1)
+    if len(parts) != 2:
+        raise ValueError(f"Invalid bucket SK format: {sk}")
+    return parts[0], parts[1]
+
+
+def get_table_definition(table_name: str) -> dict[str, Any]:
+    """
+    Get the DynamoDB table definition for CreateTable.
+
+    Returns a dictionary suitable for boto3 create_table().
+    """
+    return {
+        "TableName": table_name,
+        "BillingMode": "PAY_PER_REQUEST",
+        "AttributeDefinitions": [
+            {"AttributeName": "PK", "AttributeType": "S"},
+            {"AttributeName": "SK", "AttributeType": "S"},
+            {"AttributeName": "GSI1PK", "AttributeType": "S"},
+            {"AttributeName": "GSI1SK", "AttributeType": "S"},
+            {"AttributeName": "GSI2PK", "AttributeType": "S"},
+            {"AttributeName": "GSI2SK", "AttributeType": "S"},
+        ],
+        "KeySchema": [
+            {"AttributeName": "PK", "KeyType": "HASH"},
+            {"AttributeName": "SK", "KeyType": "RANGE"},
+        ],
+        "GlobalSecondaryIndexes": [
+            {
+                "IndexName": GSI1_NAME,
+                "KeySchema": [
+                    {"AttributeName": "GSI1PK", "KeyType": "HASH"},
+                    {"AttributeName": "GSI1SK", "KeyType": "RANGE"},
+                ],
+                "Projection": {"ProjectionType": "ALL"},
+            },
+            {
+                "IndexName": GSI2_NAME,
+                "KeySchema": [
+                    {"AttributeName": "GSI2PK", "KeyType": "HASH"},
+                    {"AttributeName": "GSI2SK", "KeyType": "RANGE"},
+                ],
+                "Projection": {"ProjectionType": "ALL"},
+            },
+        ],
+        "StreamSpecification": {
+            "StreamEnabled": True,
+            "StreamViewType": "NEW_AND_OLD_IMAGES",
+        },
+    }
+
+
+def calculate_ttl(now_ms: int, ttl_seconds: int = 86400) -> int:
+    """Calculate TTL timestamp (epoch seconds)."""
+    return (now_ms // 1000) + ttl_seconds

zae_limiter/version.py

@@ -0,0 +1,214 @@
+"""Version tracking and compatibility checking for zae-limiter infrastructure."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Current schema version - increment when schema changes
+CURRENT_SCHEMA_VERSION = "1.0.0"
+
+
+@dataclass(frozen=True, order=False)
+class ParsedVersion:
+    """Parsed semantic version components."""
+
+    major: int
+    minor: int
+    patch: int
+    prerelease: str | None = None
+
+    def __str__(self) -> str:
+        base = f"{self.major}.{self.minor}.{self.patch}"
+        if self.prerelease:
+            return f"{base}-{self.prerelease}"
+        return base
+
+    def __lt__(self, other: ParsedVersion) -> bool:
+        # Compare major.minor.patch first
+        if (self.major, self.minor, self.patch) != (other.major, other.minor, other.patch):
+            return (self.major, self.minor, self.patch) < (other.major, other.minor, other.patch)
+        # Prerelease versions are less than release versions
+        if self.prerelease and not other.prerelease:
+            return True
+        if not self.prerelease and other.prerelease:
+            return False
+        # Both have prerelease, compare lexically
+        return (self.prerelease or "") < (other.prerelease or "")
+
+    def __le__(self, other: ParsedVersion) -> bool:
+        return self == other or self < other
+
+    def __gt__(self, other: ParsedVersion) -> bool:
+        return not self <= other
+
+    def __ge__(self, other: ParsedVersion) -> bool:
+        return not self < other
+
+
+def parse_version(version_str: str) -> ParsedVersion:
+    """
+    Parse a semantic version string.
+
+    Handles formats like:
+    - "1.2.3"
+    - "1.2.3-dev"
+    - "1.2.3.dev123+gabcdef"
+    - "0.1.0"
+
+    Args:
+        version_str: Version string to parse
+
+    Returns:
+        ParsedVersion tuple
+
+    Raises:
+        ValueError: If version string is invalid
+    """
+    # Remove leading 'v' if present
+    if version_str.startswith("v"):
+        version_str = version_str[1:]
+
+    # Handle PEP 440 dev versions (e.g., "0.1.0.dev123+gabcdef")
+    # Convert to semver-like format
+    version_str = re.sub(r"\.dev\d+.*$", "-dev", version_str)
+
+    # Match standard semver with optional prerelease
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$", version_str)
+    if not match:
+        raise ValueError(f"Invalid version string: {version_str}")
+
+    return ParsedVersion(
+        major=int(match.group(1)),
+        minor=int(match.group(2)),
+        patch=int(match.group(3)),
+        prerelease=match.group(4),
+    )
+
+
+@dataclass
+class InfrastructureVersion:
+    """Version information for deployed infrastructure."""
+
+    schema_version: str
+    lambda_version: str | None
+    template_version: str | None
+    client_min_version: str
+
+    @classmethod
+    def from_record(cls, record: dict[str, str | None]) -> InfrastructureVersion:
+        """Create from a version record dictionary."""
+        return cls(
+            schema_version=record.get("schema_version") or "1.0.0",
+            lambda_version=record.get("lambda_version"),
+            template_version=record.get("template_version"),
+            client_min_version=record.get("client_min_version") or "0.0.0",
+        )
+
+
+@dataclass
+class CompatibilityResult:
+    """Result of a version compatibility check."""
+
+    is_compatible: bool
+    requires_schema_migration: bool = False
+    requires_lambda_update: bool = False
+    requires_template_update: bool = False
+    message: str = ""
+
+
+def check_compatibility(
+    client_version: str,
+    infra_version: InfrastructureVersion,
+) -> CompatibilityResult:
+    """
+    Check compatibility between client and infrastructure versions.
+
+    Rules:
+    - Major version mismatch in schema: Always incompatible (requires migration)
+    - Client version < client_min_version: Incompatible (client too old)
+    - Lambda version < client version: Lambda update available
+    - Patch version differences: Always compatible
+
+    Args:
+        client_version: The client library version (e.g., "1.2.3")
+        infra_version: The infrastructure version information
+
+    Returns:
+        CompatibilityResult with compatibility status and details
+    """
+    try:
+        client = parse_version(client_version)
+    except ValueError:
+        return CompatibilityResult(
+            is_compatible=False,
+            message=f"Invalid client version: {client_version}",
+        )
+
+    try:
+        schema = parse_version(infra_version.schema_version)
+    except ValueError:
+        return CompatibilityResult(
+            is_compatible=False,
+            message=f"Invalid schema version: {infra_version.schema_version}",
+        )
+
+    try:
+        min_version = parse_version(infra_version.client_min_version)
+    except ValueError:
+        min_version = ParsedVersion(0, 0, 0)
+
+    # Check if client meets minimum version requirement
+    if client < min_version:
+        return CompatibilityResult(
+            is_compatible=False,
+            message=(
+                f"Client version {client_version} is below minimum required "
+                f"version {infra_version.client_min_version}. Please upgrade."
+            ),
+        )
+
+    # Check schema compatibility (major version must match)
+    if client.major != schema.major:
+        return CompatibilityResult(
+            is_compatible=False,
+            requires_schema_migration=True,
+            message=(
+                f"Schema version mismatch: client major version {client.major} "
+                f"!= schema major version {schema.major}. "
+                "Schema migration required."
+            ),
+        )
+
+    # Check if Lambda needs update
+    requires_lambda_update = False
+    if infra_version.lambda_version:
+        try:
+            lambda_v = parse_version(infra_version.lambda_version)
+            # Lambda update needed if client is newer (ignoring prerelease for comparison)
+            client_release = ParsedVersion(client.major, client.minor, client.patch)
+            lambda_release = ParsedVersion(lambda_v.major, lambda_v.minor, lambda_v.patch)
+            requires_lambda_update = lambda_release < client_release
+        except ValueError:
+            # If Lambda version is invalid, suggest update
+            requires_lambda_update = True
+
+    if requires_lambda_update:
+        return CompatibilityResult(
+            is_compatible=True,  # Can still work, but update available
+            requires_lambda_update=True,
+            message=(
+                f"Lambda update available: {infra_version.lambda_version} -> {client_version}"
+            ),
+        )
+
+    # Fully compatible
+    return CompatibilityResult(
+        is_compatible=True,
+        message="Client and infrastructure versions are compatible.",
+    )
+
+
+def get_schema_version() -> str:
+    """Get the current schema version."""
+    return CURRENT_SCHEMA_VERSION