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:
2026-06-26 12:56:28 +00:00
parent e4a25947d6
commit 1e5f94b06b
5 changed files with 280 additions and 2 deletions

View 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}"),
}
}
}