tarsier 0.1.0

data/lib/tarsier/database.rb

@@ -0,0 +1,588 @@
+# frozen_string_literal: true
+
+module Tarsier
+  # Database abstraction layer with support for SQLite, PostgreSQL, and MySQL
+  #
+  # Provides a unified interface for database operations across different
+  # adapters. Connections are lazy-loaded and pooled for performance.
+  #
+  # @example Connect to SQLite
+  #   Tarsier.db :sqlite, 'app.db'
+  #
+  # @example Connect to PostgreSQL
+  #   Tarsier.db :postgres, 'postgres://localhost/myapp'
+  #
+  # @example Raw queries
+  #   Tarsier.database.execute('SELECT * FROM users WHERE id = ?', 1)
+  #
+  # @since 0.1.0
+  module Database
+    # Supported database adapters
+    ADAPTERS = {
+      sqlite: "SQLite",
+      sqlite3: "SQLite",
+      postgres: "PostgreSQL",
+      postgresql: "PostgreSQL",
+      pg: "PostgreSQL",
+      mysql: "MySQL",
+      mysql2: "MySQL"
+    }.freeze
+
+    class << self
+      # @return [Connection, nil] the current database connection
+      attr_reader :connection
+
+      # Establish a database connection
+      #
+      # @param adapter [Symbol] database adapter
+      # @param connection_string [String, nil] connection URL or path
+      # @param options [Hash] connection options
+      # @return [Connection]
+      # @raise [DatabaseError] if adapter is unsupported
+      #
+      # @example
+      #   Database.connect(:sqlite, 'db/app.db')
+      #   Database.connect(:postgres, host: 'localhost', database: 'myapp')
+      def connect(adapter, connection_string = nil, **options)
+        adapter_name = ADAPTERS[adapter.to_sym]
+        raise DatabaseError, "Unsupported adapter: #{adapter}" unless adapter_name
+
+        @connection = Connection.new(adapter, connection_string, **options)
+      end
+
+      # Disconnect from database
+      #
+      # @return [void]
+      def disconnect
+        @connection&.close
+        @connection = nil
+      end
+
+      # Check if connected
+      #
+      # @return [Boolean]
+      def connected?
+        @connection&.connected? || false
+      end
+    end
+
+    # Database connection wrapper
+    #
+    # Provides a unified interface for executing queries across different
+    # database adapters. Handles connection pooling and query execution.
+    #
+    # @since 0.1.0
+    class Connection
+      # @return [Symbol] the database adapter
+      attr_reader :adapter
+
+      # @return [Object] the underlying database connection
+      attr_reader :raw_connection
+
+      # Create a new database connection
+      #
+      # @param adapter [Symbol] database adapter
+      # @param connection_string [String, nil] connection URL or path
+      # @param options [Hash] connection options
+      def initialize(adapter, connection_string = nil, **options)
+        @adapter = normalize_adapter(adapter)
+        @options = parse_connection(connection_string, options)
+        @raw_connection = nil
+        @connected = false
+      end
+
+      # Execute a SQL query
+      #
+      # @param sql [String] SQL query
+      # @param params [Array] query parameters
+      # @return [Array<Hash>] query results
+      #
+      # @example
+      #   connection.execute('SELECT * FROM users WHERE id = ?', 1)
+      def execute(sql, *params)
+        ensure_connected
+        execute_query(sql, params)
+      end
+
+      # Execute a query and return first result
+      #
+      # @param sql [String] SQL query
+      # @param params [Array] query parameters
+      # @return [Hash, nil]
+      def get(sql, *params)
+        execute(sql, *params).first
+      end
+
+      # Insert a record and return the ID
+      #
+      # @param table [String, Symbol] table name
+      # @param attributes [Hash] column values
+      # @return [Integer] inserted row ID
+      def insert(table, attributes)
+        columns = attributes.keys.join(", ")
+        placeholders = (["?"] * attributes.size).join(", ")
+        sql = "INSERT INTO #{table} (#{columns}) VALUES (#{placeholders})"
+
+        execute(sql, *attributes.values)
+        last_insert_id
+      end
+
+      # Update records
+      #
+      # @param table [String, Symbol] table name
+      # @param attributes [Hash] column values to update
+      # @param conditions [Hash] WHERE conditions
+      # @return [Integer] number of affected rows
+      def update(table, attributes, conditions = {})
+        set_clause = attributes.keys.map { |k| "#{k} = ?" }.join(", ")
+        where_clause, where_values = build_where(conditions)
+
+        sql = "UPDATE #{table} SET #{set_clause}"
+        sql += " WHERE #{where_clause}" unless where_clause.empty?
+
+        execute(sql, *attributes.values, *where_values)
+        affected_rows
+      end
+
+      # Delete records
+      #
+      # @param table [String, Symbol] table name
+      # @param conditions [Hash] WHERE conditions
+      # @return [Integer] number of affected rows
+      def delete(table, conditions = {})
+        where_clause, where_values = build_where(conditions)
+
+        sql = "DELETE FROM #{table}"
+        sql += " WHERE #{where_clause}" unless where_clause.empty?
+
+        execute(sql, *where_values)
+        affected_rows
+      end
+
+      # Check if connected
+      #
+      # @return [Boolean]
+      def connected?
+        @connected && !@raw_connection.nil?
+      end
+
+      # Close the connection
+      #
+      # @return [void]
+      def close
+        return unless @raw_connection
+
+        case @adapter
+        when :sqlite
+          @raw_connection.close
+        when :postgres
+          @raw_connection.close
+        when :mysql
+          @raw_connection.close
+        end
+
+        @raw_connection = nil
+        @connected = false
+      end
+
+      # Run migrations
+      #
+      # @param direction [Symbol] :up or :down
+      # @return [void]
+      def migrate(direction = :up)
+        migrations_path = File.join(Tarsier.root, "db", "migrations")
+        return unless File.directory?(migrations_path)
+
+        create_migrations_table
+
+        Dir.glob(File.join(migrations_path, "*.rb")).sort.each do |file|
+          version = File.basename(file).split("_").first
+          next if direction == :up && migrated?(version)
+          next if direction == :down && !migrated?(version)
+
+          require file
+          class_name = File.basename(file, ".rb").split("_")[1..].map(&:capitalize).join
+          migration = Object.const_get(class_name).new(self)
+
+          if direction == :up
+            migration.up
+            record_migration(version)
+          else
+            migration.down
+            remove_migration(version)
+          end
+        end
+      end
+
+      # Begin a transaction
+      #
+      # @yield block to execute within transaction
+      # @return [Object] block result
+      def transaction
+        execute("BEGIN")
+        result = yield
+        execute("COMMIT")
+        result
+      rescue StandardError => e
+        execute("ROLLBACK")
+        raise e
+      end
+
+      private
+
+      def normalize_adapter(adapter)
+        case adapter.to_sym
+        when :sqlite, :sqlite3 then :sqlite
+        when :postgres, :postgresql, :pg then :postgres
+        when :mysql, :mysql2 then :mysql
+        else adapter.to_sym
+        end
+      end
+
+      def parse_connection(connection_string, options)
+        return options unless connection_string
+
+        if connection_string.is_a?(String) && connection_string.include?("://")
+          parse_url(connection_string)
+        else
+          options.merge(database: connection_string)
+        end
+      end
+
+      def parse_url(url)
+        uri = URI.parse(url)
+        {
+          host: uri.host,
+          port: uri.port,
+          database: uri.path[1..],
+          username: uri.user,
+          password: uri.password
+        }.compact
+      end
+
+      def ensure_connected
+        return if connected?
+
+        @raw_connection = create_connection
+        @connected = true
+      end
+
+      def create_connection
+        case @adapter
+        when :sqlite
+          require "sqlite3"
+          SQLite3::Database.new(@options[:database] || ":memory:")
+        when :postgres
+          require "pg"
+          PG.connect(**pg_options)
+        when :mysql
+          require "mysql2"
+          Mysql2::Client.new(**mysql_options)
+        else
+          raise DatabaseError, "Unsupported adapter: #{@adapter}"
+        end
+      end
+
+      def pg_options
+        {
+          host: @options[:host] || "localhost",
+          port: @options[:port] || 5432,
+          dbname: @options[:database],
+          user: @options[:username],
+          password: @options[:password]
+        }.compact
+      end
+
+      def mysql_options
+        {
+          host: @options[:host] || "localhost",
+          port: @options[:port] || 3306,
+          database: @options[:database],
+          username: @options[:username],
+          password: @options[:password]
+        }.compact
+      end
+
+      def execute_query(sql, params)
+        case @adapter
+        when :sqlite
+          execute_sqlite(sql, params)
+        when :postgres
+          execute_postgres(sql, params)
+        when :mysql
+          execute_mysql(sql, params)
+        end
+      end
+
+      def execute_sqlite(sql, params)
+        @raw_connection.results_as_hash = true
+        stmt = @raw_connection.prepare(sql)
+        result = stmt.execute(*params)
+        result.to_a.map { |row| symbolize_keys(row) }
+      ensure
+        stmt&.close
+      end
+
+      def execute_postgres(sql, params)
+        # Convert ? placeholders to $1, $2, etc.
+        pg_sql = sql.gsub(/\?/).with_index(1) { |_, i| "$#{i}" }
+        result = @raw_connection.exec_params(pg_sql, params)
+        result.map { |row| symbolize_keys(row) }
+      end
+
+      def execute_mysql(sql, params)
+        stmt = @raw_connection.prepare(sql)
+        result = stmt.execute(*params)
+        result&.to_a&.map { |row| symbolize_keys(row) } || []
+      end
+
+      def symbolize_keys(hash)
+        hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+      end
+
+      def last_insert_id
+        case @adapter
+        when :sqlite
+          @raw_connection.last_insert_row_id
+        when :postgres
+          execute("SELECT lastval()").first&.values&.first
+        when :mysql
+          @raw_connection.last_id
+        end
+      end
+
+      def affected_rows
+        case @adapter
+        when :sqlite
+          @raw_connection.changes
+        when :postgres
+          @raw_connection.cmd_tuples
+        when :mysql
+          @raw_connection.affected_rows
+        end
+      end
+
+      def build_where(conditions)
+        return ["", []] if conditions.empty?
+
+        clauses = conditions.map { |k, _| "#{k} = ?" }
+        [clauses.join(" AND "), conditions.values]
+      end
+
+      def create_migrations_table
+        sql = <<~SQL
+          CREATE TABLE IF NOT EXISTS schema_migrations (
+            version VARCHAR(255) PRIMARY KEY
+          )
+        SQL
+        execute(sql)
+      end
+
+      def migrated?(version)
+        result = execute("SELECT version FROM schema_migrations WHERE version = ?", version)
+        result.any?
+      end
+
+      def record_migration(version)
+        execute("INSERT INTO schema_migrations (version) VALUES (?)", version)
+      end
+
+      def remove_migration(version)
+        execute("DELETE FROM schema_migrations WHERE version = ?", version)
+      end
+    end
+
+    # Base class for migrations
+    #
+    # @example
+    #   class CreateUsers < Tarsier::Database::Migration
+    #     def up
+    #       create_table :users do |t|
+    #         t.string :name
+    #         t.string :email
+    #         t.timestamps
+    #       end
+    #     end
+    #
+    #     def down
+    #       drop_table :users
+    #     end
+    #   end
+    #
+    # @since 0.1.0
+    class Migration
+      # @param connection [Connection] database connection
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Override in subclass
+      def up
+        raise NotImplementedError
+      end
+
+      # Override in subclass
+      def down
+        raise NotImplementedError
+      end
+
+      # Create a table
+      #
+      # @param name [Symbol, String] table name
+      # @yield [TableDefinition] table definition
+      def create_table(name, &block)
+        definition = TableDefinition.new(name)
+        definition.instance_eval(&block) if block_given?
+        @connection.execute(definition.to_sql)
+      end
+
+      # Drop a table
+      #
+      # @param name [Symbol, String] table name
+      def drop_table(name)
+        @connection.execute("DROP TABLE IF EXISTS #{name}")
+      end
+
+      # Add a column
+      #
+      # @param table [Symbol, String] table name
+      # @param column [Symbol, String] column name
+      # @param type [Symbol] column type
+      # @param options [Hash] column options
+      def add_column(table, column, type, **options)
+        sql_type = TableDefinition.sql_type(type, options)
+        @connection.execute("ALTER TABLE #{table} ADD COLUMN #{column} #{sql_type}")
+      end
+
+      # Remove a column
+      #
+      # @param table [Symbol, String] table name
+      # @param column [Symbol, String] column name
+      def remove_column(table, column)
+        @connection.execute("ALTER TABLE #{table} DROP COLUMN #{column}")
+      end
+
+      # Add an index
+      #
+      # @param table [Symbol, String] table name
+      # @param columns [Array<Symbol>] column names
+      # @param options [Hash] index options
+      def add_index(table, columns, unique: false, name: nil)
+        columns = Array(columns)
+        index_name = name || "idx_#{table}_#{columns.join('_')}"
+        unique_str = unique ? "UNIQUE " : ""
+        @connection.execute("CREATE #{unique_str}INDEX #{index_name} ON #{table} (#{columns.join(', ')})")
+      end
+
+      # Execute raw SQL
+      #
+      # @param sql [String] SQL statement
+      def execute(sql)
+        @connection.execute(sql)
+      end
+    end
+
+    # Table definition builder for migrations
+    #
+    # @since 0.1.0
+    class TableDefinition
+      TYPE_MAP = {
+        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"
+      }.freeze
+
+      # @param name [Symbol, String] table name
+      def initialize(name)
+        @name = name
+        @columns = []
+        @columns << "id INTEGER PRIMARY KEY AUTOINCREMENT"
+      end
+
+      # Add a column
+      #
+      # @param name [Symbol, String] column name
+      # @param type [Symbol] column type
+      # @param options [Hash] column options
+      def column(name, type, **options)
+        @columns << "#{name} #{self.class.sql_type(type, options)}"
+      end
+
+      # Column type shortcuts
+      %i[string text integer bigint float decimal boolean date datetime timestamp time binary json].each do |type|
+        define_method(type) do |name, **options|
+          column(name, type, **options)
+        end
+      end
+
+      # Add timestamps (created_at, updated_at)
+      def timestamps
+        @columns << "created_at DATETIME"
+        @columns << "updated_at DATETIME"
+      end
+
+      # Add foreign key reference
+      #
+      # @param table [Symbol, String] referenced table
+      # @param options [Hash] reference options
+      def references(table, foreign_key: true, **options)
+        column_name = "#{table}_id"
+        @columns << "#{column_name} INTEGER"
+        @columns << "FOREIGN KEY (#{column_name}) REFERENCES #{table}(id)" if foreign_key
+      end
+
+      # Generate SQL type string
+      #
+      # @param type [Symbol] column type
+      # @param options [Hash] column options
+      # @return [String]
+      def self.sql_type(type, options = {})
+        base = TYPE_MAP[type] || "VARCHAR(255)"
+
+        if type == :string && options[:limit]
+          base = "VARCHAR(#{options[:limit]})"
+        elsif type == :decimal && (options[:precision] || options[:scale])
+          precision = options[:precision] || 10
+          scale = options[:scale] || 0
+          base = "DECIMAL(#{precision}, #{scale})"
+        end
+
+        base += " NOT NULL" if options[:null] == false
+        base += " DEFAULT #{quote_default(options[:default])}" if options.key?(:default)
+        base
+      end
+
+      # Generate CREATE TABLE SQL
+      #
+      # @return [String]
+      def to_sql
+        "CREATE TABLE #{@name} (\n  #{@columns.join(",\n  ")}\n)"
+      end
+
+      private
+
+      def self.quote_default(value)
+        case value
+        when String then "'#{value}'"
+        when nil then "NULL"
+        when true then "1"
+        when false then "0"
+        else value.to_s
+        end
+      end
+    end
+  end
+
+  # Database-related error
+  class DatabaseError < Error; end
+end

