README
¶
wasmws: Web-Assembly Websocket (for Go)
This package is a fork of github.com/tarndt/wasmws, to update dependency versions, and add some minor features I needed. Please consider using the original if it will suit your needs. If the upstream version is updated to suit my needs, I'll be deleting this fork.
What is wasmws? Why would I want to use this?
wasmws was written primarily to allow Go applications targeting WASM to communicate with a gRPC server. This is normally challenging for two reasons:
- In general, many internet ingress paths are not HTTP/2 end to end (gRPC uses HTTP/2). In particular, most CDN vendors do not support HTTP/2 back-haul to origin (ex. Cloudflare).
- Browser WASM applications cannot use grpc-go due to the low level networking that go-grpc requires for native operation not being available. (ex.
dial tcp: Protocol not availablefun...)
This library allows you to use a websocket as net.Conn for arbitrary traffic, this includes running protocols like HTTP, gRPC or any other TCP protocol over it). This is most useful for protocols that are not normally exposed to client side web applications. In our examples we will focus on gRPC since that was my use-case.
Aproach taken
Client-side (Go WASM application running in browser)
wasmws provides Go WASM specific net.Conn implementation that is backed by a browser native websocket:
myConn, err := wasmws.Dial("websocket", "ws://demos.kaazing.com/echo")
It is fairly straight forward to use this package to set up a gRPC connection:
conn, err := grpc.DialContext(dialCtx, "passthrough:///"+websocketURL, grpc.WithContextDialer(wasmws.GRPCDialer), grpc.WithTransportCredentials(creds))
See the demo client for an extended example.
Server-side
wasmws includes websocket net.Listener that provides a HTTP handler method to accept HTTP websocket connections...
wsl := wasmws.NewWebSocketListener(appCtx)
router.HandleFunc("/grpc-proxy", wsl.HTTPAccept)
And a network listener to provide net.Conns to network oriented servers:
err := grpcServer.Serve(wsl)
See the demo server for an extended example. If you need more server-side helpers checkout github.com/coder/websocket which these helpers use themselves.
Security
If you use a secure websocket and gRPC or HTTPS this means you get double TLS (once using the browser's TLS stack and once again using Go's). Unless the extra defense in depth is desirable, you may want to consider using an unsecured websocket.
Performance
Due to challenges around having the sever running as a native application and the client running in a browser coordinate, I have not yet added unit benches... :( yet. However, running the demo which performs 8192 gRPC hello world calls provides an idea of the library's performance:
Median of 6 runs:
- FireFox 71.0 (64-bit) on Linux:
SUCCESS running 8192 transactions! (average 452.88µs per operation)
- Chrome Version 79.0.3945.88 (Official Build) (64-bit) on Linux:
SUCCESS running 8192 transactions! (average 475.485µs per operation)
This implementation tries to be intelligent about managing buffers (via pooling) and switches on the fly between JavaScript ArrayBuffer and streaming Blob based websocket read interfaces based the size of the chunks/messages being received. Web browsers which do not support Blob stream and Blob arrayBuffer methods, such as Microsoft Edge, always use ArrayBuffer-based message consumption.
The test results above are from tests run on a local development workstation:
- CPU: AMD Ryzen 9 3900X 12-Core Processor
- OS: Ubuntu 18.04 LTS (Linux 4.15.X)
Running the demo
If you do not have Go installed, you will of course need to install it.
- Checkout repo:
git clone https://github.com/flimzy/wasmws.git - Change to the demo directory:
cd ./wasmws/demo/server - Build the client, server and run the server (which serves the client):
./build.bash && ./server - Open http://localhost:8080/ in your web browser
- Open the web console (Ctrl+Shift+K in Firefox, Ctrl+Shift+I in Chrome) and observe the output!
Alternatives
- Use gRPC-Web as a HTTP to gRPC gateway/proxy. (If you don't mind a TCP connection per request, running extra middleware which are also extra points of failure...)
- Use "github.com/coder/websocket"'s implementation which unlike "wasmws" does not use the browser provided websocket functionality. Test and bench your own use-case!
Future
wasmws is actively being maintained, but that does not mean there are not things to do:
Contributing
Issues, and especially issues with pull requests are welcome!
This code is licensed under MPL 2.0.
Documentation
¶
Index ¶
- Variables
- func Dial(network, address string) (net.Conn, error)
- func DialContext(ctx context.Context, network, address string) (net.Conn, error)
- func GRPCDialer(ctx context.Context, address string) (net.Conn, error)
- type DialOption
- type Dialer
- type WebSockListener
- type WebSocket
- func (ws *WebSocket) Close() error
- func (ws *WebSocket) LocalAddr() net.Addr
- func (ws *WebSocket) Read(buf []byte) (int, error)
- func (ws *WebSocket) RemoteAddr() net.Addr
- func (*WebSocket) SetDeadline(time.Time) (err error)
- func (*WebSocket) SetReadDeadline(time.Time) error
- func (*WebSocket) SetWriteDeadline(time.Time) error
- func (ws *WebSocket) Write(buf []byte) (int, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrWebsocketClosed is returned when operations are performed on a closed Websocket ErrWebsocketClosed = errors.New("WebSocket: Web socket is closed") )
Functions ¶
func Dial ¶
Dial is a standard legacy network dialer that returns a websocket-based connection. See: DialContext for details on the network and address.
func DialContext ¶
DialContext is a standard context-aware network dialer that returns a websocket-based connection. The address is a URL that should be in the form of "ws://host/path..." for unsecured websockets and "wss://host/path..." for secured websockets. If tunnel a TLS based protocol over a "wss://..." websocket you will get TLS twice, once on the websocket using the browsers TLS stack and another using the Go (or other compiled) TLS stack.
func GRPCDialer ¶
GRPCDialer can be used with google.golang.org/grpc.WithContextDialer to call DialContext. The address provided to the calling grpc.Dial should be in the form "passthrough:///"+websocketURL where websocketURL matches the description in DialContext.
Types ¶
type DialOption ¶
type DialOption interface {
// contains filtered or unexported methods
}
DialOption configures how we set up the connection.
func WithHTTPClient ¶
func WithHTTPClient(client *http.Client) DialOption
WithHTTPClient returns a DialOption that sets the HTTP client for the connection. Has no effect on the browser-based implementation.
type Dialer ¶
type Dialer struct {
// contains filtered or unexported fields
}
func NewDialer ¶
func NewDialer(opts ...DialOption) *Dialer
NewDialer allows custom configuration of the websocket dialer.
func (*Dialer) Dial ¶
Dial is a standard legacy network dialer that returns a websocket-based connection. See: DialContext for details on the network and address.
func (*Dialer) DialContext ¶
DialContext is a standard context-aware network dialer that returns a websocket-based connection. The address is a URL that should be in the form of "ws://host/path..." for unsecured websockets and "wss://host/path..." for secured websockets. If tunnel a TLS based protocol over a "wss://..." websocket you will get TLS twice, once on the websocket using the browsers TLS stack and another using the Go (or other compiled) TLS stack.
func (*Dialer) GRPCDialer ¶
GRPCDialer can be used with google.golang.org/grpc.WithContextDialer to call DialContext. The address provided to the calling grpc.Dial should be in the form "passthrough:///"+websocketURL where websocketURL matches the description in DialContext.
type WebSockListener ¶
type WebSockListener struct {
// AcceptOptions are options to be passed to [websocket.Accept].
AcceptOptions *websocket.AcceptOptions
// contains filtered or unexported fields
}
WebSockListener implements net.Listener and provides connections that are incoming websocket connections
func NewWebSocketListener ¶
func NewWebSocketListener(ctx context.Context) *WebSockListener
NewWebSocketListener constructs a new WebSockListener, the provided context is for the lifetime of the listener.
func (*WebSockListener) Accept ¶
func (wsl *WebSockListener) Accept() (net.Conn, error)
Accept fulfills the net.Listener interface and returns net.Conn that are incoming websockets
func (*WebSockListener) Addr ¶
func (wsl *WebSockListener) Addr() net.Addr
RemoteAddr returns a dummy websocket address to satisfy net.Listener
func (*WebSockListener) ServeHTTP ¶
func (wsl *WebSockListener) ServeHTTP(wtr http.ResponseWriter, req *http.Request)
ServeHTTP is a method that is mean to be used as http.HandlerFunc to accept inbound HTTP requests that are websocket connections
type WebSocket ¶
type WebSocket struct {
URL string
// contains filtered or unexported fields
}
WebSocket is a Go struct that wraps the web browser's JavaScript websocket object and provides a net.Conn interface
func New ¶
New returns a new WebSocket using the provided dial context and websocket URL. The URL should be in the form of "ws://host/path..." for unsecured websockets and "wss://host/path..." for secured websockets. If tunnel a TLS based protocol over a "wss://..." websocket you will get TLS twice, once on the websocket using the browsers TLS stack and another using the Go (or other compiled) TLS stack.
func (*WebSocket) LocalAddr ¶
LocalAddr returns a dummy websocket address to satisfy net.Conn, see: wsAddr
func (*WebSocket) RemoteAddr ¶
RemoteAddr returns a dummy websocket address to satisfy net.Conn, see: wsAddr
func (*WebSocket) SetDeadline ¶
SetDeadline implements the SetDeadline method, but is a no-op.
func (*WebSocket) SetReadDeadline ¶
SetReadDeadline implements the SetReadDeadline method but is a no-op.
func (*WebSocket) SetWriteDeadline ¶
SetWriteDeadline implements the SetWriteDeadline method, but is a no-op.
Source Files
Directories