familia 2.0.0.pre4 → 2.0.0.pre6

data/docs/overview.md

@@ -0,0 +1,359 @@
+
+# Familia - Overview
+
+> [!NOTE]
+> This document refers to Valkey throughout, but all examples and patterns work identically with Redis. Familia supports both Valkey and Redis as they share the same protocol and data structures.
+
+## Introduction
+
+Familia is a Ruby ORM for Valkey (Redis) that provides object-oriented access to Valkey's native data structures. Unlike traditional ORMs that map objects to relational tables, Familia preserves Valkey's performance and flexibility while offering a familiar Ruby interface.
+
+**Why Familia?**
+- Maps Ruby objects directly to Valkey's native data structures (strings, lists, sets, etc.)
+- Maintains Valkey's atomic operations and performance characteristics
+- Handles complex patterns (quantization, encryption, expiration) out of the box
+
+## Core Concepts
+
+### What is a Horreum Class?
+
+The ```Horreum``` class is Familia's foundation, representing Valkey-compatible objects. It's named after ancient Roman storehouses, reflecting its purpose as a structured data repository.
+
+```ruby
+class Flower < Familia::Horreum
+  identifier_field :token
+  field :name
+  field :color
+  field :species
+  list :owners
+  set :tags
+  zset :metrics
+  hashkey :props
+  string :counter
+end
+```
+
+This pattern lets you work with Valkey data as Ruby objects while maintaining direct access to Valkey's native operations.
+
+### Flexible Identifiers
+
+Horreum classes require identifiers to determine Valkey key names. You can define them in various ways:
+
+```ruby
+class User < Familia::Horreum
+  # Simple field-based identifier
+  identifier_field :email
+
+  # Computed identifier
+  identifier_field ->(user) { "user:#{user.id}" }
+
+  # Multi-field composite identifier
+  identifier_field [:type, :email]
+
+  field :email
+  field :type
+  field :id
+end
+```
+
+This flexibility allows you to adapt to different Valkey key naming strategies while maintaining clean Ruby object interfaces.
+
+### Data Types Mapping
+
+Familia provides direct mappings to Valkey's native data structures:
+
+```ruby
+class Product < Familia::Horreum
+  identifier_field :sku
+
+  # Basic fields
+  field :sku
+  field :name
+  field :price
+
+  # String fields (for counters, simple values)
+  string :view_count, default: '0'
+  # Usage: view_count.increment (atomic increment)
+
+  # Lists (ordered, allows duplicates)
+  list :categories
+  # Usage: categories.push('fruit'), categories.pop
+
+  # Sets (unordered, unique)
+  set :tags
+  # Usage: tags.add('organic'), tags.include?('organic')
+
+  # Sorted sets (scored, ordered)
+  zset :ratings
+  # Usage: ratings.add(4.5, 'customer123'), ratings.rank('customer123')
+
+  # Hash keys (dictionaries)
+  hashkey :attributes
+  # Usage: attributes['color'] = 'red', attributes.to_h
+end
+```
+
+Each type maintains Valkey's native operations while providing Ruby-friendly interfaces.
+
+## Essential Features
+
+### Automatic Expiration
+
+Set default TTL for objects that should expire:
+
+```ruby
+class Session < Familia::Horreum
+  feature :expiration
+  default_expiration 30.minutes
+
+  field :user_id
+  field :token
+end
+
+# Auto-expires in 30 minutes
+session = Session.create(user_id: '123', token: 'abc')
+```
+
+This is ideal for temporary data like authentication tokens or cache entries.
+
+### Safe Dumping for APIs
+
+Control which fields are exposed when serializing objects:
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump
+
+  @safe_dump_fields = [
+    :id,
+    :email,
+    {full_name: ->(user) { "#{user.first_name} #{user.last_name}" }}
+  ]
+
+  field :id, :email, :first_name, :last_name, :password_hash
+end
+
+user.safe_dump
+#=> {id: "123", email: "alice@example.com", full_name: "Alice Smith"}
+```
+
+Prevents accidental exposure of sensitive data in API responses.
+
+### Time-based Quantization
+
+Group time-based metrics into buckets:
+
+```ruby
+class DailyMetric < Familia::Horreum
+  feature :quantization
+  string :counter, default_expiration: 1.day, quantize: [10.minutes, '%H:%M']
+end
+```
+
+This automatically groups metrics into 10-minute intervals formatted as "HH:MM", ideal for analytics dashboards.
+
+## Advanced Patterns
+
+### Custom Methods and Logic
+
+Add domain-specific behavior to your models:
+
+```ruby
+class User < Familia::Horreum
+  field :first_name
+  field :last_name
+  field :status
+
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+
+  def active?
+    status == 'active'
+  end
+end
+```
+
+These methods work alongside Familia's persistence layer, letting you build rich domain models.
+
+### Transactional Operations
+
+Execute multiple Valkey commands atomically:
+
+```ruby
+user.transaction do |conn|
+  conn.set("user:#{user.id}:status", "active")
+  conn.zadd("active_users", Time.now.to_i, user.id)
+end
+```
+
+Preserves data integrity for complex operations that require multiple Valkey commands.
+
+### Connection Management and Pooling
+
+Configure connection pooling for production environments:
+
+```ruby
+require 'connection_pool'
+
+pools = {
+  "redis://localhost:6379/0" => ConnectionPool.new(size: 10) { Redis.new(db: 0) }
+}
+
+Familia.connection_provider = lambda do |uri|
+  pool = pools[uri]
+  pool.with { |conn| conn }
+end
+```
+
+This ensures efficient Valkey connection usage in multi-threaded applications.
+
+### Encrypted Fields
+
+Protect sensitive data at rest:
+
+```ruby
+class SecureUser < Familia::Horreum
+  feature :encrypted_fields
+
+  identifier_field :id
+  field :id
+  field :email                    # Plain text
+  encrypted_field :ssn            # Encrypted
+  encrypted_field :notes, aad_fields: [:id, :email]  # With auth data
+end
+```
+
+Uses authenticated encryption to protect data while allowing selective field access.
+
+### Open-ended Serialization
+
+Customize how objects are serialized to Valkey:
+
+```ruby
+class JsonModel < Familia::Horreum
+  def serialize_value
+    JSON.generate(to_h)
+  end
+
+  def self.deserialize_value(data)
+    new(**JSON.parse(data, symbolize_names: true))
+  end
+end
+```
+
+Enables integration with custom serialization formats beyond Familia's defaults.
+
+## Configuration
+
+### Basic Setup
+
+```ruby
+# Simple connection
+Familia.uri = 'redis://localhost:6379/0'
+
+# Multiple databases
+Familia.redis_config = {
+  host: 'localhost',
+  port: 6379,
+  db: 0,
+  timeout: 5
+}
+```
+
+### Encryption Setup (Optional)
+
+```ruby
+# Generate base64-encoded 32-byte keys
+Familia.config.encryption_keys = {
+  v1: Base64.strict_encode64(SecureRandom.bytes(32)),
+  v2: Base64.strict_encode64(SecureRandom.bytes(32))
+}
+Familia.config.current_key_version = :v2
+```
+
+## Common Patterns
+
+### Bulk Operations
+
+```ruby
+# Load multiple objects
+users = User.multiget('alice@example.com', 'bob@example.com')
+
+# Batch operations
+User.transaction do |conn|
+  conn.set('user:alice:status', 'active')
+  conn.zadd('active_users', Time.now.to_i, 'alice')
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  user = User.load('nonexistent@example.com')
+rescue Familia::Problem => e
+  puts "User not found: #{e.message}"
+end
+
+# Safe loading
+user = User.load('maybe@example.com') || User.new
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Connection Errors:**
+```ruby
+# Check connection
+Familia.connect_to_uri('redis://localhost:6379/0')
+```
+
+**Missing Keys:**
+```ruby
+# Debug key names
+user = User.new(email: 'test@example.com')
+puts user.rediskey  # Shows the Valkey key that would be used
+```
+
+**Encryption Issues:**
+```ruby
+# Validate encryption config
+Familia::Encryption.validate_configuration!
+```
+
+### Debug Mode
+
+```ruby
+# Enable debug logging
+Familia.debug = true
+
+# Check what's in Valkey
+Familia.redis.keys('*')  # List all keys (use carefully in production)
+```
+
+## Testing
+
+### Test Configuration
+
+```ruby
+# test_helper.rb or spec_helper.rb
+require 'familia'
+
+# Use separate test database
+Familia.uri = 'redis://localhost:6379/15'
+
+# Setup encryption for tests
+test_keys = {
+  v1: Base64.strict_encode64('a' * 32),
+  v2: Base64.strict_encode64('b' * 32)
+}
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clear data between tests
+def clear_redis
+  Familia.redis.flushdb
+end
+```

