ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ネットワーククライアント

Tip

この記事を読む必要があるのは:出力(outbound)の HTTP / WebSocket リクエストが必要な場合。必要ない場合はスキップしても、他の機能への影響はありません。

ErisPulse は、HTTP リクエスト、WebSocket 接続、および接続プール管理を統合した一貫したネットワーククライアントを提供しています。モジュールやアダプタは、このクライアントを優先的に使用する必要があります。aiohttp / httpx / requests などの外部ライブラリを直接インポートしてはいけません。

概要

ネットワーククライアントの主な機能は以下の通りです:

  • 統一されたインターフェース:get / post / put / delete / patch / request メソッドを提供
  • WebSocketクライアント:ws_connect でクライアントWebSocket接続を確立
  • 自動ログ:すべてのリクエストに対して自動的にログと統計情報を記録
  • ライフサイクル統合:リクエストごとに client.request ライフサイクルイベントがトリガーされ、WS接続は client.ws.connect イベントを発生
  • リトライサポート:自動リトライの回数と間隔を設定可能
  • タイムアウト制御:接続タイムアウトとリクエストタイムアウトを個別に設定
  • 接続プールの再利用:aiohttp.ClientSession に基づく接続プール管理
  • 例外体系:aiohttpの例外をErisPulseの例外(ClientError体系)に自動変換

速習

HTTPリクエスト

from ErisPulse.Core import client

# GETリクエスト
resp = await client.get("https://httpbin.org/get")
data = await resp.json()
print(resp.status)  # 200

# POSTリクエスト
resp = await client.post(
    "https://httpbin.org/post",
    json={"key": "value"},
)
data = await resp.json()

WebSocket接続

from ErisPulse import client   # 2.10+ からのルートインポート(ErisPulse.Core.client は深階層でも互換性あり)

ws = await client.ws_connect("wss://example.com/ws")

async for text in ws.iter_text():
    await ws.send_text(f"Echo: {text}")

出力接続の自動プール登録(2.10+)

ws_connect で確立された接続はデフォルトでフレームワークの接続プールに登録されます(track=False で無効化可能): connections.list(owner=...) で確認でき、その接続にブロードキャストが可能。接続が閉じられたり、リモートが切断された場合、自動的に登録解除されます。 モジュールのアンロード / アダプターの停止時に、フレームワークがその名下のすべての出力接続を一括で閉じるため、リークを防ぎます。

from ErisPulse import client, connections

ws = await client.ws_connect("wss://example.com/ws")
print(ws.id, ws.owner)   # 登録済み:接続IDと所有者

# ownerコンテキストが使用できない場合(例:ツールスレッドのコールバック)は、明示的に所有者を指定し、アンロード時に自動回収されるようにする:
ws2 = await client.ws_connect("wss://example.com/ws2", owner="MyAdapter")

接続プールとブロードキャストの詳細は接続プールとブロードキャストを参照してください。

HttpResponse

すべてのリクエストメソッドは HttpResponse オブジェクトを返します:

from ErisPulse.Core import client

resp = await client.get("https://httpbin.org/get")

resp.status       # int - HTTPステータスコード (例: 200, 404)
resp.reason       # str | None - ステータス説明 (例: "OK")
resp.headers      # レスポンスヘッダー (大文字小文字を区別しない)
resp.content_type # str | None - Content-Type
resp.url          # 最終URL (リダイレクトにより変更される可能性がある)
resp.raw          # 低レベルの元のレスポンスオブジェクト (現在は aiohttp.ClientResponse)

# レスポンスボディの読み取り
body = await resp.read()       # bytes
text = await resp.text()       # str
data = await resp.json()       # JSONを解析
text = await resp.text("gbk")  # 指定したエンコーディング

リクエストメソッド

GET

from ErisPulse.Core import client

resp = await client.get(
    "https://api.example.com/users",
    params={"page": "1", "limit": "10"},
    headers={"Authorization": "Bearer token"},
)

POST

from ErisPulse.Core import client

# JSONリクエストボディ
resp = await client.post(
    "https://api.example.com/users",
    json={"name": "Alice", "age": 30},
)

