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