aris 1.4.2 → 1.5.0

data/docs/plugins/JSON.md

@@ -0,0 +1,291 @@
+# JSON Body Parser Plugin
+
+Automatically parse JSON request bodies and attach parsed data to the request object.
+
+## Installation
+
+```ruby
+# lib/aris.rb already includes this
+require_relative 'aris/plugins/json'
+```
+
+## How It Works
+
+Runs on POST/PUT/PATCH requests. Reads `rack.input`, parses JSON, and attaches to `request.json_body`. Returns **400 Bad Request** on invalid JSON.
+
+---
+
+## Basic Usage
+
+```ruby
+Aris.routes({
+  "api.example.com": {
+    use: [:json],
+    "/users": { post: { to: CreateUserHandler } }
+  }
+})
+```
+
+**Handler access:**
+
+```ruby
+class CreateUserHandler
+  def self.call(request, params)
+    data = request.json_body
+    
+    User.create(
+      name: data['name'],
+      email: data['email']
+    )
+    
+    { success: true, user_id: user.id }
+  end
+end
+```
+
+**Request:**
+```bash
+curl -X POST https://api.example.com/users \
+  -H "content-type: application/json" \
+  -d '{"name": "Alice", "email": "alice@example.com"}'
+```
+
+---
+
+## Error Handling
+
+**Invalid JSON returns 400:**
+
+```bash
+curl -X POST https://api.example.com/users \
+  -H "content-type: application/json" \
+  -d '{invalid json}'
+```
+
+**Response:**
+```json
+{
+  "error": "Invalid JSON",
+  "message": "unexpected token at '{invalid json}'"
+}
+```
+
+---
+
+## Behavior
+
+| Request Method | Action |
+|:---|:---|
+| POST, PUT, PATCH | Parse JSON body |
+| GET, DELETE, HEAD | Skip (no action) |
+| Empty body | Skip (no action) |
+| Invalid JSON | Halt with 400 error |
+
+**Parsed data available at:**
+```ruby
+request.json_body  # Hash or Array
+```
+
+---
+
+## Common Patterns
+
+### Combine with Validation
+
+```ruby
+class CreateUserHandler
+  def self.call(request, params)
+    data = request.json_body
+    
+    # Validate required fields
+    unless data['name'] && data['email']
+      return [400, {}, [JSON.generate({ error: 'Missing required fields' })]]
+    end
+    
+    User.create(data)
+  end
+end
+```
+
+### Nested JSON
+
+```ruby
+# Request body
+{
+  "user": {
+    "name": "Alice",
+    "address": {
+      "city": "New York",
+      "zip": "10001"
+    }
+  }
+}
+
+# Handler
+data = request.json_body
+name = data['user']['name']
+city = data['user']['address']['city']
+```
+
+### JSON Arrays
+
+```ruby
+# Request: [{"name": "Alice"}, {"name": "Bob"}]
+
+data = request.json_body  # Array
+data.each do |user|
+  User.create(name: user['name'])
+end
+```
+
+---
+
+## Plugin Order
+
+Place JSON parser **early** in the pipeline:
+
+```ruby
+Aris.routes({
+  "api.example.com": {
+    use: [:json, :csrf, bearer_auth],  # Parse first
+    "/users": { post: { to: CreateUserHandler } }
+  }
+})
+```
+
+**Why?** Subsequent plugins or handlers may need access to `request.json_body`.
+
+---
+
+## Testing
+
+```ruby
+class JsonParserTest < Minitest::Test
+  def test_valid_json_parsed
+    Aris.routes({
+      "api.test": {
+        use: [:json],
+        "/data": { post: { to: DataHandler } }
+      }
+    })
+    
+    app = Aris::Adapters::RackApp.new
+    body = JSON.generate({ name: 'Alice' })
+    
+    env = {
+      'REQUEST_METHOD' => 'POST',
+      'PATH_INFO' => '/data',
+      'HTTP_HOST' => 'api.test',
+      'rack.input' => StringIO.new(body)
+    }
+    
+    status, _, response = app.call(env)
+    assert_equal 200, status
+  end
+  
+  def test_invalid_json_returns_400
+    # Same setup...
+    env['rack.input'] = StringIO.new('{invalid}')
+    
+    status, _, response = app.call(env)
+    assert_equal 400, status
+    
+    error = JSON.parse(response.first)
+    assert_equal 'Invalid JSON', error['error']
+  end
+end
+```
+
+---
+
+## Production Tips
+
+**1. content-type Validation**
+
+Currently parses regardless of content-type. For strict APIs:
+
+```ruby
+class StrictJsonParser
+  def self.call(request, response)
+    return nil unless ['POST', 'PUT', 'PATCH'].include?(request.method)
+    
+    # Require correct content-type
+    content_type = request.headers['CONTENT_TYPE']
+    unless content_type&.include?('application/json')
+      response.status = 415
+      response.body = ['Unsupported Media Type']
+      return response
+    end
+    
+    # Parse JSON...
+  end
+end
+```
+
+**2. Size Limits**
+
+Protect against large payloads:
+
+```ruby
+MAX_BODY_SIZE = 1_000_000  # 1MB
+
+def call(request, response)
+  raw_body = request.body
+  
+  if raw_body.bytesize > MAX_BODY_SIZE
+    response.status = 413
+    response.body = ['Payload Too Large']
+    return response
+  end
+  
+  # Parse JSON...
+end
+```
+
+**3. Schema Validation**
+
+Use JSON Schema for validation:
+
+```ruby
+require 'json-schema'
+
+class ValidatedJsonParser
+  SCHEMA = {
+    "type" => "object",
+    "required" => ["name", "email"],
+    "properties" => {
+      "name" => { "type" => "string" },
+      "email" => { "type" => "string", "format" => "email" }
+    }
+  }
+  
+  def self.call(request, response)
+    # Parse JSON first...
+    data = JSON.parse(request.body)
+    
+    # Validate against schema
+    errors = JSON::Validator.fully_validate(SCHEMA, data)
+    if errors.any?
+      response.status = 422
+      response.body = [JSON.generate({ errors: errors })]
+      return response
+    end
+    
+    request.json_body = data
+    nil
+  end
+end
+```
+
+---
+
+## Notes
+
+- **Only parses POST/PUT/PATCH** - GET requests ignored
+- **Empty bodies skipped** - No error, just continues
+- **Thread-safe** - Each request has isolated `json_body`
+- **No streaming** - Reads entire body into memory
+
+---
+
+Need help? Check out the [full plugin development guide](../docs/plugin-development.md).

