tinygodriver

tinygodriver

Networking additions that make TinyGo's standard-library HTTP stack more useful on desktop hosts.

The repository provides a host network driver plus TinyGo-compatible versions of newer HTTP APIs that are not yet fully available in TinyGo. The packages also build with standard Go, which makes it possible to share application code and tests between both compilers.

Packages

Quick start

Blank-import netdev before using net or net/http on a desktop TinyGo build. Use httpmux when the application needs method-aware patterns or path wildcards:

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/shibukawa/tinygodriver/httpmux"
	_ "github.com/shibukawa/tinygodriver/netdev"
)

func main() {
	mux := httpmux.NewServeMux()
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "user=%s\n", r.PathValue("id"))
	})
	addr := os.Getenv("ADDR")
	if addr == "" {
		addr = ":8080"
	}
	fmt.Println("listening on", addr)
	http.ListenAndServe(addr, mux)
}

Run the example

The included server exercises netdev, httpmux, and httprevproxy together. Its /proxy/{path...} route forwards requests to UPSTREAM_URL (default http://127.0.0.1:8081).

tinygo build -o server ./examples/httpserver
./server
# curl http://127.0.0.1:8080/healthz
# curl http://127.0.0.1:8080/proxy/users/42

Standard go run also works. In a standard Go build, netdev registration is a no-op and httpmux.ServeMux is an alias of net/http.ServeMux.

go run ./examples/httpserver

Explicit netdev registration

import "github.com/shibukawa/tinygodriver/netdev"

func main() {
	netdev.Use(netdev.New())
	// ...
}

Examples

Platform notes

See the package READMEs for detailed API behavior and limitations:

• netdev: TLS, DNS, and platform notes

• https: HTTPS client backends, configuration, and limitations

• httpmux: supported patterns and implementation selection

• httpserver: why Hijack deadlocks, what the demultiplexer does, and when the package stops being needed

• websocket: the two patch sites, reaching wss://, and what is verified

• httprevproxy: proxy features and unsupported protocols

• fasthttp: build tags, why TLS and HTTP/2 cannot work, and how dropping zstd halves the binary

• fasthttprouter: why the router needs a fork of its own, and what it costs

• fasthttpwebsocket: why FastHTTPUpgrader works on TinyGo where net/http's Hijack deadlocks

• storage/s3: supported operations, configuration, and limitations

• nosql/dynamodb: attribute values, pagination, retries and what a retry can deliver twice

• nosql/datastore: values, keys, queries, conditional writes and contention

• cloud/aws: signing another AWS service with this signer

• cloud/google: token sources, clock skew, and where the RSA code goes

• IPv4 only (matches TinyGo’s net port).

• HTTPS client (https): Network.framework on macOS, Schannel on Windows, and vendored mbedTLS on Linux, all with no external TLS library to install. Other TinyGo targets return ErrPlatformNotSupported; standard Go builds delegate to net/http.

• netdev TLS (IPPROTO_TLS): Secure Transport on macOS, Schannel on Windows and crypto/tls on host-Go Linux, none of which needs a package manager. TinyGo on Linux returns ErrProtocolNotSupported. The https package needs none of this.

• A TinyGo net/http server cannot hijack a connection. It starts a background read before every handler and cancels it by moving the read deadline into the past, which netdev cannot do to a recv() already in flight, so Hijack never returns and a protocol upgrade hangs silently. Serve through httpserver, which routes upgrades around net/http and keeps a real http.Server for everything else, on one port.

• websocket serves plaintext only. Its client reaches wss:// through Dialer.NetDialTLSContext; a server cannot terminate TLS, for the same reason fasthttp cannot.

• fasthttp serves plaintext only. TinyGo defines no tls.Server, so terminating TLS is impossible and the fork refuses rather than serving cleartext on the TLS port; HTTP/2 cannot work either, because ALPN is unobservable. Its client reaches HTTPS through a custom Dial.

• On the fasthttp stack, WebSocket needs no demultiplexer. RequestCtx.Hijack is a synchronous handoff — response written, reading stopped, handler called on the same goroutine — so the deadlock above never arises and fasthttpwebsocket upgrades from an ordinary route. Two routes to the same place: websocket + httpserver for net/http applications, fasthttpwebsocket for fasthttp ones.

Install

Install only the packages an application uses, for example:

go get github.com/shibukawa/tinygodriver/netdev@latest
go get github.com/shibukawa/tinygodriver/httpmux@latest
go get github.com/shibukawa/tinygodriver/httprevproxy@latest
go get github.com/shibukawa/tinygodriver/storage/s3@latest
go get github.com/shibukawa/tinygodriver/nosql/dynamodb@latest

Requires Go 1.27 or later, which is the module's go directive, and TinyGo 0.42 or later for TinyGo builds. TinyGo 0.41 refuses a Go 1.27 toolchain outright — requires go version 1.19 through 1.26 — so the two floors move together. Compatible with the Netdever interface in tinygo-org/drivers/netdev.

License

Apache License 2.0