Skip to content

Commit

Permalink
Make documentation corrections
Browse files Browse the repository at this point in the history
  • Loading branch information
tmaxmax committed Jan 30, 2024
1 parent 4fe653c commit e883c7e
Show file tree
Hide file tree
Showing 4 changed files with 14 additions and 21 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
19 changes: 8 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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...
}

Expand Down Expand Up @@ -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"

Expand All @@ -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)
}
}
```
Expand Down
2 changes: 1 addition & 1 deletion client_connection.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//
Expand Down
12 changes: 4 additions & 8 deletions server.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand All @@ -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 {
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit e883c7e

Please sign in to comment.