data/docs/plugins/MULTIPART.md

@@ -0,0 +1,427 @@
+# Multipart Parser Plugin (File Uploads)
+
+Parses `multipart/form-data` requests for file uploads and form submissions. Essential for handling file uploads in web applications.
+
+## Installation
+
+```ruby
+require 'aris/plugins/multipart'
+```
+
+## Basic Usage
+
+```ruby
+multipart = Aris::Plugins::Multipart.build
+
+Aris.routes({
+  "api.example.com": {
+    use: [multipart],
+    "/upload": { post: { to: UploadHandler } }
+  }
+})
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max_file_size` | Integer | `10485760` (10MB) | Maximum file size in bytes |
+| `max_files` | Integer | `10` | Maximum number of files per request |
+| `allowed_extensions` | Array | `nil` (all allowed) | Whitelist of allowed file extensions (e.g., `['.jpg', '.png']`) |
+
+## Examples
+
+### Basic File Upload
+
+```ruby
+class UploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    
+    files = data.select { |p| p[:type] == :file }
+    file = files.first
+    
+    {
+      message: "Uploaded #{file[:filename]}",
+      size: file[:data].bytesize,
+      type: file[:content_type]
+    }
+  end
+end
+
+multipart = Aris::Plugins::Multipart.build
+
+Aris.routes({
+  "api.example.com": {
+    use: [multipart],
+    "/upload": { post: { to: UploadHandler } }
+  }
+})
+```
+
+### Custom File Size Limit
+
+```ruby
+multipart = Aris::Plugins::Multipart.build(
+  max_file_size: 5_242_880  # 5MB
+)
+```
+
+### Restrict File Types
+
+```ruby
+multipart = Aris::Plugins::Multipart.build(
+  allowed_extensions: ['.jpg', '.jpeg', '.png', '.gif']
+)
+
+# Only image files allowed
+```
+
+### Multiple Files with Limits
+
+```ruby
+multipart = Aris::Plugins::Multipart.build(
+  max_files: 5,
+  max_file_size: 2_097_152  # 2MB per file
+)
+```
+
+### Processing Uploaded Files
+
+```ruby
+class ImageUploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    
+    # Get all uploaded files
+    files = data.select { |p| p[:type] == :file }
+    
+    # Get form fields
+    fields = data.select { |p| p[:type] == :field }
+    title = fields.find { |f| f[:name] == 'title' }&.dig(:data)
+    
+    # Process each file
+    uploaded_files = files.map do |file|
+      # Save to S3, disk, etc.
+      save_file(file[:filename], file[:data])
+      
+      {
+        name: file[:filename],
+        size: file[:data].bytesize,
+        content_type: file[:content_type]
+      }
+    end
+    
+    { title: title, files: uploaded_files }
+  end
+  
+  def self.save_file(filename, data)
+    # Save to disk, S3, etc.
+    File.write("/tmp/uploads/#{filename}", data)
+  end
+end
+```
+
+### Mixed Form Data and Files
+
+```ruby
+class FormHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    
+    # Extract files
+    files = data.select { |p| p[:type] == :file }
+    avatar = files.find { |f| f[:name] == 'avatar' }
+    
+    # Extract form fields
+    fields = data.select { |p| p[:type] == :field }
+    username = fields.find { |f| f[:name] == 'username' }&.dig(:data)
+    email = fields.find { |f| f[:name] == 'email' }&.dig(:data)
+    
+    {
+      user: { username: username, email: email },
+      avatar: avatar ? { filename: avatar[:filename], size: avatar[:data].bytesize } : nil
+    }
+  end
+end
+```
+
+## Parsed Data Structure
+
+Multipart data is attached to request as `@multipart_data` array:
+
+```ruby
+[
+  {
+    name: 'avatar',               # Form field name
+    filename: 'photo.jpg',        # Original filename
+    content_type: 'image/jpeg',   # MIME type
+    data: '...',                  # Binary file data
+    type: :file                   # :file or :field
+  },
+  {
+    name: 'username',
+    data: 'alice',
+    type: :field
+  }
+]
+```
+
+## Production Tips
+
+### 1. File Size Limits by Type
+
+```ruby
+# Images
+image_multipart = Aris::Plugins::Multipart.build(
+  max_file_size: 5_242_880,  # 5MB
+  allowed_extensions: ['.jpg', '.png', '.gif']
+)
+
+# Documents
+doc_multipart = Aris::Plugins::Multipart.build(
+  max_file_size: 10_485_760,  # 10MB
+  allowed_extensions: ['.pdf', '.doc', '.docx']
+)
+
+Aris.routes({
+  "api.example.com": {
+    "/upload/image": { use: [image_multipart], post: { to: ImageHandler } },
+    "/upload/document": { use: [doc_multipart], post: { to: DocHandler } }
+  }
+})
+```
+
+### 2. Save to Disk (Production)
+
+Don't keep files in memory:
+
+```ruby
+class ProductionUploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    saved_files = files.map do |file|
+      # Generate unique filename
+      ext = File.extname(file[:filename])
+      unique_name = "#{SecureRandom.uuid}#{ext}"
+      path = "/var/uploads/#{unique_name}"
+      
+      # Write to disk
+      File.binwrite(path, file[:data])
+      
+      {
+        original_name: file[:filename],
+        stored_path: path,
+        size: file[:data].bytesize
+      }
+    end
+    
+    { files: saved_files }
+  end
+end
+```
+
+### 3. Upload to S3
+
+```ruby
+require 'aws-sdk-s3'
+
+class S3UploadHandler
+  S3_CLIENT = Aws::S3::Client.new(region: 'us-east-1')
+  BUCKET = 'my-uploads-bucket'
+  
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    uploaded_files = files.map do |file|
+      key = "uploads/#{SecureRandom.uuid}/#{file[:filename]}"
+      
+      S3_CLIENT.put_object(
+        bucket: BUCKET,
+        key: key,
+        body: file[:data],
+        content_type: file[:content_type]
+      )
+      
+      {
+        filename: file[:filename],
+        url: "https://#{BUCKET}.s3.amazonaws.com/#{key}",
+        size: file[:data].bytesize
+      }
+    end
+    
+    { files: uploaded_files }
+  end
+end
+```
+
+### 4. Validate Content Type
+
+Don't trust filename extensions:
+
+```ruby
+class SecureUploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    files.each do |file|
+      # Check magic bytes (first few bytes)
+      magic = file[:data][0..3]
+      
+      case magic
+      when "\xFF\xD8\xFF"  # JPEG
+        # Valid
+      when "\x89PNG"       # PNG
+        # Valid
+      else
+        return { error: "Invalid file type for #{file[:filename]}" }
+      end
+    end
+    
+    # Process files...
+  end
+end
+```
+
+### 5. Progress Tracking (Large Files)
+
+For very large files, consider:
+- Direct-to-S3 uploads (presigned URLs)
+- Chunked uploads
+- Background job processing
+
+```ruby
+# Use presigned URLs instead
+class PresignedUploadHandler
+  def self.call(request, params)
+    S3_CLIENT = Aws::S3::Client.new(region: 'us-east-1')
+    
+    # Generate presigned URL for client to upload directly
+    presigned_url = S3_CLIENT.presigned_url(
+      :put_object,
+      bucket: 'my-bucket',
+      key: "uploads/#{SecureRandom.uuid}/file",
+      expires_in: 3600
+    )
+    
+    { upload_url: presigned_url }
+  end
+end
+```
+
+### 6. Virus Scanning
+
+```ruby
+class ScannedUploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    files.each do |file|
+      # Save temporarily
+      temp_path = "/tmp/#{SecureRandom.uuid}"
+      File.binwrite(temp_path, file[:data])
+      
+      # Scan with ClamAV or similar
+      scan_result = `clamscan #{temp_path}`
+      
+      if scan_result.include?('FOUND')
+        File.delete(temp_path)
+        return { error: "Virus detected in #{file[:filename]}" }
+      end
+      
+      File.delete(temp_path)
+    end
+    
+    # Files are clean, process them...
+  end
+end
+```
+
+## Common Patterns
+
+### Image Thumbnails
+
+```ruby
+require 'mini_magick'
+
+class ThumbnailHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    thumbnails = files.map do |file|
+      # Create thumbnail
+      image = MiniMagick::Image.read(file[:data])
+      image.resize '200x200'
+      
+      # Save original and thumbnail
+      {
+        original: save_file(file[:filename], file[:data]),
+        thumbnail: save_file("thumb_#{file[:filename]}", image.to_blob)
+      }
+    end
+    
+    { thumbnails: thumbnails }
+  end
+end
+```
+
+### CSV Import
+
+```ruby
+require 'csv'
+
+class CSVUploadHandler
+  def self.call(request, params)
+    data = request.multipart_data          # every part; or request.multipart_files / request.multipart_params
+    files = data.select { |p| p[:type] == :file }
+    
+    csv_file = files.find { |f| f[:filename].end_with?('.csv') }
+    return { error: 'No CSV file' } unless csv_file
+    
+    # Parse CSV
+    rows = CSV.parse(csv_file[:data], headers: true)
+    
+    { 
+      row_count: rows.size,
+      headers: rows.headers,
+      sample: rows.first(5).map(&:to_h)
+    }
+  end
+end
+```
+
+## Notes
+
+- Files stored in memory (not suitable for very large files)
+- For production, save to disk/S3 immediately
+- Parser handles standard multipart/form-data format
+- Validates file size and count before processing
+- Thread-safe (no shared state)
+- Only processes POST/PUT/PATCH requests
+
+## Troubleshooting
+
+**Files not parsing?**
+- Check content-type includes `multipart/form-data`
+- Verify boundary is present in content-type header
+- Ensure request method is POST/PUT/PATCH
+
+**File size errors?**
+- Check actual file size vs `max_file_size`
+- Remember limit is in bytes (10MB = 10_485_760)
+
+**Extension validation failing?**
+- Extensions must include the dot: `'.jpg'` not `'jpg'`
+- Comparison is case-insensitive
+
+**Memory issues?**
+- Don't use for large files (>10MB) in production
+- Save to disk/S3 immediately after parsing
+- Consider direct-to-S3 uploads for large files
+```