gemstack 0.2.5 → 0.3.0

data/lib/gemstack/db/json_compat.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Sequel (5.108 and earlier) parses JSON/JSONB columns with
+    # JSON.parse(json, create_additions: false), an option json 3.0 removed, so
+    # every jsonb read raises ArgumentError. JSON.parse never creates additions,
+    # so dropping the option keeps Sequel's behaviour.
+    module JSONCompat
+      def parse_json(json) = JSON.parse(json)
+
+      def self.install!
+        return unless Gem::Version.new(JSON::VERSION) >= Gem::Version.new("3.0")
+
+        Sequel.singleton_class.prepend(self)
+      end
+    end
+  end
+end
+
+GemStack::DB::JSONCompat.install!

data/lib/gemstack/db/migrator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+Sequel.extension :migration
+
+module GemStack
+  module DB
+    # Timestamped Sequel migrations in db/migrations:
+    #
+    #   # db/migrations/20260928120000_create_products.rb
+    #   Sequel.migration do
+    #     change do
+    #       create_table(:products) do
+    #         primary_key :id, type: :Bignum
+    #         String :name, null: false
+    #         timestamptz :created_at, null: false
+    #       end
+    #     end
+    #   end
+    #
+    # Migrations are plain Sequel migrations; the full Sequel schema DSL applies.
+    class Migrator
+      Entry = Struct.new(:version, :name, :file, :applied, keyword_init: true)
+
+      attr_reader :db, :path
+
+      def initialize(database = DB.connection, path = GemStack.root.join(DB.config.migrations_path).to_s)
+        @db = database
+        @path = path.to_s
+      end
+
+      def files = Dir.glob(File.join(path, "*.rb"))
+
+      # Applies pending migrations (or migrates up/down to target). Returns the
+      # file names that were applied or reverted.
+      def migrate(target: nil)
+        before = applied
+        run(target)
+        after = applied
+        (after - before) + (before - after)
+      end
+
+      # Reverts the last `steps` applied migrations.
+      def rollback(steps: 1)
+        versions = applied.map { |file| version_of(file) }.sort
+        return [] if versions.empty?
+
+        target = versions[-(steps + 1)] || 0
+        migrate(target: target)
+      end
+
+      def status
+        done = applied
+        files.map do |file|
+          base = File.basename(file)
+          Entry.new(version: version_of(base), name: base.sub(/\A\d+_/, "").delete_suffix(".rb"), file: base,
+                    applied: done.include?(base))
+        end.sort_by(&:version)
+      end
+
+      def pending = status.reject(&:applied)
+      def pending? = !pending.empty?
+
+      def applied
+        return [] if DB.table_missing?(db, :schema_migrations)
+
+        db[:schema_migrations].select_map(:filename)
+      end
+
+      private
+
+      def run(target)
+        return unless File.directory?(path)
+
+        Sequel::TimestampMigrator.new(db, path, target: target).run
+      end
+
+      def version_of(file) = File.basename(file)[/\A\d+/].to_i
+    end
+  end
+end

