eventsource

type CommentSentInfo struct {
	// Channel is the channel the comment was sent on.
	Channel string
	// WriteDuration is the wall time spent encoding and flushing this comment to
	// the connection. It is measured only when the CommentSent callback is set,
	// so a consumer can back-date a span start to WriteDuration before this
	// callback fires.
	WriteDuration time.Duration
}

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

type DecoderOption interface {
	// contains filtered or unexported methods
}

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

type Event interface {
	// Id is an identifier that can be used to allow a client to replay
	// missed Events by returning the Last-Event-Id header.
	// Return empty string if not required.
	Id() string
	// The name of the event. Return empty string if not required.
	Event() string
	// The payload of the event. Repeated calls must return the same value:
	// the server may read it more than once, for example when accounting for
	// payload sizes in addition to encoding.
	Data() string
}

type EventDiscardedInfo struct {
	// Channel is the channel the event would have been sent on.
	Channel string
	// Reason describes why the event was discarded.
	Reason EventDiscardedReason
}

type EventDiscardedReason string

type EventSentInfo struct {
	// Channel is the channel the event was sent on.
	Channel string
	// EventType is the event's type name, which may be empty.
	EventType string
	// DataSize is the size in bytes of the event's data payload only. It does
	// not include the id/event field values or SSE framing, and it measures
	// the payload before any compression, so it does not correspond exactly to
	// the bytes on the wire.
	DataSize int
	// WriteDuration is the wall time spent encoding and flushing this event to
	// the connection. It is measured only when the EventSent callback is set,
	// so a consumer can back-date a span start to WriteDuration before this
	// callback fires.
	WriteDuration time.Duration
}

type EventWithHeaders interface {
	// Headers provides access to the HTTP response headers for the event.
	Headers() http.Header
}

type EventWithLastID interface {
	// LastEventID is the value of the `id:` field that was most recently seen in an event
	// from this stream, if any. This differs from Event.Id() in that it retains the same
	// value in subsequent events if they do not provide their own `id:` field.
	LastEventID() string
}

type Logger interface {
	Println(...interface{})
	Printf(string, ...interface{})
}

type ReplayFinishedInfo struct {
	// Channel is the channel that was replayed.
	Channel string
	// EventCount is the number of replayed events written to the connection.
	// For a completed batch they have also been flushed, though a flush cannot
	// report failure, so this does not guarantee the client received them; for
	// an aborted batch they may never have been flushed at all (see Aborted).
	EventCount int
	// TotalDataSize is the summed size in bytes of the data payloads of all
	// replayed events in the batch. Like EventSentInfo.DataSize it counts the
	// data payload only -- no id/event field values, no SSE framing, measured
	// before any compression -- so it does not correspond exactly to the bytes
	// on the wire.
	TotalDataSize int64
	// DrainDuration is how long draining the batch took, as observed by the
	// connection handler, including the single flush at the end of the batch.
	// The measurement starts after the ReplayStarted callback returns, so that
	// callback's own cost is not included. A consumer can back-date a span
	// start to DrainDuration before the ReplayFinished callback fires.
	DrainDuration time.Duration
	// Aborted reports that the connection ended -- client disconnect,
	// MaxConnTime, or a write error -- before the end of the batch was
	// observed. (The handler checks the batch once more at exit, so a batch
	// that fully drained just as the connection ended is still reported
	// completed.) EventCount and TotalDataSize then reflect only the events
	// written before the exit, those events may never have been flushed to the
	// connection, and DrainDuration excludes the end-of-batch flush because
	// none occurred.
	//
	// Aborted is best-effort. If Server.Close races a subscriber that is
	// itself disconnecting mid-batch, the shutdown's drain of the abandoned
	// batch can make the batch appear completed even though the drained events
	// never reached the client; treat Aborted as a strong signal, not an exact
	// accounting.
	//
	// Aborted can also only describe what the Server observed. A Repository
	// that itself ends its batch early -- for example one that stops producing
	// when the request context is canceled -- yields a normal, non-aborted
	// ReplayFinished for whatever it produced.
	Aborted bool
}

