nats-design-subject

NATS サブジェクト階層の設計

ワイルドカードを使ってサブスクライバーが効率よくたどれるサブジェクトアーキテクチャを、適切なセグメント順序、アカウントを考慮したテナント分離、および拡張性を備えて設計します。

インタビュー段階

以下のすべてがすでに明確になっている場合は、インタビューを省略します。

• メッセージングパターン（pub/sub、リクエスト／リプライ、ストリーミング）
• マルチテナントの要件（シングル／マルチテナント、規模の要件）
• セキュリティ要件（認可、テナント分離）
• 永続化の要件（JetStream とコア NATS のどちらを使うか）

次の場合は必ずインタビューします。：既存のサブジェクトを移行する場合（まずアンチパターンの監査が必要です）

質問

1. 範囲 — 「新規設計ですか。それとも既存のサブジェクトを移行しますか？」

   • 影響：移行の場合は、まずアンチパターンの監査が必要です（references/anti-patterns.md を参照）

2. マルチテナントと規模 — 「次のどれが必要ですか？（A）シングルテナント、（B）アカウント単位のテナント分離、（C）サブジェクトプレフィックスを使った共有アカウント、（D）リージョン／シャードを伴う大規模構成」

   • 影響：テナント ID を NATS アカウント境界、サブジェクト、またはその両方のどこに置くかが決まります

3. メッセージングパターン — 「どのパターンを使いますか？（A）Pub/Sub のみ、（B）リクエスト／リプライ、（C）ストリーミング／JetStream、（D）すべて／混在」

   • 影響：JetStream ではストリームを考慮したサブジェクト設計が必要です。リクエスト／リプライには独自の慣例があります

4. セキュリティ — 「アカウントレベルの分離、サブジェクトベースの認可、またはその両方が必要ですか？」

   • 影響：アカウント境界、エクスポート／インポート、テナントプレフィックス、権限境界が決まります

5. 永続化 — 「JetStream による永続化が必要ですか。それともコア NATS のみでよいですか？」

   • 影響：ストリーム／コンシューマーのサブジェクト設計と保持に関する考慮事項が決まります

---

使用する場合

• 新しい NATS メッセージングシステムを設計する
• アカウントを考慮したマルチテナントのサブジェクト分離を計画する
• デバイスのテレメトリーやイベントストリームを整理する
• マイクロサービス間のリクエスト／リプライパターンを設定する
• イベントソーシングシステムのイベントサブジェクト構造を定義する
• エージェント間メッセージングを備えたエージェント型 AI プラットフォームを構築する

使用しない場合

• NATS サーバーまたはクラスターの設定（サブジェクト設計ではなく、インフラストラクチャの設定）
• NATS クライアントコードや接続ロジックの記述（アーキテクチャではなく、実装）
• NATS と他のメッセージングシステムの選択（技術の評価）
• 既存の NATS 接続やパフォーマンスの問題のデバッグ

---

ワークフロー

1. ドメイン境界を特定する

関係するすべての NATS アカウント境界とビジネスドメインを列挙します。厳密なマルチテナント構成では、まずテナントごとにアカウントを割り当て、その後、各アカウント内でドメインを先頭に置いた短いサブジェクトを設計します。

アカウントを意図的に利用できない場合、またはテナントの由来を保持する必要がある共有／プラットフォーム用の領域を設計する場合に限り、サブジェクトのテナントプレフィックスを使用します。

2. パターンを選択する

ユーザーのシナリオに合うパターンを選択します。

ユースケース	パターン	例
シンプルなドメイン	{domain}.{action}.{scope}	orders.created.us-west
マルチリージョン	{domain}.{action}.{region}.{id}	devices.telemetry.us-east.sensor-456
マルチテナント SaaS	テナントごとにアカウントを作成し、サブジェクトは {domain}.{action}.{id}	アカウント acme-corp 内の analytics.processed.report-123
共有アカウントの代替案	{tenant}.{domain}.{action}.{id}	acme-corp.analytics.processed.report-123
マルチテナント AI	テナントごとにアカウントを作成し、サブジェクトは agents.{action}.{agent-id}.{task-id}	アカウント tenant-abc 内の agents.task-assigned.agent-xyz.task-123
リクエスト／リプライ	{service}.request / {service}.reply	orders.request / orders.reply
イベントソーシング	{aggregate}.{action}.v{version}.{id}	orders.order.created.v1.order-123

サブスクライバーのパスやスケーリングに関するガイダンスを含む各パターンの詳細は、references/patterns.md をご覧ください。

3. セグメントを戦略的に並べる

