rb-portless 0.3.0.dev.20260630.053bdf1 → 0.3.0.dev.20260630.68c9c34

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6a25f0f7f6a0e308c80900ba3e5851b5c17a3faca8dfa7777bceec1b66f678f
-  data.tar.gz: e46d73d384930fa15d5b7ab26936e1b06a424d8d22255e523858f6e507078d71
+  metadata.gz: 749216011c6c43a8048dcbfaed840ea189a5fd62a99b2744d7e11ac482ba6f9f
+  data.tar.gz: c5f29b73ecb5ddcfe726b8db6cbf95863b9da45bd41e29dae51e98eb56cc91e9
 SHA512:
-  metadata.gz: fa2c6162f82e037036be8ea6ced48dadff8292e2b73c90abc88c7fdfeff78076e2d76eecd0cf8641b7a43fa380f84af2e72b27effe634a389c291bf1dfa0b713
-  data.tar.gz: c36ab3c5f0fcba87e3fb516cd5cf770ca4bdd7906653a75d81ff793ae0fe3b8331ef30ac437d9ff8378c2e8c97f5e2dacb9b49bbfc71259c339cb66e3b452a93
+  metadata.gz: 5cc9a46f38311264470ceb33b83406200f52b7aa693597309ec0d77d835beea88b30325a64cff7a47d7c9ab7cf3041109371f8e1b04115f2810850c623f76725
+  data.tar.gz: d5183f6f9d86daff7023528a93cc9a150a7732c3d5977a96b63134a7eac6e0ddb391fb4deee4952683adaf86c84bde678493afe65d78aa88f6953f87f0bd49fb

data/CHANGELOG.md

@@ -6,23 +6,8 @@ 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
@@ -31,10 +16,8 @@ All notable changes to this project are documented here. The format follows
   detects the LAN IP, registers `<name>.local`, and publishes it over mDNS
   (`dns-sd`/`avahi-publish`). `--ip` overrides the detected address.
 - **Public sharing (experimental).** `--ngrok`, `--tailscale`, `--funnel` expose
-  the app via ngrok / your tailnet (their CLIs, installed separately). When a
-  tool is missing or unconfigured, print an **actionable** message (install link,
-  `ngrok config add-authtoken`, "enable HTTPS in your tailnet DNS settings",
-  "run `tailscale up`") rather than failing silently — mirroring portless. Tailscale is **non-destructive**: it reads
+  the app via ngrok / your tailnet (their CLIs, installed separately). Degrade
+  gracefully when the tool is absent. Tailscale is **non-destructive**: it reads
   `tailscale serve status`, picks a free HTTPS port (never clobbering your
   existing serve/funnel config), registers with `--yes`, and removes only the
   port it created on exit — mirroring portless's port-conflict handling.

data/lib/portless/cli.rb

@@ -205,6 +205,11 @@ 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,7 +7,9 @@ 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
-    attr_reader :name, :tld, :app_port, :tls, :apps
+    DEFAULT_SCRIPT = "dev"
+
+    attr_reader :name, :tld, :script, :app_port, :tls, :apps
 
     def self.load(dir = Dir.pwd)
       new(read_file(dir), dir)
@@ -17,6 +19,7 @@ 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" } }.
@@ -29,17 +32,6 @@ 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,7 +2,6 @@
 
 require "socket"
 require "openssl"
-require "timeout"
 
 module Portless
   # "Is *our* proxy on this port?" — every proxied response carries the
@@ -27,8 +26,7 @@ module Portless
       ssl.sync_close = true
       ssl.connect
       ssl.write(REQUEST)
-      # Read timeout too — a port that accepts but never answers must not hang us.
-      marker?(Timeout.timeout(timeout) { ssl.read(4096) })
+      marker?(ssl.read(4096))
     rescue StandardError
       false
     ensure
@@ -40,7 +38,7 @@ module Portless
       Socket.tcp("127.0.0.1", port, connect_timeout: timeout) do |sock|
         sock.write(REQUEST)
         sock.close_write
-        marker?(Timeout.timeout(timeout) { sock.read(4096) })
+        marker?(sock.read(4096))
       end
     rescue StandardError
       false

data/lib/portless/hosts.rb

@@ -24,6 +24,11 @@ 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,8 +7,6 @@ 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)
@@ -20,7 +18,7 @@ module Portless
     def run
       raise Error, "no apps defined — add an \"apps\" map to portless.json" if @config.apps.empty?
 
-      ensure_trusted
+      ensure_trusted if @config.tls
       proxy_port = Daemon.ensure_running(tls: @config.tls)
       @apps = @config.apps.map { |name, command| start_app(name, command, proxy_port) }
 
@@ -59,5 +57,27 @@ 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,10 +51,13 @@ module Portless
         routes.find { |r| host.end_with?(".#{r.hostname}") }
     end
 
-    # 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)
+    private
+
+    def make_server(endpoint)
+      Async::HTTP::Server.for(endpoint) { |request| handle(request) }
+    end
+
+    def handle(request)
       host = request_host(request)
       route = route_for(host)
       return error(404, "No app is registered for #{host}.") unless route
@@ -69,12 +72,6 @@ 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/runner.rb

