diff --git a/CHANGELOG.md b/CHANGELOG.md index ab5675d..cf5df46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ This file tracks changes to this project. It follows the [Keep a Changelog forma ## Unreleased -This version removes all external dependencies of `go-sse`. All our bugs are belong to us! It also does some small API cleanups. +This version removes all external dependencies of `go-sse`. All our bugs are belong to us! It also does some API and documentation cleanups. ### Removed diff --git a/README.md b/README.md index 53e962a..2fa3ee4 100644 --- a/README.md +++ b/README.md @@ -318,18 +318,14 @@ type Event struct { Pretty self-explanatory, but make sure to read the [docs][6]! -Now, with this knowledge, let's subscribe to all unnamed events and, when the connection is established, print their data to `os.Stdout`: +Now, with this knowledge, let's subscribe to all unnamed events and, when the connection is established, print their data: ```go -out := log.New(os.Stdout, "", 0) - unsubscribe := conn.SubscribeMessages(func(event sse.Event) { - out.Printf("Received an unnamed event: %s\n", event.Data) + fmt.Printf("Received an unnamed event: %s\n", event.Data) }) ``` -We use a `log.Logger` instance because it synchronizes prints with a mutex: for each event the callback is called in a separate goroutine, so access to shared resources must be synchronized by the client. - ### Establishing the connection Great, we are subscribed now! Let's start receiving events: @@ -354,7 +350,9 @@ There may be situations where the connection does not have to live for indetermi ```go client := sse.Client{ - MaxRetries: 0, + Backoff: sse.Backoff{ + MaxRetries: -1, + }, // other settings... } @@ -390,7 +388,7 @@ Let's use what we know to create a client for the previous server example: package main import ( - "log" + "fmt" "net/http" "os" @@ -400,14 +398,13 @@ import ( func main() { r, _ := http.NewRequest(http.MethodGet, "http://localhost:8000", nil) conn := sse.NewConnection(r) - out := log.New(os.Stdout, "", 0) conn.SubscribeMessages(func(ev sse.Event) { - out.Printf("%s\n\n", ev.Data) + fmt.Printf("%s\n\n", ev.Data) }) if err := conn.Connect(); err != nil { - out.Println(err) + fmt.Fprintln(os.Stderr, err) } } ``` diff --git a/client_connection.go b/client_connection.go index 45bf2fc..fc00f79 100644 --- a/client_connection.go +++ b/client_connection.go @@ -34,7 +34,7 @@ type EventCallback func(Event) type EventCallbackRemover func() // Connection is a connection to an events stream. Created using the Client struct, -// a Connection processes the incoming events and sends them to the subscribed channels. +// a Connection processes the incoming events and calls the subscribed event callbacks. // If the connection to the server temporarily fails, the connection will be reattempted. // Retry values received from servers will be taken into account. // diff --git a/server.go b/server.go index 8008dd4..bd08cca 100644 --- a/server.go +++ b/server.go @@ -33,11 +33,8 @@ type Subscription struct { // The events will replay starting from the first valid event sent after the one with the given ID. // If the ID is invalid replaying events will be omitted and new events will be sent as normal. LastEventID EventID - // The topics to receive message from. If no topic is specified, a default topic is implied. + // The topics to receive message from. Must be a non-empty list. // Topics are orthogonal to event types. They are used to filter what the server sends to each client. - // - // If using a Provider directly, without a Server instance, you must specify at least one topic. - // The Server automatically adds the default topic if no topic is specified. Topics []string } @@ -46,7 +43,7 @@ type Subscription struct { // // Providers are required to be thread-safe. // -// After Stop is called, trying to call any method of the provider must return ErrProviderClosed. The providers +// After Shutdown is called, trying to call any method of the provider must return ErrProviderClosed. The providers // may return other implementation-specific errors too, but the close error is guaranteed to be the same across // providers. type Provider interface { @@ -74,14 +71,13 @@ type Provider interface { // ErrProviderClosed is a sentinel error returned by providers when any operation is attempted after the provider is closed. var ErrProviderClosed = errors.New("go-sse.server: provider is closed") -// ErrNoTopic is a sentinel error returned by providers when a Message is published without any topics. +// ErrNoTopic is a sentinel error returned by Providers when a Message is published without any topics. // It is not an issue to call Server.Publish without topics, because the Server will add the DefaultTopic; // it is an error to call Provider.Publish without any topics, though. var ErrNoTopic = errors.New("go-sse.server: no topics specified") // DefaultTopic is the identifier for the topic that is implied when no topics are specified for a Subscription -// or a Message. Providers are required to implement this behavior to ensure handlers don't break if providers -// are changed. +// or a Message. const DefaultTopic = "" // LogLevel are the supported log levels of the Server's Logger.