OpenSource/axum
OpenSource/axum
1
0
Fork 0
mirror of https://github.com/tokio-rs/axum.git synced 2024-11-23 07:39:25 +01:00
Code Issues Projects Releases Packages Wiki Activity

Improve documentation of sse::Event (#601)

Browse source
This commit is contained in:
Kai Jewson 2021-12-12 15:56:07 +00:00 committed by GitHub
parent 9ed18d92cf
commit 9344d27cfa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
axum/src/response/sse.rs
View file

@ -181,8 +181,13 @@ enum DataType {
}
impl Event {
/// Set Server-sent event data
/// data field(s) ("data:<content>")
/// Set the event's data data field(s) (`data:<content>`)
///
/// Newlines in `data` will automatically be broken across `data:` fields.
///
/// This corresponds to [`MessageEvent`'s data field].
///
/// [`MessageEvent`'s data field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/data
pub fn data<T>(mut self, data: T) -> Event
where
T: Into<String>,
@ -191,8 +196,11 @@ impl Event {
self
}
/// Set Server-sent event data
/// data field(s) ("data:<content>")
/// Set the event's data field to a value serialized as unformatted JSON (`data:<content>`).
///
/// This corresponds to [`MessageEvent`'s data field].
///
/// [`MessageEvent`'s data field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/data
#[cfg(feature = "json")]
#[cfg_attr(docsrs, doc(cfg(feature = "json")))]
pub fn json_data<T>(mut self, data: T) -> Result<Event, serde_json::Error>
@ -203,8 +211,9 @@ impl Event {
Ok(self)
}
/// Set Server-sent event comment
/// Comment field (":<comment-text>")
/// Set the event's comment field (`:<comment-text>`).
///
/// This field will be ignored by most SSE clients.
pub fn comment<T>(mut self, comment: T) -> Event
where
T: Into<String>,
@ -213,8 +222,15 @@ impl Event {
self
}
/// Set Server-sent event event
/// Event name field ("event:<event-name>")
/// Set the event's name field (`event:<event-name>`).
///
/// This corresponds to the `type` parameter given when calling `addEventListener` on an
/// [`EventSource`]. For example, `.event("update")` should correspond to
/// `.addEventListener("update", ...)`. If no event type is given, browsers will fire a
/// [`message` event] instead.
///
/// [`EventSource`]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource
/// [`message` event]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event
pub fn event<T>(mut self, event: T) -> Event
where
T: Into<String>,
@ -223,15 +239,23 @@ impl Event {
self
}
/// Set Server-sent event retry
/// Retry timeout field ("retry:<timeout>")
/// Set the event's retry timeout field (`retry:<timeout>`).
///
/// This sets how long clients will wait before reconnecting if they are disconnected from the
/// SSE endpoint. Note that this is just a hint: clients are free to wait for longer if they
/// wish, such as if they implement exponential backoff.
pub fn retry(mut self, duration: Duration) -> Event {
self.retry = Some(duration);
self
}
/// Set Server-sent event id
/// Identifier field ("id:<identifier>")
/// Set the event's identifier field (`id:<identifier>`).
///
/// This corresponds to [`MessageEvent`'s `lastEventId` field]. If no ID is in the event itself,
/// the browser will set that field to the last known message ID, starting with the empty
/// string.
///
/// [`MessageEvent`'s `lastEventId` field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
pub fn id<T>(mut self, id: T) -> Event
where
T: Into<String>,