{"id":15019995,"url":"https://github.com/docker/go-events","last_synced_at":"2025-05-14T15:09:43.711Z","repository":{"id":57479307,"uuid":"54530647","full_name":"docker/go-events","owner":"docker","description":"Composable event distribution for Go","archived":false,"fork":false,"pushed_at":"2025-01-14T14:25:23.000Z","size":43,"stargazers_count":133,"open_issues_count":17,"forks_count":23,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-03T03:40:02.409Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-23T04:23:50.000Z","updated_at":"2025-02-28T03:01:56.000Z","dependencies_parsed_at":"2024-12-24T13:12:55.059Z","dependency_job_id":"71864902-86be-4115-a5ef-2bd035685fde","html_url":"https://github.com/docker/go-events","commit_stats":{"total_commits":17,"total_committers":9,"mean_commits":"1.8888888888888888","dds":0.6470588235294117,"last_synced_commit":"969db071c880f36e42461f6c178ead897865e9dd"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fgo-events","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fgo-events/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fgo-events/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fgo-events/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docker","download_url":"https://codeload.github.com/docker/go-events/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254050931,"owners_count":22006385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:54:26.509Z","updated_at":"2025-05-14T15:09:43.686Z","avatar_url":"https://github.com/docker.png","language":"Go","readme":"# Docker Events Package\n\n[![GoDoc](https://godoc.org/github.com/docker/go-events?status.svg)](https://godoc.org/github.com/docker/go-events)\n\nThe Docker `events` package implements a composable event distribution package\nfor Go.\n\nOriginally created to implement the [notifications in Docker Registry\n2](https://github.com/docker/distribution/blob/master/docs/notifications.md),\nwe've found the pattern to be useful in other applications. This package is\nmost of the same code with slightly updated interfaces. Much of the internals\nhave been made available.\n\n## Usage\n\nThe `events` package centers around a `Sink` type.  Events are written with\ncalls to `Sink.Write(event Event)`. Sinks can be wired up in various\nconfigurations to achieve interesting behavior.\n\nThe canonical example is that employed by the\n[docker/distribution/notifications](https://godoc.org/github.com/docker/distribution/notifications)\npackage. Let's say we have a type `httpSink` where we'd like to queue\nnotifications. As a rule, it should send a single http request and return an\nerror if it fails:\n\n```go\nfunc (h *httpSink) Write(event Event) error {\n\tp, err := json.Marshal(event)\n\tif err != nil {\n\t\treturn err\n\t}\n\tbody := bytes.NewReader(p)\n\tresp, err := h.client.Post(h.url, \"application/json\", body)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer resp.Body.Close()\n\t\n\tif resp.Status != 200 {\n\t\treturn errors.New(\"unexpected status\")\n\t}\n\n\treturn nil\n}\n\n// implement (*httpSink).Close()\n```\n\nWith just that, we can start using components from this package. One can call\n`(*httpSink).Write` to send events as the body of a post request to a\nconfigured URL.\n\n### Retries\n\nHTTP can be unreliable. The first feature we'd like is to have some retry:\n\n```go\nhs := newHTTPSink(/*...*/)\nretry := NewRetryingSink(hs, NewBreaker(5, time.Second))\n```\n\nWe now have a sink that will retry events against the `httpSink` until they\nsucceed. The retry will backoff for one second after 5 consecutive failures\nusing the breaker strategy.\n\n### Queues\n\nThis isn't quite enough. We we want a sink that doesn't block while we are\nwaiting for events to be sent. Let's add a `Queue`:\n\n```go\nqueue := NewQueue(retry)\n```\n\nNow, we have an unbounded queue that will work through all events sent with\n`(*Queue).Write`. Events can be added asynchronously to the queue without\nblocking the current execution path. This is ideal for use in an http request.\n\n### Broadcast\n\nIt usually turns out that you want to send to more than one listener. We can\nuse `Broadcaster` to support this:\n\n```go\nvar broadcast = NewBroadcaster() // make it available somewhere in your application.\nbroadcast.Add(queue) // add your queue!\nbroadcast.Add(queue2) // and another!\n```\n\nWith the above, we can now call `broadcast.Write` in our http handlers and have\nall the events distributed to each queue. Because the events are queued, not\nlistener blocks another.\n\n### Extending\n\nFor the most part, the above is sufficient for a lot of applications. However,\nextending the above functionality can be done implementing your own `Sink`. The\nbehavior and semantics of the sink can be completely dependent on the\napplication requirements. The interface is provided below for reference:\n\n```go\ntype Sink {\n\tWrite(Event) error\n\tClose() error\n}\n```\n\nApplication behavior can be controlled by how `Write` behaves. The examples\nabove are designed to queue the message and return as quickly as possible.\nOther implementations may block until the event is committed to durable\nstorage.\n\n## Copyright and license\n\nCopyright © 2016 Docker, Inc. go-events is licensed under the Apache License,\nVersion 2.0. See [LICENSE](LICENSE) for the full license text.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocker%2Fgo-events","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocker%2Fgo-events","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocker%2Fgo-events/lists"}