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