tigrbl_spec 0.4.2.dev4__py3-none-any.whl → 0.4.3.dev4__py3-none-any.whl

tigrbl_spec/__init__.py

@@ -1,5 +1,44 @@
-"""tigrbl_spec package."""
+"""Tigrbl specification schema catalog and bindings."""
 
-__all__ = ["__version__"]
+from .schema import (
+    CURRENT_SCHEMA_VERSION,
+    SCHEMA_VERSION,
+    SpecSchemaError,
+    SpecValidationError,
+    UnknownSpecKindError,
+    UnsupportedSchemaVersionError,
+    identity_fields,
+    load_bundle,
+    load_manifest,
+    load_payload,
+    load_schema,
+    schema_path,
+    schema_versions,
+    spec_kinds,
+    spec_type,
+    validate_payload,
+    with_identity,
+)
+
+__all__ = [
+    "__version__",
+    "CURRENT_SCHEMA_VERSION",
+    "SCHEMA_VERSION",
+    "SpecSchemaError",
+    "SpecValidationError",
+    "UnknownSpecKindError",
+    "UnsupportedSchemaVersionError",
+    "identity_fields",
+    "load_bundle",
+    "load_manifest",
+    "load_payload",
+    "load_schema",
+    "schema_path",
+    "schema_versions",
+    "spec_kinds",
+    "spec_type",
+    "validate_payload",
+    "with_identity",
+]
 
 __version__ = "0.4.0.dev1"

tigrbl_spec/codegen.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+from tigrbl_spec.schema import CURRENT_SCHEMA_VERSION, spec_kinds
+
+
+class CodegenFreshnessError(AssertionError):
+    """Raised when checked-in generated models do not match packaged schemas."""
+
+
+def generated_module_name(version: str = CURRENT_SCHEMA_VERSION) -> str:
+    normalized = version.replace(".", "_")
+    return f"tigrbl_spec.models.v{normalized}"
+
+
+def check_generated_model_freshness(version: str = CURRENT_SCHEMA_VERSION) -> None:
+    module = import_module(generated_module_name(version))
+    expected = set(spec_kinds(version))
+    actual = {name for name in getattr(module, "__all__", ()) if name != "SpecDataclass"}
+    missing = sorted(expected - actual)
+    extra = sorted(actual - expected)
+    if missing or extra:
+        raise CodegenFreshnessError(
+            f"Generated tigrbl_spec dataclasses are stale for {version}: "
+            f"missing={missing}, extra={extra}"
+        )

tigrbl_spec/migrations/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from tigrbl_spec.schema import CURRENT_SCHEMA_VERSION, UnsupportedSchemaVersionError, schema_versions
+
+SUPPORTED_SCHEMA_VERSIONS = schema_versions()
+
+
+class SchemaMigrationError(ValueError):
+    """Raised when no valid schema catalog migration path exists."""
+
+
+def migration_path(
+    from_version: str,
+    to_version: str = CURRENT_SCHEMA_VERSION,
+) -> tuple[str, ...]:
+    if from_version not in SUPPORTED_SCHEMA_VERSIONS:
+        raise UnsupportedSchemaVersionError(f"Unsupported source schema version {from_version!r}")
+    if to_version not in SUPPORTED_SCHEMA_VERSIONS:
+        raise UnsupportedSchemaVersionError(f"Unsupported target schema version {to_version!r}")
+    if from_version == to_version:
+        return (from_version,)
+    versions = list(SUPPORTED_SCHEMA_VERSIONS)
+    start = versions.index(from_version)
+    end = versions.index(to_version)
+    if end < start:
+        raise SchemaMigrationError(
+            f"Downgrade migrations are not supported: {from_version!r} -> {to_version!r}"
+        )
+    path = tuple(versions[start : end + 1])
+    if len(path) < 2:
+        raise SchemaMigrationError(f"No migration path from {from_version!r} to {to_version!r}")
+    return path
+
+
+def migrate_payload(
+    spec_kind: str,
+    payload: dict[str, Any],
+    from_version: str,
+    to_version: str = CURRENT_SCHEMA_VERSION,
+) -> dict[str, Any]:
+    path = migration_path(from_version, to_version)
+    migrated = copy.deepcopy(payload)
+    if len(path) == 1:
+        return migrated
+    raise SchemaMigrationError(
+        f"No adjacent migration implementation registered for {spec_kind!r}: "
+        f"{from_version!r} -> {to_version!r}"
+    )

tigrbl_spec/models/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from tigrbl_spec.models.v0_3_20 import *  # noqa: F403

