vectra-client 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a003ec47ff2de6ec1977426169ffe1739f5fc9ba07cfcd717ca9cb88fd398f
-  data.tar.gz: ed77f5c22fd580990ee4beaa1840175329c3feda9dd9b6087ad6ff93fec9743a
+  metadata.gz: 2d3586fe349f6746ba939c2596bf5b1110551a8e7ed16a8dc6581eaa2f91af81
+  data.tar.gz: 11d141983fba57e97fc0d96792f75e8e2e50eac453671ddb25ce8456002acac2
 SHA512:
-  metadata.gz: aa3f0556520ceb6677816ffa26ec4beac0fa85f660bdebf28578f47b834c43b87ab5208057ca81b96a9e52a9dd3e645e1c406ceab254a2ade5c716fdcb7a497d
-  data.tar.gz: 55c2e660ba45abc710cd6d9bc978df5d6c5f23e1e9c058359e719d4d2d43e523af30207fa2ad5b049eb87b698c52c5adf59fe37c4619224986a3c0295d8a408f
+  metadata.gz: 6396f52e61633d9b2eed5502edbc80f8c001d85aea638afad4ff5c377e7d141ca80dd6198ace23808324411355924b2e653aa661e157fa4ae33c0b905bf31e4d
+  data.tar.gz: 1581ca62c63111caaf6fc26ced7503a101ceb30c8a0531b3fa454a0ac10376446f5a358dfbb29f045de9ba799114803af02b6a021828debc8df14cab129a5147

data/CHANGELOG.md

@@ -7,7 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2025-01-08
+### Added
+
+- **Proactive Rate Limiting** (`Vectra::RateLimiter`)
+  - Token bucket algorithm for smooth rate limiting
+  - Burst support for handling traffic spikes
+  - Per-provider rate limiter registry
+  - `RateLimitedClient` wrapper for automatic throttling
+  - Prevents API rate limit errors before they occur
+
+- **Structured JSON Logging** (`Vectra::JsonLogger`)
+  - Machine-readable JSON log format
+  - Automatic operation logging via instrumentation
+  - Custom metadata support
+  - Integration with standard Ruby Logger via `JsonFormatter`
+  - Log levels: debug, info, warn, error, fatal
+
+- **Health Check Functionality** (`Vectra::HealthCheck`)
+  - Built-in `client.health_check` method
+  - Connectivity and latency testing
+  - Optional index statistics inclusion
+  - Pool health checking for pgvector
+  - `AggregateHealthCheck` for multi-provider setups
+  - JSON-serializable results
+
+- **Error Tracking Integrations**
+  - Sentry adapter with breadcrumbs, context, and fingerprinting
+  - Honeybadger adapter with severity tags and configurable notifications
+  - Automatic error context and grouping
+
+- **Circuit Breaker Pattern** (`Vectra::CircuitBreaker`)
+  - Three-state circuit (closed, open, half-open)
+  - Automatic failover with fallback support
+  - Per-provider circuit registry
+  - Thread-safe implementation
+  - Configurable failure/success thresholds
+
+- **Credential Rotation** (`Vectra::CredentialRotator`)
+  - Zero-downtime API key rotation
+  - Pre-rotation validation
+  - Rollback support
+  - Multi-provider rotation manager
+  - Per-provider rotation tracking
+
+- **Audit Logging** (`Vectra::AuditLog`)
+  - Structured audit events for compliance
+  - Access, authentication, authorization logging
+  - Configuration change tracking
+  - Credential rotation audit trail
+  - Automatic API key sanitization
+  - Global audit logging support
+
+## [v0.3.2](https://github.com/stokry/vectra/tree/v0.3.2) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.1...v0.3.2)
+
+### Fixed
+
+- Audit log keyword parameter ordering and optional fields now align with linting and usage expectations.
+- Credential rotation utilities use symbol procs and string interpolation while keeping the existing `switch_to_secondary` API.
+
+## [v0.3.1](https://github.com/stokry/vectra/tree/v0.3.1) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.0...v0.3.1)
+
+## [v0.3.0](https://github.com/stokry/vectra/tree/v0.3.0) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.2...v0.3.0)
 
 ### Added
 
@@ -52,7 +118,13 @@ New configuration options:
 
 - Added `concurrent-ruby ~> 1.2` for thread-safe operations
 
-## [0.2.1] - 2025-01-08
+## [v0.2.2](https://github.com/stokry/vectra/tree/v0.2.2) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.1...v0.2.2)
+
+## [v0.2.1](https://github.com/stokry/vectra/tree/v0.2.1) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.0...v0.2.1)
 
 ### Added
 
