v0.21

WebSocket

はじめに

dframeworkは完全に統合されたソケットレイヤーを備えています。ミドルウェアサポート、コントローラー解決、セッション認証、htmlレンダリングを完備しhttpのRouteアーキテクチャを反映した専用のイベントルーターを提供します。ソケットサーバーはhttpサーバーと並行して自動的に起動するため個別にインストールするものは何もありません。

クライアントサイドではフレームワークのフロントエンドランタイムが接続、イベント送信、イベント待機を管理するグローバルなSocketファサードを公開します。ソケット接続はspaルーターの初期化時に自動的に確立されます。

このソケットレイヤー上に構築されるd-wireおよびd-liveリアクティブ要素の詳細についてはリアクティビティのドキュメントを参照してください。

仕組み

アプリケーションが起動するとフレームワークは/wsパスでhttpサーバーにソケットアップグレードハンドラーをアタッチします。ブラウザがwebsocket接続を開くとフレームワークはアップグレードリクエストから完全なRequestオブジェクトを生成しソケットイベントハンドラー内でクッキー、セッション、ヘッダー、認証済みユーザーへのアクセスを提供します。

受信メッセージはeventプロパティを持つjsonオブジェクトとして期待されます。ソケットルーターはそのイベント名に登録されたハンドラーを検索しhttpルートが処理されるのとまったく同様にミドルウェアパイプラインを通じて実行します。

ソケットイベントの定義

ソケットイベントはルートファイル(通常はroutes/wire.js)で定義します。基盤となるSocketRouterインスタンスに処理を委譲するグローバルなSocketファサードを使用してイベントを登録します。

イベントハンドラー

Socket.on()メソッドは名前付きイベントのハンドラーを登録します。イベント名は慣例としてコロン区切りの名前空間を使用します。

1Socket.on('chat:message', (req) => {
2 const { text } = req.body;
3 return json({ received: true, text });
4});

ハンドラーはhttpルートハンドラーと同じ引数を受け取ります。reqにはreq.body(イベントペイロード)、req.user、req.session、req.cookies、およびすべての標準リクエストメソッドへのアクセスを含む完全なリクエストオブジェクトが含まれます。グローバルレスポンスヘルパー(render()、json()、redirect()、abort()、cookie())はhttpコントローラーと同様にソケットハンドラー内でも機能します。

ハンドラーがいずれのレスポンスメソッドも呼び出さずに値を返した場合フレームワークは自動的にステータスコード200のjsonレスポンスでラップします。

インラインハンドラー

単純なイベントの場合はインライン関数を直接使用できます。

1Socket.on('ping', () => {
2 return json({ pong: true, time: Date.now() });
3});

コントローラーハンドラー

複雑なロジックの場合は使い慣れたController@method文字列表記を使用してコントローラーメソッドを参照します。フレームワークはコントローラーを動的に解決してインポートします。

1Socket.on('chat:message', 'ChatController@onMessage');
2Socket.on('chat:typing', 'ChatController@onTyping');
1export default class ChatController {
2 async onMessage(req) {
3 const { text } = req.body;
4 await Message.create({ user_id: req.user.id, text });
5 Socket.broadcast('chat:new', { text, user: req.user.name });
6 }
7
8 async onTyping() {
9 return json({ typing: true });
10 }
11}

ソケットwireコントローラーはhttpコントローラーと同じcontrollersディレクトリに保存され同じ規約に従います。単一のコントローラーでhttpルートとソケットイベントの両方を処理できます。

ミドルウェア

ソケットイベントはhttpルートと同じミドルウェアシステムをサポートします。ミドルウェア関数はreqとnextを受け取りハンドラーに進むためにnext()を呼び出す必要があります。

インラインミドルウェア

最後の要素がハンドラーでそれ以前のすべての要素がミドルウェア参照である配列を渡すことで単一のイベントにミドルウェアをアタッチできます。

1Socket.on('admin:action', ['AuthMiddleware@requireAuth', 'AdminController@execute']);

グループ化ミドルウェア

Socket.group()メソッドは共有ミドルウェアを複数のイベントに一度に適用します。

