itsscb/axum
1
0
Fork 0
mirror of https://github.com/tokio-rs/axum.git synced 2025-10-02 07:20:38 +00:00
Code Issues Packages Projects Releases 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 { impl Event {
/// Set Server-sent event data /// Set the event's data data field(s) (`data:<content>`)
/// 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 pub fn data<T>(mut self, data: T) -> Event
where where
T: Into<String>, T: Into<String>,
@ -191,8 +196,11 @@ impl Event {
self self
} }
/// Set Server-sent event data /// Set the event's data field to a value serialized as unformatted JSON (`data:<content>`).
/// data field(s) ("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(feature = "json")]
#[cfg_attr(docsrs, doc(cfg(feature = "json")))] #[cfg_attr(docsrs, doc(cfg(feature = "json")))]
pub fn json_data<T>(mut self, data: T) -> Result<Event, serde_json::Error> pub fn json_data<T>(mut self, data: T) -> Result<Event, serde_json::Error>
@ -203,8 +211,9 @@ impl Event {
Ok(self) Ok(self)
} }
/// Set Server-sent event comment /// Set the event's comment field (`:<comment-text>`).
/// Comment field (":<comment-text>") ///
/// This field will be ignored by most SSE clients.
pub fn comment<T>(mut self, comment: T) -> Event pub fn comment<T>(mut self, comment: T) -> Event
where where
T: Into<String>, T: Into<String>,
@ -213,8 +222,15 @@ impl Event {
self self
} }
/// Set Server-sent event event /// Set the event's name field (`event:<event-name>`).
/// Event 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 pub fn event<T>(mut self, event: T) -> Event
where where
T: Into<String>, T: Into<String>,
@ -223,15 +239,23 @@ impl Event {
self self
} }
/// Set Server-sent event retry /// Set the event's retry timeout field (`retry:<timeout>`).
/// 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 { pub fn retry(mut self, duration: Duration) -> Event {
self.retry = Some(duration); self.retry = Some(duration);
self self
} }
/// Set Server-sent event id /// Set the event's identifier field (`id:<identifier>`).
/// 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 pub fn id<T>(mut self, id: T) -> Event
where where
T: Into<String>, T: Into<String>,