feat(call): OperationAdapter trait + AdapterError + from_jsonschema (ADR-017 §5)
- client module: defines the async OperationAdapter trait (import() -> Result<Vec<HandlerRegistration>, AdapterError>) and the #[non_exhaustive] AdapterError enum (string-message payloads: DiscoveryFailed, SchemaParse, Transport, Unauthorized, Conflict). The trait lives in alknet-call where the types live; implementations live with their transport deps. - from_jsonschema: schema-only registration producing a FromJsonSchema-provenance HandlerRegistration with no real handler (placeholder errors if invoked), None authority/scoped_env, empty capabilities, remote_safe false (ADR-028 §4). Implements OperationAdapter; malformed (non-object) schema returns AdapterError::SchemaParse. No network I/O. - Re-exported from lib.rs. - Tests: trait compiles for Ok and Err adapters; from_jsonschema bundle shape; placeholder handler errors; OperationAdapter import Ok + SchemaParse paths. All 178+N tests pass, clippy + fmt clean. Unblocks alknet-http Phase 1 (from_openapi/from_mcp adapter implementations). Refs: tasks/call/client/operation-adapter-trait.md, tasks/call/client/from-jsonschema.md Refs: docs/architecture/decisions/017-call-protocol-client-and-adapter-contract.md §5 Refs: docs/architecture/crates/call/client-and-adapters.md
This commit is contained in:
102
crates/alknet-call/src/client/mod.rs
Normal file
102
crates/alknet-call/src/client/mod.rs
Normal file
@@ -0,0 +1,102 @@
|
||||
//! Client adapters: turn external operation sources (JSON Schema, OpenAPI,
|
||||
//! MCP, remote `from_call` peers) into `HandlerRegistration` bundles.
|
||||
//!
|
||||
//! See `docs/architecture/crates/call/client-and-adapters.md` for the
|
||||
//! OperationAdapter trait and the Adapter Location Map, and
|
||||
//! `docs/architecture/decisions/017-call-protocol-client-and-adapter-contract.md`
|
||||
//! §5 for the trait contract.
|
||||
|
||||
mod from_jsonschema;
|
||||
|
||||
pub use from_jsonschema::{from_jsonschema, FromJsonSchema};
|
||||
|
||||
use crate::registry::registration::HandlerRegistration;
|
||||
|
||||
/// Errors produced by [`OperationAdapter::import`].
|
||||
///
|
||||
/// The variant set is the v1 default (two-way-door remainder, OQ-26);
|
||||
/// `#[non_exhaustive]` lets downstream adapters (e.g. `alknet-http`'s
|
||||
/// `from_openapi`/`from_mcp`) extend without breaking match arms. All
|
||||
/// payloads are string messages — kept simple and `Send + Sync` by
|
||||
/// construction.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
#[non_exhaustive]
|
||||
pub enum AdapterError {
|
||||
/// `from_call` remote unreachable / `services/list` failed.
|
||||
#[error("discovery failed: {message}")]
|
||||
DiscoveryFailed { message: String },
|
||||
|
||||
/// `from_openapi` / `from_jsonschema` couldn't parse the spec.
|
||||
#[error("schema parse error: {message}")]
|
||||
SchemaParse { message: String },
|
||||
|
||||
/// Underlying transport error (QUIC for `from_call`, HTTP for adapters).
|
||||
#[error("transport error: {message}")]
|
||||
Transport { message: String },
|
||||
|
||||
/// HTTP 401 for `from_openapi`/`from_mcp`, auth rejected for `from_call`.
|
||||
#[error("unauthorized: {message}")]
|
||||
Unauthorized { message: String },
|
||||
|
||||
/// Namespace collision in `from_call` (DC-3); reused for other adapters.
|
||||
#[error("conflict: {message}")]
|
||||
Conflict { message: String },
|
||||
}
|
||||
|
||||
/// Import a set of operations as `HandlerRegistration` bundles.
|
||||
///
|
||||
/// Async because `from_call` requires async discovery (`services/list` +
|
||||
/// `services/schema` over a QUIC connection); sync adapters (e.g.
|
||||
/// `from_jsonschema`, `from_openapi` reading a static spec) trivially satisfy
|
||||
/// an async trait — their `import()` bodies contain no `.await` points.
|
||||
///
|
||||
/// See ADR-017 §5 (`docs/architecture/decisions/017-call-protocol-client-and-adapter-contract.md`)
|
||||
/// and `docs/architecture/crates/call/client-and-adapters.md`.
|
||||
#[async_trait::async_trait]
|
||||
pub trait OperationAdapter: Send + Sync {
|
||||
async fn import(&self) -> Result<Vec<HandlerRegistration>, AdapterError>;
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
struct OkAdapter;
|
||||
|
||||
#[async_trait::async_trait]
|
||||
impl OperationAdapter for OkAdapter {
|
||||
async fn import(&self) -> Result<Vec<HandlerRegistration>, AdapterError> {
|
||||
Ok(vec![])
|
||||
}
|
||||
}
|
||||
|
||||
struct ErrAdapter;
|
||||
|
||||
#[async_trait::async_trait]
|
||||
impl OperationAdapter for ErrAdapter {
|
||||
async fn import(&self) -> Result<Vec<HandlerRegistration>, AdapterError> {
|
||||
Err(AdapterError::SchemaParse {
|
||||
message: "x".into(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn ok_adapter_imports_empty() {
|
||||
let adapter = OkAdapter;
|
||||
match adapter.import().await {
|
||||
Ok(bundles) => assert!(bundles.is_empty()),
|
||||
Err(e) => panic!("expected Ok, got Err: {e}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn err_adapter_returns_schema_parse() {
|
||||
let adapter = ErrAdapter;
|
||||
match adapter.import().await {
|
||||
Ok(_) => panic!("expected Err"),
|
||||
Err(AdapterError::SchemaParse { message }) => assert_eq!(message, "x"),
|
||||
Err(other) => panic!("expected SchemaParse, got {other}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user