tigrbl_spec/models/v0_3_20/__init__.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from typing_extensions import Self
+
+from tigrbl_spec.schema import CURRENT_SCHEMA_VERSION, identity_fields, spec_kinds, validate_payload
+
+
+@dataclass(slots=True)
+class SpecDataclass:
+    spec_kind: str
+    spec_schema_version: str
+    spec_type: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+    KIND: ClassVar[str]
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> Self:
+        validated = validate_payload(cls.KIND, payload, CURRENT_SCHEMA_VERSION)
+        identity = identity_fields(cls.KIND, CURRENT_SCHEMA_VERSION)
+        data = {key: value for key, value in validated.items() if key not in identity}
+        return cls(data=data, **identity)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "spec_kind": self.spec_kind,
+            "spec_schema_version": self.spec_schema_version,
+            "spec_type": self.spec_type,
+            **self.data,
+        }
+
+
+def _model_class(kind: str) -> type[SpecDataclass]:
+    return dataclass(slots=True)(
+        type(kind, (SpecDataclass,), {"KIND": kind, "__annotations__": {"KIND": ClassVar[str]}})
+    )
+
+
+for _kind in spec_kinds(CURRENT_SCHEMA_VERSION):
+    globals()[_kind] = _model_class(_kind)
+
+
+__all__ = ["SpecDataclass", *spec_kinds(CURRENT_SCHEMA_VERSION)]