@@ -6,8 +6,6 @@ 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
@@ -23,8 +21,7 @@ module Portless
       command = Frameworks.inject(command, port) # --port/--host for vite/astro/etc.
       hostname = @config.hostname
 
-      warn "rb-portless: #{@config.tld_warning}" if @config.tld_warning
-      ensure_trusted
+      ensure_trusted if @config.tls
       proxy_port = Daemon.ensure_running(tls: @config.tls)
       @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)
 
@@ -43,6 +40,13 @@ 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.
@@ -79,6 +83,24 @@ 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)
@@ -100,6 +122,16 @@ 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/share/ngrok.rb

@@ -16,10 +16,7 @@ module Portless
       API = "http://127.0.0.1:4040/api/tunnels"
 
       def start(hostname:, backend_port:)
-        unless Portless.which("ngrok")
-          warn "rb-portless: ngrok not found — install it (https://ngrok.com/download) to use --ngrok"
-          return nil
-        end
+        return nil unless Portless.which("ngrok")
 
         pid = Process.spawn("ngrok", "http", backend_port.to_s, "--host-header=#{hostname}",
                             out: File::NULL, err: File::NULL)
@@ -29,11 +26,9 @@ module Portless
           { pid: pid, url: url }
         else
           stop(pid: pid)
-          warn "rb-portless: ngrok didn't produce a public URL — is your authtoken set? (`ngrok config add-authtoken <token>`)"
           nil
         end
-      rescue StandardError => e
-        warn "rb-portless: ngrok failed (#{e.message})"
+      rescue StandardError
         nil
       end
 

data/lib/portless/share/tailscale.rb

@@ -18,44 +18,21 @@ module Portless
       FUNNEL_PORTS = [ 443, 8443, 10_000 ].freeze # Funnel supports only these
 
       def start(backend_port:, funnel: false)
-        unless Portless.which("tailscale")
-          warn "rb-portless: tailscale not found — install it (https://tailscale.com/download) to use --tailscale"
-          return nil
-        end
-
-        status = status_json
-        unless status
-          warn "rb-portless: tailscale isn't connected — run `tailscale up`, then retry"
-          return nil
-        end
-        unless capability?(status, "https")
-          warn "rb-portless: tailscale HTTPS certs aren't enabled — turn on HTTPS in your tailnet DNS settings"
-          return nil
-        end
-        if funnel && !capability?(status, "funnel")
-          warn "rb-portless: tailscale Funnel isn't enabled for this node — enable it, then retry --funnel"
-          return nil
-        end
+        return nil unless Portless.which("tailscale")
 
         mode = funnel ? "funnel" : "serve"
         port = available_port(funnel: funnel)
-        unless port
-          warn "rb-portless: all tailscale Funnel ports are in use (443/8443/10000)"
-          return nil
-        end
-
-        unless system("tailscale", mode, "--bg", "--yes", "--https=#{port}",
-                      "http://127.0.0.1:#{backend_port}", out: File::NULL, err: File::NULL)
-          warn "rb-portless: `tailscale #{mode}` failed to register"
-          return nil
-        end
-
-        base = dns_name(status)
+        return nil unless port # all preferred ports already in use → don't fight it
+
+        ok = system("tailscale", mode, "--bg", "--yes", "--https=#{port}",
+                    "http://127.0.0.1:#{backend_port}", out: File::NULL, err: File::NULL)
+        return nil unless ok
+
+        base = magic_dns_url
         return (off(mode, port) and nil) unless base
 
         { mode: mode, port: port, url: format_url(base, port) }
-      rescue StandardError => e
-        warn "rb-portless: tailscale sharing failed (#{e.message})"
+      rescue StandardError
         nil
       end
 
@@ -97,25 +74,14 @@ module Portless
         []
       end
 
-      def status_json
+      def magic_dns_url
         json = JSON.parse(`tailscale status --json 2>/dev/null`)
-        json.is_a?(Hash) ? json : nil
+        dns = json.dig("Self", "DNSName").to_s.chomp(".")
+        dns.empty? ? nil : "https://#{dns}"
       rescue StandardError
         nil
       end
 
-      def dns_name(status)
-        dns = status.dig("Self", "DNSName").to_s.chomp(".")
-        dns.empty? ? nil : "https://#{dns}"
-      end
-
-      # Does this node have the HTTPS / Funnel capability? (mirrors portless)
-      def capability?(status, name)
-        node = status["Self"] || {}
-        names = Array(node["Capabilities"]) + (node["CapMap"] || {}).keys
-        names.any? { |cap| down = cap.to_s.downcase; down == name || down.end_with?("/#{name}") }
-      end
-
       def format_url(base, port)
         base = base.chomp("/")
         port == 443 ? base : "#{base}:#{port}"

data/lib/portless/state.rb

@@ -29,6 +29,7 @@ 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.053bdf1"
+  VERSION = "0.3.0.dev.20260630.68c9c34"
 end

data/lib/rb-portless.rb

@@ -22,7 +22,6 @@ 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.053bdf1
+  version: 0.3.0.dev.20260630.68c9c34
 platform: ruby
 authors:
 - David Afonso
@@ -74,7 +74,6 @@ 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

data/lib/portless/run_support.rb

@@ -1,44 +0,0 @@
-# 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