data/lib/gemstack/db/model.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Base class for models: Sequel::Model plus GemStack conventions.
+  #
+  #   class Product < GemStack::Model
+  #     field :name, :string, null: false, size: 120
+  #     field :price, :decimal, null: false, gt: 0
+  #     field :active, :boolean, null: false, default: true
+  #
+  #     validates :name, format: /\A\S/
+  #     belongs_to :category
+  #     has_many :reviews
+  #   end
+  #
+  # `field` declarations are metadata that drive validations, request
+  # schemas (Product.input_schema), serializer types and TypeScript. The
+  # database schema itself comes from migrations; everything Sequel offers
+  # (datasets, associations, hooks, plugins) is available unchanged.
+  #
+  # Created with Class.new on purpose: an *anonymous* subclass stops Sequel
+  # from binding GemStack::Model itself to a "models" table (which would need
+  # a database connection just to require this file).
+  Model = Class.new(Sequel::Model) # rubocop:disable Style/EmptyClassDefinition
+
+  class Model
+    Field = Struct.new(:name, :type, :options)
+
+    FIELD_RULES = %i[null default size gt gte lt lte in format].freeze
+
+    plugin :timestamps, update_on_create: true
+    plugin :validation_helpers
+
+    # A model may load before its migration has run (e.g. while generating the
+    # API contract right after `generate resource`); queries still fail
+    # clearly with "relation does not exist".
+    self.require_valid_table = false
+
+    class << self
+      def gemstack_fields
+        @gemstack_fields ||= superclass.respond_to?(:gemstack_fields) ? superclass.gemstack_fields.dup : {}
+      end
+
+      # Declares a field. Options: null: false (required), default:, size:
+      # (max length), gt/gte/lt/lte, in:, format:. Types are GemStack::Types.
+      def field(name, type, **options)
+        Types.fetch(type)
+        unknown = options.keys - FIELD_RULES
+        raise ArgumentError, "unknown field option(s) #{unknown.inspect} for #{name}" unless unknown.empty?
+
+        @input_schemas = nil
+        serialize_json(name) if Types::CLASS_ALIASES.fetch(type, type).to_sym == :json
+        gemstack_fields[name.to_sym] = Field.new(name.to_sym, Types::CLASS_ALIASES.fetch(type, type).to_sym,
+                                                 options.freeze)
+      end
+
+      def gemstack_validations
+        @gemstack_validations ||=
+          superclass.respond_to?(:gemstack_validations) ? superclass.gemstack_validations.dup : []
+      end
+
+      # validates :name, :sku, presence: true, length: { max: 40 }, format: /\A[A-Z]/,
+      #           inclusion: { in: %w[a b] }, numericality: { gt: 0 }, uniqueness: true
+      def validates(*names, **rules)
+        unknown = rules.keys - %i[presence length format inclusion numericality uniqueness]
+        raise ArgumentError, "unknown validation(s) #{unknown.inspect}" unless unknown.empty?
+
+        gemstack_validations << [names.map(&:to_sym), rules]
+      end
+
+      # A request schema derived from the field declarations (memoized):
+      #   accepts :create, with: Product.input_schema
+      def input_schema(only: nil, except: nil)
+        key = [only, except]
+        (@input_schemas ||= {})[key] ||= Schema.from_model(
+          self, only: only, except: except, type_name: "#{name.to_s.split("::").join}Input"
+        )
+      end
+
+      # find(42) raises GemStack::DB::RecordNotFound (404) when missing.
+      # With a Hash or block it behaves like Sequel's find (nil when missing).
+      def find(*args, &block)
+        return super if block || args.size != 1 || args.first.is_a?(Hash)
+
+        id = args.first
+        record = valid_primary_key?(id) ? with_pk(id) : nil
+        record || raise(DB::RecordNotFound, "#{name} #{id} not found")
+      end
+
+      def find_by(conditions) = first(conditions)
+      def find_by!(conditions) = first(conditions) || raise(DB::RecordNotFound, "#{name} not found")
+
+      alias create! create
+
+      # Associations with familiar names; the Sequel names work too.
+      def belongs_to(name, **) = many_to_one(name, **)
+      def has_many(name, **) = one_to_many(name, **) # rubocop:disable Naming/PredicatePrefix
+      def has_one(name, **) = one_to_one(name, **) # rubocop:disable Naming/PredicatePrefix
+      def has_and_belongs_to_many(name, **) = many_to_many(name, **) # rubocop:disable Naming/PredicatePrefix
+
+      private
+
+      # PostgreSQL's jsonb comes back as Hash/Array (pg_json); MySQL JSON and
+      # SQLite text come back as strings, so those fields are (de)serialized.
+      def serialize_json(name)
+        return if db.database_type == :postgres
+
+        plugin :serialization unless respond_to?(:serialization_map)
+        serialize_attributes :json, name unless serialization_map.key?(name.to_sym)
+      end
+
+      # For a table that doesn't exist yet, skip Sequel's schema queries: they
+      # would fail and log two errors per model (e.g. while `gemstack contract`
+      # runs before `db:migrate`). One cheap catalog lookup decides.
+      def get_db_schema(reload = reload_db_schema?)
+        return super unless missing_table?
+
+        set_columns(nil)
+        {}
+      end
+
+      def missing_table?
+        return false unless @dataset
+
+        DB.table_missing?(db, dataset.first_source_table)
+      rescue Sequel::Error
+        false
+      end
+
+      def valid_primary_key?(id)
+        return true unless integer_primary_key?
+
+        id.is_a?(Integer) || (id.is_a?(String) && id.match?(/\A\d{1,19}\z/))
+      end
+
+      def integer_primary_key?
+        return @integer_primary_key if defined?(@integer_primary_key)
+
+        @integer_primary_key = primary_key.is_a?(Symbol) && db_schema.dig(primary_key, :type) == :integer
+      end
+    end
+
+    alias update! update
+
+    # Identifies this version of the record, for ETags (Controller#stale?) and
+    # cache keys: "product/42-1759052159.123456".
+    def cache_key
+      stamp = respond_to?(:updated_at) && updated_at ? "-#{updated_at.to_f}" : ""
+      "#{Inflector.underscore(self.class.name.to_s)}/#{pk}#{stamp}"
+    end
+
+    def validate
+      super
+      validate_fields
+      self.class.gemstack_validations.each { |names, rules| apply_validations(names, rules) }
+    end
+
+    # Models are never rendered implicitly: exposing every column is how
+    # APIs leak data. Define a serializer instead.
+    def as_json(*)
+      file = "#{Inflector.underscore(self.class.name)}_serializer.rb"
+      raise Error, "#{self.class.name} has no serializer. Create #{file} " \
+                   "in app/serializers (class #{self.class.name}Serializer < GemStack::Serializer)."
+    end
+
+    def to_json(*) = as_json
+
+    private
+
+    def validate_fields
+      self.class.gemstack_fields.each_value do |field|
+        opts = field.options
+        name = field.name
+        if opts[:null] == false && !opts.key?(:default)
+          if field.type == :boolean
+            validates_includes([true, false], name, message: "must be true or false")
+          else
+            validates_presence(name, message: "is required")
+          end
+        end
+        apply_rules(name, opts)
+      end
+    end
+
+    def apply_rules(name, opts)
+      if opts[:size].is_a?(Integer)
+        validates_max_length(opts[:size], name, message: "is too long (maximum #{opts[:size]} characters)",
+                                                allow_nil: true)
+      end
+      { gt: :>, gte: :>=, lt: :<, lte: :<= }.each do |key, operator|
+        next unless opts.key?(key)
+
+        words = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
+        validates_operator(operator, opts[key], name, message: "must be #{words[key]} #{opts[key]}", allow_nil: true)
+      end
+      if opts[:in]
+        validates_includes(opts[:in], name, message: "must be one of: #{opts[:in].to_a.join(", ")}",
+                                            allow_nil: true)
+      end
+      validates_format(opts[:format], name, message: "is invalid", allow_nil: true) if opts[:format]
+    end
+
+    def apply_validations(names, rules)
+      names.each do |name|
+        validates_presence(name, message: "is required") if rules[:presence]
+        length = rules[:length]
+        if length
+          apply_rules(name, size: length[:max]) if length[:max]
+          if length[:min]
+            validates_min_length(length[:min], name, message: "is too short (minimum #{length[:min]} characters)",
+                                                     allow_nil: true)
+          end
+        end
+        apply_rules(name, format: rules[:format]) if rules[:format]
+        inclusion = rules[:inclusion]
+        apply_rules(name, in: inclusion.is_a?(Hash) ? inclusion[:in] : inclusion) if inclusion
+        numeric = rules[:numericality]
+        if numeric
+          validates_numeric(name, message: "must be a number", allow_nil: true)
+          apply_rules(name, numeric.slice(:gt, :gte, :lt, :lte)) if numeric.is_a?(Hash)
+        end
+        validates_unique(name, message: "is already taken") if rules[:uniqueness]
+      end
+    end
+  end
+end