tigrbl_spec/schema.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import copy
+import json
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, exceptions
+from referencing import Registry, Resource
+
+CURRENT_SCHEMA_VERSION = "0.3.20"
+SCHEMA_VERSION = CURRENT_SCHEMA_VERSION
+SPEC_TYPE_PREFIX = "urn:tigrbl:spec"
+
+
+class SpecSchemaError(ValueError):
+    """Base error for tigrbl_spec schema catalog failures."""
+
+
+class UnknownSpecKindError(SpecSchemaError):
+    """Raised when a payload references an unknown spec kind."""
+
+
+class UnsupportedSchemaVersionError(SpecSchemaError):
+    """Raised when a catalog version is not packaged or supported."""
+
+
+class SpecValidationError(SpecSchemaError):
+    """Raised when a spec payload does not satisfy its schema."""
+
+
+def spec_type(spec_kind: str, version: str = CURRENT_SCHEMA_VERSION) -> str:
+    return f"{SPEC_TYPE_PREFIX}:{spec_kind}:{version}"
+
+
+def identity_fields(spec_kind: str, version: str = CURRENT_SCHEMA_VERSION) -> dict[str, str]:
+    return {
+        "spec_kind": spec_kind,
+        "spec_schema_version": version,
+        "spec_type": spec_type(spec_kind, version),
+    }
+
+
+def schemas_root() -> resources.abc.Traversable:
+    return resources.files("tigrbl_spec").joinpath("schemas")
+
+
+def schema_versions() -> tuple[str, ...]:
+    versions = [
+        item.name
+        for item in schemas_root().iterdir()
+        if item.is_dir() and item.joinpath("manifest.json").is_file()
+    ]
+    return tuple(sorted(versions))
+
+
+def _require_version(version: str) -> None:
+    if version not in schema_versions():
+        raise UnsupportedSchemaVersionError(
+            f"Unsupported tigrbl_spec schema catalog version {version!r}; "
+            f"available versions: {', '.join(schema_versions()) or '<none>'}"
+        )
+
+
+@lru_cache(maxsize=None)
+def _load_json_file(version: str, filename: str) -> dict[str, Any]:
+    _require_version(version)
+    path = schemas_root().joinpath(version, filename)
+    if not path.is_file():
+        raise FileNotFoundError(f"Schema catalog file not found: {version}/{filename}")
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def load_manifest(version: str = CURRENT_SCHEMA_VERSION) -> dict[str, Any]:
+    return copy.deepcopy(_load_json_file(version, "manifest.json"))
+
+
+def load_bundle(version: str = CURRENT_SCHEMA_VERSION) -> dict[str, Any]:
+    return copy.deepcopy(_load_json_file(version, "bundle.json"))
+
+
+def spec_kinds(version: str = CURRENT_SCHEMA_VERSION) -> tuple[str, ...]:
+    manifest = load_manifest(version)
+    return tuple(sorted((manifest.get("schemas") or {}).keys()))
+
+
+def schema_path(spec_kind: str, version: str = CURRENT_SCHEMA_VERSION) -> Path:
+    if spec_kind not in spec_kinds(version):
+        raise UnknownSpecKindError(f"Unknown tigrbl_spec kind {spec_kind!r}")
+    return Path(str(schemas_root().joinpath(version, f"{spec_kind}.json")))
+
+
+def load_schema(spec_kind: str, version: str = CURRENT_SCHEMA_VERSION) -> dict[str, Any]:
+    if spec_kind not in spec_kinds(version):
+        raise UnknownSpecKindError(f"Unknown tigrbl_spec kind {spec_kind!r}")
+    return copy.deepcopy(_load_json_file(version, f"{spec_kind}.json"))
+
+
+def with_identity(
+    spec_kind: str,
+    payload: dict[str, Any],
+    version: str = CURRENT_SCHEMA_VERSION,
+) -> dict[str, Any]:
+    identified = dict(payload)
+    identified.update(identity_fields(spec_kind, version))
+    return identified
+
+
+def _identity_version(payload: dict[str, Any]) -> str:
+    value = payload.get("spec_schema_version")
+    if not isinstance(value, str):
+        raise SpecValidationError("Spec payload must include string spec_schema_version")
+    return value
+
+
+def _validate_identity(spec_kind: str, payload: dict[str, Any], version: str) -> None:
+    expected = identity_fields(spec_kind, version)
+    for field, expected_value in expected.items():
+        actual = payload.get(field)
+        if actual != expected_value:
+            raise SpecValidationError(
+                f"Spec payload identity field {field!r} must be {expected_value!r}; got {actual!r}"
+            )
+
+
+@lru_cache(maxsize=None)
+def _registry(version: str) -> Registry:
+    _require_version(version)
+    base_uri = f"urn:tigrbl:spec:schema-catalog:{version}/"
+    pairs = []
+    manifest = load_manifest(version)
+    filenames = ["shared.json", *(manifest.get("schemas") or {}).values()]
+    for filename in filenames:
+        schema = _load_json_file(version, filename)
+        pairs.append((base_uri + filename, Resource.from_contents(schema)))
+    return Registry().with_resources(pairs)
+
+
+@lru_cache(maxsize=None)
+def _validator(spec_kind: str, version: str) -> Draft202012Validator:
+    schema = load_schema(spec_kind, version)
+    base_uri = f"urn:tigrbl:spec:schema-catalog:{version}/"
+    return Draft202012Validator(schema, registry=_registry(version), _resolver=None).evolve(
+        schema={**schema, "$id": base_uri + f"{spec_kind}.json"}
+    )
+
+
+def validate_payload(
+    spec_kind: str,
+    payload: dict[str, Any],
+    version: str | None = None,
+) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise SpecValidationError("Spec payload must be a JSON object")
+    resolved_version = version or _identity_version(payload)
+    _require_version(resolved_version)
+    if spec_kind not in spec_kinds(resolved_version):
+        raise UnknownSpecKindError(f"Unknown tigrbl_spec kind {spec_kind!r}")
+    _validate_identity(spec_kind, payload, resolved_version)
+    try:
+        _validator(spec_kind, resolved_version).validate(payload)
+    except exceptions.ValidationError as exc:
+        location = ".".join(str(part) for part in exc.absolute_path)
+        prefix = f"{spec_kind} payload"
+        if location:
+            prefix = f"{prefix} at {location}"
+        raise SpecValidationError(f"{prefix} failed schema validation: {exc.message}") from exc
+    return copy.deepcopy(payload)
+
+
+def load_payload(
+    spec_kind: str,
+    payload: dict[str, Any],
+    *,
+    migrate: bool = False,
+    to_version: str = CURRENT_SCHEMA_VERSION,
+) -> dict[str, Any]:
+    from tigrbl_spec.migrations import migrate_payload
+
+    version = _identity_version(payload)
+    loaded = migrate_payload(spec_kind, payload, version, to_version) if migrate else payload
+    return validate_payload(spec_kind, loaded, to_version if migrate else version)
+
+
+INDIVIDUAL_SPEC_NAMES = spec_kinds(CURRENT_SCHEMA_VERSION)
+JSON_SCHEMA_DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+SHARED_SCHEMA_NAME = "shared.json"
+
+
+def build_shared_json_schema() -> dict[str, Any]:
+    return _load_json_file(CURRENT_SCHEMA_VERSION, SHARED_SCHEMA_NAME)
+
+
+def build_individual_spec_json_schemas() -> dict[str, dict[str, Any]]:
+    return {kind: load_schema(kind) for kind in INDIVIDUAL_SPEC_NAMES}
+
+
+def build_spec_json_schema_bundle() -> dict[str, Any]:
+    return load_manifest()

tigrbl_spec/schemas/0.3.20/AppSpec.json

