uhttp_sse

https://docs.rs/uhttp_sse
Admin
A zero-copy, zero-allocation Rust implementation of the Server-Sent Events (SSE) protocol for...
Tokens:3,240
Snippets:46
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Server-Sent Events (SSE) Message Construction

Source: https://docs.rs/uhttp_sse

This example demonstrates how to construct an SSE message using the SseMessage struct from the uhttp_sse crate. It shows how to write event and data fields and the resulting byte representation.

```APIDOC
## Server-Sent Events (SSE) Message Construction

### Description
This example demonstrates how to construct an SSE message using the `SseMessage` struct from the `uhttp_sse` crate. It shows how to write event and data fields and the resulting byte representation.

### Method
N/A (Code Example)

### Endpoint
N/A (Code Example)

### Parameters
N/A (Code Example)

### Request Example
N/A (Code Example)

### Response
#### Success Response (200)
N/A (Code Example)

#### Response Example
```rust
use uhttp_sse::SseMessage;
use std::io::Write;

let mut buf = [0; 31];

{
    let mut sse = SseMessage::new(&mut buf[..]);
    write!(sse.event().unwrap(), "ping").unwrap();
    write!(sse.data().unwrap(), "abc").unwrap();
    write!(sse.data().unwrap(), "{}", 1337).unwrap();
}

// This would result in the "ping" event listener being triggered with the data
// payload "abc1337".
assert_eq!(&buf[..], b"event:ping\ndata:abc\ndata:1337\n\n");
```
```

--------------------------------

### Finish SSE Messages

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

Demonstrates the use of the finish method to finalize an SSE message before starting a new one.

```rust
{
            let mut msg = SseMessage::new(&mut buf);
            write!(msg.data().unwrap(), "abc").unwrap();
            msg.finish().unwrap();
            write!(msg.data().unwrap(), "123").unwrap();
        }

        assert_eq!(buf, b"data:abc\n\ndata:123\n\n");
```

--------------------------------

### Create and Write SSE Message

Source: https://docs.rs/uhttp_sse

Demonstrates how to create an SSE message and write event and data fields to it. Ensure the buffer is large enough to hold the complete message.

```rust
use uhttp_sse::SseMessage;
use std::io::Write;

let mut buf = [0; 31];

{
    let mut sse = SseMessage::new(&mut buf[..]);
    write!(sse.event().unwrap(), "ping").unwrap();
    write!(sse.data().unwrap(), "abc").unwrap();
    write!(sse.data().unwrap(), "{}", 1337).unwrap();
}

// This would result in the "ping" event listener being triggered with the data
// payload "abc1337".
assert_eq!(&buf[..], b"event:ping\ndata:abc\ndata:1337\n\n");

```

--------------------------------

### Construct SSE Messages

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

Shows how to populate event, data, id, and retry fields within an SseMessage.

```rust
{
            let mut msg = SseMessage::new(&mut buf[..]);

            write!(msg.event().unwrap(), "1337").unwrap();
            write!(msg.data().unwrap(), "abc").unwrap();
            write!(msg.data().unwrap(), "def").unwrap();
            write!(msg.id().unwrap(), "42").unwrap();
            write!(msg.retry().unwrap(), "7").unwrap();
        }

        assert_eq!(&buf[..], &b"event:1337\ndata:abc\ndata:def\nid:42\nretry:7\n\n"[..]);
```

--------------------------------

### SseField Write Implementation: by_ref

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Creates a "by reference" adapter for the SseField writer.

```rust
fn by_ref(&mut self) -> &mut Self
where Self: Sized,
```

--------------------------------

### Write SSE Fields

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

Demonstrates writing multiple messages to an SseField buffer.

```rust
{
            let mut f = SseField::new(&mut buf[..], "hello").unwrap();

            write!(f, "a message {}", 1337).unwrap();
            write!(f, " another message").unwrap();
        }

        assert_eq!(&buf[..], &b"hello:a message 1337 another message\n"[..]);
```

--------------------------------

### SseMessage API

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseMessage.html

Methods for constructing and managing Server-Sent Event messages.

```APIDOC
## SseMessage Construction and Methods

### Description
The SseMessage struct allows for the creation of SSE messages. Fields are appended to the message, and the message is automatically flushed and terminated when the object goes out of scope or finish() is called.

### Methods
- **new(stream: W)**: Create a new SseMessage to write into the given stream.
- **data()**: Append a data field. This is the payload passed to the browser event listener.
- **event()**: Append an event name field to trigger specific event listeners.
- **id()**: Append an event ID field to set the last event ID.
- **retry()**: Append a retry field (integer) to set the reconnection time in milliseconds.
- **finish()**: Terminate the current message and begin a new one.

### Usage Example
```rust
let mut msg = SseMessage::new(stream);
msg.event()?.write("update")?;
msg.data()?.write("{\"status\": \"ok\"}")?;
msg.finish()?;
```
```

--------------------------------

### Use Cursor for SSE Messages

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

Utilizes a Cursor to write sequential SSE messages to a buffer.

