update: fix and update documentations, deprecate functions (#48)

Signed-off-by: Gaukas Wang <[email protected]>

README.md

@@ -104,7 +104,7 @@ connection.
 		TransportModuleBin: wasm,
 	}
 
-	dialer, _ := water.NewDialer(config)
+	dialer, _ := water.NewDialerWithContext(context.Background(), config)
 	conn, _ := dialer.DialContext(context.Background(),"tcp", remoteAddr)
 	// ...
 ```

config.go

@@ -223,6 +223,10 @@ func (c *Config) UnmarshalJSON(data []byte) error {
 		c.RuntimeConfig().Interpreter()
 	}
 
+	if confJson.Runtime.DoNotCloseOnContextDone {
+		c.RuntimeConfig().SetCloseOnContextDone(false)
+	}
+
 	return nil
 }
 
@@ -294,5 +298,9 @@ func (c *Config) UnmarshalProto(b []byte) error {
 		c.RuntimeConfig().Interpreter()
 	}
 
+	if confProto.GetRuntime().GetDoNotCloseOnContextDone() {
+		c.RuntimeConfig().SetCloseOnContextDone(false)
+	}
+
 	return nil
 }

configbuilder/config.json.go

@@ -28,7 +28,8 @@ type ConfigJSON struct {
 	} `json:"module,omitempty"`
 
 	Runtime struct {
-		ForceInterpreter bool `json:"force_interpreter,omitempty"` // If set, will use interpreter mode even on platforms with compiler support
+		ForceInterpreter        bool `json:"force_interpreter,omitempty"`            // If set, will use interpreter mode even on platforms with compiler support
+		DoNotCloseOnContextDone bool `json:"do_not_close_on_context_done,omitempty"` // If unset, will close the module when the context is done and prevent any further calls to the module
 		// Setting CompilationCache is not supported yet through JSON
 	} `json:"runtime,omitempty"`
 }

configbuilder/pb/config.proto

@@ -23,7 +23,7 @@ message Network {
 message Listener {
     string network = 1;
     string address = 2; // ip:port
-}    
+}
 
 message Module {
     repeated string argv = 1; // warning: this is not a recommended way to pass configuration parameters to the module, use transport_module.config instead. 
@@ -35,5 +35,6 @@ message Module {
 }
 
 message Runtime {
-    bool force_interpreter = 1;    
-}
+    bool force_interpreter = 1;
+    bool do_not_close_on_context_done = 2;
+}

core.go

@@ -161,10 +161,23 @@ type core struct {
 //
 // It uses the default implementation of interface.Core as
 // defined in this file.
+//
+// Deprecated: use [NewCoreWithContext] instead.
 func NewCore(config *Config) (Core, error) {
 	return NewCoreWithContext(context.Background(), config)
 }
 
+// NewCoreWithContext creates a new Core with the given context and config.
+//
+// It uses the default implementation of interface.Core as
+// defined in this file.
+//
+// The context is used to control the lifetime of the call to
+// function calls into the WebAssembly module. If the context
+// is canceled or reaches its deadline, any current and future
+// function call will return with an error. Call
+// [WazeroRuntimeConfigFactory.SetCloseOnContextDone] with false
+// to disable this behavior.
 func NewCoreWithContext(ctx context.Context, config *Config) (Core, error) {
 	var err error
 

dialer.go

@@ -30,7 +30,7 @@ type Dialer interface {
 	mustEmbedUnimplementedDialer()
 }
 
-type newDialerFunc func(*Config) (Dialer, error)
+type newDialerFunc func(context.Context, *Config) (Dialer, error)
 
 var (
 	knownDialerVersions = make(map[string]newDialerFunc)
@@ -76,12 +76,34 @@ func RegisterWATMDialer(version string, dialer newDialerFunc) error {
 	return nil
 }
 
-// NewDialer creates a new Dialer from the config.
+// NewDialer creates a new [Dialer] from the given [Config].
 //
 // It automatically detects the version of the WebAssembly Transport
 // Module specified in the config.
+//
+// Deprecated: use NewDialerWithContext instead.
 func NewDialer(c *Config) (Dialer, error) {
-	core, err := NewCore(c)
+	return NewDialerWithContext(context.Background(), c)
+}
+
+// NewDialerWithContext creates a new [Dialer] from the [Config] with
+// the given [context.Context].
+//
+// It automatically detects the version of the WebAssembly Transport
+// Module specified in the config.
+//
+// The context is passed to [NewCoreWithContext] and the registered versioned
+// dialer creation function to control the lifetime of the call to function
+// calls into the WebAssembly module.
+// If the context is canceled or reaches its deadline, any current and future
+// function call will return with an error.
+// Call [WazeroRuntimeConfigFactory.SetCloseOnContextDone] with false to disable
+// this behavior.
+//
+// The context SHOULD be used as the default context for call to [Dialer.Dial]
+// by the dialer implementation.
+func NewDialerWithContext(ctx context.Context, c *Config) (Dialer, error) {
+	core, err := NewCoreWithContext(ctx, c)
 	if err != nil {
 		return nil, err
 	}
@@ -93,7 +115,7 @@ func NewDialer(c *Config) (Dialer, error) {
 	// in a more organized way.
 	for exportName := range core.Exports() {
 		if f, ok := knownDialerVersions[exportName]; ok {
-			return f(c)
+			return f(ctx, c)
 		}
 	}
 

examples/v0/dialer/main.go

@@ -38,16 +38,16 @@ func main() {
 	config.ModuleConfig().InheritStdout()
 	config.ModuleConfig().InheritStderr()
 
-	dialer, err := water.NewDialer(config)
-	if err != nil {
-		panic(fmt.Sprintf("failed to create dialer: %v", err))
-	}
-
 	ctx := context.Background()
 	// // optional: enable wazero logging
 	// ctx = context.WithValue(ctx, experimental.FunctionListenerFactoryKey{},
 	// 	logging.NewHostLoggingListenerFactory(os.Stderr, logging.LogScopeFilesystem|logging.LogScopePoll|logging.LogScopeSock))
 
+	dialer, err := water.NewDialerWithContext(ctx, config)
+	if err != nil {
+		panic(fmt.Sprintf("failed to create dialer: %v", err))
+	}
+
 	conn, err := dialer.DialContext(ctx, "tcp", *remoteAddr)
 	if err != nil {
 		panic(fmt.Sprintf("failed to dial: %v", err))

listener.go

@@ -73,7 +73,7 @@ func RegisterWATMListener(version string, listener newListenerFunc) error {
 	return nil
 }
 
-// NewListener creates a new Listener from the config.
+// NewListener creates a new [Listener] from the given [Config].
 //
 // It automatically detects the version of the WebAssembly Transport
 // Module specified in the config.
@@ -83,12 +83,21 @@ func NewListener(c *Config) (Listener, error) {
 	return NewListenerWithContext(context.Background(), c)
 }
 
-// NewListenerWithContext creates a new Listener from the config with
-// the given context.
+// NewListenerWithContext creates a new [Listener] from the [Config] with
+// the given [context.Context].
 //
 // It automatically detects the version of the WebAssembly Transport
+// Module specified in the config.
+//
+// The context is passed to [NewCoreWithContext] and the registered versioned
+// listener creation function to control the lifetime of the call to function
+// calls into the WebAssembly module.
+// If the context is canceled or reaches its deadline, any current and future
+// function call will return with an error.
+// Call [WazeroRuntimeConfigFactory.SetCloseOnContextDone] with false to disable
+// this behavior.
 func NewListenerWithContext(ctx context.Context, c *Config) (Listener, error) {
-	core, err := NewCore(c)
+	core, err := NewCoreWithContext(ctx, c)
 	if err != nil {
 		return nil, err
 	}

log.go

@@ -12,10 +12,11 @@ func SetDefaultLogger(logger *log.Logger) {
 	log.SetDefaultLogger(logger)
 }
 
-// SetDefaultHandler sets the handler to be used by the package
+// SetDefaultLogHandler sets the handler to be used by the package
 // if no logger is specifically configured for each component.
+// Renamed from SetDefaultHandler.
 //
 // It overrides the logger specified by SetDefaultLogger.
-func SetDefaultHandler(handler log.Handler) {
+func SetDefaultLogHandler(handler log.Handler) {
 	log.SetDefaultHandler(handler)
 }

relay.go

@@ -101,7 +101,7 @@ func RegisterWATMRelay(version string, relay newRelayFunc) error {
 	return nil
 }
 
-// NewRelay creates a new Relay from the config.
+// NewRelay creates a new [Relay] from the given [Config].
 //
 // It automatically detects the version of the WebAssembly Transport
 // Module specified in the config.
@@ -111,13 +111,21 @@ func NewRelay(c *Config) (Relay, error) {
 	return NewRelayWithContext(context.Background(), c)
 }
 
-// NewRelayWithContext creates a new Relay from the config with
-// the given context.
+// NewRelayWithContext creates a new [Relay] from the [Config] with
+// the given [context.Context].
 //
 // It automatically detects the version of the WebAssembly Transport
 // Module specified in the config.
+//
+// The context is passed to [NewCoreWithContext] and the registered versioned
+// relay creation function to control the lifetime of the call to function
+// calls into the WebAssembly module.
+// If the context is canceled or reaches its deadline, any current and future
+// function call will return with an error.
+// Call [WazeroRuntimeConfigFactory.SetCloseOnContextDone] with false to disable
+// this behavior.
 func NewRelayWithContext(ctx context.Context, c *Config) (Relay, error) {
-	core, err := NewCore(c)
+	core, err := NewCoreWithContext(ctx, c)
 	if err != nil {
 		return nil, err
 	}

transport/v0/conn.go

@@ -179,7 +179,7 @@ func (c *Conn) closeOnWorkerError() {
 
 // Read implements the net.Conn interface.
 //
-// It calls to the underlying user-oriented net.Conn's Read() method.
+// It calls to the underlying user-oriented connection's [net.Conn.Read] method.
 func (c *Conn) Read(b []byte) (n int, err error) {
 	if c.callerConn == nil {
 		return 0, errors.New("water: cannot read, (*RuntimeConn).uoConn is nil")
@@ -190,7 +190,7 @@ func (c *Conn) Read(b []byte) (n int, err error) {
 
 // Write implements the net.Conn interface.
 //
-// It calls to the underlying user-oriented net.Conn's Write() method.
+// It calls to the underlying user-oriented connection's [net.Conn.Write] method.
 func (c *Conn) Write(b []byte) (n int, err error) {
 	if c.callerConn == nil {
 		return 0, errors.New("water: cannot write, (*RuntimeConn).uoConn is nil")
@@ -234,7 +234,7 @@ func (c *Conn) Close() (err error) {
 
 // LocalAddr implements the net.Conn interface.
 //
-// It calls to the underlying network connection's LocalAddr() method.
+// It calls to the underlying network connection's [net.Conn.LocalAddr] method.
 // For Listener and Relay, the network connection of interest is the srcConn.
 // And for Dialer, the network connection of interest is the dstConn.
 func (c *Conn) LocalAddr() net.Addr {
@@ -247,7 +247,7 @@ func (c *Conn) LocalAddr() net.Addr {
 
 // RemoteAddr implements the net.Conn interface.
 //
-// It calls to the underlying network connection's RemoteAddr() method.
+// It calls to the underlying network connection's [net.Conn.RemoteAddr] method.
 // For Listener and Relay, the network connection of interest is the srcConn.
 // And for Dialer, the network connection of interest is the dstConn.
 func (c *Conn) RemoteAddr() net.Addr {
@@ -260,7 +260,7 @@ func (c *Conn) RemoteAddr() net.Addr {
 
 // SetDeadline implements the net.Conn interface.
 //
-// It calls to the underlying user-oriented connection's SetDeadline() method.
+// It calls to the underlying connections' [net.Conn.SetDeadline] method.
 func (c *Conn) SetDeadline(t time.Time) (err error) {
 	// SetDeadline is only available to Dialer/Listener. But not Relay.
 	if c.callerConn == nil {
@@ -289,7 +289,7 @@ func (c *Conn) SetDeadline(t time.Time) (err error) {
 
 // SetReadDeadline implements the net.Conn interface.
 //
-// It calls to the underlying user-oriented connection's SetReadDeadline() method.
+// It calls to the underlying user-oriented connection's [net.Conn.SetReadDeadline] method.
 func (c *Conn) SetReadDeadline(t time.Time) error {
 	// SetReadDeadline is only available to Dialer/Listener. But not Relay.
 	if c.callerConn == nil {
@@ -301,7 +301,7 @@ func (c *Conn) SetReadDeadline(t time.Time) error {
 
 // SetWriteDeadline implements the net.Conn interface.
 //
-// It calls to the underlying user-oriented connection's SetWriteDeadline() method.
+// It calls to the underlying user-oriented connection's [net.Conn.SetWriteDeadline] method.
 func (c *Conn) SetWriteDeadline(t time.Time) error {
 	// SetWriteDeadline is only available to Dialer/Listener. But not Relay.
 	if c.callerConn == nil {