socketaddon

The WebSocket wire: a page and its server in two processes.

#Using it

The server calls serve or upgrades with an accept function, which is the server's side of one seat (see loopback). The page calls dial and hands the wire it returns to the scenemanager's link.

import { serve, dial } from '#addons/socket/socket.addon.ts'

// on the server
const { port, close } = await serve(8080, accept)

// in the page
const wire = dial('ws://localhost:8080', () => showDisconnected())

Everything the two ends say to each other crosses as JSON, U going up to the server and D coming down. The wire knows nothing about what is said.

A Uint8Array anywhere in a message, such as a physics world's image among the memory a kind hands a joining page (see rewind), crosses as the bytes it is rather than as JSON. The message then goes as one binary frame and arrives with each array a Uint8Array of its own, back in its place. A message holding no byte array goes as JSON text.

#Methods

On the server

Run on node.

serve( port, accept ) : Promise<{ port, close }>

Listens for WebSocket connections on port and hands each connection to accept. A connection that accept throws on is closed with code 1013 and the error as its reason. With a port of 0 the machine chooses a free one. The promise resolves once the server is listening, with the port it listens on and a close() that drops every connection and stops listening, itself returning a promise.

upgrades( accept ) : Promise<{ upgrade, close }>

The same as serve on an HTTP server someone else holds, so the game's socket shares that server's port. It listens on no port of its own. Call upgrade(req, socket, head) with each upgrade request that the code holding the HTTP server has found is meant for the game. close() drops every connection.

In the page

Run in the browser.

dial( url, gone? ) : Wire

A wire to the server at url, which the scenemanager's link takes. A send before the socket is open waits for it. gone is called once when the socket closes by any way but the wire's own close: the server went away, or was never there.

#Used by

• simulator
  Uses it as a wire for its pages.

#In the guide