1Socket.group({ middleware: 'AuthMiddleware@requireAuth' }, (auth) => {
2 auth.on('profile:update', 'ProfileController@update');
3 auth.on('profile:avatar', 'ProfileController@avatar');
4});

より流暢なapiのためにSocket.middleware()メソッドを使用してミドルウェアをチェーンすることもできます。

1Socket.middleware('AuthMiddleware@requireAuth').group({}, (auth) => {
2 auth.on('dashboard:refresh', 'DashboardController@refresh');
3});

実際のアプリケーションにおけるソケットイベントの例は以下のとおりです。

1import { Socket } from 'dframework';
2
3Socket.on('pair:status', 'auth.AuthController@wire_status').targets(['#qr-box']);
4
5Socket.group({ middleware: ['AuthMiddleware@requireAuth'] }, (auth) => {
6 auth.on('follow:toggle', 'app.FriendsController@toggle').targets(['#leaderboard-list', '#friends-list-container']);
7 auth.on('friends:tab', 'app.FriendsController@friends_tab').targets(['#friends-list-container']);
8 auth.on('playback:heartbeat', 'app.PlaybackController@handleHeartbeat');
9});

イベントへの応答

ソケットハンドラーはhttpコントローラーで利用可能なものと同じグローバルレスポンスヘルパーを使用します。すべてのレスポンスはソケット接続経由で配信されます。

HTMLのレンダリング

render()ヘルパーはビューテンプレートをコンパイルし結果のhtmlをクライアントに送信します。フレームワークはページ全体をリフレッシュすることなくクライアントサイドの指定されたターゲット要素にhtmlをモーフィングします。

1Socket.on('feed:refresh', async () => {
2 const posts = await Post.latest(20);
3 return render('partials.feed', { posts });
4});

レンダリングされたhtmlはd-wire:renderイベントとして送信されます。クライアントサイドのランタイムがそれを解析しフォーカス状態、入力値、スクロール位置を保持したままターゲットdom要素をモーフィングします。

フレームワークは不要なdom更新を防ぐためにペイロードハッシュを使用します。レンダリングされたhtmlがそのターゲットの前回レンダリングと同じハッシュを生成する場合更新は静かにスキップされます。

JSONの送信

json()ヘルパーはjsonペイロードをクライアントに返送します。

1Socket.on('stats:fetch', async () => {
2 const count = await User.count();
3 return json({ users: count });
4});

リダイレクト

redirect()ヘルパーはリダイレクト指示をクライアントに送信します。ブラウザは指定されたurlに遷移します。

1Socket.on('session:expired', () => {
2 return redirect('/login');
3});

処理の中断

abort()ヘルパーはステータスコードとオプションのメッセージを含むエラーレスポンスを送信します。

1Socket.on('admin:action', (req) => {
2 if (!req.user?.isAdmin) {
3 return abort(403, 'forbidden');
4 }
5});

デフォルトのステータスメッセージは400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、429 Too Many Requests、500 Internal Server Errorです。

クッキー

cookie()ヘルパーを使用してソケットハンドラーからクッキーを設定できます。クッキーはレスポンスとともに送信されクライアントサイドのランタイムがブラウザに適用します。

1Socket.on('theme:set', (req) => {
2 cookie('theme', req.body.theme, { path: '/', sameSite: 'Lax' });
3 return json({ ok: true });
4});

ターゲット制限

targets()チェーンメソッドを使用してイベントがレンダリングを許可されるdomターゲットセレクターを制限できます。クライアントが許可リストに含まれていないターゲットを送信した場合イベントは静かに拒否されます。

1Socket.on('sidebar:update', 'SidebarController@render').targets('#sidebar');
2Socket.on('panel:refresh', 'PanelController@render').targets(['#left-panel', '#right-panel']);

ブロードキャスト

Socket.broadcast()メソッドは接続されているすべてのwebsocketクライアントにイベントを送信します。オプションで特定の接続(通常は送信者)を除外できます。

1Socket.on('chat:send', (req, res, ws) => {
2 const message = { text: req.body.text, user: req.user.name };
3 Socket.broadcast('chat:new', message, ws);
4 return json({ sent: true });
5});

