event

Documentation

Overview

Package event is used for creating events that are sent from the server side.

Index

• Variables
• type Event
  • func (e *Event) AppendData(chunks ...[]byte)
  • func (e *Event) AppendText(chunks ...string)
  • func (e *Event) Clone() *Event
  • func (e *Event) Comment(comments ...string)
  • func (e *Event) ExpiresAt() time.Time
  • func (e *Event) ID() ID
  • func (e *Event) MarshalText() ([]byte, error)
  • func (e *Event) SetExpiry(t time.Time)
  • func (e *Event) SetID(id ID)
  • func (e *Event) SetName(name string) bool
  • func (e *Event) SetRetry(duration time.Duration)
  • func (e *Event) SetTTL(d time.Duration)
  • func (e *Event) String() string
  • func (e *Event) UnmarshalText(p []byte) error
  • func (e *Event) WriteTo(w io.Writer) (int64, error)
• type ID
  • func MustID(value string) ID
  • func NewID(value string) (ID, bool)
  • func (i ID) IsSet() bool
  • func (i ID) String() string
• type UnmarshalError
  • func (u *UnmarshalError) Error() string
  • func (u *UnmarshalError) Unwrap() error

Variables

var ErrUnexpectedEOF = parser.ErrUnexpectedEOF

ErrUnexpectedEOF is returned when UnmarshalText isn't provided a byte slice that ends in a newline.

Types

type Event

type Event struct {
	// contains filtered or unexported fields
}

Event is the representation of a single message. This representation is used only for sending events - there is another event type for the client.

func (*Event) AppendData

func (e *Event) AppendData(chunks ...[]byte)

AppendData creates multiple data fields from the given byte slices.

Server-sent events are not suited for binary data: the event fields are delimited by newlines, where a newline can be a LF, CR or CRLF sequence. When the client interprets the fields, it joins multiple data fields using LF, so information is altered. Here's an example:

initial payload: This is a\r\nmultiline\rtext.\nIt has multiple\nnewline\r\nvariations.
data sent over the wire:
  data: This is a
  data: multiline
  data: text.
  data: It has multiple
  data: newline
  data: variations
data received by client: This is a\nmultiline\ntext.\nIt has multiple\nnewline\nvariations.

Each line prepended with "data:" is a field; multiple data fields are joined together using LF as the delimiter. If you attempted to send the same payload without prepending the "data:" prefix, like so:

data: This is a
multiline
text.
It has multiple
newline
variations

there would be only one data field (the first one). The rest would be different fields, named "multiline", "text.", "It has multiple" etc., which are invalid fields according to the protocol.

Besides, the protocol explicitly states that event streams must always be UTF-8 encoded: https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream.

Still, if you need to send binary data, you can use a Base64 encoder or any other encoder that does not output any newline characters (\n or \n) and then append the resulted byte slices.

func (*Event) AppendText

func (e *Event) AppendText(chunks ...string)

AppendText creates multiple data fields from the given strings. It uses the unsafe package to convert the string to a byte slice, so no allocations are made. See the AppendData method's documentation for details about the data field type.

func (*Event) Clone

func (e *Event) Clone() *Event

Clone returns a copy of the event.

func (*Event) Comment

func (e *Event) Comment(comments ...string)

Comment creates an event comment field. If it spans on multiple lines, new comment lines are created.

func (*Event) ExpiresAt

func (e *Event) ExpiresAt() time.Time

ExpiresAt returns the timestamp when the event expires.

func (*Event) ID

func (e *Event) ID() ID

ID returns the event's ID.

func (*Event) MarshalText

func (e *Event) MarshalText() ([]byte, error)

MarshalText writes the standard textual representation of the event. Marshalling and unmarshalling will not result in an event with the same fields: comment fields will not be unmarshalled, expiry time will be lost, and data fields won't be of the same type: a multiline Text field will be unmarshalled into multiple Line fields.

Use the WriteTo method if you don't need the byte representation.

The representation is written to a bytes.Buffer, which means the error is always nil. If the buffer grows to a size bigger than the maximum allowed, MarshalText will panic. See the bytes.Buffer documentation for more info.

func (*Event) SetExpiry

func (e *Event) SetExpiry(t time.Time)

SetExpiry sets the event's expiry time to the given timestamp.

This is not sent to the clients. The expiry time can be used when implementing event replay providers, to see if an event is still valid for replay.

func (*Event) SetID

func (e *Event) SetID(id ID)

SetID sets the event's ID.

func (*Event) SetName

func (e *Event) SetName(name string) bool

SetName sets the event's name.

A Name cannot have multiple lines. If it has, the function will return false.

func (*Event) SetRetry

func (e *Event) SetRetry(duration time.Duration)

SetRetry creates an event field that tells the client to set the event stream reconnection time to the number of milliseconds it provides.

func (*Event) SetTTL

func (e *Event) SetTTL(d time.Duration)

SetTTL sets the event's expiry time to a timestamp after the given duration from the current time.

This is not sent to the clients. The expiry time can be used when implementing event replay providers, to see if an event is still valid for replay.

func (*Event) String

func (e *Event) String() string

String writes the event's standard textual representation to a strings.Builder and returns the resulted string. It may panic if the representation is too long to be buffered.

Use the WriteTo method if you don't actually need the string representation.

func (*Event) UnmarshalText

func (e *Event) UnmarshalText(p []byte) error

UnmarshalText extracts the first event found in the given byte slice into the receiver. The receiver is always reset to the event's default value before unmarshaling, so always use a new Event instance if you don't want to overwrite data.

Unmarshaling ignores comments and fields with invalid names. If no valid fields are found, an error is returned. For a field to be valid it must end in a newline - if the last field of the event doesn't end in one, an error is returned.

All returned errors are of type UnmarshalError.

func (*Event) WriteTo

func (e *Event) WriteTo(w io.Writer) (int64, error)

WriteTo writes the standard textual representation of an event to an io.Writer. This operation is heavily optimized and does zero allocations, so it is strongly preferred over MarshalText or String.

type ID

type ID struct {
	// contains filtered or unexported fields
}

The ID struct represents any valid event ID value.

func MustID

func MustID(value string) ID

MustID is the same as NewID, but it panics if the input isn't a valid ID.

func NewID

func NewID(value string) (ID, bool)

NewID creates an ID value. It also returns a flag that indicates whether the input is a valid ID. A valid ID must not have any newlines. If the input is not valid, an unset (invalid) ID is returned.

func (ID) IsSet

func (i ID) IsSet() bool

IsSet returns true if the receiver is a valid (set) ID value.

func (ID) String

func (i ID) String() string

String returns the ID's value. The value may be an empty string, make sure to check if the ID is set before using the value.

type UnmarshalError

type UnmarshalError struct {
	Reason    error
	FieldName string
	// The value of the invalid field. This is a copy of the original value.
	FieldValue string
}

UnmarshalError is the error returned by the event's UnmarshalText method. If the error is related to a specific field, FieldName will be a non-empty string. If no fields were found in the target text or any other errors occurred, only a Reason will be provided. Reason is always present.

func (*UnmarshalError) Error

func (u *UnmarshalError) Error() string

func (*UnmarshalError) Unwrap

func (u *UnmarshalError) Unwrap() error