ask-local 0.1.0

data/lib/ask/local/resolver.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    # Resolve the effective {app, service, variant, tlds} for a directory.
+    #
+    # Precedence per axis: CLI flag > ENV > ask-local.json > inference.
+    # Variant adds linked-worktree branch and opt-in current branch.
+    module Resolver
+      module_function
+
+      Result = Struct.new(:app, :service, :variant, :tlds, :sources, keyword_init: true)
+
+      def resolve(dir = Dir.pwd, name: nil, service: nil, variant: nil,
+        tlds: nil, use_branch: false)
+        config, config_dir = find_config(dir)
+        app_cfg = config ? config.app_config(dir) : {}
+        config_source = config_dir ? "ask-local.json (#{relative_label(config_dir, dir)})" : "ask-local.json"
+
+        app, app_source = first_present(
+          [name, "flag"],
+          [ENV["ASK_LOCAL_NAME"], "ASK_LOCAL_NAME"],
+          [app_cfg["name"], config_source],
+          [Inference.infer(dir), :infer]
+        )
+        app, app_source = app_source == :infer ? app : [app, app_source]
+
+        service, service_source = first_present(
+          [service, "flag"],
+          [ENV["ASK_LOCAL_SERVICE"], "ASK_LOCAL_SERVICE"],
+          [app_cfg["service"], config_source]
+        )
+
+        variant_value, variant_source = if !variant.nil? || ENV["ASK_LOCAL_VARIANT"] || app_cfg["variant"]
+          first_present(
+            [variant, "flag"],
+            [ENV["ASK_LOCAL_VARIANT"], "ASK_LOCAL_VARIANT"],
+            [app_cfg["variant"], config_source]
+          )
+        else
+          Variant.resolve(dir, use_branch: use_branch) || [nil, nil]
+        end
+
+        tld_list = parse_tlds(tlds) || parse_tlds(ENV["ASK_LOCAL_TLD"]) ||
+          Array(app_cfg["tlds"]) || [Hostname::DEFAULT_TLD]
+        tld_list = [Hostname::DEFAULT_TLD] if tld_list.empty?
+        tld_list.each do |tld|
+          raise ConfigError, "Invalid TLD #{tld.inspect}" unless Sanitize.valid_tld?(tld.downcase)
+        end
+        tld_list = tld_list.map(&:downcase).uniq
+
+        Result.new(
+          app: Sanitize.hostname_label(app),
+          service: service && Sanitize.hostname_label(service),
+          variant: variant_value && Sanitize.hostname_label(variant_value),
+          tlds: tld_list,
+          sources: { app: app_source, service: service_source, variant: variant_source }
+        )
+      end
+
+      def hostnames(result)
+        Hostname.build(app: result.app, service: result.service,
+          variant: result.variant, tlds: result.tlds)
+      end
+
+      # Walk up for the nearest ask-local.json; a root with an "apps" map
+      # covers subdirectories (monorepo). A nearer config without a match
+      # does not block a farther one with an apps entry.
+      def find_config(dir)
+        current = File.expand_path(dir)
+        fallback = nil
+        loop do
+          begin
+            loaded = Config.load(current)
+            if loaded
+              if loaded.data["apps"].is_a?(Hash)
+                return [loaded, current]
+              else
+                fallback ||= [loaded, current]
+              end
+            end
+          rescue ConfigError
+            nil
+          end
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+        fallback || [nil, nil]
+      end
+
+      def relative_label(config_dir, dir)
+        return "." if File.expand_path(config_dir) == File.expand_path(dir)
+
+        require "pathname"
+        Pathname.new(File.expand_path(dir))
+          .relative_path_from(Pathname.new(File.expand_path(config_dir))).to_s
+      rescue ArgumentError
+        "."
+      end
+
+      # NOTE: no `private` keyword here — it would cancel
+      # `module_function` mode (see Variant for details).
+      def first_present(*pairs)
+        pairs.each do |value, source|
+          if source == :infer
+            inferred, from = value
+            return [inferred, from] unless inferred.nil? || inferred.to_s.empty?
+          elsif !value.nil? && !value.to_s.strip.empty?
+            return [value.to_s.strip, source]
+          end
+        end
+        [nil, nil]
+      end
+
+      def parse_tlds(value)
+        return nil if value.nil?
+        return value.map(&:to_s) if value.is_a?(Array)
+
+        parts = value.to_s.split(",").map(&:strip).reject(&:empty?)
+        parts.empty? ? nil : parts
+      end
+    end
+  end
+end

