hamster-web 0.1.0.pre.2

data/lib/hamster/data/record.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hamster
+  module Record
+    class Error < StandardError
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+        super(result.errors.join(", "))
+      end
+    end
+
+    class ValidationError < Error; end
+    class ConflictError < Error; end
+    class NotFoundError < Error; end
+    class PersistenceError < Error; end
+    class MissingConnection < StandardError; end
+
+    class Result
+      attr_reader :record, :code, :errors, :cause
+
+      def initialize(record:, code: nil, errors: [], cause: nil)
+        @record = record
+        @code = code
+        @errors = errors
+        @cause = cause
+      end
+
+      def success?
+        code.nil?
+      end
+
+      def value!
+        return record if success?
+
+        error_class = case code
+                      when :invalid then ValidationError
+                      when :conflict then ConflictError
+                      when :not_found then NotFoundError
+                      else PersistenceError
+                      end
+        raise error_class.new(self)
+      end
+    end
+
+    def self.with_connection(connection)
+      previous = Thread.current[:hamster_record_connection]
+      Thread.current[:hamster_record_connection] = connection
+      yield
+    ensure
+      Thread.current[:hamster_record_connection] = previous
+    end
+
+    def self.connection
+      Thread.current[:hamster_record_connection] ||
+        raise(MissingConnection, "Bind a database connection with Hamster::Record.with_connection")
+    end
+
+
+    def initialize(attributes = nil, **keywords)
+      source = attributes || keywords
+      @attributes = {}
+      source.each { |key, value| @attributes[key.to_sym] = value }
+      @partial = !attributes.nil?
+    end
+
+    def [](name)
+      key = name.to_sym
+      raise MissingAttributeError, "Unloaded attribute #{key}" if @partial && !@attributes.key?(key)
+      raise MissingAttributeError, "Undeclared attribute #{key}" unless self.class.columns.key?(key)
+      @attributes[key]
+    end
+
+    def write_attribute(name, value)
+      @attributes[name.to_sym] = value
+    end
+  end
+
+  class MissingAttributeError < StandardError; end
+end

data/lib/hamster/data/table.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Table
+    include Record
+    include Persistence
+    extend Persistence::ClassMethods
+
+    REGISTRY = []
+
+    def self.inherited(child)
+      child.set_metadata(table_name, schema_name, columns) unless self == Table
+      REGISTRY << child
+    end
+
+    def self.set_metadata(name, schema, definitions)
+      @table_name = name
+      @schema_name = schema
+      @columns = definitions.dup
+    end
+
+    def self.registry
+      REGISTRY.dup.freeze
+    end
+
+    def self.table(name, schema: "public")
+      @table_name = Read.identifier(name)
+      @schema_name = Read.identifier(schema)
+    end
+
+    def self.table_name
+      @table_name || name.split("::").last.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z0-9])([A-Z])/, '\1_\2').downcase + "s"
+    end
+
+    def self.schema_name
+      @schema_name || "public"
+    end
+
+    def self.columns
+      (@columns || {}).dup.freeze
+    end
+
+    def self.column(name, type:, nullable: true, enabled: true, write: :none)
+      register_column(name, type: type, nullable: nullable, enabled: enabled, write: write)
+      # Spinel expands these names from literal column declarations at compile time.
+      if RUBY_ENGINE == "ruby"
+        define_method("#{name}") { self[name] }
+        define_method("#{name}=") { |value| write_attribute(name, value) }
+      end
+    end
+
+    def self.register_column(name, type:, nullable:, enabled:, write:)
+      raise Read::ValidationError, "Unsupported column type #{type}" unless Read::TYPES.key?(type)
+      unless [true, false].include?(nullable) && [true, false].include?(enabled)
+        raise Read::ValidationError, "Column flags must be boolean"
+      end
+      unless [:none, :create, :update, :both].include?(write)
+        raise Read::ValidationError, "Column write must be :none, :create, :update, or :both"
+      end
+      key = Read.identifier(name).to_sym
+      unless key.to_s.match?(/\A[a-z_][a-z0-9_]*\z/)
+        raise Read::ValidationError, "Column #{key} cannot be used as a record accessor"
+      end
+      if Table.method_defined?(key) || Table.private_method_defined?(key) ||
+         Table.method_defined?("#{key}=") || Table.private_method_defined?("#{key}=")
+        raise Read::ValidationError, "Column #{key} would shadow a record method"
+      end
+      @columns = columns.merge(key => { type: type, nullable: nullable, enabled: enabled, write: write }.freeze)
+    end
+
+    def self.[](name); Read::Source.new(self)[name]; end
+    def self.as(name); Read::Source.new(self, name); end
+    def self.all; Read::Source.new(self).all; end
+    def self.first(connection: nil); all.first(connection: connection); end
+    def self.last(connection: nil); all.last(connection: connection); end
+    def self.count(connection: nil); all.count(connection: connection); end
+    def self.select(*items); all.select(*items); end
+    def self.reselect(*items); all.reselect(*items); end
+    def self.group(*items); all.group(*items); end
+    def self.order(*items); all.order(*items); end
+    def self.reorder(*items); all.reorder(*items); end
+    def self.where(value); all.where(value); end
+    def self.having(value); all.having(value); end
+    def self.limit(value); all.limit(value); end
+    def self.offset(value); all.offset(value); end
+    def self.distinct(enabled = true); all.distinct(enabled); end
+    def self.joins(source, on:); all.joins(source, on: on); end
+    def self.left_joins(source, on:); all.left_joins(source, on: on); end
+  end
+end

