Struct rocket::response::stream::Event[][src]

pub struct Event { /* fields omitted */ }
Expand description

A Server-Sent Event (SSE) in a Server-Sent EventStream.

A server-sent event is either a field or a comment. Comments can be constructed via Event::comment() while fields can be constructed via Event::data(), Event::json(), and Event::retry().

use rocket::tokio::time::Duration;
use rocket::response::stream::Event;

// A `data` event with message "Hello, SSE!".
let event = Event::data("Hello, SSE!");

// The same event but with event name of `hello`.
let event = Event::data("Hello, SSE!").event("hello");

// A `retry` event to set the client-side reconnection time.
let event = Event::retry(Duration::from_secs(5));

// An event with an attached comment, event name, and ID.
let event = Event::data("Hello, SSE!")
    .with_comment("just a hello message")
    .event("hello")
    .id("1");

We largely defer to MDN’s using server-sent events documentation for client-side details but reproduce, in our words, relevant server-side documentation here.

Pitfalls

Server-Sent Events suffer from certain pitfalls. We encourage readers to read through pitfalls before making use of Rocket’s SSE support.

Comments

A server-sent comment, created via Event::comment(), is an event that appears only in the raw server-sent event data stream and is inaccessible by most clients. This includes JavaScript’s EventSource. As such, they serve little utility beyond debugging a raw data stream and keeping a connection alive. See hearbeat for information on Rocket’s EventStream keep-alive.

Fields

A server-sent field can be one of four kinds:

  • retry

    A retry event, created via Event::retry(), sets the reconnection time on the client side. It is the duration the client will wait before attempting to reconnect when a connection is lost. Most applications will not need to set a retry, opting instead to use the implementation’s default or to reconnect manually on error.

  • id

    Sets the event id to associate all subsequent fields with. This value cannot be retrieved directly via most clients, including JavaScript EventSource. Instead, it is sent by the implementation on reconnection via the Last-Event-ID header. An id can be attached to other fields via the Event::id() builder method.

  • event

    Sets the event name to associate the next data field with. In JavaScript’s EventSource, this is the event to be listened for, which defaults to message. An event can be attached to other fields via the Event::event() builder method.

  • data

    Sends data to dispatch as an event at the client. In JavaScript’s EventSource, this (and only this) results in an event handler for event, specified just prior, being triggered. A data field can be created via the Event::data() or Event::json() constructors.

Implementation Notes

A constructed Event always emits its fields in the following order:

  1. comment
  2. retry
  3. id
  4. event
  5. data

The event and id fields cannot contain new lines or carriage returns. Rocket’s default implementation automatically converts new lines and carriage returns in event and id fields to spaces.

The data and comment fields cannot contain carriage returns. Rocket converts the unencoded sequence \r\n and the isolated \r into a protocol-level \n, that is, in such a way that they are interpreted as \n at the client. For example, the raw message foo\r\nbar\rbaz is received as foo\nbar\nbaz at the client-side. Encoded sequences, such as those emitted by Event::json(), have no such restrictions.

Implementations

impl Event[src]

pub fn json<T: Serialize>(data: &T) -> Self[src]

This is supported on crate feature json only.

Creates a new Event with a data field of data serialized as JSON.

Example

use rocket::serde::Serialize;
use rocket::response::stream::Event;

#[derive(Serialize)]
#[serde(crate = "rocket::serde")]
struct MyData<'r> {
    string: &'r str,
    number: usize,
}

let data = MyData { string: "hello!", number: 10 };
let event = Event::json(&data);

pub fn data<T: Into<Cow<'static, str>>>(data: T) -> Self[src]

Creates a new Event with a data field containing the raw data.

Raw SSE is Lossy

Unencoded carriage returns cannot be expressed in the protocol. Thus, any carriage returns in data will not appear at the client-side. Instead, the sequence \r\n and the isolated \r will each appear as \n at the client-side. For example, the message foo\r\nbar\rbaz is received as foo\nbar\nbaz at the client-side.

See pitfalls for more details.

Example

use rocket::response::stream::Event;

// A `data` event with message "Hello, SSE!".
let event = Event::data("Hello, SSE!");

pub fn comment<T: Into<Cow<'static, str>>>(data: T) -> Self[src]

Creates a new comment Event.

As with Event::data(), unencoded carriage returns cannot be expressed in the protocol. Thus, any carriage returns in data will not appear at the client-side. For comments, this is generally not a concern as comments are discarded by client-side libraries.

