workers

README

workers

• 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
• environment variables (WIP)

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.

A template repository is also available.

• https://github.com/syumai/worker-template-tinygo

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-template-tinygo repository contains all the required files, so I recommend using this template.

License

MIT

Author

syumai

Documentation

Index

• func Serve(handler http.Handler)
• type KVNamespace
  • func NewKVNamespace(varName string) (KVNamespace, error)
• type KVNamespaceGetOptions
• type KVNamespaceListKey
• type KVNamespaceListOptions
• type KVNamespaceListResult
• type KVNamespacePutOptions
• type R2Bucket
  • func NewR2Bucket(varName string) (R2Bucket, error)
• type R2HTTPMetadata
• type R2Object
  • func (o *R2Object) BodyUsed() (bool, error)
• type R2Objects
• type R2PutOptions

Functions

func Serve

func Serve(handler http.Handler)

Server serves http.Handler on Cloudflare Workers. if the given handler is nil, http.DefaultServeMux will be used.

Types

type KVNamespace

type KVNamespace interface {
	GetString(key string, opts *KVNamespaceGetOptions) (string, error)
	GetReader(key string, opts *KVNamespaceGetOptions) (io.Reader, error)
	List(opts *KVNamespaceListOptions) (*KVNamespaceListResult, error)
	PutString(key string, value string, opts *KVNamespacePutOptions) error
	PutReader(key string, value io.Reader, opts *KVNamespacePutOptions) error
	Delete(key string) error
}

KVNamespace represents interface of Cloudflare Worker's KV namespace instance. - https://developers.cloudflare.com/workers/runtime-apis/kv/ - https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L850

func NewKVNamespace

func NewKVNamespace(varName string) (KVNamespace, error)

NewKVNamespace returns KVNamespace for given variable name. * variable name must be defined in wrangler.toml as kv_namespace's binding. * if the given variable name doesn't exist on global object, returns error.

type KVNamespaceGetOptions

type KVNamespaceGetOptions struct {
	CacheTTL int
}

KVNamespaceGetOptions represents Cloudflare KV namespace get options. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L930

type KVNamespaceListKey

type KVNamespaceListKey struct {
	Name string
	// Expiration is an expiration of KV value cache. The value `0` means no expiration.
	Expiration int
}

KVNamespaceListKey represents Cloudflare KV namespace list key. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L940

type KVNamespaceListOptions

type KVNamespaceListOptions struct {
	Limit  int
	Prefix string
	Cursor string
}

KVNamespaceListOptions represents Cloudflare KV namespace list options. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L946

type KVNamespaceListResult

type KVNamespaceListResult struct {
	Keys         []*KVNamespaceListKey
	ListComplete bool
	Cursor       string
}

KVNamespaceListResult represents Cloudflare KV namespace list result. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L952

type KVNamespacePutOptions

type KVNamespacePutOptions struct {
	Expiration    int
	ExpirationTTL int
}

KVNamespacePutOptions represents Cloudflare KV namespace put options. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L958

type R2Bucket

type R2Bucket interface {
	Head(key string) (*R2Object, error)
	Get(key string) (*R2Object, error)
	Put(key string, value io.ReadCloser, opts *R2PutOptions) (*R2Object, error)
	Delete(key string) error
	List() (*R2Objects, error)
}

R2Bucket represents interface of Cloudflare Worker's R2 Bucket instance. - https://developers.cloudflare.com/r2/runtime-apis/#bucket-method-definitions - https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L1006

func NewR2Bucket

func NewR2Bucket(varName string) (R2Bucket, error)

NewR2Bucket returns R2Bucket for given variable name. * variable name must be defined in wrangler.toml.

• see example: https://github.com/syumai/workers/tree/main/examples/r2-image-viewer

* if the given variable name doesn't exist on global object, returns error.

type R2HTTPMetadata

type R2HTTPMetadata struct {
	ContentType        string
	ContentLanguage    string
	ContentDisposition string
	ContentEncoding    string
	CacheControl       string
	CacheExpiry        time.Time
}

R2HTTPMetadata represents metadata of R2Object. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L1053

type R2Object

type R2Object struct {
	Key            string
	Version        string
	Size           int
	ETag           string
	HTTPETag       string
	Uploaded       time.Time
	HTTPMetadata   R2HTTPMetadata
	CustomMetadata map[string]string
	// Body is a body of R2Object.
	// This value is nil for the result of the `Head` or `Put` method.
	Body io.Reader
	// contains filtered or unexported fields
}

R2Object represents Cloudflare R2 object. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L1094

func (*R2Object) BodyUsed

func (o *R2Object) BodyUsed() (bool, error)

type R2Objects

type R2Objects struct {
	Objects   []*R2Object
	Truncated bool
	// Cursor indicates next cursor of R2Objects.
	// * This becomes empty string if cursor doesn't exist.
	Cursor            string
	DelimitedPrefixes []string
}

R2Objects represents Cloudflare R2 objects. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L1121

type R2PutOptions

type R2PutOptions struct {
	HTTPMetadata   R2HTTPMetadata
	CustomMetadata map[string]string
	MD5            string
}

R2PutOptions represents Cloudflare R2 put options. * https://github.com/cloudflare/workers-types/blob/3012f263fb1239825e5f0061b267c8650d01b717/index.d.ts#L1128