synthra 0.1.0

data/docs/API_SERVER.md

@@ -0,0 +1,278 @@
+# Production API Server
+
+FakeDataDSL includes a **production-ready REST API server** for data generation. Use it as the core of your data generation platform.
+
+## Quick Start
+
+```bash
+# Start server with default settings
+fake_data_dsl server schemas/ --port 3000
+
+# Start with authentication
+fake_data_dsl server schemas/ --port 3000 --api-key secret123
+
+# Production mode with rate limiting
+fake_data_dsl server schemas/ --port 3000 --env production --rate-limit 100
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-d, --dir DIR` | Schema directory | Required |
+| `-p, --port PORT` | Server port | 3000 |
+| `-h, --host HOST` | Bind address | 0.0.0.0 |
+| `-e, --env ENV` | Environment | development |
+| `--no-cors` | Disable CORS | CORS enabled |
+| `--rate-limit N` | Requests/minute | 0 (unlimited) |
+| `--api-key KEY` | Require API key | None |
+
+## API Endpoints
+
+### List Schemas
+
+```bash
+GET /api/schemas
+```
+
+Response:
+```json
+{
+  "schemas": [
+    { "name": "User", "fields": 5, "endpoint": "/api/user" },
+    { "name": "Order", "fields": 8, "endpoint": "/api/order" }
+  ]
+}
+```
+
+### Generate Single Record
+
+```bash
+GET /api/:schema?seed=42&mode=random
+```
+
+Query Parameters:
+- `seed` - Random seed for deterministic output
+- `mode` - Generation mode: random, edge, invalid, hostile, mixed
+
+Response:
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+
+### Generate Batch
+
+```bash
+GET /api/:schema/batch?count=100&seed=42
+```
+
+Response:
+```json
+{
+  "data": [...],
+  "meta": {
+    "count": 100,
+    "schema": "User",
+    "seed": 42,
+    "mode": "random"
+  }
+}
+```
+
+### Stream Records
+
+```bash
+GET /api/:schema/stream?count=1000
+```
+
+Returns NDJSON (newline-delimited JSON) for streaming:
+```
+{"id":"...","name":"John"}
+{"id":"...","name":"Jane"}
+```
+
+### Generate with Overrides
+
+```bash
+POST /api/:schema
+Content-Type: application/json
+
+{
+  "count": 10,
+  "seed": 42,
+  "mode": "random",
+  "overrides": {
+    "role": "admin",
+    "active": true
+  }
+}
+```
+
+### Get Schema Info
+
+```bash
+GET /api/:schema/schema
+```
+
+### Export OpenAPI/Protobuf
+
+```bash
+GET /api/:schema/openapi
+GET /api/:schema/protobuf
+```
+
+## Ruby API
+
+```ruby
+require 'fake_data_dsl'
+
+# Start server
+FakeDataDSL::APIServer.start(
+  schema_dir: "schemas/",
+  port: 3000,
+  host: "0.0.0.0",
+  environment: :production,
+  cors: true,
+  rate_limit: 100,
+  auth: { type: :api_key, keys: ["secret123"] },
+  enable_metrics: true,
+  enable_caching: true,
+  cache_ttl: 60
+)
+
+# Start in background
+thread = FakeDataDSL::APIServer.new(schema_dir: "schemas/").start_async
+```
+
+## Rack Integration
+
+Deploy with Puma, Unicorn, or any Rack-compatible server:
+
+```ruby
+# config.ru
+require 'fake_data_dsl'
+
+run FakeDataDSL::APIServer.rack_app(
+  schema_dir: "schemas/",
+  auth: { type: :api_key, keys: [ENV['API_KEY']] }
+)
+```
+
+Then run:
+```bash
+puma config.ru -p 3000 -t 4:16
+```
+
+## Authentication
+
+### API Key
+
+```ruby
+FakeDataDSL::APIServer.start(
+  schema_dir: "schemas/",
+  auth: { type: :api_key, keys: ["key1", "key2"] }
+)
+```
+
+Clients must include:
+```
+X-API-Key: key1
+```
+
+### Bearer Token
+
+```ruby
+FakeDataDSL::APIServer.start(
+  schema_dir: "schemas/",
+  auth: { type: :bearer, tokens: ["token1", "token2"] }
+)
+```
+
+Clients must include:
+```
+Authorization: Bearer token1
+```
+
+## Rate Limiting
+
+```ruby
+FakeDataDSL::APIServer.start(
+  schema_dir: "schemas/",
+  rate_limit: 100  # 100 requests per minute per IP
+)
+```
+
+When rate limited, returns:
+```json
+{
+  "error": "Rate limit exceeded",
+  "retry_after": 45
+}
+```
+
+## Metrics
+
+Enable metrics with `enable_metrics: true`:
+
+```bash
+GET /metrics
+```
+
+Response:
+```json
+{
+  "total_requests": 1250,
+  "endpoints": [
+    {
+      "endpoint": "GET /api/user",
+      "requests": 500,
+      "errors": 2,
+      "avg_duration_ms": 15.5,
+      "p99_duration_ms": 45.2
+    }
+  ]
+}
+```
+
+## Configuration
+
+All configuration options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | Integer | 3000 | Server port |
+| `host` | String | "0.0.0.0" | Bind address |
+| `environment` | Symbol | :development | :development or :production |
+| `cors` | Boolean | true | Enable CORS |
+| `rate_limit` | Integer | 0 | Requests/minute (0=unlimited) |
+| `max_batch_size` | Integer | 10,000 | Max records per batch |
+| `max_stream_size` | Integer | 1,000,000 | Max streaming records |
+| `request_timeout` | Integer | 30 | Request timeout (seconds) |
+| `enable_metrics` | Boolean | true | Enable /metrics endpoint |
+| `enable_caching` | Boolean | false | Enable response caching |
+| `cache_ttl` | Integer | 60 | Cache TTL (seconds) |
+| `auth` | Hash | nil | Authentication config |
+
+## Docker Deployment
+
+```dockerfile
+FROM ruby:3.2
+
+WORKDIR /app
+COPY Gemfile* ./
+RUN bundle install
+COPY schemas/ ./schemas/
+
+EXPOSE 3000
+
+CMD ["fake_data_dsl", "server", "schemas/", "--port", "3000", "--env", "production"]
+```
+
+```bash
+docker build -t fake-data-api .
+docker run -p 3000:3000 fake-data-api
+```

