jmap-websocket 0.6.1

JMAP over WebSocket (RFC 8887, urn:ietf:params:jmap:websocket): wire frames, capability, and a framework-agnostic server session driver
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
//! The server side of RFC 8887: a per-connection session driver.
//!
//! [`Connection::run`] reads [`Inbound`] messages from any `Stream` and
//! writes [`Outbound`] messages to any `Sink`, so it is independent of
//! the WebSocket library. The deployment does the opening handshake
//! (authentication, RFC 8887 §4.1; the `jmap` subprotocol, §4.2, see
//! [`offers_jmap`](crate::offers_jmap)), maps its library's messages to
//! [`Inbound`] / [`Outbound`] (feature `tungstenite` does this for
//! tokio-tungstenite), and calls `run` once per connection.
//!
//! - Each text message goes through [`parse_client_message`]. A
//!   [`WsRequest`] is handed to the [`RequestHandler`]
//!   ([`DispatcherHandler`] wraps a [`jmap_server::Dispatcher`]); its
//!   [`WsResponse`] or
//!   [`WsRequestError`] carries the request's `id`
//!   back as `requestId` (§4.3.3, §4.3.4).
//! - Requests run concurrently, up to
//!   [`ConnectionConfig::max_concurrent_requests`], and answer in the
//!   order they finish: "JMAP over WebSocket allows the server to process
//!   requests out of order" (§4.3.2). A request over the limit gets a
//!   `limit` error naming `maxConcurrentRequests`, which "also applies to
//!   requests made on the WebSocket connection". [`Connection::with_shared_limit`]
//!   shares the limit with the deployment's HTTP API endpoint.
//! - A [`WebSocketPushEnable`] subscribes to the [`PushSource`]; each
//!   [`WsStateChange`] it yields is cut to the requested `dataTypes`
//!   ([`filter_state_change`]) and sent, in the order the source yields
//!   them. Enabling again replaces the subscription;
//!   [`WebSocketPushDisable`] drops it (§4.3.5). [`PushHub`] is a ready
//!   source.
//! - A binary message closes the connection with status 1003, or is
//!   ignored ([`BinaryFrames`], §4.3.1).
//! - A message whose `@type` an [`ExtensionHandler`] registered
//!   ([`Connection::with_extension`]) goes to that handler, for the
//!   extension message types the JMAP Chat, VTC and Scene WebSocket
//!   drafts define (`ChatStreamEnable`, `VTCStreamEnable`,
//!   `SceneStreamEnable`, ...). The handler sends its server-to-client
//!   messages through an [`ExtensionSender`]. Any other `@type` is
//!   answered with `notRequest`.
//! - A [`CloseHandle`] ([`Connection::close_handle`]) lets the deployment
//!   end the connection with a Close frame of its choosing, such as 1008
//!   ([`CloseCode::POLICY_VIOLATION`]) when the credentials of the
//!   opening handshake expire (§4.2).

mod close;
mod extension;
mod hub;

pub use close::{CloseCode, CloseHandle, MAX_CLOSE_REASON_LEN};
pub use extension::{ExtensionHandler, ExtensionMessage, ExtensionSendError, ExtensionSender};
pub use hub::PushHub;

use std::fmt;
use std::future::Future;
use std::sync::Arc;

use futures::stream::{BoxStream, FuturesUnordered};
use futures::{Sink, SinkExt as _, Stream, StreamExt as _};
use jmap_server::Dispatcher;
use jmap_types::problem::ProblemDetails;
use jmap_types::{JmapError, JmapRequest, JmapResponse, State};
use serde_json::Value;
use tokio::sync::{OwnedSemaphorePermit, Semaphore, mpsc};

use extension::Extensions;

use crate::{
    ClientMessage, WebSocketPushDisable, WebSocketPushEnable, WsRequest, WsRequestError,
    WsResponse, WsStateChange,
};

/// The WebSocket close status for a binary message (RFC 8887 §4.3.1,
/// RFC 6455 §7.4.1: 1003 Unsupported Data).
pub const CLOSE_UNSUPPORTED_DATA: u16 = 1003;

// ---------------------------------------------------------------------------
// Messages in and out
// ---------------------------------------------------------------------------

