README: update documentation

Signed-off-by: Achille Roussel <[email protected]>

Author: achille-roussel

README.md

@@ -1,91 +1,102 @@
 # net
 
-This library provides `net.Dial` and `net.Listen` functions
-for `GOOS=wasip1`
+This library provides `net.Dial` and `net.Listen` functions for
+[`GOOS=wasip1`][wasip1].
 
-Applications built with this library are compatible with WasmEdge
-and [stealthrocket/wasi-go](https://github.com/stealthrocket/wasi-go).
+Applications built with this library are compatible with [WasmEdge][wasmedge]
+and [stealthrocket/wasi-go][wasi-go].
 
-## Dialing
+[wasi-go]: https://github.com/stealthrocket/wasi-go
+[wasip1]: https://tip.golang.org/doc/go1.21#wasip1
+[wasmedge]: https://github.com/WasmEdge/WasmEdge
 
-The library will automatically configure the default HTTP transport
-to use the `Dial` function from this library.
+## Motivation
 
-To make outbound HTTP connections you just need the following import somewhere:
+The WASI preview 1 specification has partial support for socket networking,
+preventing a large class of Go applications from running when compiled to
+WebAssembly with `GOOS=wasip1`. Extensions to the base specifications have been
+implemented by runtimes to enable a wider range of programs to be run as
+WebAssembly modules.
 
-```go
-import _ "github.com/stealthrocket/net"
-```
+This package aims to offset Go applications built with `GOOS=wasip1` the
+opportunity to leverage those WASI extensions, by providing high level functions
+similar to those found in the standard `net` package to create network clients
+and servers.
 
-To connect to databases, there's usually a way to pass in a custom `Dial`
-function.
+## Configuration
 
-For example, to connect to MySQL:
+Where possible, the package offers the ability to automatically configure the
+network stack via `init` functions called on package imports. This model is
+currently supported for `http` and `mysql` with those imports:
 
 ```go
-import (
-    "context"
+import _ "github.com/stealthrocket/net/http"
+```
+```go
+import _ "github.com/stealthrocket/net/mysql"
+```
 
-    "github.com/go-sql-driver/mysql"
-    "github.com/stealthrocket/net"
-)
+When imported, those packages alter the default configuration to install a
+dialer function implemented on top of the WASI socket extensions. When compiled
+to other targets, the import of those packages does nothing.
 
-func init() {
-    for _, network := range []string{"tcp", "tcp4", "tcp6"} {
-        mysql.RegisterDialContext(network, func(ctx context.Context, addr string) (net.Conn, error) {
-            return net.Dial(network, addr)
-        })
-    }
-}
+## Dialing
 
-func main() {
-    db, err := sql.Open("mysql", "root:@tcp(127.0.0.1:3306)/database")
-}
-```
+Packages implementing network clients for various protocols usually support
+configuration through the installation of an alternative dial function allowing
+the application to customize how network connections are established.
 
-and to connect to Redis:
+The `wasip1` sub-package provides dial functions matching the signature of those
+implemented in the standard `net` package to integrate with those configuration
+mechanisms.
 
-```go
-import (
-    "github.com/redis/go-redis/v9"
-    "github.com/stealthrocket/net"
-)
+The sub-modules contain examples of how to configure popular Go libraries to
+leverage the dial functions of `wasip1`. Here is an example for a Redis client:
 
-func main() {
-    db := redis.NewClient(&redis.Options{
-        Addr:   "127.0.0.1:6379",
-        Dialer: net.DialContext,
-    })
-}
+```go
+client := redis.NewClient(&redis.Options{
+	Addr:   "localhost:6379",
+	Dialer: wasip1.DialContext, // change the dial function to use socket extensions
+})
 ```
 
 ## Listening
 