@@ -77,9 +149,11 @@ New configuration options:
 - ✅ Pinecone - Fully implemented
 - ✅ pgvector (PostgreSQL) - Fully implemented
 - ✅ Qdrant - Fully implemented
-- 🚧 Weaviate - Stub implementation (planned for v0.3.0)
+- 🚧 Weaviate - Stub implementation (planned for v0.4.0)
+
+## [v0.2.0](https://github.com/stokry/vectra/tree/v0.2.0) (2026-01-08)
 
-## [0.2.0] - 2025-01-08
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.1.3...v0.2.0)
 
 ### Added
 
@@ -102,7 +176,13 @@ New configuration options:
 - Added IMPLEMENTATION_GUIDE.md for developers implementing new features
 - Added NEW_FEATURES_v0.2.0.md with migration guide
 
-## [0.1.1] - 2025-01-07
+## [v0.1.3](https://github.com/stokry/vectra/tree/v0.1.3) (2026-01-07)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.1.1...v0.1.3)
+
+## [v0.1.1](https://github.com/stokry/vectra/tree/v0.1.1) (2026-01-07)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/0ab2ea7b42d7fbf0b540b24889cc2b24254fef2e...v0.1.1)
 
 ### Added
 
@@ -121,37 +201,6 @@ New configuration options:
 - Updated gemspec description to include pgvector
 - Added `pg` gem as development dependency
 
-## [0.1.0] - 2024-XX-XX
-
-### Added
-
-- Initial release
-- Pinecone provider with full support for:
-  - Vector upsert, query, fetch, update, delete operations
-  - Index management (list, describe, create, delete)
-  - Namespace support
-  - Metadata filtering
-- Configuration system with global and per-client options
-- Automatic retry logic with exponential backoff
-- Comprehensive error handling with specific error classes:
-  - `AuthenticationError` - API key issues
-  - `RateLimitError` - Rate limiting with retry-after
-  - `NotFoundError` - Resource not found
-  - `ValidationError` - Invalid request parameters
-  - `ServerError` - Server-side errors
-  - `ConnectionError` - Network issues
-  - `TimeoutError` - Request timeouts
-- `Vector` class for vector representation with:
-  - Cosine similarity calculation
-  - Euclidean distance calculation
-  - Metadata support
-- `QueryResult` class with Enumerable support:
-  - Score filtering
-  - Easy iteration
-  - Result statistics
-- Full RSpec test suite
-- YARD documentation
-
 ## Planned
 
 ### [0.4.0]
@@ -164,4 +213,4 @@ New configuration options:
 
 - Background job integration (Sidekiq, GoodJob)
 - Production-ready with full documentation
-- Performance monitoring dashboard
+- Performance monitoring dashboard

data/SECURITY.md

@@ -46,30 +46,100 @@ We will:
 
 ### API Key Management
 
+**CRITICAL: Always use environment variables or secure vaults for API keys.**
+
 - **Never commit API keys** to version control
-- Store API keys in environment variables or secure vaults
+- Store API keys in environment variables or secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)
 - Use different API keys for development, staging, and production
-- Rotate API keys regularly
+- Rotate API keys regularly (every 90 days recommended)
 - Limit API key permissions to minimum required access
+- Monitor API key usage for anomalies
 
 ```ruby
 # ✅ Good - Use environment variables
 Vectra.configure do |config|
-  config.api_key = ENV['PINECONE_API_KEY']
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']  # Set in environment
+  config.environment = ENV['PINECONE_ENVIRONMENT'] || 'us-east-1'
+end
+
+# ✅ Good - Use Rails credentials (encrypted)
+Vectra.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:pinecone, :api_key)
+end
+
+# ✅ Good - Use AWS Secrets Manager
+require 'aws-sdk-secretsmanager'
+secrets = Aws::SecretsManager::Client.new
+secret = JSON.parse(secrets.get_secret_value(secret_id: 'vectra/pinecone').secret_string)
+
+Vectra.configure do |config|
+  config.api_key = secret['api_key']
 end
 
 # ❌ Bad - Hardcoded API key
 Vectra.configure do |config|
-  config.api_key = "pk-123456789"  # Never do this!
+  config.api_key = "pk-123456789"  # NEVER DO THIS!
 end
+
+# ❌ Bad - API key in config file
+# config/vectra.yml
+# api_key: "pk-123456789"  # This will be committed to git!
+```
+
+### Credential Rotation
+
+Use built-in credential rotation helpers for zero-downtime key rotation:
+
+```ruby
+require 'vectra/credential_rotation'
+
+# Setup rotation
+rotator = Vectra::CredentialRotator.new(
+  primary_key: ENV['PINECONE_API_KEY'],
+  secondary_key: ENV['PINECONE_API_KEY_NEW'],
+  provider: :pinecone
+)
+
+# Test new key before switching
+if rotator.test_secondary
+  rotator.switch_to_secondary
+  puts "Rotation complete!"
+else
+  puts "New key validation failed - keeping primary"
+end
+
+# Rollback if needed
+rotator.rollback
 ```
 
