From 1e5f94b06b2c2a54753d43fff9c64d6a712bbb79 Mon Sep 17 00:00:00 2001 From: "glm-5.2" Date: Fri, 26 Jun 2026 12:56:28 +0000 Subject: [PATCH] =?UTF-8?q?feat(call):=20OperationAdapter=20trait=20+=20Ad?= =?UTF-8?q?apterError=20+=20from=5Fjsonschema=20(ADR-017=20=C2=A75)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - client module: defines the async OperationAdapter trait (import() -> Result, 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 --- .../alknet-call/src/client/from_jsonschema.rs | 175 ++++++++++++++++++ crates/alknet-call/src/client/mod.rs | 102 ++++++++++ crates/alknet-call/src/lib.rs | 1 + tasks/call/client/from-jsonschema.md | 2 +- tasks/call/client/operation-adapter-trait.md | 2 +- 5 files changed, 280 insertions(+), 2 deletions(-) create mode 100644 crates/alknet-call/src/client/from_jsonschema.rs create mode 100644 crates/alknet-call/src/client/mod.rs diff --git a/crates/alknet-call/src/client/from_jsonschema.rs b/crates/alknet-call/src/client/from_jsonschema.rs new file mode 100644 index 0000000..ce3ad02 --- /dev/null +++ b/crates/alknet-call/src/client/from_jsonschema.rs @@ -0,0 +1,175 @@ +//! Schema-only registration: produce a `HandlerRegistration` bundle with +//! `FromJsonSchema` provenance and no real handler. The caller fetches the +//! JSON Schema doc and passes it in; this adapter does no network I/O. +//! +//! See `docs/architecture/crates/call/client-and-adapters.md` (from_jsonschema +//! section) and ADR-017 §5. + +use alknet_core::types::Capabilities; +use serde_json::Value; + +use crate::client::{AdapterError, OperationAdapter}; +use crate::protocol::wire::{CallError, ResponseEnvelope}; +use crate::registry::context::OperationContext; +use crate::registry::registration::{make_handler, HandlerRegistration, OperationProvenance}; +use crate::registry::spec::OperationSpec; + +/// Build a [`HandlerRegistration`] from a JSON Schema-described operation. +/// +/// Schema-only: no real handler is attached — a placeholder returns a +/// `NOT_FOUND`-style error if ever invoked (schema-only ops are `Internal` +/// and `remote_safe: false`, so dispatch should never reach them; the +/// placeholder fails loudly on bugs). `provenance` is `FromJsonSchema`; +/// `composition_authority` and `scoped_env` are `None`; `capabilities` is +/// empty. +pub fn from_jsonschema(spec: OperationSpec, _schema: Value) -> HandlerRegistration { + let handler = make_handler(|_input: Value, context: OperationContext| async move { + ResponseEnvelope::error( + context.request_id, + CallError::not_found("FromJsonSchema ops are schema-only and have no handler"), + ) + }); + HandlerRegistration::new( + spec, + handler, + OperationProvenance::FromJsonSchema, + None, + None, + Capabilities::new(), + ) +} + +/// A JSON-Schema-only [`OperationAdapter`]. +/// +/// Pure parse — no transport, no `.await` in `import()`. Returns +/// [`AdapterError::SchemaParse`] when the supplied schema is not a JSON +/// object. +pub struct FromJsonSchema { + spec: OperationSpec, + schema: Value, +} + +impl FromJsonSchema { + pub fn new(spec: OperationSpec, schema: Value) -> Self { + Self { spec, schema } + } +} + +#[async_trait::async_trait] +impl OperationAdapter for FromJsonSchema { + async fn import(&self) -> Result, AdapterError> { + if !self.schema.is_object() { + return Err(AdapterError::SchemaParse { + message: "schema must be a JSON object".into(), + }); + } + Ok(vec![from_jsonschema( + self.spec.clone(), + self.schema.clone(), + )]) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::client::from_jsonschema as from_jsonschema_fn; + use crate::registry::context::{AbortPolicy, ScopedOperationEnv}; + use crate::registry::env::OperationEnv; + use crate::registry::spec::{AccessControl, OperationType, Visibility}; + use std::collections::HashMap; + use std::sync::Arc; + use std::time::Duration; + + struct NoopEnv; + + #[async_trait::async_trait] + impl OperationEnv for NoopEnv { + async fn invoke_with_policy( + &self, + _namespace: &str, + _operation: &str, + _input: Value, + parent: &OperationContext, + _policy: AbortPolicy, + ) -> ResponseEnvelope { + ResponseEnvelope::ok(parent.request_id.clone(), Value::Null) + } + } + + fn test_spec(name: &str) -> OperationSpec { + OperationSpec::new( + name, + OperationType::Query, + Visibility::Internal, + serde_json::json!({}), + serde_json::json!({}), + vec![], + AccessControl::default(), + ) + } + + fn test_context(request_id: &str) -> OperationContext { + OperationContext { + request_id: request_id.to_string(), + parent_request_id: None, + identity: None, + handler_identity: None, + capabilities: Capabilities::new(), + metadata: HashMap::new(), + scoped_env: ScopedOperationEnv::empty(), + env: Arc::new(NoopEnv), + abort_policy: AbortPolicy::default(), + deadline: Some(std::time::Instant::now() + Duration::from_secs(30)), + internal: true, + } + } + + #[test] + fn from_jsonschema_bundle_shape() { + let bundle = from_jsonschema_fn::from_jsonschema(test_spec("ns/op"), serde_json::json!({})); + assert_eq!(bundle.spec.name, "ns/op"); + assert_eq!(bundle.provenance, OperationProvenance::FromJsonSchema); + assert!(bundle.composition_authority.is_none()); + assert!(bundle.scoped_env.is_none()); + assert!(!bundle.remote_safe); + } + + #[tokio::test] + async fn placeholder_handler_returns_error_when_invoked() { + let bundle = from_jsonschema_fn::from_jsonschema(test_spec("ns/op"), serde_json::json!({})); + let ctx = test_context("req-1"); + let response = (bundle.handler)(serde_json::json!({}), ctx).await; + match response.result { + Err(e) => { + assert_eq!(e.code, "NOT_FOUND"); + assert!(e.message.contains("FromJsonSchema")); + } + other => panic!("expected NOT_FOUND, got {other:?}"), + } + } + + #[tokio::test] + async fn import_returns_ok_with_one_bundle() { + let adapter = + FromJsonSchema::new(test_spec("ns/op"), serde_json::json!({"type": "object"})); + let bundles = match adapter.import().await { + Ok(b) => b, + Err(e) => panic!("expected Ok, got Err: {e}"), + }; + assert_eq!(bundles.len(), 1); + assert_eq!(bundles[0].provenance, OperationProvenance::FromJsonSchema); + } + + #[tokio::test] + async fn import_non_object_schema_returns_schema_parse() { + let adapter = FromJsonSchema::new(test_spec("ns/op"), serde_json::json!(42)); + match adapter.import().await { + Ok(_) => panic!("expected Err"), + Err(AdapterError::SchemaParse { message }) => { + assert!(message.contains("JSON object")); + } + Err(other) => panic!("expected SchemaParse, got {other}"), + } + } +} diff --git a/crates/alknet-call/src/client/mod.rs b/crates/alknet-call/src/client/mod.rs new file mode 100644 index 0000000..2b5f15e --- /dev/null +++ b/crates/alknet-call/src/client/mod.rs @@ -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, AdapterError>; +} + +#[cfg(test)] +mod tests { + use super::*; + + struct OkAdapter; + + #[async_trait::async_trait] + impl OperationAdapter for OkAdapter { + async fn import(&self) -> Result, AdapterError> { + Ok(vec![]) + } + } + + struct ErrAdapter; + + #[async_trait::async_trait] + impl OperationAdapter for ErrAdapter { + async fn import(&self) -> Result, 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}"), + } + } +} diff --git a/crates/alknet-call/src/lib.rs b/crates/alknet-call/src/lib.rs index c6a8190..cffebf5 100644 --- a/crates/alknet-call/src/lib.rs +++ b/crates/alknet-call/src/lib.rs @@ -6,5 +6,6 @@ //! - [`registry`] — operation specs, context, dispatch, and the operation registry. //! - [`protocol`] — wire format, streams, and the call adapter. +pub mod client; pub mod protocol; pub mod registry; diff --git a/tasks/call/client/from-jsonschema.md b/tasks/call/client/from-jsonschema.md index 74c789e..f42281d 100644 --- a/tasks/call/client/from-jsonschema.md +++ b/tasks/call/client/from-jsonschema.md @@ -1,7 +1,7 @@ --- id: call/client/from-jsonschema name: Implement from_jsonschema adapter (schema-only registration, FromJsonSchema provenance, no handler) -status: pending +status: completed depends_on: [call/client/operation-adapter-trait] scope: narrow risk: low diff --git a/tasks/call/client/operation-adapter-trait.md b/tasks/call/client/operation-adapter-trait.md index e473fe5..7255068 100644 --- a/tasks/call/client/operation-adapter-trait.md +++ b/tasks/call/client/operation-adapter-trait.md @@ -1,7 +1,7 @@ --- id: call/client/operation-adapter-trait name: Define OperationAdapter async trait + AdapterError enum (ADR-017 §5, DC-4/OQ-26) -status: pending +status: completed depends_on: [call/registry/handler-registration] scope: narrow risk: low