data/docs/wiki/API-Reference.md

@@ -0,0 +1,347 @@
+# API Reference
+
+## Class Methods
+
+### encrypted_field
+
+Defines an encrypted field on a Familia::Horreum class.
+
+```ruby
+encrypted_field(name, **options)
+```
+
+**Parameters:**
+- `name` (Symbol) - Field name
+- `**options` (Hash) - Standard field options plus encryption-specific options
+
+**Options:**
+- `:as` - Custom accessor method name
+- `:on_conflict` - Conflict resolution (always `:raise` for encrypted fields)
+
+**Example:**
+```ruby
+class User < Familia::Horreum
+  encrypted_field :favorite_snack
+  encrypted_field :api_key, as: :secret_key
+end
+```
+
+### encrypted_fields
+
+Returns list of encrypted field names.
+
+```ruby
+User.encrypted_fields  # => [:favorite_snack, :api_key]
+```
+
+## Instance Methods
+
+### Field Accessors
+
+Encrypted fields provide standard accessors:
+
+```ruby
+user.favorite_snack           # Get decrypted value
+user.favorite_snack = value   # Set and encrypt value
+user.favorite_snack!          # Fast write (still encrypted)
+```
+
+### Passphrase-Protected Access
+
+```ruby
+# For passphrase-protected fields
+vault.secret_data(passphrase_value: "user_passphrase")
+```
+
+## Familia::Encryption Module
+
+### manager
+
+Creates a manager instance with optional algorithm selection.
+
+```ruby
+# Use best available provider
+mgr = Familia::Encryption.manager
+
+# Use specific algorithm
+mgr = Familia::Encryption.manager(algorithm: 'xchacha20poly1305')
+```
+
+### encrypt
+
+Encrypts plaintext using the default provider.
+
+```ruby
+Familia::Encryption.encrypt(plaintext,
+  context: "User:favorite_snack:user123",
+  additional_data: nil
+)
+```
+
+### encrypt_with
+
+Encrypts plaintext with a specific algorithm.
+
+```ruby
+Familia::Encryption.encrypt_with('aes-256-gcm', plaintext,
+  context: "User:favorite_snack:user123",
+  additional_data: nil
+)
+```
+
+### decrypt
+
+Decrypts ciphertext (auto-detects algorithm from JSON).
+
+```ruby
+Familia::Encryption.decrypt(encrypted_json,
+  context: "User:favorite_snack:user123",
+  additional_data: nil
+)
+```
+
+### status
+
+Returns current encryption configuration and available providers.
+
+```ruby
+Familia::Encryption.status
+# => {
+#   default_algorithm: "xchacha20poly1305",
+#   available_algorithms: ["xchacha20poly1305", "aes-256-gcm"],
+#   preferred_available: "Familia::Encryption::Providers::XChaCha20Poly1305Provider",
+#   using_hardware: false,
+#   key_versions: [:v1],
+#   current_version: :v1
+# }
+```
+
+### benchmark
+
+Benchmarks available providers.
+
+```ruby
+Familia::Encryption.benchmark(iterations: 1000)
+# => {
+#   "xchacha20poly1305" => { time: 0.45, ops_per_sec: 4444, priority: 100 },
+#   "aes-256-gcm" => { time: 0.52, ops_per_sec: 3846, priority: 50 }
+# }
+```
+
+### validate_configuration!
+
+Validates encryption configuration at startup.
+
+```ruby
+Familia::Encryption.validate_configuration!
+# Raises Familia::EncryptionError if configuration invalid
+```
+
+### derivation_count / reset_derivation_count!
+
+Monitors key derivation operations (for testing and debugging).
+
+```ruby
+# Check how many key derivations have occurred
+count = Familia::Encryption.derivation_count.value
+# => 42
+
+# Reset counter
+Familia::Encryption.reset_derivation_count!
+```
+
+## Familia::Encryption::Manager
+
+Low-level manager class for direct provider control.
+
+### initialize
+
+```ruby
+# Use default provider
+manager = Familia::Encryption::Manager.new
+
+# Use specific algorithm
+manager = Familia::Encryption::Manager.new(algorithm: 'aes-256-gcm')
+```
+
+### encrypt / decrypt
+
+Same interface as module-level methods but tied to specific provider.
+
+## Familia::Encryption::Registry
+
+Provider management system.
+
+### setup!
+
+Registers all available providers.
+
+### get
+
+Returns provider instance by algorithm name.
+
+### default_provider
+
+Returns highest-priority available provider instance.
+
+### available_algorithms
+
+Returns array of available algorithm names.
+
+## Configuration
+
+### Familia.configure
+
+```ruby
+Familia.configure do |config|
+  # Single key configuration
+  config.encryption_keys = {
+    v1: ENV['FAMILIA_ENCRYPTION_KEY']
+  }
+  config.current_key_version = :v1
+
+  # Multi-version configuration
+  config.encryption_keys = {
+    v1_2024: ENV['OLD_KEY'],
+    v2_2025: ENV['NEW_KEY']
+  }
+  config.current_key_version = :v2_2025
+
+  # Key cache TTL (seconds)
+  config.key_cache_ttl = 300  # Default: 5 minutes
+end
+```
+
+## Data Types
+
+### EncryptedData
+
+Internal data structure for encrypted values.
+
+```ruby
+EncryptedData = Data.define(
+  :library,      # "libsodium" or "openssl"
+  :algorithm,    # "xchacha20poly1305" or "aes-256-gcm"
+  :nonce,        # Base64-encoded nonce/IV
+  :ciphertext,   # Base64-encoded ciphertext
+  :key_version   # Key version identifier
+)
+```
+
+### RedactedString
+
+String subclass that redacts sensitive data in output.
+
+```ruby
+class RedactedString < String
+  def to_s
+    '[REDACTED]'
+  end
+
+  def inspect
+    '[REDACTED]'
+  end
+end
+```
+
+## Exceptions
+
+### Familia::EncryptionError
+
+Raised for encryption/decryption failures.
+
+```ruby
+begin
+  user.decrypt_field(:favorite_snack)
+rescue Familia::EncryptionError => e
+  case e.message
+  when /key version/
+    # Handle key version mismatch
+  when /authentication/
+    # Handle tampering
+  else
+    # Handle other errors
+  end
+end
+```
+
+## CLI Commands
+
+### Generate Key
+
+```bash
+$ familia encryption:generate_key [--bits 256]
+# Outputs Base64-encoded key
+```
+
+### Verify Encryption
+
+```bash
+$ familia encryption:verify [--model User] [--field favorite_snack]
+# Verifies field encryption is working
+```
+
+### Rotate Keys
+
+```bash
+$ familia encryption:rotate [--from v1] [--to v2]
+# Migrates encrypted fields to new key
+```
+
+## Testing Helpers
+
+### EncryptionTestHelpers
+
+```ruby
+module Familia::EncryptionTestHelpers
+  # Set up test encryption keys
+  def with_test_encryption_keys(&block)
+
+  # Verify field is encrypted in storage
+  def assert_field_encrypted(model, field)
+
+  # Verify decryption works
+  def assert_decryption_works(model, field, expected)
+end
+```
+
+### RSpec Example
+
+```ruby
+RSpec.describe User do
+  include Familia::EncryptionTestHelpers
+
+  it "encrypts favorite snack field" do
+    with_test_encryption_keys do
+      user = User.create(favorite_snack: "chocolate chip cookies")
+
+      assert_field_encrypted(user, :favorite_snack)
+      assert_decryption_works(user, :favorite_snack, "chocolate chip cookies")
+    end
+  end
+end
+```
+
+## Performance Considerations
+
+### Key Derivation Caching
+
+```ruby
+# Automatic in web requests
+class ApplicationController
+  around_action :with_encryption_cache
+
+  def with_encryption_cache
+    Familia::Encryption.with_key_cache { yield }
+  end
+end
+```
+
+### Batch Operations
+
+```ruby
+# Efficient for bulk operations
+User.batch_decrypt(:favorite_snack) do |users|
+  users.each { |u| process(u.favorite_snack) }
+end
+```