samagotchi 0.109.0 → 0.110.0

data/lib/samagotchi/web/server.rb

@@ -16,6 +16,7 @@ require_relative "qr"
 require_relative "running"
 require_relative "session_hub"
 require_relative "token"
+require_relative "tunnel"
 require_relative "../config"
 require_relative "../project_scope"
 require_relative "../log"
@@ -71,19 +72,24 @@ module Samagotchi
       # @param scope ["project", "all"] "all": the plain page, every session
       # @param new_token [Boolean] replace the LAN access token first
       #   (--new-token): a running server takes the new one at once
+      # @param tunnel [String, nil] --tunnel's provider (Tunnel.for): this
+      #   run's public_url is the tunnel's, never config's, and the tunnel is
+      #   on while the server runs
       # @return [Integer] the exit status
       def self.launch(port: nil, host: nil, scope: "project", dir: Dir.pwd, open_browser: false, markdown: false,
                       view: Config::BY_KEY["web.view"].default, annotate_presets: Config::BY_KEY["web.annotate_presets"].default,
                       editor: Config::BY_KEY["web.editor"].default, new_token: false,
-                      working_set: Config::BY_KEY["web.working_set"].default)
+                      working_set: Config::BY_KEY["web.working_set"].default, tunnel: nil)
         rotate_token if new_token
-        public_url = public_url_setting
+        public_url = public_url_setting unless tunnel
         setting = host_setting(host)
         lan = Lan.wanted?(setting) ? Lan.choose(setting) : nil
         host = resolve_host(setting)
         port = resolve_port(port)
         url = scope_url(host, port, dir: dir, scope: scope)
         found = probe(host, port)
+        raise Tunnel::AlreadyRunning, port if tunnel && found.is_a?(Hash)
+
         case found
         when Hash
           if lan && !found["lan"]
@@ -93,7 +99,8 @@ module Samagotchi
           end
           puts "chi web already runs on port #{port} (pid #{found["pid"]}): #{url}"
           puts running_lan_lines(found["lan"], port) if found["lan"]
-          puts running_public_lines(public_url) if public_url
+          running_public = public_url || Running.live_public_url(probe: ->(at) { probe(host, at) })
+          puts running_public_lines(running_public) if running_public
           puts lan_off_line(setting) if new_token && !found["lan"]
           open_url(url) if open_browser
           0
@@ -101,21 +108,30 @@ module Samagotchi
           warn in_use_message(port)
           1
         else
+          if tunnel
+            provider = Tunnel.for(tunnel)
+            plan = provider.prepare(port: port, config_owner: Samagotchi::Config.get("web.proxy.owner"),
+                                    config_public_url: Samagotchi::Config.get("web.public_url"),
+                                    config_identity_header: Samagotchi::Config.get("web.proxy.identity_header"))
+            public_url = plan.public_url
+          end
           if new_token && !lan && !public_url
             puts lan_off_line(setting)
             return 0
           end
           # The participants' grants: never served from a store others can read.
           Grants.check_permissions!(Grants.path)
-          if start(port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
-                   annotate_presets: annotate_presets, editor: editor, lan: lan, working_set: working_set,
-                   public_url: public_url)
-            0
-          else
-            1
-          end
+          options = { port: port, host: host, url: url, open_browser: open_browser, markdown: markdown, view: view,
+                      annotate_presets: annotate_presets, editor: editor, lan: lan, working_set: working_set,
+                      public_url: public_url }
+          started = if plan
+                      with_tunnel(provider, plan) { start(**options, public_notes: provider.start_lines(plan)) }
+                    else
+                      start(**options)
+                    end
+          started ? 0 : 1
         end
-      rescue Lan::Error, Grants::Insecure, PublicUrl::Invalid => e
+      rescue Lan::Error, Grants::Insecure, PublicUrl::Invalid, Tunnel::Refused => e
         warn "Error: #{e.message}"
         1
       rescue Interrupt
@@ -125,18 +141,52 @@ module Samagotchi
         CLI::Exit::INTERRUPTED
       end
 