@@ -0,0 +1,146 @@
+{
+  "$defs": {
+    "AppSpecEnvelope": {
+      "additionalProperties": {
+        "$ref": "./shared.json#/$defs/SerdeValue"
+      },
+      "properties": {
+        "__dataclass__": {
+          "const": "tigrbl_core._spec.app_spec:AppSpec"
+        }
+      },
+      "required": [
+        "__dataclass__"
+      ],
+      "title": "AppSpecEnvelope",
+      "type": "object"
+    }
+  },
+  "$id": "AppSpec.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "deps": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "description": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "engine": {
+      "anyOf": [
+        {
+          "$ref": "./shared.json#/$defs/SerdeValue"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "execution_backend": {
+      "type": "string"
+    },
+    "hooks": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "jsonrpc_prefix": {
+      "type": "string"
+    },
+    "lifespan": {
+      "anyOf": [
+        {
+          "$ref": "./shared.json#/$defs/SerdeValue"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "middlewares": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "ops": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "response": {
+      "anyOf": [
+        {
+          "anyOf": [
+            {
+              "$ref": "./ResponseSpec.json"
+            },
+            {
+              "$ref": "./ResponseSpec.json#/$defs/ResponseSpecEnvelope"
+            }
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "routers": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "schemas": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "security_deps": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "spec_kind": {
+      "const": "AppSpec",
+      "description": "Tigrbl spec payload kind."
+    },
+    "spec_schema_version": {
+      "const": "0.3.20",
+      "description": "Tigrbl spec schema catalog version."
+    },
+    "spec_type": {
+      "const": "urn:tigrbl:spec:AppSpec:0.3.20",
+      "description": "Versioned Tigrbl spec type URN."
+    },
+    "system_prefix": {
+      "type": "string"
+    },
+    "tables": {
+      "$ref": "./shared.json#/$defs/StepFnTuple"
+    },
+    "title": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "spec_kind",
+    "spec_schema_version",
+    "spec_type",
+    "title",
+    "description",
+    "version",
+    "execution_backend",
+    "engine",
+    "routers",
+    "ops",
+    "tables",
+    "schemas",
+    "hooks",
+    "security_deps",
+    "deps",
+    "response",
+    "jsonrpc_prefix",
+    "system_prefix",
+    "middlewares",
+    "lifespan"
+  ],
+  "title": "AppSpec",
+  "type": "object"
+}

tigrbl_spec/schemas/0.3.20/BindingRegistrySpec.json

@@ -0,0 +1,57 @@
+{
+  "$defs": {
+    "BindingRegistrySpecEnvelope": {
+      "additionalProperties": {
+        "$ref": "./shared.json#/$defs/SerdeValue"
+      },
+      "properties": {
+        "__dataclass__": {
+          "const": "tigrbl_core._spec.binding_spec:BindingRegistrySpec"
+        }
+      },
+      "required": [
+        "__dataclass__"
+      ],
+      "title": "BindingRegistrySpecEnvelope",
+      "type": "object"
+    }
+  },
+  "$id": "BindingRegistrySpec.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "_bindings": {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "./BindingSpec.json"
+          },
+          {
+            "$ref": "./BindingSpec.json#/$defs/BindingSpecEnvelope"
+          }
+        ]
+      },
+      "type": "object"
+    },
+    "spec_kind": {
+      "const": "BindingRegistrySpec",
+      "description": "Tigrbl spec payload kind."
+    },
+    "spec_schema_version": {
+      "const": "0.3.20",
+      "description": "Tigrbl spec schema catalog version."
+    },
+    "spec_type": {
+      "const": "urn:tigrbl:spec:BindingRegistrySpec:0.3.20",
+      "description": "Versioned Tigrbl spec type URN."
+    }
+  },
+  "required": [
+    "spec_kind",
+    "spec_schema_version",
+    "spec_type",
+    "_bindings"
+  ],
+  "title": "BindingRegistrySpec",
+  "type": "object"
+}

tigrbl_spec/schemas/0.3.20/BindingSpec.json

@@ -0,0 +1,51 @@
+{
+  "$defs": {
+    "BindingSpecEnvelope": {
+      "additionalProperties": {
+        "$ref": "./shared.json#/$defs/SerdeValue"
+      },
+      "properties": {
+        "__dataclass__": {
+          "const": "tigrbl_core._spec.binding_spec:BindingSpec"
+        }
+      },
+      "required": [
+        "__dataclass__"
+      ],
+      "title": "BindingSpecEnvelope",
+      "type": "object"
+    }
+  },
+  "$id": "BindingSpec.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "spec": {
+      "$ref": "./shared.json#/$defs/TransportBindingSpec"
+    },
+    "spec_kind": {
+      "const": "BindingSpec",
+      "description": "Tigrbl spec payload kind."
+    },
+    "spec_schema_version": {
+      "const": "0.3.20",
+      "description": "Tigrbl spec schema catalog version."
+    },
+    "spec_type": {
+      "const": "urn:tigrbl:spec:BindingSpec:0.3.20",
+      "description": "Versioned Tigrbl spec type URN."
+    }
+  },
+  "required": [
+    "spec_kind",
+    "spec_schema_version",
+    "spec_type",
+    "name",
+    "spec"
+  ],
+  "title": "BindingSpec",
+  "type": "object"
+}