{"id":16188966,"url":"https://github.com/fogfish/swarm","last_synced_at":"2025-08-07T22:35:01.507Z","repository":{"id":37035092,"uuid":"392366322","full_name":"fogfish/swarm","owner":"fogfish","description":"Go channels for distributed queueing and event-driven systems","archived":false,"fork":false,"pushed_at":"2024-10-07T16:30:51.000Z","size":2499,"stargazers_count":2,"open_issues_count":13,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-20T10:23:52.770Z","etag":null,"topics":["aws-dynamodb","aws-eventbridge","aws-s3","aws-sqs","aws-websockets","event-driven","event-sourcing","golang","golang-channels","serverless"],"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/fogfish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-03T15:38:30.000Z","updated_at":"2024-10-07T16:30:25.000Z","dependencies_parsed_at":"2023-01-22T20:46:18.421Z","dependency_job_id":"904f6262-4cdd-499b-afc5-712372702f94","html_url":"https://github.com/fogfish/swarm","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fswarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fswarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fswarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fswarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fogfish","download_url":"https://codeload.github.com/fogfish/swarm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243965774,"owners_count":20375917,"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":["aws-dynamodb","aws-eventbridge","aws-s3","aws-sqs","aws-websockets","event-driven","event-sourcing","golang","golang-channels","serverless"],"created_at":"2024-10-10T07:32:54.882Z","updated_at":"2025-08-07T22:35:01.497Z","avatar_url":"https://github.com/fogfish.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./doc/swarm-v3.png\" height=\"256\" /\u003e\n  \u003ch3 align=\"center\"\u003eswarm\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\u003cstrong\u003eGo channels for distributed queueing and event-driven systems\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003c!-- Build Status  --\u003e\n    \u003ca href=\"https://github.com/fogfish/swarm/actions/\"\u003e\n      \u003cimg src=\"https://github.com/fogfish/swarm/workflows/test/badge.svg\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- GitHub --\u003e\n    \u003ca href=\"http://github.com/fogfish/swarm\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/last-commit/fogfish/swarm.svg\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Coverage --\u003e\n    \u003ca href=\"https://coveralls.io/github/fogfish/swarm?branch=main\"\u003e\n      \u003cimg src=\"https://coveralls.io/repos/github/fogfish/swarm/badge.svg?branch=main\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Go Card --\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/fogfish/swarm\"\u003e\n      \u003cimg src=\"https://goreportcard.com/badge/github.com/fogfish/swarm\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Go Version --\u003e\n    \u003ca href=\"https://golang.org/dl/\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/go-1.24+-blue.svg\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003ctable align=\"center\"\u003e\n    \u003cthead\u003e\u003ctr\u003e\u003cth\u003esub-module\u003c/th\u003e\u003cth\u003edoc\u003c/th\u003e\u003cth\u003efeatures\u003c/th\u003e\u003cth\u003eabout\u003c/th\u003e\u003c/tr\u003e\u003c/thead\u003e\n    \u003ctbody\u003e\n    \u003c!-- Module swarm + kernel --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\".\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=v*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-swarm-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    API \u0026 Kernel\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/eventbridge --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/eventbridge/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/eventbridge/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/eventbridge\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-eventbridge-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/rw-9881F3?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS EventBridge \n    \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003c!-- Module broker/eventddb --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/eventddb/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/eventddb/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/eventddb\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-eventddb-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/ro-4C90F0?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS DynamoDB Stream\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/events3 --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/events3/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/events3/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/events3\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-events3-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/ro-4C90F0?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS S3 Event\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/eventsqs --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/eventsqs/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/eventsqs/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/eventsqs\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-eventsqs-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/ro-4C90F0?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS SQS Events\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/sqs --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/sqs/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/sqs/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/sqs\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-sqs-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/rw-9881F3?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS SQS and SQS FIFO\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/websocket --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003ca href=\"./broker/websocket/\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/tag/fogfish/swarm?label=version\u0026filter=broker/websocket/*\"/\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/ro-4C90F0?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS WebSocket API\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/sns --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://img.shields.io/badge/coming%20soon-00b150?style=platic\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c!-- \u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e--\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/wo-13C9BA?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS SNS\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/eventkinesis --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://img.shields.io/badge/coming%20soon-00b150?style=platic\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c!-- \u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e--\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/ro-4C90F0?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n      \u003cimg src=\"https://img.shields.io/badge/serverless-e999b8?logo=awslambda\u0026logoColor=black\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS Kinesis Events\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/kinesis --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://img.shields.io/badge/coming%20soon-00b150?style=platic\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c!-- \u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e--\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/rw-9881F3?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS Kinesis\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/elasticache --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://img.shields.io/badge/help%20needed-035392?style=platic\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c!-- \u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e--\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/rw-9881F3?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    AWS ElastiCache\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c!-- Module broker/mqtt --\u003e\n    \u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://img.shields.io/badge/help%20needed-035392?style=platic\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c!-- \u003ca href=\"https://pkg.go.dev/github.com/fogfish/swarm/broker/websocket\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/doc-websocket-007d9c?logo=go\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/a\u003e--\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/rw-9881F3?logo=amazonsqs\u0026logoColor=white\u0026style=platic\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n    MQTT\n    \u003c/td\u003e\u003c/tr\u003e\n    \u003c/tbody\u003e\n  \u003c/table\u003e\n\u003c/p\u003e\n\n---\n\n# From Chaos to Channels\n\n\u003e *\"Finally, messaging that feels like Go!\"* — Distributed systems, done right.\n\nWriting distributed, event-driven systems in Go today is harder than it should be - a lesson learned from a decade building such systems in Erlang. Vendor APIs are clunky, non-idiomatic, and tightly coupled to specific messaging brokers.\n\n`swarm` makes asynchronous, distributed messaging in Go **idiomatic, testable, and portable** by expressing queueing/event-driven systems through Go channels instead of vendor-specific APIs.\n\n[User Guide](./doc/user-guide.md) |\n[Playground](https://go.dev/play/p/B4C9fcNmWYW) |\n[Getting started](#getting-started) | \n[Examples](./broker/) |\n[Philosophy](./doc/pattern.md)\n\n\n## Quick Start\n\nThe example below shows the simplest way to enqueue and dequeue messages using AWS SQS.\n\n```go\npackage main\n\nimport (\n  \"github.com/fogfish/swarm\"\n  \"github.com/fogfish/swarm/broker/sqs\"\n  \"github.com/fogfish/swarm/emit\"\n  \"github.com/fogfish/swarm/listen\"\n)\n\n// Example message\ntype Order struct {\n  ID     string  `json:\"id\"`\n  Amount float64 `json:\"amount\"`\n}\n\nfunc main() {\n  // create broker for AWS SQS\n  q := sqs.Endpoint().Build(\"aws-sqs-queue-name\")\n\n  // create Golang channels\n  rcv, ack := listen.Typed[Order](q.Listener)\n  out := swarm.LogDeadLetters(emit.Typed[Order](q.Emitter))\n\n  // Send messages\n  out \u003c- Order{ID: \"123\", Amount: 100.0}\n\n  // use Golang channels for I/O\n  go func() {\n    for order := range rcv {\n      processOrder(order.Object)\n      ack \u003c- order  // acknowledge processing\n    }\n  }()\n\n  q.Await()\n}\n\nfunc processOrder(order Order) {\n  // Your business logic here\n}\n```\n**That's it!** You're now using distributed messaging with native Go channels.\n- Try this code in [playground](https://go.dev/play/p/B4C9fcNmWYW) \n- Continue to [Getting Started](#getting-started) for advanced configuration\n- See more examples by browsing [/broker/*/examples/](./broker/)\n- Check the design pattern [Distributed event-driven Golang channels](./doc/pattern.md) for deep-dive into library philosophy. \n\nContinue reading to understand the purpose of the library and why it exists.\n\n\u003c!--\n### How it Works\n\ntbd.\n--\u003e\n\n## What is `swarm`?\n\n`swarm` is a Go library that solves the complexity of distributed, event-driven systems by abstracting external messaging queues (like AWS SQS, AWS EventBridge, RabbitMQ, Kafka, etc.) behind **type-safe Go channels**. \n\nBy aligning with Go's native concurrency model, `swarm` encourages developers to think in terms of **message flows rather than request-response cycles**, which reflects the asynchronous and unreliable reality of distributed systems. This mindset shift leads to more resilient, scalable, and maintainable architectures — where complexity is not hidden, but made explicit and manageable.  \n\n* **Immediate Productivity**: Use Go channel patterns you already know, no need to learn new APIs.\n* **Smooth Testing**: Write unit tests with in-memory channels; switch to real systems for integration.\n* **Future-Proof**: Swap messaging technologies without changing your business logic.\n* **Serverless-Ready**: Designed for both long-running services and ephemeral serverless functions.\n* **Scale-Out**: Idiomatic architecture to build distributed topologies and scale-out Golang applications.\n\nThink of `swarm` as net.Conn **for distributed messaging**: a universal, idiomatic interface you can depend on, regardless of the underlying transport.\n\nBelow we discussed why `swarm` exists and what problems it solves.\n\n\n## Why Choose `swarm`?\n\nTraditional messaging libraries have fundamental issues\n\n| Traditional libraries         | With `swarm`                    |\n| ----------------------------- | ------------------------------- |\n| Different SDK for each broker | One API for all brokers         |\n| Complex mocks for testing     | In-memory channels for tests    |\n| Vendor lock-in                | Portable across technologies    |\n| Sync APIs for async systems   | Native async with Go channels   |\n| Manual error handling         | Built-in retries \u0026 dead letters |\n\n`swarm` solves these problems by providing a universal, idiomatic interface built on Go's concurrency model — embracing the asynchronous nature of distributed systems, making message flows explicit, and hiding vendor-specific complexity behind familiar Go channels.\n\nSee practical scenarios for `swarm` in [Storytelling](#storytelling---why-we-built-swarm).\n\n\n## Getting started\n\nThe library requires **Go 1.24** or later due to usage of [generic alias types](https://go.dev/blog/alias-names#generic-alias-types).\n\nThe latest version of the library is available at `main` branch of this repository. All development, including new features and bug fixes, take place on the `main` branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.\n\nUse `go get` to retrieve the library and add it as dependency to your application.\n\n```bash\ngo get -u github.com/fogfish/swarm\n```\n\n### When to Use `swarm`\n\n**Perfect for:**\n- **Event-driven architectures** - Decouple services with async messaging\n- **Serverless applications** - Zero-boilerplate event consumers on AWS Lambda\n- **Microservices** - Replace fragile HTTP calls with resilient messaging\n- **High-throughput systems** - Scale message processing horizontally\n- **Multi-cloud applications** - Abstract away broker differences\n\n**You'll love it if you:**\n- Want type-safe messaging without vendor lock-in\n- Need to unit test message-driven code easily  \n- Prefer Go channels over learning broker-specific APIs\n- Value clean, testable architecture patterns\n\n## Advanced Usage and Next steps\n\n* Learn [why we built `swarm`](#storytelling---why-we-built-swarm).\n* [User guide](./doc/user-guide.md) help you with adopting the library.\n* The library supports a variety of brokers out of the box. See the table at the beginning of this document for details. If you need to implement a broker that isn’t supported yet, refer to [Bring Your Own Broker](./doc/bring-your-own-broker.md) for guidance.\n\n\n## Real-World Success Stories\n\nHere's how `swarm` solves actual production problems that teams face every day.\n\n### E-commerce Order Processing: The Cascading Failure Problem\n\nImagine you're building an e-commerce platform that processes thousands of orders per minute during Black Friday sales. Your order processing system needs to:\n* Validate payment information\n* Update inventory levels\n* Send confirmation emails\n* Update analytics systems\n* Trigger fulfillment processes\n\nWhat are problems with the traditional approach:\n* Blocking Operations: Each service call blocks until completion, making the system slow during peak loads\n* Cascading Failures: If the email service is down, the entire order process fails, even though the core business logic succeeded\n* Poor Scalability: Cannot scale individual components independently\n\n```go\nfunc ProcessOrder(order *Order) error {\n  // Synchronous calls create cascading failures\n  if err := paymentService.Charge(order.Payment); err != nil {\n    return err // Customer sees error immediately\n  }\n    \n  if err := inventoryService.Reserve(order.Items); err != nil {\n    return err // Payment charged but inventory failed\n  }\n    \n  if err := emailService.SendConfirmation(order); err != nil {\n    return err // Everything fails if email is slow\n  }\n    \n  return nil\n}\n```\n\nUsing the `swarm` library, we benefit from\n* Immediate Response: Customers get instant order confirmation\n* Fault Tolerance: If email service is down, orders still process successfully\n* Independent Scaling: Each service can scale based on its own load patterns\n\n```go\nfunc ProcessOrder(order *Order) error {\n  // Immediate response to customer\n  if err := validateOrder(order); err != nil {\n    return err\n  }\n\n  // Async processing via channels\n  orderEvents \u003c- OrderCreated{Order: order}\n    \n  return nil // Customer gets immediate confirmation\n}\n\n// Background processing\ngo func() {\n  for event := range orderEvents {\n    paymentQueue \u003c- PaymentRequest{Order: event.Order}\n    inventoryQueue \u003c- InventoryUpdate{Order: event.Order}\n    emailQueue \u003c- EmailNotification{Order: event.Order}\n  }\n}()\n```\n\n### Serverless Event Processing: The SDK Complexity Problem\n\nYou're building a serverless application on AWS that needs to process events from multiple sources - SQS queues, S3 bucket notifications, EventBridge events, and DynamoDB streams. Each service has its own SDK with different patterns.\n\n```go\n// Different patterns for each service\nfunc handleSQSEvent(event events.SQSEvent) error {\n  for _, record := range event.Records {\n    // SQS-specific parsing and acknowledgment\n    body := record.Body\n    receiptHandle := record.ReceiptHandle\n    // ... SQS-specific error handling\n  }\n}\n\nfunc handleS3Event(event events.S3Event) error {\n  for _, record := range event.Records {\n    // S3-specific parsing\n    bucket := record.S3.Bucket.Name\n    key := record.S3.Object.Key\n    // ... S3-specific error handling\n  }\n}\n```\n\nUsing the `swarm` library, we benefit from\n* Unified Interface: Same code patterns work across all AWS services\n* Easy Testing: Mock implementations for local development\n* Technology Agnostic: Can switch from SQS to EventBridge without code changes\n\n```go\nevents := eventbridge.Must(eventbridge.Listener().Build())\nupload := s3.Must(s3.Listener().Build())\norders := sqs.Must(sqs.Listener().Build())\n\nlisten.Typed[UserEvent](events)\nlisten.Typed[DataUploaded](upload)\nlisten.Typed[Order](orders)\n```\n\n### Microservices Communication: The Synchronous Trap\n\nYou have a microservices architecture where the user service, notification service, and analytics service need to communicate. Traditional REST APIs create tight coupling and cascading failures.\n\n```go\n// Synchronous REST calls create brittleness\nfunc CreateUser(user *User) error {\n  // Save user\n  if err := userDB.Save(user); err != nil {\n    return err\n  }\n\n  // Synchronous calls to other services\n  if err := notificationService.SendWelcomeEmail(user); err != nil {\n    return err // User creation fails if email fails\n  }\n\n  if err := analyticsService.TrackUserCreated(user); err != nil {\n    return err // User creation fails if analytics fails\n  }\n\n  return nil\n}\n```\n\nUsing the `swarm` library, we benefit from\n* Resilient: Core functionality works even if downstream services are down\n* Scalable: Services can process at their own pace\n* Evolvable: Easy to add new services without changing existing code\n\n```go\n// Async communication via channels\nfunc CreateUser(user *User) error {\n  // Core business logic\n  if err := userDB.Save(user); err != nil {\n      return err\n  }\n\n  // Async notifications\n  userEvents \u003c- UserCreated{User: user}\n\n  return nil // Immediate success\n}\n\n// Services consume events independently\ngo func() {\n  for event := range userEvents {\n    notificationQueue \u003c- WelcomeEmail{User: event.User}\n    analyticsQueue \u003c- UserCreatedEvent{User: event.User}\n  }\n}()\n```\n\n## How To Contribute\n\nThe library is [Apache Version 2.0](LICENSE) licensed and accepts contributions via GitHub pull requests:\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\nThe build and testing process requires [Go](https://golang.org) version 1.24 or later.\n\n**build** and **test** library.\n\n```bash\ngit clone https://github.com/fogfish/swarm\ncd swarm\ngo test ./...\n```\n\n### commit message\n\nThe commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.\n\n### bugs\n\nIf you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/swarm/issues). We appreciate detailed and accurate reports that help us to identity and replicate the issue. \n\n## Community \u0026 Support\n\n- **Documentation**: [User Guide](./doc/user-guide.md) • [API Reference](https://pkg.go.dev/github.com/fogfish/swarm)\n- **Questions**: [GitHub Discussions](https://github.com/fogfish/swarm/discussions) for Q\u0026A and ideas\n- **Issues**: [GitHub Issues](https://github.com/fogfish/swarm/issues) for bug reports and feature requests\n- **Examples**: [Live examples](./broker/) for all supported brokers \n\n\n## License\n\n[![See LICENSE](https://img.shields.io/github/license/fogfish/swarm.svg?style=for-the-badge)](LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffogfish%2Fswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fswarm/lists"}