rb-portless 0.3.0.dev.20260630.8a76e8f → 0.3.0.dev.20260630.053bdf1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dda2037a7c7e36ac84158c7c47c2a49de2006452255f552d87547e513a17f8f9
-  data.tar.gz: cf0b838ff151ed00b72ec48579719de79b0e6f37e46368cd3358595dff9482c2
+  metadata.gz: e6a25f0f7f6a0e308c80900ba3e5851b5c17a3faca8dfa7777bceec1b66f678f
+  data.tar.gz: e46d73d384930fa15d5b7ab26936e1b06a424d8d22255e523858f6e507078d71
 SHA512:
-  metadata.gz: 382f71a9be4a4a9b7b71b36e4d23d98d69831e3f17174c534cab283371357cdcb7586ee55435b5c723a6a74b6382a7a79a68fe7e56b28a26a5f2e64d5ffba8e2
-  data.tar.gz: 425b0f7286a54d778b0cfedae39e74fb4bc07415f1c93ba1243153fa4ecf55614fd4e5d09e22cd99419185db7c70f034036554df871655cf611608e2e8e236d1
+  metadata.gz: fa2c6162f82e037036be8ea6ced48dadff8292e2b73c90abc88c7fdfeff78076e2d76eecd0cf8641b7a43fa380f84af2e72b27effe634a389c291bf1dfa0b713
+  data.tar.gz: c36ab3c5f0fcba87e3fb516cd5cf770ca4bdd7906653a75d81ff793ae0fe3b8331ef30ac437d9ff8378c2e8c97f5e2dacb9b49bbfc71259c339cb66e3b452a93

data/CHANGELOG.md

@@ -6,8 +6,23 @@ All notable changes to this project are documented here. The format follows
 
 ## [0.3.0]
 
+### Fixed / hardened
+
+- **Health probes can't hang.** Added a read timeout to the TLS and plain probes
+  so a port that accepts but never answers no longer blocks `discover_port`.
+
 ### Added
 
+- **Risky-TLD warning.** Warn when the configured `tld` ends in a real/reserved
+  TLD (`dev`, `app`, `local`, …) that could intercept live traffic.
+- **More tests** — `Proxy#call` is now public, so the proxy's routing + error
+  logic is unit-tested (404 / 508 loop guard / 502 dead-backend, all stamped with
+  the health header) plus health probes and privilege logic (42 tests). The
+  successful byte-forward + **WebSocket upgrade relay** (ActionCable) need a live
+  reactor and are verified end-to-end manually — async-http servers can't be torn
+  down in-process without deadlock.
+
+
 - **Startup banner.** Running a dev server through rb-portless now prints a clear
   banner with the named URL(s) it's reachable at — not just `127.0.0.1:port`.
 - **Monorepo / multi-app.** A `portless.json` `apps` map runs several apps under

data/lib/portless/cli.rb

@@ -205,11 +205,6 @@ module Portless
       i ? Integer(args[i + 1], exception: false) : nil
     end
 
-    def todo(name, desc, _args = nil)
-      warn "rb-portless #{name}: #{desc} — not yet implemented (#{Portless::VERSION})"
-      exit 1
-    end
-
     def rest(command)
       @argv.first == command ? @argv[1..] : @argv
     end

data/lib/portless/config.rb

@@ -7,9 +7,7 @@ module Portless
   # defaults. Mirrors portless's config.ts/auto.ts: name is inferred from the
   # config, the git root, or the directory; tld defaults to "localhost".
   class Config
-    DEFAULT_SCRIPT = "dev"
-
-    attr_reader :name, :tld, :script, :app_port, :tls, :apps
+    attr_reader :name, :tld, :app_port, :tls, :apps
 
     def self.load(dir = Dir.pwd)
       new(read_file(dir), dir)
@@ -19,7 +17,6 @@ module Portless
       @dir = dir
       @name = sanitize_label(data["name"] || infer_name(dir))
       @tld = (data["tld"] || Constants::DEFAULT_TLD).to_s
