gr_api_manager 0.1.0 → 0.4.0

data/README.md

@@ -1,345 +1,614 @@
 # GR API Manager
 
-[![Gem Version](https://badge.fury.io/rb/gr-api-manager.svg)](https://rubygems.org/gems/gr-api-manager)
+[![Gem Version](https://img.shields.io/gem/v/gr_api_manager.svg?logo=rubygems&logoColor=white&color=e9573f)](https://rubygems.org/gems/gr_api_manager)
+[![Gem Total Downloads](https://img.shields.io/gem/dt/gr_api_manager.svg?logo=rubygems&logoColor=white&color=00bfa5)](https://rubygems.org/gems/gr_api_manager)
+[![Ruby Version](https://img.shields.io/badge/Ruby-%3E%3D%203.0-cc342d.svg?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Sinatra Version](https://img.shields.io/badge/Sinatra-%3E%3D%203.0-008080.svg?logo=sinatra&logoColor=white)](https://sinatrarb.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-007ec6.svg?logo=open-source-initiative&logoColor=white)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-555555.svg?logo=linux&logoColor=white)](https://rubygems.org/gems/gr_api_manager)
+[![Tests](https://img.shields.io/badge/Tests-59%2F59%20Passing-4c1.svg?logo=checkmarx&logoColor=white)](spec/)
+[![README en Español](https://img.shields.io/badge/README-Espa%C3%B1ol-red.svg?logo=google-translate&logoColor=white)](README_ES.md)
 
-A minimal, opinionated Ruby wrapper around Sinatra that eliminates boilerplate from REST API development. Authentication, parameter validation, type casting, CORS, and error handling are handled at the framework level — you write only the business logic.
+**GR API Manager** is a minimalist, high-performance Ruby wrapper on top of Sinatra and Puma, designed to build production-grade REST APIs with zero boilerplate.
 
 ---
 
-## Features
+## System Requirements
 
-- **Available on RubyGems!** Install globally and use it in any project.
-- Route-level Bearer Token authentication (opt-in/opt-out per endpoint).
-- Declarative required parameter validation with automatic `400 Bad Request` responses.
-- Smart type casting for query string values (`"10"` -> `Integer`, `"true"` -> `TrueClass`, `"9.5"` -> `Float`).
-- Global JSON error responses for `404` and `500`.
-- Broad CORS and `OPTIONS` preflight handling out of the box (Frontend ready).
-- API versioning via configurable route prefix (e.g. `/api/v1`).
+| Dependency / Environment | Required / Supported Version |
+|---|---|
+| **Ruby** | `>= 3.0` (Tested on 3.0, 3.1, 3.2, 3.3, and 3.4) |
+| **Sinatra** | `>= 3.0, < 5.0` |
+| **Puma** | `>= 5.0, < 9.0` |
+| **Dotenv** | `>= 2.8, < 4.0` |
 
 ---
 
-## Installation
+## Key Features
+
+- **Available on RubyGems (`0.4.0`)** - global installation or via Bundler.
+- **Modular Route Groups (`api.group`)** - organize large projects into clean, multi-file sub-routers with prefix & option inheritance.
+- **Dual Authentication (Static Bearer Token & Native JWT)** - support for pre-shared static tokens and zero-dependency built-in HMAC-SHA256 JWT engine.
+- **Declarative Schema & Type Validation** - validate complex request contracts with `:email`, `:url`, `:boolean`, `:file`, classes (`Integer`, `Float`, `String`, `Array`, `Hash`), enum lists, regular expressions, or custom procs.
+- **Sliding-Window Rate Limiting (429)** - sliding-window rate limiter with automatic client IP detection behind Cloudflare (`CF-Connecting-IP`), Nginx (`X-Real-IP`), or Reverse Proxies (`X-Forwarded-For`), supporting in-memory or pluggable stores (Redis).
+- **Smart Parameter Casting** - automatic type casting for query and URL parameters (`"100"` -> `100`, `"-42"` -> `-42`, `"true"` -> `true`, `"19.99"` -> `19.99`).
+- **Unified File & Binary Handling (`FilePayload`)** - transparent handling for multipart uploads, raw binary streams, Base64/Hex encoding, file serving/downloads, and disk storage with directory auto-creation.
+- **Puma Concurrency** - configurable multi-process workers and thread pools.
+- **Developer Mode (`dev_mode`)** - structured JSON error responses with full stack traces for painless debugging.
 
-Add this line to your application's Gemfile:
+---
+
+## Installation
 
+Add the gem to your `Gemfile`:
 ```ruby
-gem 'gr-api-manager'
+gem 'gr_api_manager', '~> 0.4.0'
 ```
 
-And then execute:
+And run:
 ```bash
 bundle install
 ```
 
-Or install it yourself directly via RubyGems:
+Or install directly:
 ```bash
-gem install gr-api-manager
+gem install gr_api_manager
 ```
 
 ---
 
-## Quick Start
+## Table of Contents
+
+1. [Quickstart](#quickstart)
+2. [Authentication: Static Bearer Token & Native JWT](#authentication-static-bearer-token--native-jwt)
+3. [Multi-File Modular Architecture (Importing & Grouping)](#multi-file-modular-architecture)
+4. [Full REST CRUD with HTTP Verbs](#full-rest-crud-with-http-verbs)
+5. [Declarative Schema & Type Validation](#declarative-schema--type-validation)
+6. [Comprehensive File, Binary & Image Handling](#comprehensive-file-binary--image-handling)
+7. [Serving & Downloading Files to Clients](#serving--downloading-files-to-clients)
+8. [Rate Limiting & Real IP Detection (Cloudflare/Nginx)](#rate-limiting--real-ip-detection)
+9. [Smart Parameter Casting](#smart-parameter-casting)
+10. [Responses, HTTP Status Codes & Dev Mode](#responses-http-status-codes--dev-mode)
+11. [Concurrency & Production Deployment (Puma & Docker)](#concurrency--production-deployment)
+
+---
+
+## Quickstart
+
+Create an `app.rb` file:
 
 ```ruby
 require 'gr_api_manager'
 
+# Initialize the server with static token and JWT key
 api = GRApiManager::Server.new(
-  port: 4567,
-  bearer_token: "your_secret_token",
-  prefix: "/api/v1"
+  port: 4000,
+  bearer_token: "my_static_secret_token",
+  jwt_secret: "my_jwt_signing_secret"
 )
 
-# Public endpoint
+# Public endpoint (no auth required)
 api.get('/health', auth: false) do
-  { status: 'online', time: Time.now.to_s }
+  { status: 'online', timestamp: Time.now.to_i }
 end
 
+# Protected endpoint with static token (default: auth = true)
+api.get('/protected-data') do
+  { message: "Access granted with Bearer Token", data: [10, 20, 30] }
+end
+
+# Start the server
 api.run!
 ```
 
+Run your API:
 ```bash
-curl http://localhost:4567/api/v1/health
-# => {"status":"online","time":"..."}
+ruby app.rb
 ```
 
 ---
 
-## Configuration
+## Authentication: Static Bearer Token & Native JWT
+
+`gr_api_manager` supports two complementary authentication schemes:
 
-All parameters are optional. If omitted, the manager falls back to environment variables loaded from a `.env` file at the project root (via `dotenv`). If neither is provided, defaults are used.
+### 1. Static Bearer Token
 
+Ideal for internal services, webhooks, microservices, or backend automation using a pre-shared static key.
+
+#### Configuration in `app.rb`:
 ```ruby
-GRApiManager::Server.new(
-  port: 4567,                        # Default: ENV['PORT'] || 4000
-  bearer_token: "secret",            # Default: ENV['API_TOKEN']
-  permitted_hosts: ["example.com"],  # Host allowlist — empty means allow all
-  prefix: "/api/v1"                  # Route prefix applied to all endpoints
+api = GRApiManager::Server.new(
+  bearer_token: "my_secret_company_token_2026"
 )
-```
 
-### Using a .env file (Recommended)
+# Public route
+api.get('/public', auth: false) do
+  { status: "open access" }
+end
 
-Create a `.env` file at the root of your project:
+# Protected routes (default auth: true)
+api.get('/admin/config') do
+  { database: "connected", environment: "production" }
+end
 
-```env
-PORT=4567
-API_TOKEN=your_secret_token
+api.post('/admin/restart', requires: [:reason]) do |params|
+  { action: "restarting", reason: params[:reason] }
+end
 ```
 
-Then initialize the manager with no arguments and it will pick everything up automatically:
+#### Consuming via cURL:
 
-```ruby
-require 'gr_api_manager'
-
-api = GRApiManager::Server.new
-# Reads PORT and API_TOKEN from .env
+**Valid request (200 OK):**
+```bash
+curl -H "Authorization: Bearer my_secret_company_token_2026" http://localhost:4000/admin/config
+# => {"database":"connected","environment":"production"}
 ```
 
-This is the recommended approach for production — keep secrets out of source code and out of version control. Add `.env` to your `.gitignore`.
+**Missing Authorization header (401 Unauthorized):**
+```bash
+curl http://localhost:4000/admin/config
+# => 401 {"error":"Token required. Format: 'Bearer <token>'"}
+```
 
-```text
-# .gitignore
-.env
+**Invalid token (403 Forbidden):**
+```bash
+curl -H "Authorization: Bearer wrong_token" http://localhost:4000/admin/config
+# => 403 {"error":"Invalid token"}
 ```
 
-### Priority order
+---
+
+### 2. Native JWT Authentication (HS256)
 
-When a value is provided both in code and in `.env`, the explicit argument always wins:
+Ideal for end-user facing APIs issuing dynamic tokens with expiration and claims.
 
-```text
-new(bearer_token: "hardcoded")  >  ENV['API_TOKEN']  >  nil (auth disabled)
-new(port: 4567)                 >  ENV['PORT']        >  4000
+#### Complete Workflow:
+```ruby
+api = GRApiManager::Server.new(
+  jwt_secret: "my_super_secret_jwt_key"
+)
+
+# 1. Login: issue and return token
+api.post('/auth/login', auth: false, requires: { email: :email, password: String }) do |params|
+  if params[:email] == "admin@company.com" && params[:password] == "pass123"
+    token = api.jwt_encode(
+      { user_id: 42, email: params[:email], role: "admin" },
+      exp: Time.now.to_i + 3600 # 1-hour expiration
+    )
+    { token: token, token_type: "Bearer", expires_in: 3600 }
+  else
+    status 401
+    { error: "Invalid credentials" }
+  end
+end
+
+# 2. JWT-protected route: automatically injects params[:current_user]
+api.get('/profile', auth: :jwt) do |params|
+  user = params[:current_user]
+  {
+    message: "Valid JWT token",
+    user_id: user[:user_id],
+    email: user[:email],
+    role: user[:role]
+  }
+end
 ```
 
 ---
 
-## Defining Routes
+## Multi-File Modular Architecture
+
+Divide your API into dedicated, clean route modules within a `routes/` directory:
 
-The manager exposes `get`, `post`, `put`, and `delete` methods. Each route receives a merged `params` hash containing both URL/query parameters (type-cast) and the parsed JSON body.
+```text
+my_api_project/
+├── app.rb                   # Main entrypoint and configuration
+├── .env                     # Environment variables
+├── Gemfile
+└── routes/
+    ├── auth_routes.rb       # Login & registration
+    ├── admin_routes.rb      # Admin dashboard
+    ├── payments_routes.rb   # Checkout & billing
+    └── files_routes.rb      # File uploads & storage
+```
 
+### Module 1: `routes/auth_routes.rb`
 ```ruby
-api.get('/users', auth: true, requires: [:role, :age]) do |params|
-  # params is a merged, type-cast hash of all inputs
-  { 
-    requested_role: params[:role],
-    is_adult: params[:age] >= 18 # age is safely cast to Integer
-  }
+module AuthRoutes
+  def self.setup(router, api_server)
+    router.post('/login', auth: false, requires: { email: :email, password: String }) do |params|
+      if params[:email] == "admin@company.com" && params[:password] == "secret"
+        token = api_server.jwt_encode({ user_id: 1, email: params[:email], role: "admin" })
+        { token: token }
+      else
+        status 401
+        { error: "Invalid credentials" }
+      end
+    end
+  end
 end
 ```
 
-### Options
+### Module 2: `routes/admin_routes.rb`
+```ruby
+module AdminRoutes
+  def self.setup(router)
+    router.get('/metrics') do |params|
+      { cpu: "12%", memory: "380MB", user: params[:current_user][:email] }
+    end
+
+    router.delete('/users/:id') do |params|
+      { message: "User #{params[:id]} deleted" }
+    end
+  end
+end
+```
 
-| Option     | Type    | Default | Description                                      |
-|------------|---------|---------|--------------------------------------------------|
-| `auth`     | Boolean | `true`  | Require Bearer Token for this route              |
-| `requires` | Array   | `[]`    | List of required parameter keys (symbols/strings)|
+### Module 3: `routes/files_routes.rb`
+```ruby
+module FilesRoutes
+  def self.setup(router)
+    router.post('/upload', requires: [:title]) do |params|
+      file = params[:_files][:document]
+      path = file.save_to("./storage/#{params[:title]}#{file.extension}")
+      { status: "saved", path: path, size: file.size }
+    end
+  end
+end
+```
 
----
+### Main Application File: `app.rb`
+```ruby
+require 'gr_api_manager'
 
-## Authentication
+# Require modular route files
+require_relative 'routes/auth_routes'
+require_relative 'routes/admin_routes'
+require_relative 'routes/files_routes'
 
-All routes require a valid Bearer Token by default. Pass the token in the `Authorization` header:
+api = GRApiManager::Server.new(
+  port: 4000,
+  jwt_secret: ENV['JWT_SECRET'] || "default_jwt_secret",
+  bearer_token: ENV['API_TOKEN'] || "global_static_token"
+)
 
-```bash
-curl -H "Authorization: Bearer your_secret_token" http://localhost:4567/api/v1/users
+# Root route
+api.get('/', auth: false) { { service: "Core API v1.0" } }
+
+# Mount route groups
+api.group('/auth') { |g| AuthRoutes.setup(g, api) }
+api.group('/admin', auth: :jwt) { |g| AdminRoutes.setup(g) }
+api.group('/files', auth: true) { |g| FilesRoutes.setup(g) }
+
+api.run!(workers: 2, threads: '2:8')
 ```
 
-To make a route public, set `auth: false`:
+---
+
+## Full REST CRUD with HTTP Verbs
+
+Example managing a `/products` resource:
 
 ```ruby
-api.get('/health', auth: false) do
-  { status: 'online' }
+api = GRApiManager::Server.new(prefix: '/api/v1')
+
+# 1. LIST (GET) - with auto-cast query parameters
+api.get('/products', auth: false) do |params|
+  page   = params[:page] || 1        # Integer
+  limit  = params[:limit] || 10      # Integer
+  active = params[:active] != false  # Boolean
+  
+  {
+    page: page,
+    limit: limit,
+    items: [
+      { id: 1, name: "Mechanical Keyboard", price: 89.99, active: true },
+      { id: 2, name: "4K Monitor", price: 299.99, active: true }
+    ]
+  }
 end
-```
 
-**Automatic Error Responses:**
+# 2. GET BY ID (GET)
+api.get('/products/:id', auth: false) do |params|
+  id = params[:id] # Auto Integer
+  { id: id, name: "Product #{id}", price: 49.99 }
+end
 
-```json
-// Missing header (401)
-{ "error": "Token required. Format: 'Bearer <token>'" }
+# 3. CREATE (POST) - with strong type validation
+api.post('/products', requires: { name: String, price: Float, category: ['tech', 'office'] }) do |params|
+  status 201
+  {
+    message: "Product created",
+    product: { id: rand(100..999), name: params[:name], price: params[:price] }
+  }
+end
 
-// Wrong token (403)
-{ "error": "Invalid token" }
+# 4. FULL UPDATE (PUT)
+api.put('/products/:id', requires: { name: String, price: Float }) do |params|
+  {
+    message: "Product #{params[:id]} completely updated",
+    data: params
+  }
+end
+
+# 5. PARTIAL UPDATE (PATCH)
+api.patch('/products/:id') do |params|
+  {
+    message: "Updated fields for product #{params[:id]}",
+    changes: params.except(:id)
+  }
+end
+
+# 6. DELETE (DELETE)
+api.delete('/products/:id') do |params|
+  { message: "Product #{params[:id]} deleted successfully" }
+end
 ```
 
 ---
 
-## Parameter Validation
+## Declarative Schema & Type Validation
 
-Declare required parameters at the route level. If any are missing or blank, the framework responds with `400 Bad Request` automatically — no conditional logic needed in your handler.
+The `requires:` option validates data types, string formats, uploaded files, and custom logic:
 
 ```ruby
-api.post('/users', requires: [:name, :email]) do |params|
+api.post '/catalog', requires: {
+  sku:         /^[A-Z]{3}-\d{4}$/,           # Regexp: e.g. "PRO-1234"
+  title:       String,                       # Non-empty string
+  price:       Float,                        # Float number
+  stock:       Integer,                      # Integer
+  active:      :boolean,                     # true or false
+  category:    ['electronics', 'home'],      # Enum / List of allowed values
+  photo:       :file,                        # Uploaded FilePayload
+  website:     :url,                         # Valid URL (http/https)
+  contact:     :email,                       # Valid email address
+  discount:    ->(v) { v.to_f.between?(0, 100) } # Custom Lambda validation
+} do |params|
   status 201
-  { message: "User created", user: params }
+  { status: "ok", item: params[:title] }
 end
 ```
 
-```bash
-curl -X POST http://localhost:4567/api/v1/users \
-  -H "Authorization: Bearer secret" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "Gabo"}'
+### Supported Validation Rules:
+
+| Rule | Expected Format / Type | Valid Example |
+|---|---|---|
+| `:email` | Standard email format | `"contact@domain.com"` |
+| `:url` | URL with `http://` or `https://` | `"https://api.domain.com"` |
+| `:boolean` | Native boolean (`true` or `false`) | `true`, `false` |
+| `:file` | Instance of `GRApiManager::FilePayload` | Multipart file upload |
+| `Integer` | Integer number | `42`, `100`, `-10` |
+| `Float` | Floating point number | `19.99`, `0.5`, `-3.14` |
+| `Numeric` | Any numeric value (`Integer` or `Float`) | `10`, `3.14` |
+| `String` | Non-empty string | `"Sample Text"` |
+| `Array` | Array of elements | `[1, 2, 3]` |
+| `Hash` | JSON Object or Hash | `{ key: "value" }` |
+| `['a', 'b']` | Exact inclusion in list (Enum) | `'electronics'` |
+| `/^regex$/` | Regular expression match | `"ABC-1234"` |
+| `->(val) { ... }` | Custom Lambda/Proc (must return `true`) | `->(n) { n.to_i > 0 }` |
+
+---
+
+## Comprehensive File, Binary & Image Handling
 
-# => 400 { "error": "Missing required parameters", "required": ["email"] }
+`gr_api_manager` detects incoming `Content-Type` headers and provides uniform file handling via `FilePayload`:
+
+### 1. Multipart Form Upload (`multipart/form-data`)
+```ruby
+api.post('/profile/avatar', requires: [:user_id]) do |params|
+  avatar = params[:_files][:avatar] # FilePayload instance
+
+  # Save to disk (creates directories automatically if missing)
+  saved_path = avatar.save_to("./storage/avatars/user_#{params[:user_id]}#{avatar.extension}")
+
+  {
+    message: "Avatar saved",
+    filename: avatar.filename,
+    size: avatar.size,
+    extension: avatar.extension,
+    saved_path: saved_path
+  }
+end
+```
+
+#### cURL multipart:
+```bash
+curl -X POST http://localhost:4000/profile/avatar \
+  -H "Authorization: Bearer my_token" \
+  -F "user_id=10" \
+  -F "avatar=@/path/to/my_photo.jpg"
 ```
 
 ---
 
-## Smart Type Casting
+### 2. Raw Binary Upload (Image / PDF / Octet-Stream)
 
-Query string parameters are automatically cast to native Ruby types before reaching your handler.
+Direct raw byte streaming in request body (no multipart form):
 
-| Input string | Ruby type | Value    |
-|--------------|-----------|----------|
-| `"42"`       | Integer   | `42`     |
-| `"3.14"`     | Float     | `3.14`   |
-| `"true"`     | TrueClass | `true`   |
-| `"false"`    | FalseClass| `false`  |
-| `"hello"`    | String    | `"hello"`|
+```ruby
+api.post('/documents/raw') do |params|
+  file = params[:_raw_binary] # FilePayload instance
+
+  file.save_to("./storage/docs/#{file.filename}")
+  
+  {
+    format: "raw binary",
+    detected_filename: file.filename,
+    size_bytes: file.size,
+    mime_type: file.content_type,
+    initial_hex: file.to_hex[0..30]
+  }
+end
+```
 
+#### cURL raw binary:
 ```bash
-curl "http://localhost:4567/api/v1/test/types?age=18&active=true&score=9.5" \
-  -H "Authorization: Bearer secret"
-
-# => { "age": 18, "active": true, "score": 9.5 }
+curl -X POST http://localhost:4000/documents/raw \
+  -H "Authorization: Bearer my_token" \
+  -H "Content-Type: application/pdf" \
+  -H "Content-Disposition: attachment; filename=\"contract.pdf\"" \
+  --data-binary @contract.pdf
 ```
 
 ---
 
-## Error Handling
+### 3. Base64 and Hexadecimal Conversion
+```ruby
+api.post('/files/convert') do |params|
+  file = params[:_files][:file]
 
-Global handlers return consistent JSON for unmatched routes and unhandled exceptions.
+  {
+    base64: file.to_base64, # Clean Base64 string without newlines
+    hexadecimal: file.to_hex, # Lowercase hex string
+    total_bytes: file.size
+  }
+end
+```
 
-```json
-// 404
-{ "error": "Endpoint not found", "path": "/api/v1/missing" }
+---
 
-// 500
-{ "error": "Internal Server Error", "details": "..." }
+### 4. Plain Text Upload (`text/plain`)
+```ruby
+api.post('/logs/text') do |params|
+  raw_text = params[:_raw_text] # UTF-8 String
+  { lines: raw_text.lines.count, characters: raw_text.length }
+end
 ```
 
-You can also set status codes and short-circuit responses manually inside any handler:
+---
+
+## Serving & Downloading Files to Clients
+
+When a route block returns a `String`, `gr_api_manager` serves it **directly as raw data**, allowing seamless downloads of images, PDFs, or binary streams:
 
 ```ruby
-api.get('/users/:id') do |params|
-  if params[:id] == 0
+api.get('/downloads/photo/:id', auth: false) do |params|
+  photo_path = "./storage/avatars/user_#{params[:id]}.jpg"
+  
+  unless File.exist?(photo_path)
     status 404
-    next { error: "Invalid user ID" }
+    next { error: "Photo not found" }
   end
 
-  { id: params[:id], name: "User_#{params[:id]}" }
+  # Configure response headers
+  content_type 'image/jpeg'
+  headers 'Content-Disposition' => "inline; filename=\"photo_#{params[:id]}.jpg\""
+  
+  # Return binary bytes directly
+  File.binread(photo_path)
 end
 ```
 
 ---
 
-## Request Logging
+## Rate Limiting & Real IP Detection
 
-Every request is logged to stdout with a timestamp and color-coded status:
+Protect your API with thread-safe sliding-window rate limiting per client IP:
 
-```text
-[14:32:01] GET /api/v1/health - 200
-[14:32:05] POST /api/v1/users - 400
+```ruby
+api = GRApiManager::Server.new(
+  rate_limit:          60,   # Max 60 requests
+  rate_limit_window:   60,   # per 60-second window
+  trust_proxy_headers: true  # Reads CF-Connecting-IP, X-Real-IP, X-Forwarded-For
+)
 ```
 
-Green for 2xx, red for everything else.
+Standard HTTP response headers:
+* `X-RateLimit-Limit`: Maximum allowed requests (`60`).
+* `X-RateLimit-Remaining`: Remaining requests in current window.
+* `X-RateLimit-Reset`: Unix timestamp when quota resets.
+* `Retry-After`: Seconds to wait if rate-limited (`429 Too Many Requests`).
 
 ---
 
-## Running the Server
+## Smart Parameter Casting
 
-```ruby
-api.run!
-```
+URL and Query String parameters are automatically converted to native Ruby types before entering your route block:
 
-```text
-=============================================
-  GR API MANAGER STARTED
-  Port   : 4567
-  Auth   : Enabled
-  Prefix : /api/v1
-=============================================
+```ruby
+api.get('/analytics') do |params|
+  # Request: /analytics?id=123&active=true&discount=15.5&balance=-500&category=tech
+  
+  params[:id]        # => 123 (Integer)
+  params[:active]    # => true (TrueClass)
+  params[:discount] # => 15.5 (Float)
+  params[:balance]   # => -500 (Integer)
+  params[:category]  # => "tech" (String)
+  
+  { status: "ok" }
+end
 ```
 
 ---
 
-## Full Usage Example
-
-Below is a complete working API covering the most common patterns.
+## Responses, HTTP Status Codes & Dev Mode
 
+### Custom status codes:
 ```ruby
-require 'gr_api_manager'
+api.post('/resources') do
+  status 201 # Created
+  { message: "Resource created" }
+end
+```
 
-api = GRApiManager::Server.new(
-  port: 4567,
-  bearer_token: "secret123",
-  prefix: "/api/v1"
-)
+### Developer Mode (`dev_mode: true`):
+Enable `dev_mode: true` to receive structured JSON error payloads with full stack traces during development:
 
-# 1. Public health check — no token required
-api.get('/health', auth: false) do
-  { status: 'online', time: Time.now.strftime("%Y-%m-%d %H:%M:%S") }
-end
+```ruby
+api = GRApiManager::Server.new(dev_mode: true)
+```
 
-# 2. List users — token required (default)
-api.get('/users') do |params|
-  users = [
-    { id: 1, name: "Alice", role: "admin" },
-    { id: 2, name: "Bob",   role: "viewer" }
+Error response on 500:
+```json
+{
+  "error": "Internal Server Error",
+  "details": "undefined local variable or method 'missing_var'",
+  "class": "NameError",
+  "backtrace": [
+    "/app/routes/users.rb:14:in `block in setup'",
+    "/lib/gr_api_manager.rb:482:in `instance_exec'"
   ]
-  { users: users, total: users.length }
-end
+}
+```
 
-# 3. Get single user by ID — :id is cast to Integer automatically
-api.get('/users/:id') do |params|
-  if params[:id] == 0
-    status 404
-    next { error: "User not found" }
-  end
-  { id: params[:id], name: "User_#{params[:id]}" }
-end
+---
 
-# 4. Create user — validates required fields before reaching the block
-api.post('/users', requires: [:name, :role]) do |params|
-  status 201
-  { message: "User created", user: { name: params[:name], role: params[:role] } }
-end
+## Concurrency & Production Deployment
 
-# 5. Update user
-api.put('/users/:id', requires: [:name]) do |params|
-  { message: "User #{params[:id]} updated", name: params[:name] }
-end
+### Running with Puma in Production:
+```ruby
+# Start with 4 worker processes and 4:16 threads per worker
+api.run!(workers: 4, threads: '4:16')
+```
 
-# 6. Delete user
-api.delete('/users/:id') do |params|
-  { message: "User #{params[:id]} deleted" }
-end
+### Production `Dockerfile`:
+```dockerfile
+FROM ruby:3.3-slim
 
-api.run!
-```
+WORKDIR /app
+COPY Gemfile* ./
+RUN bundle install --without development test
 
-### Minimal setup using only .env
+COPY . .
 
-```env
-# .env
-PORT=4567
-API_TOKEN=secret123
+EXPOSE 4000
+CMD ["ruby", "app.rb"]
 ```
 
-```ruby
-# api_server.rb
-require 'gr_api_manager'
+---
 
-api = GRApiManager::Server.new  # reads everything from .env
+## Automated Testing
 
-api.get('/ping', auth: false) { { pong: true } }
+Full test suite with **RSpec** and **Rack::Test**:
 
-api.run!
+```bash
+rspec
+# => 59 examples, 0 failures
 ```
 
 ---
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This project is licensed under the [MIT](LICENSE) License. Created by **Gabo Razo**.