tina4ruby 3.0.0 → 3.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47c53ad8cda483d0cde2eaec4072b5620de88dbd172d45fe9ab0df52a865c71e
-  data.tar.gz: 438bbf58dc14e8b7f91007cde01c53bc4326b4b088c8d39fac845189da9a2cf9
+  metadata.gz: 101a34de44fea572c9c21c8fea286f7adfb4c34fa5227be1c82b7def86ec8d71
+  data.tar.gz: d86ffef03c13ef707952678dde2961f9b430f81a81d7d618dd2a3c4811295611
 SHA512:
-  metadata.gz: ae5246539beea74da1618b9e498d6f6f1ea3949e26663ec862d79934c3acdb6ec7ba59cb49778444badcab81aaa5a42de3e8e2c02ed4717d3ba368f0701045a7
-  data.tar.gz: ddecbcd770270106b44733563e9c83f58e5b3084a0b190f3b5ea8041066f310cfec6017ee5e0fa03895c048a7a61100f9a8bca222a23825794726fdc7c1bebad
+  metadata.gz: 4446bf6ba80cdfb3d2ab17dabd523641f26a9eb09dbbff3cb9b6397e501206afa18bf85c1fe7b147d2aa0910ad2ca225322d7329cc6e3022ad493daee2f0e5a6
+  data.tar.gz: d4a7c8481f75d1fce92031da88b72ac88eda029aef5ebd417010c5545429b68c8f4fffd7a9048565df0e4512bfe6a23d3a578b4b952211ef2147978c18ca31ab

data/README.md

@@ -9,6 +9,14 @@
   Laravel joy. Ruby speed. 10x less code. Zero third-party dependencies.
 </p>
 
+<p align="center">
+  <a href="https://rubygems.org/gems/tina4"><img src="https://img.shields.io/gem/v/tina4?color=7b1fa2&label=RubyGems" alt="Gem"></a>
+  <img src="https://img.shields.io/badge/tests-1%2C578%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/features-38-blue" alt="Features">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
+  <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
+</p>
+
 <p align="center">
   <a href="https://tina4.com">Documentation</a> &bull;
   <a href="#getting-started">Getting Started</a> &bull;
@@ -17,27 +25,55 @@
   <a href="https://tina4.com">tina4.com</a>
 </p>
 
-<p align="center">
-  <img src="https://img.shields.io/badge/tests-1334%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/carbonah-A%2B%20rated-00cc44" alt="Carbonah A+">
-  <img src="https://img.shields.io/badge/zero--dep-core-blue" alt="Zero Dependencies">
-  <img src="https://img.shields.io/badge/ruby-3.1%2B-blue" alt="Ruby 3.1+">
-  <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT License">
-</p>
-
 ---
 
-## Quickstart
+## Quick Start
 
 ```bash
-gem install tina4ruby
-tina4ruby init my-app
-cd my-app
-tina4ruby serve
-# -> http://localhost:7147
+# Install the Tina4 CLI
+cargo install tina4  # or download binary from https://github.com/tina4stack/tina4/releases
+
+# Create a project
+tina4 init ruby ./my-app
+
+# Run it
+cd my-app && tina4 serve
 ```
 
-That's it. Zero configuration, zero classes, zero boilerplate.
+Open http://localhost:7147 — your app is running.
+
+<details>
+<summary><strong>Without the Tina4 CLI</strong></summary>
+
+```bash
+# 1. Create project
+mkdir my-app && cd my-app
+echo 'source "https://rubygems.org"' > Gemfile
+echo 'gem "tina4-ruby", "~> 3.0"' >> Gemfile
+bundle install
+
+# 2. Create entry point
+cat > app.rb << 'EOF'
+require "tina4"
+Tina4.initialize!(__dir__)
+app = Tina4::RackApp.new
+Tina4::WebServer.new(app, host: "0.0.0.0", port: 7147).start
+EOF
+
+# 3. Create .env
+echo 'TINA4_DEBUG=true' > .env
+echo 'TINA4_LOG_LEVEL=ALL' >> .env
+
+# 4. Create route directory
+mkdir -p src/routes
+
+# 5. Run
+bundle exec ruby app.rb
+```
+
+Open http://localhost:7147
+
+</details>
 
 ---
 
@@ -50,17 +86,17 @@ Every feature is built from scratch -- no gem install, no node_modules, no third
 | **HTTP** | Rack 3 server, block routing, path params (`{id:int}`, `{p:path}`), middleware pipeline, CORS, rate limiting, graceful shutdown |
 | **Templates** | Frond engine (Twig-compatible), inheritance, partials, 35+ filters, macros, fragment caching, sandboxing |
 | **ORM** | Active Record, typed fields with validation, soft delete, relationships (`has_one`/`has_many`/`belongs_to`), scopes, result caching, multi-database |
