diff --git a/README.md b/README.md index f87adec..e6ad67b 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,43 @@ # UsageGate -Usage-aware, multi-tenant API gateway built in Rust - -UsageGate is a lightweight developer-focused API gateway that provides: - • API key authentication - • Multi-tenant isolation - • Usage metering - • Rate limiting - • Quota enforcement - -Designed as a foundation for usage-based billing systems and AI-ready APIs. - -# 🚀 Overview - -Modern SaaS and AI APIs require: - • Secure API exposure - • Fine-grained usage tracking - • Rate limiting and abuse protection - • Flexible billing integration - -However, existing solutions are often: - • Overly complex (DevOps-heavy) - • Fragmented across multiple tools - • Not optimized for developer-first usage - -UsageGate aims to solve this by providing a simple, extensible, and high-performance gateway layer. - -⸻ - -# 🧩 Core Features - -1. API Key Authentication - • Header-based API key validation - • Key rotation & revocation (planned) - • Tenant-aware authentication - -⸻ - -2. Multi-Tenant Architecture - • Tenant isolation at request level - • Per-tenant configuration - • Plan-based access control - -⸻ - -3. Usage Metering - • Request-level usage tracking - • Endpoint-based aggregation - • Tenant/API key granularity - -⸻ - -4. Rate Limiting - • Per-tenant / per-key rate limiting - • Sliding window (initially fixed window) - • Redis-backed counters - -⸻ - -5. Quota Enforcement - • Monthly usage limits - • Plan-based quota control - • Over-quota request rejection - -⸻ - -6. Middleware-based Architecture - • Auth middleware - • Tenant resolution middleware - • Metering middleware - • Rate-limiting middleware - -⸻ - -# 🏗 Architecture (Phase 1) +## Conncept / コンセプト +クライアントサーバーとAPIサーバーの前に挟むだけで公開APIのビジネスモデルを展開できる。 +*Just place it between your client and API server to instantly deploy a public API business model.* + +### What's focus on ? / どんな悩みを解決するか +「従量課金性のAPIサービスを開発したい」「自社SaaSに公開API機能を搭載したい」という開発者体験を改善するためのツールです。 +*This is a tool to improve the developer experience for those who want to build pay-per-use API services or add a public API feature to their own SaaS product.* + +APIGateWayとしてサーバーを立ててもらうことで、安全でハイパフォーマンスな公開APIビジネスを構築することができます。 +*By running this as an API Gateway, you can build a secure and high-performance public API business.* + + +### What kind of functions / どんな機能を提供するか？ +- エンドユーザー向けにAPI Keyの発行・管理機能 + *API Key issuance and management for end users* +- マルチテナント管理 + *Multi-tenant management* +- API Keyの認証認可機能 + *API Key authentication and authorization* +- 公開APIの従量設定・制御機能(クォータ・レート制限) + *Usage configuration and control for public APIs (quota and rate limiting)* +- 不正利用防止 + *Fraud and abuse prevention* +- ユーザーごとの毎月の従量確認ダッシュボード + *Monthly usage dashboard per user* + +# 🏗 Architecture / アーキテクチャ Single-node architecture (monolith for simplicity and performance): -Axum (Rust) -├── Auth Middleware -├── Tenant Middleware -├── Metering Middleware -├── Rate Limit Middleware -├── API Handlers -│ -├── PostgreSQL (persistent data) -└── Redis (rate limit & counters) +Axum（Rust） +├── 認証ミドルウェア *(Authentication middleware)* +├── テナント解決 *(Tenant resolution)* +├── Usage計測 *(Usage metering)* +├── レート制限 *(Rate limiting)* +├── APIハンドラ *(API handler)* +├── PostgreSQL（永続データ） *(PostgreSQL - persistent data)* +└── ValKey（カウンタ・レート制限） *(ValKey - counter & rate limiting)* ⸻ @@ -96,7 +48,7 @@ Axum (Rust) • Async runtime: Tokio • Database: PostgreSQL • Cache / Rate limit: Redis - • Containerization: Docker (optional) + • Containerization: Docker ⸻ @@ -107,45 +59,9 @@ Authentication Header: x-api-key: -⸻ - -Core Endpoints - -Health - -GET /health - - -⸻ - -Proxy (example) - -POST /proxy/{service} - - -⸻ - -Admin APIs (simplified) - -Create Tenant - -POST /admin/tenants - -Create API Key - -POST /admin/api-keys - -Get Usage - -GET /admin/usage - - -⸻ - # 🧪 Testing Strategy • Integration tests (API behavior) • Concurrency tests (rate limit & metering) - • Tenant isolation tests • Failure scenario tests ⸻ @@ -158,135 +74,15 @@ GET /admin/usage ⸻ -# 🧠 Why Rust? - -UsageGate is not just an API service. -It is a high-throughput, correctness-critical gateway layer. - -Rust is chosen for the following reasons: - -⸻ - -## 1. Safe Concurrency - -UsageGate handles: - • Concurrent requests - • Shared state (rate limits, usage counters) - • Multi-tenant isolation - -Rust’s ownership model prevents: - • Data races - • Invalid memory access - • Unsafe shared state mutations - -⸻ - -## 2. High Performance - -Gateway layers require: - • Low latency - • High throughput - • Efficient async I/O - -Rust provides: - • Zero-cost abstractions - • No garbage collection pauses - • Efficient async execution via Tokio - -⸻ - -## 3. Strong Type Safety - -Critical domain concepts: - • TenantId - • ApiKeyId - • Plan - • UsageUnit - • Quota - -are enforced at compile time, reducing runtime errors. - -⸻ - -## 4. Explicit Error Handling - -UsageGate must handle failures such as: - • Invalid API keys - • Rate limit exceeded - • Quota exceeded - • Downstream failure - -Rust’s Result type ensures all failure paths are explicitly handled. - -⸻ - -## 5. Reliable Middleware Layer - -All requests pass through: - • Authentication - • Metering - • Rate limiting - -Rust enables writing robust and predictable middleware pipelines. - -⸻ - # 🔮 Roadmap -## Phase 1 (MVP) - • API key auth - • Usage tracking - • Rate limiting - • Basic tenant support - -⸻ - -## Phase 2 - • Plan management - • Webhook events - • Observability improvements - -⸻ - -## Phase 3 - • Stripe integration - • Usage-based billing - • Subscription management - -⸻ +https://github.com/users/ttatsato/projects/3 -## Phase 4 - • Model Context Protocol support - • AI agent integration - • Tool-level metering - -⸻ - -# 💡 Use Cases - • SaaS APIs with usage-based billing - • AI APIs (LLM / tool APIs) - • Internal API governance - • Developer platforms - -⸻ # 🧭 Positioning -UsageGate is: - • Not a full infrastructure gateway like enterprise solutions - • Not just an analytics tool - -It is: - 👉 A developer-first, usage-aware API gateway for modern SaaS and AI applications -⸻ - -# 📌 Status - -🚧 Work in progress (Phase 1) - -⸻ # 🧾 License diff --git a/docs/README.ja.md b/docs/README.ja.md deleted file mode 100644 index c6aefef..0000000 --- a/docs/README.ja.md +++ /dev/null @@ -1,305 +0,0 @@ -UsageGate - -従量課金対応・マルチテナント対応のAPIゲートウェイ（Rust製） - -UsageGateは以下の機能を提供する、開発者向けの軽量APIゲートウェイです。 - • APIキー認証 - • マルチテナント管理 - • 使用量（Usage）計測 - • レート制限 - • クォータ制御 - -SaaSの従量課金やAI API公開の基盤として設計されています。 - -⸻ - -🚀 概要 - -現代のSaaSやAI APIでは、以下が求められます： - • 安全なAPI公開 - • 利用量の正確なトラッキング - • レート制限・不正利用防止 - • 柔軟な課金連携 - -しかし既存のソリューションは： - • 構成が複雑（DevOps寄り） - • 複数ツールに分散している - • 開発者体験が悪い - -UsageGateはこれを解決するために、 -シンプルかつ高性能なAPI基盤として設計されています。 - -⸻ - -🧩 コア機能 - -1. APIキー認証 - • ヘッダーによるAPIキー認証 - • テナント単位での認証管理 - • キーのローテーション（将来対応） - -⸻ - -2. マルチテナント対応 - • リクエスト単位でのテナント分離 - • テナントごとの設定管理 - • プラン単位の制御 - -⸻ - -3. Usage計測 - • リクエスト単位でのカウント - • エンドポイント単位での集計 - • テナント / APIキー単位の集計 - -⸻ - -4. レート制限 - • テナント単位・APIキー単位で制御 - • シンプルなウィンドウベース制御（MVP） - • Redisによるカウンタ管理 - -⸻ - -5. クォータ制御 - • 月次利用量制限 - • プラン単位での制御 - • 制限超過時のリクエスト拒否 - -⸻ - -6. ミドルウェア構成 - • 認証ミドルウェア - • テナント解決ミドルウェア - • メータリングミドルウェア - • レート制限ミドルウェア - -⸻ - -🏗 アーキテクチャ（Phase 1） - -シンプルな単一構成（モノリス）で構築： - -Axum（Rust） -├── 認証ミドルウェア -├── テナント解決 -├── Usage計測 -├── レート制限 -├── APIハンドラ -│ -├── PostgreSQL（永続データ） -└── Redis（カウンタ・レート制限） - - -⸻ - -⚙️ 技術スタック - • 言語：Rust - • フレームワーク：Axum - • 非同期ランタイム：Tokio - • データベース：PostgreSQL - • キャッシュ / レート制御：Redis - • コンテナ：Docker（任意） - -⸻ - -📦 API設計（MVP） - -認証 - -Header: x-api-key: - - -⸻ - -エンドポイント - -ヘルスチェック - -GET /health - - -⸻ - -プロキシ（例） - -POST /proxy/{service} - - -⸻ - -管理API（簡易） - -テナント作成 - -POST /admin/tenants - -APIキー発行 - -POST /admin/api-keys - -Usage取得 - -GET /admin/usage - - -⸻ - -🧪 テスト戦略 - • APIの統合テスト - • 並行処理テスト（レート制限） - • テナント分離テスト - • 異常系テスト - -⸻ - -📊 可観測性（今後） - • 構造化ログ - • リクエストID - • メトリクス（p95 / p99） - • Usageダッシュボード - -⸻ - -🧠 なぜRustを使うのか - -UsageGateは単なるAPIではなく、 -高負荷かつ正確性が求められる基盤レイヤーです。 - -⸻ - -1. 安全な並行処理 - -以下のような処理を同時に扱う必要があります： - • APIリクエスト処理 - • レート制御 - • Usage計測 - • テナント分離 - -Rustは所有権モデルにより： - • データ競合 - • unsafeな共有状態 - -をコンパイル時に防止できます。 - -⸻ - -2. 高いパフォーマンス - -ゲートウェイ層では： - • 低レイテンシ - • 高スループット - • 多数の同時接続 - -が求められます。 - -Rustは： - • GCなし - • ゼロコスト抽象化 - • Tokioによる効率的な非同期処理 - -により高性能を実現します。 - -⸻ - -3. 型によるドメイン制約 - -重要な概念： - • TenantId - • ApiKeyId - • Plan - • Usage - • Quota - -を型で表現することで： - • 不正な値 - • IDの取り違え - -を防止できます。 - -⸻ - -4. 明示的なエラー処理 - -想定される失敗： - • APIキー不正 - • レート制限超過 - • クォータ超過 - • 外部API失敗 - -Rustの Result により、 -すべてのエラーケースを明示的に扱えます。 - -⸻ - -5. 信頼性の高いミドルウェア層 - -全リクエストが通過する： - • 認証 - • 計測 - • 制御 - -の層を、安全かつ堅牢に実装できます。 - -⸻ - -🔮 ロードマップ - -Phase 1（MVP） - • APIキー認証 - • Usage計測 - • レート制限 - • 基本テナント管理 - -⸻ - -Phase 2 - • プラン管理 - • Webhook - • 可観測性向上 - -⸻ - -Phase 3 - • Stripe 連携 - • 従量課金 - • サブスクリプション管理 - -⸻ - -Phase 4 - • Model Context Protocol 対応 - • AIエージェント連携 - • Tool単位課金 - -⸻ - -💡 ユースケース - • SaaSの従量課金API - • AI API（LLM / ツールAPI） - • 内部APIの利用制御 - • 開発者向けプラットフォーム - -⸻ - -🧭 ポジショニング - -UsageGateは： - • エンタープライズ向けの重いAPI Gatewayではなく - • 単なる分析ツールでもなく - -👉 開発者向けのシンプルで拡張可能なAPI基盤 - -⸻ - -📌 ステータス - -🚧 開発中（Phase 1） - -⸻ - -🧾 ライセンス - -未定 - -⸻