/workers

Go package to run an HTTP server on Cloudflare Workers.

Primary LanguageGoMIT LicenseMIT

workers

Go Reference Discord Server

  • workers is a package to run an HTTP server written in Go on Cloudflare Workers.
  • This package can easily serve http.Handler on Cloudflare Workers.
  • Caution: This is an experimental project.

Features

  • serve http.Handler
  • R2
    • Head
    • Get
    • Put
    • Delete
    • List
    • Options for R2 methods
  • KV
    • Get
    • List
    • Put
    • Delete
    • Options for KV methods
  • Cache API
  • Durable Objects
    • Calling stubs
  • D1 (alpha)
  • Environment variables
  • FetchEvent
  • Cron Triggers
  • TCP Sockets

Installation

go get github.com/syumai/workers

Usage

implement your http.Handler and give it to workers.Serve().

func main() {
	var handler http.HandlerFunc = func (w http.ResponseWriter, req *http.Request) { ... }
	workers.Serve(handler)
}

or just call http.Handle and http.HandleFunc, then invoke workers.Serve() with nil.

func main() {
	http.HandleFunc("/hello", func (w http.ResponseWriter, req *http.Request) { ... })
	workers.Serve(nil) // if nil is given, http.DefaultServeMux is used.
}

For concrete examples, see _examples directory. Currently, all examples use tinygo instead of Go due to binary size issues.

Quick Start

First, please install the following tools:

  • Node.js (and npm)
  • wrangler
    • You can install it by running npm install -g wrangler.
  • tinygo 0.29.0 or later
  • gonew
    • You can install it by running go install golang.org/x/tools/cmd/gonew@latest

After installation, please run the following commands.

gonew github.com/syumai/workers/_templates/cloudflare/worker-tinygo your.module/my-app # e.g. github.com/syumai/my-app
cd my-app
go mod tidy
make dev # start running dev server
curl http://localhost:8787/hello # outputs "Hello!"

If you want a more detailed description, please refer to the README.md file in the generated directory.

FAQ

How do I deploy a worker implemented in this package?

To deploy a Worker, the following steps are required.

  • Create a worker project using wrangler.
  • Build a Wasm binary.
  • Upload a Wasm binary with a JavaScript code to load and instantiate Wasm (for entry point).

The worker-tinygo template contains all the required files, so I recommend using this template.

The worker-go template (using regular Go, not tinygo) is also available, but it requires a paid plan of Cloudflare Workers (due to the large binary size).

Where can I have discussions about contributions, or ask questions about how to use the library?

You can do both through GitHub Issues. If you want to have a more casual conversation, please use the Discord server.