secretumvault/docs/development/build-features.md

# Build Features & Configuration

Cargo features and build options for SecretumVault.

## Quick Build Commands

### Standard Build (OpenSSL only)

```bash
cargo build --release
```

Default compilation: OpenSSL crypto, filesystem storage, basic features.

### Full Featured Build

```bash
cargo build --release --all-features
```

Enables: All crypto backends, all storage backends, Cedar policies, everything.

### Minimal Build

```bash
cargo build --release --no-default-features
```

Bare minimum for development testing.

### Custom Features

```bash
cargo build --release --features aws-lc,pqc,postgresql-storage,etcd-storage
```

---

## Available Features

### Cryptography Features

#### `aws-lc` (Post-Quantum Ready)

**Status**: ✅ Complete
**Requires**: Feature flag
**Adds**: 20 KB binary size
**Depends on**: aws-lc-rs crate

Enables AWS-LC cryptographic backend:
- RSA-2048, RSA-4096
- ECDSA P-256, P-384, P-521
- Key generation and encryption

```bash
cargo build --features aws-lc
```

Use in config:

```toml
[vault]
crypto_backend = "aws-lc"
```

#### `pqc` (Post-Quantum Cryptography)

**Status**: ✅ Complete
**Requires**: Feature flag + aws-lc
**Adds**: 100 KB binary size
**NIST Standard**: ML-KEM-768, ML-DSA-65

Enables post-quantum algorithms:
- ML-KEM-768 (key encapsulation mechanism - KEM)
- ML-DSA-65 (digital signatures)
- Requires aws-lc feature enabled
- Requires Rust feature flags

```bash
cargo build --features aws-lc,pqc
```

Use in config:

```toml
[vault]
crypto_backend = "aws-lc"
```

Then select PQC algorithms in policy/usage (implementation in engines).

#### `rustcrypto` (Planned)

**Status**: 🔄 Planned
**Description**: Pure Rust cryptography

Pure Rust implementation without FFI dependencies.

```bash
# cargo build --features rustcrypto  # Not yet implemented
```

### Storage Features

#### `etcd-storage` (Distributed HA)

**Status**: ✅ Complete
**Requires**: Feature flag
**Adds**: 2 MB binary size
**Depends on**: etcd-client crate

Enables etcd storage backend:
- Distributed key-value store
- High availability with multiple nodes
- Production-ready

```bash
cargo build --features etcd-storage
```

Use in config:

```toml
[storage]
backend = "etcd"

[storage.etcd]
endpoints = ["http://localhost:2379"]
```

#### `surrealdb-storage` (Document Store)

**Status**: ✅ Complete (in-memory)
**Requires**: Feature flag
**Adds**: 1 MB binary size
**Depends on**: surrealdb crate

Enables SurrealDB storage backend:
- Document database with rich queries
- In-memory implementation (stable)
- Real SurrealDB support can be added

```bash
cargo build --features surrealdb-storage
```

Use in config:

```toml
[storage]
backend = "surrealdb"

[storage.surrealdb]
url = "ws://localhost:8000"
```

#### `postgresql-storage` (Relational)

**Status**: ✅ Complete
**Requires**: Feature flag
**Adds**: 1.5 MB binary size
**Depends on**: sqlx with postgres driver

Enables PostgreSQL storage backend:
- Industry-standard relational database
- Strong consistency guarantees
- Production-ready

```bash
cargo build --features postgresql-storage
```

Use in config:

```toml
[storage]
backend = "postgresql"

[storage.postgresql]
connection_string = "postgres://vault:pass@localhost:5432/secretumvault"
```

### Feature Combinations

**Development** (all backends, testing only):

```bash
cargo build --all-features
```

Binary size: ~30 MB
Features: OpenSSL, AWS-LC, PQC, etcd, SurrealDB, PostgreSQL, filesystem, Cedar

**Production - High Security**:

```bash
cargo build --release --features aws-lc,pqc,etcd-storage
```

Binary size: ~15 MB
Includes: Post-quantum crypto, distributed storage

**Production - Standard**:

```bash
cargo build --release --features postgresql-storage
```

