jesus/secretumvault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
secretumvault/docs/development/features-control.md
Jesús Pérez 46fc83d000
chore: reorganization compliance: layout_conventions
2025-12-26 15:13:36 +00:00

13 KiB
Raw Blame History

Feature Control System with Justfile

Complete guide to controlling SecretumVault build features using the Justfile.

Table of Contents

  1. Overview
  2. Quick Start
  3. Predefined Feature Sets
  4. Custom Features
  5. Feature Reference
  6. Testing with Features
  7. Examples
  8. 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

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

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)

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)

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

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)

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)

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:

just build::with-features FEATURES

Examples:

# 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

just test::with-features FEATURES

Examples:

# 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

just test::all

Tests with all features enabled.

Test Minimal

just test::minimal

Tests core functionality only.

Test Specific Features

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

Test Configuration (Check without Running)

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

Build takes too long

Cause: Compiling with all features

Solution: Use minimal features for development

# 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

# 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

# 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

# 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:

# 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:

# 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):

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

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

Performance Tips

Faster builds:

# Use minimal features
just build::minimal

# Parallel compilation
cargo build -j 4

# Incremental builds
CARGO_BUILD_INCREMENTAL=1 cargo build

Faster tests:

# Test only lib (not integration tests)
just test::unit

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

Analyzing build time:

# Show compilation time per crate
cargo build -Z timings

# Profile cargo
CARGO_LOG=debug cargo build

See also: BUILD_FEATURES.md for technical details about features.