v1

package
v0.7.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2024 License: Apache-2.0 Imports: 15 Imported by: 0

README

transport/v1

This directory contains the experimental implementation of the driver for WebAssembly Transport Module (WATM) spec version 1, our first stable public release.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewDialer deprecated 

func NewDialer(c *water.Config) (water.Dialer, error)

NewDialer creates a new water.Dialer from the given water.Config.

Deprecated: use NewDialerWithContext instead.

func NewDialerWithContext 

func NewDialerWithContext(ctx context.Context, c *water.Config) (water.Dialer, error)

NewDialerWithContext creates a new water.Dialer from the given water.Config with the given context.Context.

The context is used as the default context for call to Dialer.Dial.

func NewFixedDialerWithContext 

func NewFixedDialerWithContext(ctx context.Context, c *water.Config) (water.FixedDialer, error)

func NewListener deprecated 

func NewListener(c *water.Config) (water.Listener, error)

NewListener creates a new water.Listener from the given water.Config.

Deprecated: use NewListenerWithContext instead.

func NewListenerWithContext 

func NewListenerWithContext(ctx context.Context, c *water.Config) (water.Listener, error)

NewListenerWithContext creates a new water.Listener from the water.Config with the given context.Context.

The context is passed to water.NewCoreWithContext 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 water.WazeroRuntimeConfigFactory.SetCloseOnContextDone with false to disable this behavior.

func NewRelay deprecated 

func NewRelay(c *water.Config) (water.Relay, error)

NewRelay creates a new water.Relay from the given water.Config without starting it. To start the relay, call Relay.RelayTo or Relay.ListenAndRelayTo.

Deprecated: use NewRelayWithContext instead.

func NewRelayWithContext 

func NewRelayWithContext(ctx context.Context, c *water.Config) (water.Relay, error)

NewRelayWithContext creates a new water.Relay from the water.Config with the given context.Context without starting it. To start the relay, call Relay.RelayTo or Relay.ListenAndRelayTo.

The context is passed to water.NewCoreWithContext 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 water.WazeroRuntimeConfigFactory.SetCloseOnContextDone with false to disable this behavior.

Types

type Conn 

type Conn struct {
	water.UnimplementedConn // embedded to ensure forward compatibility
	// contains filtered or unexported fields
}

Conn is the first experimental version of Conn implementation.

func (*Conn) Close 

func (c *Conn) Close() (err error)

Close implements the net.Conn interface.

It will close both the network connection AND the WASM module, then the user-facing net.Conn will be closed.

func (*Conn) LocalAddr 

func (c *Conn) LocalAddr() net.Addr

LocalAddr implements the net.Conn interface.

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 (*Conn) Read 

func (c *Conn) Read(b []byte) (n int, err error)

Read implements the net.Conn interface.

It calls to the underlying user-oriented connection's net.Conn.Read method.

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr implements the net.Conn interface.

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 (*Conn) SetDeadline 

func (c *Conn) SetDeadline(t time.Time) (err error)

SetDeadline implements the net.Conn interface.

It calls to the underlying connections' net.Conn.SetDeadline method.

func (*Conn) SetReadDeadline 

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline implements the net.Conn interface.

It calls to the underlying user-oriented connection's net.Conn.SetReadDeadline method.

func (*Conn) SetWriteDeadline 

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the net.Conn interface.

It calls to the underlying user-oriented connection's net.Conn.SetWriteDeadline method.

func (*Conn) Write 

func (c *Conn) Write(b []byte) (n int, err error)

Write implements the net.Conn interface.

It calls to the underlying user-oriented connection's net.Conn.Write method.

type CtrlPipe 

type CtrlPipe struct {
	net.Conn
}

func (*CtrlPipe) WriteExit 

func (c *CtrlPipe) WriteExit() error

type Dialer 

type Dialer struct {
	water.UnimplementedDialer // embedded to ensure forward compatibility
	// contains filtered or unexported fields
}

