ws

wsモジュールは、JSHアプリケーション用のWebSocketクライアント/サーバーAPIを提供します。 GoのネイティブWebSocket実装を基盤とする、WebSocketクラスとWebSocketServerクラスを提供します。

一般的な使用方法は以下のとおりです。

const { WebSocket, WebSocketServer } = require('ws');

WebSocket

WebSocketクライアント接続を作成します。

構文

new WebSocket(url)
new WebSocket(url, protocol)
new WebSocket(url, protocols)

パラメーター

• url String: ws://host:port/path、wss://host:port/pathなどのWebSocketサーバーアドレス
• protocol String: 要求するサブプロトコル1つ
• protocols String[]: 要求するサブプロトコルの一覧

urlがない場合や文字列以外の場合、コンストラクターはTypeErrorを発生させます。

プロパティ

readyStateの値

• WebSocket.CONNECTING = 0
• WebSocket.OPEN = 1
• WebSocket.CLOSING = 2
• WebSocket.CLOSED = 3

メッセージ型の定数

• WebSocket.TextMessage = 1
• WebSocket.BinaryMessage = 2

send()

サーバーにメッセージを送信します。

構文

ws.send(data)

パラメーター

• data String: 送信するテキストメッセージ

現在のJSH実装では、send()はテキストメッセージの使用を前提に設計されています。

ソケットが開いていない場合は、errorイベントが発生します。

使用例

1
2
3
4
5
6

const { WebSocket } = require('ws');

const ws = new WebSocket('ws://127.0.0.1:8080');
ws.on('open', () => {
    ws.send('Hello, server');
});

close()

現在の接続を閉じます。

構文

ws.close()

close()を呼び出すと、ソケットはCLOSINGを経てCLOSEDに移行し、closeイベントを発生させます。

イベント

WebSocketはEventEmitterを継承しているため、on()やaddListener()などの一般的なイベントリスナーの方式を使用できます。

open

クライアントの接続成功後に発生します。

ws.on('open', () => {
    console.println('connected');
});

close

接続が閉じると発生します。

ws.on('close', () => {
    console.println('closed');
});

message

サーバーからメッセージが届くと発生します。

コールバックは、以下のフィールドを持つイベント形式のオブジェクトを受け取ります。

1
2
3
4
5
6

const { WebSocket } = require('ws');

const ws = new WebSocket('ws://127.0.0.1:8080');
ws.on('message', (evt) => {
    console.println(evt.data);
});

error

接続または送信処理が失敗すると発生します。

ws.on('error', (err) => {
    console.println(err.message);
});

WebSocketServer

WebSocketサーバーを作成し、既存のhttp.Serverに接続します。

構文

new WebSocketServer(options)

主なオプション

• server: 接続するhttp.Serverインスタンス。必須。
• path: 受け付けるWebSocketパス。既定値は/。
• clientTracking: trueの場合、clients集合を保持します。既定値はtrue。
• verifyClient({ origin, req }): ハンドシェイクを受け付けるかどうかを同期的に決定します。falseを返すとリクエストを拒否します。
• handleProtocols(protocols, req): 要求されたサブプロトコルの一覧から、選択する値を返します。

プロパティ

WebSocketServer イベント

• connection(socket, request)
• error(err)
• close()

接続リクエストオブジェクト

connectionイベントのrequestは、Node.jsのIncomingMessageに似たヘルパーオブジェクトです。

主なプロパティ：

• url
• method
• headers
• rawHeaders
• path
• host
• requestUri
• httpVersion
• complete
• remoteAddress
• socket.remoteAddress

主なメソッド：

• query(name)
• getHeader(name)
• hasHeader(name)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

const http = require('http');
const { WebSocketServer } = require('ws');

const server = new http.Server({ network: 'tcp', address: '127.0.0.1:8080' });
const wss = new WebSocketServer({
    server,
    path: '/ws',
    verifyClient: ({ req }) => req.query('token') === 'allow',
    handleProtocols: (protocols) => {
        if (protocols.indexOf('machbase.rpc') >= 0) {
            return 'machbase.rpc';
        }
        return false;
    },
});

wss.on('connection', (socket, request) => {
    console.println(request.path, request.httpVersion, socket.protocol);
    socket.on('message', (event) => {
        socket.send('echo:' + event.data);
    });
});

server.serve();

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const { WebSocket } = require('ws');

const ws = new WebSocket('ws://127.0.0.1:8080');

ws.on('open', () => {
    console.println('websocket open');
    ws.send('test message');
});

ws.on('message', (evt) => {
    console.println(evt.data);
    ws.close();
});

ws.on('close', () => {
    console.println('websocket closed');
});

動作に関する注意

• クライアント接続は、コンストラクター内で非同期に開始します。
• 接続失敗は、errorイベントで通知します。
• 受信メッセージはテキストまたはバイナリですが、JavaScriptのsend()メソッドはテキストメッセージ用に使用してください。
• WebSocketServerは、低水準のupgradeイベントではなく、http.Serverに接続する高水準APIを提供します。
• verifyClient()とhandleProtocols()は同期的に動作します。
• verifyClient()とhandleProtocols()内では、Promiseやawaitに基づく非同期処理は使用できません。
• requestは、Node.jsのIncomingMessageの完全な実装ではなく、url、headers、query()、getHeader()などの主要なフィールド・メソッドを提供するヘルパーオブジェクトです。
• clientTrackingはclients集合を保持しますが、低水準のソケット制御APIは追加しません。
• upgrade、handleUpgrade()、noServerなどの低水準APIは、現在提供していません。