denoland-deno/std/ws/README.md

# ws

ws module is made to provide helpers to create WebSocket client/server.

## Usage

### Server

```ts
import { serve } from "https://deno.land/std/http/server.ts";
import {
  acceptWebSocket,
  isWebSocketCloseEvent,
  isWebSocketPingEvent,
  WebSocket
} from "https://deno.land/std/ws/mod.ts";

const port = Deno.args[1] || "8080";
async function main(): Promise<void> {
  console.log(`websocket server is running on :${port}`);
  for await (const req of serve(`:${port}`)) {
    const { headers, conn } = req;
    acceptWebSocket({
      conn,
      headers,
      bufReader: req.r,
      bufWriter: req.w
    })
      .then(
        async (sock: WebSocket): Promise<void> => {
          console.log("socket connected!");
          const it = sock.receive();
          while (true) {
            try {
              const { done, value } = await it.next();
              if (done) {
                break;
              }
              const ev = value;
              if (typeof ev === "string") {
                // text message
                console.log("ws:Text", ev);
                await sock.send(ev);
              } else if (ev instanceof Uint8Array) {
                // binary message
                console.log("ws:Binary", ev);
              } else if (isWebSocketPingEvent(ev)) {
                const [, body] = ev;
                // ping
                console.log("ws:Ping", body);
              } else if (isWebSocketCloseEvent(ev)) {
                // close
                const { code, reason } = ev;
                console.log("ws:Close", code, reason);
              }
            } catch (e) {
              console.error(`failed to receive frame: ${e}`);
              await sock.close(1000).catch(console.error);
            }
          }
        }
      )
      .catch(
        (err: Error): void => {
          console.error(`failed to accept websocket: ${err}`);
        }
      );
  }
}

if (import.meta.main) {
  main();
}
```

### Client

```ts
import {
  connectWebSocket,
  isWebSocketCloseEvent,
  isWebSocketPingEvent,
  isWebSocketPongEvent
} from "https://deno.land/std/ws/mod.ts";
import { encode } from "https://deno.land/std/strings/mod.ts";
import { BufReader } from "https://deno.land/std/io/bufio.ts";
import { TextProtoReader } from "https://deno.land/std/textproto/mod.ts";
import { blue, green, red, yellow } from "https://deno.land/std/fmt/colors.ts";

const endpoint = Deno.args[1] || "ws://127.0.0.1:8080";
async function main(): Promise<void> {
  const sock = await connectWebSocket(endpoint);
  console.log(green("ws connected! (type 'close' to quit)"));
  (async function(): Promise<void> {
    for await (const msg of sock.receive()) {
      if (typeof msg === "string") {
        console.log(yellow("< " + msg));
      } else if (isWebSocketPingEvent(msg)) {
        console.log(blue("< ping"));
      } else if (isWebSocketPongEvent(msg)) {
        console.log(blue("< pong"));
      } else if (isWebSocketCloseEvent(msg)) {
        console.log(red(`closed: code=${msg.code}, reason=${msg.reason}`));
      }
    }
  })();
  const tpr = new TextProtoReader(new BufReader(Deno.stdin));
  while (true) {
    await Deno.stdout.write(encode("> "));
    const [line, err] = await tpr.readLine();
    if (err) {
      console.error(red(`failed to read line from stdin: ${err}`));
      break;
    }
    if (line === "close") {
      break;
    } else if (line === "ping") {
      await sock.ping();
    } else {
      await sock.send(line);
    }
    await new Promise((resolve): number => setTimeout(resolve, 0));
  }
  await sock.close(1000);
  Deno.exit(0);
}

if (import.meta.main) {
  main();
}
```

## API

### isWebSocketCloseEvent

Returns true if input value is a WebSocketCloseEvent, false otherwise.

### isWebSocketPingEvent

Returns true if input value is a WebSocketPingEvent, false otherwise.

### isWebSocketPongEvent

Returns true if input value is a WebSocketPongEvent, false otherwise.

### append

This module is used to merge two Uint8Arrays.

- note: This module might move to common/util.

```ts
import { append } from "https://deno.land/std/ws/mod.ts";

// a = [1], b = [2]
append(a, b); // output: [1, 2]

// a = [1], b = null
append(a, b); // output: [1]

// a = [], b = [2]
append(a, b); // output: [2]
```

### unmask

Unmask masked WebSocket payload.

### writeFrame

Write WebSocket frame to inputted writer.

### readFrame

Read WebSocket frame from inputted BufReader.

### createMask

Create mask from the client to the server with random 32bit number.

### acceptable

Returns true if input headers are usable for WebSocket, otherwise false

### createSecAccept

Create value of Sec-WebSocket-Accept header from inputted nonce.

### acceptWebSocket

Upgrade inputted TCP connection into WebSocket connection.

### createSecKey

Returns base64 encoded 16 bytes string for Sec-WebSocket-Key header.

### connectWebSocket

Connect to WebSocket endpoint url with inputted endpoint string and headers.

- note: Endpoint must be acceptable for URL.