-      @script = data["script"] || DEFAULT_SCRIPT
       @app_port = data["appPort"] || data["app_port"]
       @tls = data.fetch("tls", true)
       # Monorepo: { "apps": { "web": "bin/rails server", "api": "node api.js" } }.
@@ -32,6 +29,17 @@ module Portless
       tld.split(".").include?(name) ? tld : "#{name}.#{tld}"
     end
 
+    # Real/reserved TLDs that can intercept live traffic or clash with mDNS.
+    RISKY_TLDS = %w[dev app page zip mov local].freeze
+
+    # A warning string if the tld looks risky, else nil. (.localhost / .test are safe.)
+    def tld_warning
+      last = tld.split(".").last
+      return unless RISKY_TLDS.include?(last)
+
+      "tld \".#{last}\" is a real/reserved TLD — prefer \".localhost\" so you don't intercept real traffic"
+    end
+
     def self.read_file(dir)
       json = File.join(dir, "portless.json")
       return JSON.parse(File.read(json)) if File.exist?(json)

data/lib/portless/health.rb

@@ -2,6 +2,7 @@
 
 require "socket"
 require "openssl"
+require "timeout"
 
 module Portless
   # "Is *our* proxy on this port?" — every proxied response carries the
@@ -26,7 +27,8 @@ module Portless
       ssl.sync_close = true
       ssl.connect
       ssl.write(REQUEST)
-      marker?(ssl.read(4096))
+      # Read timeout too — a port that accepts but never answers must not hang us.
+      marker?(Timeout.timeout(timeout) { ssl.read(4096) })
     rescue StandardError
       false
     ensure
@@ -38,7 +40,7 @@ module Portless
       Socket.tcp("127.0.0.1", port, connect_timeout: timeout) do |sock|
         sock.write(REQUEST)
         sock.close_write
-        marker?(sock.read(4096))
+        marker?(Timeout.timeout(timeout) { sock.read(4096) })
       end
     rescue StandardError
       false

data/lib/portless/hosts.rb

@@ -24,11 +24,6 @@ module Portless
       write(strip_block(read))
     end
 
