Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/protocol-installed-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
matrix:
os:
- ubuntu-24.04
- macos-14
- macos-15
- windows-2022
python:
- "3.11"
Expand Down
47 changes: 47 additions & 0 deletions src/stateforge_protocol/sfp/operation_admission/v1/contract.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
"""Expose the normative SFP Operation Admission v1 wire contract."""

from dataclasses import dataclass
from typing import Final

from stateforge_protocol.sfp.operation_admission.v1 import (
Expand All @@ -22,3 +23,49 @@

# Contract-context limits mirrored by the packaged validation schema.
MAX_REQUIRED_IMPLEMENTATION_ROLES: Final = 16


@dataclass(frozen=True, slots=True)
class AdmissionErrorContract:
"""Bind one structured rejection reason to its transport semantics."""

grpc_status: str
retryable: bool


def _reason(name: str) -> int:
return operation_admission_pb2.AdmissionErrorReason.Value(name)


ADMISSION_ERROR_CONTRACTS: Final = {
_reason("ADMISSION_ERROR_REASON_INVALID_OPERATION_REQUEST"): (
AdmissionErrorContract("INVALID_ARGUMENT", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_NOT_DECLARED"): (
AdmissionErrorContract("UNIMPLEMENTED", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_INCOMPATIBLE"): (
AdmissionErrorContract("FAILED_PRECONDITION", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_PRECONDITION_FAILED"): (
AdmissionErrorContract("FAILED_PRECONDITION", True)
),
_reason("ADMISSION_ERROR_REASON_PROVIDER_CAPACITY_EXHAUSTED"): (
AdmissionErrorContract("RESOURCE_EXHAUSTED", True)
),
_reason("ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE"): (
AdmissionErrorContract("UNAVAILABLE", True)
),
_reason("ADMISSION_ERROR_REASON_IDEMPOTENCY_CONFLICT"): (
AdmissionErrorContract("ALREADY_EXISTS", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_DEADLINE_EXPIRED"): (
AdmissionErrorContract("DEADLINE_EXCEEDED", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_RECORD_UNAVAILABLE"): (
AdmissionErrorContract("FAILED_PRECONDITION", False)
),
_reason("ADMISSION_ERROR_REASON_OPERATION_RECORD_EXPIRED"): (
AdmissionErrorContract("FAILED_PRECONDITION", False)
),
}
25 changes: 25 additions & 0 deletions src/stateforge_protocol/sfp/operation_admission/v1/validation.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
"validate_admission_error_detail",
"validate_admission_exchange",
"validate_admission_record",
"validate_admission_rejection",
"validate_start_operation_request",
"validate_start_operation_response",
]
Expand Down Expand Up @@ -147,6 +148,30 @@ def validate_admission_error_detail(
)


def validate_admission_rejection(
detail: operation_admission_pb2.OperationAdmissionErrorDetail,
*,
grpc_status: str,
) -> None:
"""Validate structured rejection detail and its gRPC status together."""
validate_admission_error_detail(detail)
error_contract = contract.ADMISSION_ERROR_CONTRACTS.get(detail.reason)
if error_contract is None:
raise OperationAdmissionValidationError(
"error: reason has no canonical rejection contract"
)
_VALIDATION.require_equal(
grpc_status,
error_contract.grpc_status,
"error: gRPC status does not match reason",
)
_VALIDATION.require_equal(
detail.retryable,
error_contract.retryable,
"error: retryable does not match reason",
)


def validate_admission_exchange(
request: operation_admission_pb2.StartOperationRequest,
response: operation_admission_pb2.StartOperationResponse,
Expand Down
62 changes: 62 additions & 0 deletions tests/test_operation_admission_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,21 @@ def test_error_fixture_covers_every_reason_and_creates_no_record() -> None:
"UNAVAILABLE",
"UNIMPLEMENTED",
}
assert set(contract.ADMISSION_ERROR_CONTRACTS) == {
value.number
for value in (
operation_admission_pb2.AdmissionErrorReason.DESCRIPTOR.values
)
if value.number != 0
}

for case in cases:
reason = operation_admission_pb2.AdmissionErrorReason.Value(
case["reason"]
)
error_contract = contract.ADMISSION_ERROR_CONTRACTS[reason]
assert error_contract.grpc_status == case["grpcStatus"]
assert error_contract.retryable is case["retryable"]


@pytest.mark.parametrize("case", _read_json("error-cases.json"))
Expand All @@ -484,6 +499,10 @@ def test_error_detail_round_trips_for_every_documented_case(case) -> None:
operation_admission_pb2.OperationAdmissionErrorDetail(),
)
admission_validation.validate_admission_error_detail(message)
admission_validation.validate_admission_rejection(
message,
grpc_status=case["grpcStatus"],
)
projected = json_format.MessageToDict(
message,
always_print_fields_with_no_presence=True,
Expand All @@ -492,6 +511,49 @@ def test_error_detail_round_trips_for_every_documented_case(case) -> None:
assert projected == detail


def test_rejection_rejects_status_that_does_not_match_reason() -> None:
detail = json_format.ParseDict(
{
"operationId": "22222222-2222-4222-8222-222222222222",
"reason": "ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE",
"retryable": True,
"retryAfter": "5s",
"explanation": "Provider is temporarily unavailable.",
},
operation_admission_pb2.OperationAdmissionErrorDetail(),
)

with pytest.raises(
admission_validation.OperationAdmissionValidationError,
match="gRPC status does not match reason",
):
admission_validation.validate_admission_rejection(
detail,
grpc_status="FAILED_PRECONDITION",
)


def test_rejection_rejects_retryable_that_does_not_match_reason() -> None:
detail = json_format.ParseDict(
{
"operationId": "22222222-2222-4222-8222-222222222222",
"reason": "ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE",
"retryable": False,
"explanation": "Provider is temporarily unavailable.",
},
operation_admission_pb2.OperationAdmissionErrorDetail(),
)

with pytest.raises(
admission_validation.OperationAdmissionValidationError,
match="retryable does not match reason",
):
admission_validation.validate_admission_rejection(
detail,
grpc_status="UNAVAILABLE",
)


def test_retry_after_is_forbidden_for_non_retryable_error() -> None:
detail = {
"operationId": "22222222-2222-4222-8222-222222222222",
Expand Down
Loading