chore(readme): add README.md for ws (denoland/deno_std#417)

Original: https://github.com/denoland/deno_std/commit/301c12d9d20d94d0ed36a394353835a90b5e9249

2 files changed, 203 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5eed61cc2..365637bef 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@ Here are the dedicated documentations of modules:
 - [strings](strings/README.md)
 - [testing](testing/README.md)
 - [toml](toml/README.md)
+- [ws](ws/README.md)
 
 ## Contributing
 
diff --git a/ws/README.md b/ws/README.md
new file mode 100644
index 000000000..12cd51094
--- /dev/null
+++ b/ws/README.md
@@ -0,0 +1,202 @@
+# 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/strings.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/colors/mod.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.