fix: 对齐多配置运行状态语义 (#149)

This commit is contained in:
QiuSW
2026-08-31 08:59:48 +08:00
parent 54c58551ae
commit a22d3ce0f1
18 changed files with 207 additions and 73 deletions
+1 -1
View File
@@ -6,4 +6,4 @@
python -m unittest discover -s contracts/tests/runtime-status-v1 -p "test_*.py" -v
```
测试只使用 Python 标准库,不安装依赖、不访问网络。它对冻结 Schema 的已用关键字执行验证,并覆盖状态迁移、时间/陈旧边界、offline/recovery、配置 revision、未知主版本、倒序消息和敏感字段拒绝。产品 adapter 还需在各自工单中运行本地模型映射测试。
测试只使用 Python 标准库,不安装依赖、不访问网络。它对冻结 Schema 的已用关键字执行验证,并覆盖状态迁移、时间/陈旧边界、offline/recovery、空/多配置流、四种配置应用状态、重复 `config_id`、integer revision mismatch、未知主版本、倒序消息、回退保留和敏感字段拒绝。产品 adapter 还需在各自工单中运行本地模型映射测试。
@@ -124,6 +124,17 @@ def load(path):
return json.loads(path.read_text(encoding="utf-8"))
def validate_contract(instance):
errors = validate(instance)
configurations = instance.get("configurations") if isinstance(instance, dict) else None
if isinstance(configurations, list):
config_ids = [item.get("config_id") for item in configurations if isinstance(item, dict)]
duplicates = {config_id for config_id in config_ids if config_ids.count(config_id) > 1}
if duplicates:
errors.append(f"$.configurations: duplicate config_id {sorted(duplicates)!r}")
return errors
def freshness(observed_at, evaluation_time):
age = evaluation_time - parse_datetime(observed_at)
if age < timedelta(seconds=-30):
@@ -148,7 +159,7 @@ def may_transition(previous, current):
def may_replace(previous, candidate, evaluation_time):
if candidate["schema_version"] != "yovision.runtime-status/v1":
return False
if validate(candidate):
if validate_contract(candidate):
return False
if freshness(candidate["observed_at"], evaluation_time) == "future_rejected":
return False
@@ -168,29 +179,30 @@ class RuntimeStatusV1ContractTests(unittest.TestCase):
self.assertEqual(SCHEMA["$schema"], "https://json-schema.org/draft/2020-12/schema")
self.assertEqual(SCHEMA["properties"]["schema_version"]["const"], "yovision.runtime-status/v1")
self.assertFalse(SCHEMA["additionalProperties"])
for name in ("runtime", "model", "configuration", "health"):
for name in ("runtime", "model", "health"):
self.assertFalse(SCHEMA["properties"][name]["additionalProperties"])
self.assertFalse(SCHEMA["properties"]["configurations"]["items"]["additionalProperties"])
def test_all_valid_examples_satisfy_schema(self):
paths = sorted(VALID_DIR.glob("*.json"))
self.assertGreaterEqual(len(paths), 5)
self.assertGreaterEqual(len(paths), 7)
for path in paths:
with self.subTest(path=path.name):
self.assertEqual(validate(load(path)), [])
self.assertEqual(validate_contract(load(path)), [])
def test_all_invalid_examples_are_rejected(self):
paths = sorted(INVALID_DIR.glob("*.json"))
self.assertGreaterEqual(len(paths), 5)
self.assertGreaterEqual(len(paths), 6)
for path in paths:
with self.subTest(path=path.name):
self.assertNotEqual(validate(load(path)), [])
self.assertNotEqual(validate_contract(load(path)), [])
def test_every_runtime_state_is_schema_valid(self):
for state in ALLOWED_TRANSITIONS:
message = copy.deepcopy(self.running)
message["runtime"]["state"] = state
with self.subTest(state=state):
self.assertEqual(validate(message), [])
self.assertEqual(validate_contract(message), [])
def test_state_transition_matrix(self):
self.assertTrue(may_transition("unconfigured", "starting"))
@@ -224,47 +236,79 @@ class RuntimeStatusV1ContractTests(unittest.TestCase):
older = copy.deepcopy(self.running)
older["sequence"] = self.running["sequence"] - 1
self.assertFalse(may_replace(self.running, older, evaluation))
duplicate = load(INVALID_DIR / "duplicate-config-id.json")
self.assertFalse(may_replace(self.running, duplicate, parse_datetime(duplicate["observed_at"])))
def test_configuration_revision_mismatch_is_consumer_derived(self):
message = load(VALID_DIR / "config-mismatch.json")
desired_revision = "sense-rev-21"
self.assertEqual(validate(message), [])
self.assertNotEqual(message["configuration"]["applied_revision"], desired_revision)
self.assertNotIn("desired_revision", message["configuration"])
desired_revisions = {"gate-primary": 21}
self.assertEqual(validate_contract(message), [])
report = message["configurations"][0]
self.assertNotEqual(report["applied_revision"], desired_revisions[report["config_id"]])
self.assertNotIn("desired_revision", report)
def test_configuration_apply_state_invariants(self):
cases = [
("not_configured", "rev-forbidden", None),
("applied", None, None),
("rejected", "rev-old", None),
valid_cases = [
("not_configured", None, None),
("applying", None, None),
("applying", 1, None),
("applied", 1, None),
("rejected", None, "CONFIG_INVALID"),
("rejected", 1, "CONFIG_INVALID"),
]
for apply_state, revision, error_code in cases:
for apply_state, revision, error_code in valid_cases:
message = copy.deepcopy(self.running)
message["configuration"] = {
message["configurations"] = [{
"config_id": "gate-primary",
"apply_state": apply_state,
"applied_revision": revision,
"error_code": error_code,
}
}]
with self.subTest(apply_state=apply_state):
self.assertNotEqual(validate(message), [])
self.assertEqual(validate_contract(message), [])
invalid_cases = [
("not_configured", 1, None),
("applied", None, None),
("rejected", 1, None),
]
for apply_state, revision, error_code in invalid_cases:
message = copy.deepcopy(self.running)
message["configurations"] = [{
"config_id": "gate-primary",
"apply_state": apply_state,
"applied_revision": revision,
"error_code": error_code,
}]
with self.subTest(invalid_apply_state=apply_state):
self.assertNotEqual(validate_contract(message), [])
def test_empty_multiple_and_duplicate_configuration_streams(self):
empty = load(VALID_DIR / "empty-configurations.json")
multiple = load(VALID_DIR / "configuration-states.json")
duplicate = load(INVALID_DIR / "duplicate-config-id.json")
self.assertEqual(validate_contract(empty), [])
self.assertEqual(validate_contract(multiple), [])
self.assertEqual(len(multiple["configurations"]), 4)
self.assertTrue(any("duplicate config_id" in error for error in validate_contract(duplicate)))
def test_sensitive_and_business_fields_are_rejected_by_name(self):
for forbidden in ("access_token", "password", "credential", "internal_path", "stack", "user_session", "video", "face", "alert"):
message = copy.deepcopy(self.running)
message[forbidden] = "forbidden"
with self.subTest(forbidden=forbidden):
self.assertTrue(any("additional property" in error for error in validate(message)))
self.assertTrue(any("additional property" in error for error in validate_contract(message)))
def test_logical_references_reject_paths(self):
for value in ("C:\\models\\private.pt", "/srv/models/private.pt", "../private.pt"):
message = copy.deepcopy(self.running)
message["model"]["model_ref"] = value
with self.subTest(value=value):
self.assertNotEqual(validate(message), [])
self.assertNotEqual(validate_contract(message), [])
def test_mapper_responsibilities_are_documented(self):
mapping = (CONTRACT_DIR / "mapping.md").read_text(encoding="utf-8")
for field in ("schema_version", "status_id", "brain_instance_ref", "sequence", "observed_at", "runtime.*", "model.*", "configuration.*", "health.*", "inputs[]"):
for field in ("schema_version", "status_id", "brain_instance_ref", "sequence", "observed_at", "runtime.*", "model.*", "configurations[]", "health.*", "inputs[]"):
self.assertIn(f"`{field}`", mapping)
self.assertIn("Brain", mapping)
self.assertIn("Sense", mapping)