goldlapel 0.0.1.pre.rc1-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a2ede97de5a466d34bef7406ef0d4891eb085b2c826a9b471287323ee07e44b
+  data.tar.gz: c6e806544b943d0addb3bd921a31f4deea2c0af36f3e8d0693d66bea0510af22
+SHA512:
+  metadata.gz: '0368b6e9ca5dc6685d34df7d4f28d51df78cf85f85b58f964541bc70baa07b107de4bca9d71ee4141ad5702e434c50d3fc6addc6165d2b0efb8d423049f67b73'
+  data.tar.gz: d844fe2fb94bc4071cef2764be5f50c936cbc31a35d47d634ec32a1cca593de09d86f1255d2ec9dd8f788d19c06fbc51673e36d69a2bf2e36578be9da9c55439

data/README.md

@@ -0,0 +1,116 @@
+# Gold Lapel
+
+Self-optimizing Postgres proxy — automatic materialized views and indexes. Zero code changes required.
+
+Gold Lapel sits between your app and Postgres, watches query patterns, and automatically creates materialized views and indexes to make your database faster. Port 7932 (79 = atomic number for gold, 32 from Postgres).
+
+## Install
+
+```bash
+gem install goldlapel
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "goldlapel"
+```
+
+## Quick Start
+
+```ruby
+require "goldlapel"
+
+# Start the proxy — returns a connection string pointing at Gold Lapel
+url = GoldLapel.start("postgresql://user:pass@localhost:5432/mydb")
+
+# Use the URL with any Postgres driver
+require "pg"
+conn = PG.connect(url)
+
+# Or Sequel, ActiveRecord, ROM — anything that speaks Postgres
+```
+
+Gold Lapel is driver-agnostic. `start` returns a connection string (`postgresql://...@localhost:7932/...`) that works with any Postgres driver or ORM.
+
+## API
+
+### `GoldLapel.start(upstream, port: nil, config: {}, extra_args: [])`
+
+Starts the Gold Lapel proxy and returns the proxy connection string.
+
+- `upstream` — your Postgres connection string (e.g. `postgresql://user:pass@localhost:5432/mydb`)
+- `port` — proxy port (default: 7932)
+- `config` — configuration hash (see [Configuration](#configuration) below)
+- `extra_args` — additional CLI flags passed to the binary (e.g. `["--threshold-impact", "5000"]`)
+
+### `GoldLapel.stop`
+
+Stops the proxy. Also called automatically on process exit.
+
+### `GoldLapel.proxy_url`
+
+Returns the current proxy URL, or `nil` if not running.
+
+### `GoldLapel.dashboard_url`
+
+Returns the dashboard URL (e.g. `http://127.0.0.1:7933`), or `nil` if not running. The dashboard port defaults to 7933 and can be configured via `config: { dashboard_port: 9090 }` or disabled with `dashboard_port: 0`.
+
+### `GoldLapel.config_keys`
+
+Returns an array of all valid configuration key names (as strings).
+
+### `GoldLapel::Proxy.new(upstream, port: nil, config: {}, extra_args: [])`
+
+Class interface for managing multiple instances:
+
+```ruby
+proxy = GoldLapel::Proxy.new("postgresql://user:pass@localhost:5432/mydb", port: 7932)
+url = proxy.start
+# ...
+proxy.stop
+```
+
+## Configuration
+
+Pass a config hash to configure the proxy:
+
+```ruby
+require "goldlapel"
+
+url = GoldLapel.start("postgresql://user:pass@localhost/mydb", config: {
+  mode: "butler",
+  pool_size: 50,
+  disable_matviews: true,
+  replica: ["postgresql://user:pass@replica1/mydb"],
+})
+```
+
+Keys use `snake_case` (symbols or strings) and map to CLI flags (`pool_size` -> `--pool-size`). Boolean keys are flags -- `true` enables them. Array keys produce repeated flags.
+
+Unknown keys raise `ArgumentError`. To see all valid keys:
+
+```ruby
+GoldLapel.config_keys
+```
+
+For the full configuration reference, see the [main documentation](https://github.com/goldlapel/goldlapel#setting-reference).
+
+You can also pass raw CLI flags via `extra_args`, or set environment variables (`GOLDLAPEL_PORT`, `GOLDLAPEL_UPSTREAM`, etc.) -- the binary reads them automatically.
+
+## How It Works
+
+This gem bundles the Gold Lapel Rust binary for your platform. When you call `start`, it:
+
+1. Locates the binary (bundled in gem, on PATH, or via `GOLDLAPEL_BINARY` env var)
+2. Spawns it as a subprocess listening on localhost
+3. Waits for the port to be ready
+4. Returns a connection string pointing at the proxy
+5. Cleans up automatically on process exit
+
+The binary does all the work — this wrapper just manages its lifecycle.
+
+## Links
+
+- [Website](https://goldlapel.com)
+- [Documentation](https://github.com/goldlapel/goldlapel)

data/lib/goldlapel/proxy.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+require "rbconfig"
+
+module GoldLapel
+  DEFAULT_PORT = 7932
+  DEFAULT_DASHBOARD_PORT = 7933
+  STARTUP_TIMEOUT = 10.0
+  STARTUP_POLL_INTERVAL = 0.05
+
+  class Proxy
+    attr_reader :url, :upstream, :dashboard_url
+
+    VALID_CONFIG_KEYS = %w[
+      mode min_pattern_count refresh_interval_secs pattern_ttl_secs
+      max_tables_per_view max_columns_per_view deep_pagination_threshold
+      report_interval_secs result_cache_size batch_cache_size
+      batch_cache_ttl_secs redis_url pool_size pool_timeout_secs
+      pool_mode mgmt_idle_timeout fallback read_after_write_secs
+      n1_threshold n1_window_ms n1_cross_threshold
+      tls_cert tls_key tls_client_ca config dashboard_port
+      disable_matviews disable_consolidation disable_btree_indexes
+      disable_trigram_indexes disable_expression_indexes
+      disable_partial_indexes disable_rewrite disable_prepared_cache
+      disable_result_cache disable_redis_cache disable_pool
+      disable_n1 disable_n1_cross_connection disable_shadow_mode
+      enable_coalescing replica exclude_tables
+    ].freeze
+
+    BOOLEAN_KEYS = %w[
+      disable_matviews disable_consolidation disable_btree_indexes
+      disable_trigram_indexes disable_expression_indexes
+      disable_partial_indexes disable_rewrite disable_prepared_cache
+      disable_result_cache disable_redis_cache disable_pool
+      disable_n1 disable_n1_cross_connection disable_shadow_mode
+      enable_coalescing
+    ].freeze
+
+    LIST_KEYS = %w[
+      replica exclude_tables
+    ].freeze
+
+    def self.config_keys
+      VALID_CONFIG_KEYS.dup
+    end
+
+    def self.config_to_args(config)
+      return [] if config.nil? || config.empty?
+
+      args = []
+      config.each do |key, value|
+        key = key.to_s
+        unless VALID_CONFIG_KEYS.include?(key)
+          raise ArgumentError, "Unknown config key: #{key}"
+        end
+
+        flag = "--#{key.tr('_', '-')}"
+
+        if BOOLEAN_KEYS.include?(key)
+          unless value == true || value == false
+            raise TypeError, "Config key '#{key}' expects a boolean, got #{value.class}"
+          end
+          args << flag if value
+        elsif LIST_KEYS.include?(key)
+          Array(value).each do |item|
+            args.push(flag, item.to_s)
+          end
+        else
+          args.push(flag, value.to_s)
+        end
+      end
+      args
+    end
+
+    def initialize(upstream, port: nil, config: {}, extra_args: [])
+      @upstream = upstream
+      @port = port || DEFAULT_PORT
+      @config = config
+      @extra_args = extra_args
+      @pid = nil
+      @url = nil
+      @dashboard_url = nil
+      @stderr_reader = nil
+
+      @dashboard_port = if config.key?(:dashboard_port) || config.key?("dashboard_port")
+        config.fetch(:dashboard_port, config.fetch("dashboard_port", DEFAULT_DASHBOARD_PORT)).to_i
+      else
+        DEFAULT_DASHBOARD_PORT
+      end
+    end
+
+    def start
+      return @url if running?
+
+      binary = self.class.find_binary
+      cmd = [
+        binary,
+        "--upstream", @upstream,
+        "--port", @port.to_s,
+        *self.class.config_to_args(@config),
+        *@extra_args,
+      ]
+
+      stdin, stdout, stderr, wait_thr = Open3.popen3(*cmd)
+      stdin.close
+      stdout.close
+      @pid = wait_thr.pid
+      @stderr_reader = stderr
+      @wait_thr = wait_thr
+
+      unless self.class.wait_for_port("127.0.0.1", @port, STARTUP_TIMEOUT)
+        Process.kill("KILL", @pid) rescue Errno::ESRCH
+        @wait_thr.join rescue nil
+        stderr_output = stderr.read
+        stderr.close
+        @pid = nil
+        @wait_thr = nil
+        @stderr_reader = nil
+        raise "Gold Lapel failed to start on port #{@port} " \
+              "within #{STARTUP_TIMEOUT}s.\nstderr: #{stderr_output}"
+      end
+
+      @stderr_reader.close
+      @stderr_reader = nil
+      @url = self.class.make_proxy_url(@upstream, @port)
+      @dashboard_url = @dashboard_port > 0 ? "http://127.0.0.1:#{@dashboard_port}" : nil
+
+      if @dashboard_port > 0
+        puts "goldlapel → :#{@port} (proxy) | http://127.0.0.1:#{@dashboard_port} (dashboard)"
+      else
+        puts "goldlapel → :#{@port} (proxy)"
+      end
+
+      @url
+    end
+
+    def stop
+      if @pid
+        begin
+          Process.kill("TERM", @pid)
+          unless @wait_thr.join(5)
+            Process.kill("KILL", @pid) rescue Errno::ESRCH
+            @wait_thr.join(5) rescue nil
+          end
+        rescue Errno::ESRCH
+          # Process already exited
+        end
+        @stderr_reader&.close rescue IOError
+        @pid = nil
+        @url = nil
+        @dashboard_url = nil
+        @wait_thr = nil
+        @stderr_reader = nil
+      end
+    end
+
+    def running?
+      return false unless @pid
+      Process.kill(0, @pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    # --- Class-level helpers ---
+
+    def self.find_binary
+      # 1. Explicit override via env var
+      env_path = ENV["GOLDLAPEL_BINARY"]
+      if env_path
+        return env_path if File.file?(env_path)
+        raise "GOLDLAPEL_BINARY points to #{env_path} but file not found"
+      end
+
+      # 2. Bundled binary (inside the installed gem)
+      system_name = case RbConfig::CONFIG["host_os"]
+                    when /linux/i then "linux"
+                    when /darwin/i then "darwin"
+                    when /mswin|mingw|cygwin/i then "windows"
+                    else RbConfig::CONFIG["host_os"]
+                    end
+      machine = RbConfig::CONFIG["host_cpu"]
+      arch = case machine
+             when /x86_64|amd64/i then "x86_64"
+             when /arm64|aarch64/i then "aarch64"
+             else machine
+             end
+
+      binary_name = "goldlapel-#{system_name}-#{arch}"
+      binary_name += ".exe" if system_name == "windows"
+      bundled = File.join(__dir__, "..", "..", "bin", binary_name)
+      return bundled if File.file?(bundled)
+
+      # 3. On PATH
+      on_path = which("goldlapel")
+      return on_path if on_path
+
+      raise "Gold Lapel binary not found. Set GOLDLAPEL_BINARY env var, " \
+            "install the platform-specific package, or ensure 'goldlapel' is on PATH."
+    end
+
+    def self.make_proxy_url(upstream, port)
+      # pg URL with explicit port
+      if upstream =~ /\A(postgres(?:ql)?:\/\/(?:.*@)?)([^:\/?#]+):(\d+)(.*)\z/
+        return "#{$1}localhost:#{port}#{$4}"
+      end
+      # pg URL without port
+      if upstream =~ /\A(postgres(?:ql)?:\/\/(?:.*@)?)([^:\/?#]+)(.*)\z/
+        return "#{$1}localhost:#{port}#{$3}"
+      end
+      # bare host:port (guard against scheme colons)
+      if !upstream.include?("://") && upstream.include?(":")
+        return "localhost:#{port}"
+      end
+      # bare host
+      "localhost:#{port}"
+    end
+
+    def self.wait_for_port(host, port, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        begin
+          sock = TCPSocket.new(host, port)
+          sock.close
+          return true
+        rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EHOSTUNREACH
+          sleep STARTUP_POLL_INTERVAL
+        end
+      end
+      false
+    end
+
+    # Module-level singleton
+    @instance = nil
+    @cleanup_registered = false
+
+    class << self
+      def start(upstream, port: nil, config: {}, extra_args: [])
+        if @instance&.running?
+          if @instance.upstream != upstream
+            raise "Gold Lapel is already running for a different upstream. " \
+                  "Call GoldLapel.stop before starting with a new upstream."
+          end
+          return @instance.url
+        end
+
+        @instance = Proxy.new(upstream, port: port, config: config, extra_args: extra_args)
+        unless @cleanup_registered
+          at_exit { cleanup }
+          @cleanup_registered = true
+        end
+        @instance.start
+      end
+
+      def stop
+        if @instance
+          @instance.stop
+          @instance = nil
+        end
+      end
+
+      def proxy_url
+        @instance&.url
+      end
+
+      def dashboard_url
+        @instance&.dashboard_url
+      end
+
+      private
+
+      def cleanup
+        if @instance
+          @instance.stop
+          @instance = nil
+        end
+      end
+
+      def which(cmd)
+        exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+        (ENV["PATH"] || "").split(File::PATH_SEPARATOR).each do |path|
+          exts.each do |ext|
+            full = File.join(path, "#{cmd}#{ext}")
+            return full if File.executable?(full) && File.file?(full)
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/goldlapel.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "goldlapel/proxy"
+
+module GoldLapel
+  # Module-level convenience methods (singleton pattern)
+  def self.start(upstream, port: nil, config: {}, extra_args: [])
+    Proxy.start(upstream, port: port, config: config, extra_args: extra_args)
+  end
+
+  def self.stop
+    Proxy.stop
+  end
+
+  def self.proxy_url
+    Proxy.proxy_url
+  end
+
+  def self.dashboard_url
+    Proxy.dashboard_url
+  end
+
+  def self.config_keys
+    Proxy.config_keys
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: goldlapel
+version: !ruby/object:Gem::Version
+  version: 0.0.1.pre.rc1
+platform: aarch64-linux
+authors:
+- Stephen Gibson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-15 00:00:00.000000000 Z
+dependencies: []
+description: Gold Lapel sits between your app and Postgres, watches query patterns,
+  and automatically creates materialized views and indexes to make your database faster.
+  Zero code changes required.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/goldlapel-linux-aarch64
+- lib/goldlapel.rb
+- lib/goldlapel/proxy.rb
+homepage: https://goldlapel.com
+licenses:
+- Proprietary
+metadata:
+  homepage_uri: https://goldlapel.com
+  source_code_uri: https://github.com/goldlapel/goldlapel-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Self-optimizing Postgres proxy — automatic materialized views and indexes
+test_files: []