data/lib/gemstack/db/schema_types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GemStack
+  module DB
+    # Migrations may use PostgreSQL's type names — the generators write
+    # `column :created_at, :timestamptz` — and still run on MySQL and SQLite,
+    # where each maps to the closest native type. Everything
+    # else in the Sequel schema DSL is untouched.
+    module SchemaTypes
+      MAPPINGS = {
+        mysql: { "timestamptz" => "datetime(6)", "timestamp" => "datetime(6)", "jsonb" => "json",
+                 "uuid" => "char(36)", "inet" => "varchar(45)", "citext" => "varchar(255)" },
+        sqlite: { "timestamptz" => "timestamp", "jsonb" => "json", "uuid" => "varchar(36)",
+                  "inet" => "varchar(45)", "citext" => "varchar(255)" }
+      }.freeze
+
+      private
+
+      def type_literal_specific(column)
+        type = column[:type]
+        mapped = MAPPINGS.dig(database_type, type.to_s.downcase) if type.is_a?(Symbol) || type.is_a?(String)
+        mapped || super
+      end
+    end
+  end
+end
+
+Sequel::Database.prepend(GemStack::DB::SchemaTypes)

data/lib/gemstack/db/tasks.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module GemStack
+  module DB
+    # Database lifecycle used by `gemstack db:*`, for every adapter:
+    # PostgreSQL and MySQL through a server connection without the database,
+    # SQLite by creating or deleting the file.
+    #
+    # Each method takes resolved settings (DB.settings, the default) or a URL.
+    module Tasks
+      module_function
+
+      def settings_for(target)
+        target.is_a?(String) ? Configuration.from_url(target, root: GemStack.config.root) : target.except(:source)
+      end
+
+      # The database name (SQLite: the file, relative to the app).
+      def database_name(target = DB.settings)
+        name = settings_for(target)[:database].to_s
+        name.delete_prefix("#{GemStack.config.root}/")
+      end
+
+      def exists?(target = DB.settings)
+        settings = settings_for(target)
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite" then name == ":memory:" || File.file?(name)
+        when "postgres" then with_server(settings) { |db| db[:pg_database].where(datname: name).any? }
+        else with_server(settings) { |db| db[Sequel[:information_schema][:schemata]].where(schema_name: name).any? }
+        end
+      end
+
+      # Returns :created or :exists.
+      def create(target = DB.settings)
+        settings = settings_for(target)
+        return :exists if exists?(settings)
+
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite"
+          FileUtils.mkdir_p(File.dirname(name))
+          Sequel.connect(**settings, test: true, keep_reference: false).disconnect # creates the file
+        when "postgres"
+          with_server(settings) { |db| db.run("CREATE DATABASE #{db.literal(Sequel.identifier(name))}") }
+        else
+          with_server(settings) do |db|
+            db.run("CREATE DATABASE #{db.literal(Sequel.identifier(name))} " \
+                   "CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci")
+          end
+        end
+        :created
+      end
+
+      # Refuses outside development/test unless GEMSTACK_ALLOW_DB_DROP=1.
+      def drop(target = DB.settings)
+        unless GemStack.env.local? || ENV["GEMSTACK_ALLOW_DB_DROP"] == "1"
+          raise Error, "refusing to drop the #{GemStack.env} database; set GEMSTACK_ALLOW_DB_DROP=1 to confirm"
+        end
+
+        settings = settings_for(target)
+        return :missing unless exists?(settings)
+
+        DB.disconnect
+        name = settings[:database].to_s
+        case settings[:adapter]
+        when "sqlite" then FileUtils.rm_f(["", "-wal", "-shm", "-journal"].map { |suffix| "#{name}#{suffix}" })
+        when "postgres"
+          with_server(settings) { |db| db.run("DROP DATABASE #{db.literal(Sequel.identifier(name))} WITH (FORCE)") }
+        else with_server(settings) { |db| db.run("DROP DATABASE #{db.literal(Sequel.identifier(name))}") }
+        end
+        :dropped
+      end
+
+      def seed(path = GemStack.root.join(DB.config.seeds_path))
+        return false unless File.file?(path)
+
+        load path.to_s
+        true
+      end
+
+      # A connection to the server itself: PostgreSQL's "postgres" maintenance
+      # database, or MySQL without a default database.
+      def with_server(settings)
+        server = settings.merge(database: settings[:adapter] == "postgres" ? "postgres" : nil).compact
+        db = Sequel.connect(**server, max_connections: 1, test: true, keep_reference: false)
+        yield db
+      ensure
+        db&.disconnect
+      end
+    end
+  end
+end