/// A WebSocket message received from the client, as the driver needs it.
///
/// Fragmented messages must already be coalesced (RFC 8887 §4.3); every
/// WebSocket library does this. Map Ping and Pong to nothing: the
/// library answers Pings itself.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Inbound {
    /// A text message (UTF-8, checked by the WebSocket library).
    Text(String),
    /// A binary message; its payload is not needed.
    Binary,
    /// A Close frame: the client is ending the connection.
    Close,
}

/// A WebSocket message the driver sends.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Outbound {
    /// A text message: one serialized RFC 8887 server message.
    Text(String),
    /// A Close frame with a status code and reason.
    Close {
        /// The RFC 6455 §7.4 status code.
        code: u16,
        /// The reason text.
        reason: String,
    },
}

// ---------------------------------------------------------------------------
// Configuration
// ---------------------------------------------------------------------------

/// What the driver does with a binary message (RFC 8887 §4.3.1: "the
/// endpoint can either ignore the frame or close the WebSocket
/// connection").
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BinaryFrames {
    /// Send a Close with [`CLOSE_UNSUPPORTED_DATA`] and end the connection.
    #[default]
    Close,
    /// Drop the message and keep reading.
    Ignore,
}

/// Per-connection limits and policies.
///
/// Set the limits to the values the Session's
/// `urn:ietf:params:jmap:core` capability advertises (RFC 8620 §2).
///
/// ```
/// use jmap_websocket::server::ConnectionConfig;
///
/// let config = ConnectionConfig::default()
///     .max_calls_in_request(32)
///     .max_size_request(Some(10_000_000))
///     .max_concurrent_requests(4);
/// assert_eq!(config.max_calls_in_request_value(), 32);
/// ```
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConnectionConfig {
    max_calls_in_request: usize,
    max_size_request: Option<usize>,
    max_concurrent_requests: usize,
    binary_frames: BinaryFrames,
    extension_queue_capacity: usize,
}

impl Default for ConnectionConfig {
    /// 16 calls per request, 10 000 000 octets per request, 4 concurrent
    /// requests (the RFC 8620 §2 suggested minimums), binary messages
    /// close the connection, 64 queued extension messages.
    fn default() -> Self {
        Self {
            max_calls_in_request: 16,
            max_size_request: Some(10_000_000),
            max_concurrent_requests: 4,
            binary_frames: BinaryFrames::Close,
            extension_queue_capacity: 64,
        }
    }
}

impl ConnectionConfig {
    /// `maxCallsInRequest`: a Request with more method calls gets a
    /// `limit` error naming it.
    #[must_use]
    pub fn max_calls_in_request(mut self, max: usize) -> Self {
        self.max_calls_in_request = max;
        self
    }

    /// `maxSizeRequest` in octets, or `None` for no check here: a longer
    /// text message gets a `limit` error naming it, unparsed, so with
    /// `requestId: null`. Also cap the message size in the WebSocket
    /// library, which reads the whole message before the driver sees it.
    #[must_use]
    pub fn max_size_request(mut self, max: Option<usize>) -> Self {
        self.max_size_request = max;
        self
    }

    /// `maxConcurrentRequests` on this connection. Values below 1 are
    /// treated as 1.
    #[must_use]
    pub fn max_concurrent_requests(mut self, max: usize) -> Self {
        self.max_concurrent_requests = max.max(1);
        self
    }

    /// The binary-message policy.
    #[must_use]
    pub fn binary_frames(mut self, policy: BinaryFrames) -> Self {
        self.binary_frames = policy;
        self
    }

    /// How many server-to-client messages the connection's
    /// [`ExtensionHandler`]s may queue ([`ExtensionSender`]) before
    /// [`ExtensionSender::try_send`] fails with
    /// [`ExtensionSendError::Full`] and [`ExtensionSender::send`] waits.
    /// Values below 1 are treated as 1.
    #[must_use]
    pub fn extension_queue_capacity(mut self, capacity: usize) -> Self {
        self.extension_queue_capacity = capacity.max(1);
        self
    }

    /// The `maxCallsInRequest` limit.
    pub fn max_calls_in_request_value(&self) -> usize {
        self.max_calls_in_request
    }

    /// The `maxSizeRequest` limit.
    pub fn max_size_request_value(&self) -> Option<usize> {
        self.max_size_request
    }

    /// The per-connection `maxConcurrentRequests` limit.
    pub fn max_concurrent_requests_value(&self) -> usize {
        self.max_concurrent_requests
    }

    /// The binary-message policy.
    pub fn binary_frames_value(&self) -> BinaryFrames {
        self.binary_frames
    }

