rb-portless 0.3.0.dev.20260630.7305b58 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77efce157b70a56f16f260b04bfad49a83b55d1aa1c5367b8b24f4d596ce1541
-  data.tar.gz: 17f9a98ff52119a61fc2d770e7c3df451b3bdc39547f897f0e432b7b9fb2b57d
+  metadata.gz: e49a039bffaf418a826c61337253e8cf3f46c54b500f30936fba6e8153f96804
+  data.tar.gz: b4c6fad1e96ac1c2fd11a9366ad36273af95976e2abcdb1387d4b1b60dd1bd27
 SHA512:
-  metadata.gz: f4e976fc65b4887516767d64b8d273066e8b03cfccebca66e762e473d8f77b6a441dd78b24ff4fe3a5485628e845ce904e8898a75e0e4db80e5d3852b9767869
-  data.tar.gz: e320411a2f3104a3ab3ab4f5c61cd7f41c423d4978a0e4b001fbf67554c008c7ea396da8950a0cd09928facaa192cb518d16cda6f97391b87a8f5387f7483b41
+  metadata.gz: 7754996324bcc3c53dac67a3c2999cc2c57d25d0bc6126ac4041d6dfb2936c49ca675b63ddb1fb24d86ad5b3a49b76b76e7397ae20f32f0d637f3b3f63e4f640
+  data.tar.gz: ec5a8e7ff23b18f7766015e11627938776d88eb672fe174a3902e273af14d044f69db69a146de48284799e08de5425544837a94160cf3c2ddf6eff7faa447673

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
@@ -16,7 +31,13 @@ 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. Degrade gracefully when the tool is absent.
+  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.
 
 ## [0.2.0]
 

data/README.md

@@ -95,7 +95,17 @@ rb-portless run --ngrok bin/dev        # https://xxxx.ngrok.app
 rb-portless run --tailscale bin/dev    # your-machine.tailnet.ts.net
 rb-portless run --funnel bin/dev       # tailscale Funnel (public)
 ```
-Each degrades gracefully if the tool isn't installed.
+
+These use the tools' own CLIs — **install them separately** (we don't bundle
+anything, same as portless), and each degrades gracefully if the tool is absent:
+- **ngrok** — install the `ngrok` CLI and configure an authtoken (free account).
+- **tailscale** — install `tailscale`, be logged into a tailnet, and enable HTTPS
+  certificates (and Funnel, for `--funnel`) in your tailnet settings.
+
+> **Your tailnet config is safe.** rb-portless reads `tailscale serve status`,
+> picks a **free** HTTPS port (never one you're already serving on), registers
+> with `--yes`, and on exit turns off **only the port it created** — it never
+> touches your existing `serve`/`funnel` setup.
 
 ## Commands
 

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/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/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

@@ -5,41 +5,121 @@ require "json"
 module Portless
   module Share
     # Expose the local app on your tailnet (`serve`) or publicly (`funnel`) via
-    # the tailscale CLI. Returns { mode:, url: } or nil. EXPERIMENTAL. Mirrors
-    # portless's tailscale.ts.
+    # the tailscale CLI. Returns { mode:, port:, url: } or nil. EXPERIMENTAL.
+    #
+    # SAFETY (mirrors portless's tailscale.ts): we never clobber your existing
+    # serve config — we read `tailscale serve status` for ports already in use
+    # and pick the first FREE one from the preferred list, register with `--yes`
+    # (no prompt), and on teardown turn off ONLY the port we registered.
     module Tailscale
       module_function
 
+      PREFERRED_SERVE_PORTS = [ 443, 8443, 8444, 8445, 8446, 8447, 8448, 8449, 8450 ].freeze
+      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"
-        ok = system("tailscale", mode, "--bg", "--https=443", "http://127.0.0.1:#{backend_port}",
-                    out: File::NULL, err: File::NULL)
-        return nil unless ok
+        port = available_port(funnel: funnel)
+        unless port
+          warn "rb-portless: all tailscale Funnel ports are in use (443/8443/10000)"
+          return nil
+        end
 
-        url = magic_dns_url
-        url ? { mode: mode, url: url } : nil
-      rescue StandardError
+        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 => e
+        warn "rb-portless: tailscale sharing failed (#{e.message})"
         nil
       end
 
       def stop(handle)
         return unless handle && Portless.which("tailscale")
 
-        system("tailscale", handle[:mode], "--https=443", "off", out: File::NULL, err: File::NULL)
+        off(handle[:mode], handle[:port])
+      end
+
+      # Turn off ONLY the registration we created (scoped to our port).
+      def off(mode, port)
+        system("tailscale", mode, "--yes", "--https=#{port}", "off", out: File::NULL, err: File::NULL)
       rescue StandardError
         nil
       end
 
-      # The machine's MagicDNS name → its tailnet HTTPS URL.
-      def magic_dns_url
+      # First free HTTPS port from the preferred pool, never one already in use by
+      # the user's existing serve/funnel config. nil if the funnel pool is full.
+      def available_port(funnel:)
+        used = used_serve_ports
+        pool = funnel ? FUNNEL_PORTS : PREFERRED_SERVE_PORTS
+        free = pool.find { |port| !used.include?(port) }
+        return free if free
+        return nil if funnel
+
+        port = PREFERRED_SERVE_PORTS.last + 1
+        port += 1 while used.include?(port)
+        port
+      end
+
+      # HTTPS ports the user's current serve config already occupies.
+      def used_serve_ports
+        config = JSON.parse(`tailscale serve status --json 2>/dev/null`)
+        ports = []
+        (config["Web"] || {}).each_key { |host_port| ports << Regexp.last_match(1).to_i if host_port =~ /:(\d+)\z/ }
+        (config["TCP"] || {}).each_key { |port| ports << port.to_i }
+        ports
+      rescue StandardError
+        []
+      end
+
+      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}"
+      end
     end
   end
 end

data/lib/portless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Portless
-  VERSION = "0.3.0.dev.20260630.7305b58"
+  VERSION = "0.3.0"
 end

metadata

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