# フォームリクエストボディ
resp = await client.post(
    "https://api.example.com/login",
    data={"username": "admin", "password": "123"},
)

# バイナリデータ
resp = await client.post(
    "https://api.example.com/upload",
    data=b"raw bytes",
    headers={"Content-Type": "application/octet-stream"},
)

# ファイルアップロード (filesパラメータを使用、aiohttpをインポートする必要はない)
# 形式: {フィールド名: ファイルオブジェクト/bytes/(filename, file)/(filename, file, content_type)}
resp = await client.post(
    "https://api.example.com/upload",
    data={"description": "プロフィール画像"},            # 任意: 通常のフォームフィールドも同時に送信可能
    files={
        "file": ("photo.png", open("photo.png", "rb"), "image/png"),
    },
)

# 簡略化された書き方: ファイルオブジェクトを直接渡す
resp = await client.post(
    "https://api.example.com/upload",
    files={"file": open("photo.png", "rb")},
)

# メモリ内のデータを直接アップロード (ファイルに落とす必要はない)
import io

resp = await client.post(
    "https://api.example.com/upload",
    files={"file": ("data.txt", io.BytesIO(b"file content"), "text/plain")},
)

PUT / DELETE / PATCH

from ErisPulse.Core import client

resp = await client.put("https://api.example.com/users/1", json={"name": "Bob"})
resp = await client.delete("https://api.example.com/users/1")
resp = await client.patch("https://api.example.com/users/1", json={"age": 31})

一般的なrequest

from ErisPulse.Core import client

resp = await client.request(
    "OPTIONS",
    "https://api.example.com/resource",
    headers={"Origin": "https://example.com"},
)

パラメータの説明

HTTPリクエストパラメータ

パラメータ 型 説明
url str リクエストURL
params dict[str, str] クエリパラメータ (オプション)
headers dict[str, str] 追加のリクエストヘッダー (オプション)
data Any リクエストボディ (フォームまたはバイナリデータ) (オプション)
json Any JSONリクエストボディ (オプション)
files dict[str, Any] ファイルアップロードフィールド (オプション、multipart/form-dataを自動構築)
timeout float 今回のリクエストのタイムアウト (秒) (オプション、デフォルト値を上書き)
max_retries int 今回の最大リトライ回数 (オプション、デフォルト値を上書き)

ws_connect パラメータ

パラメータ 型 説明
url str WebSocketサーバーのURL
headers dict[str, str] 追加のリクエストヘッダー (オプション)
heartbeat float ハートビートの間隔 (秒) (オプション)

タイムアウトとリトライ

from ErisPulse.Core import Client

# タイムアウトを設定したクライアントを作成
client = Client(
    timeout=60,           # リクエスト全体のタイムアウト 60秒
    connect_timeout=5,    # 接続のタイムアウト 5秒
    max_retries=3,        # 失敗時に自動リトライ 3回
    retry_delay=2,        # リトライ間隔 2秒
)

# 単一のリクエストでタイムアウトを上書き
resp = await client.get("https://slow-api.example.com/data", timeout=120)

Note

クライアントクラスは 2.8.0 から Client に名前が変更されました(sdk.client の属性名は変更されません);HttpClient は旧名として互換性の別名として残されています。古いコードは変更する必要はありません。

デフォルトヘッダーのカスタマイズ

client = Client(
    headers={
        "Authorization": "Bearer token",
        "X-App-Id": "my-app",
    },
    user_agent="MyBot/1.0",
)

リクエスト統計

from ErisPulse.Core import client

# 統計情報の取得
stats = client.stats
# {"total_requests": 42, "total_errors": 1, "total_bytes_sent": 0, "total_bytes_received": 0}

# 統計情報のリセット
client.reset_stats()

ライフサイクルイベント

HTTPリクエストイベント

リクエストが完了するたびに client.request イベントがトリガーされ、監視に使用できます:

from ErisPulse.Core import lifecycle

@lifecycle.on("client.request")
async def on_request(event_data):
    print(f"{event_data['method']} {event_data['url']} -> {event_data['status']} ({event_data['elapsed']}s)")

WebSocket接続イベント

WebSocket接続が確立されたたびに client.ws.connect イベントがトリガーされます:

from ErisPulse.Core import lifecycle