    /// The extension message queue capacity.
    pub fn extension_queue_capacity_value(&self) -> usize {
        self.extension_queue_capacity
    }
}

// ---------------------------------------------------------------------------
// Parsing client messages
// ---------------------------------------------------------------------------

/// The RFC 8887 §4.3.4 `RequestError` for a request-level `err`: its RFC
/// 8620 §3.6.1 problem details (status from [`jmap_server::error_status`])
/// with `requestId` set to `request_id`.
pub fn request_error(err: &JmapError, request_id: Option<String>) -> WsRequestError {
    let status = jmap_server::error_status(err).as_u16();
    WsRequestError::new(ProblemDetails::for_jmap_error(err, status), request_id)
}

/// Reads one text message from the client (RFC 8887 §4.3).
///
/// In order:
///
/// 1. Longer than `maxSizeRequest`: `limit` (`maxSizeRequest`).
/// 2. Not JSON: `notJSON`, with the detail text of the RFC 8887 §4.4
///    example.
/// 3. Not an object, or `@type` missing or not one of `Request`,
///    `WebSocketPushEnable`, `WebSocketPushDisable`: `notRequest`.
/// 4. `Request`: `id`, when present, must be a string (§4.3.2), else
///    `notRequest`; the rest must be an RFC 8620 §3.3 Request
///    ([`jmap_server::parse_request`]: `notRequest`, or `limit` for
///    `maxCallsInRequest`).
/// 5. `WebSocketPushEnable` / `WebSocketPushDisable` with members of the
///    wrong type: `notRequest`.
///
/// Every error carries the message's `id` as `requestId` when the message
/// is an object with a string `id`, and `null` otherwise, so the client
/// can correlate it (§4.3.4: "MUST be returned if given in the request").
///
/// ```
/// use jmap_websocket::ClientMessage;
/// use jmap_websocket::server::{ConnectionConfig, parse_client_message};
///
/// let config = ConnectionConfig::default();
/// let m = parse_client_message(r#"{"@type":"WebSocketPushDisable"}"#, &config).unwrap();
/// assert!(matches!(m, ClientMessage::PushDisable(_)));
///
/// let e = parse_client_message("The quick brown fox", &config).unwrap_err();
/// assert_eq!(e.problem.problem_type, "urn:ietf:params:jmap:error:notJSON");
/// assert_eq!(e.request_id, None);
/// ```
///
/// # Errors
///
/// The [`WsRequestError`] to send back, as listed above.
// The error is the message to send back, built once per bad message;
// boxing it would only add an allocation and a deref for the caller.
#[allow(clippy::result_large_err)]
pub fn parse_client_message(
    text: &str,
    config: &ConnectionConfig,
) -> Result<ClientMessage, WsRequestError> {
    match parse_message(text, config, |_| false)? {
        Parsed::Core(message) => Ok(message),
        Parsed::Extension(_) => unreachable!("no extension types were given"),
    }
}

/// A client message: an RFC 8887 one, or one for an [`ExtensionHandler`].
enum Parsed {
    Core(ClientMessage),
    Extension(ExtensionMessage),
}

/// [`parse_client_message`], also accepting the `@type`s for which
/// `is_extension` is true.
#[allow(clippy::result_large_err)] // as parse_client_message
fn parse_message(
    text: &str,
    config: &ConnectionConfig,
    is_extension: impl Fn(&str) -> bool,
) -> Result<Parsed, WsRequestError> {
    if let Some(max) = config.max_size_request
        && text.len() > max
    {
        let mut err = JmapError::limit("maxSizeRequest");
        err.description = Some(format!(
            "The request is {} octets, more than maxSizeRequest {max}.",
            text.len()
        ));
        return Err(request_error(&err, None));
    }
    let value: Value = serde_json::from_str(text).map_err(|_| {
        let mut err = JmapError::not_json();
        err.description = Some("The request did not parse as I-JSON.".to_owned());
        request_error(&err, None)
    })?;
    let Value::Object(mut obj) = value else {
        return Err(not_request("The message is not a JSON object.", None));
    };
    let request_id = obj.get("id").and_then(Value::as_str).map(str::to_owned);
    let Some(Value::String(ty)) = obj.remove("@type") else {
        return Err(not_request("The message has no string @type.", request_id));
    };
    match ty.as_str() {
        "Request" => {
            let id = match obj.remove("id") {
                None | Some(Value::Null) => None,
                Some(Value::String(s)) => Some(s),
                Some(_) => return Err(not_request("The request id is not a String.", None)),
            };
            match jmap_server::parse_request(Value::Object(obj), config.max_calls_in_request) {
                Ok(request) => Ok(Parsed::Core(ClientMessage::Request(WsRequest::new(
                    request, id,
                )))),
                Err(err) => Err(request_error(&err, id)),
            }
        }
        "WebSocketPushEnable" => serde_json::from_value::<WebSocketPushEnable>(Value::Object(obj))
            .map(|m| Parsed::Core(ClientMessage::PushEnable(m)))
            .map_err(|_| not_request("Malformed WebSocketPushEnable.", request_id)),
        "WebSocketPushDisable" => {
            serde_json::from_value::<WebSocketPushDisable>(Value::Object(obj))
                .map(|m| Parsed::Core(ClientMessage::PushDisable(m)))
                .map_err(|_| not_request("Malformed WebSocketPushDisable.", request_id))
        }
        ty if is_extension(ty) => Ok(Parsed::Extension(ExtensionMessage::new(ty, obj))),
        _ => Err(not_request(
            "The @type is not one a client may send.",
            request_id,
        )),
    }
}