Dialer implements water.Dialer utilizing Water WATM API v1.

Example

ExampleDialer demonstrates how to use v1.Dialer as a water.Dialer. 

config := &water.Config{
	TransportModuleBin:  wasmReverse,
	ModuleConfigFactory: water.NewWazeroModuleConfigFactory(),
}

waterDialer, err := v1.NewDialerWithContext(context.Background(), config)
if err != nil {
	panic(err)
}

// create a local TCP listener
tcpListener, err := net.Listen("tcp", "localhost:0")
if err != nil {
	panic(err)
}
defer tcpListener.Close() // skipcq: GO-S2307

waterConn, err := waterDialer.DialContext(context.Background(), "tcp", tcpListener.Addr().String())
if err != nil {
	panic(err)
}
defer waterConn.Close() // skipcq: GO-S2307

tcpConn, err := tcpListener.Accept()
if err != nil {
	panic(err)
}
defer tcpConn.Close() // skipcq: GO-S2307

var msg = []byte("hello")
n, err := waterConn.Write(msg)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short write")
}

buf := make([]byte, 1024)
n, err = tcpConn.Read(buf)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short read")
}

if err := waterConn.Close(); err != nil {
	panic(err)
}

fmt.Println(string(buf[:n]))

Output:

olleh

func (*Dialer) Dial 

func (d *Dialer) Dial(network, address string) (conn water.Conn, err error)

Dial dials the network address using the dialerFunc specified in config.

Implements water.Dialer.

func (*Dialer) DialContext 

func (d *Dialer) DialContext(ctx context.Context, network, address string) (conn water.Conn, err error)

DialContext dials the network address using the dialerFunc specified in config.

The context is passed to water.NewCoreWithContext 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 water.WazeroRuntimeConfigFactory.SetCloseOnContextDone with false to disable this behavior.

Implements water.Dialer.

type FixedDialer 

type FixedDialer struct {
	water.UnimplementedFixedDialer // embedded to ensure forward compatibility
	// contains filtered or unexported fields
}
Example

ExampleFixedDialer demonstrates how to use v1.FixedDialer as a water.Dialer. 

config := &water.Config{
	TransportModuleBin:  wasmReverse,
	ModuleConfigFactory: water.NewWazeroModuleConfigFactory(),
	DialedAddressValidator: func(network, address string) error {
		if network != "tcp" || address != "localhost:7700" {
			return fmt.Errorf("invalid address: %s", address)
		}
		return nil
	},
}

waterDialer, err := v1.NewFixedDialerWithContext(context.Background(), config)
if err != nil {
	panic(err)
}

// create a local TCP listener
tcpListener, err := net.Listen("tcp", "localhost:7700")
if err != nil {
	panic(err)
}
defer tcpListener.Close() // skipcq: GO-S2307

waterConn, err := waterDialer.DialFixedContext(context.Background())
if err != nil {
	panic(err)
}
defer waterConn.Close() // skipcq: GO-S2307

tcpConn, err := tcpListener.Accept()
if err != nil {
	panic(err)
}
defer tcpConn.Close() // skipcq: GO-S2307

var msg = []byte("hello")
n, err := waterConn.Write(msg)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short write")
}

buf := make([]byte, 1024)
n, err = tcpConn.Read(buf)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short read")
}

if err := waterConn.Close(); err != nil {
	panic(err)
}

fmt.Println(string(buf[:n]))

Output:

olleh

func (*FixedDialer) DialFixed 

func (f *FixedDialer) DialFixed() (conn water.Conn, err error)

func (*FixedDialer) DialFixedContext 

func (f *FixedDialer) DialFixedContext(ctx context.Context) (conn water.Conn, err error)

type Listener 

type Listener struct {
	water.UnimplementedListener // embedded to ensure forward compatibility
	// contains filtered or unexported fields
}

Listener implements water.Listener utilizing Water WATM API v1.

Example

ExampleListener demonstrates how to use v1.Listener as a water.Listener. 