選択したアカウント内で、サブジェクトのセグメントを左から右へ並べる際は、次のルールを適用します。

• 広い範囲から具体的な範囲へ：ドメイン → アクション → スコープ → 識別子
• カーディナリティの低い値を左、高い値を右へ：リージョン（値が少ない）を ID（数百万の値）より前に配置します
• ID や UUID をアクションより前に配置しないでください

✓ GOOD: orders.created.us-west.order-123
                            ↑          ↑
                       low-card    high-card

✗ BAD:  orders.order-123.us-west.created
                ↑
           high-card early (kills wildcard filtering)

これが重要な理由：NATS のワイルドカードマッチングは左から右へスキャンします。カーディナリティの高い値を左側に置くと、サブスクライバーは何千もの ID にマッチさせる必要がある非効率な orders.*.us-west.created パターンを使うことになります。

よくある順序の誤りと移行戦略については、references/anti-patterns.md をお読みください。

4. サブスクライバーのパスを計画する

各ドメインについて、サブスクライバーがどのようにフィルタリングするかを記述します。

orders.>                    → All order events
orders.created.>            → All order creation events
orders.created.us-west.>    → Orders created in US West
orders.created.us-west.order-123 → Specific order

パブリッシャーではなく、サブスクライバー向けにサブジェクトを設計してください。整理方法を決めるのはサブスクライバーです。適切な階層にすれば、ワイルドカードを使って効率的にフィルタリングできます。

5. セキュリティモデルを設計する（マルチテナントの場合）

ユーザーがテナント分離やロールベースのアクセスを必要とする場合：

• テナント分離には NATS Accounts を優先します。各テナントに独自のサブジェクト名前空間を割り当てます
• テナント間の可視性を前提とせず、アカウント間のフェデレーションにはエクスポート／インポートを使用します
• 共有アカウントの代替策やプラットフォームの集約用サーフェスに限り、サブジェクトにテナント ID を使用します
• 管理者／プラットフォーム用サブジェクトをユーザー操作用サブジェクトから分離します（_admin.> またはプラットフォームアカウントのサブジェクト）
• サービスごとに最小権限のアクセス許可を適用します

アカウントベースのテナント構成、認可パターン、テナント分離の例については、references/security.md をお読みください。

6. JetStream ストリームを設計する（永続化が必要な場合）

ユーザーが JetStream を必要とする場合：

• JetStream のストリーム、コンシューマー、KV バケットをアカウントスコープのリソースとして扱います
• トポロジーが同一の場合は、テナントアカウント間でストリーム名／KV 名を再利用します
• 各テナントアカウント内にドメインごとに 1 つのストリームを使用します
• 共有アカウント内のテナントごとのストリームは、代替策としてのみ使用します
• きめ細かなルーティングにはコンシューマーフィルターを使用します
• アカウントとドメインの保持期間制限を設定します（金融：年単位、テレメトリー：日単位）
• サブジェクトセグメントは 4～6 個に抑えます。階層を深くするのではなく、コンシューマーフィルターを使用します

ストリーム設計、コンシューマーパターン、コア NATS からの移行については、references/jetstream.md をお読みください。

7. 検証して出力を作成する

次のテンプレートを使って設計を提示します。

# NATS Subject Architecture: [System Name]

## Domain Overview
[Describe the domains and their interactions]

## Subject Hierarchy

### Domain: [Name]
- `domain.action.{scope}.{id}`
- `domain.action.{scope}.{id}`

Subscriber paths:
- `domain.>` — All events
- `domain.action.>` — Specific action

[Repeat for each domain]

## Multi-Tenancy Model
[NATS Accounts, exports/imports, or shared-account subject prefixes]

## Security Model
[Authorization rules per role/service, if applicable]

## JetStream Streams
[Account-scoped stream definitions and consumer filters, if applicable]

## Quality Validation
[Run checklist below]

出力例

# NATS Subject Architecture: IoT Smart Building Platform

## Domain Overview

Smart building system with 10,000+ sensors across multiple regions sending temperature, humidity, and occupancy data. Needs real-time monitoring, regional aggregation, and alerting.

## Subject Hierarchy

### Domain: Devices
- `devices.telemetry.{region}.{device-id}.{metric}`
- `devices.telemetry.us-west.sensor-456.temperature`
- `devices.telemetry.us-west.sensor-456.humidity`
- `devices.telemetry.eu-central.sensor-789.occupancy`

Subscriber paths:
- `devices.telemetry.>` — All telemetry (global monitoring)
- `devices.telemetry.us-west.>` — Regional dashboard (US West)
- `devices.telemetry.>.>.temperature` — All temperature readings

