tarsier 0.1.0

data/README.md

@@ -0,0 +1,984 @@
+# Tarsier
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tarsier-rb/tarsier/main/assets/logo.png" alt="Tarsier Logo" width="200">
+</p>
+
+<p align="center">
+  A modern, high-performance Ruby web framework designed for speed, simplicity, and developer productivity.
+</p>
+
+<p align="center">
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.3-red.svg" alt="Ruby"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
+
+---
+
+Tarsier delivers sub-millisecond routing through a compiled radix tree architecture while maintaining an intuitive API that feels natural to Ruby developers.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Command Line Interface](#command-line-interface)
+- [Routing](#routing)
+- [Controllers](#controllers)
+- [Request and Response](#request-and-response)
+- [Middleware](#middleware)
+- [Database](#database)
+- [WebSocket and SSE](#websocket-and-sse)
+- [Models](#models)
+- [Configuration](#configuration)
+- [Testing](#testing)
+- [Benchmarks](#benchmarks)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **High Performance**: Compiled radix tree router achieving 700,000+ routes per second
+- **Zero Runtime Dependencies**: Core framework operates without external dependencies
+- **Multi-Database Support**: Built-in support for SQLite, PostgreSQL, and MySQL
+- **Modern Ruby**: Built for Ruby 3.3+ with YJIT and Fiber scheduler support
+- **Async Native**: First-class support for Fiber-based concurrency patterns
+- **Type Safety Ready**: Complete RBS type signatures for static analysis
+- **Developer Experience**: Intuitive APIs, detailed error messages, minimal boilerplate
+- **Production Ready**: Built-in middleware for CORS, CSRF, rate limiting, and compression
+
+---
+
+## Requirements
+
+- Ruby 3.3 or higher
+- Rack 3.0+ (for Rack compatibility layer)
+
+---
+
+## Installation
+
+Add Tarsier to your application's Gemfile:
+
+```ruby
+gem 'tarsier'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install globally for CLI access:
+
+```bash
+gem install tarsier
+```
+
+---
+
+## Quick Start
+
+Create a new application:
+
+```bash
+tarsier new my_app
+cd my_app
+bin/server
+```
+
+Or create a minimal application manually:
+
+```ruby
+# app.rb
+require 'tarsier'
+
+# Flask-style minimal syntax
+app = Tarsier.app do
+  get('/') { { message: 'Hello, World!' } }
+  
+  get('/users/:id') do |req|
+    { user_id: req.params[:id] }
+  end
+  
+  post('/users') do |req, res|
+    res.status = 201
+    { created: true, name: req.params[:name] }
+  end
+end
+
+run app
+```
+
+Start the server:
+
+```bash
+rackup app.rb
+```
+
+Visit `http://localhost:9292` to see your application running.
+
+---
+
+## Command Line Interface
+
+Tarsier provides a comprehensive CLI for project scaffolding and development workflows.
+
+### Creating Applications
+
+```bash
+# Standard application with views
+tarsier new my_app
+
+# API-only application (no view layer)
+tarsier new my_api --api
+
+# Minimal application structure
+tarsier new my_app --minimal
+
+# Skip optional setup steps
+tarsier new my_app --skip-git --skip-bundle
+```
+
+### Code Generation
+
+```bash
+# Generate a controller with actions
+tarsier generate controller users index show create update destroy
+
+# Generate a model with attributes
+tarsier generate model user name:string email:string created_at:datetime
+
+# Generate a complete resource (model + controller + routes)
+tarsier generate resource post title:string body:text published:boolean
+
+# Generate custom middleware
+tarsier generate middleware authentication
+
+# Generate a database migration
+tarsier generate migration create_users name:string email:string
+tarsier generate migration add_role_to_users
+```
+
+Shorthand aliases are available:
+
+```bash
+tarsier g controller users index show
+tarsier g model user name:string
+```
+
+### Development Server
+
+```bash
+# Start with defaults (port 7827)
+tarsier server
+
+# Custom port
+tarsier server -p 4000
+
+# Specify environment
+tarsier server -e production
+
+# Bind to specific host
+tarsier server -b 127.0.0.1
+```
+
+### Interactive Console
+
+```bash
+# Development console
+tarsier console
+
+# Production console
+tarsier console -e production
+```
+
+### Route Inspection
+
+```bash
+# Display all routes
+tarsier routes
+
+# Filter routes by pattern
+tarsier routes -g users
+
+# Output as JSON
+tarsier routes --json
+```
+
+### Version Information
+
+```bash
+tarsier version
+```
+
+---
+
+## Routing
+
+Tarsier uses a compiled radix tree router optimized for high-throughput applications.
+
+### Basic Routes
+
+```ruby
+Tarsier.routes do
+  get '/users', to: 'users#index'
+  post '/users', to: 'users#create'
+  get '/users/:id', to: 'users#show'
+  put '/users/:id', to: 'users#update'
+  delete '/users/:id', to: 'users#destroy'
+end
+```
+
+### Route Parameters
+
+```ruby
+Tarsier.routes do
+  # Required parameters
+  get '/users/:id', to: 'users#show'
+  
+  # Multiple parameters
+  get '/posts/:post_id/comments/:id', to: 'comments#show'
+  
+  # Wildcard parameters
+  get '/files/*path', to: 'files#show'
+  
+  # Parameter constraints
+  get '/posts/:id', to: 'posts#show', constraints: { id: /\d+/ }
+end
+```
+
+### RESTful Resources
+
+```ruby
+Tarsier.routes do
+  # Full resource routes
+  resources :posts
+  
+  # Nested resources
+  resources :posts do
+    resources :comments
+  end
+  
+  # Limit actions
+  resources :posts, only: [:index, :show]
+  resources :posts, except: [:destroy]
+  
+  # Singular resource
+  resource :profile
+end
+```
+
+### Namespaces and Scopes
+
+```ruby
+Tarsier.routes do
+  # Namespace (affects path and controller lookup)
+  namespace :admin do
+    resources :users
+  end
+  # Routes: /admin/users -> Admin::UsersController
+  
+  # Scope (affects path only)
+  scope path: 'api/v1' do
+    resources :users
+  end
+  # Routes: /api/v1/users -> UsersController
+end
+```
+
+### Named Routes
+
+```ruby
+Tarsier.routes do
+  get '/login', to: 'sessions#new', as: :login
+  get '/logout', to: 'sessions#destroy', as: :logout
+  
+  root to: 'home#index'
+end
+
+# Generate paths
+app.path_for(:login)  # => "/login"
+app.path_for(:user, id: 123)  # => "/users/123"
+```
+
+---
+
+## Controllers
+
+Controllers handle request processing with support for filters, parameter validation, and multiple response formats.
+
+### Basic Controller
+
+```ruby
+class UsersController < Tarsier::Controller
+  def index
+    users = User.all
+    render json: users
+  end
+  
+  def show
+    user = User.find(params[:id])
+    render json: user
+  end
+  
+  def create
+    user = User.create(params.permit(:name, :email))
+    render json: user, status: 201
+  end
+end
+```
+
+### Filters
+
+```ruby
+class UsersController < Tarsier::Controller
+  before_action :authenticate
+  before_action :load_user, only: [:show, :update, :destroy]
+  after_action :log_request
+  
+  def show
+    render json: @user
+  end
+  
+  private
+  
+  def authenticate
+    head 401 unless current_user
+  end
+  
+  def load_user
+    @user = User.find(params[:id])
+  end
+  
+  def log_request
+    Logger.info("Processed #{action_name}")
+  end
+end
+```
+
+### Parameter Validation
+
+```ruby
+class UsersController < Tarsier::Controller
+  params do
+    requires :name, type: String, min: 2, max: 100
+    requires :email, type: String, format: URI::MailTo::EMAIL_REGEXP
+    optional :role, type: String, in: %w[user admin], default: 'user'
+    optional :age, type: Integer, greater_than: 0
+  end
+  
+  def create
+    # validated_params contains coerced and validated parameters
+    user = User.create(validated_params)
+    render json: user, status: 201
+  end
+end
+```
+
+### Exception Handling
+
+```ruby
+class ApplicationController < Tarsier::Controller
+  rescue_from ActiveRecord::RecordNotFound, with: :not_found
+  rescue_from ValidationError, with: :unprocessable
+  
+  private
+  
+  def not_found(exception)
+    render json: { error: 'Resource not found' }, status: 404
+  end
+  
+  def unprocessable(exception)
+    render json: { errors: exception.errors }, status: 422
+  end
+end
+```
+
+### Response Streaming
+
+```ruby
+class ReportsController < Tarsier::Controller
+  def export
+    response.stream do |out|
+      User.find_each do |user|
+        out << user.to_csv
+        out << "\n"
+      end
+    end
+  end
+end
+```
+
+---
+
+## Request and Response
+
+### Request Object
+
+The request object provides immutable access to request data with lazy parsing for optimal performance.
+
+```ruby
+# HTTP method and path
+request.method        # => :GET
+request.path          # => '/users/123'
+request.url           # => 'https://example.com/users/123'
+
+# Parameters
+request.params        # Combined route, query, and body params
+request.query_params  # Query string parameters only
+request.body_params   # Parsed body parameters
+request.route_params  # Parameters from route matching
+
+# Headers and metadata
+request.headers       # All HTTP headers
+request.header('Authorization')  # Specific header
+request.content_type  # Content-Type header
+request.accept        # Accept header
+request.user_agent    # User-Agent header
+
+# Client information
+request.ip            # Client IP address
+request.cookies       # Parsed cookies
+
+# Request type checks
+request.get?          # => true/false
+request.post?         # => true/false
+request.json?         # Content-Type includes application/json
+request.xhr?          # X-Requested-With: XMLHttpRequest
+request.secure?       # HTTPS request
+```
+
+### Response Object
+
+```ruby
+# Set status and headers
+response.status = 201
+response.set_header('X-Custom-Header', 'value')
+response.content_type = 'application/json'
+
+# Response helpers
+response.json({ data: users })
+response.html('<h1>Hello</h1>')
+response.text('Plain text response')
+response.redirect('/new-location', status: 302)
+
+# Cookies
+response.set_cookie('session', token, 
+  http_only: true, 
+  secure: true,
+  same_site: 'Strict',
+  max_age: 86400
+)
+response.delete_cookie('session')
+
+# Streaming
+response.stream do |out|
+  out << 'chunk 1'
+  out << 'chunk 2'
+end
+```
+
+---
+
+## Middleware
+
+Tarsier includes production-ready middleware and supports custom middleware development.
+
+### Built-in Middleware
+
+```ruby
+app = Tarsier.application do
+  # Request logging
+  use Tarsier::Middleware::Logger
+  
+  # CORS handling
+  use Tarsier::Middleware::CORS,
+    origins: ['https://example.com'],
+    methods: %w[GET POST PUT DELETE],
+    credentials: true
+  
+  # CSRF protection
+  use Tarsier::Middleware::CSRF,
+    skip: ['/api/webhooks']
+  
+  # Rate limiting
+  use Tarsier::Middleware::RateLimit,
+    limit: 100,
+    window: 60
+  
+  # Response compression
+  use Tarsier::Middleware::Compression,
+    min_size: 1024
+  
+  # Static file serving
+  use Tarsier::Middleware::Static,
+    root: 'public',
+    cache_control: 'public, max-age=31536000'
+end
+```
+
+### Custom Middleware
+
+```ruby
+class TimingMiddleware < Tarsier::Middleware::Base
+  def call(request, response)
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    
+    @app.call(request, response)
+    
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+    response.set_header('X-Response-Time', "#{(duration * 1000).round(2)}ms")
+    
+    response
+  end
+end
+```
+
+### Middleware Stack Management
+
+```ruby
+app.middleware_stack.insert_before(Tarsier::Middleware::Logger, CustomMiddleware)
+app.middleware_stack.insert_after(Tarsier::Middleware::CORS, AnotherMiddleware)
+app.middleware_stack.delete(Tarsier::Middleware::Static)
+app.middleware_stack.swap(OldMiddleware, NewMiddleware)
+```
+
+---
+
+## Database
+
+Tarsier includes a lightweight database layer with support for SQLite, PostgreSQL, and MySQL.
+
+### Connecting to a Database
+
+```ruby
+# SQLite
+Tarsier.db :sqlite, 'db/app.db'
+Tarsier.db :sqlite, ':memory:'  # In-memory database
+
+# PostgreSQL
+Tarsier.db :postgres, 'postgres://localhost/myapp'
+Tarsier.db :postgres, host: 'localhost', database: 'myapp', username: 'user'
+
+# MySQL
+Tarsier.db :mysql, host: 'localhost', database: 'myapp', username: 'root'
+```
+
+### Raw Queries
+
+```ruby
+# Execute queries
+Tarsier.database.execute('SELECT * FROM users WHERE active = ?', true)
+
+# Get single result
+user = Tarsier.database.get('SELECT * FROM users WHERE id = ?', 1)
+
+# Insert and get ID
+id = Tarsier.database.insert(:users, name: 'John', email: 'john@example.com')
+
+# Update records
+Tarsier.database.update(:users, { active: false }, id: 1)
+
+# Delete records
+Tarsier.database.delete(:users, id: 1)
+```
+
+### Transactions
+
+```ruby
+Tarsier.database.transaction do
+  Tarsier.database.insert(:accounts, user_id: 1, balance: 100)
+  Tarsier.database.update(:users, { has_account: true }, id: 1)
+end
+# Automatically rolls back on error
+```
+
+### Migrations
+
+Generate a migration:
+
+```bash
+tarsier generate migration create_users name:string email:string
+```
+
+Migration file:
+
+```ruby
+class CreateUsers < Tarsier::Database::Migration
+  def up
+    create_table :users do |t|
+      t.string :name
+      t.string :email, null: false
+      t.boolean :active, default: true
+      t.timestamps
+    end
+    
+    add_index :users, :email, unique: true
+  end
+
+  def down
+    drop_table :users
+  end
+end
+```
+
+Run migrations:
+
+```ruby
+Tarsier.database.migrate        # Run pending migrations
+Tarsier.database.migrate(:down) # Rollback migrations
+```
+
+### Supported Column Types
+
+| Type | SQL Type |
+|------|----------|
+| string | VARCHAR(255) |
+| text | TEXT |
+| integer | INTEGER |
+| bigint | BIGINT |
+| float | REAL |
+| decimal | DECIMAL |
+| boolean | BOOLEAN |
+| date | DATE |
+| datetime | DATETIME |
+| timestamp | TIMESTAMP |
+| time | TIME |
+| binary | BLOB |
+| json | JSON |
+
+---
+
+## WebSocket and SSE
+
+### WebSocket Support
+
+```ruby
+class ChatSocket < Tarsier::WebSocket
+  on :connect do
+    subscribe "room:#{params[:room_id]}"
+    broadcast "room:#{params[:room_id]}", { type: 'join', user: current_user }
+  end
+  
+  on :message do |data|
+    broadcast "room:#{params[:room_id]}", {
+      type: 'message',
+      user: current_user,
+      content: data
+    }
+  end
+  
+  on :close do
+    broadcast "room:#{params[:room_id]}", { type: 'leave', user: current_user }
+  end
+end
+```
+
+### Server-Sent Events
+
+```ruby
+class EventsController < Tarsier::Controller
+  def stream
+    sse = Tarsier::SSE.new(request, response)
+    sse.start
+    
+    loop do
+      sse.send({ time: Time.now.iso8601 }, event: 'tick', id: SecureRandom.uuid)
+      sleep 1
+    end
+  rescue IOError
+    sse.close
+  end
+end
+```
+
+---
+
+## Models
+
+Tarsier includes a lightweight ORM with Active Record-style patterns. Models integrate seamlessly with the database layer.
+
+### Model Definition
+
+```ruby
+class User < Tarsier::Model
+  table :users
+  
+  attribute :name, :string
+  attribute :email, :string
+  attribute :active, :boolean, default: true
+  attribute :created_at, :datetime
+  
+  validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+  validates :email, presence: true, format: /@/
+  
+  has_many :posts
+  has_one :profile
+  belongs_to :organization
+end
+```
+
+### CRUD Operations
+
+```ruby
+# Create
+user = User.create(name: 'John', email: 'john@example.com')
+user = User.new(name: 'Jane')
+user.save
+
+# Read
+User.find(1)
+User.find!(1)  # Raises RecordNotFoundError if not found
+User.find_by(email: 'john@example.com')
+User.all
+
+# Update
+user.update(name: 'John Doe')
+user.name = 'Johnny'
+user.save
+
+# Delete
+user.destroy
+```
+
+### Query Interface
+
+```ruby
+# Chainable query methods
+User.where(active: true)
+    .where_not(role: 'guest')
+    .order(created_at: :desc)
+    .limit(10)
+    .offset(20)
+
+# Range queries
+User.where(age: 18..65)
+
+# IN queries
+User.where(status: ['active', 'pending'])
+
+# Select specific columns
+User.select(:id, :name, :email)
+
+# Pluck values
+User.where(active: true).pluck(:email)
+User.pluck(:id)  # Same as User.ids
+
+# Joins
+User.joins(:posts, on: 'users.id = posts.user_id')
+
+# Eager loading
+User.includes(:posts, :profile)
+
+# Aggregations
+User.count
+User.where(active: true).count
+User.exists?(email: 'test@example.com')
+
+# Batch operations
+User.where(inactive: true).update_all(archived: true)
+User.where(archived: true).delete_all
+
+# Find or create
+User.where(email: 'new@example.com').find_or_create_by({ email: 'new@example.com' })
+User.where(email: 'new@example.com').find_or_initialize_by({ email: 'new@example.com' })
+```
+
+### Validations
+
+```ruby
+class Post < Tarsier::Model
+  attribute :title, :string
+  attribute :body, :text
+  attribute :status, :string
+  
+  validates :title, presence: true, length: { minimum: 5, maximum: 200 }
+  validates :status, inclusion: { in: %w[draft published archived] }
+end
+
+post = Post.new(title: 'Hi')
+post.valid?  # => false
+post.errors  # => { title: ["is too short (minimum 5)"] }
+```
+
+### Associations
+
+```ruby
+class Post < Tarsier::Model
+  belongs_to :user
+  has_many :comments
+end
+
+class Comment < Tarsier::Model
+  belongs_to :post
+  belongs_to :user
+end
+
+# Access associations
+post = Post.find(1)
+post.user      # => User instance
+post.comments  # => Array of Comment instances
+```
+
+---
+
+## Configuration
+
+```ruby
+Tarsier.application do
+  configure do
+    # Security
+    self.secret_key = ENV.fetch('SECRET_KEY')
+    self.force_ssl = true
+    
+    # Server
+    self.host = '0.0.0.0'
+    self.port = 3000
+    
+    # Application
+    self.log_level = :info
+    self.default_format = :json
+    self.static_files = true
+  end
+end
+```
+
+### Environment-Specific Configuration
+
+```ruby
+Tarsier.application do
+  configure do
+    case Tarsier.env
+    when 'production'
+      self.force_ssl = true
+      self.log_level = :warn
+    when 'development'
+      self.log_level = :debug
+    when 'test'
+      self.log_level = :error
+    end
+  end
+end
+```
+
+---
+
+## Testing
+
+Tarsier applications are designed for testability with RSpec integration.
+
+### Setup
+
+```ruby
+# spec/spec_helper.rb
+require 'tarsier'
+require 'rack/test'
+
+RSpec.configure do |config|
+  config.include Rack::Test::Methods
+  
+  def app
+    Tarsier.app
+  end
+end
+```
+
+### Controller Tests
+
+```ruby
+RSpec.describe UsersController do
+  describe 'GET /users' do
+    it 'returns users list' do
+      get '/users'
+      
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to have_key('users')
+    end
+  end
+  
+  describe 'POST /users' do
+    it 'creates a user' do
+      post '/users', { name: 'John', email: 'john@example.com' }.to_json,
+           'CONTENT_TYPE' => 'application/json'
+      
+      expect(last_response.status).to eq(201)
+    end
+  end
+end
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+bundle exec rspec spec/controllers
+bundle exec rspec --format documentation
+```
+
+---
+
+## Benchmarks
+
+Run the included benchmark suite:
+
+```bash
+bundle exec rake benchmark
+bundle exec rake benchmark:router
+bundle exec rake benchmark:request
+```
+
+### Performance Characteristics
+
+| Operation | Throughput |
+|-----------|------------|
+| Static route matching | 700,000+ req/sec |
+| Parameterized routes | 250,000+ req/sec |
+| Nested resources | 115,000+ req/sec |
+| Request parsing | 700,000+ req/sec |
+
+Benchmarks performed on Ruby 3.3 with YJIT enabled.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/improvement`)
+3. Commit your changes (`git commit -am 'Add new feature'`)
+4. Push to the branch (`git push origin feature/improvement`)
+5. Create a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/tarsier-rb/tarsier.git
+cd tarsier
+bundle install
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop
+bundle exec yard doc
+```
+
+---
+
+## License
+
+Tarsier is released under the [MIT License](LICENSE.txt).
+
+---
+
+## Acknowledgments
+
+Tarsier draws inspiration from the Ruby web framework ecosystem, particularly Rails, Sinatra, and Roda, while pursuing its own vision of performance and simplicity.