type ReplayInfo struct {
	// Channel is the channel being replayed.
	Channel string
}

type Repository interface {
	// Gets the Events which should follow on from the specified channel and event id. This method may be called
	// from different goroutines, so it must be safe for concurrent access.
	//
	// It is important for the Repository to close the channel after all the necessary events have been
	// written to it. The stream will not be able to proceed to any new events until it has finished consuming
	// the channel that was returned by Replay.
	//
	// Replay may return nil if there are no events to be sent.
	Replay(channel, id string) chan Event
}

type RepositoryWithContext interface {
	Repository
	// ReplayWithContext behaves like Replay, but additionally receives a context that is cancelled
	// when the subscriber goes away. It has the same channel-closing responsibilities as Replay,
	// and may likewise return nil if there are no events to be sent.
	ReplayWithContext(ctx context.Context, channel, id string) <-chan Event
}

type Server struct {
	AllowCORS   bool          // Enable all handlers to be accessible from any origin
	ReplayAll   bool          // Replay repository even if there's no Last-Event-Id specified
	BufferSize  int           // How many messages do we let the client get behind before disconnecting
	Gzip        bool          // Enable compression if client can accept it
	MaxConnTime time.Duration // If non-zero, HTTP connections will be automatically closed after this time
	// Logger, when set, receives DEBUG lines for subscriber lifecycle events
	// (add, remove, replay drain), a WARN line when a slow subscriber is
	// dropped, and write errors. Lines identify connections by an opaque
	// subscriber id and never include the channel name, because channel names
	// may contain values (such as credentials) that must not appear in logs.
	Logger Logger
	// Trace, when set, receives callbacks at points in the Server's lifecycle. See
	// ServerTrace for the concurrency contract that callbacks must satisfy.
	//
	// EXPERIMENTAL: this field and the ServerTrace API are subject to change or
	// removal in any future release. See ServerTrace.
	Trace *ServerTrace
	// contains filtered or unexported fields
}

type ServerTrace struct {
	// SubscriberAdded is called once for each new subscriber, after the HTTP
	// response has been started and before the subscription is registered with
	// the Server, so it precedes every other callback for that subscriber.
	SubscriberAdded func(context.Context, SubscriberAddedInfo)

	// SubscriberRemoved is called when a subscriber's connection has ended, for
	// any reason. It is called once for each SubscriberAdded.
	SubscriberRemoved func(context.Context, SubscriberRemovedInfo)

	// SubscriberDropped is called when a subscriber is forcibly disconnected
	// because it could not keep up and fell more than BufferSize events behind.
	// SubscriberRemoved is also called for the same subscriber with reason
	// ReasonBufferOverflow, so a consumer that only needs a disconnect signal
	// can implement SubscriberRemoved alone. (The one exception is a drop that
	// lands after the handler has already finished removing the connection for
	// another cause; the removal that paired with it then carries that earlier
	// reason.)
	//
	// Unlike the other callbacks, this one takes no context: it fires on the
	// Server's dispatch goroutine, which has no association with any single
	// subscriber's request, so no request context is available here.
	SubscriberDropped func(SubscriberDroppedInfo)

	// EventSent is called after an event has been written to a subscriber's
	// connection and the write has been flushed, so a client may observe the
	// event before this callback runs. The info reports the event type, payload
	// size, and the measured write duration, but never the payload itself.
	//
	// EventSent fires only for events that are written and flushed
	// individually. Replayed events are encoded in bulk and not reported
	// individually here -- even though gzip compression or a full response
	// buffer may deliver some of their bytes before the batch ends -- so use
	// ReplayFinished for batch-level replay telemetry.
	EventSent func(context.Context, EventSentInfo)

	// CommentSent is called after a comment has been written to a subscriber's
	// connection.
	CommentSent func(context.Context, CommentSentInfo)

	// EventDiscarded is called when an event is dropped before delivery. This
	// currently happens only on jitter-enabled servers, which coalesce events
	// that arrive while an earlier event is still pending and discard a pending
	// event whose connection ends before its delay elapses. The discarded item
	// may be an event or a comment; both are reported here.
	EventDiscarded func(context.Context, EventDiscardedInfo)

	// WriteError is called when encoding or writing an event to a subscriber's
	// connection fails. The subscriber is removed after this callback.
	WriteError func(context.Context, WriteErrorInfo)

	// ReplayStarted is called when a subscriber begins draining a batch of
	// replayed events provided by a Repository. Every ReplayStarted is followed
	// by exactly one ReplayFinished for the same batch.
	ReplayStarted func(context.Context, ReplayInfo)

	// ReplayFinished is called when a subscriber has finished draining a batch
	// of replayed events, or when the connection ends while the batch is still
	// draining; the info's Aborted field distinguishes the two.
	ReplayFinished func(context.Context, ReplayFinishedInfo)
}

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

