secretumvault/docs/development/features-control.md

# Feature Control System with Justfile

Complete guide to controlling SecretumVault build features using the Justfile.

## Table of Contents

1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Predefined Feature Sets](#predefined-feature-sets)
4. [Custom Features](#custom-features)
5. [Feature Reference](#feature-reference)
6. [Testing with Features](#testing-with-features)
7. [Examples](#examples)
8. [Common Workflows](#common-workflows)

---

## Overview

SecretumVault uses **Cargo features** to control optional functionality:

- **Crypto backends**: openssl, aws-lc, pqc (post-quantum), rustcrypto
- **Storage backends**: etcd, surrealdb, postgresql (filesystem always included)
- **Components**: cedar, server, cli

The **Justfile provides recipes** that make feature management simple:
- Predefined feature sets for common scenarios
- Custom feature combinations via parameters
- Feature display and documentation

### Architecture

```
Justfile (variables + recipes)
    ↓
justfiles/build.just (build recipes with features)
justfiles/test.just  (test recipes with features)
    ↓
cargo build --features (actual Rust compilation)
    ↓
Cargo.toml ([features] section)
```

---

## Quick Start

### Show Available Features

```bash
just show-features
```

Output:
```
═══════════════════════════════════════════════════════
CRYPTO BACKENDS
═══════════════════════════════════════════════════════
  openssl           Classical crypto (RSA, ECDSA) [DEFAULT]
  aws-lc           AWS-LC cryptographic backend
  pqc              Post-quantum (ML-KEM-768, ML-DSA-65)
  rustcrypto      Pure Rust crypto [PLANNED]

═══════════════════════════════════════════════════════
STORAGE BACKENDS
═══════════════════════════════════════════════════════
  (default)                Filesystem [DEFAULT]
  etcd-storage         Distributed etcd storage
  surrealdb-storage  SurrealDB document database
  postgresql-storage  PostgreSQL relational

═══════════════════════════════════════════════════════
OPTIONAL FEATURES
═══════════════════════════════════════════════════════
  server           HTTP server [DEFAULT]
  cli              CLI tools [DEFAULT]
  cedar             Cedar authorization
```

### Show Predefined Configurations

```bash
just show-config
```

Output:
```
Development (all features):
  Features: aws-lc,pqc,etcd-storage,surrealdb-storage,postgresql-storage
  Command:  just build::dev

Production High-Security (PQC + etcd):
  Features: aws-lc,pqc,etcd-storage
  Command:  just build::secure

Production Standard (OpenSSL + PostgreSQL):
  Features: postgresql-storage
  Command:  just build::prod

Production HA (etcd distributed):
  Features: etcd-storage
  Command:  just build::ha

Minimal (core only):
  Features: (none)
  Command:  just build::minimal
```

---

## Predefined Feature Sets

### Development (All Features)

```bash
just build::dev
```

**What it does**: Builds with every available feature enabled.

**Features**:
- aws-lc crypto backend (classical + PQC-ready)
- pqc (post-quantum: ML-KEM-768, ML-DSA-65)
- etcd-storage (distributed)
- surrealdb-storage (document DB)
- postgresql-storage (relational)

**Use case**: Development, testing, exploring all functionality

**Binary size**: ~30 MB

### Production Secure (Post-Quantum)

```bash
just build::secure
```

**What it does**: Production-ready with post-quantum cryptography and distributed storage.

**Features**:
- aws-lc (post-quantum ready)
- pqc (ML-KEM, ML-DSA)
- etcd-storage (HA)

**Use case**: Security-critical deployments, future-proof

**Binary size**: ~15 MB

### Production Standard

```bash
just build::prod
```

**What it does**: Standard production with proven stable components.

**Features**:
- postgresql-storage (relational DB)
- OpenSSL (default crypto)

**Use case**: Traditional production deployments

**Binary size**: ~8 MB

### Production HA (High Availability)

```bash
just build::ha
```

**What it does**: Distributed storage for high-availability clusters.

**Features**:
- etcd-storage (3+ node cluster)

**Use case**: HA clusters, multi-node deployments

**Binary size**: ~9 MB

### Minimal (Core Only)

```bash
just build::minimal
```

**What it does**: Core functionality only, filesystem storage.

**Features**: None (only defaults)

**Use case**: Testing, minimal footprint, education

**Binary size**: ~5 MB

---

## Custom Features

### Build with Custom Features

For any combination not in predefined sets:

```bash
just build::with-features FEATURES
```

**Examples**:

```bash
# Specific backend combinations
just build::with-features aws-lc,postgresql-storage
just build::with-features etcd-storage,cedar

# Multiple backends
just build::with-features etcd-storage,surrealdb-storage,postgresql-storage

# Only PQC
just build::with-features aws-lc,pqc

# Custom combination
just build::with-features aws-lc,pqc,etcd-storage,cedar
```

### Test with Custom Features

```bash
just test::with-features FEATURES
```

**Examples**:

```bash
# Test specific backends
just test::with-features postgresql-storage
just test::with-features etcd-storage,surrealdb-storage

# Test crypto
just test::with-features aws-lc,pqc
```

---

## Feature Reference

### Crypto Features

| Feature | Type | Default | Description |
|---------|------|---------|-------------|
| `aws-lc` | Backend | No | AWS-LC cryptographic library (PQC-ready) |
| `pqc` | Extension | No | Post-quantum algorithms (requires aws-lc) |
| `rustcrypto` | Backend | No | Pure Rust crypto (planned) |
| (openssl) | Default | Yes | Classical crypto (always available) |

**Compatibility**:
- `pqc` requires `aws-lc` feature
- Only one backend can be active (openssl is default)

### Storage Features

| Feature | Type | Default | Description |
|---------|------|---------|-------------|
| `etcd-storage` | Backend | No | etcd distributed KV store |
| `surrealdb-storage` | Backend | No | SurrealDB document database |
| `postgresql-storage` | Backend | No | PostgreSQL relational database |
| (filesystem) | Default | Yes | Filesystem storage (always available) |

**Compatibility**:
- Multiple storage backends can be enabled
- Filesystem is always available
- Configure which to use via `svault.toml`

### Component Features

| Feature | Type | Default | Description |
|---------|------|---------|-------------|
| `server` | Component | Yes | HTTP server (Axum) |
| `cli` | Component | Yes | Command-line tools |
| `cedar` | Component | No | Cedar policy engine |

---

## Testing with Features

### Test All Features

```bash
just test::all
```

Tests with all features enabled.

### Test Minimal

```bash
just test::minimal
```

Tests core functionality only.

### Test Specific Features

```bash
just test::with-features aws-lc,pqc
just test::with-features etcd-storage
just test::with-features postgresql-storage
```

### Test Configuration (Check without Running)

```bash
just build::test-config aws-lc,pqc
```

Validates that the feature combination is valid without full compilation.

---

## Examples

### Scenario 1: Develop Locally with All Features

```bash
# Show what's available
just show-config

# Build with all features
just build::dev

# Test to make sure everything works
just test::all

# Run the code
just dev-start
```

### Scenario 2: Deploy to Kubernetes with Post-Quantum

```bash
# Build secure (PQC + etcd)
just build::secure

# Build Docker image
just build::docker

# Deploy to K8s
just deploy::k8s-apply
```

### Scenario 3: Production with PostgreSQL

```bash
# Build standard production
just build::prod

# Test with prod features
just test::with-features postgresql-storage

# Build Docker
just build::docker

# Deploy
just deploy::compose-up
```

### Scenario 4: Test New Storage Backend

```bash
# Build with specific backend
just build::with-features surrealdb-storage

# Test that backend
just test::with-features surrealdb-storage

# Check compilation
just build::test-config surrealdb-storage,etcd-storage
```

### Scenario 5: Cross-Platform Build

```bash
# Build for ARM64
just build::target aarch64-unknown-linux-gnu

# Or use predefined with target
cargo build --release --target aarch64-unknown-linux-gnu --features aws-lc,pqc
```

---

## Common Workflows

### Daily Development

```bash
# Full workflow: format + lint + test + build
just check-all

# Or step by step
just fmt
just lint
just test::all
just build::dev
```

### Feature Development

```bash
# Developing a new storage backend (e.g., Consul)
just build::test-config consul-storage
just test::with-features consul-storage
just build::with-features consul-storage
```

### Pre-Release Verification

```bash
# Test all predefined configurations
just test::all
just build::dev
just build::secure
just build::prod
just build::ha
just build::minimal

# Verify each compiles
cargo check --features aws-lc,pqc,etcd-storage,surrealdb-storage,postgresql-storage
cargo check --features aws-lc,pqc,etcd-storage
cargo check --features postgresql-storage
cargo check --features etcd-storage
cargo check --no-default-features
```

### CI/CD Pipeline

```bash
# In GitHub Actions / GitLab CI
just dev::fmt-check      # Verify formatting
just dev::lint           # Run clippy
just test::all           # Test all features
just build::secure       # Build production-secure binary
```

### Production Build

```bash
# Standard production
just build::prod

# OR High-security production
just build::secure

# Verify binary
ls -lh target/release/svault
```

---

## Feature Combinations

### Recommended Combinations

```
Development:
  aws-lc,pqc,etcd-storage,surrealdb-storage,postgresql-storage

Production (High-Security):
  aws-lc,pqc,etcd-storage

Production (Standard):
  postgresql-storage

Production (HA):
  etcd-storage

Testing:
  (no features) - minimal core
```

### Do NOT Combine

```
✗ Multiple crypto backends (only one can be used)
  aws-lc + rustcrypto  (invalid)
  openssl + aws-lc     (openssl is default, don't add)

✗ Conflicting features (if not implemented)
  Check Cargo.toml [features] for conflicts
```

---

## Troubleshooting

### "Unknown feature"

```
error: unknown feature `xyz` in `[dependencies.vault]`
```

Solution: Feature not defined in Cargo.toml

```bash
# Check available features
just show-features
just cargo-features
```

### Build takes too long

Cause: Compiling with all features

Solution: Use minimal features for development

```bash
# Instead of all-features
just build::minimal

# Or specific features
just build::with-features etcd-storage
```

### Binary too large

Cause: All features enabled

Solution: Use production feature sets

```bash
# Instead of dev (30 MB)
just build::prod      # 8 MB
just build::secure    # 15 MB
```

### Feature compilation fails

Cause: Missing system dependencies

Solution: Check feature requirements

```bash
# etcd requires tokio
# postgresql requires libpq
# surrealdb requires openssl

# On macOS
brew install openssl postgresql

# On Ubuntu
sudo apt-get install libssl-dev libpq-dev
```

### Test fails with specific features

Solution: Test combinations individually

```bash
# Test each feature set separately
just test::with-features etcd-storage
just test::with-features surrealdb-storage
just test::with-features postgresql-storage

# Compare with all
just test::all
```

---

## Integration with Cargo

The Justfile recipes are wrappers around `cargo build --features`. You can also build directly with cargo:

```bash
# Equivalent to just build::secure
cargo build --release --features aws-lc,pqc,etcd-storage

# Equivalent to just build::with-features FEATS
cargo build --release --features aws-lc,pqc

# Equivalent to just build::minimal
cargo build --release --no-default-features
```

---

## Environment Variables

Control features via environment:

```bash
# Set FEATURES variable (not used by Justfile, but available)
export FEATURES="aws-lc,pqc,etcd-storage"
cargo build --release --features "$FEATURES"
```

Or in Justfile (if you modify it):

```just
CUSTOM_FEATURES := env('FEATURES', 'etcd-storage')

build-env:
    cargo build --release --features {{ CUSTOM_FEATURES }}
```

---

## Performance Tips

**Faster builds**:
```bash
# Use minimal features
just build::minimal

# Parallel compilation
cargo build -j 4

# Incremental builds
CARGO_BUILD_INCREMENTAL=1 cargo build
```

**Faster tests**:
```bash
# Test only lib (not integration tests)
just test::unit

# Single thread
cargo test --lib -- --test-threads=1
```

**Analyzing build time**:
```bash
# Show compilation time per crate
cargo build -Z timings

# Profile cargo
CARGO_LOG=debug cargo build
```

---

**See also**: [BUILD_FEATURES.md](BUILD_FEATURES.md) for technical details about features.