-| **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface |
-| **Auth** | Zero-dep JWT (RS256), sessions (file, Redis, MongoDB), password hashing, form tokens |
-| **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE |
-| **Background** | DB-backed queue with priority, delayed jobs, retry, batch processing, multi-queue |
+| **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface, query caching (TINA4_DB_CACHE=true for 4x speedup) |
+| **Auth** | Zero-dep JWT (HS256/RS256), sessions (file/Redis/Valkey/MongoDB/database), password hashing, form tokens |
+| **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE, WSDL/SOAP with auto WSDL |
+| **Background** | Queue (SQLite/RabbitMQ/Kafka/MongoDB) with priority, delayed jobs, retry, batch processing |
 | **Real-time** | Native WebSocket (RFC 6455), per-path routing, connection manager |
 | **Frontend** | tina4-css (~24 KB), frond.js helper, SCSS compiler, live reload, CSS hot-reload |
 | **DX** | Dev admin dashboard, error overlay, request inspector, AI tool integration, Carbonah green benchmarks |
 | **Data** | Migrations with rollback, 50+ fake data generators, ORM and table seeders |
-| **Other** | REST client, localization (6 languages), in-memory cache (TTL/tags/LRU), event system, inline testing, configurable error pages |
+| **Other** | REST client, localization (6 languages), cache (memory/Redis/file), event system, inline testing, messenger (.env driven), configurable error pages |
 
