gemstack 0.2.5 → 0.3.0

data/lib/gemstack/db.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "json"
+require "gemstack/core"
+require "gemstack/schema"
+
+require_relative "db/json_compat"
+require_relative "db/configuration"
+require_relative "db/schema_types"
+
+module GemStack
+  # SQL databases through Sequel: PostgreSQL, MySQL
+  # (mysql2 or trilogy) and SQLite, configured by config/database.yml or
+  # DATABASE_URL. Load it with `require "gemstack/db"` in config/app.rb and add the driver gem
+  # (pg, mysql2, trilogy or sqlite3) to the Gemfile — `gemstack new` does.
+  #
+  #   GemStack.db[:products].where(active: true).count     # the Sequel::Database
+  #   GemStack.transaction { order.save; payment.save }
+  module DB
+    class Config < Settings
+      # An explicit database URL; wins over DATABASE_URL and config/database.yml
+      # (see DB::Configuration). Test uses TEST_DATABASE_URL, never DATABASE_URL,
+      # so a development database from .env can't be wiped by the test suite.
+      setting :url, default: nil
+      # One connection per server thread by default (database.yml `pool:` wins).
+      setting :pool_size, default: lambda {
+        Integer(ENV.fetch("GEMSTACK_DB_POOL") { ENV.fetch("GEMSTACK_MAX_THREADS", 5) })
+      }
+      setting :pool_timeout, default: 5
+      setting :migrations_path, default: "db/migrations"
+      setting :seeds_path, default: "db/seeds.rb"
+      setting :log_queries, default: -> { GemStack.env.development? }
+      # Queries slower than this are logged at WARN in every environment.
+      setting :slow_query_ms, default: 500
+      # Server-side statement timeout in ms (nil = the database's default).
+      # PostgreSQL: statement_timeout; MySQL: max_execution_time (SELECTs); SQLite: none.
+      setting :statement_timeout, default: nil
+      # Sequel extensions to load; nil = pg_json + pg_array on PostgreSQL, none elsewhere.
+      setting :extensions, default: nil
+      # Extra options passed to Sequel.connect.
+      setting :options, default: {}
+    end
+
+    class RecordNotFound < NotFound; end
+
+    # Stored and compared in UTC on every adapter (MySQL DATETIME and SQLite
+    # text have no time zone); PostgreSQL timestamptz is unaffected.
+    Sequel.database_timezone = :utc
+
+    # Adapts Sequel's logging to the GemStack logger: SQL at DEBUG only when
+    # config.db.log_queries is on, slow queries at WARN, and failures of the
+    # existence probes Sequel runs on purpose (table_exists?, model setup
+    # before a migration) are not reported as errors.
+    class QueryLogger
+      PROBE = /: SELECT (?:NULL AS [`"']nil[`"'] FROM \S+ LIMIT 1|\* FROM \S+ LIMIT 0)\z/
+
+      def initialize(logger, queries:)
+        @logger = logger
+        @queries = queries
+      end
+
+      def debug(message) = (@logger.debug(message) if @queries)
+      def info(message) = @logger.info(message)
+      def warn(message) = @logger.warn(message)
+      def error(message) = (@logger.error(message) unless PROBE.match?(message.to_s))
+    end
+
+    @mutex = Mutex.new
+
+    class << self
+      def config = GemStack.config.db
+
+      def connection
+        @connection || @mutex.synchronize { @connection ||= connect }
+      end
+
+      def connected? = !@connection.nil?
+
+      # The resolved connection settings (a Hash; see DB::Configuration).
+      def settings = @settings ||= Configuration.resolve
+
+      # "postgres", "mysql2", "trilogy" or "sqlite".
+      def adapter = settings[:adapter]
+      def postgres?(db = nil) = type(db) == :postgres
+      def mysql?(db = nil) = type(db) == :mysql
+      def sqlite?(db = nil) = type(db) == :sqlite
+
+      # Sequel's database type (:postgres, :mysql, :sqlite) — from the
+      # connection when there is one, so no query is needed.
+      def type(db = nil)
+        db ||= @connection
+        return db.database_type if db
+
+        { "postgres" => :postgres, "mysql2" => :mysql, "trilogy" => :mysql, "sqlite" => :sqlite }.fetch(adapter)
+      end
+
+      # Builds the Sequel::Database. Connections are opened lazily, so an
+      # unavailable database doesn't prevent the application from booting.
+      def connect(target = settings)
+        target = Configuration.from_url(target, root: GemStack.config.root) if target.is_a?(String)
+        opts = target.except(:source)
+        options = { max_connections: opts.delete(:max_connections) || config.pool_size,
+                    pool_timeout: config.pool_timeout, test: false, keep_reference: false }
+        options.merge!(adapter_options(opts[:adapter], opts[:database]))
+        db = open_database(opts.merge(options).merge(config.options))
+        configure(db)
+        Sequel::Model.db = db
+        db
+      end
+
+      # Closes pooled connections (e.g. before Puma forks workers). The
+      # Database object stays in place and reconnects lazily: models hold a
+      # reference to it, so replacing it would split them from GemStack.db.
+      def disconnect
+        @connection&.disconnect
+      end
+
+      def transaction(**, &) = connection.transaction(**, &)
+
+      # Forgets the resolved settings and the connection (tests, console).
+      def reset!
+        @connection&.disconnect
+        @connection = nil
+        @settings = nil
+      end
+
+      # True when the table isn't there — one catalog query, nothing logged
+      # (Sequel's table_exists? probes with a failing SELECT).
+      def table_missing?(db, table)
+        name = table.to_s
+        case db.database_type
+        when :postgres then db.get(Sequel.function(:to_regclass, db.literal(table))).nil?
+        when :mysql
+          db[Sequel[:information_schema][:tables]].where(table_schema: Sequel.function(:database),
+                                                         table_name: name).empty?
+        when :sqlite then db[:sqlite_master].where(type: %w[table view], name: name).empty?
+        else !db.table_exists?(table)
+        end
+      end
+
+      private
+
+      def configure(db)
+        extensions = config.extensions || (postgres?(db) ? %i[pg_json pg_array] : [])
+        db.extension(*extensions) unless extensions.empty?
+        db.log_warn_duration = config.slow_query_ms / 1000.0 if config.slow_query_ms
+        db.loggers << QueryLogger.new(GemStack.logger, queries: config.log_queries)
+        db.sql_log_level = :debug
+      end
+
+      def open_database(options)
+        Sequel.connect(**options)
+      rescue Sequel::AdapterNotFound, LoadError => e
+        gem_name = Configuration::DRIVER_GEMS.fetch(options[:adapter], options[:adapter])
+        raise ConfigurationError, "#{options[:adapter]} needs gem \"#{gem_name}\" in the Gemfile (#{e.message})"
+      end
+
+      def adapter_options(adapter, database)
+        timeout = config.statement_timeout && Integer(config.statement_timeout)
+        case adapter
+        when "postgres" then timeout ? { connect_sqls: ["SET statement_timeout = #{timeout}"] } : {}
+        when "mysql2", "trilogy"
+          sqls = timeout ? ["SET SESSION max_execution_time = #{timeout}"] : []
+          { encoding: "utf8mb4", connect_sqls: sqls }
+        when "sqlite"
+          # Several Puma threads share the file: wait for the write lock instead
+          # of failing, and let readers work while one connection writes.
+          sqls = database == ":memory:" ? [] : ["PRAGMA journal_mode = WAL", "PRAGMA synchronous = NORMAL"]
+          { timeout: 5_000, connect_sqls: sqls }
+        else {}
+        end
+      end
+    end
+  end
+
+  # A model base class bound to an explicit table, like Sequel::Model(:table):
+  #   class Item < GemStack::Model(:inventory_items)
+  def self.Model(source) = Model.Model(source) # rubocop:disable Naming/MethodName
+
+  class << self
+    def db = DB.connection
+    def transaction(**, &) = DB.transaction(**, &)
+  end
+end
+
+require_relative "db/model"
+require_relative "db/errors"
+require_relative "db/migrator"
+require_relative "db/tasks"
+
+GemStack::Config.namespace(:db, GemStack::DB::Config)
+
+GemStack::Plugins.register(:db) do |app|
+  GemStack::DB.connection
+  app.on_shutdown { GemStack::DB.disconnect } if app.respond_to?(:on_shutdown)
+
+  # A friendly nudge in development; never blocks boot.
+  if GemStack.env.development?
+    begin
+      pending = GemStack::DB::Migrator.new.pending
+      unless pending.empty?
+        GemStack.logger.warn("#{pending.size} pending migration(s) — run `gemstack db:migrate`",
+                             first: pending.first.file)
+      end
+    rescue Sequel::Error
+      nil # database not reachable yet; requests will report it
+    end
+  end
+end

data/lib/gemstack/dev/file_watcher.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GemStack
+  module Dev
+    # Detects changes (edits, additions, deletions) in a set of glob patterns.
+    # Polling keeps it dependency-free and reliable across editors, containers
+    # and network filesystems; it is only used in development.
+    #
+    # Modification times are the cheap first check; a file whose mtime changed
+    # only counts as changed if its content digest changed too. Tools that
+    # rewrite files with identical content — Bundler 4 rewrites Gemfile.lock on
+    # every `bundle exec` — therefore don't trigger reloads or restarts.
+    class FileWatcher
+      Entry = Struct.new(:mtime, :bytes, :digest)
+
+      def initialize(patterns, root: Dir.pwd, exclude: [])
+        @patterns = Array(patterns)
+        @exclude = Array(exclude)
+        @root = root.to_s
+        @entries = scan({})
+      end
+
+      # True once per change: the new state becomes the baseline.
+      def changed?
+        current = scan(@entries)
+        changed = current.keys != @entries.keys ||
+                  current.any? { |path, entry| entry.digest != @entries[path].digest }
+        @entries = current
+        changed
+      end
+
+      def files
+        found = Dir.glob(@patterns, base: @root)
+        found.reject! { |file| @exclude.any? { |pattern| File.fnmatch?(pattern, file, File::FNM_PATHNAME) } }
+        found.sort
+      end
+
+      private
+
+      # Reuses the previous digest when mtime and size are unchanged.
+      def scan(previous)
+        files.each_with_object({}) do |file, entries|
+          path = File.join(@root, file)
+          stat = File.stat(path)
+          next if stat.directory?
+
+          old = previous[file]
+          same = old && old.mtime == stat.mtime && old.bytes == stat.size
+          entries[file] = Entry.new(stat.mtime, stat.size, same ? old.digest : Digest::SHA256.file(path).hexdigest)
+        rescue Errno::ENOENT
+          next
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/dev/gateway.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+module GemStack
+  module Dev
+    # The development gateway: one public origin in front of Next.js and the
+    # Ruby API.
+    #
+    # For each connection it reads only the request line and headers, picks
+    # an upstream by path (api_path → API, everything else → frontend), adds
+    # X-Forwarded-* headers and then copies raw bytes in both directions.
+    # Because it never interprets bodies, streaming responses, Server-Sent
+    # Events and WebSocket upgrades (Next.js HMR, realtime) just work.
+    #
+    # Each request gets its own upstream connection (`Connection: close`
+    # upstream), so routing stays correct per request without parsing
+    # response framing. That trade-off is fine on localhost and is the reason
+    # this gateway is for development only.
+    class Gateway
+      Upstream = Struct.new(:name, :host, :port, :label) do
+        def to_s = "#{host}:#{port}"
+      end
+
+      MAX_HEAD = 64 * 1024
+      CONNECT_TIMEOUT = 2
+      HOP_BY_HOP = %w[connection keep-alive proxy-connection].freeze
+      FORWARDED = %w[x-forwarded-for x-forwarded-proto x-forwarded-host x-forwarded-port].freeze
+
+      attr_reader :port
+      attr_accessor :api, :frontend
+
+      def initialize(port:, api_path:, api:, frontend: nil, bind: %w[127.0.0.1 ::1], on_error: nil)
+        @port = port
+        @api_path = api_path.to_s.chomp("/")
+        @api = api
+        @frontend = frontend
+        @bind = Array(bind)
+        @on_error = on_error
+        @servers = []
+        @threads = []
+      end
+
+      def start
+        @bind.each do |host|
+          server = listen(host)
+          next unless server
+
+          @port = server.addr[1] if @port.zero? # port 0: let the OS choose (tests)
+          @servers << server
+        end
+        raise Error, "could not listen on any of #{@bind.join(", ")}" if @servers.empty?
+
+        @threads = @servers.map { |server| Thread.new { accept_loop(server) } }
+        self
+      end
+
+      def stop
+        @servers.each { |server| server.close unless server.closed? }
+        @threads.each { |thread| thread.join(1) }
+        @servers.clear
+      end
+
+      def api_request?(path)
+        return true if @api_path.empty?
+
+        path == @api_path || path.start_with?("#{@api_path}/")
+      end
+
+      private
+
+      def listen(host)
+        TCPServer.new(host, @port)
+      rescue Errno::EADDRINUSE
+        stop
+        raise Error,
+              "port #{@port} is already in use on #{host}. Stop the other process or run PORT=#{@port + 1} gemstack dev"
+      rescue Errno::EADDRNOTAVAIL, Errno::EAFNOSUPPORT, SocketError
+        nil # e.g. no IPv6 loopback on this machine
+      end
+
+      def accept_loop(server)
+        loop do
+          client = server.accept
+          Thread.new(client) { |socket| handle(socket) }
+        end
+      rescue IOError, Errno::EBADF, Errno::EINVAL
+        nil # server closed
+      end
+
+      def handle(client)
+        head, rest = read_head(client)
+        return unless head
+
+        request_line, *header_lines = head.split("\r\n")
+        _method, target, = request_line.split(" ", 3)
+        return respond(client, 400, "text/plain", "Bad Request") unless target
+
+        path = target.sub(%r{\Ahttps?://[^/]+}i, "").split("?", 2).first
+        api = api_request?(path)
+        upstream = api ? @api : @frontend
+        return unavailable(client, api, header_lines, nil) unless upstream
+
+        server = connect(upstream)
+        return unavailable(client, api, header_lines, upstream) unless server
+
+        server.write("#{request_line}\r\n#{rewrite(header_lines, client).join("\r\n")}\r\n\r\n")
+        server.write(rest) unless rest.empty?
+        relay(client, server)
+      rescue IOError, SystemCallError
+        nil # client or upstream went away
+      rescue StandardError => e
+        @on_error&.call(e)
+      ensure
+        [client, server].each { |socket| socket&.close unless socket&.closed? }
+      end
+
+      def read_head(client)
+        buffer = String.new(encoding: Encoding::BINARY)
+        until (index = buffer.index("\r\n\r\n"))
+          return nil if buffer.bytesize > MAX_HEAD
+
+          buffer << client.readpartial(16 * 1024)
+        end
+        [buffer.byteslice(0, index), buffer.byteslice(index + 4, buffer.bytesize)]
+      rescue IOError, SystemCallError # EOFError is an IOError
+        nil
+      end
+
+      def rewrite(lines, client)
+        upgrade = upgrade?(lines)
+        host = nil
+        kept = lines.reject do |line|
+          name = line[/\A[^:]+/].to_s.strip.downcase
+          host = line.split(":", 2).last.strip if name == "host"
+          FORWARDED.include?(name) || (!upgrade && HOP_BY_HOP.include?(name))
+        end
+        kept << "Connection: close" unless upgrade
+        kept << "X-Forwarded-For: #{client_ip(client)}"
+        kept << "X-Forwarded-Proto: http"
+        kept << "X-Forwarded-Host: #{host}" if host
+        kept << "X-Forwarded-Port: #{@port}"
+      end
+
+      def upgrade?(lines)
+        connection = lines.find { |l| l.match?(/\Aconnection\s*:/i) }
+        connection&.match?(/upgrade/i) && lines.any? { |l| l.match?(/\Aupgrade\s*:/i) }
+      end
+
+      def client_ip(client)
+        client.remote_address.ip_address
+      rescue StandardError
+        "127.0.0.1"
+      end
+
+      def connect(upstream)
+        Socket.tcp(upstream.host, upstream.port, connect_timeout: CONNECT_TIMEOUT)
+      rescue SystemCallError, SocketError, IOError
+        nil
+      end
+
+      # Upstream → client on this thread; client → upstream on a helper
+      # thread. The exchange ends when the upstream closes (after its
+      # response, or when a WebSocket/stream ends).
+      def relay(client, server)
+        pump = Thread.new do
+          IO.copy_stream(client, server)
+          server.close_write
+        rescue IOError, SystemCallError
+          nil
+        end
+        IO.copy_stream(server, client)
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        pump&.kill
+      end
+
+      def unavailable(client, api, header_lines, upstream)
+        name = api ? "Ruby API" : "Next.js"
+        state = upstream ? "is starting or not running" : "is not configured"
+        message = "#{name} #{state}. Check the terminal running `gemstack dev`."
+        if api
+          body = JSON.generate(error: { code: "upstream_unavailable", message: message })
+          respond(client, 503, "application/json", body)
+        elsif header_lines.any? { |l| l.match?(%r{\Aaccept\s*:.*text/html}i) }
+          respond(client, 503, "text/html; charset=utf-8", waiting_page(name, message, refresh: !upstream.nil?))
+        else
+          respond(client, 503, "text/plain", message)
+        end
+      end
+
+      def respond(client, status, type, body)
+        reason = { 400 => "Bad Request", 503 => "Service Unavailable" }.fetch(status, "Error")
+        client.write("HTTP/1.1 #{status} #{reason}\r\ncontent-type: #{type}\r\ncontent-length: #{body.bytesize}\r\n" \
+                     "cache-control: no-store\r\nretry-after: 1\r\nconnection: close\r\n\r\n#{body}")
+      end
+
+      def waiting_page(name, message, refresh:)
+        <<~HTML
+          <!doctype html>
+          <html lang="en"><head><meta charset="utf-8"><title>GemStack · #{name}</title>
+          #{'<meta http-equiv="refresh" content="1">' if refresh}
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <style>
+            body{font:16px/1.5 system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0;
+                 background:#0b0d12;color:#e6e8ee}
+            main{max-width:32rem;padding:2rem;text-align:center}
+            .dot{display:inline-block;width:.6rem;height:.6rem;border-radius:50%;background:#f5b041;
+                 margin-right:.5rem;animation:p 1s infinite alternate}
+            @keyframes p{to{opacity:.3}} code{background:#1c2030;padding:.1rem .35rem;border-radius:4px}
+          </style></head>
+          <body><main><h1>GemStack</h1><p><span class="dot"></span>#{message.sub(/`([^`]+)`/, '<code>\1</code>')}</p>
+          <p style="color:#8a90a2">#{"This page refreshes automatically." if refresh}</p></main></body></html>
+        HTML
+      end
+    end
+  end
+end

data/lib/gemstack/dev/managed_process.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # A child process whose output is streamed, line by line, to a Terminal.
+    # Each child runs in its own process group so stopping it also stops
+    # anything it spawned (e.g. npm → node).
+    class ManagedProcess
+      attr_reader :name, :command, :pid, :status
+
+      def initialize(name, command, terminal:, env: {}, chdir: Dir.pwd)
+        @name = name
+        @command = Array(command)
+        @terminal = terminal
+        @env = env
+        @chdir = chdir.to_s
+        @pid = nil
+        @status = nil
+      end
+
+      def start
+        reader, writer = IO.pipe
+        @status = nil
+        @pid = Process.spawn(@env, *@command, chdir: @chdir, out: writer, err: writer, in: File::NULL,
+                                              pgroup: true)
+        writer.close
+        @output = Thread.new do
+          reader.each_line { |line| @terminal.line(@name, line) }
+        rescue IOError
+          nil
+        ensure
+          reader.close
+        end
+        self
+      rescue SystemCallError => e
+        writer&.close
+        reader&.close
+        @terminal.line(@name, "could not start `#{@command.join(" ")}`: #{e.message}")
+        @status = :failed_to_start
+        self
+      end
+
+      # Non-blocking. Records the exit status once the process has exited.
+      def running?
+        return false unless @pid
+        return false if @status
+
+        done = Process.waitpid2(@pid, Process::WNOHANG)
+        return true unless done
+
+        @status = done[1]
+        false
+      rescue Errno::ECHILD
+        @status ||= :unknown
+        false
+      end
+
+      def exited? = !@status.nil?
+
+      def stop(timeout: 5)
+        return unless running?
+
+        signal("TERM")
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        sleep 0.05 while running? && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        signal("KILL") if running?
+        running?
+        @output&.join(1)
+      end
+
+      def restart
+        stop
+        start
+      end
+
+      def describe_status
+        case @status
+        when Process::Status then @status.signaled? ? "signal #{@status.termsig}" : "status #{@status.exitstatus}"
+        else @status.to_s
+        end
+      end
+
+      private
+
+      def signal(name)
+        Process.kill(name, -@pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        begin
+          Process.kill(name, @pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/dev/ports.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module GemStack
+  module Dev
+    module Ports
+      module_function
+
+      # An unused TCP port on host, chosen by the OS.
+      def free(host = "127.0.0.1")
+        server = TCPServer.new(host, 0)
+        server.addr[1]
+      ensure
+        server&.close
+      end
+
+      def open?(host, port, timeout: 0.5)
+        Socket.tcp(host, port, connect_timeout: timeout).close
+        true
+      rescue SystemCallError, SocketError, IOError
+        false
+      end
+    end
+  end
+end