第3引数はブロードキャストから除外するwebsocket接続です。現在のwsを渡すことで送信者が自身のメッセージを受信するのを防ぐことができます。

jobs/内のバックグラウンドジョブからSocket.broadcast()およびSocket.setState()を直接呼び出すこともできます。ワーカースレッドはredisのような外部ブローカーを必要とすることなくソケットイベントをメインプロセスに自動的にリレーします。

1// inside any background job
2Socket.broadcast('task:complete', { taskId: 42 });
3Socket.setState('#task-status', { done: true });

ターゲット配信

全員にブロードキャストするのではなく特定のクライアントにメッセージを送信する必要がある場合dframeworkはSocketファサード上で対象指定メソッドを提供します。接続は接続時および認証済みソケットリクエスト中に認証済みユーザーのIDとセッションIDを自動的に追跡します。

特定ユーザーへの送信

Socket.toUser()メソッドはユーザーIDまたはユーザーモデルインスタンスに属するすべてのオープンなwebsocket接続にイベントを送信します。

1// using numeric user id
2Socket.toUser(42, 'notification:new', { text: 'you received a payment' });
3
4// using model instance
5Socket.toUser(user, 'notification:new', { text: 'profile updated' });
6
7// push component state directly
8Socket.toUserState(42, '#cart-count', { count: 3 });
9
10// fluent chaining syntax
11Socket.toUser(42).emit('notification:new', { text: 'order shipped' });
12Socket.toUser(42).setState('#cart-count', { count: 3 });

複数ユーザーへの送信

Socket.toUsers()メソッドはユーザーIDまたはユーザーモデルインスタンスのリストにイベントをディスパッチします。

1// dispatch event to multiple users
2Socket.toUsers([1, 2, 3], 'room:update', { active: true });
3
4// push component state directly to multiple users
5Socket.toUsersState([1, 2, 3], '#status', { online: true });
6
7// fluent chaining syntax
8Socket.toUsers([1, 2, 3]).emit('room:update', { active: true });
9Socket.toUsers([1, 2, 3]).setState('#status', { online: true });

セッションへの送信

Socket.toSession()メソッドは特定のセッションIDに一致するすべての接続を対象とします。

1// dispatch event to specific session
2Socket.toSession(sessionId, 'session:revoked', { reason: 'logged in from new device' });
3
4// push component state directly to specific session
5Socket.toSessionState(sessionId, '#auth-panel', { authenticated: false });
6
7// fluent chaining syntax
8Socket.toSession(sessionId).emit('session:revoked', { reason: 'logged in from new device' });
9Socket.toSession(sessionId).setState('#auth-panel', { authenticated: false });

ダイレクトソケットターゲット

Socket.to()ヘルパーはwebsocketインスタンスを直接対象とします。

1Socket.to(ws).emit('direct:message', { ok: true });
2Socket.to(ws, 'direct:message', { ok: true });
3Socket.to(ws).setState('#chat-box', { focused: true });

マルチガードターゲット

アプリケーションがconfig/auth.jsで複数の認証ガード(例えばweb、admin、partner)を定義している場合接続は設定されたすべてのガードにわたってIDを自動的に追跡します。

Socket.toUser(id)は任意のガード(またはデフォルトガード)上でそのユーザーIDに一致する接続に配信します。特定のガードを明示的に対象とするにはSocket.guard()を使用してディスパッチのスコープを制限するか直接ガードメソッドを呼び出すことができます。

1// target single user or multiple users through the guard scope
2Socket.guard('admin').toUser(5, 'admin:alert', { text: 'server restart scheduled' });
3Socket.guard('admin').toUsers([5, 6], 'admin:alert', { text: 'maintenance incoming' });
4
5// fluent state updates scoped by guard
6Socket.guard('admin').toUser(5).setState('#admin-panel', { status: 'maintenance' });
7Socket.guard('admin').toUsers([5, 6]).setState('#admin-panel', { status: 'maintenance' });
8
9// direct guard dispatch methods
10Socket.toGuardUser('admin', 5, 'admin:alert', { text: 'server restart scheduled' });
11Socket.toGuardUsers('admin', [5, 6], 'admin:alert', { text: 'server restart scheduled' });
12
13// direct guard component state updates
14Socket.toGuardUserState('admin', 5, '#admin-panel', { status: 'maintenance' });
15Socket.toGuardUsersState('admin', [5, 6], '#admin-panel', { status: 'maintenance' });
16
17// fluent chaining on direct guard methods
18Socket.toGuardUser('admin', 5).emit('admin:alert', { text: 'server restart scheduled' });
19Socket.toGuardUser('admin', 5).setState('#admin-panel', { status: 'maintenance' });
20Socket.toGuardUsers('admin', [5, 6]).emit('admin:alert', { text: 'server restart scheduled' });
21Socket.toGuardUsers('admin', [5, 6]).setState('#admin-panel', { status: 'maintenance' });

