netdev

netdev — host Netdever for TinyGo

TinyGo’s net / net/http packages do not talk to the OS directly. They call a Netdever registered with UseNetdev. On microcontrollers that is usually Wi-Fi firmware (WiFiNINA, etc.). On a desktop host there is no default driver, which produces:

Netdev not set

This package implements a Netdever on Linux / macOS / Windows using the host TCP/IP stack, compatible with the interface in tinygo-org/drivers/netdev.

Usage

Blank-import the package before any net / net/http use (init registers the driver under TinyGo):

package main

import (
	"net/http"

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

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("ok"))
	})
	http.ListenAndServe(":8080", nil)
}

Or register explicitly:

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

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

Build

With TinyGo:

tinygo build -o server ./examples/httpserver
./server

Standard go build / go run also work: the driver is a no-op registrar because the stock net package does not use netdev.

go run ./examples/httpserver

Notes

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

• Unix domain sockets (unix, unixgram, unixpacket) are not supported and will not be. TinyGo’s net rejects those networks before a driver is consulted, and the Netdever interface addresses sockets as netip.AddrPort, which cannot carry a filesystem path. Use tcp4 on 127.0.0.1 for local IPC.

• Listening on port 0 works, but net.Listener.Addr() still reports port 0. The Netdever Bind signature returns only an error, so the port the OS picked cannot be handed back to TinyGo’s net. Read it from the driver instead:

  d := netdev.New()
  netdev.Use(d)
  fd, _ := d.Socket(netdev.AF_INET, netdev.SOCK_STREAM, netdev.IPPROTO_TCP)
  d.Bind(fd, netip.MustParseAddrPort("127.0.0.1:0"))
  laddr, _ := d.LocalAddr(fd) // 127.0.0.1:54321
  

  A full fix needs an upstream change in TinyGo’s listenTCP.

• Socket errors are reported as the shared classes in netdev.Err* (ErrConnRefused, ErrAddrNotAvailable, …), so errors.Is works the same on Linux, macOS, and Windows.

• IPPROTO_TLS uses Secure Transport on macOS, so a binary needs no Homebrew and no OpenSSL. Peer certificates and hostnames are verified against the system keychain; set SSL_CERT_FILE to add a private CA, which is read in Go and passed in as an extra anchor.

  Secure Transport is the only OS-provided option that fits this seam: it hands over an already connected descriptor, and an nw_connection owns DNS, TCP and TLS as one unit and cannot adopt one. The cost is that Secure Transport stops at TLS 1.2; the previous OpenSSL implementation negotiated 1.3.

• Windows has two socket backends. Host Go uses a pure-Go one built on syscall plus a few ws2_32 entry points, so go build needs no C compiler; that matters because the blank import is a no-op under host Go and used to break builds that never touched this package. TinyGo has no windows syscall package, so it keeps the cgo backend and still needs mingw-w64.

• IPPROTO_TLS uses Schannel on Windows, reached through SSPI. It ships with the OS, so there is nothing to install here either, and it reaches TLS 1.3 where the OS supports it. Peer certificates and hostnames are verified against the Windows certificate store; SSL_CERT_FILE adds a private CA the same way it does on macOS.

  TLS is the one part that does need cgo. A cgo-free host-Go build keeps full socket support and returns ErrProtocolNotSupported for IPPROTO_TLS.

• Standard Go Linux builds can exercise the same OpenSSL adapter. TinyGo Linux cannot safely call the distribution's shared OpenSSL because it bypasses glibc process initialization, so TinyGo Linux currently returns ErrProtocolNotSupported for IPPROTO_TLS.

• OpenSSL 3 is a build and runtime dependency on host-Go Linux only (libssl-dev on Debian/Ubuntu). macOS and TinyGo Linux need neither it nor a package manager.

• DNS uses /etc/hosts (or the Windows hosts file) plus a simple UDP A-record resolver. Nameservers come from /etc/resolv.conf, falling back to 8.8.8.8 when none is found.

• Name resolution asks the OS first, so the DNS suffix search list and any domain-scoped resolvers a VPN installs both apply. The lookup order is: localhost, the hosts file, NETDEV_DNS, the system resolver, then the built-in UDP query.

  Build	System resolver
  host Go, any OS	net.LookupHost
  Windows, cgo (incl. TinyGo)	getaddrinfo via ws2_32
  TinyGo on macOS and Linux	none, falls through to the UDP query

  TinyGo cannot reach a system resolver on macOS or Linux, and this is a linker limitation rather than a choice: getaddrinfo is absent from TinyGo's macos-minimal-sdk libSystem stubs, and TinyGo's Linux linker does not expose the libc socket stubs either — which is why sys_linux.go issues raw syscalls instead of calling libc. A link failure cannot be recovered from at run time, so attempting it would break builds that currently work. On those two builds an unqualified short name will not resolve; use NETDEV_DNS or the hosts file.

• NETDEV_DNS overrides which resolvers are used, on every platform:

  NETDEV_DNS=10.0.0.53
  NETDEV_DNS=10.0.0.53,10.0.0.54:5353   # comma or space separated, :port optional
  

  It replaces the discovered list outright rather than being appended to it, so a resolver that cannot answer internal names is not tried first. Unparseable and non-IPv4 entries are skipped rather than failing the lookup.

  This exists because what the package can discover is not always what the machine actually uses:

  • Windows has no /etc/resolv.conf at all, so without an override every lookup goes to 8.8.8.8 and no internal or split-horizon name can ever resolve.
  • macOS /etc/resolv.conf is a legacy file the OS documents as not consulted — it says so in its own header, and directs you to scutil --dns. It happens to carry the right servers on a simple network, but it does not represent the domain-scoped resolvers a VPN installs.
  • Linux reads the real thing and is generally correct.

  Two further limits apply everywhere: search and domain lines are ignored, so an unqualified short name will not resolve, and a resolver list with only IPv6 entries is treated as empty because this package is IPv4-only.

  The hosts file is read before any resolver, so an entry in /etc/hosts or %SystemRoot%\System32\drivers\etc\hosts also works.

• Multiple goroutines may call socket methods concurrently; the driver serializes bookkeeping and relies on OS sockets for I/O.