+      # The tunnel on while the block runs (the server), off after it
+      # whatever ends it (Ctrl-C, SIGTERM, SIGHUP, a port taken), and only
+      # once #up succeeded: a refusal before it, or a failed #up, turns off
+      # nothing (a live tunnel of another chi web stays).
+      def self.with_tunnel(provider, plan)
+        provider.up(plan)
+        upped = true
+        yield
+      ensure
+        tunnel_down(provider, plan) if upped
+      end
+
+      # The tunnel's teardown, before any line (a hung-up terminal can't
+      # write): a failure is one warning line, never a crash or another exit
+      # status, and a second Ctrl-C during it only cuts it short.
+      def self.tunnel_down(provider, plan)
+        line = begin
+          provider.down_line(plan, provider.down(plan))
+        rescue Tunnel::Refused, SignalException => e
+          provider.down_warning(plan, e)
+        end
+        say(line) if line
+      end
+
+      # A line that may meet a terminal gone (SIGHUP): never an error.
+      def self.say(line)
+        puts line
+        $stdout.flush
+      rescue IOError, SystemCallError
+        nil
+      end
+
       # @param hub [SessionHub, nil] the session projection the page streams
       #   from; built over the app's state dir unless given
       # @param lan [Lan::Choice, nil] also listen on this LAN address, where
       #   every request but this machine's needs the access token
       # @param token_path [String] the LAN access token's file
       # @param public_url [PublicUrl, nil] behind an auth proxy
-      #   (web.public_url): every request needs the access token
+      #   (web.public_url, or --tunnel's): every request needs the access token
+      # @param public_notes [Array<String>] lines after the proxied link's
+      #   (the tunnel's)
       # @return [Boolean] false when the port was taken (said so on stderr)
       def self.start(port: nil, host: nil, url: nil, open_browser: false, state_dir: nil, manager: nil, markdown: false,
                      view: Config::BY_KEY["web.view"].default, annotate_presets: Config::BY_KEY["web.annotate_presets"].default, hub: nil, lan: nil,
                      editor: Config::BY_KEY["web.editor"].default, token_path: Token.path,
-                     working_set: Config::BY_KEY["web.working_set"].default, public_url: nil)
+                     working_set: Config::BY_KEY["web.working_set"].default, public_url: nil, public_notes: [])
         config_restart_unsubscribe = ConfigFile.watch_restart_settings!(process: :web) do |message|
           Samagotchi::Log.warn(:config, "restart_required", echo: "Warning: config: #{message}")
         end
@@ -164,10 +214,12 @@ module Samagotchi
         # the in-use line instead.
         running_path = Running.path(state_dir: state_dir)
         started = lambda do
-          record_running(running_path, port)
+          record_running(running_path, port, public_url)
           puts "Chi Web on #{url} (public: #{File.expand_path("public", __dir__)})"
           puts lan_lines(ip: lan.ip, port: port, token: Token.read(token_path), others: lan.others, public: lan.public) if lan
-          puts public_lines(public_url, token: Token.read(token_path), codes: owner_codes(state_dir)) if public_url
+          if public_url
+            puts public_lines(public_url, token: Token.read(token_path), codes: owner_codes(state_dir), notes: public_notes)
+          end
           puts "Press Ctrl-C to stop."
           $stdout.flush # a log file isn't line-buffered
           if open_browser
@@ -203,11 +255,11 @@ module Samagotchi
 
       class LanListenError < StandardError; end
 
-      # Where this chi web listens, for chi share's link (Web::Running); a
-      # write that fails leaves the server running and the readers on
-      # web.port.
-      def self.record_running(path, port)
-        Running.record(port: port, path: path)
+      # Where this chi web listens, and its public_url (config's or the
+      # tunnel's), for chi share's link (Web::Running); a write that fails
+      # leaves the server running and the readers on web.port and config.
+      def self.record_running(path, port, public_url = nil)
+        Running.record(port: port, path: path, public_url: public_url&.origin)
       rescue SystemCallError => e
         Samagotchi::Log.warn(:web, "running_record_failed", error: e.class.name)
       end
@@ -251,32 +303,36 @@ module Samagotchi
                               owner: Samagotchi::Config.get("web.proxy.owner"))
       end
 
