1#[cfg(feature = "unstable_protocol_v2")]
7pub(crate) const UNKNOWN_IMPLEMENTATION: &str = "unknown";
8
9#[cfg(feature = "unstable_protocol_v2")]
19pub(crate) fn normalize_newer_v2_initialize_request(
20 params: &serde_json::Map<String, serde_json::Value>,
21) -> Result<serde_json::Map<String, serde_json::Value>, crate::Error> {
22 use crate::{schema::ProtocolVersion, v2::schema as v2};
23 use serde::Deserialize as _;
24
25 let mut params = params.clone();
26 let info_parses = params
27 .get("info")
28 .is_some_and(|info| v2::Implementation::deserialize(info).is_ok());
29 if !info_parses {
30 let unknown = v2::Implementation::new(UNKNOWN_IMPLEMENTATION, UNKNOWN_IMPLEMENTATION);
31 params.insert(
32 "info".into(),
33 serde_json::to_value(unknown).map_err(crate::Error::into_internal_error)?,
34 );
35 }
36 retain_parsable_capabilities::<v2::ClientCapabilities>(&mut params, "capabilities");
37 retain_object(&mut params, "_meta");
38 params.insert(
39 "protocolVersion".into(),
40 serde_json::to_value(ProtocolVersion::V2).map_err(crate::Error::into_internal_error)?,
41 );
42 let initialize: v2::InitializeRequest =
43 serde_json::from_value(serde_json::Value::Object(params))?;
44 let serde_json::Value::Object(normalized) =
45 serde_json::to_value(initialize).map_err(crate::Error::into_internal_error)?
46 else {
47 return Err(crate::util::internal_error(
48 "initialize params did not serialize to an object",
49 ));
50 };
51 Ok(normalized)
52}
53
54fn retain_parsable_capabilities<T: serde::de::DeserializeOwned>(
57 params: &mut serde_json::Map<String, serde_json::Value>,
58 key: &str,
59) {
60 if !retain_object(params, key) {
61 return;
62 }
63 if let Some(serde_json::Value::Object(capabilities)) = params.get_mut(key) {
64 capabilities.retain(|name, value| {
65 let single = serde_json::Map::from_iter([(name.clone(), value.clone())]);
66 serde_json::from_value::<T>(serde_json::Value::Object(single)).is_ok()
67 });
68 }
69}
70
71fn retain_object(params: &mut serde_json::Map<String, serde_json::Value>, key: &str) -> bool {
73 match params.get(key) {
74 Some(serde_json::Value::Object(_)) => true,
75 Some(_) => {
76 params.remove(key);
77 false
78 }
79 None => false,
80 }
81}
82
83pub(crate) fn normalize_v1_initialize_request(
93 params: &serde_json::Value,
94) -> Result<serde_json::Map<String, serde_json::Value>, crate::Error> {
95 use crate::{schema::ProtocolVersion, v1::schema as v1};
96 use serde::Deserialize as _;
97
98 let info = params
99 .get("info")
100 .and_then(|info| v1::Implementation::deserialize(info).ok());
101 let mut capabilities = serde_json::Map::new();
102 if let Some(source) = params
103 .get("capabilities")
104 .and_then(serde_json::Value::as_object)
105 {
106 for key in ["auth", "elicitation", "_meta"] {
107 if let Some(value) = source.get(key) {
108 capabilities.insert(key.into(), value.clone());
109 }
110 }
111 }
112 if let Some(auth) = capabilities
113 .get_mut("auth")
114 .and_then(serde_json::Value::as_object_mut)
115 {
116 let terminal = auth
117 .remove("terminal")
118 .is_some_and(|value| value.is_object());
119 auth.insert("terminal".into(), terminal.into());
120 }
121 capabilities.insert(
122 "session".into(),
123 serde_json::json!({ "configOptions": { "boolean": {} } }),
124 );
125 let mut target = serde_json::Map::from_iter([
126 (
127 "protocolVersion".to_owned(),
128 serde_json::to_value(ProtocolVersion::V1).map_err(crate::Error::into_internal_error)?,
129 ),
130 ("clientCapabilities".to_owned(), capabilities.into()),
131 ]);
132 if let Some(info) = info {
133 target.insert(
134 "clientInfo".into(),
135 serde_json::to_value(info).map_err(crate::Error::into_internal_error)?,
136 );
137 }
138 if let Some(meta) = params.get("_meta") {
139 target.insert("_meta".into(), meta.clone());
140 }
141 retain_parsable_capabilities::<v1::ClientCapabilities>(&mut target, "clientCapabilities");
142 retain_object(&mut target, "_meta");
143 let initialize: v1::InitializeRequest =
144 serde_json::from_value(serde_json::Value::Object(target))?;
145 let serde_json::Value::Object(normalized) =
146 serde_json::to_value(initialize).map_err(crate::Error::into_internal_error)?
147 else {
148 return Err(crate::util::internal_error(
149 "initialize params did not serialize to an object",
150 ));
151 };
152 Ok(normalized)
153}
154
155#[cfg(feature = "unstable_protocol_v2")]
165#[derive(Debug, Clone, PartialEq, Eq)]
166#[non_exhaustive]
167pub enum InitializeOutcome {
168 Initialized(Box<crate::v2::schema::InitializeResponse>),
170 LowerVersion(InitializationVersionMismatch),
176}
177
178#[cfg(feature = "unstable_protocol_v2")]
189#[derive(Debug, Clone, PartialEq, Eq)]
190#[non_exhaustive]
191pub struct InitializationVersionMismatch {
192 pub requested: crate::schema::ProtocolVersion,
194 pub response: SelectedInitializeResponse,
197}
198
199#[cfg(feature = "unstable_protocol_v2")]
200impl InitializationVersionMismatch {
201 #[must_use]
206 pub fn new(
207 requested: crate::schema::ProtocolVersion,
208 response: SelectedInitializeResponse,
209 ) -> Self {
210 Self {
211 requested,
212 response,
213 }
214 }
215
216 #[must_use]
219 pub fn selected(&self) -> crate::schema::ProtocolVersion {
220 self.response.protocol_version()
221 }
222}
223
224#[cfg(feature = "unstable_protocol_v2")]
225impl std::fmt::Display for InitializationVersionMismatch {
226 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
227 write!(
228 f,
229 "requested ACP protocol version {} but peer selected {}",
230 self.requested,
231 self.selected(),
232 )
233 }
234}
235
236#[cfg(feature = "unstable_protocol_v2")]
244#[derive(Debug, Clone, PartialEq, Eq)]
245#[non_exhaustive]
246pub enum SelectedInitializeResponse {
247 V1(Box<crate::v1::schema::InitializeResponse>),
249}
250
251#[cfg(feature = "unstable_protocol_v2")]
252impl SelectedInitializeResponse {
253 #[must_use]
255 pub fn protocol_version(&self) -> crate::schema::ProtocolVersion {
256 match self {
257 Self::V1(response) => response.protocol_version,
258 }
259 }
260}
261
262#[cfg(feature = "unstable_protocol_v2")]
264fn parse_v1_selection(
265 version: crate::schema::ProtocolVersion,
266 value: serde_json::Value,
267) -> Option<crate::Result<crate::v1::schema::InitializeResponse>> {
268 (version == crate::schema::ProtocolVersion::V1).then(|| {
269 <crate::v1::schema::InitializeResponse as crate::JsonRpcResponse>::from_json(
270 "initialize",
271 value,
272 )
273 })
274}
275
276#[cfg(feature = "unstable_protocol_v2")]
277impl crate::JsonRpcResponse for InitializeOutcome {
278 fn into_json(self, method: &str) -> Result<serde_json::Value, crate::Error> {
279 match self {
280 Self::Initialized(response) => response.into_json(method),
281 Self::LowerVersion(mismatch) => match mismatch.response {
282 SelectedInitializeResponse::V1(response) => response.into_json(method),
283 },
284 }
285 }
286
287 fn from_json(method: &str, value: serde_json::Value) -> Result<Self, crate::Error> {
288 let selected: crate::schema::ProtocolVersion = value
289 .get("protocolVersion")
290 .cloned()
291 .map(serde_json::from_value)
292 .transpose()
293 .ok()
294 .flatten()
295 .ok_or_else(|| {
296 crate::Error::invalid_params()
297 .data("initialize.protocolVersion must be a valid ACP protocol version")
298 })?;
299 let requested = crate::schema::ProtocolVersion::V2;
300 if selected == requested {
301 return crate::v2::schema::InitializeResponse::from_json(method, value)
302 .map(|response| Self::Initialized(Box::new(response)));
303 }
304 match parse_v1_selection(selected, value) {
305 Some(response) => Ok(Self::LowerVersion(InitializationVersionMismatch::new(
306 requested,
307 SelectedInitializeResponse::V1(Box::new(response?)),
308 ))),
309 None => Err(crate::Error::invalid_request().data(format!(
310 "unsupported ACP protocol version {selected} in initialize response",
311 ))),
312 }
313 }
314}
315
316#[cfg(feature = "unstable_protocol_v2")]
321#[derive(Debug, Clone)]
322pub(crate) struct InitializeNegotiation(pub(crate) crate::v2::schema::InitializeRequest);
323
324#[cfg(feature = "unstable_protocol_v2")]
325impl crate::JsonRpcMessage for InitializeNegotiation {
326 fn matches_method(method: &str) -> bool {
327 crate::v2::schema::InitializeRequest::matches_method(method)
328 }
329
330 fn method(&self) -> &str {
331 self.0.method()
332 }
333
334 fn to_untyped_message(&self) -> Result<crate::UntypedMessage, crate::Error> {
335 self.0.to_untyped_message()
336 }
337
338 fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error> {
339 crate::v2::schema::InitializeRequest::parse_message(method, params).map(Self)
340 }
341}
342
343#[cfg(feature = "unstable_protocol_v2")]
344impl crate::JsonRpcRequest for InitializeNegotiation {
345 type Response = InitializeOutcome;
346}
347
348mod imp {
349 use std::sync::{Arc, Mutex};
350
351 use crate::RawJsonRpcId;
352 use crate::schema::ProtocolVersion;
353 use crate::{UntypedMessage, role::RemoteStyle};
354
355 #[derive(Clone, Copy, Debug)]
356 pub(crate) enum ProtocolMode {
357 Disabled,
358 Acp(AcpProtocolMode),
359 }
360
361 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
362 pub(crate) struct AcpProtocolMode {
363 api: ProtocolVersionKind,
364 initialize_surface: InitializeSurface,
365 initialization_role: InitializationRole,
366 requires_initialize: bool,
371 }
372
373 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
374 enum InitializeSurface {
375 Peer,
376 Proxy,
377 }
378
379 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
380 #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
381 enum InitializationRole {
382 Unchecked,
387 Initiator,
388 Responder,
389 }
390
391 impl AcpProtocolMode {
392 fn is_incoming_initialize_request(self, method: &str) -> bool {
393 match self.initialize_surface {
394 InitializeSurface::Peer => method == "initialize",
395 InitializeSurface::Proxy => method == "proxy/initialize",
396 }
397 }
398
399 fn is_incoming_initialize_response(method: &str) -> bool {
400 method == "initialize"
404 }
405
406 fn is_outgoing_initialize_response(self, method: &str) -> bool {
407 match self.initialize_surface {
408 InitializeSurface::Peer => method == "initialize",
409 InitializeSurface::Proxy => method == "proxy/initialize",
410 }
411 }
412 }
413
414 impl ProtocolMode {
415 pub(crate) fn disabled() -> Self {
416 Self::Disabled
417 }
418
419 pub(crate) fn v1_agent() -> Self {
420 Self::Acp(AcpProtocolMode {
421 api: ProtocolVersionKind::V1,
422 initialize_surface: InitializeSurface::Peer,
423 initialization_role: InitializationRole::Unchecked,
424 requires_initialize: false,
425 })
426 }
427
428 pub(crate) fn require_initialize(self) -> Self {
432 match self {
433 Self::Acp(mode)
434 if mode.api == ProtocolVersionKind::V1
435 && mode.initialize_surface == InitializeSurface::Peer =>
436 {
437 Self::Acp(AcpProtocolMode {
438 requires_initialize: true,
439 ..mode
440 })
441 }
442 mode => mode,
443 }
444 }
445
446 pub(crate) fn v1_client() -> Self {
447 Self::Acp(AcpProtocolMode {
448 api: ProtocolVersionKind::V1,
449 initialize_surface: InitializeSurface::Peer,
450 initialization_role: InitializationRole::Unchecked,
451 requires_initialize: false,
452 })
453 }
454
455 pub(crate) fn v1_proxy() -> Self {
456 Self::Acp(AcpProtocolMode {
457 api: ProtocolVersionKind::V1,
458 initialize_surface: InitializeSurface::Proxy,
459 initialization_role: InitializationRole::Unchecked,
460 requires_initialize: false,
461 })
462 }
463
464 #[cfg(feature = "unstable_protocol_v2")]
465 pub(crate) fn v2_agent() -> Self {
466 Self::Acp(AcpProtocolMode {
467 api: ProtocolVersionKind::V2,
468 initialize_surface: InitializeSurface::Peer,
469 initialization_role: InitializationRole::Responder,
470 requires_initialize: false,
471 })
472 }
473
474 #[cfg(feature = "unstable_protocol_v2")]
475 pub(crate) fn v2_client() -> Self {
476 Self::Acp(AcpProtocolMode {
477 api: ProtocolVersionKind::V2,
478 initialize_surface: InitializeSurface::Peer,
479 initialization_role: InitializationRole::Initiator,
480 requires_initialize: false,
481 })
482 }
483
484 #[cfg(feature = "unstable_protocol_v2")]
485 pub(crate) fn v2_proxy() -> Self {
486 Self::Acp(AcpProtocolMode {
487 api: ProtocolVersionKind::V2,
488 initialize_surface: InitializeSurface::Proxy,
489 initialization_role: InitializationRole::Unchecked,
490 requires_initialize: false,
491 })
492 }
493
494 pub(crate) fn merge(self, other: Self) -> Self {
495 match (self, other) {
496 (Self::Disabled, other) => other,
497 (this, Self::Disabled) => this,
498 (Self::Acp(this), Self::Acp(other)) => {
499 assert_eq!(
500 this.api, other.api,
501 "cannot merge ACP builders with different API protocol versions; \
502 handler chains share a single API surface",
503 );
504 assert_eq!(
505 this.initialize_surface, other.initialize_surface,
506 "cannot merge standard ACP and proxy ACP builders; \
507 handler chains share one initialization surface",
508 );
509 assert_eq!(
510 this.initialization_role, other.initialization_role,
511 "cannot merge ACP builders with different initialization roles; \
512 handler chains share one connection lifecycle",
513 );
514 Self::Acp(AcpProtocolMode {
515 requires_initialize: this.requires_initialize || other.requires_initialize,
516 ..this
517 })
518 }
519 }
520 }
521
522 pub(crate) fn api_protocol_version(self) -> Option<ProtocolVersion> {
523 match self {
524 Self::Disabled => None,
525 Self::Acp(mode) => Some(mode.api.as_protocol_version()),
526 }
527 }
528 }
529
530 #[derive(Clone, Debug)]
531 pub(crate) struct ProtocolCompat {
532 mode: Option<AcpProtocolMode>,
533 state: Arc<Mutex<ProtocolState>>,
534 }
535
536 #[derive(Debug)]
537 struct ProtocolState {
538 negotiated: ProtocolVersionKind,
539 pending_initialize: Option<ProtocolVersionKind>,
540 incoming_initialize_id: Option<RawJsonRpcId>,
541 initialization: InitializationState,
542 initialized: bool,
544 repeatable: bool,
551 }
552
553 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
554 enum InitializationState {
555 Unchecked,
556 Uninitialized,
557 Initializing,
558 Ready,
559 }
560
561 enum InitializeResponseCheck {
564 Negotiated(ProtocolVersionKind),
565 #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
567 LowerVersion,
568 }
569
570 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
571 enum ProtocolVersionKind {
572 V1,
573 V2,
574 }
575
576 impl ProtocolVersionKind {
577 fn as_protocol_version(self) -> ProtocolVersion {
578 match self {
579 Self::V1 => ProtocolVersion::V1,
580 Self::V2 => ProtocolVersion::from(2_u16),
581 }
582 }
583
584 fn from_protocol_version(version: ProtocolVersion) -> Option<Self> {
585 if version == ProtocolVersion::V1 {
586 Some(Self::V1)
587 } else if version == ProtocolVersion::from(2_u16) {
588 Some(Self::V2)
589 } else {
590 None
591 }
592 }
593 }
594
595 impl ProtocolCompat {
596 pub(crate) fn new(mode: ProtocolMode) -> Self {
597 let mode = match mode {
598 ProtocolMode::Disabled => None,
599 ProtocolMode::Acp(mode) => Some(mode),
600 };
601 let negotiated = mode.map_or(ProtocolVersionKind::V1, |mode| mode.api);
602 let initialization = match mode.map(|mode| mode.initialization_role) {
603 Some(InitializationRole::Initiator | InitializationRole::Responder) => {
604 InitializationState::Uninitialized
605 }
606 Some(InitializationRole::Unchecked) | None => InitializationState::Unchecked,
607 };
608
609 Self {
610 mode,
611 state: Arc::new(Mutex::new(ProtocolState {
612 negotiated,
613 pending_initialize: None,
614 incoming_initialize_id: None,
615 initialization,
616 initialized: false,
617 repeatable: false,
618 })),
619 }
620 }
621
622 #[cfg(all(test, feature = "unstable_protocol_v2"))]
623 pub(crate) fn incoming_message(
624 &self,
625 message: UntypedMessage,
626 ) -> Result<UntypedMessage, crate::Error> {
627 self.incoming_request(&RawJsonRpcId::Number(0), message)
628 }
629
630 pub(crate) fn incoming_request(
631 &self,
632 id: &RawJsonRpcId,
633 message: UntypedMessage,
634 ) -> Result<UntypedMessage, crate::Error> {
635 let Some(mode) = self.mode else {
636 return Ok(message);
637 };
638
639 if mode.api == ProtocolVersionKind::V2 && *id == RawJsonRpcId::Null {
643 return Err(crate::jsonrpc::raw_id::null_v2_request_id());
644 }
645
646 if mode.is_incoming_initialize_request(message.method()) {
647 return self.incoming_initialize_request(mode, id, message);
648 }
649 if mode.initialize_surface == InitializeSurface::Proxy
650 && (message.method() == "initialize" || successor_encloses_initialize(&message))
651 {
652 return Err(invalid_proxy_initialize_direction());
653 }
654
655 if mode.requires_initialize && !self.has_initialized() {
656 return Err(initialization_required(message.method()));
657 }
658 self.ensure_initialized(message.method())?;
659 ensure_matching_protocol_version(
660 message.method(),
661 self.active_wire_version(),
662 mode.api,
663 )?;
664 if mode.initialization_role == InitializationRole::Responder {
665 self.close_repeat_window();
666 }
667 Ok(message)
668 }
669
670 pub(crate) fn outgoing_message(
671 &self,
672 mut message: UntypedMessage,
673 remote_style: RemoteStyle,
674 ) -> Result<UntypedMessage, crate::Error> {
675 let Some(mode) = self.mode else {
676 return Ok(message);
677 };
678
679 let wire_version = if let Some(params) =
680 outgoing_initialize_params(mode, remote_style, &mut message)?
681 {
682 prepare_initialize_request(mode, params)?;
683 self.begin_outgoing_initialize(mode)?;
684 mode.api
685 } else {
686 self.ensure_initialized(message.method())?;
687 self.active_wire_version()
688 };
689
690 ensure_matching_protocol_version(message.method(), mode.api, wire_version)?;
691 if mode.initialization_role == InitializationRole::Initiator {
692 self.close_repeat_window();
693 }
694 Ok(message)
695 }
696
697 pub(crate) fn incoming_notification(
698 &self,
699 message: UntypedMessage,
700 ) -> Result<Vec<UntypedMessage>, crate::Error> {
701 let Some(mode) = self.mode else {
702 return Ok(vec![message]);
703 };
704
705 self.ensure_notification_allowed(message.method())?;
706 ensure_matching_protocol_version(
707 message.method(),
708 self.active_wire_version(),
709 mode.api,
710 )?;
711 Ok(vec![message])
712 }
713
714 pub(crate) fn outgoing_notification(
715 &self,
716 message: UntypedMessage,
717 ) -> Result<Vec<UntypedMessage>, crate::Error> {
718 let Some(mode) = self.mode else {
719 return Ok(vec![message]);
720 };
721
722 self.ensure_notification_allowed(message.method())?;
723 ensure_matching_protocol_version(
724 message.method(),
725 mode.api,
726 self.active_wire_version(),
727 )?;
728 Ok(vec![message])
729 }
730
731 pub(crate) fn incoming_response(
737 &self,
738 method: &str,
739 accepts_lower_version: bool,
740 result: Result<serde_json::Value, crate::Error>,
741 ) -> Result<serde_json::Value, crate::Error> {
742 let Some(mode) = self.mode else {
743 return result;
744 };
745
746 if AcpProtocolMode::is_incoming_initialize_response(method) {
747 return self.incoming_initialize_response(mode, accepts_lower_version, result);
748 }
749
750 let value = result?;
751 self.ensure_initialized(method)?;
752 ensure_matching_protocol_version(method, self.active_wire_version(), mode.api)?;
753 Ok(value)
754 }
755
756 #[cfg(all(test, feature = "unstable_protocol_v2"))]
757 pub(crate) fn outgoing_response(
758 &self,
759 method: &str,
760 result: Result<serde_json::Value, crate::Error>,
761 ) -> Result<serde_json::Value, crate::Error> {
762 self.outgoing_response_to(&RawJsonRpcId::Number(0), method, result)
763 }
764
765 pub(crate) fn outgoing_response_to(
766 &self,
767 id: &RawJsonRpcId,
768 method: &str,
769 result: Result<serde_json::Value, crate::Error>,
770 ) -> Result<serde_json::Value, crate::Error> {
771 let Some(mode) = self.mode else {
772 return result;
773 };
774
775 if mode.is_outgoing_initialize_response(method) {
776 match mode.initialization_role {
777 InitializationRole::Initiator => {
778 return result.and_then(|_| {
779 Err(unexpected_initialize_response(mode.initialization_role))
780 });
781 }
782 InitializationRole::Responder if !self.is_pending_incoming_initialize(id) => {
783 return result.and_then(|_| {
784 Err(unexpected_initialize_response(mode.initialization_role))
785 });
786 }
787 InitializationRole::Unchecked | InitializationRole::Responder => {}
788 }
789 let mut value = match result {
790 Ok(value) => value,
791 Err(error) => {
792 self.fail_initialize();
793 return Err(error);
794 }
795 };
796 let negotiated = self.pending_initialize().or_else(|| {
797 (mode.initialization_role == InitializationRole::Unchecked).then_some(mode.api)
798 });
799 let negotiated = negotiated
800 .ok_or_else(|| unexpected_initialize_response(mode.initialization_role))?;
801 if let Err(error) = ensure_matching_protocol_version(method, mode.api, negotiated)
802 .and_then(|()| prepare_initialize_response(mode, &mut value))
803 {
804 self.fail_initialize();
805 return Err(error);
806 }
807 self.complete_initialize(negotiated)?;
808 return Ok(value);
809 }
810
811 let value = result?;
812 self.ensure_initialized(method)?;
813 let wire_version = self.active_wire_version();
814
815 ensure_matching_protocol_version(method, mode.api, wire_version)?;
816 Ok(value)
817 }
818
819 fn incoming_initialize_request(
820 &self,
821 mode: AcpProtocolMode,
822 id: &RawJsonRpcId,
823 mut message: UntypedMessage,
824 ) -> Result<UntypedMessage, crate::Error> {
825 let requested = required_protocol_version_from_value(message.params())?;
826 #[cfg(feature = "unstable_protocol_v2")]
837 if mode.api == ProtocolVersionKind::V2 && requested < mode.api.as_protocol_version() {
838 return Err(crate::v2::schema::Error::unsupported_protocol_version(
839 requested,
840 &[mode.api.as_protocol_version()],
841 )
842 .into());
843 }
844 if mode.api == ProtocolVersionKind::V1 && requested > ProtocolVersion::V1 {
845 message.params = serde_json::Value::Object(super::normalize_v1_initialize_request(
846 message.params(),
847 )?);
848 }
849 #[cfg(feature = "unstable_protocol_v2")]
852 if mode.api == ProtocolVersionKind::V2 && requested > mode.api.as_protocol_version() {
853 let serde_json::Value::Object(params) = message.params() else {
854 return Err(invalid_initialize_protocol_version());
855 };
856 message.params = serde_json::Value::Object(
857 super::normalize_newer_v2_initialize_request(params)?,
858 );
859 }
860
861 prepare_initialize_request(mode, &mut message.params)?;
862 self.begin_incoming_initialize(mode, id)?;
863 Ok(message)
864 }
865
866 fn incoming_initialize_response(
867 &self,
868 mode: AcpProtocolMode,
869 accepts_lower_version: bool,
870 result: Result<serde_json::Value, crate::Error>,
871 ) -> Result<serde_json::Value, crate::Error> {
872 let mut value = match result {
873 Ok(value) => value,
874 Err(error) => {
875 self.fail_initialize();
876 return Err(error);
877 }
878 };
879 let response = (|| {
880 let pending = self.pending_initialize().or_else(|| {
881 (mode.initialization_role == InitializationRole::Unchecked).then_some(mode.api)
882 });
883 let pending = pending
884 .ok_or_else(|| unexpected_initialize_response(mode.initialization_role))?;
885 let response_version = required_protocol_version_from_value(&value)?;
886 let wire_version = ProtocolVersionKind::from_protocol_version(response_version)
887 .ok_or_else(|| unsupported_protocol_version(response_version, mode.api))?;
888 #[cfg(feature = "unstable_protocol_v2")]
893 if accepts_lower_version
894 && mode.initialization_role == InitializationRole::Initiator
895 && wire_version < mode.api
896 && let Some(response) =
897 super::parse_v1_selection(wire_version.as_protocol_version(), value.clone())
898 {
899 response?;
900 return Ok(InitializeResponseCheck::LowerVersion);
901 }
902 #[cfg(not(feature = "unstable_protocol_v2"))]
903 let _ = accepts_lower_version;
904 if wire_version != mode.api {
905 return Err(required_protocol_version(mode.api, wire_version));
906 }
907 ensure_matching_protocol_version("initialize", pending, wire_version)?;
908 prepare_initialize_response(mode, &mut value)?;
909 Ok(InitializeResponseCheck::Negotiated(wire_version))
910 })();
911
912 match response {
913 Ok(InitializeResponseCheck::Negotiated(wire_version)) => {
914 self.complete_initialize(wire_version)?;
915 Ok(value)
916 }
917 Ok(InitializeResponseCheck::LowerVersion) => {
920 self.fail_initialize();
921 Ok(value)
922 }
923 Err(error) => {
924 self.fail_initialize();
925 Err(error)
926 }
927 }
928 }
929
930 fn begin_incoming_initialize(
931 &self,
932 mode: AcpProtocolMode,
933 id: &RawJsonRpcId,
934 ) -> Result<(), crate::Error> {
935 match mode.initialization_role {
936 InitializationRole::Initiator => return Err(invalid_initialize_direction()),
937 InitializationRole::Unchecked | InitializationRole::Responder => {}
938 }
939 self.begin_initialize(mode.api, Some(id))
940 }
941
942 fn begin_outgoing_initialize(&self, mode: AcpProtocolMode) -> Result<(), crate::Error> {
943 match mode.initialization_role {
944 InitializationRole::Responder => return Err(invalid_initialize_direction()),
945 InitializationRole::Unchecked | InitializationRole::Initiator => {}
946 }
947 self.begin_initialize(mode.api, None)
948 }
949
950 fn begin_initialize(
951 &self,
952 requested: ProtocolVersionKind,
953 incoming_id: Option<&RawJsonRpcId>,
954 ) -> Result<(), crate::Error> {
955 let mut state = self
956 .state
957 .lock()
958 .expect("protocol compatibility state mutex poisoned");
959 match state.initialization {
960 InitializationState::Unchecked => {
961 state.pending_initialize = Some(requested);
962 Ok(())
963 }
964 InitializationState::Uninitialized => {
965 state.initialization = InitializationState::Initializing;
966 state.pending_initialize = Some(requested);
967 state.incoming_initialize_id = incoming_id.cloned();
968 Ok(())
969 }
970 InitializationState::Initializing => Err(crate::Error::invalid_request()
971 .data("ACP initialization is already in progress on this connection")),
972 InitializationState::Ready if state.repeatable => {
975 state.initialization = InitializationState::Initializing;
976 state.repeatable = false;
977 state.pending_initialize = Some(requested);
978 state.incoming_initialize_id = incoming_id.cloned();
979 Ok(())
980 }
981 InitializationState::Ready => Err(crate::Error::invalid_request().data(
982 "ACP initialization cannot be repeated after any other request; reconnect to initialize again",
983 )),
984 }
985 }
986
987 fn close_repeat_window(&self) {
989 self.state
990 .lock()
991 .expect("protocol compatibility state mutex poisoned")
992 .repeatable = false;
993 }
994
995 fn ensure_initialized(&self, method: &str) -> Result<(), crate::Error> {
996 let state = self
997 .state
998 .lock()
999 .expect("protocol compatibility state mutex poisoned")
1000 .initialization;
1001 match state {
1002 InitializationState::Unchecked | InitializationState::Ready => Ok(()),
1003 InitializationState::Uninitialized | InitializationState::Initializing => {
1004 Err(initialization_required(method))
1005 }
1006 }
1007 }
1008
1009 fn ensure_notification_allowed(&self, method: &str) -> Result<(), crate::Error> {
1010 let initialization = self
1011 .state
1012 .lock()
1013 .expect("protocol compatibility state mutex poisoned")
1014 .initialization;
1015 if initialization == InitializationState::Initializing && method == "$/cancel_request" {
1016 return Ok(());
1017 }
1018 self.ensure_initialized(method)
1019 }
1020
1021 fn complete_initialize(&self, negotiated: ProtocolVersionKind) -> Result<(), crate::Error> {
1022 let mut state = self
1023 .state
1024 .lock()
1025 .expect("protocol compatibility state mutex poisoned");
1026 if state.pending_initialize.is_none()
1027 && state.initialization != InitializationState::Unchecked
1028 {
1029 return Err(unexpected_initialize_response(
1030 self.mode
1031 .expect("protocol initialization requires an ACP mode")
1032 .initialization_role,
1033 ));
1034 }
1035 if !matches!(
1036 state.initialization,
1037 InitializationState::Unchecked | InitializationState::Initializing
1038 ) {
1039 return Err(unexpected_initialize_response(
1040 self.mode
1041 .expect("protocol initialization requires an ACP mode")
1042 .initialization_role,
1043 ));
1044 }
1045 state.pending_initialize = None;
1046 state.incoming_initialize_id = None;
1047 state.negotiated = negotiated;
1048 state.initialized = true;
1049 if state.initialization == InitializationState::Initializing {
1050 state.initialization = InitializationState::Ready;
1051 state.repeatable = true;
1052 }
1053 Ok(())
1054 }
1055
1056 fn fail_initialize(&self) {
1057 let mut state = self
1058 .state
1059 .lock()
1060 .expect("protocol compatibility state mutex poisoned");
1061 state.pending_initialize = None;
1062 state.incoming_initialize_id = None;
1063 if state.initialization == InitializationState::Initializing {
1064 if state.initialized {
1067 state.initialization = InitializationState::Ready;
1068 state.repeatable = true;
1069 } else {
1070 state.initialization = InitializationState::Uninitialized;
1071 }
1072 }
1073 }
1074
1075 fn has_initialized(&self) -> bool {
1076 self.state
1077 .lock()
1078 .expect("protocol compatibility state mutex poisoned")
1079 .initialized
1080 }
1081
1082 fn is_pending_incoming_initialize(&self, id: &RawJsonRpcId) -> bool {
1083 self.state
1084 .lock()
1085 .expect("protocol compatibility state mutex poisoned")
1086 .incoming_initialize_id
1087 .as_ref()
1088 == Some(id)
1089 }
1090
1091 fn active_wire_version(&self) -> ProtocolVersionKind {
1092 let state = self
1093 .state
1094 .lock()
1095 .expect("protocol compatibility state mutex poisoned");
1096 state.pending_initialize.unwrap_or(state.negotiated)
1097 }
1098
1099 fn pending_initialize(&self) -> Option<ProtocolVersionKind> {
1100 self.state
1101 .lock()
1102 .expect("protocol compatibility state mutex poisoned")
1103 .pending_initialize
1104 }
1105 }
1106
1107 fn required_protocol_version_from_value(
1108 value: &serde_json::Value,
1109 ) -> Result<ProtocolVersion, crate::Error> {
1110 let Some(version) = value.get("protocolVersion") else {
1111 return Err(invalid_initialize_protocol_version());
1112 };
1113
1114 serde_json::from_value(version.clone()).map_err(|_| invalid_initialize_protocol_version())
1115 }
1116
1117 fn outgoing_initialize_params(
1118 mode: AcpProtocolMode,
1119 remote_style: RemoteStyle,
1120 message: &mut UntypedMessage,
1121 ) -> Result<Option<&mut serde_json::Value>, crate::Error> {
1122 if successor_encloses_initialize(message) {
1123 return Err(invalid_prewrapped_initialize());
1124 }
1125
1126 match mode.initialize_surface {
1127 InitializeSurface::Peer => {
1128 Ok((message.method() == "initialize").then_some(&mut message.params))
1129 }
1130 InitializeSurface::Proxy => {
1131 if message.method() == "initialize" {
1132 if remote_style != RemoteStyle::Successor {
1133 return Err(invalid_proxy_initialize_direction());
1134 }
1135 return Ok(Some(&mut message.params));
1136 }
1137 if message.method() == "proxy/initialize" {
1138 return Err(invalid_proxy_initialize_direction());
1139 }
1140 Ok(None)
1141 }
1142 }
1143 }
1144
1145 fn successor_encloses_initialize(message: &UntypedMessage) -> bool {
1146 let mut method = message.method();
1147 let mut params = message.params();
1148 let mut wrapped = false;
1149
1150 while method == "proxy/successor" {
1151 wrapped = true;
1152 let Some(inner_method) = params.get("method").and_then(serde_json::Value::as_str)
1153 else {
1154 return false;
1155 };
1156 method = inner_method;
1157 if method == "proxy/successor" {
1158 let Some(inner_params) = params.get("params") else {
1159 return false;
1160 };
1161 params = inner_params;
1162 }
1163 }
1164
1165 wrapped && matches!(method, "initialize" | "proxy/initialize")
1166 }
1167
1168 fn invalid_initialize_protocol_version() -> crate::Error {
1169 crate::Error::invalid_params()
1170 .data("initialize.protocolVersion must be a valid ACP protocol version")
1171 }
1172
1173 fn initialization_required(method: &str) -> crate::Error {
1174 crate::Error::invalid_request().data(format!(
1175 "ACP initialization must complete before `{method}` can be used",
1176 ))
1177 }
1178
1179 fn invalid_initialize_direction() -> crate::Error {
1180 crate::Error::invalid_request()
1181 .data("ACP clients send `initialize` requests and ACP agents respond to them")
1182 }
1183
1184 fn unexpected_initialize_response(role: InitializationRole) -> crate::Error {
1185 let detail = match role {
1186 InitializationRole::Initiator => "before an initialize request is pending",
1187 InitializationRole::Responder => "before an initialize request was received",
1188 InitializationRole::Unchecked => "without a pending initialize request",
1189 };
1190 crate::Error::invalid_request().data(format!("received an initialize response {detail}"))
1191 }
1192
1193 fn invalid_proxy_initialize_direction() -> crate::Error {
1194 crate::Error::invalid_request().data(
1195 "proxy initialization must arrive as `proxy/initialize`; outgoing `initialize` must target the successor so the connection can apply `proxy/successor`",
1196 )
1197 }
1198
1199 fn invalid_prewrapped_initialize() -> crate::Error {
1200 crate::Error::invalid_request().data(
1201 "initialize requests must be sent as a logical `initialize` message; `proxy/successor` wrapping is applied by connection routing",
1202 )
1203 }
1204
1205 fn set_protocol_version(
1206 value: &mut serde_json::Value,
1207 version: ProtocolVersionKind,
1208 ) -> Result<(), crate::Error> {
1209 let serde_json::Value::Object(object) = value else {
1210 return Err(invalid_initialize_protocol_version());
1211 };
1212 object.insert(
1213 "protocolVersion".into(),
1214 serde_json::to_value(version.as_protocol_version())
1215 .map_err(crate::Error::into_internal_error)?,
1216 );
1217 Ok(())
1218 }
1219
1220 fn prepare_initialize_request(
1221 mode: AcpProtocolMode,
1222 value: &mut serde_json::Value,
1223 ) -> Result<(), crate::Error> {
1224 set_protocol_version(value, mode.api)?;
1225 #[cfg(feature = "unstable_protocol_v2")]
1226 if mode.initialization_role != InitializationRole::Unchecked {
1227 <crate::v2::schema::InitializeRequest as crate::JsonRpcMessage>::parse_message(
1228 "initialize",
1229 value,
1230 )?;
1231 }
1232 Ok(())
1233 }
1234
1235 fn prepare_initialize_response(
1236 mode: AcpProtocolMode,
1237 value: &mut serde_json::Value,
1238 ) -> Result<(), crate::Error> {
1239 set_protocol_version(value, mode.api)?;
1240 #[cfg(feature = "unstable_protocol_v2")]
1241 if mode.initialization_role != InitializationRole::Unchecked {
1242 <crate::v2::schema::InitializeResponse as crate::JsonRpcResponse>::from_json(
1243 "initialize",
1244 value.clone(),
1245 )?;
1246 }
1247 Ok(())
1248 }
1249
1250 fn ensure_matching_protocol_version(
1251 method: &str,
1252 from: ProtocolVersionKind,
1253 to: ProtocolVersionKind,
1254 ) -> Result<(), crate::Error> {
1255 if from == to {
1256 return Ok(());
1257 }
1258
1259 Err(crate::Error::invalid_request().data(format!(
1260 "ACP protocol translation from {} to {} is not supported for `{method}`; register a handler for the negotiated protocol version",
1261 from.as_protocol_version(),
1262 to.as_protocol_version(),
1263 )))
1264 }
1265
1266 fn unsupported_protocol_version(
1267 version: ProtocolVersion,
1268 supported: ProtocolVersionKind,
1269 ) -> crate::Error {
1270 crate::Error::invalid_request().data(format!(
1271 "unsupported ACP protocol version {version}; this endpoint only supports ACP protocol version {}",
1272 supported.as_protocol_version(),
1273 ))
1274 }
1275
1276 fn required_protocol_version(
1277 required: ProtocolVersionKind,
1278 negotiated: ProtocolVersionKind,
1279 ) -> crate::Error {
1280 crate::Error::invalid_request().data(format!(
1281 "required ACP protocol version {} but peer negotiated {}; use a matching implementation for the negotiated protocol version",
1282 required.as_protocol_version(),
1283 negotiated.as_protocol_version(),
1284 ))
1285 }
1286
1287 #[cfg(all(test, feature = "unstable_protocol_v2"))]
1288 mod tests {
1289 use super::*;
1290 use agent_client_protocol_schema::v2;
1291
1292 fn negotiated(compat: &ProtocolCompat) -> ProtocolVersionKind {
1293 compat
1294 .state
1295 .lock()
1296 .expect("protocol compatibility state mutex poisoned")
1297 .negotiated
1298 }
1299
1300 fn pending_initialize(compat: &ProtocolCompat) -> Option<ProtocolVersionKind> {
1301 compat
1302 .state
1303 .lock()
1304 .expect("protocol compatibility state mutex poisoned")
1305 .pending_initialize
1306 }
1307
1308 fn initialization_state(compat: &ProtocolCompat) -> InitializationState {
1309 compat
1310 .state
1311 .lock()
1312 .expect("protocol compatibility state mutex poisoned")
1313 .initialization
1314 }
1315
1316 fn v2_implementation() -> v2::Implementation {
1317 v2::Implementation::new("protocol-compat-test", env!("CARGO_PKG_VERSION"))
1318 }
1319
1320 fn v2_initialize_request(protocol_version: ProtocolVersion) -> v2::InitializeRequest {
1321 v2::InitializeRequest::new(protocol_version, v2_implementation())
1322 }
1323
1324 fn v2_initialize_response(protocol_version: ProtocolVersion) -> v2::InitializeResponse {
1325 v2::InitializeResponse::new(protocol_version, v2_implementation())
1326 }
1327
1328 #[test]
1329 fn initialize_request_sets_active_wire_version_before_response() -> Result<(), crate::Error>
1330 {
1331 let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
1332 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1333 assert_eq!(
1334 initialization_state(&compat),
1335 InitializationState::Uninitialized
1336 );
1337
1338 compat.incoming_message(UntypedMessage::new(
1339 "initialize",
1340 v2_initialize_request(ProtocolVersion::V2),
1341 )?)?;
1342
1343 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1344 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1345 assert_eq!(
1346 initialization_state(&compat),
1347 InitializationState::Initializing
1348 );
1349
1350 compat.outgoing_response(
1351 "initialize",
1352 Ok(serde_json::to_value(v2_initialize_response(
1353 ProtocolVersion::V2,
1354 ))?),
1355 )?;
1356
1357 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1358 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1359 assert_eq!(initialization_state(&compat), InitializationState::Ready);
1360 Ok(())
1361 }
1362
1363 #[test]
1364 fn outgoing_initialize_sets_active_wire_version_before_response() -> Result<(), crate::Error>
1365 {
1366 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1367 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1368 assert_eq!(
1369 initialization_state(&compat),
1370 InitializationState::Uninitialized
1371 );
1372
1373 compat.outgoing_message(
1374 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1375 RemoteStyle::Counterpart,
1376 )?;
1377
1378 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1379 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1380 assert_eq!(
1381 initialization_state(&compat),
1382 InitializationState::Initializing
1383 );
1384
1385 compat.incoming_response(
1386 "initialize",
1387 false,
1388 Ok(serde_json::to_value(v2_initialize_response(
1389 ProtocolVersion::V2,
1390 ))?),
1391 )?;
1392
1393 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1394 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1395 assert_eq!(initialization_state(&compat), InitializationState::Ready);
1396 Ok(())
1397 }
1398
1399 #[test]
1400 fn failed_incoming_initialize_response_clears_pending_wire_version()
1401 -> Result<(), crate::Error> {
1402 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1403 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1404
1405 compat.outgoing_message(
1406 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1407 RemoteStyle::Counterpart,
1408 )?;
1409
1410 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1411 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1412
1413 let result = compat.incoming_response(
1414 "initialize",
1415 false,
1416 Err(crate::Error::invalid_request().data("initialize failed")),
1417 );
1418
1419 assert!(result.is_err());
1420 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1421 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1422 assert_eq!(
1423 initialization_state(&compat),
1424 InitializationState::Uninitialized
1425 );
1426 compat.outgoing_message(
1427 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1428 RemoteStyle::Counterpart,
1429 )?;
1430 assert_eq!(
1431 initialization_state(&compat),
1432 InitializationState::Initializing
1433 );
1434 Ok(())
1435 }
1436
1437 #[test]
1438 fn incoming_initialize_response_requires_protocol_version() -> Result<(), crate::Error> {
1439 for value in [
1440 serde_json::json!({}),
1441 serde_json::json!({ "protocolVersion": 100_000 }),
1442 ] {
1443 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1444 compat.outgoing_message(
1445 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1446 RemoteStyle::Counterpart,
1447 )?;
1448
1449 let error = compat
1450 .incoming_response("initialize", false, Ok(value))
1451 .expect_err("initialize responses must declare an ACP protocol version");
1452 let data = error
1453 .data
1454 .as_ref()
1455 .and_then(|data| data.as_str())
1456 .unwrap_or_default();
1457 assert!(data.contains("protocolVersion"), "{error:?}");
1458 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1459 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1460 assert_eq!(
1461 initialization_state(&compat),
1462 InitializationState::Uninitialized
1463 );
1464 }
1465
1466 Ok(())
1467 }
1468
1469 fn v2_client_receiving(
1472 negotiation: bool,
1473 response: Result<serde_json::Value, crate::Error>,
1474 ) -> Result<(ProtocolCompat, Result<serde_json::Value, crate::Error>), crate::Error>
1475 {
1476 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1477 compat.outgoing_message(
1478 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1479 RemoteStyle::Counterpart,
1480 )?;
1481 let result = compat.incoming_response("initialize", negotiation, response);
1482 Ok((compat, result))
1483 }
1484
1485 fn v1_initialize_response() -> crate::v1::schema::InitializeResponse {
1486 crate::v1::schema::InitializeResponse::new(ProtocolVersion::V1)
1487 .agent_info(crate::v1::schema::Implementation::new("v1-agent", "1.0.0"))
1488 }
1489
1490 #[test]
1491 fn plain_initialize_request_rejects_lower_version() -> Result<(), crate::Error> {
1492 let (compat, result) =
1493 v2_client_receiving(false, Ok(serde_json::to_value(v1_initialize_response())?))?;
1494 let error = result.expect_err("send_request keeps the local version guard");
1495 let data = error
1496 .data
1497 .as_ref()
1498 .and_then(|data| data.as_str())
1499 .unwrap_or_default();
1500 assert!(data.contains("peer negotiated 1"), "{error:?}");
1501 assert_eq!(
1502 initialization_state(&compat),
1503 InitializationState::Uninitialized
1504 );
1505 Ok(())
1506 }
1507
1508 #[test]
1509 fn initialize_negotiation_receives_lower_version_as_success() -> Result<(), crate::Error> {
1510 let v1_response = serde_json::to_value(v1_initialize_response())?;
1511 let (compat, result) = v2_client_receiving(true, Ok(v1_response.clone()))?;
1512 assert_eq!(result?, v1_response);
1513
1514 assert_eq!(
1516 initialization_state(&compat),
1517 InitializationState::Uninitialized
1518 );
1519 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1520 compat
1521 .outgoing_message(
1522 UntypedMessage::new("session/new", serde_json::json!({}))?,
1523 RemoteStyle::Counterpart,
1524 )
1525 .expect_err("v2 traffic still requires a v2 handshake");
1526 compat.outgoing_message(
1527 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1528 RemoteStyle::Counterpart,
1529 )?;
1530 Ok(())
1531 }
1532
1533 #[test]
1534 fn initialize_negotiation_keeps_failures_as_errors() -> Result<(), crate::Error> {
1535 let remote: crate::Error = crate::v2::schema::Error::unsupported_protocol_version(
1536 ProtocolVersion::V2,
1537 &[ProtocolVersion::V1],
1538 )
1539 .into();
1540 let (compat, result) = v2_client_receiving(true, Err(remote.clone()))?;
1541 assert_eq!(result, Err(remote));
1542 assert_eq!(
1543 initialization_state(&compat),
1544 InitializationState::Uninitialized
1545 );
1546
1547 for malformed in [
1548 serde_json::json!({}),
1549 serde_json::json!({ "protocolVersion": "one" }),
1550 serde_json::json!({ "protocolVersion": 0 }),
1551 ] {
1552 let (compat, result) = v2_client_receiving(true, Ok(malformed))?;
1553 result.expect_err("malformed initialize responses are errors");
1554 assert_eq!(
1555 initialization_state(&compat),
1556 InitializationState::Uninitialized
1557 );
1558 }
1559 Ok(())
1560 }
1561
1562 #[test]
1563 fn initialize_negotiation_does_not_change_proxies() -> Result<(), crate::Error> {
1564 let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
1565 compat.outgoing_message(
1566 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1567 RemoteStyle::Successor,
1568 )?;
1569 compat
1570 .incoming_response(
1571 "initialize",
1572 true,
1573 Ok(serde_json::to_value(v1_initialize_response())?),
1574 )
1575 .expect_err("only a client's own handshake can report a lower version");
1576 Ok(())
1577 }
1578
1579 #[test]
1580 fn initialize_outcome_round_trips_by_selected_version() -> Result<(), crate::Error> {
1581 use super::super::{
1582 InitializationVersionMismatch, InitializeOutcome, SelectedInitializeResponse,
1583 };
1584 use crate::JsonRpcResponse as _;
1585
1586 let v2_response = v2_initialize_response(ProtocolVersion::V2);
1587 let wire = serde_json::to_value(&v2_response)?;
1588 let outcome = InitializeOutcome::from_json("initialize", wire.clone())?;
1589 assert_eq!(
1590 outcome,
1591 InitializeOutcome::Initialized(Box::new(v2_response))
1592 );
1593 assert_eq!(outcome.into_json("initialize")?, wire);
1594
1595 let v1_response = v1_initialize_response();
1596 let wire = serde_json::to_value(&v1_response)?;
1597 let outcome = InitializeOutcome::from_json("initialize", wire.clone())?;
1598 assert_eq!(
1599 outcome,
1600 InitializeOutcome::LowerVersion(InitializationVersionMismatch::new(
1601 ProtocolVersion::V2,
1602 SelectedInitializeResponse::V1(Box::new(v1_response)),
1603 ))
1604 );
1605 let InitializeOutcome::LowerVersion(mismatch) = &outcome else {
1606 unreachable!();
1607 };
1608 assert_eq!(mismatch.requested, ProtocolVersion::V2);
1609 assert_eq!(mismatch.selected(), ProtocolVersion::V1);
1610 assert_eq!(outcome.into_json("initialize")?, wire);
1611
1612 for value in [
1613 serde_json::json!({}),
1614 serde_json::json!({ "protocolVersion": 3 }),
1615 ] {
1616 InitializeOutcome::from_json("initialize", value)
1617 .expect_err("only v2 and lower known versions are outcomes");
1618 }
1619 Ok(())
1620 }
1621
1622 #[test]
1623 fn malformed_v2_initialize_requests_do_not_begin_a_handshake() -> Result<(), crate::Error> {
1624 let malformed = serde_json::json!({ "protocolVersion": ProtocolVersion::V2 });
1625
1626 let client = ProtocolCompat::new(ProtocolMode::v2_client());
1627 client
1628 .outgoing_message(
1629 UntypedMessage::new("initialize", malformed.clone())?,
1630 RemoteStyle::Counterpart,
1631 )
1632 .expect_err("native v2 clients must send the complete initialize request shape");
1633 assert_eq!(
1634 initialization_state(&client),
1635 InitializationState::Uninitialized
1636 );
1637 client.outgoing_message(
1638 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1639 RemoteStyle::Counterpart,
1640 )?;
1641 assert_eq!(
1642 initialization_state(&client),
1643 InitializationState::Initializing
1644 );
1645
1646 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1647 agent
1648 .incoming_message(UntypedMessage::new("initialize", malformed)?)
1649 .expect_err("native v2 agents must receive the complete initialize request shape");
1650 assert_eq!(
1651 initialization_state(&agent),
1652 InitializationState::Uninitialized
1653 );
1654 agent.incoming_message(UntypedMessage::new(
1655 "initialize",
1656 v2_initialize_request(ProtocolVersion::V2),
1657 )?)?;
1658 assert_eq!(
1659 initialization_state(&agent),
1660 InitializationState::Initializing
1661 );
1662 Ok(())
1663 }
1664
1665 #[test]
1666 fn malformed_v2_initialize_success_leaves_client_uninitialized_for_retry()
1667 -> Result<(), crate::Error> {
1668 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1669 compat.outgoing_message(
1670 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1671 RemoteStyle::Counterpart,
1672 )?;
1673
1674 compat
1675 .incoming_response(
1676 "initialize",
1677 false,
1678 Ok(serde_json::json!({ "protocolVersion": ProtocolVersion::V2 })),
1679 )
1680 .expect_err("initialize success must contain the complete v2 response shape");
1681 assert_eq!(
1682 initialization_state(&compat),
1683 InitializationState::Uninitialized
1684 );
1685 assert_eq!(pending_initialize(&compat), None);
1686
1687 compat.outgoing_message(
1688 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1689 RemoteStyle::Counterpart,
1690 )?;
1691 assert_eq!(
1692 initialization_state(&compat),
1693 InitializationState::Initializing
1694 );
1695 Ok(())
1696 }
1697
1698 #[test]
1699 fn malformed_v2_initialize_success_leaves_agent_uninitialized_for_retry()
1700 -> Result<(), crate::Error> {
1701 let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
1702 compat.incoming_message(UntypedMessage::new(
1703 "initialize",
1704 v2_initialize_request(ProtocolVersion::V2),
1705 )?)?;
1706
1707 compat
1708 .outgoing_response(
1709 "initialize",
1710 Ok(serde_json::json!({ "protocolVersion": ProtocolVersion::V2 })),
1711 )
1712 .expect_err("initialize success must contain the complete v2 response shape");
1713 assert_eq!(
1714 initialization_state(&compat),
1715 InitializationState::Uninitialized
1716 );
1717 assert_eq!(pending_initialize(&compat), None);
1718
1719 compat.incoming_message(UntypedMessage::new(
1720 "initialize",
1721 v2_initialize_request(ProtocolVersion::V2),
1722 )?)?;
1723 assert_eq!(
1724 initialization_state(&compat),
1725 InitializationState::Initializing
1726 );
1727 Ok(())
1728 }
1729
1730 #[test]
1731 fn v2_peer_traffic_requires_completed_initialization() -> Result<(), crate::Error> {
1732 for compat in [
1733 ProtocolCompat::new(ProtocolMode::v2_agent()),
1734 ProtocolCompat::new(ProtocolMode::v2_client()),
1735 ] {
1736 for error in [
1737 compat
1738 .incoming_message(UntypedMessage::new(
1739 "session/new",
1740 serde_json::json!({}),
1741 )?)
1742 .expect_err("incoming requests must wait for initialization"),
1743 compat
1744 .outgoing_message(
1745 UntypedMessage::new("session/new", serde_json::json!({}))?,
1746 RemoteStyle::Counterpart,
1747 )
1748 .expect_err("outgoing requests must wait for initialization"),
1749 compat
1750 .incoming_notification(UntypedMessage::new(
1751 "session/update",
1752 serde_json::json!({}),
1753 )?)
1754 .expect_err("incoming notifications must wait for initialization"),
1755 compat
1756 .outgoing_notification(UntypedMessage::new(
1757 "session/update",
1758 serde_json::json!({}),
1759 )?)
1760 .expect_err("outgoing notifications must wait for initialization"),
1761 compat
1762 .incoming_response("session/new", false, Ok(serde_json::json!({})))
1763 .expect_err("incoming responses must wait for initialization"),
1764 compat
1765 .outgoing_response("session/new", Ok(serde_json::json!({})))
1766 .expect_err("outgoing responses must wait for initialization"),
1767 ] {
1768 let data = error
1769 .data
1770 .as_ref()
1771 .and_then(|data| data.as_str())
1772 .unwrap_or_default();
1773 assert!(data.contains("initialization must complete"), "{error:?}");
1774 }
1775 }
1776 Ok(())
1777 }
1778
1779 #[test]
1780 fn v2_initialization_allows_only_protocol_cancellation_notifications()
1781 -> Result<(), crate::Error> {
1782 let client = ProtocolCompat::new(ProtocolMode::v2_client());
1783 client.outgoing_message(
1784 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1785 RemoteStyle::Counterpart,
1786 )?;
1787 client.outgoing_notification(UntypedMessage::new(
1788 "$/cancel_request",
1789 serde_json::json!({ "requestId": 1 }),
1790 )?)?;
1791 client
1792 .outgoing_notification(UntypedMessage::new(
1793 "session/update",
1794 serde_json::json!({}),
1795 )?)
1796 .expect_err("ordinary notifications must wait for initialization");
1797
1798 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1799 agent.incoming_message(UntypedMessage::new(
1800 "initialize",
1801 v2_initialize_request(ProtocolVersion::V2),
1802 )?)?;
1803 agent.incoming_notification(UntypedMessage::new(
1804 "$/cancel_request",
1805 serde_json::json!({ "requestId": 1 }),
1806 )?)?;
1807 agent
1808 .incoming_notification(UntypedMessage::new(
1809 "session/update",
1810 serde_json::json!({}),
1811 )?)
1812 .expect_err("ordinary notifications must wait for initialization");
1813 Ok(())
1814 }
1815
1816 fn error_data(error: &crate::Error) -> &str {
1817 error
1818 .data
1819 .as_ref()
1820 .and_then(|data| data.as_str())
1821 .unwrap_or_default()
1822 }
1823
1824 #[test]
1825 fn v2_peer_initialization_has_one_direction() -> Result<(), crate::Error> {
1826 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1827 let error = agent
1828 .outgoing_message(
1829 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1830 RemoteStyle::Counterpart,
1831 )
1832 .expect_err("agents must not initiate initialization");
1833 assert!(
1834 error_data(&error).contains("clients send `initialize`"),
1835 "{error:?}"
1836 );
1837 assert_eq!(
1838 initialization_state(&agent),
1839 InitializationState::Uninitialized
1840 );
1841
1842 let client = ProtocolCompat::new(ProtocolMode::v2_client());
1843 let error = client
1844 .incoming_message(UntypedMessage::new(
1845 "initialize",
1846 v2_initialize_request(ProtocolVersion::V2),
1847 )?)
1848 .expect_err("clients must not receive initialization requests");
1849 assert!(
1850 error_data(&error).contains("clients send `initialize`"),
1851 "{error:?}"
1852 );
1853 assert_eq!(
1854 initialization_state(&client),
1855 InitializationState::Uninitialized
1856 );
1857 Ok(())
1858 }
1859
1860 fn initialized_v2_agent() -> Result<ProtocolCompat, crate::Error> {
1862 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1863 agent.incoming_message(UntypedMessage::new(
1864 "initialize",
1865 v2_initialize_request(ProtocolVersion::V2),
1866 )?)?;
1867 agent.outgoing_response(
1868 "initialize",
1869 Ok(serde_json::to_value(v2_initialize_response(
1870 ProtocolVersion::V2,
1871 ))?),
1872 )?;
1873 Ok(agent)
1874 }
1875
1876 fn initialized_v2_client() -> Result<ProtocolCompat, crate::Error> {
1878 let client = ProtocolCompat::new(ProtocolMode::v2_client());
1879 client.outgoing_message(
1880 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1881 RemoteStyle::Counterpart,
1882 )?;
1883 client.incoming_response(
1884 "initialize",
1885 false,
1886 Ok(serde_json::to_value(v2_initialize_response(
1887 ProtocolVersion::V2,
1888 ))?),
1889 )?;
1890 Ok(client)
1891 }
1892
1893 #[test]
1894 fn v2_agent_accepts_repeated_initialize_before_other_requests() -> Result<(), crate::Error>
1895 {
1896 let agent = initialized_v2_agent()?;
1897 assert_eq!(initialization_state(&agent), InitializationState::Ready);
1898
1899 agent.incoming_notification(UntypedMessage::new(
1901 "$/cancel_request",
1902 serde_json::json!({ "requestId": 1 }),
1903 )?)?;
1904
1905 for _ in 0..2 {
1906 agent.incoming_message(UntypedMessage::new(
1907 "initialize",
1908 v2_initialize_request(ProtocolVersion::V2),
1909 )?)?;
1910 assert_eq!(
1911 initialization_state(&agent),
1912 InitializationState::Initializing
1913 );
1914 agent
1915 .incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)
1916 .expect_err("requests must wait for the repeated initialize");
1917 agent.outgoing_response(
1918 "initialize",
1919 Ok(serde_json::to_value(v2_initialize_response(
1920 ProtocolVersion::V2,
1921 ))?),
1922 )?;
1923 assert_eq!(initialization_state(&agent), InitializationState::Ready);
1924 assert_eq!(negotiated(&agent), ProtocolVersionKind::V2);
1925 }
1926
1927 agent.incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)?;
1928 let error = agent
1929 .incoming_message(UntypedMessage::new(
1930 "initialize",
1931 v2_initialize_request(ProtocolVersion::V2),
1932 )?)
1933 .expect_err("initialize must not be repeated after another request");
1934 assert_eq!(i32::from(error.code), -32600);
1935 assert!(
1936 error_data(&error).contains("cannot be repeated after any other request"),
1937 "{error:?}"
1938 );
1939 assert_eq!(initialization_state(&agent), InitializationState::Ready);
1940 Ok(())
1941 }
1942
1943 #[test]
1944 fn v2_agent_keeps_window_open_when_a_request_is_rejected() -> Result<(), crate::Error> {
1945 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1946 agent.incoming_message(UntypedMessage::new(
1947 "initialize",
1948 v2_initialize_request(ProtocolVersion::V2),
1949 )?)?;
1950 agent
1952 .incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)
1953 .expect_err("requests must wait for initialization");
1954 agent.outgoing_response(
1955 "initialize",
1956 Ok(serde_json::to_value(v2_initialize_response(
1957 ProtocolVersion::V2,
1958 ))?),
1959 )?;
1960 agent.incoming_message(UntypedMessage::new(
1961 "initialize",
1962 v2_initialize_request(ProtocolVersion::V2),
1963 )?)?;
1964 assert_eq!(
1965 initialization_state(&agent),
1966 InitializationState::Initializing
1967 );
1968 Ok(())
1969 }
1970
1971 #[test]
1972 fn failed_repeated_initialize_keeps_previous_initialization() -> Result<(), crate::Error> {
1973 let agent = initialized_v2_agent()?;
1974 agent.incoming_message(UntypedMessage::new(
1975 "initialize",
1976 v2_initialize_request(ProtocolVersion::V2),
1977 )?)?;
1978 agent
1979 .outgoing_response(
1980 "initialize",
1981 Err(crate::Error::invalid_params().data("rejected")),
1982 )
1983 .expect_err("the handler's error is forwarded");
1984 assert_eq!(initialization_state(&agent), InitializationState::Ready);
1985
1986 agent
1988 .incoming_message(UntypedMessage::new(
1989 "initialize",
1990 serde_json::json!({ "protocolVersion": 2 }),
1991 )?)
1992 .expect_err("an exact v2 repeat must be a valid v2 request");
1993 assert_eq!(initialization_state(&agent), InitializationState::Ready);
1994
1995 agent.incoming_message(UntypedMessage::new(
1997 "initialize",
1998 v2_initialize_request(ProtocolVersion::V2),
1999 )?)?;
2000 agent.outgoing_response(
2001 "initialize",
2002 Ok(serde_json::to_value(v2_initialize_response(
2003 ProtocolVersion::V2,
2004 ))?),
2005 )?;
2006 agent.incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)?;
2007 Ok(())
2008 }
2009
2010 #[test]
2011 fn v2_agent_answers_lower_version_repeat_like_a_first_initialize()
2012 -> Result<(), crate::Error> {
2013 let agent = initialized_v2_agent()?;
2014 let error = agent
2015 .incoming_message(UntypedMessage::new(
2016 "initialize",
2017 serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2018 )?)
2019 .expect_err("a v2 agent supports no version at or below v1");
2020 assert_eq!(i32::from(error.code), -32022);
2023 assert_eq!(
2024 error.data,
2025 Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2026 );
2027 assert_eq!(initialization_state(&agent), InitializationState::Ready);
2029 assert_eq!(agent.active_wire_version(), ProtocolVersionKind::V2);
2030 agent.incoming_message(UntypedMessage::new(
2031 "initialize",
2032 v2_initialize_request(ProtocolVersion::V2),
2033 )?)?;
2034 Ok(())
2035 }
2036
2037 #[test]
2038 fn v2_client_may_repeat_initialize_before_other_requests() -> Result<(), crate::Error> {
2039 let client = initialized_v2_client()?;
2040 client.outgoing_message(
2041 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2042 RemoteStyle::Counterpart,
2043 )?;
2044 assert_eq!(
2045 initialization_state(&client),
2046 InitializationState::Initializing
2047 );
2048 client.incoming_response(
2049 "initialize",
2050 false,
2051 Ok(serde_json::to_value(v2_initialize_response(
2052 ProtocolVersion::V2,
2053 ))?),
2054 )?;
2055 assert_eq!(initialization_state(&client), InitializationState::Ready);
2056
2057 client.incoming_message(UntypedMessage::new(
2059 "session/request_permission",
2060 serde_json::json!({}),
2061 )?)?;
2062 client.outgoing_message(
2063 UntypedMessage::new("session/new", serde_json::json!({}))?,
2064 RemoteStyle::Counterpart,
2065 )?;
2066 let error = client
2067 .outgoing_message(
2068 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2069 RemoteStyle::Counterpart,
2070 )
2071 .expect_err("initialize must not be repeated after another request");
2072 assert!(
2073 error_data(&error).contains("cannot be repeated after any other request"),
2074 "{error:?}"
2075 );
2076 assert_eq!(initialization_state(&client), InitializationState::Ready);
2077 Ok(())
2078 }
2079
2080 #[test]
2081 fn concurrent_initialize_is_rejected_for_first_and_repeated_handshakes()
2082 -> Result<(), crate::Error> {
2083 for agent in [
2084 ProtocolCompat::new(ProtocolMode::v2_agent()),
2085 initialized_v2_agent()?,
2086 ] {
2087 agent.incoming_request(
2088 &RawJsonRpcId::Number(1),
2089 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2090 )?;
2091 let error = agent
2092 .incoming_request(
2093 &RawJsonRpcId::Number(2),
2094 UntypedMessage::new(
2095 "initialize",
2096 v2_initialize_request(ProtocolVersion::V2),
2097 )?,
2098 )
2099 .expect_err("only one initialize may be in flight");
2100 assert_eq!(i32::from(error.code), -32600);
2101 assert!(error_data(&error).contains("in progress"), "{error:?}");
2102 }
2103 Ok(())
2104 }
2105
2106 #[test]
2107 fn v2_connections_reject_null_request_ids() -> Result<(), crate::Error> {
2108 for compat in [
2109 ProtocolCompat::new(ProtocolMode::v2_agent()),
2110 ProtocolCompat::new(ProtocolMode::v2_proxy()),
2111 initialized_v2_agent()?,
2112 initialized_v2_client()?,
2113 ] {
2114 for method in ["initialize", "proxy/initialize", "session/new"] {
2115 let state = initialization_state(&compat);
2116 let error = compat
2117 .incoming_request(
2118 &RawJsonRpcId::Null,
2119 UntypedMessage::new(
2120 method,
2121 v2_initialize_request(ProtocolVersion::V2),
2122 )?,
2123 )
2124 .expect_err("v2 request ids must not be null");
2125 assert_eq!(i32::from(error.code), -32600);
2126 assert!(error_data(&error).contains("not null"), "{error:?}");
2127 assert_eq!(initialization_state(&compat), state);
2128 assert_eq!(pending_initialize(&compat), None);
2129 }
2130 }
2131
2132 let v1_agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2134 v1_agent.incoming_request(
2135 &RawJsonRpcId::Null,
2136 UntypedMessage::new(
2137 "initialize",
2138 serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2139 )?,
2140 )?;
2141 Ok(())
2142 }
2143
2144 #[test]
2145 fn newer_version_initialize_keeps_what_parses_under_v2() -> Result<(), crate::Error> {
2146 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2147 let request = agent.incoming_message(UntypedMessage::new(
2148 "initialize",
2149 serde_json::json!({
2150 "protocolVersion": 3,
2151 "info": { "name": "future-client" },
2152 "capabilities": {
2153 "auth": "malformed",
2154 "elicitation": {},
2155 "_futureCapability": { "dropped": true }
2156 },
2157 "_meta": "malformed",
2158 "_futureField": true
2159 }),
2160 )?)?;
2161 let initialize: v2::InitializeRequest =
2162 serde_json::from_value(request.params().clone())?;
2163 assert_eq!(initialize.protocol_version, ProtocolVersion::V2);
2164 assert_eq!(
2165 initialize.info,
2166 v2::Implementation::new("unknown", "unknown")
2167 );
2168 assert_eq!(initialize.capabilities.auth, None);
2169 assert!(initialize.capabilities.elicitation.is_some());
2170 assert_eq!(initialize.meta, None);
2171 assert_eq!(request.params(), &serde_json::to_value(&initialize)?);
2172
2173 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2176 let request = agent.incoming_message(UntypedMessage::new(
2177 "initialize",
2178 serde_json::json!({
2179 "protocolVersion": 3,
2180 "info": { "name": "future-client", "version": "3.0.0" },
2181 "capabilities": [],
2182 "_meta": { "kept": true }
2183 }),
2184 )?)?;
2185 let initialize: v2::InitializeRequest =
2186 serde_json::from_value(request.params().clone())?;
2187 assert_eq!(
2188 initialize.info,
2189 v2::Implementation::new("future-client", "3.0.0")
2190 );
2191 assert_eq!(initialize.capabilities, v2::ClientCapabilities::new());
2192 assert_eq!(
2193 request.params()["_meta"],
2194 serde_json::json!({ "kept": true })
2195 );
2196 Ok(())
2197 }
2198
2199 #[test]
2200 fn exact_version_initialize_stays_strict() -> Result<(), crate::Error> {
2201 let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2202 let error = agent
2203 .incoming_message(UntypedMessage::new(
2204 "initialize",
2205 serde_json::json!({ "protocolVersion": 2, "info": { "name": "client" } }),
2206 )?)
2207 .expect_err("an exact v2 request must carry a valid `info`");
2208 assert_eq!(i32::from(error.code), -32602);
2209 assert_eq!(
2210 initialization_state(&agent),
2211 InitializationState::Uninitialized
2212 );
2213 Ok(())
2214 }
2215
2216 #[test]
2217 fn v1_downgrade_keeps_what_parses_under_v1() -> Result<(), crate::Error> {
2218 let agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2219 let request = agent.incoming_message(UntypedMessage::new(
2220 "initialize",
2221 serde_json::json!({
2222 "protocolVersion": 2,
2223 "info": "malformed",
2224 "capabilities": { "elicitation": {} },
2225 "_meta": 7
2226 }),
2227 )?)?;
2228 let initialize: crate::v1::schema::InitializeRequest =
2229 serde_json::from_value(request.params().clone())?;
2230 assert_eq!(initialize.protocol_version, ProtocolVersion::V1);
2231 assert_eq!(initialize.client_info, None);
2232 assert!(initialize.client_capabilities.elicitation.is_some());
2233 assert_eq!(initialize.meta, None);
2234 assert!(request.params().get("clientInfo").is_none());
2235 assert!(request.params().get("_meta").is_none());
2236
2237 let agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2238 let request = agent.incoming_message(UntypedMessage::new(
2239 "initialize",
2240 serde_json::json!({ "protocolVersion": 2 }),
2241 )?)?;
2242 let initialize: crate::v1::schema::InitializeRequest =
2243 serde_json::from_value(request.params().clone())?;
2244 assert_eq!(initialize.client_info, None);
2245 Ok(())
2246 }
2247
2248 #[test]
2249 fn rejected_concurrent_initialize_does_not_clear_the_active_handshake()
2250 -> Result<(), crate::Error> {
2251 let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2252 let accepted_id = RawJsonRpcId::Number(1);
2253 let rejected_id = RawJsonRpcId::Number(2);
2254
2255 compat.incoming_request(
2256 &accepted_id,
2257 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2258 )?;
2259 let duplicate_error = compat
2260 .incoming_request(
2261 &rejected_id,
2262 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2263 )
2264 .expect_err("a second initialize request must be rejected while one is active");
2265 compat
2266 .outgoing_response_to(&rejected_id, "initialize", Err(duplicate_error))
2267 .expect_err("the rejected initialize receives its own error response");
2268
2269 assert_eq!(
2270 initialization_state(&compat),
2271 InitializationState::Initializing
2272 );
2273 assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2274
2275 compat.outgoing_response_to(
2276 &accepted_id,
2277 "initialize",
2278 Ok(serde_json::to_value(v2_initialize_response(
2279 ProtocolVersion::V2,
2280 ))?),
2281 )?;
2282 assert_eq!(initialization_state(&compat), InitializationState::Ready);
2283 Ok(())
2284 }
2285
2286 #[test]
2287 fn rejected_wrong_direction_initialize_does_not_clear_client_handshake()
2288 -> Result<(), crate::Error> {
2289 let compat = ProtocolCompat::new(ProtocolMode::v2_client());
2290 compat.outgoing_message(
2291 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2292 RemoteStyle::Counterpart,
2293 )?;
2294
2295 let wrong_direction_id = RawJsonRpcId::Number(2);
2296 let wrong_direction_error = compat
2297 .incoming_request(
2298 &wrong_direction_id,
2299 UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2300 )
2301 .expect_err("agents must not send initialize requests to clients");
2302 compat
2303 .outgoing_response_to(
2304 &wrong_direction_id,
2305 "initialize",
2306 Err(wrong_direction_error),
2307 )
2308 .expect_err("the wrong-direction initialize receives its own error response");
2309
2310 assert_eq!(
2311 initialization_state(&compat),
2312 InitializationState::Initializing
2313 );
2314 assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2315
2316 compat.incoming_response(
2317 "initialize",
2318 false,
2319 Ok(serde_json::to_value(v2_initialize_response(
2320 ProtocolVersion::V2,
2321 ))?),
2322 )?;
2323 assert_eq!(initialization_state(&compat), InitializationState::Ready);
2324 Ok(())
2325 }
2326
2327 #[test]
2328 fn incoming_initialize_request_negotiates_newer_protocol_versions()
2329 -> Result<(), crate::Error> {
2330 for requested in [2_u16, 3, u16::MAX] {
2331 let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2332 let request = compat.incoming_message(UntypedMessage::new(
2333 "initialize",
2334 v2_initialize_request(ProtocolVersion::from(requested)),
2335 )?)?;
2336 assert_eq!(request.params()["protocolVersion"], serde_json::json!(2));
2337 assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2338
2339 let response = compat.outgoing_response(
2340 "initialize",
2341 Ok(serde_json::to_value(v2_initialize_response(
2342 ProtocolVersion::V2,
2343 ))?),
2344 )?;
2345 assert_eq!(response["protocolVersion"], serde_json::json!(2));
2346 assert_eq!(initialization_state(&compat), InitializationState::Ready);
2347 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
2348 }
2349 Ok(())
2350 }
2351
2352 #[test]
2353 fn incoming_initialize_request_rejects_unsupported_protocol_version()
2354 -> Result<(), crate::Error> {
2355 let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2356 let error = compat
2357 .incoming_message(UntypedMessage::new(
2358 "initialize",
2359 serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2360 )?)
2361 .expect_err("v2 agents should reject v1 initialization without a v1 handler");
2362 assert_eq!(i32::from(error.code), -32022);
2363 assert_eq!(
2364 error.data,
2365 Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2366 );
2367 assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
2368 assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
2369 assert_eq!(
2370 initialization_state(&compat),
2371 InitializationState::Uninitialized
2372 );
2373
2374 Ok(())
2375 }
2376
2377 #[test]
2378 fn v1_proxy_negotiates_newer_proxy_initialize_down_to_v1() -> Result<(), crate::Error> {
2379 for requested in [2_u16, 3] {
2380 let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2381 let request = compat.incoming_message(UntypedMessage::new(
2382 "proxy/initialize",
2383 serde_json::json!({
2384 "protocolVersion": requested,
2385 "info": { "name": "future-client", "version": "1.0.0" },
2386 "capabilities": { "elicitation": {}, "_future": true },
2387 "_futureField": true
2388 }),
2389 )?)?;
2390 let initialize: crate::v1::schema::InitializeRequest =
2392 serde_json::from_value(request.params().clone())?;
2393 assert_eq!(initialize.protocol_version, ProtocolVersion::V1);
2394 assert_eq!(
2395 initialize.client_info,
2396 Some(crate::v1::schema::Implementation::new(
2397 "future-client",
2398 "1.0.0"
2399 ))
2400 );
2401 assert!(initialize.client_capabilities.elicitation.is_some());
2402 assert!(request.params().get("_futureField").is_none());
2403 assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V1));
2404
2405 let response = compat.outgoing_response(
2406 "proxy/initialize",
2407 Ok(serde_json::to_value(v1_initialize_response())?),
2408 )?;
2409 assert_eq!(response["protocolVersion"], serde_json::json!(1));
2410 }
2411
2412 let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2414 let request = compat.incoming_message(UntypedMessage::new(
2415 "proxy/initialize",
2416 serde_json::json!({ "protocolVersion": 0 }),
2417 )?)?;
2418 assert_eq!(request.params()["protocolVersion"], serde_json::json!(1));
2419 Ok(())
2420 }
2421
2422 #[test]
2423 fn v2_proxy_negotiates_proxy_initialize_like_a_v2_agent() -> Result<(), crate::Error> {
2424 let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2425 let request = compat.incoming_message(UntypedMessage::new(
2426 "proxy/initialize",
2427 serde_json::json!({
2428 "protocolVersion": 3,
2429 "info": { "name": "future-client" },
2430 "capabilities": { "elicitation": {}, "_future": { "dropped": true } },
2431 "_futureField": true
2432 }),
2433 )?)?;
2434 let initialize: v2::InitializeRequest =
2435 serde_json::from_value(request.params().clone())?;
2436 assert_eq!(initialize.protocol_version, ProtocolVersion::V2);
2437 assert_eq!(
2438 initialize.info,
2439 v2::Implementation::new("unknown", "unknown")
2440 );
2441 assert!(initialize.capabilities.elicitation.is_some());
2442 assert_eq!(request.params(), &serde_json::to_value(&initialize)?);
2443 assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2444
2445 let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2447 let error = compat
2448 .incoming_message(UntypedMessage::new(
2449 "proxy/initialize",
2450 serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2451 )?)
2452 .expect_err("a v2 proxy supports no version at or below v1");
2453 assert_eq!(i32::from(error.code), -32022);
2454 assert_eq!(
2455 error.data,
2456 Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2457 );
2458 assert_eq!(pending_initialize(&compat), None);
2459 Ok(())
2460 }
2461
2462 #[test]
2463 fn exact_version_proxy_initialize_is_unchanged() -> Result<(), crate::Error> {
2464 let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2465 let params = serde_json::json!({
2466 "protocolVersion": 1,
2467 "clientCapabilities": {},
2468 "_futureField": true
2469 });
2470 let request = compat
2471 .incoming_message(UntypedMessage::new("proxy/initialize", params.clone())?)?;
2472 assert_eq!(request.params(), ¶ms);
2473
2474 let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2475 let params = serde_json::to_value(v2_initialize_request(ProtocolVersion::V2))?;
2476 let request = compat
2477 .incoming_message(UntypedMessage::new("proxy/initialize", params.clone())?)?;
2478 assert_eq!(request.params(), ¶ms);
2479 Ok(())
2480 }
2481
2482 #[test]
2483 fn proxy_initialize_requests_reject_wrong_directions_and_wrapping()
2484 -> Result<(), crate::Error> {
2485 for mode in [ProtocolMode::v1_proxy(), ProtocolMode::v2_proxy()] {
2486 let compat = ProtocolCompat::new(mode);
2487 for error in [
2488 compat
2489 .incoming_message(UntypedMessage::new(
2490 "initialize",
2491 serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2492 )?)
2493 .expect_err("proxy initialization must arrive through `proxy/initialize`"),
2494 compat
2495 .incoming_message(UntypedMessage::new(
2496 "proxy/successor",
2497 serde_json::json!({
2498 "method": "initialize",
2499 "params": { "protocolVersion": ProtocolVersion::V2 }
2500 }),
2501 )?)
2502 .expect_err("successor traffic must not carry initialization"),
2503 compat
2504 .incoming_message(UntypedMessage::new(
2505 "proxy/successor",
2506 serde_json::json!({
2507 "method": "proxy/successor",
2508 "params": {
2509 "method": "proxy/initialize",
2510 "params": { "protocolVersion": ProtocolVersion::V2 }
2511 }
2512 }),
2513 )?)
2514 .expect_err("nested successor traffic must not carry initialization"),
2515 compat
2516 .outgoing_message(
2517 UntypedMessage::new(
2518 "initialize",
2519 serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2520 )?,
2521 RemoteStyle::Predecessor,
2522 )
2523 .expect_err("downstream proxy initialization must use `proxy/successor`"),
2524 compat
2525 .outgoing_message(
2526 UntypedMessage::new(
2527 "proxy/initialize",
2528 serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2529 )?,
2530 RemoteStyle::Successor,
2531 )
2532 .expect_err("a proxy must not send `proxy/initialize` downstream"),
2533 ] {
2534 let data = error
2535 .data
2536 .as_ref()
2537 .and_then(|data| data.as_str())
2538 .unwrap_or_default();
2539 assert!(data.contains("proxy/initialize"), "{error:?}");
2540 assert!(data.contains("proxy/successor"), "{error:?}");
2541 }
2542 assert_eq!(pending_initialize(&compat), None);
2543 }
2544
2545 Ok(())
2546 }
2547
2548 #[test]
2549 fn outgoing_initialize_rejects_non_object_params() -> Result<(), crate::Error> {
2550 for (compat, message, remote_style) in [
2551 (
2552 ProtocolCompat::new(ProtocolMode::v2_client()),
2553 UntypedMessage::new("initialize", serde_json::Value::Null)?,
2554 RemoteStyle::Counterpart,
2555 ),
2556 (
2557 ProtocolCompat::new(ProtocolMode::v2_proxy()),
2558 UntypedMessage::new("initialize", serde_json::Value::Null)?,
2559 RemoteStyle::Successor,
2560 ),
2561 ] {
2562 let error = compat
2563 .outgoing_message(message, remote_style)
2564 .expect_err("initialize params must be an object");
2565 let data = error
2566 .data
2567 .as_ref()
2568 .and_then(|data| data.as_str())
2569 .unwrap_or_default();
2570 assert!(data.contains("protocolVersion"), "{error:?}");
2571 assert_eq!(pending_initialize(&compat), None);
2572 }
2573
2574 Ok(())
2575 }
2576
2577 #[test]
2578 fn outgoing_initialize_rejects_explicit_successor_wrapping() -> Result<(), crate::Error> {
2579 for message in [
2580 UntypedMessage::new(
2581 "proxy/successor",
2582 serde_json::json!({
2583 "method": "initialize",
2584 "params": { "protocolVersion": ProtocolVersion::V1 }
2585 }),
2586 )?,
2587 UntypedMessage::new(
2588 "proxy/successor",
2589 serde_json::json!({
2590 "method": "proxy/successor",
2591 "params": {
2592 "method": "initialize",
2593 "params": { "protocolVersion": ProtocolVersion::V1 }
2594 }
2595 }),
2596 )?,
2597 ] {
2598 let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2599 let error = compat
2600 .outgoing_message(message, RemoteStyle::Successor)
2601 .expect_err("connection routing must own successor wrapping");
2602 let data = error
2603 .data
2604 .as_ref()
2605 .and_then(|data| data.as_str())
2606 .unwrap_or_default();
2607 assert!(data.contains("logical `initialize`"), "{error:?}");
2608 assert!(data.contains("proxy/successor"), "{error:?}");
2609 assert_eq!(pending_initialize(&compat), None);
2610 }
2611
2612 Ok(())
2613 }
2614
2615 #[test]
2616 fn proxy_initialize_round_trip_uses_the_selected_protocol_version()
2617 -> Result<(), crate::Error> {
2618 for (mode, selected, selected_kind) in [
2619 (
2620 ProtocolMode::v1_proxy(),
2621 ProtocolVersion::V1,
2622 ProtocolVersionKind::V1,
2623 ),
2624 (
2625 ProtocolMode::v2_proxy(),
2626 ProtocolVersion::V2,
2627 ProtocolVersionKind::V2,
2628 ),
2629 ] {
2630 let compat = ProtocolCompat::new(mode);
2631 let request = compat.incoming_message(UntypedMessage::new(
2632 "proxy/initialize",
2633 serde_json::json!({ "protocolVersion": selected }),
2634 )?)?;
2635 assert_eq!(
2636 required_protocol_version_from_value(request.params())?,
2637 selected
2638 );
2639 assert_eq!(pending_initialize(&compat), Some(selected_kind));
2640
2641 let response = compat.outgoing_response(
2642 "proxy/initialize",
2643 Ok(serde_json::json!({ "protocolVersion": selected })),
2644 )?;
2645 assert_eq!(required_protocol_version_from_value(&response)?, selected);
2646 assert_eq!(negotiated(&compat), selected_kind);
2647 assert_eq!(pending_initialize(&compat), None);
2648 assert_eq!(compat.active_wire_version(), selected_kind);
2649 }
2650
2651 Ok(())
2652 }
2653
2654 #[test]
2655 fn proxy_initialize_response_rejects_the_wrong_version_and_clears_pending_state()
2656 -> Result<(), crate::Error> {
2657 for (mode, selected, unsupported, selected_kind) in [
2658 (
2659 ProtocolMode::v1_proxy(),
2660 ProtocolVersion::V1,
2661 ProtocolVersion::V2,
2662 ProtocolVersionKind::V1,
2663 ),
2664 (
2665 ProtocolMode::v2_proxy(),
2666 ProtocolVersion::V2,
2667 ProtocolVersion::V1,
2668 ProtocolVersionKind::V2,
2669 ),
2670 ] {
2671 let compat = ProtocolCompat::new(mode);
2672 let request = compat.outgoing_message(
2673 UntypedMessage::new(
2674 "initialize",
2675 serde_json::json!({ "protocolVersion": unsupported }),
2676 )?,
2677 RemoteStyle::Successor,
2678 )?;
2679 assert_eq!(
2680 required_protocol_version_from_value(request.params())?,
2681 selected
2682 );
2683 assert_eq!(pending_initialize(&compat), Some(selected_kind));
2684
2685 let error = compat
2686 .incoming_response(
2687 "initialize",
2688 false,
2689 Ok(serde_json::json!({ "protocolVersion": unsupported })),
2690 )
2691 .expect_err("proxy initialization must reject a mismatched response version");
2692 let data = error
2693 .data
2694 .as_ref()
2695 .and_then(|data| data.as_str())
2696 .unwrap_or_default();
2697 assert!(
2698 data.contains(&format!(
2699 "required ACP protocol version {selected} but peer negotiated {unsupported}"
2700 )),
2701 "{error:?}"
2702 );
2703 assert_eq!(negotiated(&compat), selected_kind);
2704 assert_eq!(pending_initialize(&compat), None);
2705 assert_eq!(compat.active_wire_version(), selected_kind);
2706 }
2707
2708 Ok(())
2709 }
2710
2711 #[test]
2712 #[should_panic(expected = "cannot merge ACP builders with different API protocol versions")]
2713 fn merging_different_api_protocol_modes_panics() {
2714 let _ = ProtocolMode::v1_agent().merge(ProtocolMode::v2_agent());
2715 }
2716
2717 #[test]
2718 #[should_panic(expected = "cannot merge standard ACP and proxy ACP builders")]
2719 fn merging_standard_and_proxy_protocol_modes_panics() {
2720 let _ = ProtocolMode::v1_agent().merge(ProtocolMode::v1_proxy());
2721 }
2722 }
2723}
2724
2725pub(crate) use imp::{ProtocolCompat, ProtocolMode};