domain_extractor 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3a08e0e813341f588f96df2c7ec48eede21b5e93b6f46e127d15b2266439919
-  data.tar.gz: f05739738dda333fa4793397f4c51c047574d2c94e591ed6c76904f8cdc51fe7
+  metadata.gz: 0b791db73463bab1af5200390a77607e87094609a4982c267cf45462648edb09
+  data.tar.gz: 1202be56be2eb390bbd767e2c60369a61268261fefe5c593acdb064d586e7431
 SHA512:
-  metadata.gz: f1d4c335712a677707d7fedb966924e9f9a2f0e06f9084fc5ab1075d5d620ae51cd390a2e5013245e6fb9ec3d32563ed7c090d989807e86d01a304ac8ba6d9bc
-  data.tar.gz: 143f192445d137c456668c44e260cf96183ca0afae22be308e884f9fa9c9248cbf43b5608466412fc0734e652565c72bea45990bc4d038ac20934b854f6b929f
+  metadata.gz: 957f691b10eb6bd705646cf192c9c3fecf84a246a3a76e8e5f29406d38b97f52277006bfaa9e09fc334eb3594eeae61c977e05eb95c10021d7cdce6a27ae8325
+  data.tar.gz: 205629c265724025d48c9d25318c78ede7d6bccf93486cae0b5957a4094ef94a46dde00a5b97540517c4b2f5244025e5ace4eb9de6bf4c6f0e0a7477692897e7

data/CHANGELOG.md