ユーザー接続の取り消し

Socket.revokeUser()メソッドはすべてのガードまたは特定のガードにわたってユーザーのアクティブなソケット接続を即座に認証解除します。

1// revoke user on all guards
2Socket.revokeUser(userId);
3
4// revoke user only on a specific guard
5Socket.revokeUser(adminId, 'admin');

すべての対象指定メソッド(toUser、toUserState、toUsers、toUsersState、toSession、toSessionState、to、guard、toGuardUser、toGuardUserState、toGuardUsers、toGuardUsersState、revokeUser)はhttpコントローラー、wireハンドラー、バックグラウンドジョブ全体でシームレスに動作します。

Socketファサード

グローバルのSocketはすべてのメソッド呼び出しをアプリケーションのSocketRouterインスタンスに委譲するプロキシファサードです。アプリケーションの初期化後にグローバルに利用可能でありフレームワークからインポートすることもできます。

1import { Socket } from 'dframework';

ファサードはすべてのメソッドを公開します: on()、group()、middleware()、broadcast()、setState()、to()、toUser()、toUserState()、toUsers()、toUsersState()、toSession()、toSessionState()、guard()、toGuardUser()、toGuardUserState()、toGuardUsers()、toGuardUsersState()、revokeUser()、liveNotify()。

クライアントサイドでの使用

フレームワークのフロントエンドランタイムはwebsocket接続を管理するグローバルなSocketオブジェクトをwindow上に提供します。

接続

websocket接続はspaルーターの初期化時に自動的に確立されます。手動で接続することもできます。

1await Socket.connect();

接続urlはデフォルトで/wsでありセキュアなページでは自動的にwss:をセキュアでないページではws:を使用します。完全なuriは現在のページのlocation.hostから構築されます。

Socketフロントエンドファサードはスコープ付きスクリプト(type="text/dspa"、インラインページスクリプト、およびd-spa-scope付きモジュールスクリプト)内でのみ利用可能です。スコープコンテキスト外では利用できません。

イベントの送信

サーバーにイベントを送信するにはSocket.emit()を使用します。データペイロードとオプションのターゲットセレクターを渡すことができます。

1Socket.emit('chat:send', { text: 'hello world' });
1Socket.emit('dashboard:refresh', { filter: 'today' }, '#dashboard');

ターゲットが指定されている場合サーバーハンドラーのレンダリング出力はその特定のdom要素にモーフィングされます。

イベントの待機

サーバーからプッシュされたイベントを受信するにはクライアントサイドでSocket.on()を使用します。

1Socket.on('chat:new', (data) => {
2 appendMessage(data.text, data.user);
3});

ブロードキャストイベントの場合コールバックはデータペイロードを直接受け取ります。

オリジン保護

IMPORTANT

ソケットサーバーはクロスサイトwebsocketハイジャック(cswsh)攻撃を防ぐためすべてのアップグレードリクエストの`Origin`ヘッダーを`APP_URL`に対して検証します。不一致のオリジンからの接続は即座に拒否されます。

local環境では設定されたurlに関係なくlocalhostおよび127.0.0.1からの接続が許可されます。

デバッグモード

デバッグモードが有効なlocal環境ではソケットルーターはすべてのレスポンスに詳細なタイミング情報とクエリ情報を付加します。クライアント側のdebugbarには各ソケットイベントの経過時間、実行されたクエリ、リクエストヘッダーが表示されhttpリクエストと同等の可視性が提供されます。