data/docs/CONFIG_FILE.md

@@ -0,0 +1,315 @@
+# Configuration File Guide
+
+FakeDataDSL supports YAML configuration files following Rails conventions. This allows you to configure the gem without code changes and have environment-specific settings.
+
+## Quick Start
+
+Create `config/fake_data_dsl.yml`:
+
+```yaml
+default_mode: random
+max_unique_retries: 1000
+
+limits:
+  max_array_size: 100
+  max_recursion: 5
+```
+
+The configuration is automatically loaded when FakeDataDSL initializes.
+
+## File Locations
+
+FakeDataDSL searches for configuration files in this order:
+
+1. `config/fake_data_dsl.yml` (Rails convention)
+2. `fake_data_dsl.yml` (project root)
+3. `.fake_data_dsl.yml` (hidden file)
+
+The first file found is used.
+
+## Configuration Options
+
+### Core Settings
+
+```yaml
+# Default generation mode
+# Options: random, edge, invalid, hostile, mixed
+default_mode: random
+
+# Maximum retries for unique value generation
+max_unique_retries: 1000
+
+# Allow eval() in custom expressions (security risk!)
+allow_eval: false
+
+# Use FastEngine for batch generation (not thread-safe)
+fast_mode: false
+```
+
+### Field Handling
+
+```yaml
+# Probability that optional fields appear (0.0 - 1.0)
+optional_field_presence_rate: 0.8
+
+# Probability that nullable fields are null (0.0 - 1.0)
+nullable_field_null_rate: 0.1
+```
+
+### Resource Limits
+
+```yaml
+limits:
+  # Maximum artificial latency in milliseconds
+  max_latency_ms: 10000
+  
+  # Maximum recursion depth for nested schemas
+  max_recursion: 10
+  
+  # Maximum array size
+  max_array_size: 1000
+  
+  # Maximum text length
+  max_text_length: 10000
+```
+
+## Environment-Specific Configuration
+
+Override settings per environment:
+
+```yaml
+# Base configuration (applies to all environments)
+default_mode: random
+max_unique_retries: 1000
+
+limits:
+  max_array_size: 100
+
+# Test environment overrides
+test:
+  default_mode: edge        # Use edge cases in tests
+  max_unique_retries: 100   # Faster test failures
+  limits:
+    max_array_size: 10      # Smaller arrays in tests
+
+# Development environment
+development:
+  default_mode: random
+
+# Production environment
+production:
+  fast_mode: true
+  limits:
+    max_array_size: 1000
+```
+
+### Environment Detection
+
+FakeDataDSL detects the environment from these variables (in order):
+
+1. `RAILS_ENV`
+2. `RACK_ENV`
+3. `FAKE_DATA_DSL_ENV`
+4. Default: `"development"`
+
+## Manual Configuration
+
+### Load from Custom Path
+
+```ruby
+# Load specific file
+FakeDataDSL::ConfigFile.load_and_apply("custom/path/config.yml")
+
+# Load with specific environment
+FakeDataDSL::ConfigFile.load_and_apply("config.yml", env: "staging")
+```
+
+### Load Without Applying
+
+```ruby
+# Just load the config hash
+config = FakeDataDSL::ConfigFile.load("config.yml", env: "test")
+puts config["default_mode"]  # => "edge"
+
+# Apply later
+FakeDataDSL::ConfigFile.apply(config)
+```
+
+### Check Config File Location
+
+```ruby
+path = FakeDataDSL::ConfigFile.find_config_file
+puts "Using config: #{path || 'none found'}"
+```
+
+## Complete Example
+
+```yaml
+# config/fake_data_dsl.yml
+
+# =========================================
+# Base Configuration (all environments)
+# =========================================
+
+# Generation settings
+default_mode: random
+max_unique_retries: 1000
+
+# Field behavior
+optional_field_presence_rate: 0.8
+nullable_field_null_rate: 0.1
+
+# Resource limits
+limits:
+  max_latency_ms: 10000
+  max_recursion: 10
+  max_array_size: 100
+  max_text_length: 10000
+
+# =========================================
+# Test Environment
+# =========================================
+test:
+  # Deterministic for reproducible tests
+  default_mode: random
+  
+  # Fail fast on uniqueness issues
+  max_unique_retries: 50
+  
+  # Smaller data for faster tests
+  limits:
+    max_array_size: 5
+    max_text_length: 100
+
+# =========================================
+# Development Environment
+# =========================================
+development:
+  # More realistic data
+  default_mode: random
+  
+  # Allow more retries during development
+  max_unique_retries: 2000
+
+# =========================================
+# CI Environment
+# =========================================
+ci:
+  # Test edge cases in CI
+  default_mode: mixed
+  
+  # Strict limits
+  limits:
+    max_recursion: 5
+    max_array_size: 50
+
+# =========================================
+# Production Environment
+# =========================================
+production:
+  # Maximum performance
+  fast_mode: true
+  
+  # Higher limits for bulk operations
+  limits:
+    max_array_size: 10000
+```
+
+## Programmatic Configuration
+
+You can still configure FakeDataDSL programmatically, which takes precedence over file config:
+
+```ruby
+# File config is loaded first, then this overrides
+FakeDataDSL.configure do |config|
+  config.default_mode = :edge
+  config.limits.max_array_size = 50
+end
+```
+
+## Disabling Auto-Loading
+
+To prevent automatic config file loading:
+
+```ruby
+# Set before requiring the gem
+ENV['FAKE_DATA_DSL_SKIP_CONFIG'] = 'true'
+require 'fake_data_dsl'
+```
+
+Or remove/rename the config file.
+
+## Best Practices
+
+### 1. Version Control Your Config
+
+```bash
+git add config/fake_data_dsl.yml
+git commit -m "Add FakeDataDSL configuration"
+```
+
+### 2. Document Environment Differences
+
+```yaml
+# Test: Fast, small datasets, edge cases
+test:
+  max_unique_retries: 50  # Fail fast
+  limits:
+    max_array_size: 5     # Faster tests
+```
+
+### 3. Use Sensible Defaults
+
+Don't over-configure. The defaults are designed for common use cases.
+
+### 4. Keep Secrets Out
+
+Config files shouldn't contain secrets. Use environment variables if needed:
+
+```ruby
+# In code, not in config file
+FakeDataDSL.configure do |config|
+  config.api_key = ENV['FAKE_DATA_API_KEY']
+end
+```
+
+## Troubleshooting
+
+### Config Not Loading
+
+```ruby
+# Check if config file was found
+puts FakeDataDSL::ConfigFile.find_config_file
+# => nil means no config file found
+
+# Check current configuration
+puts FakeDataDSL.configuration.default_mode
+```
+
+### Wrong Environment
+
+```ruby
+# Check detected environment
+puts ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+
+# Force specific environment
+FakeDataDSL::ConfigFile.load_and_apply(env: "production")
+```
+
+### Invalid YAML
+
+```yaml
+# Bad: Tabs instead of spaces
+limits:
+	max_array_size: 100  # Tab character causes error
+
+# Good: Use spaces
+limits:
+  max_array_size: 100    # Spaces work
+```
+
+## See Also
+
+- [Quick Start Guide](../tech_docs/quick_start.md)
+- [Configuration API](../tech_docs/api/overview.md)
+- [Resource Limits](../tech_docs/performance/resource_limits.md)