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

feat: migrate protocol and HTTP to structured interface references

Browse Source 
T-20: identify interfaces by exact scope/name pairs; add optional opaque scope_ref metadata and separate shape validation from path-dependent scope compatibility. Preserve call error precedence, strict JSON, validators and transport boundaries. Mechanically migrate consumers and document API/wire compatibility and deferred lifecycle semantics.

Validation: cargo fmt --all --check; git diff --check; cargo check --workspace --all-targets; cargo test -p wip-protocol -p wip-http; cargo test --workspace (221 passing tests including doctests); cargo test --workspace --all-targets; nix develop --command cargo clippy --workspace --all-targets -- -D warnings; RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps. All pass. cargo/rustc 1.95.0; development-shell Clippy/rustc 1.97.1.
This commit is contained in:
Hare
2026-10-07 18:29:51 +09:00
parent bf5fa54f44
commit 8ecc307fc9
34 changed files with 2124 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/wip-host/README.md
+4
View File
@@ -10,6 +10,10 @@ wip-host = "0.1.0"
wip-interface = "0.1.0"
```
Protocol publication and dispatch use `wip_protocol::InterfaceReference { scope, name }` and compare both fields exactly. The legacy `InterfaceRef` registration token remains Host-private: `protocol_reference()` maps its opaque string verbatim to the name at root scope `/`, without parsing it. Registry lookup and fetch accept structured references; non-root references do not resolve legacy registrations. Legacy responses omit `scope_ref`.
Malformed interface-reference shapes fail calls as `InvalidRequest` before object resolution. A well-shaped reference outside the target path's ancestor-or-self scope fails at the membership check as `InterfaceMismatch`.
See the [API documentation](https://docs.rs/wip-host) for publication, provider, execution-context, and effect-guarantee boundaries.
Licensed under either of Apache-2.0 or MIT at your option.
crates/wip-host/src/lib.rs
+57 -17
View File
@@ -49,8 +49,8 @@ pub use wip_protocol::{
Target,
};
use wip_protocol::{
FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor, Object, ProtocolError,
ProtocolErrorCode, ValidationError, Value,
FetchInterfaceRequest, FetchInterfaceResponse, InterfaceDescriptor, InterfaceReference, Object,
ProtocolError, ProtocolErrorCode, ValidationError, Value,
};
/// Opaque bytes used as a conditional execution precondition.
@@ -192,11 +192,22 @@ impl ExecutionContext {
pub struct InterfaceRef(String);
impl InterfaceRef {
/// Returns the opaque reference for a protocol transport.
/// Returns the legacy opaque registration reference.
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
/// Maps the legacy registration reference to a root-scoped protocol reference.
///
/// The opaque registration string is copied as the name without parsing it.
#[must_use]
pub fn protocol_reference(&self) -> InterfaceReference {
InterfaceReference {
scope: "/".into(),
name: self.0.clone(),
}
}
}
/// One atomic observation of an interface reference, descriptor, and validator.
@@ -229,13 +240,14 @@ impl InterfaceObservation {
/// local validation error.
pub fn protocol_response(&self) -> Result<FetchInterfaceResponse, ProtocolError> {
let response = FetchInterfaceResponse {
interface: self.reference.0.clone(),
interface: self.reference.protocol_reference(),
descriptor: self.descriptor.clone(),
scope_ref: None,
validator: self.validator.as_ref().map(|validator| validator.0.clone()),
};
response
.validate_for(&FetchInterfaceRequest {
interface: self.reference.0.clone(),
interface: self.reference.protocol_reference(),
})
.map_err(|_| ProtocolError {
code: ProtocolErrorCode::Internal,
@@ -354,10 +366,16 @@ impl InterfaceRegistry {
})
}
/// Resolves a transport-provided opaque reference string in this registry.
/// Resolves a structured protocol reference to a legacy registration token.
///
/// Legacy artifacts are published only at root scope. The name is looked up
/// verbatim; no scope or name parsing is performed.
#[must_use]
pub fn resolve(&self, reference: &str) -> Option<InterfaceRef> {
let reference = InterfaceRef(reference.to_owned());
pub fn resolve(&self, reference: &InterfaceReference) -> Option<InterfaceRef> {
if reference.scope != "/" {
return None;
}
let reference = InterfaceRef(reference.name.clone());
self.artifacts.contains_key(&reference).then_some(reference)
}
@@ -367,14 +385,20 @@ impl InterfaceRegistry {
self.artifacts.get(reference).map(Self::observation)
}
/// Implements canonical `fetch_interface` semantics for an opaque reference.
/// Implements canonical `fetch_interface` semantics for a structured reference.
///
/// Unknown and currently unpublished references map to `InterfaceNotFound`,
/// not object membership errors or authorization failures.
pub fn fetch_interface(&self, reference: &str) -> Result<InterfaceObservation, ProtocolError> {
let reference = InterfaceRef(reference.to_owned());
self.artifacts
.get(&reference)
/// Malformed references map to `InvalidRequest`. Unknown and currently
/// unpublished references (including non-root scopes) map to `InterfaceNotFound`.
pub fn fetch_interface(
&self,
reference: &InterfaceReference,
) -> Result<InterfaceObservation, ProtocolError> {
reference.validate().map_err(|error| ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: error.to_string(),
})?;
self.resolve(reference)
.and_then(|reference| self.artifacts.get(&reference))
.map(Self::observation)
.ok_or_else(|| ProtocolError {
code: ProtocolErrorCode::InterfaceNotFound,
@@ -625,7 +649,7 @@ impl<T: WipObject> PublishedObject<T> {
interfaces: self
.interfaces
.iter()
.map(|bound| bound.artifact.reference.0.clone())
.map(|bound| bound.artifact.reference.protocol_reference())
.collect(),
r#ref: self.implementation.reference().map(str::to_owned),
validator: self
@@ -678,10 +702,17 @@ impl<T: WipObject> PublishedObject<T> {
);
}
if interface.reference.validate_for_path(&target.path).is_err() {
return pre_dispatch_failure(
CallErrorKind::InterfaceMismatch,
"interface scope is not an ancestor of the target path",
);
}
let Some(bound) = self
.interfaces
.iter()
.find(|bound| bound.artifact.reference.as_str() == interface.reference.as_str())
.find(|bound| bound.artifact.reference.protocol_reference() == interface.reference)
else {
return pre_dispatch_failure(
CallErrorKind::InterfaceMismatch,
@@ -1039,6 +1070,11 @@ pub trait ObjectProvider {
) -> Result<CallResult, CallError> {
wip_protocol::validate_path(&request.target.path)
.map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
request
.interface
.reference
.validate()
.map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
let path = request.target.path.clone();
let execution = catch_unwind(AssertUnwindSafe(|| {
self.execute_operation(context, &path, |publication| {
@@ -1088,6 +1124,10 @@ pub trait ObjectProvider {
) -> Result<CallResult, CallError> {
wip_protocol::validate_path(&target.path)
.map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
interface
.reference
.validate()
.map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
let path = target.path.clone();
let execution = catch_unwind(AssertUnwindSafe(|| {
self.execute_operation(context, &path, |publication| {
crates/wip-host/tests/host.rs
+133 -14
View File
@@ -35,7 +35,10 @@ fn principal_projection_orders_subsets_and_rejects_unimplemented_or_duplicate_to
.unwrap();
assert_eq!(
projected.protocol_object().interfaces,
vec![write.reference().as_str(), read.reference().as_str()]
vec![
write.reference().protocol_reference(),
read.reference().protocol_reference()
]
);
assert!(
publication()
@@ -58,14 +61,18 @@ fn principal_projection_orders_subsets_and_rejects_unimplemented_or_duplicate_to
.interfaces
.is_empty()
);
let full = registry.fetch_interface(read.reference().as_str()).unwrap();
let full = registry
.fetch_interface(&read.reference().protocol_reference())
.unwrap();
let filtered = full
.clone()
.project_operations(|operation| operation == "label");
assert_eq!(filtered.descriptor.operations.len(), 1);
assert_eq!(full.descriptor.operations.len(), 3);
assert_eq!(
registry.fetch_interface(read.reference().as_str()).unwrap(),
registry
.fetch_interface(&read.reference().protocol_reference())
.unwrap(),
full
);
}
@@ -478,7 +485,8 @@ fn request(
validator: object_validator.map(<[u8]>::to_vec),
},
interface: InterfaceTarget {
reference: reference.as_str().to_owned(),
reference: reference.protocol_reference(),
scope_ref: None,
validator: interface_validator.map(<[u8]>::to_vec),
},
operation: operation.into(),
@@ -497,17 +505,22 @@ fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor()
let reference = provider.reader.reference();
assert_ne!(reference.as_str(), "Reader");
let observation = registry.fetch_interface(reference.as_str()).unwrap();
let observation = registry
.fetch_interface(&reference.protocol_reference())
.unwrap();
assert_eq!(observation.reference, *reference);
assert_eq!(observation.descriptor, ReaderDefinition::descriptor());
assert_eq!(observation.validator, Some(Validator::new(b"schema-v1")));
let response = observation.protocol_response().unwrap();
assert_eq!(response.interface, reference.as_str());
assert_eq!(response.interface, reference.protocol_reference());
assert_eq!(response.scope_ref, None);
assert_eq!(response.descriptor, ReaderDefinition::descriptor());
assert_eq!(response.validator.as_deref(), Some(b"schema-v1".as_slice()));
response.descriptor.validate().unwrap();
let mut invalid_observation = registry.fetch_interface(reference.as_str()).unwrap();
let mut invalid_observation = registry
.fetch_interface(&reference.protocol_reference())
.unwrap();
let duplicate_operation = invalid_observation.descriptor.operations[0].clone();
invalid_observation
.descriptor
@@ -516,7 +529,12 @@ fn registry_returns_atomic_canonical_observation_without_rewriting_descriptor()
let invalid_response = invalid_observation.protocol_response().unwrap_err();
assert_eq!(invalid_response.code, ProtocolErrorCode::Internal);
let error = registry.fetch_interface("unknown").unwrap_err();
let error = registry
.fetch_interface(&wip_protocol::InterfaceReference {
scope: "/".into(),
name: "unknown".into(),
})
.unwrap_err();
assert_eq!(error.code, ProtocolErrorCode::InterfaceNotFound);
}
@@ -532,8 +550,8 @@ fn canonical_object_projection_supports_optional_metadata_and_ordered_sets() {
assert_eq!(
object.interfaces,
vec![
provider.writer.reference().as_str().to_owned(),
provider.reader.reference().as_str().to_owned(),
provider.writer.reference().protocol_reference(),
provider.reader.reference().protocol_reference(),
]
);
assert!(!format!("{object:?}").contains("secret-handle"));
@@ -814,7 +832,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
validator: Some(b"stale".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
reference: hidden.reference().protocol_reference(),
scope_ref: None,
validator: None,
},
"missing".into(),
@@ -832,7 +851,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
validator: Some(b"stale".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
reference: hidden.reference().protocol_reference(),
scope_ref: None,
validator: None,
},
"hidden".into(),
@@ -850,7 +870,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
validator: Some(b"object-v1".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
reference: hidden.reference().protocol_reference(),
scope_ref: None,
validator: None,
},
"hidden".into(),
@@ -868,7 +889,8 @@ fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
validator: Some(b"object-v1".to_vec()),
},
InterfaceTarget {
reference: provider.reader.reference().as_str().into(),
reference: provider.reader.reference().protocol_reference(),
scope_ref: None,
validator: Some(b"schema-v1".to_vec()),
},
"add".into(),
@@ -1122,3 +1144,100 @@ fn execution_context_is_propagated_and_preflight_prevents_invocation() {
);
assert_eq!(provider.calls.get(), calls);
}
#[test]
fn legacy_registry_boundaries_copy_names_verbatim_and_match_exact_scope() {
let (registry, provider, _) = registry_and_provider();
let legacy = provider.writer.reference();
let reference = legacy.protocol_reference();
assert_eq!(reference.scope, "/");
assert_eq!(reference.name, legacy.as_str());
// The registry's colon-delimited name remains opaque, not parsed.
assert!(reference.name.starts_with("wip-interface:"));
assert_eq!(registry.resolve(&reference).as_ref(), Some(legacy));
let nested = wip_protocol::InterfaceReference {
scope: "/open".into(),
name: reference.name.clone(),
};
assert!(registry.resolve(&nested).is_none());
assert_eq!(
registry.fetch_interface(&nested).unwrap_err().code,
ProtocolErrorCode::InterfaceNotFound
);
let malformed = wip_protocol::InterfaceReference {
scope: "relative".into(),
name: reference.name,
};
assert_eq!(
registry.fetch_interface(&malformed).unwrap_err().code,
ProtocolErrorCode::InvalidRequest
);
}
#[test]
fn call_reference_shape_precedes_resolution_and_scope_membership_is_exact() {
let (_, provider, _) = registry_and_provider();
for (scope, name) in [("relative", "valid"), ("/", ""), ("/bad/", "valid")] {
let mut call = request(
"/open",
None,
provider.writer.reference(),
None,
"label",
BTreeMap::new(),
);
call.interface.reference = wip_protocol::InterfaceReference {
scope: scope.into(),
name: name.into(),
};
assert_eq!(
provider.call_operation(call.clone()).unwrap_err().kind(),
CallErrorKind::InvalidRequest
);
assert_eq!(
provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
call.target,
call.interface,
call.operation,
|_| Ok::<_, ()>(BTreeMap::new()),
)
.unwrap_err()
.kind(),
CallErrorKind::InvalidRequest
);
}
assert_eq!(provider.resolutions.get(), 0);
// /other is outside the target scope; /open is self but has no legacy artifact.
for scope in ["/other", "/open"] {
let mut call = request(
"/open",
None,
provider.writer.reference(),
None,
"label",
BTreeMap::new(),
);
call.interface.reference.scope = scope.into();
assert_eq!(
provider.call_operation(call.clone()).unwrap_err().kind(),
CallErrorKind::InterfaceMismatch
);
assert_eq!(
provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
call.target,
call.interface,
call.operation,
|_| -> Result<BTreeMap<String, Value>, ()> { panic!("must not decode") },
)
.unwrap_err()
.kind(),
CallErrorKind::InterfaceMismatch
);
}
assert_eq!(provider.calls.get(), 0);
assert_eq!(provider.authorization_checks.get(), 0);
}