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

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 Getenv(name string) string
• func Serve(handler http.Handler)
• type KVNamespace
  • func NewKVNamespace(varName string) (*KVNamespace, error)
  • func (kv *KVNamespace) Delete(key string) error
  • func (kv *KVNamespace) GetReader(key string, opts *KVNamespaceGetOptions) (io.Reader, error)
  • func (kv *KVNamespace) GetString(key string, opts *KVNamespaceGetOptions) (string, error)
  • func (kv *KVNamespace) List(opts *KVNamespaceListOptions) (*KVNamespaceListResult, error)
  • func (kv *KVNamespace) PutReader(key string, value io.Reader, opts *KVNamespacePutOptions) error
  • func (kv *KVNamespace) PutString(key string, value string, opts *KVNamespacePutOptions) error
• type KVNamespaceGetOptions
• type KVNamespaceListKey
• type KVNamespaceListOptions
• type KVNamespaceListResult
• type KVNamespacePutOptions
• type R2Bucket
  • func NewR2Bucket(varName string) (*R2Bucket, error)
  • func (r *R2Bucket) Delete(key string) error
  • func (r *R2Bucket) Get(key string) (*R2Object, error)
  • func (r *R2Bucket) Head(key string) (*R2Object, error)
  • func (r *R2Bucket) List() (*R2Objects, error)
  • func (r *R2Bucket) Put(key string, value io.ReadCloser, opts *R2PutOptions) (*R2Object, error)
• type R2HTTPMetadata
• type R2Object
  • func (o *R2Object) BodyUsed() (bool, error)
• type R2Objects
• type R2PutOptions

Functions

func Getenv

func Getenv(name string) string

Getenv gets a value of an environment variable.

• https://developers.cloudflare.com/workers/platform/environment-variables/
• Technically, this function is just an alias for js.Global().Get(env_name).String().

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 struct {
	// contains filtered or unexported fields
}

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.

func (*KVNamespace) Delete

func (kv *KVNamespace) Delete(key string) error

Delete deletes key-value pair specified by the key.

• if a network error happens, returns error.

func (*KVNamespace) GetReader

func (kv *KVNamespace) GetReader(key string, opts *KVNamespaceGetOptions) (io.Reader, error)

GetReader gets stream value by the specified key.

• if a network error happens, returns error.

func (*KVNamespace) GetString

func (kv *KVNamespace) GetString(key string, opts *KVNamespaceGetOptions) (string, error)

GetString gets string value by the specified key.

• if a network error happens, returns error.

func (*KVNamespace) List

func (kv *KVNamespace) List(opts *KVNamespaceListOptions) (*KVNamespaceListResult, error)

List lists keys stored into the KV namespace.

func (*KVNamespace) PutReader

func (kv *KVNamespace) PutReader(key string, value io.Reader, opts *KVNamespacePutOptions) error

PutReader puts stream value into KV with key.

• This method copies all bytes into memory for implementation restriction.
• if a network error happens, returns error.

func (*KVNamespace) PutString

func (kv *KVNamespace) PutString(key string, value string, opts *KVNamespacePutOptions) error

PutString puts string value into KV with key.

• if a network error happens, 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 struct {
	// contains filtered or unexported fields
}

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.

func (*R2Bucket) Delete

func (r *R2Bucket) Delete(key string) error

Delete returns the result of `delete` call to R2Bucket.

• if a network error happens, returns error.

func (*R2Bucket) Get

func (r *R2Bucket) Get(key string) (*R2Object, error)

Get returns the result of `get` call to R2Bucket.

• if the object for given key doesn't exist, returns nil.
• if a network error happens, returns error.

func (*R2Bucket) Head

func (r *R2Bucket) Head(key string) (*R2Object, error)

Head returns the result of `head` call to R2Bucket.

• Body field of *R2Object is always nil for Head call.
• if the object for given key doesn't exist, returns nil.
• if a network error happens, returns error.

func (*R2Bucket) List

func (r *R2Bucket) List() (*R2Objects, error)

List returns the result of `list` call to R2Bucket.

• if a network error happens, returns error.

func (*R2Bucket) Put

func (r *R2Bucket) Put(key string, value io.ReadCloser, opts *R2PutOptions) (*R2Object, error)

Put returns the result of `put` call to R2Bucket.

• This method copies all bytes into memory for implementation restriction.
• Body field of *R2Object is always nil for Put call.
• if a network error happens, 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