@lifecycle.on("client.ws.connect")
async def on_ws_connect(event_data):
    print(f"WS接続: {event_data['url']}")

コンテキストマネージャー

# コンテキストマネージャーとして使用し、セッションを自動的に閉じる
async with Client(timeout=30) as client:
    resp = await client.get("https://httpbin.org/get")
    data = await resp.json()

WebSocketクライアント

client.ws_connect() を使用して WebSocketクライアント接続を確立し、ClientWebSocket オブジェクトを返します。クライアントとサーバーの WebSocket は WebSocketConnectionBase 基底クラスを共有し、send/receive/iter のインターフェースは完全に一致します。

基本的な使い方

from ErisPulse.Core import client

ws = await client.ws_connect("wss://example.com/ws", heartbeat=30)

await ws.send_text("Hello")
await ws.send_bytes(b"\x00\x01\x02")
await ws.send_json({"type": "ping"})

メッセージの受信

高レベルメソッド(推奨)

メッセージの種類を自動的にフィルタリングし、切断時に WebSocketDisconnect をスローします:

from ErisPulse.Core import client
from ErisPulse.Core.Bases.errors import WebSocketDisconnect

ws = await client.ws_connect("wss://example.com/ws")

# 単一のメッセージ受信
text = await ws.receive_text()    # str
data = await ws.receive_bytes()   # bytes
obj = await ws.receive_json()     # dict / list

# 繰り返し受信 (切断時に自動的に停止)
async for text in ws.iter_text():
    print(text)

async for data in ws.iter_bytes():
    print(data)

async for obj in ws.iter_json():
    print(obj)

低レベルメソッド

receive() と iter_messages() を使用して、原始メッセージの種類を処理し、TEXT / BINARY / CLOSE / ERROR を区別できます:

from ErisPulse.Core import client
from ErisPulse.Core.Bases.websocket import WSMessage

ws = await client.ws_connect("wss://example.com/ws")

# 単一の原始メッセージ受信
msg = await ws.receive()
# msg.type  -> WSMessage.TEXT / WSMessage.BINARY / WSMessage.CLOSE / WSMessage.ERROR
# msg.data  -> str | bytes | None

# 繰り返し原始メッセージ受信 (CLOSE/ERROR で自動的に停止)
async for msg in ws.iter_messages():
    if msg.type == WSMessage.TEXT:
        print(f"テキスト: {msg.data}")
    elif msg.type == WSMessage.BINARY:
        print(f"バイナリ: {len(msg.data)} bytes")

WSMessage

WSMessage は、低レベルライブラリに依存しない統一された WebSocketメッセージ型です:

属性 型 説明
type str メッセージの種類: WSMessage.TEXT / WSMessage.BINARY / WSMessage.CLOSE / WSMessage.ERROR
data Any メッセージデータ

ClientWebSocket 属性

属性 型 説明
url URL 接続URL
headers Headers レスポンスヘッダー
closed bool 接続が閉じられているか
raw object 低レベルの元のオブジェクト (aiohttp.ClientWebSocketResponse)

ライフサイクルフック

サービス側 WebSocketConnection と同様に、on_disconnect と on_error のコールバックがサポートされています:

from ErisPulse.Core import client

ws = await client.ws_connect("wss://example.com/ws")

@ws.on_disconnect
async def handle_disconnect(ws, reason="unknown"):
    print(f"接続が切断されました: {reason}")

@ws.on_error
async def handle_error(ws, error=""):
    print(f"接続エラー: {error}")

接続の閉じ方

await ws.close(code=1000, reason="正常な切断")

例外体系

ErisPulse は、統一された例外階層を定義し、sdk.client からリクエストを発行すると、aiohttpの例外がErisPulseの例外に自動的に変換されます。

後方互換性:aiohttp.ClientSession を直接使用する古いモジュール/アダプターは完全に影響を受けません。例外変換は sdk.client からリクエストを発行する場合にのみ有効で、aiohttpを直接使用するコードは aiohttp.ClientError などの元の例外をキャッチします。2つの方法は共存可能です。

例外階層

