websocket

README

@mygo-plugins/websocket

A WebSocket for MyGo apps whose connections Go makes, with the API of the browser's. Unlike the browser's, it may send any header with the opening handshake, such as Authorization, Cookie or Origin, and is not subject to the page's Content Security Policy.

Use the plugin in Go:

import "github.com/egoist/mygo/plugins/websocket"

mygo.Use(websocket.Plugin) // or websocket.New(websocket.Options{...})

and connect in the frontend:

import { WebSocket } from "@mygo-plugins/websocket";

const ws = new WebSocket("wss://example.com/live", ["v1"], {
  headers: { authorization: `Bearer ${token}` },
});
ws.onopen = () => ws.send("hello");
ws.onmessage = (e) => console.log(e.data);
ws.onclose = (e) => console.log(e.code, e.reason, e.wasClean);

Messages are sent in order, bufferedAmount counts the bytes Go has not written yet, and received messages wait in Go while the page is behind, so a fast server cannot fill the page's memory. Connections close (1001, going away) when their page navigates away or its window closes. No extensions (such as permessage-deflate) are negotiated.

The documentation covers closing, failures and the options of the Go side.

Documentation

Overview

Package websocket is the WebSocket plugin of MyGo: pages open WebSocket connections from Go with the WebSocket class of its JavaScript package, @mygo-plugins/websocket, which has the API of the browser's. Unlike the browser's, it may send any header with the opening handshake, such as Authorization or Cookie, and is not subject to the page's Content Security Policy.

mygo.Use(websocket.Plugin)

and in the frontend:

import { WebSocket } from "@mygo-plugins/websocket";

const ws = new WebSocket("wss://example.com/live", [], {
  headers: { authorization: `Bearer ${token}` },
});
ws.onmessage = (e) => console.log(e.data);

Connections close when their page navigates away or its window closes.

Index

• Variables
• func New(opts Options) mygo.Plugin
• type Options

Variables

var Plugin = New(Options{})

Plugin is the plugin with the default options.

Functions

func New

func New(opts Options) mygo.Plugin

New returns the plugin with options.

Types

type Options

type Options struct {
	// Client makes the opening handshakes; nil means http.DefaultClient.
	// Its Timeout and CheckRedirect are ignored: connections last, and
	// redirects fail them, as in browsers.
	Client *http.Client
	// Allow, when not nil, decides whether pages may open a connection
	// with the handshake request; a connection it refuses fails.
	Allow func(r *http.Request) bool
	// MaxMessageSize is the most bytes a received message may have, 64 MiB
	// when zero. A bigger message fails the connection.
	MaxMessageSize int64
	// CloseTimeout is how long a connection closed by the page waits for
	// the server to finish the closing handshake, 5 seconds when zero.
	CloseTimeout time.Duration
}

Options configure the plugin.