data/lib/hamster/data.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "web/instrumentation"
+require_relative "database/errors"
+require_relative "database/configuration"
+require_relative "database/result"
+require_relative "database/connection"
+require_relative "database/pool"
+require_relative "database/admin"
+require_relative "database/database"
+require_relative "data/record"
+require_relative "data/persistence"
+require_relative "data/read/nodes"
+require_relative "data/read/relation"
+require_relative "data/read/validator"
+require_relative "data/read/compiler"
+require_relative "data/read/decoder"
+require_relative "data/table"
+require_relative "data/query"
+require_relative "data/read/schema"

data/lib/hamster/database/admin.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Database
+    class Admin
+      def self.create!(configuration)
+        connection = Connection.new(Postgres.connect(admin_configuration(configuration)))
+        existing = connection.execute("SELECT 1 FROM pg_database WHERE datname = $1", [configuration.database])
+        return false unless existing.rows.empty?
+
+        connection.execute_script("CREATE DATABASE #{quote_identifier(configuration.database)}")
+        true
+      ensure
+        connection&.close
+      end
+
+      def self.admin_configuration(configuration)
+        Configuration.new(
+          adapter: configuration.adapter,
+          host: configuration.host,
+          port: configuration.port,
+          database: configuration.admin_database,
+          username: configuration.admin_username,
+          password: configuration.admin_password,
+          pool_size: 1,
+          checkout_timeout: configuration.checkout_timeout
+        )
+      end
+
+      def self.quote_identifier(identifier)
+        raise ConfigurationError, "unsafe database name" unless identifier.match?(/\A[a-z_][a-z0-9_]*\z/)
+
+        "\"#{identifier}\""
+      end
+
+      private_class_method :admin_configuration, :quote_identifier
+    end
+  end
+end