-HTTP servers can be created like so:
+Network servers can be created using the `wasip1.Listen` function, which mimics
+the signature of `net.Listen` but uses WASI socket extensiosn to create the
+`net.Listener`.
+
+For example, a program compiled to `GOOS=wasip1` can create a http server by
+first constructing a listener and passing it to the server's `Serve` method:
 
 ```go
 import (
     "net/http"
 
-    "github.com/stealthrocket/net"
+    "github.com/stealthrocket/net/wasip1"
 )
 
 func main() {
-    listener, err := net.Listen("tcp", "127.0.0.1:8080")
+    listener, err := wasip1.Listen("tcp", "127.0.0.1:3000")
     if err != nil {
-        // TODO: handle listen error
+        ...
     }
     server := &http.Server{
-        // TODO: setup HTTP server
+        ...
+    }
+    if err := server.Serve(listener); err != nil {
+        ...
     }
-    err = server.Serve(listener)
 }
 ```
 
+Note that using convenience functions like `http.ListenAndServe` will not
+work since they are hardcoded to depend on the standard `net` package.
+
 ## Name Resolution
 
-There are two methods available for resolving a set of IP addresses
-for a hostname.
+There are two methods available for resolving a set of IP addresses for a
+hostname.
 
 ### getaddrinfo
 
@@ -98,6 +109,8 @@ implementation.
 
 Note that `sock_getaddrinfo` may block.
 
+At this time, this is this package defaults to using this approach.
+
 ### Pure Go Resolver
 
 The pure Go name resolver is not currently enabled for GOOS=wasip1.
@@ -113,7 +126,7 @@ The library will then automatically configure the `net.DefaultResolver`.
 All you need is the following import somewhere in your application:
 
 ```go
-import _ "github.com/stealthrocket/net"
+import _ "github.com/stealthrocket/net/wasip1"
 ```
 
 You should then be able to use the lookup functions from the standard

wasip1/lookup_wasip1.go

@@ -3,10 +3,29 @@
 package wasip1
 
 import (
+	"context"
+	"errors"
 	"net"
 	"os"
 )
 
+func dialResolverNotSupported(ctx context.Context, network, address string) (net.Conn, error) {
+	// The net.Resolver type makes a call to net.DialUDP to determine which
+	// resolved addresses are reachable, which does not go through its Dial
+	// hook. As a result, it is unusable on GOOS=wasip1 because it fails
+	// even when the Dial function is set because WASI preview 1 does not
+	// have a mechanism for opening UDP sockets.
+	//
+	// Instead of having (often indirect) use of the net.Resolver crash, we
+	// override the Dial function to error earlier in the resolver lifecycle
+	// with an error which is more explicit to the end user.
+	return nil, errors.New("net.Resolver not supported on GOOS=wasip1")
+}
+
+func init() {
+	net.DefaultResolver.Dial = dialResolverNotSupported
+}
+
 func lookupAddr(op, network, address string) (net.Addr, error) {
 	var hints addrInfo
 	switch network {

wasip1/net_wasip1.go

@@ -3,31 +3,12 @@
 package wasip1
 
 import (
-	"context"
-	"errors"
 	"fmt"
 	"net"
 	"os"
 	"syscall"
 )
 
-func dialResolverNotSupported(ctx context.Context, network, address string) (net.Conn, error) {
-	// The net.Resolver type makes a call to net.DialUDP to determine which
-	// resolved addresses are reachable, which does not go through its Dial
-	// hook. As a result, it is unusable on GOOS=wasip1 because it fails
-	// even when the Dial function is set because WASI preview 1 does not
-	// have a mechanism for opening UDP sockets.
-	//
-	// Instead of having (often indirect) use of the net.Resolver crash, we
-	// override the Dial function to error earlier in the resolver lifecycle
-	// with an error which is more explicit to the end user.
-	return nil, errors.New("net.Resolver not supported on GOOS=wasip1")
-}
-
-func init() {
-	net.DefaultResolver.Dial = dialResolverNotSupported
-}
-
 func newOpError(op string, addr net.Addr, err error) error {
 	return &net.OpError{
 		Op:   op,