data/lib/ask/local/route_store.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Ask
+  module Local
+    # Persistent hostname -> backend mapping in ~/.ask-local/routes.json.
+    #
+    # Entries: {hostname, target, kind, pid} where target is a unix socket
+    # path (kind "socket") or "127.0.0.1:PORT" (kind "tcp"), and pid 0
+    # marks a static alias. Guarded by flock; stale PIDs pruned on read.
+    # Modeled on portless RouteStore and puma-dev's AppPool registry.
+    class RouteStore
+      FILE_MODE = 0o644
+      DIR_MODE = 0o755
+
+      attr_reader :dir, :routes_path, :pid_path, :port_path
+
+      def initialize(dir, on_warning: nil)
+        @dir = dir
+        @routes_path = File.join(dir, "routes.json")
+        @pid_path = File.join(dir, "proxy.pid")
+        @port_path = File.join(dir, "proxy.port")
+        @on_warning = on_warning
+      end
+
+      def ensure_dir
+        FileUtils.mkdir_p(dir, mode: DIR_MODE)
+        File.chmod(DIR_MODE, dir)
+        Ownership.fix(dir)
+      rescue SystemCallError
+        nil
+      end
+
+      def with_lock
+        ensure_dir
+        File.open("#{routes_path}.lock", File::CREAT | File::RDWR, FILE_MODE) do |f|
+          f.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def load_routes(prune: false)
+        return [] unless File.file?(routes_path)
+
+        parsed = JSON.parse(File.read(routes_path))
+        unless parsed.is_a?(Array)
+          @on_warning&.call("Corrupted routes file (expected array): #{routes_path}")
+          return []
+        end
+        routes = parsed.select { |r| valid_route?(r) }
+        alive = routes.select { |r| r["pid"] == 0 || alive?(r["pid"]) }
+        save_routes(alive) if prune && alive.length != routes.length
+        alive
+      rescue JSON::ParserError
+        @on_warning&.call("Corrupted routes file (invalid JSON): #{routes_path}")
+        []
+      rescue SystemCallError
+        []
+      end
+
+      def load_routes_raw
+        return [] unless File.file?(routes_path)
+
+        parsed = JSON.parse(File.read(routes_path))
+        parsed.is_a?(Array) ? parsed.select { |r| valid_route?(r) } : []
+      rescue JSON::ParserError, SystemCallError
+        []
+      end
+
+      # Returns killed pid when force takes over a live route.
+      # `spec` marks daemon-supervised managed apps ({dir: ...}); the
+      # proxy supervisor may idle-kill and boot-on-request those backends.
+      def add_route(hostname, target, pid, kind:, force: false, spec: nil)
+        killed = nil
+        with_lock do
+          routes = load_routes(prune: true)
+          existing = routes.find { |r| r["hostname"] == hostname }
+          if existing && existing["pid"] != pid && alive?(existing["pid"])
+            raise RouteConflictError.new(hostname, existing["pid"]) unless force
+
+            begin
+              Process.kill("TERM", existing["pid"])
+              killed = existing["pid"]
+            rescue SystemCallError
+              nil
+            end
+          end
+          routes.reject! { |r| r["hostname"] == hostname }
+          entry = { "hostname" => hostname, "target" => target, "kind" => kind, "pid" => pid }
+          entry["spec"] = spec if spec
+          routes << entry
+          save_routes(routes)
+        end
+        killed
+      end
+
+      def remove_route(hostname, owner_pid: nil)
+        with_lock do
+          routes = load_routes(prune: true)
+          routes.reject! do |r|
+            r["hostname"] == hostname && (owner_pid.nil? || r["pid"] == owner_pid)
+          end
+          save_routes(routes)
+        end
+      end
+
+      def prune_stale
+        stale = []
+        with_lock do
+          all = load_routes_raw
+          alive, dead = all.partition { |r| r["pid"] == 0 || alive?(r["pid"]) }
+          stale = dead
+          save_routes(alive) unless dead.empty?
+        end
+        stale
+      end
+
+      def find(hostname)
+        load_routes.find { |r| r["hostname"] == hostname }
+      end
+
+      private
+
+      def valid_route?(value)
+        value.is_a?(Hash) &&
+          value["hostname"].is_a?(String) &&
+          value["target"].is_a?(String) &&
+          value["pid"].is_a?(Integer) &&
+          (value["spec"].nil? || (value["spec"].is_a?(Hash) && value["spec"]["dir"].is_a?(String)))
+      end
+
+      def save_routes(routes)
+        File.write(routes_path, JSON.pretty_generate(routes))
+        File.chmod(FILE_MODE, routes_path)
+        Ownership.fix(routes_path)
+      rescue SystemCallError
+        nil
+      end
+
+      def alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/ask/local/runner.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "socket"
+
+module Ask
+  module Local
+    # Boots and supervises one app backend.
+    #
+    # Managed Ruby apps (Rails/Rack with puma available): puma bound to a
+    # unix socket — zero TCP ports, readiness by dialing the socket
+    # (puma-dev model). Without puma, managed degrades to rackup on TCP
+    # (run-mode shape). Run mode (everything else): subprocess with
+    # injected PORT/ASK_LOCAL_URL, readiness by TCP connect.
+    class Runner
+      SOCKET_DIR = File.join("tmp", "sockets")
+      SOCKET_NAME = "ask-local.sock"
+
+      App = Struct.new(:name, :hostname, :url, :pid, :target, :kind,
+        :command, keyword_init: true)
+
+      def initialize(store:, on_log: nil)
+        @store = store
+        @on_log = on_log || ->(msg) { puts msg }
+      end
+
+      # Boot a managed Rack app. Socket when puma exists, else TCP rackup.
+      def boot_managed(name:, hostname:, url:, dir:, force: false)
+        if puma_available?(dir)
+          boot_socket(name: name, hostname: hostname, url: url, dir: dir, force: force)
+        else
+          boot_tcp_fallback(name: name, hostname: hostname, url: url, dir: dir, force: force)
+        end
+      end
+
+      # Boot a backend for an existing route (daemon supervisor). Does not
+      # re-register the route — target path is deterministic
+      # (dir/tmp/sockets/ask-local.sock) and the route entry stays.
+      def boot_supervised(name:, hostname:, url:, dir:)
+        socket_path = File.expand_path(File.join(dir, SOCKET_DIR, SOCKET_NAME))
+        FileUtils.mkdir_p(File.dirname(socket_path))
+        FileUtils.rm_f(socket_path)
+        pid = spawn_socket(dir, socket_path, name, url)
+        unless wait_for_socket(socket_path, timeout: 60)
+          stop_pid(pid)
+          raise Error, "App '#{name}' did not boot within 60s. " \
+            "Last log lines (#{log_path(dir, name)}):\n#{log_tail(log_path(dir, name))}"
+        end
+        write_backend_pid(hostname, pid)
+        App.new(name: name, hostname: hostname, url: url, pid: pid,
+          target: socket_path, kind: "socket", command: nil)
+      end
+
+      def boot_socket(name:, hostname:, url:, dir:, force: false)
+        socket_path = File.expand_path(File.join(dir, SOCKET_DIR, SOCKET_NAME))
+        FileUtils.mkdir_p(File.dirname(socket_path))
+        FileUtils.rm_f(socket_path)
+        pid = spawn_socket(dir, socket_path, name, url)
+
+        unless wait_for_socket(socket_path, timeout: 60)
+          stop_pid(pid)
+          raise Error, "App '#{name}' did not boot within 60s. " \
+            "Last log lines (#{log_path(dir, name)}):\n#{log_tail(log_path(dir, name))}"
+        end
+
+        @store.add_route(hostname, socket_path, Process.pid, kind: "socket",
+          force: force, spec: { "dir" => dir })
+        write_backend_pid(hostname, pid)
+        App.new(name: name, hostname: hostname, url: url, pid: pid,
+          target: socket_path, kind: "socket", command: socket_command(dir, socket_path))
+      end
+
+      def boot_tcp_fallback(name:, hostname:, url:, dir:, force: false)
+        port = Ports.find_free
+        env = child_env(dir, url: url, port: port)
+        config_ru = File.join(dir, "config.ru")
+        cmd = ["rackup", "-o", "127.0.0.1", "-p", port.to_s, config_ru]
+        pid = with_clean_env { spawn(env, *cmd, chdir: dir, out: log_path(dir, name), err: [:child, :out]) }
+        Process.detach(pid)
+        unless wait_for_tcp(port, timeout: 60)
+          stop_pid(pid)
+          raise Error, "App '#{name}' did not boot within 60s. " \
+            "Last log lines (#{log_path(dir, name)}):\n#{log_tail(log_path(dir, name))}"
+        end
+        target = "127.0.0.1:#{port}"
+        @store.add_route(hostname, target, Process.pid, kind: "tcp", force: force)
+        write_backend_pid(hostname, pid)
+        App.new(name: name, hostname: hostname, url: url, pid: pid,
+          target: target, kind: "tcp", command: cmd)
+      end
+
+      # Run an arbitrary command with PORT + ASK_LOCAL_URL. Returns App.
+      def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false)
+        port ||= Ports.find_free
+        env = child_env(dir, url: url, port: port)
+        pid = with_clean_env { spawn(env, *command, chdir: dir) }
+        Process.detach(pid)
+        target = "127.0.0.1:#{port}"
+        @store.add_route(hostname, target, Process.pid, kind: "tcp", force: force)
+        write_backend_pid(hostname, pid)
+        App.new(name: name, hostname: hostname, url: url, pid: pid,
+          target: target, kind: "tcp", command: command)
+      end
+
+      def child_env(dir, url:, port:)
+        env = { "ASK_LOCAL_URL" => url }
+        env["PORT"] = port.to_s if port
+        env["HOST"] = "127.0.0.1"
+        ca = File.join(Certs.state_dir, "ca.pem")
+        env["NODE_EXTRA_CA_CERTS"] = ca if File.file?(ca)
+        env
+      end
+
+      def puma_available?(dir)
+        with_clean_env { bundle_puma?(dir) || system_puma? }
+      end
+
+      # Spawned backends must not inherit our own bundle: under
+      # `bundle exec` rubygems restricts executables to the Gemfile,
+      # hiding system puma/rackup from the child. Strip Bundler env so
+      # the app boots with its own gems.
+      def with_clean_env(&block)
+        if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+          Bundler.with_unbundled_env(&block)
+        else
+          saved = {}
+          %w[BUNDLE_GEMFILE RUBYOPT RUBYLIB GEM_HOME GEM_PATH].each do |k|
+            saved[k] = ENV.delete(k)
+          end
+          begin
+            yield
+          ensure
+            saved.each { |k, v| ENV[k] = v unless v.nil? }
+          end
+        end
+      end
+
+      private
+
+      def socket_command(dir, socket_path)
+        socket = "unix://#{socket_path}"
+        config_ru = File.join(dir, "config.ru")
+        # Puma 8 takes config.ru positionally (no --rackup flag).
+        if bundle_puma?(dir)
+          ["bundle", "exec", "puma", "-b", socket, config_ru]
+        else
+          ["puma", "-b", socket, config_ru]
+        end
+      end
+
+      # Shared spawn for CLI boots and daemon supervision.
+      def spawn_socket(dir, socket_path, name, url)
+        env = child_env(dir, url: url, port: nil)
+        cmd = socket_command(dir, socket_path)
+        pid = with_clean_env { spawn(env, *cmd, chdir: dir, out: log_path(dir, name), err: [:child, :out]) }
+        Process.detach(pid)
+        pid
+      end
+
+      def bundle_puma?(dir)
+        gemfile = File.join(dir, "Gemfile")
+        return false unless File.file?(gemfile)
+
+        out, status = Open3.capture2("bundle", "exec", "puma", "-V",
+          chdir: dir, err: File::NULL)
+        status.success? && !out.empty?
+      rescue SystemCallError
+        false
+      end
+
+      def system_puma?
+        _out, status = Open3.capture2("puma", "-V", err: File::NULL)
+        status.success?
+      rescue SystemCallError
+        false
+      end
+
+      def wait_for_socket(path, timeout:)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until File.socket?(path)
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep 0.25
+        end
+        begin
+          UNIXSocket.new(path).close
+          true
+        rescue SystemCallError
+          false
+        end
+      end
+
+      def wait_for_tcp(port, timeout:)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          begin
+            TCPSocket.new("127.0.0.1", port).close
+            return true
+          rescue SystemCallError
+            return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+            sleep 0.25
+          end
+        end
+      end
+
+      def log_path(dir, name)
+        path = File.expand_path(File.join(dir, "log", "ask-local-#{name}.log"))
+        FileUtils.mkdir_p(File.dirname(path))
+        Log.rotate(path)
+        path
+      end
+
+      # Sidecar so `ask-local stop` can find the backend after the CLI
+      # that booted it has exited (the route owner pid is the CLI, not
+      # the backend). Removed alongside the route on clean stop.
+      def write_backend_pid(hostname, pid)
+        @store.ensure_dir
+        File.write(File.join(@store.dir, "backend-#{hostname}.pid"), "#{pid}\n")
+      rescue SystemCallError
+        nil
+      end
+
+      def log_tail(path, lines: 10)
+        return "(no log file)" unless File.file?(path)
+
+        File.readlines(path).last(lines).join
+      rescue SystemCallError
+        "(unreadable log)"
+      end
+
+      def stop_pid(pid)
+        Process.kill("TERM", pid)
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/ask/local/sanitize.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Ask
+  module Local
+    # DNS label sanitization (RFC 1035): lowercase, hyphen-separated,
+    # max 63 chars with hash suffix on truncation.
+    #
+    # Borrowed semantics from portless sanitizeForHostname/truncateLabel,
+    # reimplemented in idiomatic Ruby.
+    module Sanitize
+      MAX_DNS_LABEL_LENGTH = 63
+
+      module_function
+
+      def truncate_label(label)
+        return label if label.length <= MAX_DNS_LABEL_LENGTH
+
+        hash = Digest::SHA256.hexdigest(label)[0, 6]
+        prefix = label[0, MAX_DNS_LABEL_LENGTH - 7].gsub(/-+\z/, "")
+        "#{prefix}-#{hash}"
+      end
+
+      def hostname_label(name)
+        sanitized = name.to_s.downcase
+          .gsub(/[^a-z0-9-]/, "-")
+          .gsub(/-{2,}/, "-")
+          .gsub(/\A-+|-+\z/, "")
+        truncate_label(sanitized)
+      end
+
+      def valid_tld?(tld)
+        return false if tld.nil? || tld.empty? || tld.length > 253
+
+        tld.split(".").all? do |label|
+          !label.empty? && label.length <= 63 &&
+            label.match?(/\A[a-z0-9]([a-z0-9-]*[a-z0-9])?\z/)
+        end
+      end
+    end
+  end
+end