178 lines
4.7 KiB
Markdown
178 lines
4.7 KiB
Markdown
# k-template
|
|
|
|
A production-ready, modular Rust API template for K-Suite applications, following Hexagonal Architecture principles.
|
|
|
|
## Features
|
|
|
|
- **Hexagonal Architecture**: Clear separation between Domain, Infrastructure, and API layers
|
|
- **Multiple Auth Modes**: Session-based, JWT, or both - fully configurable
|
|
- **OIDC Integration**: Connect to any OpenID Connect provider (Keycloak, Auth0, Zitadel, etc.)
|
|
- **Database Flexibility**: SQLite (default) or PostgreSQL via feature flags
|
|
- **Type-Safe Configuration**: Newtypes with built-in validation for all security-sensitive values
|
|
- **Cargo Generate Ready**: Pre-configured for scaffolding new services
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Use cargo-generate (Recommended)
|
|
|
|
```bash
|
|
cargo generate --git https://github.com/GKaszewski/k-template.git
|
|
```
|
|
|
|
You'll be prompted to choose:
|
|
- **Project name**: Your new service name
|
|
- **Database**: `sqlite` or `postgres`
|
|
- **Session auth**: Enable cookie-based sessions
|
|
- **JWT auth**: Enable Bearer token authentication
|
|
- **OIDC**: Enable OpenID Connect integration
|
|
|
|
### Option 2: Clone directly
|
|
|
|
```bash
|
|
git clone https://github.com/GKaszewski/k-template.git my-api
|
|
cd my-api
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
### Run
|
|
|
|
```bash
|
|
# Development (with hot reload via cargo-watch)
|
|
cargo watch -x run
|
|
|
|
# Or simply
|
|
cargo run
|
|
```
|
|
|
|
The API will be available at `http://localhost:3000/api/v1/`.
|
|
|
|
## Configuration
|
|
|
|
All configuration is done via environment variables. See [.env.example](.env.example) for all options.
|
|
|
|
### Authentication Modes
|
|
|
|
Set `AUTH_MODE` to one of:
|
|
|
|
| Mode | Description | Required Features |
|
|
|------|-------------|-------------------|
|
|
| `session` | Cookie-based sessions | `auth-axum-login` |
|
|
| `jwt` | Bearer token authentication | `auth-jwt` |
|
|
| `both` | Try JWT first, fall back to session | `auth-axum-login`, `auth-jwt` |
|
|
|
|
### OIDC Integration
|
|
|
|
To enable OIDC login (e.g., "Login with Google"):
|
|
|
|
1. Enable the `auth-oidc` feature (enabled by default)
|
|
2. Configure your OIDC provider in `.env`:
|
|
```env
|
|
OIDC_ISSUER=https://your-provider.com
|
|
OIDC_CLIENT_ID=your-client-id
|
|
OIDC_CLIENT_SECRET=your-secret
|
|
OIDC_REDIRECT_URL=http://localhost:3000/api/v1/auth/callback
|
|
```
|
|
3. Users can login via `GET /api/v1/auth/login/oidc`
|
|
|
|
## Feature Flags
|
|
|
|
Features are configured in `api/Cargo.toml`:
|
|
|
|
```toml
|
|
[features]
|
|
default = ["sqlite", "auth-axum-login", "auth-oidc", "auth-jwt"]
|
|
```
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| `sqlite` | SQLite database support (default) |
|
|
| `postgres` | PostgreSQL database support |
|
|
| `auth-axum-login` | Session-based authentication |
|
|
| `auth-oidc` | OpenID Connect integration |
|
|
| `auth-jwt` | JWT token authentication |
|
|
| `auth-full` | All auth features combined |
|
|
|
|
### Common Configurations
|
|
|
|
**JWT-only API (stateless)**:
|
|
```toml
|
|
default = ["sqlite", "auth-jwt"]
|
|
```
|
|
|
|
**OIDC + JWT (typical SPA backend)**:
|
|
```toml
|
|
default = ["sqlite", "auth-oidc", "auth-jwt"]
|
|
```
|
|
|
|
**Full-featured (all auth methods)**:
|
|
```toml
|
|
default = ["sqlite", "auth-full"]
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `POST` | `/api/v1/auth/login` | Login with email/password |
|
|
| `POST` | `/api/v1/auth/register` | Register new user |
|
|
| `POST` | `/api/v1/auth/logout` | Logout (session mode) |
|
|
| `GET` | `/api/v1/auth/me` | Get current user |
|
|
| `POST` | `/api/v1/auth/token` | Get JWT for session user |
|
|
| `GET` | `/api/v1/auth/login/oidc` | Start OIDC login flow |
|
|
| `GET` | `/api/v1/auth/callback` | OIDC callback |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
k-template/
|
|
├── domain/ # Core business logic (no I/O dependencies)
|
|
│ └── src/
|
|
│ ├── entities.rs # User entity
|
|
│ ├── value_objects.rs # Email, Password, OIDC newtypes
|
|
│ ├── repositories.rs # Repository interfaces (ports)
|
|
│ └── services.rs # Domain services
|
|
│
|
|
├── infra/ # Infrastructure adapters
|
|
│ └── src/
|
|
│ ├── auth/ # Auth backends (OIDC, JWT)
|
|
│ └── user_repository.rs
|
|
│
|
|
├── api/ # HTTP API layer
|
|
│ └── src/
|
|
│ ├── routes/ # API endpoints
|
|
│ ├── config.rs # Configuration
|
|
│ └── state.rs # Application state
|
|
│
|
|
├── .env.example # Configuration template
|
|
└── compose.yml # Docker Compose for local dev
|
|
```
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
cargo test --all-features
|
|
|
|
# Domain tests only
|
|
cargo test -p domain
|
|
```
|
|
|
|
### Database Migrations
|
|
|
|
```bash
|
|
# SQLite
|
|
sqlx migrate run --source migrations_sqlite
|
|
|
|
# PostgreSQL
|
|
sqlx migrate run --source migrations_postgres
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|