{"id":26330713,"url":"https://github.com/asyncapi/go-watermill-template","last_synced_at":"2025-04-09T17:20:17.643Z","repository":{"id":37939004,"uuid":"293630791","full_name":"asyncapi/go-watermill-template","owner":"asyncapi","description":"Go template for the AsyncAPI Generator using Watermill module","archived":false,"fork":false,"pushed_at":"2025-04-02T14:38:21.000Z","size":2155,"stargazers_count":52,"open_issues_count":2,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-09T17:20:01.216Z","etag":null,"topics":["asyncapi","generator","go","hacktoberfest","nodejs","rabbitmq","template","watermill"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/asyncapi.png","metadata":{"funding":{"github":"asyncapi","patreon":null,"open_collective":"asyncapi","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-07T20:56:24.000Z","updated_at":"2025-04-08T06:01:50.000Z","dependencies_parsed_at":"2023-12-15T22:06:46.972Z","dependency_job_id":"e4b41db8-a080-45a2-917b-b40b6bdb7e30","html_url":"https://github.com/asyncapi/go-watermill-template","commit_stats":{"total_commits":336,"total_committers":8,"mean_commits":42.0,"dds":0.03273809523809523,"last_synced_commit":"afc0ffcde0a6b9f4df9378d3bb6bf315ab4adef9"},"previous_names":["asyncapi/go-template"],"tags_count":116,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fgo-watermill-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fgo-watermill-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fgo-watermill-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fgo-watermill-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asyncapi","download_url":"https://codeload.github.com/asyncapi/go-watermill-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074922,"owners_count":21043490,"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":["asyncapi","generator","go","hacktoberfest","nodejs","rabbitmq","template","watermill"],"created_at":"2025-03-15T22:17:07.456Z","updated_at":"2025-04-09T17:20:17.622Z","avatar_url":"https://github.com/asyncapi.png","language":"JavaScript","funding_links":["https://github.com/sponsors/asyncapi","https://opencollective.com/asyncapi"],"categories":[],"sub_categories":[],"readme":"[![AsyncAPI logo](./assets/logo_banner.png)](https://www.asyncapi.com)\n\u003c!-- toc is generated with GitHub Actions do not remove toc markers --\u003e\n\n\u003c!-- toc --\u003e\n\n- [Overview](#overview)\n- [Template Output](#template-output)\n- [Technical requirements](#technical-requirements)\n- [Async API Requirements](#async-api-requirements)\n- [Supported protocols](#supported-protocols)\n- [How to use the template](#how-to-use-the-template)\n  * [CLI](#cli)\n    + [Run the following command to generate a Go module](#run-the-following-command-to-generate-a-go-module)\n    + [How to use the generated code](#how-to-use-the-generated-code)\n      - [Pre-requisites](#pre-requisites)\n      - [Running the code](#running-the-code)\n- [Template configuration](#template-configuration)\n- [Contribution guide](#contribution-guide)\n\n\u003c!-- tocstop --\u003e\n\n## Overview\n\nThis template generates a Go module that uses [watermill](https://github.com/ThreeDotsLabs/watermill) as library for building event-driven applications. The reason to choose [watermill](https://github.com/ThreeDotsLabs/watermill) is because it provides an abstraction to messaging supporting multiple protocols. This will help this generator support multiple protocols.\n\n## Template Output\n\nThe `go` code generated by this template has the following structure\n\n- __asyncapi__\n  - handlers.go -- handlers for publishers and subscribers\n  - payloads.go -- generated `go` structs using Modelina\n  - publishers.go\n  - router.go -- configures [watermill](https://watermill.io/) router, needed only for subscribers\n  - server.go -- server config\n  - subscribers.go\n- go.mod\n- go.sum\n- main.go\n\n## Technical requirements\n\n- 1.1.0 =\u003c [Generator](https://github.com/asyncapi/generator/) \u003c 2.0.0,\n- Generator specific [requirements](https://github.com/asyncapi/generator/#requirements)\n\n## Async API Requirements\n\nTo have correctly generated code, your AsyncAPI file MUST define operationId for every operation.\n\nExample:\n```\nchannels:\n  light/measured:\n    subscribe:\n      operationId: LumenPublish\n```\n\n## Supported protocols\n\n|  Protocol |  Subscriber | Publishers   |\n|---|---|---|\n|  AMQP | Yes   | Yes   |\n\n\n## How to use the template\n\nThis template must be used with the AsyncAPI Generator. You can find all available options [here](https://github.com/asyncapi/generator/).\n\n### CLI\n\nThis template has been tested to generate an AMQP subscriber for [this asyncapi.yaml file](./test/asyncapi.yaml)\n\n#### Run the following command to generate a Go module\n\n```bash\nnpm install -g @asyncapi/generator\n# clone this repository and navigate to this repository\nag test/asyncapi.yaml @asyncapi/go-watermill-template -o /path/to/generated-code -p moduleName=your-go-module-name\n```\n\nFollowing are the options that can be passed to the generator\n\n1. moduleName: name of the go module to be generated\n\n#### How to use the generated code\n\nThe above code currently generates a Go module that has a AMQP subscriber.\n\n##### Pre-requisites\nTo run the generated code the following needs to be installed\n\n1. go 1.16 +\n2. rabbitmq-server OR docker\n\n##### Running the code\n\n1. Navigate to the path where the code was generated\n2. Run the following commands to download the dependencies\n```bash\ngo mod download\ngo mod tidy\n```\n3. Currently the code does not utilize the server bindings to generate the server URI. It is currently hardcoded to point to a local instance of `rabbitmq`. It is hardcoded as `\"amqp://guest:guest@localhost:5672/\"` at `\u003cgenerated-code\u003e/config/server.go`. Change it as per your rabbitmq instance requirements\n4. Finally to execute the code run\n```bash\ngo run main.go\n```\n5. Running local instance of `rabbitmq`, navigate to it using `http://localhost:15672/` with username and password `guest`/ `guest` (These are default rabbitmq credentials).\n   FYI one can start an instance of `rabbitmq` using  `docker` as follow\n   ```\n   docker run -d -p 15672:15672 -p 5672:5672 rabbitmq:3-management\n   ```\n6. Create a queue as per the AsyncAPI spec.\n   This can be done either of the following ways\n   -  Using the UI: Refer to this [article](https://www.cloudamqp.com/blog/part3-rabbitmq-for-beginners_the-management-interface.html) that walks through the process of how this can be done in the UI / RabbitMQ Admin\n   - `cURL` request. Default rabbitmq user is `guest` and password is `guest`\n   ```\n    curl --user \u003crabbit-user\u003e:\u003crabbit-password\u003e -X PUT \\\n      http://localhost:15672/api/queues/%2f/\u003cqueue-name\u003e \\\n      -H 'cache-control: no-cache' \\\n      -H 'content-type: application/json' \\\n      -d '{\n    \"auto_delete\":false,\n    \"durable\":true\n    }'\n   ```\n7. Publish a message to the queue as per the AsyncAPI spec. This can be done either of the following ways\n   - Using the UI: Refer to this [article](https://www.cloudamqp.com/blog/part3-rabbitmq-for-beginners_the-management-interface.html) that walks through the process of how this can be done in the UI / RabbitMQ Admin\n   - `cURL` request. Default rabbitmq user is `guest` and password is `guest`\n   ```\n    curl --user \u003crabbit-user\u003e:\u003crabbit-password\u003e -X POST \\\n      http://localhost:15672/api/exchanges/%2f/amq.default/publish \\\n      -H 'cache-control: no-cache' \\\n      -H 'content-type: application/json' \\\n      -d ' {\n    \"properties\":{},\n    \"routing_key\":\"light/measured\",\n    \"payload\":\"{\\\"id\\\":1,\\\"lumens\\\":2,\\\"sentAt\\\":\\\"2021-09-21\\\"}\",\n    \"payload_encoding\":\"string\"\n    }'\n   ```\n8. Check the output at the terminal where `go run main.go` was running and the published message should be printed\n\n## Template configuration\n\nYou can configure this template by passing different parameters in the Generator CLI: `-p PARAM1_NAME=PARAM1_VALUE -p PARAM2_NAME=PARAM2_VALUE`\n\n|Name|Description|Required|Example|\n|---|---|---|---|\n|moduleName|Name for the generated Go module|false|`my-app`|\n\n## Contribution guide\n\nIf you are interested in contributing to this repo refer to the [contributing](https://github.com/asyncapi/go-watermill-template/blob/master/docs/contributing.md) docs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fgo-watermill-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasyncapi%2Fgo-watermill-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fgo-watermill-template/lists"}