1# Docker Events Package
2
3[](https://godoc.org/github.com/docker/go-events)
4[](https://circleci.com/gh/docker/go-events)
5
6The Docker `events` package implements a composable event distribution package
7for Go.
8
9Originally created to implement the [notifications in Docker Registry
102](https://github.com/docker/distribution/blob/master/docs/notifications.md),
11we've found the pattern to be useful in other applications. This package is
12most of the same code with slightly updated interfaces. Much of the internals
13have been made available.
14
15## Usage
16
17The `events` package centers around a `Sink` type. Events are written with
18calls to `Sink.Write(event Event)`. Sinks can be wired up in various
19configurations to achieve interesting behavior.
20
21The canonical example is that employed by the
22[docker/distribution/notifications](https://godoc.org/github.com/docker/distribution/notifications)
23package. Let's say we have a type `httpSink` where we'd like to queue
24notifications. As a rule, it should send a single http request and return an
25error if it fails:
26
27```go
28func (h *httpSink) Write(event Event) error {
29 p, err := json.Marshal(event)
30 if err != nil {
31 return err
32 }
33 body := bytes.NewReader(p)
34 resp, err := h.client.Post(h.url, "application/json", body)
35 if err != nil {
36 return err
37 }
38 defer resp.Body.Close()
39
40 if resp.Status != 200 {
41 return errors.New("unexpected status")
42 }
43
44 return nil
45}
46
47// implement (*httpSink).Close()
48```
49
50With just that, we can start using components from this package. One can call
51`(*httpSink).Write` to send events as the body of a post request to a
52configured URL.
53
54### Retries
55
56HTTP can be unreliable. The first feature we'd like is to have some retry:
57
58```go
59hs := newHTTPSink(/*...*/)
60retry := NewRetryingSink(hs, NewBreaker(5, time.Second))
61```
62
63We now have a sink that will retry events against the `httpSink` until they
64succeed. The retry will backoff for one second after 5 consecutive failures
65using the breaker strategy.
66
67### Queues
68
69This isn't quite enough. We we want a sink that doesn't block while we are
70waiting for events to be sent. Let's add a `Queue`:
71
72```go
73queue := NewQueue(retry)
74```
75
76Now, we have an unbounded queue that will work through all events sent with
77`(*Queue).Write`. Events can be added asynchronously to the queue without
78blocking the current execution path. This is ideal for use in an http request.
79
80### Broadcast
81
82It usually turns out that you want to send to more than one listener. We can
83use `Broadcaster` to support this:
84
85```go
86var broadcast = NewBroadcaster() // make it available somewhere in your application.
87broadcast.Add(queue) // add your queue!
88broadcast.Add(queue2) // and another!
89```
90
91With the above, we can now call `broadcast.Write` in our http handlers and have
92all the events distributed to each queue. Because the events are queued, not
93listener blocks another.
94
95### Extending
96
97For the most part, the above is sufficient for a lot of applications. However,
98extending the above functionality can be done implementing your own `Sink`. The
99behavior and semantics of the sink can be completely dependent on the
100application requirements. The interface is provided below for reference:
101
102```go
103type Sink {
104 Write(Event) error
105 Close() error
106}
107```
108
109Application behavior can be controlled by how `Write` behaves. The examples
110above are designed to queue the message and return as quickly as possible.
111Other implementations may block until the event is committed to durable
112storage.
113
114## Copyright and license
115
116Copyright © 2016 Docker, Inc. go-events is licensed under the Apache License,
117Version 2.0. See [LICENSE](LICENSE) for the full license text.
View as plain text