Livebook & Benchmarking

View Source

ExkPasswd provides interactive Livebook notebooks for learning, experimentation, and performance analysis.

What is Livebook?

Livebook is an interactive notebook platform for Elixir. Think Jupyter notebooks, but native to Elixir with live code execution, visualizations, and collaborative features.

Available Notebooks

ExkPasswd includes five interactive notebooks:

📘 Quick Start

Get started with ExkPasswd basics:

  • Generate passwords with presets
  • Create custom configurations
  • Batch generation
  • Strength analysis

For: New users and quick reference

📗 Advanced Usage

Deep dive into advanced features:

  • Fine-grained configuration control
  • Character substitutions (leetspeak)
  • Custom dictionaries and internationalization
  • Transform protocol usage

For: Users building custom password policies

📕 Security Analysis

Understand password security:

  • Entropy calculations explained
  • Strength ratings and crack time estimates
  • Preset security comparisons
  • Cryptographic randomness verification

For: Security-conscious users and auditors

📊 Benchmarks

Performance metrics and analysis:

  • Password generation speed
  • Dictionary O(1) lookup verification
  • Batch vs individual generation comparison
  • Memory usage analysis

For: Performance optimization and verification

🛠️ Contributing Guide

Interactive developer onboarding:

  • Architecture exploration with live code
  • Test changes without running full test suite
  • Create custom presets and transforms
  • Performance testing your changes

For: Contributors and developers

Running Notebooks

Option 1: Run in Browser (Easiest)

Click any "Run in Livebook" badge in the README or notebook files to run directly in your browser without installation.

Option 2: Local Livebook

  1. Install Livebook:

    mix escript.install hex livebook

  2. Start Livebook server:

    livebook server

  3. Open a notebook:

    • Navigate to the ExkPasswd directory
    • Open any .livemd file from notebooks/

Option 3: Livebook Desktop

Download Livebook Desktop for a native app experience.

Benchmarks

ExkPasswd includes standalone benchmark scripts for CI/automation:

Running Benchmarks

# All benchmarks
mix bench.all

# Individual benchmarks
mix bench.password  # Password generation performance
mix bench.dict      # Dictionary operation performance
mix bench.batch     # Batch generation performance

Benchmark Scripts

  • bench/password_generation.exs - Core generation, presets, transforms
  • bench/dictionary.exs - Dictionary operations (O(1) verification)
  • bench/batch.exs - Batch vs individual generation comparison

CI vs Local Mode

Benchmarks automatically adapt to their environment:

CI Mode (when CI=true):

  • Fast verification (~30 seconds total)
  • Verifies benchmarks compile and run
  • Shorter durations: time: 0.5s, warmup: 0.1s
  • Smaller batch sizes: [10, 100]

Local Mode (default):

  • Accurate performance measurement (~5+ minutes)
  • Full benchmark durations: time: 5s, warmup: 2s
  • Large batch sizes: [100, 1000, 10_000]

Running in CI mode locally:

CI=true mix bench.all

Why Two Approaches?

Livebook Notebooks (Interactive)

  • Learn by doing with live code execution
  • Experiment with configurations safely
  • Run on your own hardware for accurate results
  • Great for exploration and education

Benchmark Scripts (Automation)

  • Run in CI to catch API breaking changes
  • Fast verification without performance measurement
  • Scripted for automation and regression testing
  • No GUI required

CI Integration

Benchmarks run automatically in GitHub Actions on every push and pull request via .github/workflows/benchmarks.yml.

Purpose: Verify benchmarks compile and run successfully, catching API breaking changes that would break benchmark code.

Not for: Performance regression detection (too noisy on CI hardware).

Performance Characteristics

ExkPasswd is optimized for speed:

  • Dictionary lookups: O(1) via tuple-based indexing
  • Case transforms: Pre-computed variants (3x faster)
  • Batch generation: Buffered random bytes (1.5-3x faster for large batches)
  • Custom dictionaries: ETS-backed for O(1) lookups

Benchmarks verify these characteristics remain true as the codebase evolves.

Resources