{"id":31763995,"url":"https://github.com/dispatchrun/dispatch-go","last_synced_at":"2025-10-09T23:39:27.034Z","repository":{"id":247012081,"uuid":"797947891","full_name":"dispatchrun/dispatch-go","owner":"dispatchrun","description":"Go library to develop Dispatch applications.","archived":false,"fork":false,"pushed_at":"2024-07-04T04:41:48.000Z","size":301,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-07-06T05:12:48.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/dispatchrun.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":"2024-05-08T19:39:02.000Z","updated_at":"2024-07-06T05:13:05.579Z","dependencies_parsed_at":"2024-07-06T05:13:01.919Z","dependency_job_id":"e32cd80d-7810-4e01-9396-238e37a77343","html_url":"https://github.com/dispatchrun/dispatch-go","commit_stats":null,"previous_names":["dispatchrun/dispatch-go"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dispatchrun/dispatch-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dispatchrun%2Fdispatch-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dispatchrun%2Fdispatch-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dispatchrun%2Fdispatch-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dispatchrun%2Fdispatch-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dispatchrun","download_url":"https://codeload.github.com/dispatchrun/dispatch-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dispatchrun%2Fdispatch-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002311,"owners_count":26083340,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-10-09T23:39:20.692Z","updated_at":"2025-10-09T23:39:27.029Z","avatar_url":"https://github.com/dispatchrun.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/dispatchrun/.github/blob/main/profile/dispatch_logo_dark.png?raw=true\"\u003e\n    \u003cimg alt=\"dispatch logo\" src=\"https://github.com/dispatchrun/.github/blob/main/profile/dispatch_logo_light.png?raw=true\" height=\"64\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n[![Test](https://github.com/dispatchrun/dispatch-go/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/dispatchrun/dispatch-go/actions/workflows/test.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/dispatchrun/dispatch-go.svg)](https://pkg.go.dev/github.com/dispatchrun/dispatch-go)\n[![Apache 2 License](https://img.shields.io/badge/license-Apache%202-blue.svg)](LICENSE)\n[![Discord](https://img.shields.io/discord/1126309607166464131?label=Discord)](Discord)\n\nGo package to develop applications with Dispatch.\n\n[signup]: https://console.dispatch.run/\n\n- [What is Dispatch?](#what-is-dispatch)\n- [Installation](#installation)\n  - [Installing the Dispatch CLI](#installing-the-dispatch-cli)\n  - [Installing the Dispatch SDK](#installing-the-dispatch-sdk)\n- [Usage](#usage)\n  - [Writing Dispatch Applications](#writing-dispatch-applications)\n  - [Running Dispatch Applications](#running-dispatch-applications)\n  - [Writing Transactional Applications with Dispatch](#writing-transactional-applications-with-dispatch)\n  - [Integration with HTTP servers](#integration-with-http-servers)\n  - [Configuration](#configuration)\n  - [Serialization](#serialization)\n- [Examples](#examples)\n- [Contributing](#contributing)\n\n## What is Dispatch?\n\nDispatch is a cloud service for developing scalable and reliable applications in\nGo, including:\n\n- **Event-Driven Architectures**\n- **Background Jobs**\n- **Transactional Workflows**\n- **Multi-Tenant Data Pipelines**\n\nDispatch differs from alternative solutions by allowing developers to write\nsimple Go code: it has a **minimal API footprint**, which usually only\nrequires wrapping a function (no complex framework to learn), failure\nrecovery is built-in by default for transient errors like rate limits or\ntimeouts, with a **zero-configuration** model.\n\nTo get started, follow the instructions to [sign up for Dispatch][signup] 🚀.\n\n## Installation\n\n### Installing the Dispatch CLI\n\nAs a pre-requisite, we recommend installing the Dispatch CLI to simplify the\nconfiguration and execution of applications that use Dispatch. On macOS, this\ncan be done easily using [Homebrew](https://docs.brew.sh/):\n\n```console\nbrew tap dispatchrun/dispatch\nbrew install dispatch\n```\n\nAlternatively, you can download the latest `dispatch` binary from the\n[Releases](https://github.com/dispatchrun/dispatch/releases) page.\n\n_Note that this step is optional, applications that use Dispatch can run without\nthe CLI, passing configuration through environment variables or directly in the\ncode. However, the CLI automates the onboarding flow and simplifies the\nconfiguration, so we recommend starting with it._\n\n### Installing the Dispatch SDK\n\nThe Go SDK can be added as a dependency using:\n\n```console\ngo get github.com/dispatchrun/dispatch-go@latest\n```\n\nIf you're starting fresh, don't forget to run `go mod init` first (e.g. `go mod init dispatch-example`).\n\n## Usage\n\n### Writing Dispatch Applications\n\nThe following snippet shows how to write a simple Dispatch application\nthat does the following:\n\n1. declare a Dispatch function named `greet` which can run asynchronously\n1. start a Dispatch endpoint to handle function calls\n1. schedule a call to `greet` with the argument `World`\n\n```go\n# main.go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"github.com/dispatchrun/dispatch-go\"\n)\n\nfunc main() {\n    greet := dispatch.Func(\"greet\", func(ctx context.Context, msg string) (any, error) {\n        fmt.Printf(\"Hello, %s!\\n\", msg)\n        return nil, nil\n    })\n\n    endpoint, err := dispatch.New(greet)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    go func() {\n        if _, err := greet.Dispatch(context.Background(), \"World\"); err != nil {\n            log.Fatal(err)\n        }\n    }()\n\n    if err := endpoint.ListenAndServe(); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\nObviously, this is just an example, a real application would perform much more\ninteresting work, but it's a good start to get a sense of how to use Dispatch.\n\n### Running Dispatch Applications\n\nThe simplest way to run a Dispatch application is to use the Dispatch CLI, first\nwe need to login:\n\n```console\ndispatch login\n```\n\nThen we are ready to run the example program we wrote above:\n\n```console\ndispatch run -- go run main.go\n```\n\n### Writing Transactional Applications with Dispatch\n\nDispatch functions are _coroutines_ that can be suspended and resumed at _await_\npoints. The await points are durability checkpoints; if a function fails midway\nthrough execution, it can be retried automatically from these checkpoints.\n\n```go\npipeline := dispatch.Func(\"pipeline\", func (ctx context.Context, msg string) (string, error) {\n    // Each await point is a durability step, the functions can be run across the\n    // fleet of service instances and retried as needed without losing track of\n    // progress through the function execution.\n    msg, _ = transform1.Await(ctx, msg)\n    msg, _ = transform2.Await(ctx, msg)\n    return publish.Await(ctx, msg)\n})\n\npublish := dispatch.Func(\"publish\", func (ctx context.Context, msg string) (*dispatchhttp.Response, error) {\n    // Each dispatch function runs concurrently to the others, even if it does\n    // blocking operations like this POST request, it does not prevent other\n    // concurrent operations from carrying on in the program.\n    return dispatchhttp.Post(\"https://somewhere.com/\", bytes.NewBufferString(msg))\n})\n\ntransform1 := dispatch.Func(\"transform1\", func (ctx context.Context, msg string) (string, error) {\n    // ...\n})\n\ntransform2 := dispatch.Func(\"transform2\", func (ctx context.Context, msg string) (string, error) {\n    // ...\n})\n```\n\nThis model is composable and can be used to create fan-out/fan-in control flows.\n`gather` can be used to wait on multiple concurrent calls:\n\n```go\nprocess := dispatch.Func(\"process\", func (ctx context.Context, msgs []string) ([]string, error) {\n    // Transform messages concurrently and await the results.\n    return transform.Gather(ctx, msgs)\n})\n\ntransform := dispatch.Func(\"transform\", func (ctx context.Context, msg string) (string, error) {\n    // ...\n})\n```\n\nDispatch converts Go functions into _Distributed Coroutines_, which can be\nsuspended and resumed on any instance of a service across a fleet. For a deep\ndive on these concepts, read our\n[_Distributed Coroutines_](https://dispatch.run/blog/distributed-coroutines-in-python)\nblog post.\n\n### Integration with HTTP servers\n\nDispatch can be integrated into an existing HTTP server.\n\nIn the example below, a request to `/` triggers an asynchronous call to the `greet`\nfunction:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"net/http\"\n\n    \"github.com/dispatchrun/dispatch-go\"\n)\n\nfunc main() {\n    greet := dispatch.Func(\"greet\", func(ctx context.Context, msg string) (any, error) {\n        fmt.Printf(\"Hello, %s!\\n\", msg)\n        return nil, nil\n    })\n\n    endpoint, err := dispatch.New(greet)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    mux := http.NewServeMux()\n\n    mux.Handle(endpoint.Handler())\n\n    mux.Handle(\"/\", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        greet.Dispatch(r.Context(), \"World\")\n        w.WriteHeader(http.StatusOK)\n    }))\n\n    if err := http.ListenAndServe(\"localhost:8000\", mux); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n### Configuration\n\nThe Dispatch CLI automatically configures the SDK, so manual configuration is\nusually not required when running Dispatch applications. However, in some\nadvanced cases, it might be useful to explicitly set configuration options.\n\nIn order for Dispatch to interact with functions remotely, the SDK needs to be\nconfigured with the address at which the server can be reached. The Dispatch\nAPI Key must also be set, and optionally, a public signing key should be\nconfigured to verify that requests originated from Dispatch. These\nconfiguration options can be passed as arguments to the\nthe `Dispatch` constructor, but by default they will be loaded from environment\nvariables:\n\n| Environment Variable        | Value Example                      |\n| :-------------------------- | :--------------------------------- |\n| `DISPATCH_API_KEY`          | `d4caSl21a5wdx5AxMjdaMeWehaIyXVnN` |\n| `DISPATCH_ENDPOINT_URL`     | `https://service.domain.com`       |\n| `DISPATCH_VERIFICATION_KEY` | `-----BEGIN PUBLIC KEY-----...`    |\n\n### Serialization\n\n#### Inputs \u0026 Outputs\n\nDispatch uses protobuf to serialize input and output values.\n\nThe inputs and outputs must either be primitive values, list or maps\nof primitive values, or have a type that implements one of the\nfollowing interfaces:\n- `encoding.TextMarshaler`\n- `encoding.BinaryMarshaler`\n- `json.Marshaler`\n- `proto.Message`\n\n#### Coroutine State\n\nDispatch uses the [coroutine] library to serialize coroutines.\n\n[coroutine]: https://github.com/dispatchrun/coroutine\n\nThe user must ensure that the contents of their stack frames are\nserializable.\n\nFor help with a serialization issues, please submit a [GitHub issue][issues].\n\n[issues]: https://github.com/dispatchrun/dispatch-go/issues\n\n## Examples\n\nCheck out the [examples](examples/) directory for code samples to help you get\nstarted with the SDK.\n\n## Contributing\n\nContributions are always welcome! Would you spot a typo or anything that needs\nto be improved, feel free to send a pull request.\n\nPull requests need to pass all CI checks before getting merged. Anything that\nisn't a straightforward change would benefit from being discussed in an issue\nbefore submitting a change.\n\nRemember to be respectful and open minded!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdispatchrun%2Fdispatch-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdispatchrun%2Fdispatch-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdispatchrun%2Fdispatch-go/lists"}