fn not_request(detail: &str, request_id: Option<String>) -> WsRequestError {
    let mut err = JmapError::not_request();
    err.description = Some(detail.to_owned());
    request_error(&err, request_id)
}

// ---------------------------------------------------------------------------
// Request handling
// ---------------------------------------------------------------------------

/// Answers the Requests of one connection.
///
/// Implement it to add work around each dispatch (a `using` check, state
/// change notification, metrics), or use [`DispatcherHandler`].
pub trait RequestHandler: Send + Sync + 'static {
    /// Process one parsed Request. `Err` is a request-level error (RFC
    /// 8620 §3.6.1, e.g. `unknownCapability`) and is sent as a
    /// `RequestError`; method-level errors belong in the Response.
    fn handle(
        &self,
        request: JmapRequest,
    ) -> impl Future<Output = Result<JmapResponse, JmapError>> + Send;

    /// Called on every `RequestError` before it is sent, including those
    /// the driver makes itself. Set a localized `title` here (RFC 9457
    /// §3.1.3); the default leaves the problem as it is.
    fn prepare_problem(&self, problem: &mut ProblemDetails) {
        let _ = problem;
    }
}

type SessionStateFn = dyn Fn() -> State + Send + Sync;

/// A [`RequestHandler`] that dispatches every Request on a
/// [`Dispatcher`] for one caller.
///
/// ```
/// use std::sync::Arc;
/// use jmap_websocket::server::DispatcherHandler;
/// use jmap_websocket::jmap_server::Dispatcher;
/// use jmap_websocket::jmap_types::State;
///
/// let dispatcher: Arc<Dispatcher<()>> = Arc::new(Dispatcher::new());
/// let handler = DispatcherHandler::new(dispatcher, (), || State::from("s0"))
///     .with_known_capabilities(["urn:ietf:params:jmap:core"]);
/// # let _ = handler;
/// ```
pub struct DispatcherHandler<C> {
    dispatcher: Arc<Dispatcher<C>>,
    caller: C,
    session_state: Arc<SessionStateFn>,
    known_capabilities: Option<Vec<String>>,
}

impl<C: Clone + Send + Sync + 'static> DispatcherHandler<C> {
    /// Dispatch on `dispatcher` as `caller` (the authenticated principal
    /// of the opening handshake, RFC 8887 §4.1). `session_state` gives
    /// the Response's `sessionState` (RFC 8620 §3.4) at each dispatch.
    pub fn new(
        dispatcher: Arc<Dispatcher<C>>,
        caller: C,
        session_state: impl Fn() -> State + Send + Sync + 'static,
    ) -> Self {
        Self {
            dispatcher,
            caller,
            session_state: Arc::new(session_state),
            known_capabilities: None,
        }
    }

    /// Answer a Request whose `using` names a capability not in
    /// `capabilities` with `unknownCapability` (RFC 8620 §3.3) through
    /// [`jmap_server::check_known_capabilities`]. Without this every
    /// `using` is accepted.
    #[must_use]
    pub fn with_known_capabilities<I, S>(mut self, capabilities: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.known_capabilities = Some(capabilities.into_iter().map(Into::into).collect());
        self
    }
}