Binary size: ~8 MB
Includes: OpenSSL crypto, PostgreSQL storage

**Minimal** (OpenSSL only):

```bash
cargo build --release
```

Binary size: ~5 MB
Includes: OpenSSL, filesystem storage

---

## Default Features

When building without `--no-default-features`:

```rust
default = ["server", "cli"]
```

- `server` - Enables HTTP server
- `cli` - Enables command-line tools

---

## Feature Dependencies

```
[aws-lc]
  ├── aws-lc-rs crate
  └── openssl (system dependency)

[pqc]
  ├── aws-lc (required)
  ├── ml-kem-768 support
  └── ml-dsa-65 support

[etcd-storage]
  ├── etcd-client crate
  └── tokio async runtime

[surrealdb-storage]
  ├── surrealdb crate
  └── tokio async runtime

[postgresql-storage]
  ├── sqlx crate
  ├── postgres driver
  └── tokio async runtime
```

---

## Cargo.toml Configuration

View in root `Cargo.toml`:

```toml
[features]
default = ["server", "cli"]

# Crypto backends
aws-lc = ["aws-lc-rs", "openssl"]
pqc = ["aws-lc"]
rustcrypto = ["rust-crypto"]

# Storage backends
etcd-storage = ["etcd-client"]
surrealdb-storage = ["surrealdb"]
postgresql-storage = ["sqlx"]

# Components
server = ["axum", "tokio-util"]
cli = ["clap", "colored"]
cedar = ["cedar-policy"]

[dependencies]
# Core
tokio = { version = "1", features = ["full"] }
axum = { version = "0.7", optional = true }
serde = { version = "1", features = ["derive"] }

# Optional crypto
aws-lc-rs = { version = "1.15", optional = true }

# Optional storage
etcd-client = { version = "0.17", optional = true }
surrealdb = { version = "1.0", optional = true }
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-native-tls"], optional = true }

# Optional CLI
clap = { version = "4", features = ["derive"], optional = true }
```

---

## Conditional Compilation

Features enable conditional code:

```rust
#[cfg(feature = "aws-lc")]
pub mod aws_lc;

#[cfg(feature = "aws-lc")]
pub fn create_aws_lc_backend() -> Result<Box<dyn CryptoBackend>> {
    Ok(Box::new(AwsLcBackend::new()?))
}

#[cfg(feature = "pqc")]
pub fn has_pqc_support() -> bool {
    true
}

#[cfg(not(feature = "pqc"))]
pub fn has_pqc_support() -> bool {
    false
}
```

Registry dispatch fails gracefully if feature not enabled:

```rust
pub fn create(backend: &str) -> Result<Box<dyn CryptoBackend>> {
    match backend {
        "openssl" => Ok(Box::new(OpenSSLBackend::new()?)),
        "aws-lc" => {
            #[cfg(feature = "aws-lc")]
            return Ok(Box::new(AwsLcBackend::new()?));

            #[cfg(not(feature = "aws-lc"))]
            return Err(ConfigError::FeatureNotEnabled("aws-lc"));
        }
        unknown => Err(ConfigError::UnknownBackend(unknown.to_string()))
    }
}
```

---

## Build Optimization

### Release Build

```bash
cargo build --release
```

Optimizations:
- Optimize for speed (`opt-level = 3`)
- Strip debug symbols
- Link time optimization (LTO)
- ~50% smaller, 2-3x faster than debug

### Debug Build

```bash
cargo build
```

Use for development:
- Full debug symbols
- Fast compilation
- Easier debugging

### Optimized for Size

```bash
cargo build --release -Z unstable-options --space-opt
```

Reduces binary size for container deployments.

### Profiling Build

```bash
RUSTFLAGS="-g" cargo build --release
```

Keeps debug symbols for profiling tools.

---

## Dependency Management

### Check for Vulnerabilities

```bash
cargo audit
```

Scans dependencies for known security issues.

### Update Dependencies

```bash
cargo update
```

Updates to latest compatible versions.

### Verify Dependencies

```bash
cargo tree
```

Shows dependency tree and versions.

```bash
cargo tree --duplicates
```