Example

use rocket::response::stream::Event;

let event = Event::comment("bet you'll never see me!");

pub fn retry(period: Duration) -> Self[src]

Creates a new retry Event.

Example

use rocket::response::stream::Event;
use rocket::tokio::time::Duration;

let event = Event::retry(Duration::from_millis(250));

pub fn event<T: Into<Cow<'static, str>>>(self, event: T) -> Self[src]

Sets the value of the ‘event’ (event type) field.

Event names may not contain new lines \n or carriage returns \r. If event does contain new lines or carriage returns, they are replaced with spaces ( ) before being sent to the client.

Example

use rocket::response::stream::Event;

// The event name is "start".
let event = Event::data("hi").event("start");

// The event name is "then end", with `\n` replaced with ` `.
let event = Event::data("bye").event("then\nend");

pub fn id<T: Into<Cow<'static, str>>>(self, id: T) -> Self[src]

Sets the value of the ‘id’ (last event ID) field.

Event IDs may not contain new lines \n or carriage returns \r. If id does contain new lines or carriage returns, they are replaced with spaces ( ) before being sent to the client.

Example

use rocket::response::stream::Event;

// The event ID is "start".
let event = Event::data("hi").id("start");

// The event ID is "then end", with `\n` replaced with ` `.
let event = Event::data("bye").id("then\nend");

Sets the value of the ‘id’ field. It may not contain newlines.

pub fn with_data<T: Into<Cow<'static, str>>>(self, data: T) -> Self[src]

Sets or replaces the value of the data field.

Example

use rocket::response::stream::Event;

// The data "hello" will be sent.
let event = Event::data("hi").with_data("hello");

// The two below are equivalent.
let event = Event::comment("bye").with_data("goodbye");
let event = Event::data("goodbyte").with_comment("bye");

pub fn with_comment<T: Into<Cow<'static, str>>>(self, data: T) -> Self[src]

Sets or replaces the value of the comment field.

Example

use rocket::response::stream::Event;

// The comment "🚀" will be sent.
let event = Event::comment("Rocket is great!").with_comment("🚀");

// The two below are equivalent.
let event = Event::comment("bye").with_data("goodbye");
let event = Event::data("goodbyte").with_comment("bye");

pub fn with_retry(self, period: Duration) -> Self[src]

Sets or replaces the value of the retry field.

Example

use rocket::response::stream::Event;
use rocket::tokio::time::Duration;

// The reconnection will be set to 10 seconds.
let event = Event::retry(Duration::from_millis(500))
    .with_retry(Duration::from_secs(10));

// The two below are equivalent.
let event = Event::comment("bye").with_retry(Duration::from_millis(500));
let event = Event::retry(Duration::from_millis(500)).with_comment("bye");

Trait Implementations

impl Clone for Event[src]

fn clone(&self) -> Event[src]

Returns a copy of the value. Read more

fn clone_from(&mut self, source: &Self)1.0.0[src]

Performs copy-assignment from source. Read more

impl Debug for Event[src]

fn fmt(&self, f: &mut Formatter<'_>) -> Result[src]

Formats the value using the given formatter. Read more

impl Hash for Event[src]

fn hash<__H: Hasher>(&self, state: &mut __H)[src]

Feeds this value into the given Hasher. Read more

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher
1.3.0[src]

Feeds a slice of this type into the given Hasher. Read more

impl PartialEq<Event> for Event[src]

fn eq(&self, other: &Event) -> bool[src]

This method tests for self and other values to be equal, and is used by ==. Read more

fn ne(&self, other: &Event) -> bool[src]

This method tests for !=.

impl Eq for Event[src]

impl StructuralEq for Event[src]

impl StructuralPartialEq for Event[src]

Auto Trait Implementations

impl RefUnwindSafe for Event

impl Send for Event

impl Sync for Event

impl Unpin for Event

impl UnwindSafe for Event

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<Q, K> Equivalent<K> for Q where
    K: Borrow<Q> + ?Sized,
    Q: Eq + ?Sized
[src]

pub fn equivalent(&self, key: &K) -> bool[src]

Compare self to key and return true if they are equal.

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

pub fn to_owned(&self) -> T[src]

Creates owned data from borrowed data, usually by cloning. Read more

pub fn clone_into(&self, target: &mut T)[src]

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V