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
//! A client for Rails' Action Cable.
//!
//! A [`Client`] owns one WebSocket connection to an Action Cable server and multiplexes any
//! number of channel subscriptions over it. It keeps the connection alive the way the
//! official JavaScript client does: the server beats a ping every three seconds, and a
//! connection that goes quiet for longer than [`ClientBuilder::stale_after`] is torn down
//! and redialed with backoff. Subscriptions survive reconnects; they are resubscribed as
//! soon as the server says welcome.
//!
//! ```no_run
//! use actioncable::{Client, Identifier};
//! use serde_json::json;
//!
//! # async fn run() -> Result<(), actioncable::Error> {
//! let client = Client::builder("wss://example.com/cable").build()?;
//! client.connect().await?;
//!
//! let room = client
//! .subscribe(Identifier::new("RoomChannel").param("id", 42))
//! .await?;
//!
//! let reader = room.clone();
//! tokio::spawn(async move {
//! while let Some(message) = reader.next().await {
//! println!("{message}");
//! }
//! });
//!
//! room.perform("speak", json!({ "body": "Hello!" })).await?;
//! room.unsubscribe().await?;
//! client.close().await;
//! # Ok(())
//! # }
//! ```
//!
//! Two things are pluggable. A [`Transport`] carries bytes: the built-in
//! `WebSocketTransport` speaks RFC 6455 over tokio-tungstenite behind the default
//! `websocket` feature, and any other WebSocket library can be dropped in behind the same
//! trait with [`ClientBuilder::transport`]. Without the feature and without a transport,
//! [`ClientBuilder::build`] returns [`Error::NoTransport`]. A [`Protocol`] speaks one Action Cable
//! wire format, negotiated as one WebSocket subprotocol: [`V1Json`] implements
//! `actioncable-v1-json`, and a new format is a new `Protocol` rather than a fork of this
//! client. [`ClientBuilder::protocols`] offers several, and the server picks the one it
//! knows.
//!
//! Where the Go client takes a `context`, this one takes nothing: [`Client::connect`] and
//! [`Client::subscribe`] wait until the server answers or the client stops, and a caller
//! who wants a deadline wraps the call in [`tokio::time::timeout`]. Dropping either future
//! is safe. The client keeps running — [`Client::last_error`] says what it is failing on —
//! and a subscription the server never confirmed is forgotten.
//!
//! A client that stops for good says so through [`Client::done`] and [`Client::err`]: the
//! server hung up and said not to come back, the attempts
//! [`ClientBuilder::max_attempts`] allows ran out, or
//! [`ClientBuilder::stop_on_error`] recognized a failure no reconnect can repair.
//!
//! Where the Go client takes callbacks, this one offers both: a stream of [`Event`]s on
//! every [`Subscription`], and [`SubscribeRequest`] for the callback form on top of the
//! same stream. Headers that expire come from a [`HeaderProvider`], which a closure
//! returning a future satisfies. Nothing here logs through a logger of its own; the
//! client's chatter goes to `tracing`.
//!
//! The `test-support` feature adds `actioncable::test_support`, an in-memory transport a
//! test plays the server on, for testing code built on this client without a network.
pub use ;
pub use Client;
pub use ;
pub use Identifier;
pub use Message;
pub use ;
pub use ;
pub use ;
pub use ;
pub use WebSocketTransport;
/// Compiles the README's examples as doctests.
;