impl<C> fmt::Debug for DispatcherHandler<C> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("DispatcherHandler")
            .field("known_capabilities", &self.known_capabilities)
            .finish_non_exhaustive()
    }
}

impl<C: Clone + Send + Sync + 'static> RequestHandler for DispatcherHandler<C> {
    async fn handle(&self, request: JmapRequest) -> Result<JmapResponse, JmapError> {
        if let Some(known) = &self.known_capabilities {
            jmap_server::check_known_capabilities(&request, known)?;
        }
        let state = (self.session_state)();
        Ok(self
            .dispatcher
            .dispatch(request, self.caller.clone(), state)
            .await)
    }
}

/// The [`StateChange`](jmap_types::StateChange) a Response implies: the
/// `newState` of every `Foo/set` response whose state changed
/// (`oldState` differs, RFC 8620 §5.3), keyed by its `accountId` and the
/// data type `Foo`. `None` when nothing changed.
///
/// A deployment that learns of changes from its store instead (for
/// example changes other connections or other protocols make) publishes
/// those itself; this covers the writes made through this dispatcher.
pub fn state_change_for_response(response: &JmapResponse) -> Option<jmap_types::StateChange> {
    let mut changed: std::collections::BTreeMap<
        jmap_types::Id,
        std::collections::BTreeMap<String, State>,
    > = std::collections::BTreeMap::new();
    for call in &response.method_responses {
        let Some(type_name) = call.name.strip_suffix("/set") else {
            continue;
        };
        let args = &call.arguments;
        let (Some(account), Some(new)) = (
            args.get("accountId").and_then(serde_json::Value::as_str),
            args.get("newState").and_then(serde_json::Value::as_str),
        ) else {
            continue;
        };
        if args.get("oldState").and_then(serde_json::Value::as_str) == Some(new) {
            continue;
        }
        changed
            .entry(jmap_types::Id::from(account))
            .or_default()
            .insert(type_name.to_owned(), State::from(new));
    }
    (!changed.is_empty()).then(|| jmap_types::StateChange::new(changed))
}

/// A [`RequestHandler`] that runs `inner`, then publishes the state
/// changes of its `/set` responses ([`state_change_for_response`]) to a
/// [`PushHub`], so connections with push enabled hear about writes made
/// over the WebSocket without the deployment wiring it by hand.
///
/// ```
/// use std::sync::Arc;
/// use jmap_websocket::server::{DispatcherHandler, PublishingHandler, PushHub};
/// use jmap_websocket::jmap_server::Dispatcher;
/// use jmap_websocket::jmap_types::State;
///
/// let dispatcher: Arc<Dispatcher<()>> = Arc::new(Dispatcher::new());
/// let hub = PushHub::new(64);
/// let handler = PublishingHandler::new(
///     DispatcherHandler::new(dispatcher, (), || State::from("s0")),
///     hub.clone(),
/// );
/// # let _ = handler;
/// ```
#[derive(Debug)]
pub struct PublishingHandler<H> {
    inner: H,
    hub: PushHub,
}

impl<H: RequestHandler> PublishingHandler<H> {
    /// Publish `inner`'s `/set` state changes to `hub`.
    pub fn new(inner: H, hub: PushHub) -> Self {
        Self { inner, hub }
    }
}

impl<H: RequestHandler> RequestHandler for PublishingHandler<H> {
    async fn handle(&self, request: JmapRequest) -> Result<JmapResponse, JmapError> {
        let response = self.inner.handle(request).await?;
        if let Some(change) = state_change_for_response(&response) {
            self.hub.publish(change);
        }
        Ok(response)
    }

    fn prepare_problem(&self, problem: &mut ProblemDetails) {
        self.inner.prepare_problem(problem);
    }
}

// ---------------------------------------------------------------------------
// Push
// ---------------------------------------------------------------------------

/// Where a connection's push notifications come from (RFC 8887 §4.3.5).
///
/// One value serves one connection, so it may be scoped to the
/// connection's caller: it must yield only changes that caller may see.
pub trait PushSource: Send + 'static {
    /// Start a subscription for `enable`: yield every later state change,
    /// and first, when `enable.push_state` is a token this source issued,
    /// the changes since it ("the server SHOULD immediately send all
    /// changes since that state token", §4.3.5.2).
    ///
    /// The source may skip types outside `enable.data_types`; the driver
    /// cuts every notification to them anyway. A stream that ends turns
    /// push off for the connection.
    fn subscribe(&mut self, enable: &WebSocketPushEnable) -> BoxStream<'static, WsStateChange>;
}