```rust
{
            let mut c = Cursor::new(&mut buf[..]);

            {
                let mut msg = SseMessage::new(&mut c);
                write!(msg.data().unwrap(), "abc").unwrap();
            }

            {
                let mut msg = SseMessage::new(&mut c);
                write!(msg.data().unwrap(), "def").unwrap();
            }
        }

        assert_eq!(&buf[..], &b"data:abc\n\ndata:def\n\n"[..]);
```

--------------------------------

### SseField Write Implementation: write_all

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Attempts to write an entire buffer to the value of the current SSE field.

```rust
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
```

--------------------------------

### SseField Write Implementation: write_all_vectored

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Attempts to write multiple buffers to the value of the current SSE field. This is a nightly-only experimental API.

```rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
```

--------------------------------

### SseField Write Implementation: write_fmt

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Writes a formatted string to the value of the current SSE field, returning any error encountered.

```rust
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>
```

--------------------------------

### SseField Write Implementation: write_vectored

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Writes data from a slice of buffers into the current SSE field. This is an experimental API.

```rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>
```

--------------------------------

### SseField Write Implementation: write

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Appends data to the value of the current SSE field. This method writes a buffer into the writer and returns the number of bytes written.

```rust
fn write(&mut self, buf: &[u8]) -> Result<usize>
```

--------------------------------

### SseField Write Implementation: flush

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Ensures that all buffered contents for the current SSE field are written to their destination.

```rust
fn flush(&mut self) -> Result<()>
```

--------------------------------

### SseField Blanket Implementation: Borrow

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the Borrow trait, allowing immutable borrowing of the SseField.

```rust
fn borrow(&self) -> &T
```

--------------------------------

### SseField Blanket Implementation: Any

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the Any trait for any type T, providing runtime type information.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### SseField Blanket Implementation: From

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the From trait, allowing conversion from a type T to itself.

```rust
fn from(t: T) -> T
```

--------------------------------

### SseField Blanket Implementation: TryFrom

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the TryFrom trait, allowing fallible conversion from a type U to T.

```rust
type Error = Infallible

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

--------------------------------

### SseMessage API

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

The SseMessage struct represents an SSE message. It allows appending fields like data, event, id, and retry to the stream. The message is automatically terminated and flushed when the object goes out of scope.

```APIDOC
## SseMessage

### Description
Represents an SSE message. Each message consists of any number of fields followed by a message terminating sequence.

### Methods
- **new(stream: W)**: Creates a new SseMessage to write into the given stream.
- **data()**: Appends a data field to the message.
- **event()**: Appends an event name field to the message.
- **id()**: Appends an event ID field to the message.
- **retry()**: Appends a retry field (integer) to the message.
- **finish()**: Terminates the current message and begins a new one.

### Usage Example
```rust
let mut buf = [0; 31];
{
    let mut sse = SseMessage::new(&mut buf[..]);
    write!(sse.event().unwrap(), "ping").unwrap();
    write!(sse.data().unwrap(), "abc").unwrap();
}
```
```

--------------------------------

### SseField Write Implementation: is_write_vectored

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Determines if the writer for the SSE field has an efficient write_vectored implementation. This is a nightly-only experimental API.

```rust
fn is_write_vectored(&self) -> bool
```

--------------------------------

### SseField Blanket Implementation: BorrowMut

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the BorrowMut trait, allowing mutable borrowing of the SseField.

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

--------------------------------

### SseField Blanket Implementation: TryInto

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the TryInto trait, allowing fallible conversion from a type T to U.

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

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

--------------------------------

### SseField Blanket Implementation: Into

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the Into trait, allowing conversion to a type U if U implements From<T>.

```rust
fn into(self) -> U
where U: From<T>,
```

--------------------------------

### Define SseField Struct

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Defines the SseField struct, which holds a writer and represents a field in an SSE message. The assigned name is automatically written on initialization.

```rust
pub struct SseField<W: Write>(/* private fields */);
```

--------------------------------

### SseField Drop Implementation

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

Implements the Drop trait for SseField, ensuring that the field terminating sequence is written when the SseField object goes out of scope.

```rust
impl<W: Write> Drop for SseField<W>
Writes the field terminating sequence on drop.
```

--------------------------------

### SseField API

Source: https://docs.rs/uhttp_sse/latest/src/uhttp_sse/lib.rs.html

The SseField struct represents a single field within an SSE message, consisting of a name and a value.

```APIDOC
## SseField

### Description
Represents a field in an SSE message. The field name is written upon initialization, and the value is appended by writing into the object. The field is terminated when the object goes out of scope.

### Note
The written value must not contain any newline characters (\n).
```

--------------------------------

### SseField Struct

Source: https://docs.rs/uhttp_sse/latest/uhttp_sse/struct.SseField.html

The SseField struct is used to construct SSE message fields. It implements the Write trait, allowing data to be appended to the field value. Fields are automatically terminated when the object is dropped.

```APIDOC
## SseField

### Description
A field in an SSE message. Each field has a name and a value. The assigned name is automatically written when the object is initialized, and the value is then appended by writing into the SseField object. When the SseField object goes out of scope, the field is terminated.

### Usage
- The written value must not contain any `\n` newline characters.
- Implements `std::io::Write` to allow appending data to the field value.
- Implements `Drop` to write the field terminating sequence automatically.
```
Tokens:
Raw