17 unstable releases (3 breaking)
0.3.6 | May 2, 2023 |
---|---|
0.3.5 | Mar 13, 2023 |
0.3.4 | Feb 22, 2023 |
0.3.0-alpha.2 |
|
0.0.1 | Dec 9, 2022 |
#726 in Web programming
77 downloads per month
47KB
1K
SLoC
cometd-client
lib.rs
:
This crate aims to make a client for CometD protocol.
This project is in progress and might change a lot from version to version.
Table of contents
- Connect endpoints
- Authentication
- Authentication through authorization header
- Authentication through cookie
- How to interact with client?
Connect endpoints
Client has ability to customize endpoints base paths:
- [
CometdClientBuilder::handshake_base_path
]; - [
CometdClientBuilder::subscribe_base_path
]; - [
CometdClientBuilder::connect_base_path
]; - [
CometdClientBuilder::disconnect_base_path
];
For example to change handshake base path and
get http://[::1]:1025/notifications/node/0/handshake
you can do this:
use cometd_client::CometdClientBuilder;
# || -> Result<(), Box<dyn std::error::Error>> {
let client = CometdClientBuilder::new(&"http://[::1]:1025/notifications/".parse()?)
.handshake_base_path("hand/")
.build()?;
# let _client: cometd_client::CometdClient<()> = client;
# Ok(())
# };
Same for others endpoints.
Authentication
There is 2 options to authenticate on server,
through authorization
header and cookie.
Authentication through authorization header
To use access token with authorization
header,
you must set it through [CometdClientBuilder::access_token
].
This library provide 2 default structs:
[types::access_token::Bearer
] and [types::access_token::Basic
].
use cometd_client::{CometdClientBuilder, types::access_token::{Bearer, Basic}};
# || -> Result<(), Box<dyn std::error::Error>> {
// let access_token = Bearer::new("access-token");
let access_token = Basic::create("username", Some("optional password"))?;
let client = CometdClientBuilder::new(&"http://[::1]:1025/notifications/".parse()?)
.access_token(access_token)
.build()?;
# let _client: cometd_client::CometdClient<()> = client;
# Ok(())
# };
But you can make you own access token for authorization
header:
use core::fmt::{Formatter, Debug};
use cometd_client::types::AccessToken;
struct OAuth(String);
impl Debug for OAuth {
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
write!(f, "OAuth(***)")
}
}
impl OAuth {
pub fn new(access_token: &str) -> Self {
Self(format!("OAuth {access_token}"))
}
}
impl AccessToken for OAuth {
fn get_authorization_token(&self) -> &str {
&self.0
}
}
Authentication through cookie
If you use session cookies for authentication (or other reasons) you can set it (or them)
through [CometdClientBuilder::cookie
] or [CometdClientBuilder::cookies
].
use cometd_client::CometdClientBuilder;
# || -> Result<(), Box<dyn std::error::Error>> {
let client = CometdClientBuilder::new(&"http://[::1]:1025/notifications/".parse()?)
.cookie("cookie0-name", "cookie0-value")
.cookies([
("cookie1-name", "cookie1-value"),
("cookie2-name", "cookie2-value")
])
.build()?;
# let _client: cometd_client::CometdClient<()> = client;
# Ok(())
# };
How to interact with client?
Client use MPMC channel to send messages and errors.
[CometdClientBuilder::build
] spawn task which do handshake and start wait for messages.
If handshake request was unsuccessful with [types::Reconnect::Handshake
] or [types::Reconnect::Retry
] advice from server,
then client tries redo it by [CometdClientBuilder::number_of_retries
] times.
In other cases task send error to event channel and stops.
After successful handshake task start listen messages coming from server.
If during that requests occurs error with [types::Reconnect::Handshake
] advice,
then client will tries redo handshake (look above).
If error will be with [types::Reconnect::Retry
] advice, then it will try redo it
by [CometdClientBuilder::number_of_retries
] times.
To send subscribe command you must use [CometdClient::subscribe
].
If error occurs it will be redone by same scheme as for connect (look above).
To get event channel receiver use [CometdClient::rx
].
use cometd_client::{types::CometdClientEvent, CometdClientBuilder};
# async fn _test() -> Result<(), Box<dyn std::error::Error>> {
let client = CometdClientBuilder::new(&"http://[::0]:1025/notifications/".parse()?)
.build()?;
# let client: cometd_client::CometdClient<()> = client;
let mut rx = client.rx();
tokio::spawn(async move {
while let Some(event) = rx.recv().await {
match event {
CometdClientEvent::Message(messages) => println!("got messages: `{messages:?}`."),
CometdClientEvent::Error(error) => eprintln!("got error: `{error:?}`."),
}
}
});
# Ok(())
# }
Dependencies
~10–16MB
~304K SLoC