/// A [`PushSource`] that never pushes, for a server whose capability says
/// `supportsPush: false`. A [`WebSocketPushEnable`] is accepted and
/// yields nothing.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default)]
pub struct NoPush;

impl PushSource for NoPush {
    fn subscribe(&mut self, _enable: &WebSocketPushEnable) -> BoxStream<'static, WsStateChange> {
        futures::stream::empty().boxed()
    }
}

/// Cuts `change` to `data_types` (RFC 8887 §4.3.5.2: "A `StateChange`
/// notification will only be sent if the data for one of these types
/// changes. Other types are omitted from the `TypeState` object.").
///
/// `None` keeps every type. Accounts left with no types are dropped;
/// `None` is returned when nothing is left. An empty list therefore
/// matches nothing.
pub fn filter_state_change(
    mut change: WsStateChange,
    data_types: Option<&[String]>,
) -> Option<WsStateChange> {
    if let Some(types) = data_types {
        change.state_change.changed.retain(|_, by_type| {
            by_type.retain(|name, _| types.iter().any(|t| t == name));
            !by_type.is_empty()
        });
    }
    if change.state_change.changed.is_empty() {
        None
    } else {
        Some(change)
    }
}

// ---------------------------------------------------------------------------
// The driver
// ---------------------------------------------------------------------------