-    def managed_hostnames
-      read[/#{Regexp.escape(Constants::HOSTS_BEGIN)}\n(.*?)#{Regexp.escape(Constants::HOSTS_END)}/m, 1]
-        .to_s.scan(/^\s*127\.0\.0\.1\s+(\S+)/).flatten
-    end
-
     def build_block(hostnames)
       return "" if hostnames.empty?
       lines = hostnames.uniq.map { |h| "127.0.0.1\t#{h}" }

data/lib/portless/multi.rb

@@ -7,6 +7,8 @@ module Portless
   # supervised + torn down together. Ruby sets env per-spawn, so there's no
   # NODE_OPTIONS loader hack (cf. portless's turbo.ts).
   class Multi
+    include RunSupport
+
     App = Struct.new(:name, :hostname, :port, :url, :pid, keyword_init: true)
 
     def initialize(config: Config.load, route_store: RouteStore.new)
@@ -18,7 +20,7 @@ module Portless
     def run
       raise Error, "no apps defined — add an \"apps\" map to portless.json" if @config.apps.empty?
 
-      ensure_trusted if @config.tls
+      ensure_trusted
       proxy_port = Daemon.ensure_running(tls: @config.tls)
       @apps = @config.apps.map { |name, command| start_app(name, command, proxy_port) }
 
@@ -57,27 +59,5 @@ module Portless
       @apps.each { |app| @route_store.remove(app.hostname, owner_pid: Process.pid) }
       kill_all("TERM")
     end
-
-    def child_env(port, url)
-      {
-        "PORT" => port.to_s,
-        "HOST" => "127.0.0.1",
-        "PORTLESS_URL" => url,
-        "SSL_CERT_FILE" => (File.exist?(State.ca_cert) ? State.ca_cert : nil)
-      }.compact
-    end
-
-    def display_url(hostname, proxy_port)
-      scheme = @config.tls ? "https" : "http"
-      default = @config.tls ? Constants::HTTPS_PORT : Constants::HTTP_PORT
-      suffix = proxy_port && proxy_port != default ? ":#{proxy_port}" : ""
-      "#{scheme}://#{hostname}#{suffix}"
-    end
-
-    def ensure_trusted
-      Trust.install! if Privilege.interactive? && !Trust.trusted?
-    rescue Portless::Error
-      nil
-    end
   end
 end

data/lib/portless/proxy.rb

@@ -51,13 +51,10 @@ module Portless
         routes.find { |r| host.end_with?(".#{r.hostname}") }
     end
 
-    private
-
-    def make_server(endpoint)
-      Async::HTTP::Server.for(endpoint) { |request| handle(request) }
-    end
-
-    def handle(request)
+    # The reverse-proxy app: resolve the request's host to a backend, forward it,
+    # stamp the health header. Public so it can be mounted in a test reactor
+    # (Async::HTTP::Server.for(endpoint, &proxy.method(:call))).
+    def call(request)
       host = request_host(request)
       route = route_for(host)
       return error(404, "No app is registered for #{host}.") unless route
@@ -72,6 +69,12 @@ module Portless
       error(502, "Backend for #{host} is not responding (#{e.class}).")
     end
 
+    private
+
+    def make_server(endpoint)
+      Async::HTTP::Server.for(endpoint) { |request| call(request) }
+    end
+
     def build_forward(request, host, hops)
       headers = Protocol::HTTP::Headers.new
       request.headers.each do |key, value|

data/lib/portless/run_support.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Portless
+  # Shared bits of the two run paths (single-app Runner + multi-app Multi):
+  # the child env, the display URL, and first-run CA trust. Both expect a
+  # `@config`.
+  module RunSupport
+    private
+
+    def child_env(port, url)
+      {
+        "PORT" => port.to_s,
+        "HOST" => "127.0.0.1",
+        "PORTLESS_URL" => url,
+        # Let the app's own server-side TLS verification trust our CA.
+        "SSL_CERT_FILE" => (File.exist?(State.ca_cert) ? State.ca_cert : nil)
+      }.compact
+    end
+
+    def display_url(hostname, proxy_port)
+      scheme = @config.tls ? "https" : "http"
+      default = @config.tls ? Constants::HTTPS_PORT : Constants::HTTP_PORT
+      suffix = proxy_port && proxy_port != default ? ":#{proxy_port}" : ""
+      "#{scheme}://#{hostname}#{suffix}"
+    end
+
+    # Trust the local CA on first run (HTTPS only, interactive; never blocks the
+    # run), so HTTPS works without browser warnings — like portless.
+    def ensure_trusted
+      return unless @config.tls
+      return if Trust.trusted?
+
+      unless Privilege.interactive?
+        warn "rb-portless: CA not trusted — run `rb-portless trust` (HTTPS shows warnings until then)"
+        return
+      end
+
+      warn "rb-portless: trusting the local CA (first run)…"
+      Trust.install!
+    rescue Portless::Error => e
+      warn "rb-portless: couldn't auto-trust the CA (#{e.message}) — run `rb-portless trust`"
+    end
+  end
+end

data/lib/portless/runner.rb

@@ -6,6 +6,8 @@ module Portless
   # group (forwarding signals), and deregister on exit. Rails/puma respect PORT
   # natively. Mirrors portless's runApp/spawnCommand.
   class Runner
+    include RunSupport
+
     def initialize(command:, config: Config.load, route_store: RouteStore.new, options: {})
       @command = Array(command)
       @config = config
@@ -21,7 +23,8 @@ module Portless
       command = Frameworks.inject(command, port) # --port/--host for vite/astro/etc.
       hostname = @config.hostname
 
-      ensure_trusted if @config.tls
+      warn "rb-portless: #{@config.tld_warning}" if @config.tld_warning
+      ensure_trusted
       proxy_port = Daemon.ensure_running(tls: @config.tls)
       @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)
 