data/lib/hamster/database/configuration.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Database
+    class Configuration
+      attr_reader :adapter, :host, :port, :database, :username, :password,
+                  :pool_size, :checkout_timeout, :admin_database,
+                  :admin_username, :admin_password
+
+      def initialize(adapter:, host:, port:, database:, username:, password:, pool_size:, checkout_timeout:,
+                     admin_database: "postgres", admin_username: nil, admin_password: nil)
+        @adapter = adapter.to_s
+        @host = host.to_s
+        @port = integer_value(port, "port")
+        @database = database.to_s
+        @username = username.to_s
+        @password = password.to_s
+        @pool_size = integer_value(pool_size, "pool_size")
+        @checkout_timeout = float_value(checkout_timeout, "checkout_timeout")
+        @admin_database = admin_database.to_s
+        @admin_username = (admin_username || username).to_s
+        @admin_password = (admin_password || password).to_s
+        validate!
+      end
+
+      def self.from_env(env = ENV, app_name: "hamster")
+        if env.key?("DATABASE_TLS") || env.key?("DATABASE_SSLMODE")
+          raise ConfigurationError, "database TLS settings are unsupported by the postgres adapter"
+        end
+
+        adapter = env.fetch("DATABASE_ADAPTER", "postgres").dup
+        host = env.fetch("DATABASE_HOST", "127.0.0.1").dup
+        port = env.fetch("DATABASE_PORT", "5432").dup
+        app_name = env.fetch("HAMSTER_APP_NAME", app_name).dup
+        environment = env.fetch("HAMSTER_ENV", "development").dup
+        database = env.fetch("DATABASE_NAME", "#{app_name}_#{environment}").dup
+        username = env.fetch("DATABASE_USERNAME").dup
+        password = env.fetch("DATABASE_PASSWORD", "").dup
+        admin_database = env.fetch("DATABASE_ADMIN_NAME", "postgres").dup
+        admin_username = env.fetch("DATABASE_ADMIN_USERNAME", username).dup
+        admin_password = env.fetch("DATABASE_ADMIN_PASSWORD", password).dup
+        pool_size = env.fetch("DATABASE_POOL_SIZE", "5").dup
+        checkout_timeout = env.fetch("DATABASE_CHECKOUT_TIMEOUT", "5.0").dup
+        new(
+          adapter: adapter, host: host, port: port, database: database,
+          username: username, password: password, pool_size: pool_size,
+          checkout_timeout: checkout_timeout, admin_database: admin_database,
+          admin_username: admin_username, admin_password: admin_password
+        )
+      rescue KeyError => error
+        raise ConfigurationError, "missing database setting #{error.key}"
+      end
+
+      private
+
+      def integer_value(value, name)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise ConfigurationError, "database #{name} must be an integer"
+      end
+
+      def float_value(value, name)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ConfigurationError, "database #{name} must be a number"
+      end
+
+      def validate!
+        raise ConfigurationError, "unsupported database adapter #{adapter.inspect}" unless adapter == "postgres"
+        raise ConfigurationError, "database host must not be empty" if host.empty?
+        raise ConfigurationError, "database port must be between 1 and 65535" unless port.between?(1, 65_535)
+        raise ConfigurationError, "database name must not be empty" if database.empty?
+        unless database.match?(/\A[a-z_][a-z0-9_]*\z/)
+          raise ConfigurationError, "database name must be a lowercase PostgreSQL identifier"
+        end
+        raise ConfigurationError, "database admin name must not be empty" if admin_database.empty?
+        raise ConfigurationError, "database admin username must not be empty" if admin_username.empty?
+        raise ConfigurationError, "database username must not be empty" if username.empty?
+        raise ConfigurationError, "database pool_size must be positive" unless pool_size.positive?
+        raise ConfigurationError, "database checkout_timeout must be positive" unless checkout_timeout.positive?
+      end
+    end
+  end
+end

