1 // Package eventsource implements a client and server to allow streaming data one-way over a HTTP connection 2 // using the Server-Sent Events API http://dev.w3.org/html5/eventsource/ 3 // 4 // The client and server respect the Last-Event-ID header. 5 // If the Repository interface is implemented on the server, events can be replayed in case of a network disconnection. 6 package eventsource 7 8 // Event is the interface for any event received by the client or sent by the server. 9 type Event interface { 10 // Id is an identifier that can be used to allow a client to replay 11 // missed Events by returning the Last-Event-Id header. 12 // Return empty string if not required. 13 Id() string 14 // The name of the event. Return empty string if not required. 15 Event() string 16 // The payload of the event. 17 Data() string 18 } 19 20 // Repository is an interface to be used with Server.Register() allowing clients to replay previous events 21 // through the server, if history is required. 22 type Repository interface { 23 // Gets the Events which should follow on from the specified channel and event id. This method may be called 24 // from different goroutines, so it must be safe for concurrent access. 25 // 26 // It is important for the Repository to close the channel after all the necessary events have been 27 // written to it. The stream will not be able to proceed to any new events until it has finished consuming 28 // the channel that was returned by Replay. 29 // 30 // Replay may return nil if there are no events to be sent. 31 Replay(channel, id string) chan Event 32 } 33 34 // Logger is the interface for a custom logging implementation that can handle log output for a Stream. 35 type Logger interface { 36 Println(...interface{}) 37 Printf(string, ...interface{}) 38 } 39 40 // StreamErrorHandlerResult contains values returned by StreamErrorHandler. 41 type StreamErrorHandlerResult struct { 42 // CloseNow can be set to true to tell the Stream to immediately stop and not retry, as if Close had 43 // been called. 44 // 45 // If CloseNow is false, the Stream will proceed as usual after an error: if there is an existing 46 // connection it will retry the connection, and if the Stream is still being initialized then the 47 // retry behavior is configurable (see StreamOptionCanRetryFirstConnection). 48 CloseNow bool 49 } 50 51 // StreamErrorHandler is a function type used with StreamOptionErrorHandler. 52 // 53 // This function will be called whenever Stream encounters either a network error or an HTTP error response 54 // status. The returned value determines whether Stream should retry as usual, or immediately stop. 55 // 56 // The error may be any I/O error returned by Go's networking types, or it may be the eventsource type 57 // SubscriptionError representing an HTTP error response status. 58 // 59 // For errors during initialization of the Stream, this function will be called on the same goroutine that 60 // called the Subscribe method; for errors on an existing connection, it will be called on a worker 61 // goroutine. It should return promptly and not block the goroutine. 62 // 63 // In this example, the error handler always logs the error with log.Printf, and it forces the stream to 64 // close permanently if there was an HTTP 401 error: 65 // 66 // func handleError(err error) eventsource.StreamErrorHandlerResult { 67 // log.Printf("stream error: %s", err) 68 // if se, ok := err.(eventsource.SubscriptionError); ok && se.Code == 401 { 69 // return eventsource.StreamErrorHandlerResult{CloseNow: true} 70 // } 71 // return eventsource.StreamErrorHandlerResult{} 72 // } 73 type StreamErrorHandler func(error) StreamErrorHandlerResult 74