Familia v2.0 Documentation

Welcome to the comprehensive documentation for Familia v2.0. This wiki covers all major features including security, connection management, architecture, and object relationships.

📚 Documentation Structure

🔐 Security & Data Protection

  1. Encrypted Fields Overview - Persistent encrypted storage with modular providers
  2. Transient Fields Guide - Non-persistent secure data handling with RedactedString
  3. Security Model - Cryptographic design and Ruby memory limitations

🏗️ Architecture & System Design

  1. Feature System Guide - Modular architecture with dependencies and conflict resolution (new!)
  2. Connection Pooling Guide - Provider pattern for efficient Redis/Valkey pooling (new!)
  3. Relationships Guide - Object relationships and membership system (new!)

🛠️ Implementation & Usage

  1. Implementation Guide - Configuration, providers, and advanced usage
  2. API Reference - Complete class and method documentation

🚀 Operations (As Needed)

  1. Migrating Guide - Upgrading existing fields (coming soon)
  2. Key Management - Rotation and best practices (coming soon)

🚀 Quick Start Examples

Encrypted Fields (Persistent)

```ruby class User < Familia::Horreum feature :encrypted_fields encrypted_field :secret_recipe end

Configure encryption

Familia.configure do |config| config.encryption_keys = { v1: ENV[‘FAMILIA_ENCRYPTION_KEY’] } config.current_key_version = :v1 end

user = User.new(secret_recipe: “donna’s cookies”) user.save user.secret_recipe # => “donna’s cookies” (automatically decrypted) ```

Feature System (Modular)

```ruby class Customer < Familia::Horreum feature :safe_dump # API-safe serialization feature :expiration # TTL support feature :encrypted_fields # Secure storage

field :name, :email encrypted_field :api_key default_expiration 24.hours safe_dump_fields :name, :email end ```

Connection Pooling (Performance)

```ruby # Configure connection provider for multi-database pooling Familia.connection_provider = lambda do |uri| parsed = URI.parse(uri) pool_key = “#parsedparsed.host:#parsedparsed.port/#|| 0”

@pools[pool_key] ||= ConnectionPool.new(size: 10) do Redis.new(host: parsed.host, port: parsed.port, db: parsed.db || 0) end

@pools[pool_key].with { |conn| conn } end ```

Object Relationships

```ruby class Customer < Familia::Horreum feature :relationships identifier_field :custid field :custid, :name, :email

# Customer collections set :domains end

class Domain < Familia::Horreum feature :relationships identifier_field :domain_id field :domain_id, :name, :dns_zone

# Declare membership in customer collections member_of Customer, :domains, type: :set end

Create objects and establish relationships

customer = Customer.new(custid: “cust123”, name: “Acme Corp”) domain = Domain.new(domain_id: “dom456”, name: “acme.com”)

Establish bidirectional relationship

domain.add_to_customer_domains(customer.custid) customer.domains.add(domain.identifier)

Query relationships

domain.in_customer_domains?(customer.custid) # => true customer.domains.member?(domain.identifier) # => true ```