data/lib/hamster/database/connection.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+
+module Hamster
+  class Database
+    class Connection
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+        @usable = true
+      end
+
+      def execute(sql, params = [])
+        Hamster::Instrumentation.instrument("db.execute", attributes: {"db.system.name" => "postgresql", "db.operation.name" => Hamster::Instrumentation.sql_operation(sql)}, kind: "client") do |details|
+          begin
+            execute_statement(sql, params)
+          rescue Error => error
+            Database.telemetry_error(details, error)
+            raise
+          end
+        end
+      end
+
+      def execute_statement(sql, params)
+        values = serialize_params(params)
+        result = raw.exec_params(sql, values)
+        result_object(result)
+      rescue ArgumentError => error
+        raise error
+      rescue PG::Error => error
+        mark_unusable unless usable_status?
+        raise QueryError.new("database query failed", original: error,
+                             sqlstate: Postgres.sqlstate(error))
+      rescue StandardError => error
+        mark_unusable unless usable_status?
+        raise error if error.is_a?(Error)
+
+        raise ConnectionError.new("database operation failed: #{error.message}", original: error)
+      end
+
+      def execute_script(sql)
+        Hamster::Instrumentation.instrument("db.execute_script", attributes: {"db.system.name" => "postgresql", "db.operation.name" => "SCRIPT"}, kind: "client") do |details|
+          begin
+            execute_script_statement(sql)
+          rescue Error => error
+            Database.telemetry_error(details, error)
+            raise
+          end
+        end
+      end
+
+      def execute_script_statement(sql)
+        result_object(raw.exec(sql))
+      rescue PG::Error => error
+        mark_unusable unless usable_status?
+        raise QueryError.new("database query failed", original: error,
+                             sqlstate: Postgres.sqlstate(error))
+      rescue StandardError => error
+        mark_unusable unless usable_status?
+        raise error if error.is_a?(Error)
+
+        raise ConnectionError.new("database operation failed: #{error.message}", original: error)
+      end
+
+      def transaction
+        raise TransactionError, "nested transactions are not supported" unless idle?
+
+        execute("BEGIN")
+        begin
+          result = yield self
+          execute("COMMIT")
+          result
+        rescue StandardError => original
+          begin
+            execute("ROLLBACK") unless idle?
+          rescue StandardError
+            mark_unusable
+          end
+          raise original
+        end
+      end
+
+      def idle?
+        raw.transaction_status == PG::PQTRANS_IDLE
+      rescue StandardError
+        false
+      end
+
+      def usable?
+        @usable && raw.transaction_status != PG::PQTRANS_UNKNOWN
+      rescue StandardError
+        false
+      end
+
+      def close
+        raw.close unless raw.transaction_status == PG::PQTRANS_UNKNOWN
+      rescue StandardError
+        mark_unusable
+      ensure
+        @usable = false
+      end
+
+      def mark_unusable
+        @usable = false
+      end
+
+      private
+
+      private :execute_statement, :execute_script_statement
+
+      def usable_status?
+        raw.transaction_status != PG::PQTRANS_UNKNOWN
+      rescue StandardError
+        false
+      end
+
+      def serialize_params(params)
+        raise ArgumentError, "database parameters must be an Array" unless params.is_a?(Array)
+
+        params.map do |value|
+          case value
+          when NilClass, String then value
+          when Integer then value.to_s
+          when Time then value.iso8601(6)
+          when DateTime then value.iso8601(6)
+          when Date then value.iso8601
+          when TrueClass then "true"
+          when FalseClass then "false"
+          else
+            raise ArgumentError, "unsupported database parameter #{value.class}"
+          end
+        end
+      end
+
+      def copy_rows(result)
+        rows = []
+        row_index = 0
+        while row_index < result.ntuples
+          row = []
+          column_index = 0
+          while column_index < result.nfields
+            row << result.getvalue(row_index, column_index)
+            column_index += 1
+          end
+          rows << row
+          row_index += 1
+        end
+        rows
+      end
+
+      def result_object(result)
+        Result.new(columns: result.fields.dup, rows: copy_rows(result), types: copy_types(result),
+                   command_tag: result.cmd_tag)
+      end
+
+      def copy_types(result)
+        types = []
+        column_index = 0
+        while column_index < result.nfields
+          types << result.ftype(column_index)
+          column_index += 1
+        end
+        types
+      end
+    end
+  end
+end