-      # What web.public_url adds to the start lines: the proxied link (the
-      # token in its fragment) and who the owner is. On this machine the
+      # What web.public_url adds to the start lines: the proxied link (a
+      # one-time code in its fragment), who the owner is, +notes+ (the
+      # tunnel's) and, at a terminal, the link's QR code. On this machine the
       # page opens through the proxy too; a direct request takes the token
       # as Authorization: Bearer only (no cookie for 127.0.0.1, which every
       # local port would get).
-      def self.public_lines(public_url, token:, codes: owner_codes)
+      def self.public_lines(public_url, token:, codes: owner_codes, notes: [], qr: $stdout.tty?)
         unless token
-          return ["Proxied: #{public_url.origin}/ (no access token: its file is gone; chi web --new-token makes one)"]
+          return ["Proxied: #{public_url.origin}/ (no access token: its file is gone; chi web --new-token makes one)",
+                  *notes]
         end
 
         who = if public_url.identity_header.nil? then "token only, no identity header"
               elsif public_url.owner then "owner #{public_url.owner} by #{public_url.identity_header}, and the token"
               else "nobody is the owner by identity: web.proxy.owner is unset"
               end
-        code = codes.issue(kind: :owner, ttl: LinkCodes::OWNER_TTL)
-        ["Proxied: #{public_url.link(code)}   ← opens chi web as you once, within #{LinkCodes::OWNER_TTL / 60} minutes " \
-         "(chi web again prints a new one)",
-         "         (#{who}; on this machine the page opens through the proxy too)"]
+        link = public_url.link(codes.issue(kind: :owner, ttl: LinkCodes::OWNER_TTL))
+        lines = ["Proxied: #{link}   ← opens chi web as you once, within #{LinkCodes::OWNER_TTL / 60} minutes " \
+                 "(chi web again prints a new one)",
+                 "         (#{who}; on this machine the page opens through the proxy too)", *notes]
+        lines.concat(QR.lines(link)) if qr
+        lines
       end
 
       # The owner's one-time link codes, next to the grants.
       def self.owner_codes(state_dir = nil) = LinkCodes.for_grants(Grants.path(state_dir: state_dir))
 
-      # A second chi web, when this machine's config has web.public_url: the
-      # link from this config and the token file, never from what answered
-      # on the port.
+      # A second chi web, when this machine's config has web.public_url (or
+      # the running chi web recorded one: Running.live_public_url): the link
+      # from there and the token file, never from what answered on the port.
       def self.running_public_lines(public_url, token_path: Token.path, codes: owner_codes)
         return ["Proxied: #{public_url.origin}/"] unless Token.read(token_path)
 

