WebSocketアクション

WebSocketアクションは、WebSocketのサーバーに接続し、ステップに並べた順にメッセージを送受信して、受け取ったものを返します。

外部アクションとしてmozership/probe-websocket で公開しています。ワークフローが初めて使うときにProbeがダウンロードし、固定したコミットのaction.ymlが示すSHA-256と一致する実行ファイルだけを実行します。Probe v1.17.0以降が必要です。ガードの下で実行するには、またprobe checkでwithを検査するには、v1.21.0以降が必要です。

基本的な構文

ステップでは40文字のコミットSHAでアクションを固定します。各リリース のノートの先頭に、コピーして使うusesの行があります。

steps:
  - name: Subscribe and get an update
    uses: github.com/mozership/probe-websocket@a159244b9ab3f5ec4c61782af1e711bce705c8a8 # v0.1.0
    with:
      url: wss://stream.example.com/ws
      headers:
        Authorization: "Bearer {{vars.token}}"
      messages:
        - send: {type: subscribe, channel: ticker}
        - receive:
            match: {type: subscribed}
        - receive:
            count: 3
            match: {type: update}
    test: res.code == 101 && len(res.messages) == 4 && res.messages[3].data.price > 0

ステップごとに新しく接続し、messagesを順に実行してから閉じます。購読は次のステップに引き継がれないため、一連のやり取りは1つのステップにまとめます。

パラメータ

これら以外のキーをwithに書くと、何も送る前にステップが失敗します。action.ymlはこれらをparamsとして申告しているため、probe checkがそのキーを行番号とともに報告します。

メッセージ

messagesの各エントリには、次のキーのうちちょうど1つを書きます。

receiveには次のオプションがあります。

matchがあるとき、countは一致したメッセージの数です。読み飛ばしたメッセージは残しません。

レスポンスオブジェクト

res.messagesの各メッセージには、次のプロパティがあります。

サーバーがハンドシェイクに応答した後のことは、すべて結果として扱います。そのため、401で拒否されたハンドシェイク、期待したメッセージより前の切断、届かなかったメッセージもテストで確かめられます。メッセージの処理は実行できない最初のエントリで止まり、res.errorがそのエントリを示します。たとえばmessages[1] took 2 of 3 messages: timed out after 10sのようになります。接続の拒否やタイムアウトのように、ハンドシェイクに応答を得られなかったときだけ、ステップをエラーとして失敗させます。

すべてのエントリを終えた時点でサーバーが接続を閉じていなければ、アクションが1000で閉じます。16 MiBを超えるメッセージを受け取ると、やり取りはそこで終わります。

steps:
  - name: The feed sends two updates, then closes
    uses: github.com/mozership/probe-websocket@a159244b9ab3f5ec4c61782af1e711bce705c8a8 # v0.1.0
    with:
      url: wss://stream.example.com/replay
      messages:
        - receive:
            until_close: true
            match: {type: update}
    test: len(res.messages) == 2 && res.close.code == 1000

ガードの下での動作

このアクションは実行のガードを守り、action.ymlでguard: [read-only, allow-host]を申告しています。そのため、どちらのガードの下でも--allow-actionなしで実行します。拒否したステップは、接続する前に種類refusedで失敗します。

• --read-onlyの下では、受信だけのステップを実行します。メッセージがサーバーで何をするかは判断できないため、sendかsend_binaryのエントリを含むステップは拒否します。購読の申し込みのように、何かを送らないとメッセージを返さないサーバーには、--allow-actionで許可が必要です。
• --allow-hostの下では、urlのホストと、ハンドシェイクの各リダイレクト先のホストが、実行が許可するものでなければなりません。ポートのないURLは、スキームの既定のポート（wsは80、wssは443）として扱います。

ガードを参照してください。

関連項目

• 外部アクション - Probeが外部アクションを解決し、照合する仕組み
• HTTP - 通常のHTTPリクエスト
• GraphQL - HTTPでのGraphQLのクエリ