data/lib/tarsier/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Tarsier
+  # Base error class for all Tarsier errors
+  class Error < StandardError; end
+
+  # Raised when a route cannot be found
+  class RouteNotFoundError < Error
+    attr_reader :method, :path
+
+    def initialize(method, path)
+      @method = method
+      @path = path
+      super("No route matches [#{method}] #{path}")
+    end
+  end
+
+  # Raised when route definition is invalid
+  class InvalidRouteError < Error; end
+
+  # Raised when parameter validation fails
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super("Validation failed: #{errors.map { |k, v| "#{k} #{v.join(', ')}" }.join('; ')}")
+    end
+  end
+
+  # Raised when a required parameter is missing
+  class MissingParameterError < ValidationError
+    def initialize(param_name)
+      super({ param_name => ["is required"] })
+    end
+  end
+
+  # Raised when parameter type coercion fails
+  class TypeCoercionError < Error
+    attr_reader :param_name, :expected_type, :actual_value
+
+    def initialize(param_name, expected_type, actual_value)
+      @param_name = param_name
+      @expected_type = expected_type
+      @actual_value = actual_value
+      super("Cannot coerce '#{actual_value}' to #{expected_type} for parameter '#{param_name}'")
+    end
+  end
+
+  # Raised when middleware configuration is invalid
+  class MiddlewareError < Error; end
+
+  # Raised when controller action is not found
+  class ActionNotFoundError < Error
+    attr_reader :controller, :action
+
+    def initialize(controller, action)
+      @controller = controller
+      @action = action
+      super("Action '#{action}' not found in #{controller}")
+    end
+  end
+
+  # Raised when response has already been sent
+  class ResponseAlreadySentError < Error
+    def initialize
+      super("Response has already been sent")
+    end
+  end
+
+  # Raised when streaming is not supported
+  class StreamingNotSupportedError < Error
+    def initialize
+      super("Streaming is not supported by the current server")
+    end
+  end
+end

data/lib/tarsier/middleware/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tarsier
+  module Middleware
+    # Base class for all middleware
+    # Provides a consistent interface for request/response processing
+    class Base
+      attr_reader :app, :options
+
+      # @param app [Object] the next middleware or application
+      # @param options [Hash] middleware options
+      def initialize(app, **options)
+        @app = app
+        @options = options
+      end
+
+      # Process the request
+      # @param request [Request] the request object
+      # @param response [Response] the response object
+      # @return [Response]
+      def call(request, response)
+        before(request, response)
+        result = @app.call(request, response)
+        after(request, result)
+        result
+      end
+
+      protected
+
+      # Called before the next middleware/app
+      # Override in subclasses
+      # @param request [Request]
+      # @param response [Response]
+      def before(request, response)
+        # Override in subclass
+      end
+
+      # Called after the next middleware/app
+      # Override in subclasses
+      # @param request [Request]
+      # @param response [Response]
+      def after(request, response)
+        # Override in subclass
+      end
+    end
+  end
+end