data/lib/samagotchi/web/tunnel/tailscale.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../tunnel"
+require_relative "../public_url"
+require_relative "../../session"
+
+module Samagotchi
+  module Web
+    module Tunnel
+      # `chi web --tunnel tailscale`: Tailscale Serve on this machine's
+      # tailnet name, port 443 → chi web's 127.0.0.1 port, never Funnel.
+      # The identity is the Tailscale login Serve sends (Tailscale-User-Login);
+      # the owner is web.proxy.owner, else this machine's own login.
+      #
+      # Serve's other ports are never touched, and on 443 only exactly what
+      # this provider sets (one handler / → http://127.0.0.1:<port>, no
+      # Funnel) is adopted or turned off: anything else there is refused at
+      # start and left alone at exit.
+      class Tailscale
+        # The CLI to run, before PATH: every spec that runs it sets this to a
+        # fake.
+        ENV_CLI = "SAMAGOTCHI_TAILSCALE_CLI"
+        # The macOS app's own CLI, when there is no tailscale on PATH (never
+        # in a test run).
+        APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+        IDENTITY_HEADER = "Tailscale-User-Login"
+        STATUS_TIMEOUT = 5
+        SERVE_TIMEOUT = 15
+        LOCK_DOCS = "https://tailscale.com/kb/1226/tailnet-lock"
+
+        # No tailscale to run.
+        class CliMissing < Refused
+          def initialize
+            super("tailscale isn't installed: no tailscale on PATH or at #{APP_CLI} (install it from tailscale.com, " \
+                  "or set #{ENV_CLI} to its path)")
+          end
+        end
+
+        # SAMAGOTCHI_TAILSCALE_CLI names something that can't run.
+        class CliOverrideMissing < Refused
+          def initialize(path)
+            super("#{ENV_CLI} is #{path}, which isn't an executable file")
+          end
+        end
+
+        # Tailscale is installed but not connected (BackendState).
+        class NotRunning < Refused
+          def initialize(state)
+            super("Tailscale isn't connected (#{state}): open the Tailscale app and sign in, then run this again")
+          end
+        end
+
+        # No MagicDNS name for this machine.
+        class NoDnsName < Refused
+          def initialize
+            super("this machine has no tailnet name: turn on MagicDNS in the Tailscale admin console (DNS)")
+          end
+        end
+
+        # HTTPS certificates are off (no CertDomains for the name).
+        class NoHttps < Refused
+          def initialize(name)
+            super("HTTPS certificates are off for this tailnet (none for #{name}): turn them on in the Tailscale admin " \
+                  "console (DNS); rename this machine first, certificate names go into a public log")
+          end
+        end
+
+        # A tagged machine's UserID isn't a person: no owner by default.
+        class TaggedOwner < Refused
+          def initialize(tags)
+            super("this machine is tagged (#{tags.join(", ")}), so its Tailscale login isn't a person's: set " \
+                  "web.proxy.owner to your Tailscale login")
+          end
+        end
+
+        # Something other than this provider's one handler serves 443.
+        class ServeInUse < Refused
+          def initialize(what)
+            super("Tailscale Serve already serves port 443 here (#{what}), and chi web won't change it: turn it off " \
+                  "with tailscale serve --https=443 off, or use it as it is without --tunnel")
+          end
+        end
+
+        # Funnel (the public internet) is on for 443.
+        class Funnel < Refused
+          def initialize(name)
+            super("Tailscale Funnel is on for #{name} (the public internet), and chi web never runs behind Funnel: " \
+                  "turn it off first (tailscale funnel status shows it)")
+          end
+        end
+
+        # @param env [Hash] ENV: SAMAGOTCHI_TAILSCALE_CLI, PATH, the test-run flags
+        # @param app_cli [String] the app bundle's CLI (a spec's own path)
+        # @param runner [#call] (argv, timeout:) → Runner::Result
+        def initialize(env: ENV, app_cli: APP_CLI, runner: Runner.new)
+          @env = env
+          @app_cli = app_cli
+          @runner = runner
+        end
+
+        # The tailscale command: SAMAGOTCHI_TAILSCALE_CLI, else tailscale on
+        # PATH, else the macOS app's CLI (not in a test run).
+        # @raise [CliMissing, CliOverrideMissing]
+        def cli
+          @cli ||= lookup
+        end
+
+        # Everything checked before anything changes: connected, the name
+        # and its certificate, the owner, config conflicts, what Serve has
+        # on 443, Tailnet Lock.
+        # @param config_owner [String, nil] web.proxy.owner
+        # @param config_public_url [String, nil] web.public_url
+        # @param config_identity_header [String, nil] web.proxy.identity_header
+        # @return [Plan]
+        # @raise [Refused]
+        def prepare(port:, config_owner: nil, config_public_url: nil, config_identity_header: nil)
+          status = json(%w[status --json])
+          dns_name = connected_name(status)
+          origin = "https://#{dns_name}"
+          check_config(origin, config_public_url, config_identity_header)
+          owner, owner_source = owner_for(status, config_owner)
+          adopted = classify(json(%w[serve status --json]), dns_name, port) == :ours
+          public_url = PublicUrl.from_config(url: origin, identity_header: IDENTITY_HEADER, owner: owner)
+          Plan.new(public_url: public_url, owner_source: owner_source, adopted: adopted, lock_off: lock_off?,
+                   port: port, dns_name: dns_name)
+        end
+
+        # Serve 443 → the plan's port, in the background (tailscaled keeps
+        # it until #down, also past a chi web killed hard: the next
+        # --tunnel adopts it). The explicit target: chi web binds 127.0.0.1
+        # only.
+        # @raise [CliFailed, CliTimeout] its output in the message (a consent URL)
+        def up(plan)
+          args = ["serve", "--bg", "--https=443", plan.target]
+          result = run(args, timeout: SERVE_TIMEOUT)
+          raise CliFailed.new(command(args), result.output) unless result.success
+
+          nil
+        end
+
+        # 443 off again, only while Serve has exactly what #up set (the same
+        # test as the adopt): a handler someone added meanwhile, another
+        # target, Funnel, is left as it is (`serve --https=443 off` would drop
+        # all of 443).
+        # @return [Symbol] :off, :changed (left alone), :gone (443 was off already)
+        # @raise [Refused] a command that failed (the caller warns)
+        def down(plan)
+          state = begin
+            classify(json(%w[serve status --json]), plan.dns_name, plan.port)
+          rescue ServeInUse, Funnel
+            :changed
+          end
+          return state == :none ? :gone : state unless state == :ours
+
+          args = %w[serve --https=443 off]
+          result = run(args, timeout: SERVE_TIMEOUT)
+          raise CliFailed.new(command(args), result.output) unless result.success
+
+          :off
+        end
+
+        # What the start lines add: how it is reached and whose login is the
+        # owner, and the Tailnet Lock warning.
+        def start_lines(plan)
+          source = plan.owner_source == :config ? "web.proxy.owner" : "this machine's Tailscale login"
+          via = "         via Tailscale Serve (tailnet only), owner #{plan.public_url.owner} (#{source})"
+          via += "; Serve already forwarded port 443 here, chi web turns it off on exit" if plan.adopted
+          lines = [via]
+          if plan.lock_off
+            lines << "Tailnet Lock is off: a device Tailscale's servers add to your tailnet could reach this page; " \
+                     "tailscale lock init turns it on (#{LOCK_DOCS})"
+          end
+          lines
+        end
+
+        # The line #down's outcome is said in, nil for none.
+        def down_line(plan, outcome)
+          case outcome
+          when :off then "Tailscale Serve: port 443 is off again."
+          when :changed
+            "Tailscale Serve's port 443 changed while chi web ran (#{plan.dns_name}): left as it is " \
+              "(tailscale serve status shows it)"
+          end
+        end
+
+        # A #down that failed: Serve may still forward the name.
+        def down_warning(plan, error)
+          "Warning: Tailscale Serve may still forward #{plan.dns_name} to 127.0.0.1:#{plan.port} (#{error.message}): " \
+            "turn it off with tailscale serve --https=443 off"
+        end
+
+        # What Serve has on 443: :none, :ours (exactly one handler / →
+        # http://127.0.0.1:<port>, no Funnel), or a ServeInUse / Funnel.
+        # Other ports are not looked at.
+        # @raise [ServeInUse, Funnel, UnexpectedOutput]
+        def classify(serve, dns_name, port)
+          raise UnexpectedOutput, command(%w[serve status --json]) unless serve.is_a?(Hash)
+
+          funnel = hash(serve["AllowFunnel"]).find { |key, on| on && https_key?(key) }
+          raise Funnel, funnel.first if funnel
+
+          tcp = hash(serve["TCP"])["443"]
+          web = hash(serve["Web"]).select { |key, _| https_key?(key) }
+          return :none if tcp.nil? && web.empty?
+          return :ours if ours?(tcp, web, dns_name, port)
+
+          raise ServeInUse, describe(tcp, web)
+        end
+
+        private
+
+        def lookup
+          override = @env[ENV_CLI].to_s.strip
+          unless override.empty?
+            return override if executable?(override)
+
+            raise CliOverrideMissing, override
+          end
+          on_path = @env["PATH"].to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
+                                .map { |dir| File.join(dir, "tailscale") }.find { |path| executable?(path) }
+          return on_path if on_path
+          return @app_cli if !Session.test_session_env?(env: @env) && executable?(@app_cli)
+
+          raise CliMissing
+        end
+
+        def executable?(path) = File.file?(path) && File.executable?(path)
+
+        def connected_name(status)
+          raise UnexpectedOutput, command(%w[status --json]) unless status.is_a?(Hash)
+
+          state = status["BackendState"].to_s
+          raise NotRunning, (state.empty? ? "no state" : state) unless state == "Running"
+
+          name = hash(status["Self"])["DNSName"].to_s.strip.downcase.delete_suffix(".")
+          raise NoDnsName if name.empty?
+          raise NoHttps, name unless Array(status["CertDomains"]).any? { |domain| domain.to_s.casecmp?(name) }
+
+          name
+        end
+
+        def check_config(origin, config_public_url, config_identity_header)
+          unless blank?(config_public_url) || configured_origin(config_public_url) == origin
+            raise ConfigConflict.new("web.public_url", config_public_url.to_s.strip, origin)
+          end
+          return if blank?(config_identity_header) || config_identity_header.to_s.strip.casecmp?(IDENTITY_HEADER)
+
+          raise ConfigConflict.new("web.proxy.identity_header", config_identity_header.to_s.strip, IDENTITY_HEADER)
+        end
+
+        def configured_origin(url)
+          PublicUrl.from_config(url: url)&.origin
+        rescue PublicUrl::Invalid
+          nil
+        end
+
+        # [login, :config | :login]
+        def owner_for(status, config_owner)
+          return [config_owner.to_s.strip, :config] unless blank?(config_owner)
+
+          me = hash(status["Self"])
+          tags = Array(me["Tags"])
+          raise TaggedOwner, tags.map(&:to_s) unless tags.empty?
+
+          login = hash(hash(status["User"])[me["UserID"].to_s])["LoginName"].to_s.strip
+          raise UnexpectedOutput, command(%w[status --json]) if login.empty?
+
+          [login, :login]
+        end
+
+        def ours?(tcp, web, dns_name, port)
+          handlers = { "Handlers" => { "/" => { "Proxy" => "http://127.0.0.1:#{port}" } } }
+          tcp == { "HTTPS" => true } && web.size == 1 && web.keys.first.casecmp?("#{dns_name}:443") &&
+            web.values.first == handlers
+        end
+
+        def describe(tcp, web)
+          parts = web.values.flat_map do |entry|
+            hash(hash(entry)["Handlers"]).map { |path, handler| "#{path} → #{handler_target(handler)}" }
+          end
+          forward = hash(tcp)["TCPForward"]
+          parts << "TCP → #{forward}" if forward
+          parts.empty? ? "a configuration chi web didn't make" : parts.join(", ")
+        end
+
+        def handler_target(handler)
+          handler = hash(handler)
+          handler["Proxy"] || (handler["Path"] && "files #{handler["Path"]}") || (handler.key?("Text") && "text") ||
+            handler.keys.join("/")
+        end
+
+        def https_key?(key) = key.to_s.end_with?(":443")
+
+        # Tailnet Lock is off (Enabled false); a failure says nothing.
+        def lock_off?
+          json(%w[lock status --json]).then { |lock| lock.is_a?(Hash) && lock["Enabled"] == false }
+        rescue Refused
+          false
+        end
+
+        def json(args)
+          result = run(args, timeout: STATUS_TIMEOUT)
+          raise CliFailed.new(command(args), result.output) unless result.success
+
+          JSON.parse(result.stdout)
+        rescue JSON::ParserError
+          raise UnexpectedOutput, command(args)
+        end
+
+        def run(args, timeout:)
+          @runner.call([cli, *args], timeout: timeout)
+        rescue Runner::Timeout => e
+          raise CliTimeout.new(command(args), timeout, e.output)
+        rescue SystemCallError => e
+          raise CliFailed.new(command(args), e.message)
+        end
+
+        def command(args) = ["tailscale", *args].join(" ")
+        def hash(value) = value.is_a?(Hash) ? value : {}
+        def blank?(value) = value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/samagotchi/web/tunnel.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../config"
+
+module Samagotchi
+  module Web
+    # `chi web --tunnel PROVIDER`: chi web reached from outside this machine
+    # through a provider that gives it an https name and tells it who is
+    # asking (Tailscale Serve: docs/configuration.md "Tailscale Serve"). The
+    # provider checks what it can before anything changes (#prepare), turns
+    # the tunnel on (#up) and off again on exit (#down), never touching what
+    # it didn't set. The public_url it makes is this run's, never written to
+    # config.yml.
+    module Tunnel
+      PROVIDERS = %w[tailscale].freeze
+
+      # What a tunnel's #prepare found: the PublicUrl chi web runs with this
+      # time, whose login is the owner (:config for web.proxy.owner, :login
+      # for this machine's own), whether the serve was already there (a
+      # leftover of an earlier run: #down resets it all the same), whether
+      # Tailnet Lock is off (a warning line), and the port it forwards to.
+      Plan = Data.define(:public_url, :owner_source, :adopted, :lock_off, :port, :dns_name) do
+        def target = "http://127.0.0.1:#{port}"
+      end
+
+      # Why `chi web --tunnel` won't start: each condition its own class and
+      # its own text (callers add only context).
+      class Refused < StandardError; end
+
+      # @return [Tailscale] the provider +name+ names
+      # @raise [ArgumentError] an unknown name (the flag's list refuses it first)
+      def self.for(name, **)
+        case name.to_s
+        when "tailscale"
+          require_relative "tunnel/tailscale"
+          Tailscale.new(**)
+        else raise ArgumentError, "unknown tunnel #{name} (#{PROVIDERS.join(", ")})"
+        end
+      end
+
+      # A web.public_url or web.proxy.identity_header setting the tunnel would
+      # override for its run.
+      class ConfigConflict < Refused
+        def initialize(key, value, tunnel_value)
+          env = Config::BY_KEY.fetch(key).env_key
+          super("#{key} is #{value}, but --tunnel sets it to #{tunnel_value} for this run: remove it from config.yml " \
+                "or the environment (#{env}), or drop --tunnel")
+        end
+      end
+
+      # A chi web already answers on the port: --tunnel starts its own.
+      class AlreadyRunning < Refused
+        def initialize(port)
+          super("chi web already runs on port #{port}, and --tunnel starts its own: stop that one first (Ctrl-C in its " \
+                "terminal), or use --port")
+        end
+      end
+
+      # The provider's command exited with an error.
+      class CliFailed < Refused
+        def initialize(command, output)
+          text = output.to_s.strip
+          super("#{command} failed#{text.empty? ? " (no output)" : ": #{text}"}")
+        end
+      end
+
+      # The provider's command didn't finish in time (stopped): a tailnet
+      # where Serve isn't allowed yet prints a consent URL and waits.
+      class CliTimeout < Refused
+        def initialize(command, seconds, output)
+          text = output.to_s.strip
+          super("#{command} didn't finish in #{seconds} s and was stopped#{": #{text}" unless text.empty?}" \
+                "#{" (if it printed a URL, open it to allow this, then run chi web again)" unless text.empty?}")
+        end
+      end
+
+      # The provider's command printed something chi can't read: never a
+      # guess that could change the wrong thing.
+      class UnexpectedOutput < Refused
+        def initialize(command)
+          super("#{command} printed something chi can't read (a newer version?); nothing was changed")
+        end
+      end
+
+      # A command run with a deadline: its own process group, both pipes read
+      # on threads, the group KILLed past +timeout+ (what it printed so far
+      # goes into the Timeout).
+      class Runner
+        Result = Data.define(:stdout, :stderr, :success) do
+          def output = [stdout, stderr].map(&:to_s).reject(&:empty?).join("\n")
+        end
+
+        class Timeout < StandardError
+          attr_reader :output
+
+          def initialize(output)
+            @output = output
+            super("timed out")
+          end
+        end
+
+        # @return [Result]
+        # @raise [Timeout]
+        # @raise [SystemCallError] the command can't run (ENOENT, EACCES)
+        def call(argv, timeout:)
+          Open3.popen3(*argv, pgroup: true) do |stdin, out, err, wait|
+            stdin.close
+            readers = [out, err].map { |io| Thread.new { io.read }.tap { |t| t.report_on_exception = false } }
+            unless wait.join(timeout)
+              stop(wait.pid)
+              readers.each { |reader| reader.join(1) }
+              raise Timeout, readers.map { |reader| text(reader) }.reject(&:empty?).join("\n")
+            end
+            # A process it left behind may hold the pipes: what was read by then.
+            readers.each { |reader| reader.join(1) }
+            Result.new(stdout: text(readers[0]), stderr: text(readers[1]), success: wait.value.success?)
+          end
+        end
+
+        private
+
+        def text(reader) = reader.alive? ? "" : reader.value.to_s
+
+        def stop(pid)
+          Process.kill("KILL", -pid)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end