Hare/wip-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: align protocol error semantics

Browse Source
This commit is contained in:
Hare
2026-09-30 05:26:34 +09:00
parent 75119f23e5
commit 027555eb4e
9 changed files with 323 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/wip-protocol/src/error.rs
+102 -6
View File
@@ -223,10 +223,29 @@ impl Display for ValidationError {
impl Error for ValidationError {}
/// Stable protocol failure code returned by a host or produced by a client.
/// One core interaction whose failure codes form a closed set.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolInteraction {
/// Fetch one object by its Worldspace path.
Fetch,
/// Fetch a bounded tree of objects.
FetchTree,
/// Fetch one interface descriptor by its opaque reference.
FetchInterface,
/// Invoke one operation on a path-targeted object.
CallOperation,
}
/// Stable protocol failure code returned by a host.
///
/// This is the complete wire-level code set. A Client treats a malformed success
/// or failure response, including a code disallowed for its interaction, as a
/// Client-local `InvalidResponse`. An unsupported descriptor format is likewise
/// a Client-local `UnsupportedDescriptorFormat`; neither condition is a code a
/// Host can return.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolErrorCode {
/// The request is structurally invalid.
/// The request is structurally invalid before an operation descriptor is fixed.
InvalidRequest,
/// The target object is not published.
NotFound,
@@ -236,10 +255,8 @@ pub enum ProtocolErrorCode {
InterfaceMismatch,
/// The selected operation is not declared by the current interface.
OperationNotFound,
/// Supplied operation arguments are invalid.
/// Supplied arguments do not match the fixed operation declaration.
InvalidArguments,
/// A host result does not satisfy the declaration.
InvalidResult,
/// The operation requires an object validator and none was supplied.
ValidatorRequired,
/// The supplied object validator does not match current state.
@@ -251,9 +268,88 @@ pub enum ProtocolErrorCode {
/// A published operation is not permitted for the caller.
PermissionDenied,
/// A bounded protocol resource limit was exceeded.
///
/// For `call_operation`, the Host guarantees that the operation was not run
/// or that all of its effects were rolled back.
ResourceLimitExceeded,
/// The host encountered an internal failure.
/// The Host encountered an internal failure.
///
/// For `call_operation`, the Host guarantees that the operation was not run
/// or that all of its effects were rolled back.
Internal,
/// The Host cannot guarantee that the operation was not run or rolled back.
///
/// A Client must not automatically retry because the operation may have
/// committed effects even though no success response was available.
OperationOutcomeUnknown,
}
impl ProtocolErrorCode {
/// Every canonical wire-level error code.
pub const ALL: [Self; 14] = [
Self::InvalidRequest,
Self::NotFound,
Self::InterfaceNotFound,
Self::InterfaceMismatch,
Self::OperationNotFound,
Self::InvalidArguments,
Self::ValidatorRequired,
Self::ValidatorMismatch,
Self::InterfaceValidatorRequired,
Self::InterfaceValidatorMismatch,
Self::PermissionDenied,
Self::ResourceLimitExceeded,
Self::Internal,
Self::OperationOutcomeUnknown,
];
/// Whether a Host may return this code for `interaction`.
///
/// `false` identifies an invalid error response; it does not turn that
/// response into another wire-level protocol failure.
#[must_use]
pub const fn is_allowed_for(self, interaction: ProtocolInteraction) -> bool {
use ProtocolErrorCode::{
InterfaceMismatch, InterfaceNotFound, InterfaceValidatorMismatch,
InterfaceValidatorRequired, Internal, InvalidArguments, InvalidRequest, NotFound,
OperationNotFound, OperationOutcomeUnknown, PermissionDenied, ResourceLimitExceeded,
ValidatorMismatch, ValidatorRequired,
};
use ProtocolInteraction::{CallOperation, Fetch, FetchInterface, FetchTree};
match (interaction, self) {
(_, InvalidRequest | ResourceLimitExceeded | Internal) => true,
(Fetch | FetchTree, NotFound) => true,
(FetchInterface, InterfaceNotFound) => true,
(
CallOperation,
NotFound
| InterfaceMismatch
| OperationNotFound
| InvalidArguments
| ValidatorRequired
| ValidatorMismatch
| InterfaceValidatorRequired
| InterfaceValidatorMismatch
| PermissionDenied
| OperationOutcomeUnknown,
) => true,
(
_,
NotFound
| InterfaceNotFound
| InterfaceMismatch
| OperationNotFound
| InvalidArguments
| ValidatorRequired
| ValidatorMismatch
| InterfaceValidatorRequired
| InterfaceValidatorMismatch
| PermissionDenied
| OperationOutcomeUnknown,
) => false,
}
}
}
/// Transport-independent protocol failure.
crates/wip-protocol/src/lib.rs
+16 -3
View File
@@ -16,7 +16,20 @@
//! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
//! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
//! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
//! | Stable failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
//! | Stable Host failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
//! | Per-interaction allowed failure codes | [`ProtocolInteraction`] / [`ProtocolErrorCode::is_allowed_for`] |
//!
//! [`ProtocolErrorCode`] is a closed set of Host-returned wire failures. After a
//! Client receives a response, an invalid Object, Descriptor, operation result,
//! malformed error, or error code disallowed by [`ProtocolInteraction`] is a
//! Client-local `InvalidResponse`, not another wire error. A descriptor whose
//! `format` is not supported is a Client-local `UnsupportedDescriptorFormat`.
//!
//! For `call_operation`, [`ProtocolErrorCode::Internal`] and
//! [`ProtocolErrorCode::ResourceLimitExceeded`] guarantee that the operation did
//! not run or that all effects were rolled back. Only
//! [`ProtocolErrorCode::OperationOutcomeUnknown`] means the Host cannot make that
//! guarantee; Clients must not automatically retry it.
//!
//! Paths, object refs, interface refs, and validators remain separate concepts.
//! They are represented by ordinary protocol strings/bytes in the corresponding
@@ -35,8 +48,8 @@ mod model;
mod validation;
pub use error::{
NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ValidationError,
ValidationErrorKind, ValueKind,
NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
ValidationError, ValidationErrorKind, ValueKind,
};
pub use model::{
CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
crates/wip-protocol/src/model.rs
+14
View File
@@ -379,6 +379,9 @@ impl FetchRequest {
}
/// Validates an object returned for this request.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_response(&self, response: &FetchResponse) -> Result<(), ValidationError> {
response.validate_at_path(&self.path)
}
@@ -393,6 +396,9 @@ impl FetchTreeRequest {
impl FetchTreeResponse {
/// Validates tree shape, names, depth, and node limit for `request`.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_for(&self, request: &FetchTreeRequest) -> Result<(), ValidationError> {
crate::validation::validate_fetch_tree_response(self, request)
}
@@ -400,6 +406,11 @@ impl FetchTreeResponse {
impl FetchInterfaceResponse {
/// Validates request correspondence and descriptor semantics.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`]. Descriptor format support is a
/// separate Client concern: an otherwise valid descriptor with an unsupported
/// `format` is a Client-local `UnsupportedDescriptorFormat`.
pub fn validate_for(&self, request: &FetchInterfaceRequest) -> Result<(), ValidationError> {
crate::validation::validate_fetch_interface_response(self, request)
}
@@ -414,6 +425,9 @@ impl CallOperationRequest {
impl CallOperationResponse {
/// Validates this result against the named operation in `descriptor`.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_for(
&self,
descriptor: &InterfaceDescriptor,
crates/wip-protocol/tests/validation.rs
+146 -20
View File
@@ -5,8 +5,8 @@ use wip_protocol::{
FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, NameNamespace,
Object, ObjectTreeNode, OperationDeclaration, ParameterDeclaration, PathSegment, ProtocolError,
ProtocolErrorCode, ProtocolResult, ReturnDeclaration, Target, TypeDeclaration, TypeExpr,
UnionCase, ValidationErrorKind, Value, ValueKind,
ProtocolErrorCode, ProtocolInteraction, ProtocolResult, ReturnDeclaration, Target,
TypeDeclaration, TypeExpr, UnionCase, ValidationErrorKind, Value, ValueKind,
};
fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
@@ -729,24 +729,26 @@ fn fetch_tree_dtos_validate_names_depth_limit_and_siblings() {
}
#[test]
fn protocol_result_and_every_canonical_error_code_are_available() {
let codes = [
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::NotFound,
ProtocolErrorCode::InterfaceNotFound,
ProtocolErrorCode::InterfaceMismatch,
ProtocolErrorCode::OperationNotFound,
ProtocolErrorCode::InvalidArguments,
ProtocolErrorCode::InvalidResult,
ProtocolErrorCode::ValidatorRequired,
ProtocolErrorCode::ValidatorMismatch,
ProtocolErrorCode::InterfaceValidatorRequired,
ProtocolErrorCode::InterfaceValidatorMismatch,
ProtocolErrorCode::PermissionDenied,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
];
assert_eq!(codes.len(), 14);
fn protocol_result_exposes_the_exact_canonical_wire_error_codes() {
assert_eq!(
ProtocolErrorCode::ALL,
[
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::NotFound,
ProtocolErrorCode::InterfaceNotFound,
ProtocolErrorCode::InterfaceMismatch,
ProtocolErrorCode::OperationNotFound,
ProtocolErrorCode::InvalidArguments,
ProtocolErrorCode::ValidatorRequired,
ProtocolErrorCode::ValidatorMismatch,
ProtocolErrorCode::InterfaceValidatorRequired,
ProtocolErrorCode::InterfaceValidatorMismatch,
ProtocolErrorCode::PermissionDenied,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
ProtocolErrorCode::OperationOutcomeUnknown,
]
);
let failure: ProtocolResult<()> = ProtocolResult::Failure(ProtocolError {
code: ProtocolErrorCode::InvalidArguments,
@@ -758,3 +760,127 @@ fn protocol_result_and_every_canonical_error_code_are_available() {
ProtocolResult::Success(Value::Unit)
);
}
fn assert_allowed_codes(interaction: ProtocolInteraction, expected: &[ProtocolErrorCode]) {
let actual: Vec<_> = ProtocolErrorCode::ALL
.into_iter()
.filter(|code| code.is_allowed_for(interaction))
.collect();
assert_eq!(actual, expected);
for code in ProtocolErrorCode::ALL {
assert_eq!(
code.is_allowed_for(interaction),
expected.contains(&code),
"unexpected {code:?} validity for {interaction:?}"
);
}
}
#[test]
fn fetch_error_codes_are_exhaustive() {
assert_allowed_codes(
ProtocolInteraction::Fetch,
&[
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::NotFound,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
],
);
}
#[test]
fn fetch_tree_error_codes_are_exhaustive() {
assert_allowed_codes(
ProtocolInteraction::FetchTree,
&[
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::NotFound,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
],
);
}
#[test]
fn fetch_interface_error_codes_are_exhaustive() {
assert_allowed_codes(
ProtocolInteraction::FetchInterface,
&[
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::InterfaceNotFound,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
],
);
}
#[test]
fn call_operation_error_codes_are_exhaustive() {
assert_allowed_codes(
ProtocolInteraction::CallOperation,
&[
ProtocolErrorCode::InvalidRequest,
ProtocolErrorCode::NotFound,
ProtocolErrorCode::InterfaceMismatch,
ProtocolErrorCode::OperationNotFound,
ProtocolErrorCode::InvalidArguments,
ProtocolErrorCode::ValidatorRequired,
ProtocolErrorCode::ValidatorMismatch,
ProtocolErrorCode::InterfaceValidatorRequired,
ProtocolErrorCode::InterfaceValidatorMismatch,
ProtocolErrorCode::PermissionDenied,
ProtocolErrorCode::ResourceLimitExceeded,
ProtocolErrorCode::Internal,
ProtocolErrorCode::OperationOutcomeUnknown,
],
);
}
#[test]
fn invalid_success_payloads_remain_client_local_validation_failures() {
let fetch = FetchRequest {
path: "/articles/one".into(),
};
assert!(matches!(
fetch.validate_response(&object("other")).unwrap_err().kind,
ValidationErrorKind::ObjectNameMismatch { .. }
));
let interface_request = FetchInterfaceRequest {
interface: "catalog-v1".into(),
};
let mut invalid_descriptor = descriptor();
invalid_descriptor
.operations
.push(invalid_descriptor.operations[0].clone());
assert!(matches!(
FetchInterfaceResponse {
interface: interface_request.interface.clone(),
descriptor: invalid_descriptor,
validator: None,
}
.validate_for(&interface_request)
.unwrap_err()
.kind,
ValidationErrorKind::DuplicateName {
namespace: NameNamespace::Operation,
..
}
));
assert!(matches!(
CallOperationResponse {
result: Value::String("not a boolean".into()),
validator: None,
}
.validate_for(&descriptor(), "publish")
.unwrap_err()
.kind,
ValidationErrorKind::TypeMismatch {
expected: ValueKind::Boolean,
actual: ValueKind::String,
}
));
}