### Domain: Alerts
- `alerts.triggered.{severity}.{region}.{device-id}`
- `alerts.triggered.critical.us-west.sensor-456`

Subscriber paths:
- `alerts.triggered.critical.>` — Critical alerts only
- `alerts.triggered.>.us-west.>` — Regional alert dashboard

## Multi-Tenancy Model

Not applicable (single organization)

## Security Model

- Building operators: `devices.telemetry.>`, `alerts.>` (subscribe only)
- Alert service: `alerts.>` (publish + subscribe)
- Admin: `>` (full access)

## JetStream Streams

Stream: `telemetry-us-west`
  Subjects: `devices.telemetry.us-west.>`
  Retention: 24h (high volume)
  
Stream: `alerts`
  Subjects: `alerts.>`
  Retention: 30d

## Quality Validation

✓ All segments follow broad-to-specific order
✓ Device IDs at rightmost position
✓ Naming consistent (lowercase, hyphens)
✓ Regional filtering efficient
✓ 4 segments (within 4-6 limit)

マイクロサービス、IoT、SaaS、イベントソーシング、エージェント型 AI プラットフォームにわたる実際の活用例については、references/use-cases.md をお読みください。

---

クイックスタート（シンプルなケース）

マルチテナントではないシンプルな単一ドメインシステムを設計する場合：

1. パターン 1（シンプルなドメイン）を使用します：{domain}.{action}.{id}
2. リファレンスを読み飛ばし、上記のワークフローに従います
3. 例：orders.created.order-123、payments.authorized.payment-456

マルチリージョン、マルチテナント、またはイベントソーシングが必要な場合は、完全なワークフローに進み、必要に応じてリファレンスをお読みください。

---

リファレンスの参照方法

このスキルには、詳細なリファレンスドキュメントが 5 つ含まれています。ワークフローの各ステップで必要に応じてお読みください。

• patterns.md：最初のパターンを選択するときに読みます（ステップ 2）
• anti-patterns.md：既存のサブジェクトを移行または監査するときに読みます
• security.md：マルチテナント／認可が必要なときに読みます（ステップ 5）
• jetstream.md：永続化が必要なときに読みます（ステップ 6）
• use-cases.md：ドメインごとの完全な実例を確認するときに読みます

最初にすべてのリファレンスを読む必要はありません。ワークフローに応じて段階的に活用してください。

---

命名規則

• すべて小文字で、ハイフンを使用します：orders.created ✓
• アンダースコアは使用しません：orders_created ✗
• 大文字と小文字を混在させません：Orders.Created ✗
• セグメントは最大 4～6 個に抑えます

---

品質チェックリスト

• すべてのセグメントが大分類から小分類への順序（{domain}.{action}.{scope}.{id}）に従っている
• アクション／スコープのセグメントより前に UUID／ID フィールドがない
• 命名規則が一貫している（すべて小文字、ハイフンを使用し、アンダースコアは使用しない）
• 各ドメインのサブスクライバー用ワイルドカードパスが記載されている
• 6 セグメントを超えるサブジェクトがない
• マルチテナントの境界が明確である（テナントごとのアカウント、共有アカウントのプレフィックスへのフォールバック、またはその両方）
• 管理者／監視アクセス用のセキュリティサブジェクトが定義されている
• 競合するパターンがない（例：orders.created.123 と orders.123.created）
• 高カーディナリティに関する判断が記録されている（ID の配置を選択した理由）

設計のテスト

デプロイ前にサブジェクト階層を検証します：

# Start local NATS server
nats-server -D

# Test subscriber wildcards
nats sub "orders.>"                    # Should match all order subjects
nats sub "orders.created.>"            # Should match only creations
nats sub "orders.created.us-west.>"    # Should match region-specific

# Test publishing
nats pub "orders.created.us-west.order-123" "test message"

# Verify JetStream streams (if applicable)
nats stream info orders-stream
nats consumer info orders-stream order-consumer

既存のデプロイでは、現在のサブジェクトを監査します：

# List active subjects (requires monitoring enabled)
nats server report jetstream

# Check subject permissions
nats server check connection --account <account-name>

リファレンスドキュメント

• パターン：サブスクライバーパスとスケーリングのガイダンスを含む 6 つの階層パターン
• アンチパターン：検出方法、修正方法、移行戦略を含む一般的な誤り
• セキュリティとマルチテナンシー：認可パターンとテナント分離
• JetStream の設計：ストリームフィルター、コンシューマーサブジェクト、保持ポリシー
• ユースケース：マイクロサービス、IoT、SaaS、イベントソーシング、エージェント型 AI の完全な例