Struct rocket::response::stream::Event

source ·
pub struct Event { /* private fields */ }
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 heartbeat 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§

source§

impl Event

source

pub fn empty() -> Self

Creates a new Event with an empty data field.

This is exactly equivalent to Event::data("").

§Example
use rocket::response::stream::Event;

let event = Event::empty();
source

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

Available 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);
source

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

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!");
source

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

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!");
source

pub fn retry(period: Duration) -> Self

Creates a new retry Event.

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

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

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

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");
source

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

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.

source

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

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("goodbye").with_comment("bye");
source

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

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("goodbye").with_comment("bye");
source

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

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§

source§

impl Clone for Event

source§

fn clone(&self) -> Event

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Event

source§

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

Formats the value using the given formatter. Read more
source§

impl Hash for Event

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

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

impl PartialEq for Event

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for Event

source§

impl StructuralPartialEq for Event

Auto Trait Implementations§

§

impl Freeze for Event

§

impl RefUnwindSafe for Event

§

impl Send for Event

§

impl Sync for Event

§

impl Unpin for Event

§

impl UnwindSafe for Event

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

source§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self, E>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

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

source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

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

source§

fn equivalent(&self, key: &K) -> bool

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

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

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

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Paint for T
where T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Resetting.

§Example
println!("{}", value.resetting());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> Upcast<T> for U
where T: UpcastFrom<U>,

source§

fn upcast(self) -> T

source§

impl<T, B> UpcastFrom<Counter<T, B>> for T

source§

fn upcast_from(value: Counter<T, B>) -> T

source§

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

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more