RubyGems - familia - Versions diffs - 2.0.0.pre19 → 2.0.0.pre21 - Mend

familia 2.0.0.pre19 → 2.0.0.pre21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (372) hide show

data/docs/archive/FAMILIA_UPDATE.md DELETED Viewed

@@ -1,226 +0,0 @@
-# Familia v2.0.0-pre Series Update Overview
-**Familia** is a Ruby ORM for Redis/Valkey that provides object mapping and persistence capabilities. This document summarizes the major updates from v2.0.0-pre through v2.0.0-pre7, representing a significant evolution with new features, security enhancements, and architectural improvements.
-## Version Summary
-| Version | Focus | Key Features |
-|---------|-------|-------------|
-| v2.0.0-pre | Foundation | Modern API, Valkey support, connection pooling |
-| v2.0.0-pre5 | Security | Encrypted fields, transient fields, RedactedString |
-| v2.0.0-pre6 | Architecture | Horreum reorganization, enhanced persistence |
-| v2.0.0-pre7 | Relationships | Comprehensive relationship system, permissions |
----
-## v2.0.0-pre - Foundation Release
-### Major API Modernization
-- **Complete API redesign** for clarity and modern Ruby conventions
-- **Valkey compatibility** alongside traditional Valkey/Redis support
-- **Ruby 3.4+ modernization** with fiber and thread safety improvements
-- **Connection pooling foundation** with provider pattern architecture
-### Security & Dependency Management
-- **Critical security fixes** in Ruby workflow vulnerabilities
-- **Systematic dependency resolution** via multi-constraint optimization
-- **GitHub Actions security hardening** with matrix optimization
-### Documentation Infrastructure
-- **YARD documentation workflow** with automated GitHub Pages deployment
-- **Comprehensive wiki system** with structured documentation
-- **Developer-focused guides** for implementation and usage
----
-## v2.0.0-pre5 - Security Enhancement Release
-### Encrypted Fields System
-- **Field-level encryption** with transparent access patterns
-- **Multiple encryption providers**:
-  - XChaCha20-Poly1305 (preferred, requires rbnacl)
-  - AES-256-GCM (fallback, OpenSSL-based)
-- **Field-specific key derivation** for cryptographic domain separation
-- **Configurable key versioning** supporting key rotation
-```ruby
-class Vault < Familia::Horreum
-  feature :encrypted_fields
-  field :name                    # Plaintext
-  encrypted_field :secret_key    # Encrypted at rest
-  encrypted_field :api_token     # Transparent access
-end
-```
-### Transient Fields & RedactedString
-- **Non-persistent field storage** for sensitive runtime data
-- **RedactedString wrapper** preventing accidental logging/serialization
-- **Memory-safe handling** of sensitive data in Ruby objects
-- **API-safe serialization** excluding transient fields
-```ruby
-class User < Familia::Horreum
-  feature :transient_fields
-  field :email
-  transient_field :password      # Never persisted
-  transient_field :session_token # Runtime only
-end
-```
-### Connection Pooling Enhancement
-- **Connection provider pattern** for flexible pooling strategies
-- **Multi-database support** with intelligent pool management
-- **Thread-safe connection handling** for concurrent applications
-- **Configurable pool sizing** and timeout management
----
-## v2.0.0-pre6 - Architecture Enhancement Release
-### Horreum Architecture Reorganization
-- **Modular class structure** with cleaner separation of concerns
-- **Enhanced feature system** with dependency management
-- **Improved inheritance patterns** for better code organization
-- **Streamlined base class functionality**
-### Enhanced Persistence Operations
-- **New `save_if_not_exists` method** for conditional persistence
-- **Atomic persistence operations** with transaction support
-- **Enhanced error handling** for persistence failures
-- **Improved data consistency** guarantees
-### Security Improvements
-- **Encryption field security hardening** with additional validation
-- **Enhanced memory protection** for sensitive data handling
-- **Improved key management** patterns and best practices
-- **Security test suite expansion** with comprehensive coverage
----
-## v2.0.0-pre7 - Relationships & Permissions Release
-### Comprehensive Relationships System
-- **Three relationship types** optimized for different use cases:
-  - `participates_in` - Multi-presence tracking with score encoding
-  - `indexed_by` - O(1) hash-based lookups
-  - `member_of` - Bidirectional membership with collision-free naming
-```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-  identifier_field :custid
-  field :custid, :name, :email
-  # Define collections
-  set :domains
-  participates_in :active_users, type: :sorted_set
-end
-class Domain < Familia::Horreum
-  feature :relationships
-  identifier_field :domain_id
-  field :domain_id, :name
-  # Bidirectional relationship
-  member_of Customer, :domains, type: :set
-end
-```
-### Categorical Permission System
-- **Bit-encoded permissions** for efficient storage and querying
-- **Time-based permission scoring** for temporal access control
-- **Permission tier hierarchies** with inheritance patterns
-- **Scalable permission management** for large object collections
-### Advanced Relationship Features
-- **Score-based sorting** with custom scoring functions
-- **Permission-aware queries** filtering by access levels
-- **Relationship validation framework** ensuring data integrity
-- **Performance optimizations** for large-scale relationship operations
----
-## Breaking Changes & Migration
-### v2.0.0-pre Series
-- **API method renaming** for consistency and clarity
-- **Configuration changes** in connection management
-- **Feature activation syntax** updates for the new system
-- **Identifier field declaration** syntax modernization
-### Security Considerations
-- **Encryption key configuration** required for encrypted fields
-- **Memory handling changes** for sensitive data protection
-- **Permission system migration** for existing relationship data
----
-## Performance Improvements
-### Connection Management
-- **Pool-based connections** reducing connection overhead
-- **Intelligent connection reuse** across operations
-- **Concurrent operation support** with thread-safe pooling
-### Relationship Operations
-- **O(1) indexed lookups** for field-based queries
-- **Optimized sorted set operations** for scored relationships
-- **Batch relationship operations** for bulk updates
-- **Memory-efficient bit encoding** for permission storage
-### Feature System
-- **Lazy feature loading** reducing memory footprint
-- **Dependency-aware activation** preventing conflicts
-- **Optimized method dispatch** for feature methods
----
-## Migrating Guide Summary
-### From v1.x to v2.0.0-pre
-1. **Update connection configuration** to use new pooling system
-2. **Migrate identifier declarations** to new syntax
-3. **Update feature activations** to use `feature :name` syntax
-4. **Review method calls** for renamed API methods
-### Security Feature Adoption
-1. **Configure encryption keys** for encrypted fields
-2. **Identify sensitive fields** for encryption/transient marking
-3. **Update serialization code** to handle RedactedString
-4. **Implement key rotation procedures** for production systems
-### Relationship System Migration
-1. **Analyze existing relationships** for optimization opportunities
-2. **Choose appropriate relationship types** based on usage patterns
-3. **Implement permission systems** for access-controlled relationships
-4. **Update queries** to use new relationship methods
----
-## Next Steps & Roadmap
-### Immediate (v2.0.0 Final)
-- **Production stability** testing and bug fixes
-- **Performance benchmarking** and optimization
-- **Documentation completion** for all features
-- **Migration tooling** for existing applications
-### Future Releases
-- **Advanced encryption features** with hardware security modules
-- **Extended relationship types** for specialized use cases
-- **Performance analytics** and monitoring integration
-- **Cloud-native deployment** patterns and examples
----
-## Resources
-- [GitHub Repository](https://github.com/delano/familia)
-- [Wiki Documentation](https://github.com/delano/familia/wiki)
-- [API Reference](docs/wiki/API-Reference.md)
-- [Implementation Guide](docs/wiki/Implementation-Guide.md)
-- [Security Model](docs/wiki/Security-Model.md)

data/docs/archive/README.md DELETED Viewed

@@ -1,64 +0,0 @@
-# Archived Documentation
-This directory contains original documentation files that have either been migrated to the new Scriv-based changelog system or incorporated into other documents.
-## Migration Date
-**Sept 22, 1015** - Deprecated api-reference.md, to reduce surface area for stale documentation to hide.
-**Sept 1, 2025** - As part of implementing [Issue #84: Scriv-based changelog system](https://github.com/delano/familia/issues/84)
-## Archived Files
-### FAMILIA_UPDATE.md
-**Original Purpose:** Version summary table and detailed release notes for v2.0.0-pre series
-**Migrating Destinations:**
-- **Changelog entries** → Extracted to Scriv fragments, aggregated into `CHANGELOG.md`
-- **Migrating guides** → Reorganized into `docs/migrating/v2.0.0-pre*.md`
-- **Feature descriptions** → Cross-referenced with existing feature guides in `docs/guides/`
-### FAMILIA_RELATIONSHIPS.md
-**Original Purpose:** Auto-generated relationship methods reference
-**Migration Destination:**
-- **Complete content** → Moved to `docs/guides/relationships-methods.md`
-- **Cross-referenced** with existing `docs/guides/Relationships-Guide.md`
-### FAMILIA_TECHNICAL.md
-**Original Purpose:** Technical API reference for v2.0.0-pre series classes and methods
-**Migration Destination:**
-- **Core technical content** → Moved to `docs/reference/api-technical.md`
-- **Cross-referenced** with existing `docs/guides/API-Reference.md`
-## New Documentation Structure
-```
-docs/
-├── migrating/              # Version-specific migrating guides
-│   ├── v2.0.0-pre.md
-│   ├── v2.0.0-pre5.md      # Security features
-│   ├── v2.0.0-pre6.md      # Architecture improvements
-│   └── v2.0.0-pre7.md      # Relationships system
-│
-├── guides/                 # Feature-specific guides (moved from wiki/)
-│   ├── relationships.md    # From FAMILIA_RELATIONSHIPS.md
-│   └── [other guides...]
-│
-├── reference/              # Technical reference
-│   └── api-technical.md
-│
-└── archive/                # This directory
-```
-## Finding Migrated Content
-- **Version changes** → Check `CHANGELOG.md` (generated from fragments)
-- **How to upgrade** → See `docs/migration/` for version-specific guides
-- **Feature usage** → See `docs/guides/` for implementation examples
-- **API reference** → See `docs/reference/` for technical details
-## References
-- [Issue #84](https://github.com/delano/familia/issues/84) - Original migration plan
-- [Scriv Documentation](https://scriv.readthedocs.io/) - Changelog management tool
-- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard

data/docs/archive/api-reference.md DELETED Viewed

@@ -1,333 +0,0 @@
-# API Reference
-> [!NOTE]
-> This document is deprecated. For comprehensive encryption API documentation, see [`docs/reference/api-technical.md`](../reference/api-technical.md) which contains complete implementation details and examples.
-## Class Methods
-### encrypted_field
-Defines an encrypted field on a Familia::Horreum class.
-```ruby
-encrypted_field(name, aad_fields: [], **options)
-```
-**Parameters:**
-- `name` (Symbol) - Field name
-- `aad_fields` (Array<Symbol>) - Additional fields to include in authentication
-- `**options` (Hash) - Standard field options
-**Example:**
-```ruby
-class User < Familia::Horreum
-  feature :encrypted_fields
-  encrypted_field :favorite_snack
-  encrypted_field :api_key
-  encrypted_field :notes, aad_fields: [:user_id, :email]  # With tamper protection
-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 that return ConcealedString objects:
-```ruby
-user.favorite_snack           # Returns ConcealedString (safe for logging)
-user.favorite_snack.reveal   # Get actual decrypted value
-user.favorite_snack = value   # Set and encrypt value
-user.favorite_snack!          # Fast write (still encrypted)
-```
-**ConcealedString Methods:**
-```ruby
-concealed = user.favorite_snack
-concealed.to_s                # => "[CONCEALED]" (safe for logging)
-concealed.reveal              # => "actual value"
-concealed.clear!              # Clear from memory
-concealed.cleared?            # Check if cleared
-```
-## Familia::Encryption Module
-### with_request_cache
-Enables key derivation caching for performance optimization:
-```ruby
-Familia::Encryption.with_request_cache do
-  # Multiple encryption operations reuse derived keys
-  user.secret_one = "value1"
-  user.secret_two = "value2"
-  user.save
-end
-```
-### clear_request_cache!
-Manually clears the request-level key cache:
-```ruby
-Familia::Encryption.clear_request_cache!
-```
-### encrypt / decrypt
-Low-level encryption methods (typically used internally):
-```ruby
-# Encrypt with context for key derivation
-encrypted = Familia::Encryption.encrypt(plaintext,
-  context: "User:favorite_snack:user123",
-  additional_data: nil
-)
-# Decrypt (auto-detects algorithm from JSON)
-decrypted = 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 for key rotation
-  config.encryption_keys = {
-    v1_2024: ENV['OLD_KEY'],
-    v2_2025: ENV['NEW_KEY']
-  }
-  config.current_key_version = :v2_2025
-  # Optional personalization (XChaCha20-Poly1305 only)
-  config.encryption_personalization = 'MyApp-2024'
-end
-# Always validate configuration
-Familia::Encryption.validate_configuration!
-```
-## 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
-)
-```
-### ConcealedString
-String-like object that conceals sensitive data in output and provides memory safety.
-```ruby
-class ConcealedString
-  def reveal
-    # Returns actual decrypted string value
-  end
-  def to_s
-    '[CONCEALED]'
-  end
-  def inspect
-    '[CONCEALED]'
-  end
-  def clear!
-    # Best-effort memory wiping
-  end
-  def cleared?
-    # Returns true if cleared from memory
-  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
-```
-## Instance Methods
-### encrypted_data?
-Check if any encrypted fields have values:
-```ruby
-user.encrypted_data?  # => true if any encrypted fields have values
-```
-### clear_encrypted_fields!
-Clear all encrypted field values from memory:
-```ruby
-user.clear_encrypted_fields!  # Clear all ConcealedString values
-```
-### encrypted_fields_cleared?
-Check if all encrypted fields have been cleared:
-```ruby
-user.encrypted_fields_cleared?  # => true if all cleared
-```
-### re_encrypt_fields!
-Re-encrypt all encrypted fields with current key version:
-```ruby
-user.re_encrypt_fields!  # Uses current_key_version
-user.save
-```
-### encrypted_fields_status
-Get encryption status for debugging:
-```ruby
-user.encrypted_fields_status
-# => {
-#   ssn: { encrypted: true, cleared: false },
-#   credit_card: { encrypted: true, cleared: true }
-# }
-```
----
-> [!IMPORTANT]
-> For complete implementation details, configuration examples, and advanced usage patterns, see the comprehensive documentation in [`docs/reference/api-technical.md`](../reference/api-technical.md).