/// Why [`Connection::run`] stopped early.
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum ConnectionError {
    /// The incoming stream returned an error.
    #[error("receiving a WebSocket message failed")]
    Receive(#[source] Box<dyn std::error::Error + Send + Sync>),
    /// The outgoing sink returned an error.
    #[error("sending a WebSocket message failed")]
    Send(#[source] Box<dyn std::error::Error + Send + Sync>),
    /// A server message did not serialize.
    #[error("serializing a server message failed")]
    Serialize(#[source] serde_json::Error),
}

/// One JMAP-over-WebSocket connection: a [`RequestHandler`], a
/// [`PushSource`] and limits. See the [module docs](self).
pub struct Connection<H, P = NoPush> {
    handler: Arc<H>,
    push: P,
    config: ConnectionConfig,
    shared_limit: Option<Arc<Semaphore>>,
    extensions: Extensions,
    close: Arc<close::Shared>,
}

impl<H, P> fmt::Debug for Connection<H, P> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Connection")
            .field("config", &self.config)
            .field("shared_limit", &self.shared_limit.is_some())
            .field("extensions", &self.extensions)
            .finish_non_exhaustive()
    }
}

impl<H: RequestHandler> Connection<H, NoPush> {
    /// A connection answering with `handler`, with no push
    /// ([`NoPush`]) and the default [`ConnectionConfig`].
    pub fn new(handler: Arc<H>) -> Self {
        Self {
            handler,
            push: NoPush,
            config: ConnectionConfig::default(),
            shared_limit: None,
            extensions: Extensions::default(),
            close: close::Shared::new(),
        }
    }
}

type InFlight = std::pin::Pin<
    Box<
        dyn Future<
                Output = (
                    Option<String>,
                    Result<JmapResponse, JmapError>,
                    Option<OwnedSemaphorePermit>,
                ),
            > + Send,
    >,
>;

impl<H: RequestHandler, P: PushSource> Connection<H, P> {
    /// Push notifications from `push`.
    pub fn with_push<Q: PushSource>(self, push: Q) -> Connection<H, Q> {
        Connection {
            handler: self.handler,
            push,
            config: self.config,
            shared_limit: self.shared_limit,
            extensions: self.extensions,
            close: self.close,
        }
    }

    /// Use `config`.
    #[must_use]
    pub fn with_config(mut self, config: ConnectionConfig) -> Self {
        self.config = config;
        self
    }

    /// Also hold a permit of `limit` while each Request runs, failing the
    /// Request with `maxConcurrentRequests` when none is free. Share one
    /// semaphore with the HTTP API endpoint to apply the limit to "the sum
    /// of requests made on both" (RFC 8887 §4.3.2).
    #[must_use]
    pub fn with_shared_limit(mut self, limit: Arc<Semaphore>) -> Self {
        self.shared_limit = Some(limit);
        self
    }

    /// Route client messages of `handler`'s
    /// [`message_types`](ExtensionHandler::message_types) to `handler`
    /// instead of answering them with `notRequest`. Call it once per
    /// extension capability the Session advertises; see
    /// [`ExtensionHandler`] for the order of calls.
    ///
    /// # Panics
    ///
    /// If one of the types is an RFC 8887 type (`Request`,
    /// `WebSocketPushEnable`, `WebSocketPushDisable`, `Response`,
    /// `RequestError`, `StateChange`) or was registered by an earlier
    /// handler: both are programming errors.
    #[must_use]
    pub fn with_extension<X: ExtensionHandler>(mut self, handler: X) -> Self {
        self.extensions.register(handler);
        self
    }

    /// A handle that closes this connection while it runs, with a Close
    /// frame code and reason of the deployment's choosing (for expired
    /// credentials, RFC 8887 §4.2). Take it before calling
    /// [`run`](Self::run); see [`CloseHandle`] for what closing does.
    pub fn close_handle(&self) -> CloseHandle {
        CloseHandle::new(Arc::clone(&self.close))
    }

    /// Serve the connection until the client closes it, the incoming
    /// stream ends, or the deployment closes it.
    ///
    /// Returns `Ok` after a Close, the end of `incoming`, a binary
    /// message under [`BinaryFrames::Close`] (after sending the Close), or
    /// a [`CloseHandle::close`] (after sending its Close).
    /// Requests still running then are dropped; method calls the
    /// [`Dispatcher`] already started still finish (see
    /// [`Dispatcher::dispatch`], Cancellation). Before returning, by any
    /// path, it closes the extension message queue, waits for an
    /// [`ExtensionHandler::handle`] that is running, and calls every
    /// [`ExtensionHandler::close`].
    ///
    /// # Errors
    ///
    /// [`ConnectionError`] if `incoming` or `outgoing` fails, or a message
    /// does not serialize.
    pub async fn run<S, K, E>(self, mut incoming: S, mut outgoing: K) -> Result<(), ConnectionError>
    where
        S: Stream<Item = Result<Inbound, E>> + Unpin,
        E: std::error::Error + Send + Sync + 'static,
        K: Sink<Outbound> + Unpin,
        K::Error: std::error::Error + Send + Sync + 'static,
    {
        let Self {
            handler,
            mut push,
            config,
            shared_limit,
            mut extensions,
            close,
        } = self;
        let mut in_flight: FuturesUnordered<InFlight> = FuturesUnordered::new();
        let mut subscription: Option<(BoxStream<'static, WsStateChange>, Option<Vec<String>>)> =
            None;
        let mut extension_queue = extensions.start(config.extension_queue_capacity);

        let result: Result<(), ConnectionError> = async {
            loop {
                // Checked first so that, once a Close is requested, no
                // other ready branch writes ahead of it.
                if let Some((code, reason)) = close.requested_now() {
                    let frame = Outbound::Close { code: code.as_u16(), reason };
                    send(&mut outgoing, frame).await?;
                    return Ok(());
                }
                tokio::select! {
                    // Polled in order, close first: when the loop was
                    // already waiting here and a Close request and another
                    // branch become ready together, the Close must win.
                    biased;
                    // Only wakes the loop; the check above sends the Close.
                    _ = close.requested() => {}
                    done = in_flight.next(), if !in_flight.is_empty() => {
                        let Some((request_id, result, permit)) = done else { continue };
                        drop(permit);
                        let text = match result {
                            Ok(response) => to_text(&WsResponse::new(response, request_id))?,
                            Err(err) => error_text(&*handler, request_error(&err, request_id))?,
                        };
                        send(&mut outgoing, Outbound::Text(text)).await?;
                    }
                    change = next_change(&mut subscription) => {
                        match change {
                            Some(change) => {
                                let types = subscription.as_ref().and_then(|(_, t)| t.as_deref());
                                if let Some(change) = filter_state_change(change, types) {
                                    send(&mut outgoing, Outbound::Text(to_text(&change)?)).await?;
                                }
                            }
                            None => subscription = None,
                        }
                    }
                    (id, result) = extensions.next_done() => {
                        if let Err(err) = result {
                            let text = error_text(&*handler, extension::extension_error(&err, id))?;
                            send(&mut outgoing, Outbound::Text(text)).await?;
                        }
                    }
                    queued = next_queued(&mut extension_queue) => {
                        match queued {
                            Some(text) => send(&mut outgoing, Outbound::Text(text)).await?,
                            // Every handler dropped its sender.
                            None => extension_queue = None,
                        }
                    }
                    // While an extension message is handled, later messages
                    // wait, so they see its effect.
                    message = incoming.next(), if !extensions.is_busy() => {
                        let message = match message {
                            None | Some(Ok(Inbound::Close)) => return Ok(()),
                            Some(Err(e)) => return Err(ConnectionError::Receive(Box::new(e))),
                            Some(Ok(m)) => m,
                        };
                        let text = match message {
                            Inbound::Text(text) => text,
                            Inbound::Binary => match config.binary_frames {
                                BinaryFrames::Ignore => continue,
                                BinaryFrames::Close => {
                                    let close = Outbound::Close {
                                        code: CLOSE_UNSUPPORTED_DATA,
                                        reason: "binary messages are not supported".to_owned(),
                                    };
                                    send(&mut outgoing, close).await?;
                                    return Ok(());
                                }
                            },
                            Inbound::Close => return Ok(()),
                        };
                        let parsed = parse_message(&text, &config, |ty| extensions.handles(ty));
                        let message = match parsed {
                            Ok(Parsed::Extension(message)) => {
                                extensions.dispatch(message);
                                continue;
                            }
                            Ok(Parsed::Core(message)) => Ok(message),
                            Err(e) => Err(e),
                        };
                        match message {
                            Err(e) => {
                                send(&mut outgoing, Outbound::Text(error_text(&*handler, e)?)).await?;
                            }
                            Ok(ClientMessage::Request(WsRequest { id, request })) => {
                                match admit(&in_flight, &config, shared_limit.as_ref()) {
                                    Ok(permit) => {
                                        let h = Arc::clone(&handler);
                                        in_flight.push(Box::pin(async move {
                                            let result = h.handle(request).await;
                                            (id, result, permit)
                                        }));
                                    }
                                    Err(()) => {
                                        let err = JmapError::limit("maxConcurrentRequests");
                                        let text = error_text(&*handler, request_error(&err, id))?;
                                        send(&mut outgoing, Outbound::Text(text)).await?;
                                    }
                                }
                            }
                            Ok(ClientMessage::PushEnable(enable)) => {
                                let stream = push.subscribe(&enable);
                                subscription = Some((stream, enable.data_types));
                            }
                            Ok(ClientMessage::PushDisable(_)) => subscription = None,
                        }
                    }
                }
            }
        }
        .await;

        close.end();
        // Close the queue first, so a handler waiting to send returns.
        drop(extension_queue);
        extensions.close().await;
        result
    }
}

/// The next queued extension message; pending forever without a queue.
async fn next_queued(queue: &mut Option<mpsc::Receiver<String>>) -> Option<String> {
    match queue {
        Some(rx) => rx.recv().await,
        None => std::future::pending().await,
    }
}

/// A slot for one more Request, or `Err` at the limit.
fn admit(
    in_flight: &FuturesUnordered<InFlight>,
    config: &ConnectionConfig,
    shared: Option<&Arc<Semaphore>>,
) -> Result<Option<OwnedSemaphorePermit>, ()> {
    if in_flight.len() >= config.max_concurrent_requests {
        return Err(());
    }
    match shared {
        None => Ok(None),
        Some(s) => Arc::clone(s).try_acquire_owned().map(Some).map_err(|_| ()),
    }
}

/// The next push from the subscription; pending forever without one.
async fn next_change(
    subscription: &mut Option<(BoxStream<'static, WsStateChange>, Option<Vec<String>>)>,
) -> Option<WsStateChange> {
    match subscription {
        Some((stream, _)) => stream.next().await,
        None => std::future::pending().await,
    }
}

fn to_text<T: serde::Serialize>(message: &T) -> Result<String, ConnectionError> {
    serde_json::to_string(message).map_err(ConnectionError::Serialize)
}

fn error_text<H: RequestHandler>(
    handler: &H,
    mut error: WsRequestError,
) -> Result<String, ConnectionError> {
    handler.prepare_problem(&mut error.problem);
    to_text(&error)
}

async fn send<K>(outgoing: &mut K, message: Outbound) -> Result<(), ConnectionError>
where
    K: Sink<Outbound> + Unpin,
    K::Error: std::error::Error + Send + Sync + 'static,
{
    outgoing
        .send(message)
        .await
        .map_err(|e| ConnectionError::Send(Box::new(e)))
}

#[cfg(test)]
mod tests;