wrappedTcpListener, err := net.Listen("tcp", "localhost:0")
if err != nil {
	panic(fmt.Sprintf("failed to listen: %v", err))
}

// start using W.A.T.E.R. API below this line, have fun!
config := &water.Config{
	TransportModuleBin:  wasmReverse,
	NetworkListener:     wrappedTcpListener,
	ModuleConfigFactory: water.NewWazeroModuleConfigFactory(),
}

waterListener, err := v1.NewListenerWithContext(context.Background(), config)
if err != nil {
	panic(fmt.Sprintf("failed to listen: %v", err))
}
defer waterListener.Close() // skipcq: GO-S2307

tcpConn, err := net.Dial("tcp", waterListener.Addr().String())
if err != nil {
	panic(err)
}
defer tcpConn.Close() // skipcq: GO-S2307

waterConn, err := waterListener.Accept()
if err != nil {
	panic(err)
}
defer waterConn.Close() // skipcq: GO-S2307

var msg = []byte("hello")
n, err := tcpConn.Write(msg)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short write")
}

buf := make([]byte, 1024)
n, err = waterConn.Read(buf)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short read")
}

if err := waterConn.Close(); err != nil {
	panic(err)
}

fmt.Println(string(buf[:n]))

Output:

olleh

func (*Listener) Accept 

func (l *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection after processing the data with the WASM module.

The returned net.Conn implements net.Conn and could be seen as the inbound connection with a wrapping transport protocol handled by the WASM module.

Implements net.Listener.

func (*Listener) AcceptWATER 

func (l *Listener) AcceptWATER() (water.Conn, error)

AcceptWATER waits for and returns the next connection to the listener as a water.Conn.

Implements water.Listener.

func (*Listener) Addr 

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address.

Implements net.Listener.

func (*Listener) Close 

func (l *Listener) Close() error

Close closes the listener.

Implements net.Listener.

type Relay 

type Relay struct {
	water.UnimplementedRelay // embedded to ensure forward compatibility
	// contains filtered or unexported fields
}

Relay implements water.Relay utilizing Water WATM API v1.

Example

ExampleRelay demonstrates how to use v1.Relay as a water.Relay. 

// Relay destination: a local TCP server
tcpListener, err := net.Listen("tcp", "localhost:0")
if err != nil {
	panic(err)
}
defer tcpListener.Close() // skipcq: GO-S2307

config := &water.Config{
	TransportModuleBin:  wasmReverse,
	ModuleConfigFactory: water.NewWazeroModuleConfigFactory(),
}

waterRelay, err := v1.NewRelayWithContext(context.Background(), config)
if err != nil {
	panic(err)
}
defer waterRelay.Close() // skipcq: GO-S2307

// in a goroutine, start relay
go func() {
	err := waterRelay.ListenAndRelayTo("tcp", "localhost:0", "tcp", tcpListener.Addr().String())
	if err != nil {
		panic(err)
	}
}()
time.Sleep(100 * time.Millisecond) // 100ms to spin up relay

// test source: a local TCP client
clientConn, err := net.Dial("tcp", waterRelay.Addr().String())
if err != nil {
	panic(err)
}
defer clientConn.Close() // skipcq: GO-S2307

serverConn, err := tcpListener.Accept()
if err != nil {
	panic(err)
}
defer serverConn.Close() // skipcq: GO-S2307

var msg = []byte("hello")
n, err := clientConn.Write(msg)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short write")
}

buf := make([]byte, 1024)
n, err = serverConn.Read(buf)
if err != nil {
	panic(err)
}
if n != len(msg) {
	panic("short read")
}

if err := waterRelay.Close(); err != nil {
	panic(err)
}

fmt.Println(string(buf[:n]))

Output:

olleh

func (*Relay) Addr 

func (r *Relay) Addr() net.Addr

Addr implements water.Relay.

func (*Relay) Close 

func (r *Relay) Close() error

Close implements water.Relay.

func (*Relay) ListenAndRelayTo 

