wasm-http-server/README.md

Welcome to go-wasm-http-server 👋

Build your Go HTTP Server to WebAssembly and embed it in a ServiceWorker!

Examples

• Hello example (sources)
• Hello example with state (sources)
• Hello example with state and keepalive (sources)
• 😺 Catption generator example (sources)

Requirements

go-wasm-http-server requires you to build your Go application to WebAssembly, so you need to make sure your code is compatible:

• no C bindings
• no System dependencies such as file system or network (database server for example)

Usage

Step 1: Build to js/wasm

In your Go code, replace http.ListenAndServe() (or net.Listen() + http.Serve()) by wasmhttp.Serve():

📄 server.go

// +build !js,!wasm

package main

import (
    "net/http"
)

func main() {
    // Define handlers...

    http.ListenAndServe(":8080", nil)
}

becomes:

📄 server_js_wasm.go

// +build js,wasm

package main

import (
    wasmhttp "github.com/nlepage/go-wasm-http-server"
)

func main() {
    // Define handlers...

    wasmhttp.Serve(nil)
}

You may want to use build tags as shown above (or file name suffixes) in order to be able to build both to WebAssembly and other targets.

Then build your WebAssembly binary:

GOOS=js GOARCH=wasm go build -o server.wasm .

Step 2: Create ServiceWorker file

Create a ServiceWorker file with the following code:

📄 sw.js

importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v1.0.0/sw.js')

registerWasmHTTPListener('path/to/server.wasm')

By default the server will deploy at the ServiceWorker's scope root, check registerWasmHTTPListener()'s API for more information.

You may want to add these additional event listeners in your ServiceWorker:

// Skip installed stage and jump to activating stage
addEventListener('install', (event) => {
  event.waitUntil(skipWaiting())
})

// Start controlling clients as soon as the SW is activated
addEventListener('activate', event => {
  event.waitUntil(clients.claim())
})

Step 3: Register the ServiceWorker

In your web page(s), register the ServiceWorker:

<script>
  // By default the ServiceWorker's scope will be "server/"
  navigator.serviceWorker.register('server/sw.js')
</script>

Now your web page(s) may start fetching from the server:

// The server will receive a request for "/path/to/resource"
fetch('server/path/to/resource').then(res => {
  // use response...
})

API

Go API

See pkg.go.dev/github.com/nlepage/go-wasm-http-server

registerWasmHTTPListener(wasmUrl, options)

Instantiates and runs the WebAssembly module at wasmUrl, and registers a fetch listener forwarding requests to the WebAssembly module.

wasmUrl

URL string of the WebAssembly module, example: "path/to/my-module.wasm".

options

An optional object containing:

• base (string): Base path of the server, relative to the ServiceWorker's scope.
• args (string[]): Arguments for the WebAssembly module.

Why?

go-wasm-http-server can help you put up a demonstration for a project without actually running a Go HTTP server.

How?

If you want to know how go-wasm-http-server works, I will be presenting the project at the FOSDEM 2021 Go devroom.

The slides are available here.

Author

👤 Nicolas Lepage

• Website: https://nicolas.lepage.dev/
• Twitter: @njblepage
• Github: @nlepage

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 Nicolas Lepage.
This project is Apache 2.0 licensed.

---

This README was generated with ❤️ by readme-md-generator