Identifies duplicate dependencies.

---

## Feature-Specific Testing

### Test with All Features

```bash
cargo test --all-features
```

Runs all tests with every feature enabled.

### Test Specific Feature

```bash
cargo test --features aws-lc,pqc
```

Tests only with those features.

### Test Minimal Build

```bash
cargo test --no-default-features
```

Tests core functionality without optional features.

---

## Docker Build Optimization

### Multi-stage Build with Minimal Runtime

```dockerfile
# Stage 1: Builder
FROM rust:1.82-alpine as builder
RUN apk add --no-cache libssl-dev
WORKDIR /build
COPY . .
RUN cargo build --release --features aws-lc,pqc,etcd-storage

# Stage 2: Runtime
FROM alpine:latest
RUN apk add --no-cache libssl3 ca-certificates
COPY --from=builder /build/target/release/svault /usr/local/bin/
ENTRYPOINT ["svault"]
```

Results:
- Builder stage: ~500 MB
- Runtime image: ~50 MB (with all libraries)

### Feature-Specific Docker Images

Development (all features):

```bash
docker build -t vault-dev --build-arg FEATURES="--all-features" .
```

Production (minimal):

```bash
docker build -t vault-prod --build-arg FEATURES="--release" .
```

---

## Benchmark Features

### Enable Benchmarking

```bash
cargo bench --all-features
```

Benchmarks operations with all features enabled.

### Specific Benchmark

```bash
cargo bench encrypt --features aws-lc,pqc
```

Benchmark encryption operations with PQC.

---

## Cross-Compilation

### Build for Different Architecture

```bash
# ARM64 (aarch64)
cargo build --release --target aarch64-unknown-linux-gnu

# x86-64
cargo build --release --target x86_64-unknown-linux-gnu

# macOS ARM (Apple Silicon)
cargo build --release --target aarch64-apple-darwin
```

Install target:

```bash
rustup target add aarch64-unknown-linux-gnu
```

---

## Feature Combinations Reference

| Build | Command | Binary Size | Use Case |
|-------|---------|-------------|----------|
| Minimal | `cargo build --release` | ~5 MB | Testing, education |
| Standard | `cargo build --release --features postgresql-storage` | ~8 MB | Production standard |
| HA | `cargo build --release --features etcd-storage` | ~9 MB | High availability |
| Secure | `cargo build --release --features aws-lc,pqc,postgresql-storage` | ~18 MB | Post-quantum production |
| Full | `cargo build --all-features` | ~30 MB | Development, testing |

---

## Troubleshooting Build Issues

### Feature Not Found

```
error: feature `xyz` not found
```

Solution: Check `Cargo.toml` for correct feature name.

### Dependency Conflict

```
error: conflicting versions for dependency `tokio`
```

Solution: Run `cargo update` to resolve.

### Compilation Error with Feature

```
error[E0433]: cannot find function `aws_lc_function` in this scope
```

Solution: Ensure feature is enabled: `cargo build --features aws-lc`

### Linking Error

```
error: linking with `cc` failed
```

Solution: Install system dependencies:

```bash
# macOS
brew install openssl

# Ubuntu/Debian
sudo apt-get install libssl-dev

# Alpine
apk add --no-cache libssl-dev
```

### Out of Memory During Compilation

Solution: Use incremental builds:

```bash
cargo build -Z incremental
```

Or reduce parallel jobs:

```bash
cargo build -j 2
```

---

## Production Build Checklist

- [ ] Run `cargo audit` - no vulnerabilities
- [ ] Run `cargo clippy -- -D warnings` - no warnings
- [ ] Run `cargo test --all-features` - all tests pass
- [ ] Build with `--release` flag
- [ ] Test with intended feature set
- [ ] Verify binary size acceptable
- [ ] Test on target platform (if cross-compiling)
- [ ] Verify dependencies lock file is committed

---

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo audit
      - run: cargo clippy -- -D warnings
      - run: cargo test --all-features
      - run: cargo build --release --all-features
```

---

**Next steps**: See [Deployment Guide](../DEPLOYMENT.md) for building and running in production.