gr_api_manager 0.1.0 → 0.3.0

data/README.md

@@ -1,164 +1,185 @@
 # GR API Manager
 
 [![Gem Version](https://badge.fury.io/rb/gr-api-manager.svg)](https://rubygems.org/gems/gr-api-manager)
+[![README en Español](https://img.shields.io/badge/README-Español-blue)](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.
+A minimal Ruby wrapper around Sinatra that eliminates boilerplate from REST API development. Auth, parameter validation, type casting, CORS, error handling, **file uploads, raw binaries, images, Base64 and hexadecimal** — all at the framework level. You write only the business logic.
 
 ---
 
 ## Features
 
-- **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`).
+- Available on **RubyGems** — install globally, use anywhere.
+- Route-level Bearer Token auth (on/off per endpoint).
+- Declarative required parameter validation → automatic `400 Bad Request`.
+- Smart type casting: `"10"` → `Integer`, `"true"` → `TrueClass`, `"9.5"` → `Float`.
+- Global JSON error responses for `404`, `500`, and `413`.
+- Broad CORS and preflight `OPTIONS` out of the box.
+- API versioning via configurable route prefix (`/api/v1`, `/geo/v2`, etc.).
+- **Full binary & file support** — multipart, raw binary, Base64, hex, `text/plain`.
+- Configurable body size limit with `mb` / `gb` helpers.
+- **Dev mode** — full stack traces on `500` for easier debugging.
 
 ---
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
-gem 'gr-api-manager'
+gem 'gr-api-manager'   # Gemfile
 ```
 
-And then execute:
 ```bash
 bundle install
-```
-
-Or install it yourself directly via RubyGems:
-```bash
-gem install gr-api-manager
+# or: gem install gr-api-manager
 ```
 
 ---
 
-## Quick Start
+## Quick Start — name it anything you want
+
+The `Server` object is just a Ruby object. Call it `api`, `app`, `pais_api`, `backend`, `mi_servicio` — whatever fits your project. There is no magic name.
 
 ```ruby
 require 'gr_api_manager'
 
-api = GRApiManager::Server.new(
-  port: 4567,
-  bearer_token: "your_secret_token",
-  prefix: "/api/v1"
-)
-
-# Public endpoint
-api.get('/health', auth: false) do
-  { status: 'online', time: Time.now.to_s }
-end
+# Any name works
+api      = GRApiManager::Server.new(port: 4567, bearer_token: "secret")
+pais_api = GRApiManager::Server.new(prefix: "/geo/v1")
+reports  = GRApiManager::Server.new(port: 5000, max_body_size: GRApiManager.gb(1))
 
+api.get('/health', auth: false) { { status: 'ok' } }
 api.run!
 ```
 
-```bash
-curl http://localhost:4567/api/v1/health
-# => {"status":"online","time":"..."}
-```
-
 ---
 
 ## Configuration
 
-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.
-
 ```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
+  port:            4567,
+  bearer_token:    "secret",
+  permitted_hosts: ["example.com"],   # empty = allow all
+  prefix:          "/api/v1",
+  max_body_size:   GRApiManager.mb(50),  # default 50 MB
+  dev_mode:        false                 # default false
 )
 ```
 
-### Using a .env file (Recommended)
+### Size helpers
 
-Create a `.env` file at the root of your project:
+Express limits cleanly without doing manual math:
+
+```ruby
+GRApiManager.mb(50)    # 50 megabytes
+GRApiManager.mb(200)   # 200 megabytes — for large file uploads
+GRApiManager.gb(1)     # 1 gigabyte   — for heavy reports or video
+
+# Examples
+video_api  = GRApiManager::Server.new(max_body_size: GRApiManager.gb(2))
+json_api   = GRApiManager::Server.new(max_body_size: GRApiManager.mb(1))
+report_api = GRApiManager::Server.new(max_body_size: GRApiManager.mb(500))
+```
+
+### `.env` file (recommended for production)
 
 ```env
 PORT=4567
 API_TOKEN=your_secret_token
 ```
 
-Then initialize the manager with no arguments and it will pick everything up automatically:
-
 ```ruby
-require 'gr_api_manager'
-
-api = GRApiManager::Server.new
-# Reads PORT and API_TOKEN from .env
+api = GRApiManager::Server.new   # picks up PORT and API_TOKEN automatically
 ```
 
-This is the recommended approach for production — keep secrets out of source code and out of version control. Add `.env` to your `.gitignore`.
+Explicit arguments always override `.env`. Add `.env` to `.gitignore`.
 
-```text
-# .gitignore
-.env
-```
+---
 
-### Priority order
+## HTTP Verbs — what each one does
 
-When a value is provided both in code and in `.env`, the explicit argument always wins:
+| Method | Purpose | Typical use |
+|---|---|---|
+| `GET` | **Read** — fetch data, no side effects | List, search, get by ID |
+| `POST` | **Create** — add a new resource | Create user, upload file |
+| `PUT` | **Full replace** — replace an existing resource entirely | Update full user profile |
+| `PATCH` | **Partial update** — modify specific fields only | Change only an email |
+| `DELETE` | **Remove** — delete a resource | Delete user, remove file |
 
-```text
-new(bearer_token: "hardcoded")  >  ENV['API_TOKEN']  >  nil (auth disabled)
-new(port: 4567)                 >  ENV['PORT']        >  4000
+```ruby
+api.get('/users')         { ... }   # list
+api.get('/users/:id')     { ... }   # read one
+api.post('/users')        { ... }   # create
+api.put('/users/:id')     { ... }   # full replace
+api.patch('/users/:id')   { ... }   # partial update
+api.delete('/users/:id')  { ... }   # delete
 ```
 
 ---
 
 ## Defining Routes
 
-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.
-
 ```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
-  }
+api.post('/path', auth: true, requires: [:name, :email]) do |params|
+  # params — merged hash: URL segments + query string (type-cast) + parsed body
+  { result: "ok" }
 end
 ```
 
-### Options
-
-| Option     | Type    | Default | Description                                      |
-|------------|---------|---------|--------------------------------------------------|
-| `auth`     | Boolean | `true`  | Require Bearer Token for this route              |
-| `requires` | Array   | `[]`    | List of required parameter keys (symbols/strings)|
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `auth` | Boolean | `true` | Require Bearer Token |
+| `requires` | Array | `[]` | Required parameter keys |
 
 ---
 
-## Authentication
+## Success Responses
 
-All routes require a valid Bearer Token by default. Pass the token in the `Authorization` header:
+Return any Hash or Array — the framework serializes to JSON automatically.
 
-```bash
-curl -H "Authorization: Bearer your_secret_token" http://localhost:4567/api/v1/users
+```ruby
+# Simple hash
+api.get('/ping', auth: false) { { pong: true } }
+
+# Set a status code
+api.post('/users', requires: [:name]) do |params|
+  status 201
+  { message: "Created", user: { name: params[:name] } }
+end
+
+# Short-circuit with next
+api.get('/users/:id') do |params|
+  if params[:id] == 0
+    status 404
+    next { error: "Not found" }
+  end
+  { id: params[:id], name: "Alice" }
+end
 ```
 
-To make a route public, set `auth: false`:
+> Returning a `String` sends it **as-is** (no JSON wrapping) — useful for binary file responses.
+
+---
+
+## Authentication
 
 ```ruby
-api.get('/health', auth: false) do
-  { status: 'online' }
+api.get('/health', auth: false) { { status: 'online' } }  # public
+
+api.get('/data') do |params|    # protected (default)
+  { secret: "data" }
 end
 ```
 
-**Automatic Error Responses:**
+```bash
+curl -H "Authorization: Bearer your_token" http://localhost:4567/api/v1/data
+```
 
 ```json
-// Missing header (401)
+// 401 — missing header
 { "error": "Token required. Format: 'Bearer <token>'" }
 
-// Wrong token (403)
+// 403 — wrong token
 { "error": "Invalid token" }
 ```
 
@@ -166,10 +187,8 @@ end
 
 ## Parameter 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.
-
 ```ruby
-api.post('/users', requires: [:name, :email]) do |params|
+api.post('/users', requires: [:name, :email, :role]) do |params|
   status 201
   { message: "User created", user: params }
 end
@@ -179,37 +198,219 @@ end
 curl -X POST http://localhost:4567/api/v1/users \
   -H "Authorization: Bearer secret" \
   -H "Content-Type: application/json" \
-  -d '{"name": "Gabo"}'
+  -d '{"name":"Gabo"}'
 
-# => 400 { "error": "Missing required parameters", "required": ["email"] }
+# => 400 { "error": "Missing required parameters", "required": ["email", "role"] }
 ```
 
 ---
 
 ## Smart Type Casting
 
-Query string parameters are automatically cast to native Ruby types before reaching your handler.
+Query string values are cast to native Ruby types before reaching your block:
 
-| Input string | Ruby type | Value    |
-|--------------|-----------|----------|
-| `"42"`       | Integer   | `42`     |
-| `"3.14"`     | Float     | `3.14`   |
-| `"true"`     | TrueClass | `true`   |
-| `"false"`    | FalseClass| `false`  |
-| `"hello"`    | String    | `"hello"`|
+| String | Ruby type | Value |
+|---|---|---|
+| `"42"` | Integer | `42` |
+| `"3.14"` | Float | `3.14` |
+| `"true"` | TrueClass | `true` |
+| `"false"` | FalseClass | `false` |
 
 ```bash
-curl "http://localhost:4567/api/v1/test/types?age=18&active=true&score=9.5" \
-  -H "Authorization: Bearer secret"
+curl "http://localhost:4567/api/v1/products?page=2&active=true&price=9.99"
+# params => { page: 2, active: true, price: 9.99 }
+```
+
+---
+
+## File & Binary Body Handling
+
+The framework auto-detects `Content-Type` and parses accordingly. **No extra setup needed.**
 
-# => { "age": 18, "active": true, "score": 9.5 }
+### Supported body formats
+
+| Content-Type | What you get in `params` |
+|---|---|
+| `application/json` | Regular symbolized hash |
+| `multipart/form-data` | Text fields + `:_files` → `{ field: FilePayload }` |
+| `image/*`, `video/*`, `audio/*` | `:_raw_binary` → `FilePayload` |
+| `application/pdf`, `application/msword`, `application/vnd.*` | `:_raw_binary` → `FilePayload` |
+| `application/octet-stream` | `:_raw_binary` → `FilePayload` |
+| `text/plain` | `:_raw_text` → `String` |
+
+### `FilePayload` API
+
+| Method | Returns | Description |
+|---|---|---|
+| `#read` | `String` (binary) | Raw bytes |
+| `#to_base64` | `String` | Base64-encoded (no newlines) |
+| `#to_hex` | `String` | Lowercase hexadecimal string |
+| `#save_to(path)` | `String` | Save to disk, returns path |
+| `#filename` | `String` | Original filename |
+| `#content_type` | `String` | MIME type |
+| `#size` | `Integer` | Size in bytes |
+| `#extension` | `String` | Extension (`.jpg`, `.pdf`, etc.) |
+| `#to_h` | `Hash` | JSON-safe summary |
+
+### Multipart image upload
+
+```ruby
+api.post('/upload/avatar', auth: true) do |params|
+  file = params[:_files][:avatar]
+  halt 400, { error: 'Field "avatar" required' }.to_json unless file
+  halt 400, { error: "Invalid type" }.to_json unless %w[.jpg .png .webp].include?(file.extension)
+
+  file.save_to("/uploads/#{file.filename}")
+  status 201
+  { message: "Uploaded", file: file.to_h }
+end
+```
+
+```bash
+curl -X POST http://localhost:4567/api/v1/upload/avatar \
+  -H "Authorization: Bearer secret" \
+  -F "avatar=@photo.jpg"
+```
+
+### Multiple files in one request
+
+```ruby
+api.post('/documents', auth: true) do |params|
+  files = params[:_files] || {}
+  halt 400, { error: 'No files received' }.to_json if files.empty?
+
+  saved = files.map { |_, f| f.save_to("/uploads/#{f.filename}"); f.to_h }
+  status 201
+  { uploaded: saved }
+end
+```
+
+```bash
+curl -X POST http://localhost:4567/api/v1/documents \
+  -H "Authorization: Bearer secret" \
+  -F "doc=@report.pdf" -F "thumbnail=@thumb.png"
+```
+
+### Raw binary body (image, PDF, Word, etc.)
+
+```ruby
+api.post('/files/raw', auth: true) do |params|
+  file = params[:_raw_binary]
+  halt 400, { error: 'Binary body required' }.to_json unless file
+
+  path = file.save_to("/uploads/#{file.filename}")
+  { saved_to: path, magic_bytes: file.to_hex[0, 8], size: file.size }
+end
+```
+
+```bash
+curl -X POST http://localhost:4567/api/v1/files/raw \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: image/png" --data-binary @photo.png
+
+curl -X POST http://localhost:4567/api/v1/files/raw \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/pdf" --data-binary @doc.pdf
+```
+
+### Base64 inside JSON
+
+```ruby
+require 'base64'
+
+api.post('/files/base64', auth: true, requires: [:data, :filename]) do |params|
+  raw  = Base64.strict_decode64(params[:data])
+  File.open("/uploads/#{params[:filename]}", 'wb') { |f| f.write(raw) }
+  { message: "Saved", bytes: raw.bytesize }
+end
+```
+
+```bash
+BASE64=$(base64 -w0 photo.jpg)
+curl -X POST http://localhost:4567/api/v1/files/base64 \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d "{\"filename\":\"photo.jpg\",\"data\":\"$BASE64\"}"
+```
+
+### Hexadecimal
+
+```ruby
+api.post('/files/tohex', auth: true) do |params|
+  file = params[:_raw_binary]
+  halt 400, { error: 'Binary body required' }.to_json unless file
+  # to_hex converts any binary to a lowercase hex string
+  { hex: file.to_hex, bytes: file.size }
+end
+```
+
+### Plain text body
+
+```ruby
+api.post('/notes', auth: true) do |params|
+  text = params[:_raw_text]
+  halt 400, { error: 'Empty body' }.to_json if text.nil? || text.strip.empty?
+  { received: text, words: text.split.size }
+end
+```
+
+### Serving a file as binary response
+
+```ruby
+api.get('/files/:name', auth: true) do |params|
+  path = "/uploads/#{File.basename(params[:name].to_s)}"
+  halt 404, { error: "Not found" }.to_json unless File.exist?(path)
+
+  content_type 'application/octet-stream'
+  response.headers['Content-Disposition'] = "attachment; filename=\"#{File.basename(path)}\""
+  File.binread(path)   # String → sent as-is, no JSON wrapping
+end
+```
+
+### Body size limit
+
+```json
+// When exceeded → 413
+{ "error": "Payload too large", "max_bytes": 52428800 }
+```
+
+```ruby
+GRApiManager::Server.new(max_body_size: GRApiManager.mb(200))  # 200 MB
+GRApiManager::Server.new(max_body_size: GRApiManager.gb(2))    # 2 GB
+GRApiManager::Server.new(max_body_size: GRApiManager.mb(1))    # 1 MB
 ```
 
 ---
 
-## Error Handling
+## Dev Mode
+
+Enable during development for full stack traces on `500` errors:
 
-Global handlers return consistent JSON for unmatched routes and unhandled exceptions.
+```ruby
+api = GRApiManager::Server.new(
+  bearer_token: "secret",
+  dev_mode: true   # ⚠️ Disable in production
+)
+```
+
+**Production (dev_mode: false):**
+```json
+{ "error": "Internal Server Error", "details": "undefined method 'foo' for nil" }
+```
+
+**Development (dev_mode: true):**
+```json
+{
+  "error": "Internal Server Error",
+  "details": "undefined method 'foo' for nil",
+  "class": "NoMethodError",
+  "backtrace": ["app.rb:42:in 'block in register_route'", "..."]
+}
+```
+
+---
+
+## Error Handling
 
 ```json
 // 404
@@ -217,30 +418,19 @@ Global handlers return consistent JSON for unmatched routes and unhandled except
 
 // 500
 { "error": "Internal Server Error", "details": "..." }
-```
-
-You can also set status codes and short-circuit responses manually inside any handler:
 
-```ruby
-api.get('/users/:id') do |params|
-  if params[:id] == 0
-    status 404
-    next { error: "Invalid user ID" }
-  end
-
-  { id: params[:id], name: "User_#{params[:id]}" }
-end
+// 413
+{ "error": "Payload too large", "max_bytes": 52428800 }
 ```
 
 ---
 
 ## Request Logging
 
-Every request is logged to stdout with a timestamp and color-coded status:
-
 ```text
-[14:32:01] GET /api/v1/health - 200
+[14:32:01] GET  /api/v1/health - 200
 [14:32:05] POST /api/v1/users - 400
+[14:32:10] POST /api/v1/upload/avatar - 201
 ```
 
 Green for 2xx, red for everything else.
@@ -249,97 +439,389 @@ Green for 2xx, red for everything else.
 
 ## Running the Server
 
-```ruby
-api.run!
-```
-
 ```text
 =============================================
   GR API MANAGER STARTED
-  Port   : 4567
-  Auth   : Enabled
-  Prefix : /api/v1
+  Port      : 4567
+  Auth      : Enabled
+  Prefix    : /api/v1
+  Max Body  : 50.0 MB
+  Dev Mode  : Off
 =============================================
 ```
 
 ---
 
-## Full Usage Example
+## Complete Example — Country API
 
-Below is a complete working API covering the most common patterns.
+This shows how the framework handles a real-world CRUD API with file uploads. Note that the server is named `pais_api` — **you can name it anything**.
 
 ```ruby
 require 'gr_api_manager'
+require 'fileutils'
 
-api = GRApiManager::Server.new(
-  port: 4567,
-  bearer_token: "secret123",
-  prefix: "/api/v1"
+FileUtils.mkdir_p('/uploads/flags')
+
+pais_api = GRApiManager::Server.new(
+  port:          4567,
+  bearer_token:  "geo_secret_2024",
+  prefix:        "/geo/v1",
+  max_body_size: GRApiManager.mb(5),
+  dev_mode:      true
 )
 
-# 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") }
+COUNTRIES = [
+  { id: 1, name: "Mexico",    capital: "Mexico City",  pop: 128_000_000, continent: "North America" },
+  { id: 2, name: "Argentina", capital: "Buenos Aires", pop: 45_000_000,  continent: "South America" },
+  { id: 3, name: "Spain",     capital: "Madrid",       pop: 47_000_000,  continent: "Europe" }
+]
+
+# GET — list all (public)
+pais_api.get('/countries', auth: false) do
+  { total: COUNTRIES.size, countries: COUNTRIES }
 end
 
-# 2. List users — token required (default)
-api.get('/users') do |params|
-  users = [
-    { id: 1, name: "Alice", role: "admin" },
-    { id: 2, name: "Bob",   role: "viewer" }
-  ]
-  { users: users, total: users.length }
+# GET — single country (:id cast to Integer automatically)
+pais_api.get('/countries/:id', auth: false) do |params|
+  c = COUNTRIES.find { |x| x[:id] == params[:id] }
+  status 404 and next { error: "Not found" } unless c
+  c
 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]}" }
+# GET — search by name
+pais_api.get('/countries/search', auth: false, requires: [:name]) do |params|
+  results = COUNTRIES.select { |c| c[:name].downcase.include?(params[:name].downcase) }
+  { total: results.size, countries: results }
 end
 
-# 4. Create user — validates required fields before reaching the block
-api.post('/users', requires: [:name, :role]) do |params|
+# POST — create (protected)
+pais_api.post('/countries', auth: true, requires: [:name, :capital, :pop]) do |params|
+  c = { id: COUNTRIES.size + 1, name: params[:name],
+        capital: params[:capital], pop: params[:pop],
+        continent: params[:continent] || "Unknown" }
+  COUNTRIES << c
   status 201
-  { message: "User created", user: { name: params[:name], role: params[:role] } }
+  { message: "Country created", country: c }
 end
 
-# 5. Update user
-api.put('/users/:id', requires: [:name]) do |params|
-  { message: "User #{params[:id]} updated", name: params[:name] }
+# PUT — full replace (protected)
+pais_api.put('/countries/:id', auth: true, requires: [:name, :capital]) do |params|
+  c = COUNTRIES.find { |x| x[:id] == params[:id] }
+  status 404 and next { error: "Not found" } unless c
+  c[:name] = params[:name]; c[:capital] = params[:capital]
+  c[:pop]  = params[:pop] if params[:pop]
+  { message: "Updated", country: c }
 end
 
-# 6. Delete user
-api.delete('/users/:id') do |params|
-  { message: "User #{params[:id]} deleted" }
+# PATCH — partial update (protected)
+pais_api.patch('/countries/:id', auth: true) do |params|
+  c = COUNTRIES.find { |x| x[:id] == params[:id] }
+  status 404 and next { error: "Not found" } unless c
+  [:name, :capital, :pop, :continent].each { |k| c[k] = params[k] if params[k] }
+  { message: "Patched", country: c }
 end
 
-api.run!
+# DELETE (protected)
+pais_api.delete('/countries/:id', auth: true) do |params|
+  c = COUNTRIES.find { |x| x[:id] == params[:id] }
+  status 404 and next { error: "Not found" } unless c
+  COUNTRIES.delete(c)
+  { message: "Deleted", id: params[:id] }
+end
+
+# POST — upload flag (multipart, protected)
+pais_api.post('/countries/:id/flag', auth: true) do |params|
+  file = params[:_files]&.dig(:flag)
+  halt 400, { error: 'Field "flag" required' }.to_json unless file
+  halt 400, { error: "Format not allowed: #{file.extension}" }.to_json \
+    unless %w[.jpg .jpeg .png .svg .webp].include?(file.extension)
+
+  file.save_to("/uploads/flags/#{params[:id]}#{file.extension}")
+  status 201
+  { message: "Flag uploaded", file: file.to_h }
+end
+
+# GET — download flag (public, binary response)
+pais_api.get('/countries/:id/flag', auth: false) do |params|
+  f = Dir.glob("/uploads/flags/#{params[:id]}.*").first
+  halt 404, { error: "Flag not found" }.to_json unless f
+
+  content_type 'application/octet-stream'
+  response.headers['Content-Disposition'] = "attachment; filename=\"#{File.basename(f)}\""
+  File.binread(f)
+end
+
+pais_api.run!
+```
+
+```bash
+curl http://localhost:4567/geo/v1/countries
+curl http://localhost:4567/geo/v1/countries/1
+curl -X POST http://localhost:4567/geo/v1/countries \
+  -H "Authorization: Bearer geo_secret_2024" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Brazil","capital":"Brasilia","pop":215000000}'
+curl -X PATCH http://localhost:4567/geo/v1/countries/1 \
+  -H "Authorization: Bearer geo_secret_2024" \
+  -H "Content-Type: application/json" \
+  -d '{"pop":130000000}'
+curl -X POST http://localhost:4567/geo/v1/countries/1/flag \
+  -H "Authorization: Bearer geo_secret_2024" \
+  -F "flag=@mexico_flag.png"
+curl -X DELETE http://localhost:4567/geo/v1/countries/3 \
+  -H "Authorization: Bearer geo_secret_2024"
 ```
 
-### Minimal setup using only .env
+---
+
+## High Traffic & Concurrency
+
+GR API Manager is built on **Puma** (the standard production Ruby server) and handles concurrent traffic out of the box. Here's how each layer works and what you can tune.
+
+### How it handles concurrency
+
+Puma uses a **multi-worker + multi-thread** model:
+- **Workers** = OS processes, each with its own memory. More workers = more CPU cores used.
+- **Threads** = lightweight concurrent handlers inside each worker. Threads share memory.
 
-```env
-# .env
-PORT=4567
-API_TOKEN=secret123
 ```
+Request → Worker 1 → Thread A  →  route handler
+                   → Thread B  →  route handler
+                   → ...
+       → Worker 2 → Thread A  →  route handler
+                   → ...
+```
+
+A server with `workers: 4, threads: '2:8'` can handle up to **32 simultaneous requests** before queuing.
+
+### Configuring workers and threads
+
+Pass them directly to `run!`:
 
 ```ruby
-# api_server.rb
+api.run!(
+  workers: 4,     # Number of Puma worker processes
+  threads: '2:8'  # min_threads:max_threads per worker
+)
+```
+
+Or via environment variables (recommended for production):
+
+```bash
+WEB_CONCURRENCY=4 ruby app.rb
+```
+
+**Practical starting points:**
+
+| Scenario | Workers | Threads |
+|---|---|---|
+| Development / local | 1 | `1:4` |
+| Small server (1–2 CPU cores) | 2 | `2:8` |
+| Medium server (4 CPU cores) | 4 | `2:8` |
+| High-traffic (8+ CPU cores) | 8 | `4:16` |
+| I/O-heavy (DB, external APIs) | 2 | `8:32` |
+
+### Built-in rate limiting
+
+Protect your server from flooding and abusive clients with the built-in sliding-window rate limiter:
+
+```ruby
+api = GRApiManager::Server.new(
+  bearer_token:      "secret",
+  rate_limit:        100,   # max 100 requests per IP
+  rate_limit_window: 60     # per 60-second window
+)
+```
+
+When a client exceeds the limit, they receive `429 Too Many Requests`:
+
+```json
+{ "error": "Too many requests", "retry_after_seconds": 60 }
+```
+
+Response headers are automatically added to every request:
+
+```
+X-RateLimit-Limit:     100
+X-RateLimit-Remaining: 47
+Retry-After:           60   (only on 429 responses)
+X-RateLimit-Reset:     1721620800
+```
+
+The limiter is **thread-safe** (uses a `Mutex`) and runs a background cleanup thread automatically to prevent memory growth from tracked IPs.
+
+**Common rate limit configs:**
+
+```ruby
+# Public API — moderate protection
+GRApiManager::Server.new(rate_limit: 200, rate_limit_window: 60)
+
+# Strict — auth endpoints, login, password reset
+GRApiManager::Server.new(rate_limit: 10, rate_limit_window: 60)
+
+# Generous — internal service behind a trusted proxy
+GRApiManager::Server.new(rate_limit: 2000, rate_limit_window: 60)
+```
+
+### Production architecture for truly massive traffic
+
+For thousands of concurrent users, add layers in front of the framework:
+
+```
+Internet
+   │
+   ▼
+[Nginx]          ← terminates SSL, serves static files, load balances
+   │
+   ├──▶ GR API Manager (worker 1, port 4567)
+   ├──▶ GR API Manager (worker 2, port 4568)
+   └──▶ GR API Manager (worker 3, port 4569)
+```
+
+**Minimal Nginx config for load balancing:**
+
+```nginx
+upstream gr_api {
+    server 127.0.0.1:4567;
+    server 127.0.0.1:4568;
+    server 127.0.0.1:4569;
+}
+
+server {
+    listen 80;
+    server_name api.yourdomain.com;
+
+    location / {
+        proxy_pass         http://gr_api;
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+```
+
+### What the banner shows
+
+```text
+=============================================
+  GR API MANAGER STARTED
+  Port      : 4567
+  Auth      : Enabled
+  Prefix    : /api/v1
+  Max Body  : 50.0 MB
+  Workers   : 4  |  Threads: 2:8
+  Rate Limit: 100 req / 60s per IP
+  Dev Mode  : Off
+=============================================
+```
+
+---
+
+## Multiple Route Groups on One Server
+
+
+You don't need to spin up separate servers for different API sections. Register all your route groups on **a single server instance** — one process, one port, zero extra resource cost.
+
+The cleanest pattern is to extract each group into its own file and pass the server object as an argument:
+
+```
+project/
+├── main.rb
+└── routes/
+    ├── users.rb
+    ├── countries.rb
+    └── products.rb
+```
+
+```ruby
+# routes/users.rb
+def register_users(api)
+  api.get('/users', auth: false) do
+    { users: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }] }
+  end
+
+  api.post('/users', auth: true, requires: [:name, :email]) do |params|
+    status 201
+    { message: "User created", user: { name: params[:name], email: params[:email] } }
+  end
+
+  api.delete('/users/:id', auth: true) do |params|
+    { message: "User #{params[:id]} deleted" }
+  end
+end
+```
+
+```ruby
+# routes/countries.rb
+def register_countries(api)
+  COUNTRIES = [
+    { id: 1, name: "Mexico", capital: "Mexico City" },
+    { id: 2, name: "Spain",  capital: "Madrid" }
+  ]
+
+  api.get('/countries', auth: false) do
+    { total: COUNTRIES.size, countries: COUNTRIES }
+  end
+
+  api.get('/countries/:id', auth: false) do |params|
+    c = COUNTRIES.find { |x| x[:id] == params[:id] }
+    status 404 and next { error: "Not found" } unless c
+    c
+  end
+end
+```
+
+```ruby
+# routes/products.rb
+def register_products(api)
+  api.get('/products', auth: false) do
+    { products: [{ id: 1, name: "Laptop", price: 999.99 }] }
+  end
+
+  api.post('/products', auth: true, requires: [:name, :price]) do |params|
+    status 201
+    { message: "Product created", product: { name: params[:name], price: params[:price] } }
+  end
+end
+```
+
+```ruby
+# main.rb — one server, three route groups, one process
 require 'gr_api_manager'
+require_relative 'routes/users'
+require_relative 'routes/countries'
+require_relative 'routes/products'
 
-api = GRApiManager::Server.new  # reads everything from .env
+api = GRApiManager::Server.new(
+  port:         4567,
+  bearer_token: "secret",
+  prefix:       "/api/v1"
+)
 
-api.get('/ping', auth: false) { { pong: true } }
+register_users(api)       # mounts: GET/POST /api/v1/users, DELETE /api/v1/users/:id
+register_countries(api)   # mounts: GET /api/v1/countries, GET /api/v1/countries/:id
+register_products(api)    # mounts: GET/POST /api/v1/products
 
 api.run!
+# All routes available on a single process at localhost:4567
 ```
 
+```bash
+# All three groups work on the same server
+curl http://localhost:4567/api/v1/users
+curl http://localhost:4567/api/v1/countries
+curl http://localhost:4567/api/v1/products
+
+curl -X POST http://localhost:4567/api/v1/users \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Carlos","email":"carlos@example.com"}'
+```
+
+This approach scales cleanly — add new route groups without touching `main.rb` logic, and everything shares the same auth token, prefix, and body size limit.
+
 ---
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).