data/lib/hamster/database/database.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Database
+    attr_reader :configuration
+
+    def initialize(configuration, migrations_path:)
+      @configuration = configuration
+      @migrations_path = File.expand_path(migrations_path)
+      @pool = Pool.new(configuration)
+    end
+
+    # Database boundaries own SQLSTATE classification, never the telemetry core.
+    def self.telemetry_error(details, error)
+      state = error.sqlstate
+      if state.instance_of?(String) && state.valid_encoding? && state.match?(/\A[0-9A-Z]{5}\z/)
+        details["db.response.status_code"] = state
+      end
+    rescue StandardError
+      Hamster::Instrumentation.diagnostic
+    end
+
+    def with_connection
+      connection = Hamster::Instrumentation.instrument("db.checkout", attributes: {"db.system.name" => "postgresql"}) do |details|
+        begin
+          @pool.checkout
+        rescue Error => error
+          Database.telemetry_error(details, error)
+          raise
+        end
+      end
+      begin
+        Hamster::Record.with_connection(connection) { yield connection }
+      ensure
+        @pool.checkin(connection)
+      end
+    end
+
+    def migrate!
+      with_connection do |connection|
+        connection.transaction do
+          connection.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS schema_migrations (
+              version TEXT PRIMARY KEY,
+              applied_at TIMESTAMPTZ NOT NULL
+            )
+          SQL
+
+          applied = rows(connection, "SELECT version FROM schema_migrations ORDER BY version")
+          migration_files.each do |version, path|
+            next if applied.any? { |row| row["version"] == version }
+
+            connection.execute_script(File.read(path))
+            connection.execute("INSERT INTO schema_migrations (version, applied_at) VALUES ($1, $2)",
+                               [version, Time.now.utc.iso8601])
+          end
+        end
+      end
+      true
+    end
+
+    def verify!
+      with_connection do |connection|
+        present = rows(connection, "SELECT to_regclass('public.schema_migrations') AS name")
+        raise ConfigurationError, "migration tracking is missing; run bin/hamster db:migrate" if present.first["name"].nil?
+        applied = rows(connection, "SELECT version FROM schema_migrations ORDER BY version").map { |row| row["version"] }
+        missing = migration_files.map(&:first) - applied
+        raise ConfigurationError, "pending migrations #{missing.join(', ')}; run bin/hamster db:migrate" unless missing.empty?
+      end
+      true
+    end
+
+    def shutdown
+      @pool.shutdown
+    end
+
+    private
+
+    def rows(connection, sql, params = [])
+      connection.execute(sql, params).hashes
+    end
+
+    def migration_files
+      files = Dir[File.join(@migrations_path, "*.sql")].sort.map do |path|
+        [File.basename(path, ".sql").split("_", 2).first, path]
+      end
+      versions = files.map(&:first)
+      raise ConfigurationError, "duplicate migration versions" unless versions.uniq.length == versions.length
+      files
+    end
+  end
+end

data/lib/hamster/database/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Database
+    class Error < StandardError
+      attr_reader :original, :sqlstate
+
+      def initialize(message, original: nil, sqlstate: nil)
+        super(message)
+        @original = original
+        @sqlstate = sqlstate
+      end
+    end
+
+    class ConfigurationError < Error; end
+    class CheckoutTimeout < Error; end
+    class ConnectionError < Error; end
+    class QueryError < Error; end
+    class TransactionError < Error; end
+  end
+end

data/lib/hamster/database/pool.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Hamster
+  class Database
+    class Pool
+      def initialize(configuration)
+        @configuration = configuration
+        @lock = Mutex.new
+        @ready = ConditionVariable.new
+        @available = []
+        @total = 0
+        @borrowed = 0
+        @closed = false
+      end
+
+      def checkout
+        connection = reserve
+        begin
+          connection ||= Connection.new(Postgres.connect(@configuration))
+        rescue StandardError
+          release_failed_reservation
+          raise
+        end
+        connection
+      end
+
+      def checkin(connection)
+        reusable = connection.usable?
+        if reusable && !connection.idle?
+          begin
+            connection.execute("ROLLBACK")
+            reusable = connection.idle?
+          rescue StandardError
+            reusable = false
+          end
+        end
+
+        connection.close unless reusable
+        @lock.synchronize do
+          @borrowed -= 1
+          if reusable && !@closed
+            @available << connection
+          else
+            @total -= 1
+          end
+          @ready.broadcast
+        end
+      end
+
+      def shutdown
+        available = @lock.synchronize do
+          @closed = true
+          connections = @available
+          @available = []
+          @ready.broadcast
+          connections
+        end
+        available.each(&:close)
+      end
+
+      private
+
+      def reserve
+        deadline = Time.now + @configuration.checkout_timeout
+        @lock.synchronize do
+          loop do
+            raise ConnectionError, "database pool is shut down" if @closed
+
+            connection = @available.pop
+            if connection
+              @borrowed += 1
+              return connection
+            end
+
+            if @total < @configuration.pool_size
+              @total += 1
+              @borrowed += 1
+              return nil
+            end
+
+            remaining = deadline - Time.now
+            raise CheckoutTimeout, "database pool checkout timed out" unless remaining.positive?
+
+            @ready.wait(@lock, remaining)
+          end
+        end
+      end
+
+      def release_failed_reservation
+        @lock.synchronize do
+          @total -= 1
+          @borrowed -= 1
+          @ready.broadcast
+        end
+      end
+    end
+  end
+end