@@ -40,13 +43,6 @@ module Portless
 
     private
 
-    def display_url(hostname, proxy_port)
-      scheme = @config.tls ? "https" : "http"
-      default = @config.tls ? Constants::HTTPS_PORT : Constants::HTTP_PORT
-      suffix = proxy_port && proxy_port != default ? ":#{proxy_port}" : ""
-      "#{scheme}://#{hostname}#{suffix}"
-    end
-
     # ── LAN mode (--lan) ──────────────────────────────────────────────────
     # Register a `<name>.local` route, publish it over mDNS, and surface the URL
     # so phones/tablets on the Wi-Fi can reach the app.
@@ -83,24 +79,6 @@ module Portless
       Share::Tailscale.stop(@tailscale) if @tailscale
     end
 
-    # Trust the local CA on first run (like portless), so HTTPS works without
-    # browser warnings out of the box. Interactive only — macOS prompts for
-    # keychain auth; in CI/no-TTY we skip with a hint rather than hang. Never
-    # blocks the run if trusting fails.
-    def ensure_trusted
-      return if Trust.trusted?
-
-      unless Privilege.interactive?
-        warn "rb-portless: CA not trusted — run `rb-portless trust` (HTTPS shows warnings until then)"
-        return
-      end
-
-      warn "rb-portless: trusting the local CA (first run)…"
-      Trust.install!
-    rescue Portless::Error => e
-      warn "rb-portless: couldn't auto-trust the CA (#{e.message}) — run `rb-portless trust`"
-    end
-
     # Run the child in its own process group so we can signal the whole tree,
     # forwarding INT/TERM and propagating its exit status.
     def supervise(command, port, url)
@@ -122,16 +100,6 @@ module Portless
       nil
     end
 
-    def child_env(port, url)
-      {
-        "PORT" => port.to_s,
-        "HOST" => "127.0.0.1",
-        "PORTLESS_URL" => url,
-        # Let the app's own server-side TLS verification trust our CA.
-        "SSL_CERT_FILE" => (File.exist?(State.ca_cert) ? State.ca_cert : nil)
-      }.compact
-    end
-
     # Explicit command wins; bare `rb-portless` falls back to the project's dev
     # runner (bin/dev, then bin/rails server).
     def resolved_command

data/lib/portless/state.rb

@@ -29,7 +29,6 @@ module Portless
     def proxy_log = path("proxy.log")
     def ca_cert = path("ca.pem")
     def ca_key = path("ca-key.pem")
-    def ca_serial = path("ca.srl")
     def ca_trusted_marker = path("ca.trusted")
     def host_certs_dir = path("host-certs")
 

data/lib/portless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Portless
-  VERSION = "0.3.0.dev.20260630.8a76e8f"
+  VERSION = "0.3.0.dev.20260630.053bdf1"
 end

data/lib/rb-portless.rb

@@ -22,6 +22,7 @@ require_relative "portless/lan_ip"
 require_relative "portless/mdns"
 require_relative "portless/share/ngrok"
 require_relative "portless/share/tailscale"
+require_relative "portless/run_support"
 require_relative "portless/runner"
 require_relative "portless/multi"
 require_relative "portless/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rb-portless
 version: !ruby/object:Gem::Version
-  version: 0.3.0.dev.20260630.8a76e8f
+  version: 0.3.0.dev.20260630.053bdf1
 platform: ruby
 authors:
 - David Afonso
@@ -74,6 +74,7 @@ files:
 - lib/portless/rails.rb
 - lib/portless/rails_hosts.rb
 - lib/portless/route_store.rb
+- lib/portless/run_support.rb
 - lib/portless/runner.rb
 - lib/portless/service.rb
 - lib/portless/share/ngrok.rb