クライアントフローマップ

クライアントフローマップ

目的: jsonlog を統合するクライアントに期待される上位シーケンスを定義すること。

主要フロー

1. auth.jsonlog.com で認証をブートストラップし、アカウント単位ルート用の Bearer トークンを取得する。
2. POST /log（公開またはチャネル指定）へ JSON ボディでログを送信する。
3. GET /ws アップグレードで、必要に応じて cid / level フィルタを付けてリアルタイムログを受信する。
4. HTTP / WebSocket の読み書きで、アカウントクレーム（acc）によるプライベートチャネルアクセス制御を行う。
5. POST /query で耐久 SSTable ファイルを探索し、GET /query/stats で集計を確認する。
6. GET /health と GET /stats でサービスの可用性と書き込み経路状態を監視する。

エンドポイント分類

• 取り込み:
  • POST /log
  • GET /log
• ストリーミング:
  • GET /ws（WebSocket アップグレードエンドポイント）
• クエリ:
  • POST /query
  • GET /query/stats
• サービス:
  • GET /health
  • GET /stats
• ドキュメント:
  • GET /openapi.json
  • GET /docs
  • GET /swagger

セキュリティ要件

• JWT 署名検証はデフォルトで https://auth.jsonlog.com/.well-known/jwks.json?client_id=cid_jsonlog を使用します。
• /query ルートは Bearer 認証が必要で、JWT の acc によりアカウント分離を行います。
• プライベートチャネルアクセスは JWT の acc がチャネル所有アカウントと一致する必要があります。
• 不正なプライベートチャネル読み取りはチャネル探索を防ぐため 404 を返します。
• 認証なし利用はローカル開発専用で、本番デフォルトにしてはいけません。