func (r *Relay) ListenAndRelayTo(lnetwork, laddress, rnetwork, raddress string) error

ListenAndRelayTo implements water.Relay.

func (*Relay) RelayTo 

func (r *Relay) RelayTo(network, address string) error

RelayTo implements water.Relay.

type TransportModule 

type TransportModule struct {
	// contains filtered or unexported fields
}

TransportModule acts like a "managed core". It was build to provide WebAssembly Transport Module API-facing functions and utilities that are exclusive to version 0.

func UpgradeCore 

func UpgradeCore(core water.Core) *TransportModule

UpgradeCore upgrades a water.Core to a v0 TransportModule.

func (*TransportModule) AcceptFor 

func (tm *TransportModule) AcceptFor(reverseCallerConn net.Conn) (sourceConn net.Conn, err error)

AcceptFor is used to make the Transport Module act as a listener and accept a network connection.

func (*TransportModule) Associate 

func (tm *TransportModule) Associate() error

Associate is used to make the Transport Module act as a relay and associate two network connections, where one is from a source via a listener, and the other is to a destination via a dialer.

func (*TransportModule) Cancel 

func (tm *TransportModule) Cancel(timeout time.Duration) error

Cancel cancels the worker thread if it is running and returns the error returned by the worker thread. This call is designed to block until the worker thread exits.

If a timeout is set, this function will cancel the underlying context to terminate the WebAssembly execution if the worker does not exit before the timeout.

func (*TransportModule) Cleanup 

func (tm *TransportModule) Cleanup()

Clean up the Transport Module by closing all connections pushed into the Transport Module.

func (*TransportModule) Close 

func (tm *TransportModule) Close() error

func (*TransportModule) Core 

func (tm *TransportModule) Core() water.Core

func (*TransportModule) Defer 

func (tm *TransportModule) Defer(f func())

func (*TransportModule) DeferAll 

func (tm *TransportModule) DeferAll()

func (*TransportModule) DialFixedFrom 

func (tm *TransportModule) DialFixedFrom(reverseCallerConn net.Conn) (destConn net.Conn, err error)

func (*TransportModule) DialFrom 

func (tm *TransportModule) DialFrom(reverseCallerConn net.Conn) (destConn net.Conn, err error)

DialFrom is used to make the Transport Module act as a dialer and dial a network connection.

Takes the reverse caller connection as an argument, which is used to communicate with the caller.

func (*TransportModule) ExitedWith 

func (tm *TransportModule) ExitedWith() error

ExitedWith returns the error that the worker thread exited with.

It is recommended to use TransportModule.WaitWorker to wait for the worker thread to exit and get the error. This function does not check if the worker thread has exited yet and will return always return nil before the worker thread exits.

func (*TransportModule) GetManagedConns 

func (tm *TransportModule) GetManagedConns(fd int32) net.Conn

GetManagedConns returns the net.Conn associated with the file descriptor.

func (*TransportModule) Initialize 

func (tm *TransportModule) Initialize() error

Initialize initializes the WASMv0 runtime by getting all the exported functions from the WASM module.

All imports must be set before calling this function.

func (*TransportModule) LinkNetworkInterface 

func (tm *TransportModule) LinkNetworkInterface(dialer *networkDialer, listener net.Listener) error

func (*TransportModule) PushConn 

func (tm *TransportModule) PushConn(conn net.Conn) (fd int32, err error)

PushConn pushes a net.Conn into the Transport Module.

func (*TransportModule) StartWorker 

func (tm *TransportModule) StartWorker() error

Worker spins up a worker thread for the WATM to run a blocking function, which is expected to be the mainloop.

This function is non-blocking, so it will not return any error once the WebAssembly worker thread is started. To get the error, use TransportModule.WaitWorker or TransportModule.ExitedWith.

func (*TransportModule) WaitWorker 

func (tm *TransportModule) WaitWorker() error

WaitWorker waits for the worker thread to exit and returns the error if any.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.