type Stream struct {

	// Events emits the events received by the stream
	Events chan Event
	// Errors emits any errors encountered while reading events from the stream.
	//
	// Errors during initialization of the stream are not pushed to this channel, since until the
	// Subscribe method has returned the caller would not be able to consume the channel. If you have
	// configured the Stream to be able to retry on initialization errors, but you still want to know
	// about those errors or control how they are handled, use StreamOptionErrorHandler.
	//
	// If an error handler has been specified with StreamOptionErrorHandler, the Errors channel is
	// not used and will be nil.
	Errors chan error

	// Logger is a logger that, when set, will be used for logging informational messages.
	//
	// This field is exported for backward compatibility, but should not be set directly because
	// it may be used by multiple goroutines. Use SetLogger instead.
	Logger Logger
	// contains filtered or unexported fields
}

type StreamErrorHandler func(error) StreamErrorHandlerResult

type StreamErrorHandlerResult struct {
	// CloseNow can be set to true to tell the Stream to immediately stop and not retry, as if Close had
	// been called.
	//
	// If CloseNow is false, the Stream will proceed as usual after an error: if there is an existing
	// connection it will retry the connection, and if the Stream is still being initialized then the
	// retry behavior is configurable (see StreamOptionCanRetryFirstConnection).
	CloseNow bool
}

type StreamOption interface {
	// contains filtered or unexported methods
}

type SubscriberAddedInfo struct {
	// Channel is the channel the subscriber connected to.
	Channel string
	// SubscriberID is an opaque per-connection identifier that can be used to
	// correlate this callback with SubscriberRemoved and SubscriberDropped.
	// Identifiers are unique within one Server only; distinct Servers issue
	// overlapping ids.
	SubscriberID uint64
	// HasLastEventID reports whether the subscriber supplied a Last-Event-ID.
	HasLastEventID bool
}

type SubscriberDroppedInfo struct {
	// Channel is the channel the subscriber was connected to.
	Channel string
	// SubscriberID matches the value from the corresponding SubscriberAddedInfo.
	SubscriberID uint64
	// BufferSize is the number of events the subscriber was allowed to fall
	// behind before being dropped.
	BufferSize int
}

type SubscriberRemovedInfo struct {
	// Channel is the channel the subscriber was connected to.
	Channel string
	// SubscriberID matches the value from the corresponding SubscriberAddedInfo.
	SubscriberID uint64
	// Reason describes why the connection ended. When a Server-initiated close
	// races the handler's own exit, the reasons rank as follows:
	// buffer_overflow outranks everything, since the SubscriberDropped
	// callback that already fired promises a removal with the matching
	// reason; write_error outranks the remaining Server reasons, since the
	// handler has already reported that failure through WriteError; and any
	// Server-recorded reason outranks client_closed and max_conn_time. Reason
	// is empty only if the connection ended because a consumer callback
	// panicked on the handler goroutine, which leaves no recorded cause.
	Reason SubscriberRemovedReason
	// ConnDuration is how long the connection was open.
	ConnDuration time.Duration
}

type SubscriberRemovedReason string

type SubscriptionError struct {
	Code    int
	Message string
	Header  http.Header
}

type WriteErrorInfo struct {
	// Channel is the channel the write was attempted on.
	Channel string
	// Err is the error returned by encoding or writing the event.
	Err error
}