+**Rotation Best Practices:**
+
+1. **Test new credentials** before switching
+2. **Monitor for errors** after rotation
+3. **Keep old key active** for 24-48 hours after rotation
+4. **Rotate during low-traffic periods** when possible
+5. **Use gradual migration** for high-traffic systems
+
 ### Network Security
 
 - Always use HTTPS for API connections (enforced by default)
 - Verify SSL certificates (enabled by default)
 - Use VPN or private networks when possible
 - Monitor API usage for unusual patterns
+- **mTLS Support**: For providers that support mutual TLS, configure client certificates
+
+```ruby
+# mTLS configuration (provider-specific)
+# Note: mTLS support depends on provider capabilities
+# For pgvector, use SSL connection parameters:
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.host = "postgresql://user:pass@host/db?sslmode=verify-full&sslcert=/path/to/client.crt&sslkey=/path/to/client.key"
+end
+
+# For cloud providers, check provider documentation for mTLS setup
+```
 
 ### Data Security
 
@@ -137,6 +207,7 @@ end
 - Monitor for authentication failures
 - Track unusual query patterns
 - Set up alerts for rate limit violations
+- **Enable audit logging** for compliance requirements
 
 ```ruby
 # ❌ Bad - Logs API key
@@ -144,8 +215,67 @@ logger.info("Using API key: #{config.api_key}")
 
 # ✅ Good - Logs without sensitive data
 logger.info("Initializing Vectra client for #{config.provider}")
+
+# ✅ Good - Use audit logging for security events
+require 'vectra/audit_log'
+
+audit = Vectra::AuditLog.new(output: "log/audit.json.log")
+
+# Log access events
+audit.log_access(
+  user_id: current_user.id,
+  operation: "query",
+  index: "sensitive-data",
+  result_count: 10
+)
+
+# Log authentication events
+audit.log_authentication(
+  user_id: user.id,
+  success: true,
+  provider: "pinecone"
+)
+
+# Log credential rotations
+audit.log_credential_rotation(
+  provider: "pinecone",
+  success: true,
+  rotated_by: admin_user.id
+)
+```
+
+### Audit Logging
+
+For compliance and security auditing:
+
+```ruby
+# Setup global audit logging
+Vectra::AuditLogging.setup!(
+  output: "log/audit.json.log",
+  app: "my-service",
+  env: Rails.env
+)
+
+# Automatic audit logging for operations
+Vectra::Instrumentation.on_operation do |event|
+  Vectra::AuditLogging.log(:access,
+    user_id: current_user&.id,
+    operation: event.operation,
+    index: event.index,
+    success: event.success?
+  )
+end
 ```
 
+**Audit Log Events:**
+- `access` - Data access operations
+- `authentication` - Auth success/failure
+- `authorization` - Permission checks
+- `configuration_change` - Config modifications
+- `credential_rotation` - Key rotations
+- `data_modification` - Upsert/delete/update
+- `error` - Security-relevant errors
+
 ## Known Security Considerations
 
 ### API Key Exposure

data/docs/_layouts/page.html

@@ -35,6 +35,8 @@
           <li><a href="{{ site.baseurl }}/guides/installation" class="tma-sidebar__link {% if page.url == '/guides/installation/' %}tma-sidebar__link--active{% endif %}">Installation</a></li>
           <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-sidebar__link {% if page.url == '/guides/getting-started/' %}tma-sidebar__link--active{% endif %}">Quick Start</a></li>
           <li><a href="{{ site.baseurl }}/guides/performance" class="tma-sidebar__link {% if page.url == '/guides/performance/' %}tma-sidebar__link--active{% endif %}">Performance</a></li>
+          <li><a href="{{ site.baseurl }}/guides/monitoring" class="tma-sidebar__link {% if page.url == '/guides/monitoring/' %}tma-sidebar__link--active{% endif %}">Monitoring</a></li>
+          <li><a href="{{ site.baseurl }}/guides/security" class="tma-sidebar__link {% if page.url == '/guides/security/' %}tma-sidebar__link--active{% endif %}">Security</a></li>
         </ul>
       </div>