-**676 tests across 28 modules. All Carbonah benchmarks rated A+.**
+**1,578 tests across 38 built-in features. Zero dependencies. All Carbonah benchmarks rated A+.**
 
 For full documentation visit **[tina4.com](https://tina4.com)**.
 
@@ -322,7 +358,7 @@ db = Tina4::Database.new("mysql://localhost:3306/mydb", username: "user", passwo
 db = Tina4::Database.new("mssql://localhost:1433/mydb", username: "sa", password: "pass")
 db = Tina4::Database.new("firebird://localhost:3050/path/to/db", username: "SYSDBA", password: "masterkey")
 
-result = db.fetch("SELECT * FROM users WHERE age > ?", [18], limit: 20, skip: 0)
+result = db.fetch("SELECT * FROM users WHERE age > ?", [18], limit: 20, offset: 0)
 row = db.fetch_one("SELECT * FROM users WHERE id = ?", [1])
 db.insert("users", { name: "Alice", email: "alice@test.com" })
 db.commit
@@ -345,9 +381,9 @@ end
 ### JWT Authentication
 
 ```ruby
-auth = Tina4::Auth.new
-token = auth.get_token({ user_id: 42 })
-payload = auth.get_payload(token)
+token = Tina4::Auth.get_token({ user_id: 42 })
+result = Tina4::Auth.valid_token(token)
+payload = Tina4::Auth.get_payload(token)
 ```
 
 POST/PUT/PATCH/DELETE routes require `Authorization: Bearer <token>` by default. Use `auth: false` to make public, `secure_get` to protect GET routes.
@@ -364,11 +400,10 @@ Backends: file (default), Redis, MongoDB. Set via `TINA4_SESSION_HANDLER` in `.e
 ### Queues
 
 ```ruby
-producer = Tina4::Producer.new(Tina4::Queue.new(topic: "emails"))
-producer.produce({ to: "alice@example.com" })
+queue = Tina4::Queue.new(topic: "emails")
+queue.produce("emails", { to: "alice@example.com" })
 
-consumer = Tina4::Consumer.new(Tina4::Queue.new(topic: "emails"))
-consumer.each { |msg| send_email(msg.data) }
+queue.consume("emails") { |msg| send_email(msg.payload) }
 ```
 
 ### GraphQL
@@ -486,7 +521,7 @@ cache.tag("users").flush
 
 ## Dev Mode
 
-Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
+Set `TINA4_DEBUG=true` in `.env` to enable:
 
 - **Live reload** -- browser auto-refreshes on code changes
 - **CSS hot-reload** -- SCSS changes apply without page refresh
@@ -500,9 +535,14 @@ Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
 ```bash
 tina4ruby init [dir]             # Scaffold a new project
 tina4ruby serve [port]           # Start dev server (default: 7147)
+tina4ruby serve --production     # Auto-install and use Puma production server
 tina4ruby migrate                # Run pending migrations
 tina4ruby migrate --create <desc># Create a migration file
 tina4ruby migrate --rollback     # Rollback last batch
+tina4ruby generate model <name>  # Generate ORM model scaffold
+tina4ruby generate route <name>  # Generate route scaffold
+tina4ruby generate migration <d> # Generate migration file
+tina4ruby generate middleware <n># Generate middleware scaffold
 tina4ruby seed                   # Run seeders from src/seeds/
 tina4ruby routes                 # List all registered routes
 tina4ruby test                   # Run test suite
@@ -510,6 +550,53 @@ tina4ruby build                  # Build distributable gem
 tina4ruby ai [--all]             # Detect AI tools and install context
 ```
 
+### Production Server Auto-Detection
+
+`tina4 serve` automatically detects and uses the best available production server:
+
+- **Ruby**: Puma (if installed), otherwise WEBrick -- Puma gives 2.8x improvement
+- Use `tina4ruby serve --production` to auto-install Puma
+
+### Scaffolding with `tina4 generate`
+
+Quickly scaffold new components:
+
+```bash
+tina4ruby generate model User          # Creates src/orm/user.rb with field stubs
+tina4ruby generate route users         # Creates src/routes/users.rb with CRUD stubs
+tina4ruby generate migration "add age" # Creates migration SQL file
+tina4ruby generate middleware AuthLog   # Creates middleware class
+```
+
+### ORM Relationships & Eager Loading
+
+```ruby
+# Relationships
+orders = user.has_many("Order", "user_id")
+profile = user.has_one("Profile", "user_id")
+customer = order.belongs_to("Customer", "customer_id")
+
+# Eager loading with include:
+users = User.all(include: ["orders", "profile"])
+```
+
+### DB Query Caching
+
+Enable query caching for up to 4x speedup on read-heavy workloads:
+
+```bash
+# .env
+TINA4_DB_CACHE=true
+```
+
+### Frond Pre-Compilation
+
+Templates are pre-compiled for 2.8x faster rendering.
+
+### Gallery
+
+7 interactive examples with **Try It** deploy.
+
 ## Environment
 
 ```bash
@@ -517,8 +604,9 @@ SECRET=your-jwt-secret
 DATABASE_URL=sqlite://data/app.db
 DATABASE_USERNAME=
 DATABASE_PASSWORD=
-TINA4_DEBUG_LEVEL=DEBUG              # DEBUG, INFO, WARNING, ERROR, ALL
-TINA4_LANGUAGE=en                    # en, fr, af, zh, ja, es
+TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
+TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
+TINA4_LOCALE=en                    # en, fr, af, zh, ja, es
 TINA4_SESSION_HANDLER=SessionFileHandler
 SWAGGER_TITLE=My API
 ```

data/lib/tina4/auth.rb

@@ -12,27 +12,130 @@ module Tina4
       def setup(root_dir = Dir.pwd)
         @keys_dir = File.join(root_dir, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)
-        ensure_keys
+        ensure_keys unless use_hmac?
       end
 
-      def create_token(payload, expires_in: 3600)
-        ensure_keys
+      # ── HS256 helpers (stdlib only, no gem) ──────────────────────
+
+      # Returns true when SECRET env var is set and no RSA keys exist in .keys/
+      def use_hmac?
+        secret = ENV["SECRET"]
+        return false if secret.nil? || secret.empty?
+
+        # If RSA keys already exist on disk, prefer RS256 for backward compat
+        @keys_dir ||= File.join(Dir.pwd, KEYS_DIR)
+        !(File.exist?(File.join(@keys_dir, "private.pem")) &&
+          File.exist?(File.join(@keys_dir, "public.pem")))
+      end
+
+      def hmac_secret
+        ENV["SECRET"]
+      end
+
+      # Base64url-encode without padding (JWT spec)
+      def base64url_encode(data)
+        Base64.urlsafe_encode64(data, padding: false)
+      end
+
+      # Base64url-decode (handles missing padding)
+      def base64url_decode(str)
+        # Add back padding
+        remainder = str.length % 4
+        str += "=" * ((4 - remainder) % 4) if remainder != 0
+        Base64.urlsafe_decode64(str)
+      end
+
+      # Build a JWT using HS256 with Ruby's OpenSSL::HMAC (no gem needed)
+      def hmac_encode(claims, secret)
+        header = { "alg" => "HS256", "typ" => "JWT" }
+        segments = [
+          base64url_encode(JSON.generate(header)),
+          base64url_encode(JSON.generate(claims))
+        ]
+        signing_input = segments.join(".")
+        signature = OpenSSL::HMAC.digest("SHA256", secret, signing_input)
+        segments << base64url_encode(signature)
+        segments.join(".")
+      end
+
+      # Decode and verify a JWT signed with HS256. Returns the payload hash or nil.
+      def hmac_decode(token, secret)
+        parts = token.split(".")
+        return nil unless parts.length == 3
+
+        header_json = base64url_decode(parts[0])
+        header = JSON.parse(header_json)
+        return nil unless header["alg"] == "HS256"
+
+        # Verify signature
+        signing_input = "#{parts[0]}.#{parts[1]}"
+        expected_sig = OpenSSL::HMAC.digest("SHA256", secret, signing_input)
+        actual_sig = base64url_decode(parts[2])
+
+        # Constant-time comparison to prevent timing attacks
+        return nil unless OpenSSL.fixed_length_secure_compare(expected_sig, actual_sig)
+
+        payload = JSON.parse(base64url_decode(parts[1]))
+
+        # Check expiry
+        now = Time.now.to_i
+        return nil if payload["exp"] && now >= payload["exp"]
+        return nil if payload["nbf"] && now < payload["nbf"]
+
+        payload
+      rescue ArgumentError, JSON::ParserError, OpenSSL::HMACError
+        nil
+      end
+
+      # ── Token API (auto-selects HS256 or RS256) ─────────────────
+
+      def get_token(payload, expires_in: 3600)
         now = Time.now.to_i
         claims = payload.merge(
           "iat" => now,
           "exp" => now + expires_in,
           "nbf" => now
         )
-        require "jwt"
-        JWT.encode(claims, private_key, "RS256")
+
+        if use_hmac?
+          hmac_encode(claims, hmac_secret)
+        else
+          ensure_keys
+          require "jwt"
+          JWT.encode(claims, private_key, "RS256")
+        end
       end
 
 
-      def validate_token(token)
-        ensure_keys
-        require "jwt"
-        decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
-        { valid: true, payload: decoded[0] }
+      def valid_token(token)
+        if use_hmac?
+          hmac_decode(token, hmac_secret)
+        else
+          ensure_keys
+          require "jwt"
+          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
+          decoded[0]
+        end
+      rescue JWT::ExpiredSignature
+        nil
+      rescue JWT::DecodeError
+        nil
+      end
+
+      def valid_token_detail(token)
+        if use_hmac?
+          payload = hmac_decode(token, hmac_secret)
+          if payload
+            { valid: true, payload: payload }
+          else
+            { valid: false, error: "Invalid or expired token" }
+          end
+        else
+          ensure_keys
+          require "jwt"
+          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
+          { valid: true, payload: decoded[0] }
+        end
       rescue JWT::ExpiredSignature
         { valid: false, error: "Token expired" }
       rescue JWT::DecodeError => e
@@ -53,34 +156,36 @@ module Tina4
 
 
       def get_payload(token)
-        require "jwt"
-        decoded = JWT.decode(token, nil, false)
-        decoded[0]
-      rescue JWT::DecodeError
+        parts = token.split(".")
+        return nil unless parts.length == 3
+
+        payload_json = base64url_decode(parts[1])
+        JSON.parse(payload_json)
+      rescue ArgumentError, JSON::ParserError
         nil
       end
 
       def refresh_token(token, expires_in: 3600)
-        result = validate_token(token)
-        return nil unless result[:valid]
+        payload = valid_token(token)
+        return nil unless payload
 
-        payload = result[:payload].reject { |k, _| %w[iat exp nbf].include?(k) }
-        create_token(payload, expires_in: expires_in)
+        payload = payload.reject { |k, _| %w[iat exp nbf].include?(k) }
+        get_token(payload, expires_in: expires_in)
       end
 
       def authenticate_request(headers)
         auth_header = headers["HTTP_AUTHORIZATION"] || headers["Authorization"] || ""
-        return { valid: false, error: "No authorization header" } unless auth_header =~ /\ABearer\s+(.+)\z/i
+        return nil unless auth_header =~ /\ABearer\s+(.+)\z/i
 
         token = Regexp.last_match(1)
 
         # API_KEY bypass — matches tina4_python behavior
         api_key = ENV["TINA4_API_KEY"] || ENV["API_KEY"]
         if api_key && !api_key.empty? && token == api_key
-          return { valid: true, payload: { "api_key" => true } }
+          return { "api_key" => true }
         end
 
-        validate_token(token)
+        valid_token(token)
       end
 
       def validate_api_key(provided, expected: nil)
@@ -107,15 +212,15 @@ module Tina4
           token = Regexp.last_match(1)
 
           # API_KEY bypass — matches tina4_python behavior
-          api_key = ENV["API_KEY"]
+          api_key = ENV["TINA4_API_KEY"] || ENV["API_KEY"]
           if api_key && !api_key.empty? && token == api_key
             env["tina4.auth"] = { "api_key" => true }
             return true
           end
 
-          result = validate_token(token)
-          if result[:valid]
-            env["tina4.auth"] = result[:payload]
+          payload = valid_token(token)
+          if payload
+            env["tina4.auth"] = payload
             true
           else
             false
@@ -129,6 +234,10 @@ module Tina4
         @default_secure_auth ||= bearer_auth
       end
 
+      # Legacy aliases
+      alias_method :create_token, :get_token
+      alias_method :validate_token, :valid_token_detail
+
       def private_key
         @private_key ||= OpenSSL::PKey::RSA.new(File.read(private_key_path))
       end
@@ -140,6 +249,8 @@ module Tina4
       private
 
       def ensure_keys
+        return if use_hmac?
+
         @keys_dir ||= File.join(Dir.pwd, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)
         unless File.exist?(private_key_path) && File.exist?(public_key_path)
@@ -169,8 +280,7 @@ module Tina4
         return true if auth_header.empty?
 
         if auth_header =~ /\ABearer\s+(.+)\z/i
-          result = validate_token(Regexp.last_match(1))
-          result[:valid]
+          !valid_token(Regexp.last_match(1)).nil?
         else
           false
         end

data/lib/tina4/auto_crud.rb

@@ -21,10 +21,36 @@ module Tina4
         end
       end
 
+      # Build a sample request body from ORM field definitions.
+      def build_example(model_class)
+        example = {}
+        return example unless model_class.respond_to?(:field_definitions)
+
+        model_class.field_definitions.each do |name, opts|
+          next if opts[:primary_key] && opts[:auto_increment]
+
+          case opts[:type]
+          when :integer
+            example[name.to_s] = 0
+          when :numeric, :float, :decimal
+            example[name.to_s] = 0.0
+          when :boolean
+            example[name.to_s] = true
+          when :datetime
+            example[name.to_s] = "2024-01-01T00:00:00"
+          else
+            example[name.to_s] = "string"
+          end
+        end
+        example
+      end
+
       # Generate REST endpoints for a single model class
       def generate_routes_for(model_class, prefix: "/api")
         table = model_class.table_name
         pk = model_class.primary_key_field || :id
+        pretty_name = table.to_s.split("_").map(&:capitalize).join(" ")
+        example_body = build_example(model_class)
 
         # GET /api/{table} -- list all with pagination, filtering, sorting
         Tina4::Router.add_route("GET", "#{prefix}/#{table}", proc { |req, res|
@@ -63,7 +89,7 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
-        })
+        }, swagger_meta: { summary: "List all #{pretty_name}", tags: [table.to_s] })
 
         # GET /api/{table}/{id} -- get single record
         Tina4::Router.add_route("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
@@ -78,7 +104,7 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
-        })
+        }, swagger_meta: { summary: "Get #{pretty_name} by ID", tags: [table.to_s] })
 
         # POST /api/{table} -- create record
         Tina4::Router.add_route("POST", "#{prefix}/#{table}", proc { |req, res|
@@ -93,6 +119,19 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
+        }, swagger_meta: {
+          summary: "Create #{pretty_name}",
+          tags: [table.to_s],
+          request_body: {
+            "description" => "#{pretty_name} data",
+            "required" => true,
+            "content" => {
+              "application/json" => {
+                "schema" => { "type" => "object" },
+                "example" => example_body
+              }
+            }
+          }
         })
 
         # PUT /api/{table}/{id} -- update record
@@ -118,6 +157,19 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
+        }, swagger_meta: {
+          summary: "Update #{pretty_name}",
+          tags: [table.to_s],
+          request_body: {
+            "description" => "#{pretty_name} data",
+            "required" => true,
+            "content" => {
+              "application/json" => {
+                "schema" => { "type" => "object" },
+                "example" => example_body
+              }
+            }
+          }
         })
 
         # DELETE /api/{table}/{id} -- delete record
@@ -137,7 +189,7 @@ module Tina4
           rescue => e
             res.json({ error: e.message }, status: 500)
           end
-        })
+        }, swagger_meta: { summary: "Delete #{pretty_name}", tags: [table.to_s] })
       end
 
       def clear!