v0

README

tinygo/v0

This directory contains package you might find useful when building a v0 WATM with TinyGo.

Documentation

Index

• Constants
• func BuildDialerWithDialingTransport(dt DialingTransport)
• func BuildDialerWithWrappingTransport(wt WrappingTransport)
• func BuildListenerWithListeningTransport(lt ListeningTransport)
• func BuildListenerWithWrappingTransport(wt WrappingTransport)
• func BuildRelayWithListeningDialingTransport(lt ListeningTransport, dt DialingTransport)
• func BuildRelayWithWrappingTransport(wt WrappingTransport, wrapSelection RelayWrapSelection)
• func WorkerFairness(fair bool)
• type ConfigurableTransport
• type DialingTransport
• type ListeningTransport
• type RelayWrapSelection
• type WrappingTransport

Constants

const (
	EventFdRead  uint16 = iota + 1 // readable event
	EventFdWrite                   // writeable event
)

Functions

func BuildDialerWithDialingTransport

func BuildDialerWithDialingTransport(dt DialingTransport)

BuildDialerWithDialingTransport arms the dialer with a DialingTransport that is used to dial a remote address and provide high-level application layer protocol over the dialed connection.

Mutually exclusive with BuildDialerWithWrappingTransport.

func BuildDialerWithWrappingTransport

func BuildDialerWithWrappingTransport(wt WrappingTransport)

BuildDialerWithWrappingTransport arms the dialer with a WrappingTransport that is used to wrap a v0net.Conn into another net.Conn by providing some high-level application layer protocol.

Mutually exclusive with BuildDialerWithDialingTransport.

func BuildListenerWithListeningTransport

func BuildListenerWithListeningTransport(lt ListeningTransport)

BuildListenerWithListeningTransport arms the listener with a ListeningTransport that is used to accept incoming connections on a local address and provide high-level application layer protocol over the accepted connection.

Mutually exclusive with BuildListenerWithWrappingTransport.

func BuildListenerWithWrappingTransport

func BuildListenerWithWrappingTransport(wt WrappingTransport)

BuildListenerWithWrappingTransport arms the listener with a WrappingTransport that is used to wrap a v0net.Conn into another net.Conn by providing some high-level application layer protocol.

Mutually exclusive with BuildListenerWithListeningTransport.

func BuildRelayWithListeningDialingTransport

func BuildRelayWithListeningDialingTransport(lt ListeningTransport, dt DialingTransport)

BuildRelayWithListeningDialingTransport arms the relay with a ListeningTransport that is used to accept incoming connections on a local address and provide high-level application layer protocol over the accepted connection, and a DialingTransport that is used to dial a remote address and provide high-level application layer protocol over the dialed connection.

Mutually exclusive with BuildRelayWithWrappingTransport.

func BuildRelayWithWrappingTransport

func BuildRelayWithWrappingTransport(wt WrappingTransport, wrapSelection RelayWrapSelection)

BuildRelayWithWrappingTransport arms the relay with a WrappingTransport that is used to wrap a v0net.Conn into another net.Conn by providing some high-level application layer protocol.

The caller MUST keep in mind that the WrappingTransport is used to wrap the connection to the remote address, not the connection from the source address (the dialing peer). To reverse this behavior, i.e., wrap the inbounding connection, set wrapSelection to RelayWrapSource.

Mutually exclusive with BuildRelayWithListeningDialingTransport.

func WorkerFairness

func WorkerFairness(fair bool)

WorkerFairness sets the fairness of a worker.

If sourceConn or remoteConn will not work in non-blocking mode, it is highly recommended to set fair to true, otherwise it is most likely that the worker will block on reading from a blocking connection forever and therefore make no progress in the other direction.

Types

type ConfigurableTransport

type ConfigurableTransport interface {
	Configure(config []byte) error
}

ConfigurableTransport is a transport type that can be configured with a config file in the form of a byte slice.

type DialingTransport

type DialingTransport interface {
	// SetDialer sets the dialer function that is used to dial
	// a remote address.
	//
	// In v0, the input parameter of the dialer function is
	// unused inside the WATM, given the connection is always
	// managed by the host application.
	//
	// The returned v0net.Conn is NOT by default set to non-blocking.
	// It is the responsibility of the transport to make it
	// non-blocking by calling v0net.Conn.SetNonblock. This is to
	// allow some transport to perform blocking operations such as
	// TLS handshake.
	SetDialer(dialer func(network, address string) (v0net.Conn, error))

	// Dial dials a remote address and returns a v0net.Conn that
	// provides high-level application layer protocol over the
	// dialed connection.
	//
	// The transport SHOULD provide non-blocking v0net.Conn.Read
	// operation on the returned v0net.Conn if possible, otherwise
	// the worker may block on reading from a blocking connection.
	// And it is highly recommended to pass all funtions other than
	// Read and Write to the underlying v0net.Conn from the underlying
	// dialer function.
	Dial(network, address string) (v0net.Conn, error)
}

DialingTransport is a transport type that can be used to dial a remote address and provide high-level application layer protocol over the dialed connection.

type ListeningTransport

type ListeningTransport interface {
	// SetListener sets the listener that is used to accept
	// incoming connections.
	//
	// The returned v0net.Conn is not by default non-blocking.
	// It is the responsibility of the transport to make it
	// non-blocking if required by calling v0net.Conn.SetNonblock.
	SetListener(listener v0net.Listener)

	// Accept accepts an incoming connection and returns a
	// net.Conn that provides high-level application layer
	// protocol over the accepted connection.
	//
	// The transport SHOULD provide non-blocking v0net.Conn.Read
	// operation on the returned v0net.Conn if possible, otherwise
	// the worker may block on reading from a blocking connection.
	// And it is highly recommended to pass all funtions other than
	// Read and Write to the underlying v0net.Conn from the underlying
	// dialer function.
	Accept() (v0net.Conn, error)
}

ListeningTransport is a transport type that can be used to accept incoming connections on a local address and provide high-level application layer protocol over the accepted connection.

type RelayWrapSelection

type RelayWrapSelection bool

const (
	RelayWrapRemote RelayWrapSelection = false
	RelayWrapSource RelayWrapSelection = true
)

type WrappingTransport

type WrappingTransport interface {
	// Wrap wraps a v0net.Conn into another v0net.Conn with a protocol
	// wrapper layer.
	//
	// The returned v0net.Conn is NOT by default set to non-blocking.
	// It is the responsibility of the transport to make it
	// non-blocking by calling v0net.Conn.SetNonblock. This is to
	// allow some transport to perform blocking operations such as
	// TLS handshake.
	//
	// The transport SHOULD provide non-blocking v0net.Conn.Read
	// operation on the returned v0net.Conn if possible, otherwise
	// the worker may block on reading from a blocking connection.
	// And it is highly recommended to pass all funtions other than
	// Read and Write to the underlying v0net.Conn from the underlying
	// dialer function.
	Wrap(v0net.Conn) (v0net.Conn, error)
}

WrappingTransport is the most basic transport type. It wraps a v0net.Conn into another v0net.Conn by providing some high-level application layer protocol.