ErisPulseError
├── ClientError                  # HTTP/WSクライアントリクエスト例外の基底クラス
│   ├── ClientConnectionError    # 接続失敗 (DNS解決失敗、接続拒否、ネットワーク不可)
│   ├── ClientTimeoutError       # 接続タイムアウトまたはリクエストタイムアウト
│   └── HTTPStatusError          # HTTP 4xx/5xxステータスコードエラー
└── WebSocketError               # WebSocket例外の基底クラス
    └── WebSocketDisconnect      # WebSocket接続切断 (クライアントとサーバー共通)

例外のキャッチ

from ErisPulse.Core import client
from ErisPulse.Core.Bases.errors import (
    ClientError,
    ClientConnectionError,
    ClientTimeoutError,
    HTTPStatusError,
    WebSocketDisconnect,
    WebSocketError,
)

# HTTPリクエストの例外処理
try:
    resp = await client.get("https://api.example.com/data")
    data = await resp.json()
except ClientConnectionError:
    print("サーバーに接続できません")
except ClientTimeoutError:
    print("リクエストがタイムアウトしました")
except ClientError as e:
    print(f"リクエストが失敗しました: {e}")

# WebSocketの例外処理
try:
    ws = await client.ws_connect("wss://example.com/ws")
    async for text in ws.iter_text():
        await ws.send_text(f"Echo: {text}")
except WebSocketDisconnect as e:
    print(f"接続が切断されました: code={e.code}, reason={e.reason}")
except WebSocketError as e:
    print(f"WebSocketエラー: {e}")

統一的なキャッチ

ClientError を使用して、HTTP/WSクライアントリクエストのすべての例外を統一的にキャッチします:

from ErisPulse.Core.Bases.errors import ClientError

try:
    resp = await client.get("https://api.example.com/data")
except ClientError as e:
    print(f"クライアントエラー: {e}")

HTTPStatusError

リクエスト後にステータスコードをチェックして例外をスローする必要がある場合、手動で使用できます:

from ErisPulse.Core.Bases.errors import HTTPStatusError

resp = await client.get("https://api.example.com/data")
if resp.status >= 400:
    raise HTTPStatusError(resp.status, await resp.text())

アダプターでの使用

アダプターは、グローバルクライアントまたは独自のクライアントインスタンスを使用してプラットフォームAPIリクエストを送信できます:

from ErisPulse.Core import client
from ErisPulse.Core.Bases import BaseAdapter
from ErisPulse.Core.Bases.errors import ClientError

class MyAdapter(BaseAdapter):
    async def call_api(self, endpoint, **params):
        try:
            resp = await client.post(
                f"https://api.platform.com/{endpoint}",
                json=params,
                headers={"Authorization": f"Bearer {self.token}"},
            )
            return await resp.json()
        except ClientError as e:
            self.logger.error(f"API呼び出しに失敗しました: {e}")
            raise

from ErisPulse import sdk を使用して sdk.client を使うことも可能で、効果は同じです。

最適な実践

  1. グローバルクライアントの優先使用:from ErisPulse.Core import client を使用してグローバルシングルトンを取得し、フレームワークによる統一管理と監視を容易にする
  2. 直接 aiohttp のインポートを避ける:client を使用して aiohttp.ClientSession を置き換え、将来の下層実装の変更に伴うコード変更を必要としないようにする。古いコードは直接 aiohttp を使用しても正常に動作し、2つの方法は共存可能
  3. ErisPulse例外体系の使用:sdk.client からのリクエストでは aiohttp.ClientError ではなく ClientError をキャッチし、特定のHTTPライブラリに依存しないコードを保証する。直接 aiohttp を使用する古いコードは影響を受けない
  4. 適切なタイムアウトの設定:APIの応答速度に応じて適切なタイムアウト時間を設定し、長時間のブロッキングを避ける
  5. リトライメカニズムの使用:不安定なAPIにはリトライを有効にして、信頼性を高める
  6. リクエスト統計の監視:sdk.client.stats または client.request ライフサイクルイベントを使用してリクエスト状況を監視する
  7. WebSocketの高レベルメソッドの使用:iter_text / iter_json などの高レベルメソッドを優先し、メッセージの種類を区別する必要がある場合にのみ iter_messages を使用する

関連ドキュメント