@@ -5,6 +5,274 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9] - 2026-03-11
+
+### Added - URI-Compatible Accessors and Authentication Extraction
+
+This major release adds a much broader **URI-compatible API for common absolute-URL workflows** along with new authentication extraction, URI manipulation helpers, and expanded documentation.
+
+#### 🔐 Authentication Extraction
+
+**Comprehensive userinfo parsing** for database connections, Redis, FTP, SFTP, and any URL scheme with embedded credentials:
+
+- `user` - Extract username from URL
+- `password` - Extract password from URL
+- `userinfo` - Complete userinfo string (user:password)
+- `decoded_user` - Percent-decoded username (handles special characters)
+- `decoded_password` - Percent-decoded password (handles special characters)
+
+**Supported URL Schemes:**
+
+- **Redis/Rediss**: `redis://username:password@host:6379/0`, `rediss://:password@host:6380`
+- **PostgreSQL**: `postgresql://user:pass@localhost:5432/dbname`
+- **MySQL**: `mysql://user:pass@host:3306/database`
+- **MongoDB**: `mongodb+srv://user:pass@cluster.mongodb.net/db`
+- **FTP/SFTP/FTPS**: `ftp://user:pass@host/path`, `sftp://user:pass@host:22/path`
+- **HTTP/HTTPS**: `https://user:pass@api.example.com` (deprecated but supported)
+
+**Special Character Handling:**
+
+- Automatic percent-decoding of credentials with `@`, `:`, and other special characters
+- `decoded_user` and `decoded_password` provide clean, usable credentials
+- Handles edge cases: password-only (`:password`), username-only, empty passwords
+
+#### 🔧 Complete URI Component Access
+
+**Common URI components** are now accessible as both getters and setters:
+
+**Read Access:**
+
+- `scheme` - URL scheme (http, https, redis, postgresql, etc.)
+- `host` - Host value for the parsed URI
+- `hostname` - Hostname helper for URI-style access
+- `port` - Port number
+- `path` - URL path
+- `query` - Raw query string
+- `fragment` - Fragment/anchor (#section)
+- `user`, `password`, `userinfo` - Authentication components
+- `subdomain`, `domain`, `tld`, `root_domain` - Domain components (existing)
+
+**Write Access (Setter Methods):**
+
+- `scheme=`, `host=`, `hostname=`, `port=`, `path=`, `query=`, `fragment=`
+- `user=`, `password=`, `userinfo=`
+- Enables programmatic URI construction and modification
+
+#### 🛠️ Authentication Helper Methods
+
+**Basic Authentication:**
+
+```ruby
+# Generate Authorization header from parsed URL
+result = DomainExtractor.parse('https://user:pass@api.example.com')
+result.basic_auth_header
+# => "Basic dXNlcjpwYXNz"
+
+# Or use module method directly
+DomainExtractor.basic_auth_header('user', 'password')
+# => "Basic dXNlcjpwYXNzd29yZA=="
+```
+
+**Bearer Token Authentication:**
+
+```ruby
+DomainExtractor.bearer_auth_header('eyJhbGciOiJIUzI1NiIs...')
+# => "Bearer eyJhbGciOiJIUzI1NiIs..."
+```
+
+**Credential Encoding/Decoding:**
+```ruby
+# Encode credentials for URL use (percent-encoding)
+DomainExtractor.encode_credential('P@ss:word!')
+# => "P%40ss%3Aword%21"
+
+# Decode percent-encoded credentials
+DomainExtractor.decode_credential('P%40ss%3Aword%21')
+# => "P@ss:word!"
+```
+
+#### 🌐 Advanced URI Methods
+
+**URI Manipulation:**
+- `merge(relative_url)` - Merge with relative URL (RFC 2396 compliant)
+- `normalize` - Normalize URI (lowercase scheme/host, remove default ports)
+- `absolute?` - Check if URI is absolute
+- `relative?` - Check if URI is relative
+- `default_port` - Get default port for scheme (80 for http, 443 for https, 6379 for redis, etc.)
+- `build_url` - Reconstruct complete URL from components
+
+**Proxy Detection:**
+- `find_proxy` - Automatic proxy detection from environment variables
+- Checks scheme-specific proxy variables, falls back to `http_proxy` / `HTTP_PROXY`, and respects `no_proxy`
+- Returns proxy URI or nil
+
+**Alias Methods for URI Compatibility:**
+- `to_str` - Alias for `to_s`
+- `hostname` - URI-style hostname accessor
+- `query` - Raw query string access
+
+#### 📊 Real-World Use Cases
+
+**Database Connection Parsing:**
+```ruby
+db_url = 'postgresql://appuser:SecurePass@db.prod.internal:5432/production'
+result = DomainExtractor.parse(db_url)
+
+result.user           # => "appuser"
+result.password       # => "SecurePass"
+result.host           # => "db.prod.internal"
+result.port           # => 5432
+result.path           # => "/production"
+```
+
+**Redis Connection with Special Characters:**
+```ruby
+redis_url = 'rediss://default:P%40ss%3Aword@redis.cloud:6385/0'
+result = DomainExtractor.parse(redis_url)
+
+result.password         # => "P%40ss%3Aword"
+result.decoded_password # => "P@ss:word"
+result.scheme           # => "rediss"
+result.port             # => 6385
+```
+
+**API Authentication Header Generation:**
+```ruby
+api_url = 'https://nick@untappd.com:MySuperAPIToken123@api.untappd.com/v4'
+result = DomainExtractor.parse(api_url)
+
+# Generate Basic Auth header
+auth_header = result.basic_auth_header
+# Use in HTTP request:
+# headers['Authorization'] = auth_header
+```
+
+**FTP/SFTP Deployment:**
+```ruby
+deploy_url = 'sftp://deploy_user:DeployKey123@deployment.internal:22/var/www/app'
+result = DomainExtractor.parse(deploy_url)
+
+result.user     # => "deploy_user"
+result.password # => "DeployKey123"
+result.host     # => "deployment.internal"
+result.port     # => 22
+result.path     # => "/var/www/app"
+```
+
+#### 🔒 Security Considerations
+
+**Important Security Notes:**
+- Embedding credentials in URLs is **deprecated** per RFC 3986 and should be avoided in production
+- Use environment variables, secret managers, or secure vaults for credential storage
+- The library supports credential extraction for **legacy systems** and **configuration parsing**
+- Always use HTTPS/TLS when credentials must be transmitted
+- Never log URLs containing credentials
+- Consider using header-based authentication (Bearer tokens, API keys) instead
+
+**Safe Credential Handling:**
+```ruby
+# ✅ Good: Parse from environment variable
+db_url = ENV['DATABASE_URL']
+config = DomainExtractor.parse(db_url)
+
+# ✅ Good: Extract and use separately
+username = config.decoded_user
+password = config.decoded_password
+# Pass to connection library without logging URL
+
+# ❌ Bad: Hardcode credentials in source
+db_url = 'postgresql://user:password@localhost/db'  # Don't do this!
+```
+
+#### 🚀 Performance
+
+**Maintains Performance-First Design:**
+- All new features use frozen constants and optimized string operations
+- Auth extraction adds <5μs overhead per parse
+- Core hot paths remain allocation-conscious
+- Thread-safe stateless modules
+- Full parse throughput depends on host complexity; see the benchmark docs for measured results
+
+#### 🔄 URI-Style Access
+
+**Common URI-style access with additional domain helpers:**
+```ruby
+# Before (using URI)
+uri = URI.parse('https://user:pass@example.com:8080/path?query=value#section')
+uri.scheme    # => "https"
+uri.user      # => "user"
+uri.password  # => "pass"
+uri.host      # => "example.com"
+uri.port      # => 8080
+
+# After (using DomainExtractor) - identical API
+result = DomainExtractor.parse('https://user:pass@example.com:8080/path?query=value#section')
+result.scheme    # => "https"
+result.user      # => "user"
+result.password  # => "pass"
+result.host      # => "example.com"
+result.port      # => 8080
+
+# PLUS: Additional domain parsing features
+result.subdomain     # => nil
+result.domain        # => "example"
+result.tld           # => "com"
+result.root_domain   # => "example.com"
+
+# PLUS: Decoded credentials
+result.decoded_user     # => "user"
+result.decoded_password # => "pass"
+
+# PLUS: Authentication helpers
+result.basic_auth_header # => "Basic dXNlcjpwYXNz"
+```
+
+#### 📦 Implementation Details
+
+**New Modules:**
+- `DomainExtractor::Auth` - Authentication component extraction with percent-decoding
+- `DomainExtractor::URIHelpers` - Advanced URI manipulation and helper methods
+
+**Enhanced Modules:**
+- `DomainExtractor::Parser` - Now extracts auth components and additional URI parts
+- `DomainExtractor::Result` - Builds results with auth and URI components
+- `DomainExtractor::ParsedURL` - Extended with URI-compatible methods and setters
+
+**Code Quality:**
+- 200+ comprehensive test cases covering all scenarios
+- RuboCop clean with zero offenses
+- 100% backward compatible - no breaking changes
+- Extensive documentation with real-world examples
+
+#### 🎯 Migration from URI Library
+
+**Low-friction migration for common absolute-URL use cases:**
+```ruby
+# Swap URI.parse for DomainExtractor.parse
+# Before:
+require 'uri'
+uri = URI.parse(url)
+
+# After:
+require 'domain_extractor'
+uri = DomainExtractor.parse(url)
+
+# Common URI-style accessors continue to work, plus you get:
+# - Multi-part TLD support
+# - Domain component extraction
+# - Decoded credentials
+# - Authentication helpers
+# - Better performance
+```
+
+#### 📚 Documentation
+
+- Comprehensive CHANGELOG with all features documented
+- README updated with authentication examples
+- Real-world use cases for Redis, databases, FTP, APIs
+- Security best practices section
+- Migration guide from URI library
+
 ## [0.2.7] - 2025-11-09
 
 ### Added - URL Formatting API

data/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2025, OpenSite AI. All rights reserved.
+Copyright (c) 2026, OpenSite AI. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met: