rb-portless 0.3.0.dev.20260630.68c9c34 → 0.3.0.dev.20260630.fb5fc36

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 749216011c6c43a8048dcbfaed840ea189a5fd62a99b2744d7e11ac482ba6f9f
-  data.tar.gz: c5f29b73ecb5ddcfe726b8db6cbf95863b9da45bd41e29dae51e98eb56cc91e9
+  metadata.gz: ad245d30c0c47ba8ac0be15c5483524cedc6d2a6fffd30b4df35ad0904287af6
+  data.tar.gz: 64e421e608545dc03fa7ad75506cd473ae86cece15b90bc38395c03fa8db0bba
 SHA512:
-  metadata.gz: 5cc9a46f38311264470ceb33b83406200f52b7aa693597309ec0d77d835beea88b30325a64cff7a47d7c9ab7cf3041109371f8e1b04115f2810850c623f76725
-  data.tar.gz: d5183f6f9d86daff7023528a93cc9a150a7732c3d5977a96b63134a7eac6e0ddb391fb4deee4952683adaf86c84bde678493afe65d78aa88f6953f87f0bd49fb
+  metadata.gz: cf6f98facf2bc05067f832f1f865b18977a00b9cbd608189289d5c89284a2b887f1d056cbcf3c664ef5a5a4762808e30dea9c1b8f582e430750562ce8b3c3b4b
+  data.tar.gz: '02658fcdf8c2ad85e58a3d5cf71148dcbec8819adb2d0bc439ec06cb44aad599d5e84a0055804ce910374f72012720e758ed418a7ded1e25033f57760f433d13'

data/CHANGELOG.md

@@ -6,8 +6,20 @@ 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** — health probes and privilege logic. (Verified manually, since
+  the Async proxy can't be driven in-process without deadlock: HTTP/HTTPS/HTTP-2
+  forwarding, wildcard routing, and the **WebSocket upgrade relay** / ActionCable.)
+
+
 - **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
@@ -16,8 +28,10 @@ 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). Degrade
-  gracefully when the tool is absent. Tailscale is **non-destructive**: it reads
+  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
   `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/config.rb

@@ -32,6 +32,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/runner.rb

@@ -21,6 +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 if @config.tls
       proxy_port = Daemon.ensure_running(tls: @config.tls)
       @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)

data/lib/portless/share/ngrok.rb

@@ -16,7 +16,10 @@ module Portless
       API = "http://127.0.0.1:4040/api/tunnels"
 
       def start(hostname:, backend_port:)
-        return nil unless Portless.which("ngrok")
+        unless Portless.which("ngrok")
+          warn "rb-portless: ngrok not found — install it (https://ngrok.com/download) to use --ngrok"
+          return nil
+        end
 
         pid = Process.spawn("ngrok", "http", backend_port.to_s, "--host-header=#{hostname}",
                             out: File::NULL, err: File::NULL)
@@ -26,9 +29,11 @@ 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
+      rescue StandardError => e
+        warn "rb-portless: ngrok failed (#{e.message})"
         nil
       end
 

data/lib/portless/share/tailscale.rb

@@ -18,21 +18,44 @@ module Portless
       FUNNEL_PORTS = [ 443, 8443, 10_000 ].freeze # Funnel supports only these
 
       def start(backend_port:, funnel: false)
-        return nil unless Portless.which("tailscale")
+        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
 
         mode = funnel ? "funnel" : "serve"
         port = available_port(funnel: funnel)
-        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
+        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 (off(mode, port) and nil) unless base
 
         { mode: mode, port: port, url: format_url(base, port) }
-      rescue StandardError
+      rescue StandardError => e
+        warn "rb-portless: tailscale sharing failed (#{e.message})"
         nil
       end
 
@@ -74,14 +97,25 @@ module Portless
         []
       end
 
-      def magic_dns_url
+      def status_json
         json = JSON.parse(`tailscale status --json 2>/dev/null`)
-        dns = json.dig("Self", "DNSName").to_s.chomp(".")
-        dns.empty? ? nil : "https://#{dns}"
+        json.is_a?(Hash) ? json : nil
       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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Portless
-  VERSION = "0.3.0.dev.20260630.68c9c34"
+  VERSION = "0.3.0.dev.20260630.fb5fc36"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rb-portless
 version: !ruby/object:Gem::Version
-  version: 0.3.0.dev.20260630.68c9c34
+  version: 0.3.0.dev.20260630.fb5fc36
 platform: ruby
 authors:
 - David Afonso