Add Python CultNet schema catalog facade
This commit is contained in:
parent
828947a188
commit
c47b84560e
6 changed files with 217 additions and 2 deletions
|
|
@ -17,7 +17,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti.
|
|||
- Python CultNet schema catalog:
|
||||
Exposes shared wire-message schema descriptors from the package surface so
|
||||
both the interop peer and CultMesh local server describe the CultNet/CultMesh
|
||||
messages they speak through the same catalog authority.
|
||||
messages they speak through the same catalog authority. Python callers can
|
||||
also ingest and filter remote schema catalog responses through typed
|
||||
`CultNetSchemaCatalog` and `CultNetSchemaDescriptor` helpers, including
|
||||
`CultNetRawClient.sync_schema_catalog(...)`.
|
||||
- Python CultMesh discovery client:
|
||||
Fetches Verse catalogs and peer exchange responses from the live Python
|
||||
endpoint over CultNet frames.
|
||||
|
|
|
|||
|
|
@ -32,6 +32,8 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
|
|||
"CultNetDatabaseSubscription",
|
||||
"CultNetMessage",
|
||||
"CultNetRawClient",
|
||||
"CultNetSchemaCatalog",
|
||||
"CultNetSchemaDescriptor",
|
||||
"CultNetSimulationConsensus",
|
||||
"CultNetSimulationConsensusOptions",
|
||||
"CultNetSimulationObservationHub",
|
||||
|
|
@ -58,6 +60,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
|
|||
"simulation_observation",
|
||||
"snapshot_request",
|
||||
"wire_message_schema_descriptors",
|
||||
"wire_message_schema_catalog",
|
||||
"wire_message_schema_json",
|
||||
"witness_artifact_bundle",
|
||||
"write_frame",
|
||||
|
|
|
|||
|
|
@ -27,8 +27,11 @@ from .replication import (
|
|||
schema_document_map,
|
||||
)
|
||||
from .schema_catalog import (
|
||||
CultNetSchemaCatalog,
|
||||
CultNetSchemaDescriptor,
|
||||
INTEROP_WIRE_CONTRACT,
|
||||
wire_message_schema_descriptors,
|
||||
wire_message_schema_catalog,
|
||||
wire_message_schema_json,
|
||||
)
|
||||
from .simulation import (
|
||||
|
|
@ -41,6 +44,8 @@ __all__ = [
|
|||
"CultNetMessage",
|
||||
"CultNetDatabaseSubscription",
|
||||
"CultNetRawClient",
|
||||
"CultNetSchemaCatalog",
|
||||
"CultNetSchemaDescriptor",
|
||||
"CultNetAppliedRecord",
|
||||
"CultNetClientAuthorityScope",
|
||||
"CultNetSimulationConsensus",
|
||||
|
|
@ -69,6 +74,7 @@ __all__ = [
|
|||
"simulation_observation",
|
||||
"snapshot_request",
|
||||
"wire_message_schema_descriptors",
|
||||
"wire_message_schema_catalog",
|
||||
"wire_message_schema_json",
|
||||
"witness_artifact_bundle",
|
||||
"write_frame",
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ from .messages import (
|
|||
shard_log_request,
|
||||
snapshot_request,
|
||||
)
|
||||
from .schema_catalog import CultNetSchemaCatalog, CultNetSchemaDescriptor
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
|
@ -57,6 +58,39 @@ class CultNetRawClient:
|
|||
expected_schema_version="cultnet.schema_catalog_response.v0",
|
||||
)
|
||||
|
||||
def fetch_schema_descriptors(
|
||||
self,
|
||||
*,
|
||||
message_id: str = "cultnet-python-schema-catalog",
|
||||
include_schema_json: bool = False,
|
||||
schema_ids: list[str] | None = None,
|
||||
kinds: list[str] | None = None,
|
||||
) -> list[CultNetSchemaDescriptor]:
|
||||
response = self.fetch_schema_catalog(
|
||||
message_id=message_id,
|
||||
include_schema_json=include_schema_json,
|
||||
schema_ids=schema_ids,
|
||||
kinds=kinds,
|
||||
)
|
||||
return CultNetSchemaCatalog().apply_response(response)
|
||||
|
||||
def sync_schema_catalog(
|
||||
self,
|
||||
catalog: CultNetSchemaCatalog,
|
||||
*,
|
||||
message_id: str = "cultnet-python-schema-catalog",
|
||||
include_schema_json: bool = False,
|
||||
schema_ids: list[str] | None = None,
|
||||
kinds: list[str] | None = None,
|
||||
) -> list[CultNetSchemaDescriptor]:
|
||||
response = self.fetch_schema_catalog(
|
||||
message_id=message_id,
|
||||
include_schema_json=include_schema_json,
|
||||
schema_ids=schema_ids,
|
||||
kinds=kinds,
|
||||
)
|
||||
return catalog.apply_response(response)
|
||||
|
||||
def fetch_snapshot(
|
||||
self,
|
||||
*,
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@ from __future__ import annotations
|
|||
|
||||
import hashlib
|
||||
import json
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
INTEROP_WIRE_CONTRACT = "cultnet.schema.v0"
|
||||
|
|
@ -33,6 +34,110 @@ WIRE_MESSAGE_SCHEMA_VERSIONS = (
|
|||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CultNetSchemaDescriptor:
|
||||
schema_id: str
|
||||
kind: str
|
||||
schema_version: str | None = None
|
||||
document_type: str | None = None
|
||||
title: str | None = None
|
||||
wire_contracts: tuple[str, ...] = ()
|
||||
content_hash: str | None = None
|
||||
schema_json: str | None = None
|
||||
|
||||
@classmethod
|
||||
def from_wire(cls, value: dict[str, Any]) -> "CultNetSchemaDescriptor":
|
||||
schema_id = str(value.get("schemaId") or "")
|
||||
kind = str(value.get("kind") or "")
|
||||
if not schema_id:
|
||||
raise ValueError("schema descriptor schemaId must be non-empty")
|
||||
if not kind:
|
||||
raise ValueError("schema descriptor kind must be non-empty")
|
||||
return cls(
|
||||
schema_id=schema_id,
|
||||
kind=kind,
|
||||
schema_version=_optional_string(value.get("schemaVersion")),
|
||||
document_type=_optional_string(value.get("documentType")),
|
||||
title=_optional_string(value.get("title")),
|
||||
wire_contracts=tuple(str(contract) for contract in value.get("wireContracts") or []),
|
||||
content_hash=_optional_string(value.get("contentHash")),
|
||||
schema_json=_optional_string(value.get("schemaJson")),
|
||||
)
|
||||
|
||||
def to_wire(self, *, include_schema_json: bool | None = None) -> dict[str, Any]:
|
||||
wire: dict[str, Any] = {
|
||||
"schemaId": self.schema_id,
|
||||
"kind": self.kind,
|
||||
"wireContracts": list(self.wire_contracts),
|
||||
}
|
||||
if self.schema_version is not None:
|
||||
wire["schemaVersion"] = self.schema_version
|
||||
if self.document_type is not None:
|
||||
wire["documentType"] = self.document_type
|
||||
if self.title is not None:
|
||||
wire["title"] = self.title
|
||||
if self.content_hash is not None:
|
||||
wire["contentHash"] = self.content_hash
|
||||
if self.schema_json is not None and include_schema_json is not False:
|
||||
wire["schemaJson"] = self.schema_json
|
||||
return wire
|
||||
|
||||
|
||||
@dataclass
|
||||
class CultNetSchemaCatalog:
|
||||
_descriptors: dict[str, CultNetSchemaDescriptor] = field(default_factory=dict)
|
||||
|
||||
def upsert(self, descriptor: CultNetSchemaDescriptor | dict[str, Any]) -> CultNetSchemaDescriptor:
|
||||
value = descriptor if isinstance(descriptor, CultNetSchemaDescriptor) else CultNetSchemaDescriptor.from_wire(descriptor)
|
||||
self._descriptors[value.schema_id] = value
|
||||
return value
|
||||
|
||||
def get(self, schema_id: str) -> CultNetSchemaDescriptor | None:
|
||||
return self._descriptors.get(schema_id)
|
||||
|
||||
def list(
|
||||
self,
|
||||
*,
|
||||
schema_ids: list[str] | None = None,
|
||||
kinds: list[str] | None = None,
|
||||
) -> list[CultNetSchemaDescriptor]:
|
||||
requested_schema_ids = set(schema_ids or [])
|
||||
requested_kinds = set(kinds or [])
|
||||
return [
|
||||
descriptor
|
||||
for descriptor in sorted(self._descriptors.values(), key=lambda item: item.schema_id)
|
||||
if (not requested_schema_ids or descriptor.schema_id in requested_schema_ids)
|
||||
and (not requested_kinds or descriptor.kind in requested_kinds)
|
||||
]
|
||||
|
||||
def apply_response(self, response: dict[str, Any]) -> list[CultNetSchemaDescriptor]:
|
||||
if response.get("schemaVersion") != "cultnet.schema_catalog_response.v0":
|
||||
raise ValueError(f"Expected cultnet.schema_catalog_response.v0, received {response.get('schemaVersion')!r}")
|
||||
applied = []
|
||||
for descriptor in response.get("schemas") or []:
|
||||
if not isinstance(descriptor, dict):
|
||||
continue
|
||||
applied.append(self.upsert(descriptor))
|
||||
return applied
|
||||
|
||||
def create_response(
|
||||
self,
|
||||
*,
|
||||
message_id: str = "",
|
||||
include_schema_json: bool = False,
|
||||
schema_ids: list[str] | None = None,
|
||||
kinds: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
return {
|
||||
"schemaVersion": "cultnet.schema_catalog_response.v0",
|
||||
"messageId": message_id,
|
||||
"schemas": [
|
||||
descriptor.to_wire(include_schema_json=include_schema_json)
|
||||
for descriptor in self.list(schema_ids=schema_ids, kinds=kinds)
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def wire_message_schema_descriptors(include_schema_json: bool) -> list[dict[str, Any]]:
|
||||
descriptors = []
|
||||
for schema_version, title, schema_id in WIRE_MESSAGE_SCHEMA_VERSIONS:
|
||||
|
|
@ -51,6 +156,13 @@ def wire_message_schema_descriptors(include_schema_json: bool) -> list[dict[str,
|
|||
return descriptors
|
||||
|
||||
|
||||
def wire_message_schema_catalog(*, include_schema_json: bool = True) -> CultNetSchemaCatalog:
|
||||
catalog = CultNetSchemaCatalog()
|
||||
for descriptor in wire_message_schema_descriptors(include_schema_json):
|
||||
catalog.upsert(descriptor)
|
||||
return catalog
|
||||
|
||||
|
||||
def wire_message_schema_json(schema_id: str, title: str, schema_version: str) -> str:
|
||||
properties = {
|
||||
"schemaVersion": {"const": schema_version},
|
||||
|
|
@ -296,3 +408,10 @@ def wire_message_shared_defs() -> dict[str, Any]:
|
|||
"verseDescriptor": {"type": "object"},
|
||||
"peerCard": {"type": "object"},
|
||||
}
|
||||
|
||||
|
||||
def _optional_string(value: Any) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
text = str(value)
|
||||
return text if text else None
|
||||
|
|
|
|||
|
|
@ -24,6 +24,8 @@ from cultnet_py import (
|
|||
compute_simulation_claim_hash,
|
||||
CultNetClientAuthorityScope,
|
||||
CultNetRawClient,
|
||||
CultNetSchemaCatalog,
|
||||
CultNetSchemaDescriptor,
|
||||
CultNetSimulationConsensusOptions,
|
||||
apply_raw_snapshot,
|
||||
apply_shard_log_response,
|
||||
|
|
@ -42,9 +44,10 @@ from cultnet_py import (
|
|||
shard_log_request,
|
||||
simulation_observation,
|
||||
snapshot_request,
|
||||
wire_message_schema_catalog,
|
||||
wire_message_schema_descriptors,
|
||||
witness_artifact_bundle,
|
||||
)
|
||||
from cultnet_py import wire_message_schema_descriptors
|
||||
from cultmesh_py import create_node
|
||||
from cultmesh_py import (
|
||||
CultMesh,
|
||||
|
|
@ -835,6 +838,45 @@ class CultCacheTests(unittest.TestCase):
|
|||
for required_field in ["witnessCount", "supportWeight", "totalWeight", "hasQuorum", "confidence"]:
|
||||
self.assertIn(required_field, consensus_schema["required"])
|
||||
|
||||
def test_cultnet_schema_catalog_applies_filters_and_responses(self) -> None:
|
||||
catalog = wire_message_schema_catalog(include_schema_json=True)
|
||||
descriptor = catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json")
|
||||
self.assertIsNotNone(descriptor)
|
||||
assert descriptor is not None
|
||||
self.assertEqual(descriptor.kind, "wire_message")
|
||||
self.assertEqual(descriptor.schema_version, "cultnet.document_put_raw.v0")
|
||||
self.assertIsNotNone(descriptor.schema_json)
|
||||
|
||||
filtered = catalog.list(kinds=["wire_message"], schema_ids=[descriptor.schema_id])
|
||||
self.assertEqual(filtered, [descriptor])
|
||||
|
||||
response = catalog.create_response(
|
||||
message_id="catalog-response",
|
||||
include_schema_json=False,
|
||||
schema_ids=[descriptor.schema_id],
|
||||
kinds=["wire_message"],
|
||||
)
|
||||
self.assertEqual(response["schemaVersion"], "cultnet.schema_catalog_response.v0")
|
||||
self.assertNotIn("schemaJson", response["schemas"][0])
|
||||
|
||||
remote = CultNetSchemaCatalog()
|
||||
applied = remote.apply_response({
|
||||
"schemaVersion": "cultnet.schema_catalog_response.v0",
|
||||
"messageId": "remote",
|
||||
"schemas": [
|
||||
CultNetSchemaDescriptor(
|
||||
schema_id="schema:custom",
|
||||
kind="shared_contract",
|
||||
schema_version="custom.v0",
|
||||
wire_contracts=("cultnet.schema.v0",),
|
||||
content_hash="hash",
|
||||
schema_json="{}",
|
||||
).to_wire()
|
||||
],
|
||||
})
|
||||
self.assertEqual(applied[0].schema_id, "schema:custom")
|
||||
self.assertEqual(remote.get("schema:custom"), applied[0])
|
||||
|
||||
def test_cultnet_shard_helpers_match_schema_v0_shape(self) -> None:
|
||||
catalog = shard_catalog_request(
|
||||
message_id="catalog-1",
|
||||
|
|
@ -1658,6 +1700,12 @@ class CultCacheTests(unittest.TestCase):
|
|||
hello_response = raw_client.request(hello(runtime_id="probe"), expected_schema_version="cultnet.hello.v0")
|
||||
schema_response = raw_client.fetch_schema_catalog(schema_ids=["mesh.server_note.v1"], include_schema_json=True)
|
||||
wire_schema_response = raw_client.fetch_schema_catalog(kinds=["wire_message"], include_schema_json=True)
|
||||
synced_schema_catalog = CultNetSchemaCatalog()
|
||||
synced_wire_descriptors = raw_client.sync_schema_catalog(
|
||||
synced_schema_catalog,
|
||||
kinds=["wire_message"],
|
||||
include_schema_json=True,
|
||||
)
|
||||
snapshot_response = raw_client.fetch_snapshot(schema_ids=["mesh.server_note.v1"])
|
||||
shard_catalog = raw_client.fetch_shard_catalog(schema_ids=["mesh.server_note.v1"])
|
||||
shard_log = raw_client.fetch_shard_log(shard_id="primary", shard_epoch=1)
|
||||
|
|
@ -1697,6 +1745,8 @@ class CultCacheTests(unittest.TestCase):
|
|||
self.assertEqual(wire_descriptors["cultnet.document_put_raw.v0"]["kind"], "wire_message")
|
||||
self.assertIn("schemaJson", wire_descriptors["cultnet.document_put_raw.v0"])
|
||||
self.assertIn("cultmesh.peer_exchange_response.v0", wire_descriptors)
|
||||
self.assertIn("cultnet.document_put_raw.v0", {descriptor.schema_version for descriptor in synced_wire_descriptors})
|
||||
self.assertIsNotNone(synced_schema_catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json"))
|
||||
self.assertEqual(snapshot_response["documents"][0]["recordKey"], "note:1")
|
||||
self.assertEqual(shard_catalog["shards"][0]["schemaIds"], ["mesh.server_note.v1"])
|
||||
self.assertEqual(shard_log["entries"][0]["changeKind"], "added")
|
||||
|
|
|
|||
Loading…
Reference in a new issue