data/lib/gemstack/db/testing.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "gemstack/db"
+require "securerandom"
+
+module GemStack
+  module DB
+    # Test support, used by the generated test/test_helper.rb:
+    #
+    #   require "gemstack/db/testing"
+    #   GemStack::DB::Testing.prepare!             # create + migrate the test database
+    #   GemStack::TestCase.include GemStack::DB::Testing::Transactions
+    module Testing
+      module_function
+
+      # Creates the test database if needed and applies pending migrations,
+      # so `gemstack test` works on a fresh checkout.
+      def prepare!
+        Tasks.create
+        Migrator.new.migrate
+      end
+
+      # Valid attribute values for a model, derived from its `field`
+      # declarations (types, size, gt/gte/lt/lte, in:). Unique-looking values
+      # use a sequence; `references` fields create the referenced record.
+      # Fields with a `format:` rule may need an override.
+      #
+      #   Product.create(GemStack::DB::Testing.sample_attributes(Product, name: "Lamp"))
+      def sample_attributes(model, overrides = {})
+        @sequence = (@sequence || 0) + 1
+        model.gemstack_fields.each_value.with_object({}) do |field, attrs|
+          attrs[field.name] = sample_value(model, field, @sequence)
+        end.merge(overrides)
+      end
+
+      # sample_attributes as JSON-ready values (for request bodies).
+      def sample_payload(model, overrides = {})
+        sample_attributes(model, overrides).transform_values do |value|
+          case value
+          when BigDecimal then value.to_s("F")
+          when Time then value.utc.iso8601
+          when Date then value.iso8601
+          else value
+          end
+        end
+      end
+
+      def sample_value(model, field, sequence)
+        opts = field.options
+        return Array(opts[:in]).first if opts[:in]
+
+        case field.type
+        when :string, :text then sample_string(field, opts, sequence)
+        when :integer, :bigint then bounded(opts, 1, step: 1).to_i
+        when :float then bounded(opts, 1.5, step: 1).to_f
+        when :decimal then BigDecimal(bounded(opts, BigDecimal("9.99"), step: 1).to_s)
+        when :boolean then true
+        when :date then Date.today
+        when :datetime then Time.now.utc.round
+        when :uuid then SecureRandom.uuid
+        when :json then { "sample" => true }
+        when :references then sample_reference(model, field)
+        end
+      end
+
+      def sample_string(field, opts, sequence)
+        value = "#{Inflector.humanize(field.name)} #{sequence}"
+        opts[:size].is_a?(Integer) ? value[0, opts[:size]] : value
+      end
+
+      def bounded(opts, value, step:)
+        value = opts[:gt] + step if opts[:gt] && value <= opts[:gt]
+        value = opts[:gte] if opts[:gte] && value < opts[:gte]
+        value = opts[:lt] - step if opts[:lt] && value >= opts[:lt]
+        value = opts[:lte] if opts[:lte] && value > opts[:lte]
+        value
+      end
+
+      def sample_reference(model, field)
+        reflection = model.association_reflections.values.find { |r| r[:key] == field.name }
+        target = reflection&.associated_class ||
+                 Object.const_get(Inflector.camelize(field.name.to_s.delete_suffix("_id")))
+        target.create(sample_attributes(target)).pk
+      end
+
+      # Runs every test inside a transaction that is rolled back afterwards.
+      # Requests made through rack-test run on the same thread, so they see
+      # (and roll back) the same data. Nested GemStack.transaction calls
+      # become savepoints.
+      module Transactions
+        def run(...)
+          result = nil
+          DB.connection.transaction(rollback: :always, auto_savepoint: true) { result = super }
+          result
+        end
+      end
+    end
+  end
+end