RSFGA is a high-performance, 100% API-compatible Rust implementation of OpenFGA, an authorization/permission engine inspired by Google Zanzibar.
Current Phase: Phase 1 - MVP Implementation ✅ Complete (~918 tests)
| Component | Status |
|---|---|
| OpenFGA Compatibility Test Suite | ✅ Complete (194 tests) |
| Type System & DSL Parser | ✅ Complete |
| Storage Layer (Memory) | ✅ Complete |
| Storage Layer (PostgreSQL) | ✅ Complete |
| Storage Layer (MySQL/MariaDB/TiDB) | ✅ Complete |
| Storage Layer (CockroachDB) | ✅ Complete |
| Storage Layer (RocksDB) | ✅ Complete |
| Graph Resolver | ✅ Complete |
| Batch Check Handler | ✅ Complete |
| REST & gRPC APIs | ✅ Complete |
| CEL Condition Evaluation | ✅ Complete |
| Observability (Metrics, Tracing, Logging) | ✅ Complete |
| Configuration Management | ✅ Complete |
| Documentation | ✅ Complete |
| Deployment (Docker, K8s, Helm) | ✅ Complete |
- Drop-in Replacement: 100% API compatible with OpenFGA - swap with zero code changes
- High Performance: 2x+ throughput through async graph traversal and lock-free caching
- Production Ready: Comprehensive observability, structured logging, Prometheus metrics
- Type Safe: Rust's compile-time guarantees prevent common authorization bugs
The easiest way to run RSFGA:
# Pull from GitHub Container Registry
docker pull ghcr.io/julianshen/rsfga:latest
# Run with in-memory storage
docker run -p 8080:8080 -p 50051:50051 ghcr.io/julianshen/rsfga:latest
# Run with RocksDB persistent storage
docker run -p 8080:8080 -p 50051:50051 \
-e RSFGA_STORAGE__BACKEND=rocksdb \
-v rsfga-data:/data \
ghcr.io/julianshen/rsfga:latest
# Run with PostgreSQL
docker run -p 8080:8080 -p 50051:50051 \
-e RSFGA_STORAGE__BACKEND=postgres \
-e RSFGA_STORAGE__DATABASE_URL="postgres://user:password@host:5432/rsfga" \
ghcr.io/julianshen/rsfga:latest- Rust 1.80+ (Install Rust) - MSRV (Minimum Supported Rust Version)
- PostgreSQL 14+ / MySQL 8.0+ / CockroachDB (optional, for persistent storage)
# Clone the repository
git clone https://github.com/julianshen/rsfga.git
cd rsfga
# Build in release mode
cargo build --release
# Run the server
./target/release/rsfga --config config.yamlWith in-memory storage (for development/testing):
# Run with environment variables
RSFGA_STORAGE__BACKEND=memory ./target/release/rsfgaWith RocksDB (for embedded/edge deployments):
RSFGA_STORAGE__BACKEND=rocksdb \
RSFGA_STORAGE__DATA_PATH=/var/lib/rsfga \
./target/release/rsfgaWith PostgreSQL (for production):
# Set up PostgreSQL connection
export RSFGA_STORAGE__DATABASE_URL="postgres://user:password@localhost:5432/rsfga"
# Create config file
cat > config.yaml << EOF
server:
host: "0.0.0.0"
port: 8080
storage:
backend: postgres
pool_size: 10
connection_timeout_secs: 5
logging:
level: info
json: true
metrics:
enabled: true
tracing:
enabled: true
jaeger_endpoint: "localhost:6831"
service_name: rsfga
EOF
# Build the server (standalone binary coming in M1.9 Section 4)
cargo build --releaseOnce the server is running, you can interact with it using the OpenFGA API:
1. Create a Store:
curl -X POST http://localhost:8080/stores \
-H "Content-Type: application/json" \
-d '{"name": "my-store"}'2. Create an Authorization Model:
STORE_ID="<store-id-from-above>"
curl -X POST "http://localhost:8080/stores/${STORE_ID}/authorization-models" \
-H "Content-Type: application/json" \
-d '{
"schema_version": "1.1",
"type_definitions": [
{
"type": "user",
"relations": {}
},
{
"type": "document",
"relations": {
"viewer": {
"this": {}
},
"editor": {
"this": {}
},
"owner": {
"this": {}
}
},
"metadata": {
"relations": {
"viewer": {"directly_related_user_types": [{"type": "user"}]},
"editor": {"directly_related_user_types": [{"type": "user"}]},
"owner": {"directly_related_user_types": [{"type": "user"}]}
}
}
}
]
}'3. Write a Relationship Tuple:
curl -X POST "http://localhost:8080/stores/${STORE_ID}/write" \
-H "Content-Type: application/json" \
-d '{
"writes": {
"tuple_keys": [
{
"user": "user:alice",
"relation": "viewer",
"object": "document:readme"
}
]
}
}'4. Check a Permission:
curl -X POST "http://localhost:8080/stores/${STORE_ID}/check" \
-H "Content-Type: application/json" \
-d '{
"tuple_key": {
"user": "user:alice",
"relation": "viewer",
"object": "document:readme"
}
}'
# Returns: {"allowed": true}RSFGA is a drop-in replacement for OpenFGA. To migrate:
- Update the endpoint: Change your OpenFGA server URL to point to RSFGA
- No code changes needed: All APIs are 100% compatible
- Database migration: If using PostgreSQL, RSFGA uses the same schema
See docs/MIGRATION.md for detailed migration instructions.
┌─────────────────────────────────────────────────────────────┐
│ Clients │
│ (HTTP REST / gRPC / SDK) │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ rsfga-api │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Axum (REST) │ │ Tonic (gRPC) │ │ Observability│ │
│ └────────┬────────┘ └────────┬────────┘ └──────┬──────┘ │
└───────────┼────────────────────┼─────────────────┼──────────┘
│ │ │
┌───────────▼────────────────────▼─────────────────▼──────────┐
│ rsfga-server │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Check Handler │ │ Batch Handler │ │ Config │ │
│ └────────┬────────┘ └────────┬────────┘ └─────────────┘ │
└───────────┼────────────────────┼────────────────────────────┘
│ │
┌───────────▼────────────────────▼────────────────────────────┐
│ rsfga-domain │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Graph Resolver │ │ Type System │ │ Cache │ │
│ │ (Async/Parallel)│ │ (DSL Parser) │ │ (Lock-free) │ │
│ └────────┬────────┘ └─────────────────┘ └─────────────┘ │
└───────────┼─────────────────────────────────────────────────┘
│
┌───────────▼─────────────────────────────────────────────────┐
│ rsfga-storage │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ In-Memory │ │ PostgreSQL │ │
│ │ (DashMap) │ │ (SQLx async) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
RSFGA supports configuration through YAML files and environment variables.
server:
host: "0.0.0.0"
port: 8080
request_timeout_secs: 30
max_connections: 10000
storage:
backend: postgres # or "memory"
database_url: "postgres://user:pass@localhost:5432/rsfga"
pool_size: 10
connection_timeout_secs: 5
logging:
level: info # trace, debug, info, warn, error
json: true # JSON format for production
metrics:
enabled: true
path: /metrics # Note: Currently hardcoded to /metrics in router
tracing:
enabled: false # default is false; set to true to enable Jaeger tracing
jaeger_endpoint: "localhost:6831"
service_name: rsfgaEnvironment variables override config file values. Use RSFGA_ prefix with __ for nested keys:
RSFGA_SERVER__PORT=9090
RSFGA_STORAGE__DATABASE_URL="postgres://..."
RSFGA_LOGGING__LEVEL=debug| Metric | OpenFGA Baseline | RSFGA Target | Strategy |
|---|---|---|---|
| Check throughput | 483 req/s | 1000+ req/s | Async graph traversal, lock-free caching |
| Batch check | 23 checks/s | 500+ checks/s | Parallel execution, deduplication |
| Write throughput | 59 req/s | 150+ req/s | Batch processing, async invalidation |
| Check p95 latency | 22ms | <20ms | Optimized graph resolution |
Note: These are target performance numbers. Validation is pending Milestone 1.7 benchmarking. See ADR Validation Status for details.
rsfga/
├── crates/
│ ├── rsfga-api/ # HTTP & gRPC API layer + server binary
│ ├── rsfga-server/ # Request handlers & business logic
│ ├── rsfga-domain/ # Graph resolver, type system, cache
│ ├── rsfga-storage/ # Storage abstraction & backends
│ └── compatibility-tests/ # OpenFGA compatibility tests
├── deploy/
│ ├── kubernetes/ # Kubernetes manifests
│ └── helm/rsfga/ # Helm chart
├── docs/
│ └── design/ # Architecture & design documents
├── Dockerfile # Multi-stage Docker build
├── CLAUDE.md # Development guide (TDD methodology)
└── plan.md # Implementation plan
- API Specification - Complete REST/gRPC API reference
- Architecture - System design and components
- Architecture Decisions - ADRs with rationale
- Migration Guide - Migrating from OpenFGA
- Deployment Guide - Docker, Kubernetes, Helm deployment
- Data Models - Data structures and schemas
# Build
cargo build
# Run tests
cargo test
# Run with coverage
cargo tarpaulin --out Html
# Lint
cargo clippy --all-targets --all-features -- -D warnings
# Format
cargo fmtSee CLAUDE.md for development methodology and CONTRIBUTING.md for contribution guidelines.
- Phase 0: OpenFGA Compatibility Test Suite (150+ tests)
- Phase 1: MVP - OpenFGA Compatible Core
- Type System & Parser
- Storage Layer (Memory + PostgreSQL)
- Graph Resolver
- Batch Check Handler
- REST & gRPC APIs
- CEL Conditions
- Observability
- Configuration
- Documentation (in progress)
- Deployment (Docker, K8s)
- Phase 2: Precomputation Engine (<1ms p99 latency)
- Phase 3: Distributed Edge (global <10ms latency)
Licensed under the Apache License, Version 2.0. See LICENSE for details.
- OpenFGA for the original implementation
- Google Zanzibar for foundational concepts
Built with Rust for performance and safety