wsv 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d932b12a288921b6935081095a656825c9efaaabb9d086350104c6d92c76d42
-  data.tar.gz: 91c097132033a2030f4e5e9f8f4aa9c799078e7006320cbfff566ea88ae6c1b9
+  metadata.gz: 782b303e2d6eeb0f45f6b3a012523b94611a4991d59ef6669768b21936f47a8e
+  data.tar.gz: 25b99b347007975bac86ccd93c212f5fb0bc85522054c36badac601bae5f3638
 SHA512:
-  metadata.gz: a272e137f58400e80dd58d4d32f6dd1f998ee5eb148c281d95674be1b087ea72c966ea4d3b84381b28589181d0e3e1a787accea3133e899f2dd8490c04ace055
-  data.tar.gz: 7250c73ce5e90e6c85d598b5966bdc01467bc5aeff6869c3e63e2031a8f7c7d2baa8d873f0e347bf76d55e7e567787ba041cd3c4b790a2d192b5ff8fc806d2de
+  metadata.gz: b3619a62d69f29a3498081d8174a0a01c61484ede73f9875de9867b4a4dd451f639dcbe0bee99fb3bea00b78c0ba289618ab7eeec3b066705d8ca437a9cea134
+  data.tar.gz: c58379c2eab12176f492d993d1e194dc0f3a33c16ba7d8736134498e4d13ce8031816a5d22688f1639c0ea3127c5787ad4c235874b20929490eac52881c3e9b0

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.10.1
+
+- Update gem description and README tagline to position wsv as
+  "Defensive by design" — surfaces the actual security defaults on
+  RubyGems.org and `gem search` (the 0.10.0 description still said
+  "tiny static web server").
+- Refactor `Wsv::Server` (~250 → 150 lines): per-connection lifecycle
+  is now `Server::Connection` (`#serve` / `#reject` + safe write /
+  drain / close), concurrency cap is `Server::ConnectionThrottle`
+  (`#try_spawn`). Behavior unchanged.
+- Extract `Server::UrlHost.format` so `Banner` and `BrowserLauncher`
+  share the IPv6 bracketing / RFC 6874 zone-id encoding rule (was
+  duplicated in two places, fixed in tandem once already).
+- Simplify `Response::FileBuilder` body construction: the HEAD guard
+  and range/full body branch collapse into a single method.
+- Move executable from `bin/wsv` to `exe/wsv` per Bundler convention.
+- Various README polish: Gemfile install path first, Examples for
+  Jekyll / Astro / Vite, GHFM `> [!WARNING]` for the prod-use caveat.
+
+## 0.10.0
+
+- Add `--cors` flag. When set, every response carries
+  `Access-Control-Allow-Origin: *` and `Vary: Origin`, and `OPTIONS`
+  preflight requests get `204 No Content` with `Access-Control-Allow-Methods:
+  GET, HEAD, OPTIONS` (echoing `Access-Control-Request-Headers` when
+  present). Unblocks browser fetches from a frontend served on a different
+  port (or a Service Worker) during local development. Matches the `--cors`
+  convention used by `http-server`, `serve`, and `live-server`. Without the
+  flag, no CORS headers are added and `OPTIONS` continues to return `405`.
+- Add `--open` flag that launches the OS default browser at the served URL
+  on startup. Uses `open` (macOS), `xdg-open` (Linux/BSD), or `cmd /c start`
+  (Windows). Best-effort: unsupported platforms or spawn failures are logged
+  but never abort the server. Wildcard binds (`0.0.0.0`, `::`) translate to
+  the matching loopback address for the URL.
+- Custom 404 page convention: when the served directory contains a
+  `404.html` file, it is served as the body of every `404 Not Found`
+  response (`Content-Type: text/html`) instead of the built-in plain
+  text. Matches Jekyll / Hugo / Netlify behaviour. `403` and other
+  error statuses are not rewritten.
+- Add `--spa` flag for single-page-app routing: a request whose path resolves
+  to `404` falls back to the root `index.html` so client-side routers (React
+  Router, Vue Router, etc.) get the SPA shell instead of a real 404. `403`
+  and other errors are unaffected -- dotfile and traversal blocks still
+  apply, and existing files at the requested path are served normally.
+- Send `X-Content-Type-Options: nosniff` on every response so browsers
+  honour the declared `Content-Type` instead of MIME-sniffing the body.
+- TLS / HTTPS support via Ruby's built-in `openssl` (no extra gem dependency).
+  - `--tls` enables HTTPS. Without `--cert / --key`, wsv looks for
+    `~/.config/wsv/cert.pem` and `~/.config/wsv/key.pem` (respecting
+    `XDG_CONFIG_HOME`); if neither is present, an ephemeral self-signed
+    certificate is generated in memory and a warning is printed.
+  - `--cert PATH --key PATH` uses a user-supplied PEM cert / key pair and
+    implies `--tls`. Specifying only one of the two is an error.
+  - `~/.config/wsv/` (or `$XDG_CONFIG_HOME/wsv/`) is the recommended location
+    for mkcert-issued certificates: `mkcert -cert-file ~/.config/wsv/cert.pem
+    -key-file ~/.config/wsv/key.pem localhost 127.0.0.1 ::1`.
+  - The HTTP scheme in the startup banner switches to `https://` when TLS is
+    enabled.
+  - The TLS handshake honours the per-request read deadline, so slow-handshake
+    clients cannot hold a worker beyond the configured timeout.
+
 ## 0.9.0
 
 - Normalize the redirect `Location` to an origin-form path. Previously, an

data/README.md

@@ -1,20 +1,27 @@
 # wsv
 
-`wsv` is a minimal static web server for local previews.
+`wsv` is a zero-dependency static preview server for Ruby projects. Defensive by design: blocks dotfiles and binds to loopback by default.
 
-It has no runtime dependencies outside Ruby's standard library. Run `wsv` in a directory and it serves that directory over HTTP.
+It has no runtime dependencies outside Ruby's standard library. Run `wsv` in a directory and it serves that directory over HTTP/HTTPS.
+
+Requires Ruby 3.2 or later.
 
 ## Installation
 
-```sh
-gem install wsv
+Add to your Gemfile:
+
+```ruby
+group :development do
+  gem "wsv"
+end
 ```
 
-For local development:
+Then run `bundle install` and start with `bundle exec wsv`.
+
+Or install globally:
 
 ```sh
-gem build wsv.gemspec
-gem install ./wsv-0.1.0.gem
+gem install wsv
 ```
 
 ## Usage
@@ -26,8 +33,11 @@ wsv [options] [directory]
 Examples:
 
 ```sh
-wsv
-wsv public
+wsv                       # serve current directory
+wsv _site                 # Jekyll / Bridgetown output
+wsv build                 # Astro / Hugo output
+wsv --spa dist            # Vite / esbuild / webpack SPA output
+wsv --tls --open          # HTTPS, open browser at startup
 wsv -h 0.0.0.0 -p 3000 ./dist
 ```
 
@@ -36,10 +46,43 @@ Options:
 ```text
 -h, --host HOST    Bind host (default: 127.0.0.1)
 -p, --port PORT    Bind port (default: 8000)
+    --tls          Enable HTTPS (uses ~/.config/wsv/{cert,key}.pem if both present, else self-signed)
+    --cert PATH    TLS certificate file (PEM); implies --tls
+    --key PATH     TLS private key file (PEM); implies --tls
+    --spa          Single-page-app mode: fall back to root index.html on 404
+    --open         Open the served URL in the default browser at startup
+    --cors         Send Access-Control-Allow-Origin: * on every response
     --help         Show help
     --version      Show version
 ```
 
+## TLS / HTTPS
+
+`--tls` enables HTTPS on the chosen `--port`. Three modes:
+
+1. Ephemeral self-signed: `wsv --tls` with no cert configured: wsv
+   generates an in-memory self-signed certificate. Browsers will show a
+   security warning; click through "Advanced → Proceed" once per session.
+2. `~/.config/wsv/` auto-detection (recommended): if both
+   `~/.config/wsv/cert.pem` and `~/.config/wsv/key.pem` exist (resolved via
+   `$XDG_CONFIG_HOME` if set), `--tls` uses them. If only one of the two
+   files is present, wsv refuses to start so the misconfiguration does not
+   silently fall back to a self-signed certificate. Combine with
+   [mkcert](https://github.com/FiloSottile/mkcert) to skip browser warnings:
+
+   ```sh
+   mkcert -install     # one-time: register a local CA in your trust stores
+   mkdir -p ~/.config/wsv
+   mkcert -cert-file ~/.config/wsv/cert.pem \
+          -key-file  ~/.config/wsv/key.pem  \
+          localhost 127.0.0.1 ::1
+   chmod 600 ~/.config/wsv/key.pem
+   wsv --tls           # → https://localhost:8000/ with no warning
+   ```
+
+3. Explicit cert/key files: `wsv --cert path/to/cert.pem --key path/to/key.pem`
+   for project-specific certificates. Both flags must be provided together.
+
 ## Behavior
 
 - Serves files from the selected directory.
@@ -50,10 +93,24 @@ Options:
 - Honours `If-Modified-Since` and returns `304 Not Modified` when applicable.
 - Rejects paths that resolve outside the served directory.
 - Sends `Cache-Control: no-cache` so the browser revalidates each request.
+- With `--spa`, serves the root `index.html` instead of `404` when a path
+  resolves to "not found" (so client-side routers like React Router or
+  Vue Router work). `403` and other errors are unaffected, so dotfile and
+  traversal blocks still apply.
+- If the served directory contains a `404.html` file, it is served as the
+  body of every `404 Not Found` response (with `Content-Type: text/html`)
+  instead of the built-in plain text. Matches the convention of Jekyll,
+  Hugo, and many static hosts.
+- With `--cors`, every response carries `Access-Control-Allow-Origin: *`
+  (and `Vary: Origin`), and `OPTIONS` preflight requests get `204 No Content`
+  with the matching CORS headers. Lets a frontend on a different port (or a
+  Service Worker) fetch assets from `wsv` during local development.
 
 ## Security model
 
-`wsv` is intended for **local development previews, not for production or internet-facing use**.
+> [!WARNING]
+> `wsv` is intended for local development previews, not for production or internet-facing use.
+
 Within that scope it tries to behave defensively:
 
 ### What `wsv` protects against
@@ -77,16 +134,22 @@ Within that scope it tries to behave defensively:
   (default 10s, configurable). Stalled connections receive `408`.
 - Header injection — CR/LF in response header values is rejected at
   construction time, so user-derived strings cannot inject extra headers.
+- MIME sniffing — every response carries `X-Content-Type-Options: nosniff`
+  so browsers honour the declared `Content-Type` rather than guessing from
+  body contents.
 - Single-client monopolisation — connections are handled by a thread pool
-  capped at `max_connections` (default 8). Excess clients receive `503`.
+  capped at `max_connections` (default 8). Excess clients receive `503`
+  (or are closed without response in TLS mode, since writing plaintext over
+  a half-handshaked TLS socket would corrupt the client's view of the
+  protocol).
 - Transient `accept(2)` errors — per-connection failures (`ECONNABORTED`,
   `EMFILE`, etc.) are logged and skipped instead of killing the server.
 
 ### What `wsv` does NOT do
 
 - Authentication, authorization, or rate limiting.
-- TLS / HTTPS.
 - HTTP keep-alive (each response sets `Connection: close`).
+- HTTP/2. Use Caddy / nginx as a front proxy if you need it.
 - ETags / `If-None-Match`.
 - Production-grade DoS resistance under hostile network load.
 - Defend against TOCTOU attacks from other local processes that can write
@@ -106,8 +169,7 @@ If you need any of the above, use a real production server.
 `wsv` follows [Semantic Versioning](https://semver.org/). The public API
 that SemVer covers is the CLI:
 
-- The flags listed above (`-h` / `--host`, `-p` / `--port`, `--help`,
-  `--version`) and their meanings.
+- The flags listed in Options above and their meanings.
 - The directory argument and the default behaviour when it is omitted.
 - Process exit codes (`0` for success, `1` for usage / setup errors).
 
@@ -115,11 +177,9 @@ Within a major version, `wsv` will not silently change the default bind
 host, default port, the dotfile-blocking rule, or the security posture in
 ways that would surprise an existing user.
 
-The Ruby classes inside `lib/wsv/` (`Wsv::Server`, `Wsv::App`,
-`Wsv::PathResolver`, `Wsv::Request`, `Wsv::Response`, `Wsv::MimeTypes`,
-`Wsv::Status`) are implementation details. They may change at any
-time, including in patch releases. If you want to embed `wsv` as a
-library, pin a specific version.
+The Ruby classes inside `lib/wsv/` are implementation details. They may
+change in any release, including patches. Pin the gem version if you
+embed `wsv` as a library.
 
 ## License
 

data/lib/wsv/app.rb

@@ -2,6 +2,7 @@
 
 require "time"
 require "uri"
+require_relative "cors"
 require_relative "path_resolver"
 require_relative "response"
 
@@ -10,27 +11,59 @@ module Wsv
     ALLOWED_METHODS = %w[GET HEAD].freeze
     RANGE_PATTERN = /\Abytes=(\d+)?-(\d+)?\z/
 
-    def initialize(root)
+    def initialize(root, spa: false, cors: false)
       @resolver = PathResolver.new(root)
+      @spa = spa
+      @cors = Cors.new if cors
     end
 
     def call(request)
+      return @cors.preflight(request) if @cors && request.method == "OPTIONS"
+
+      response = build_response(request)
+      @cors ? @cors.overlay(response) : response
+    end
+
+    private
+
+    def build_response(request)
       head = request.head?
 
       unless ALLOWED_METHODS.include?(request.method)
-        return Response.text(405, headers: { "Allow" => "GET, HEAD" }, head: head)
+        return Response.text(405, headers: { "Allow" => allow_methods }, head: head)
       end
 
       raw_path, query = request.target.split("?", 2)
       result = @resolver.resolve(raw_path)
 
-      return Response.text(result.status, head: head) if result.error?
+      # SPA fallback: when the path resolves to 404, retry with "/" so client-side
+      # routes (React Router etc.) get index.html instead of a real 404. Other
+      # error statuses (403/400) are not rewritten, so dotfile / traversal blocks
+      # still take effect.
+      if @spa && result.error? && result.status == 404
+        fallback = @resolver.resolve("/")
+        result = fallback if fallback.file?
+      end
+
+      return error_response(result.status, head: head) if result.error?
       return Response.redirect(redirect_location(raw_path, query), head: head) if result.redirect?
 
       file_response(result.file, request, head: head)
     end
 
-    private
+    def allow_methods
+      @cors ? Cors::ALLOW_METHODS : "GET, HEAD"
+    end
+
+    def error_response(status, head:)
+      if status == 404
+        # Custom 404 page convention: when the served root contains a `404.html`
+        # file, serve it as the body of any 404 response (Content-Type: text/html).
+        custom = @resolver.resolve("/404.html")
+        return Response.file(custom.file, status: 404, head: head) if custom.file?
+      end
+      Response.text(status, head: head)
+    end
 
     def file_response(file, request, head:)
       return Response.not_modified if not_modified?(file, request.headers["if-modified-since"])
@@ -60,6 +93,8 @@ module Wsv
       return nil if header_value.nil? || header_value.empty?
 
       match = header_value.match(RANGE_PATTERN)
+      # Per RFC 7233, an unparseable Range is treated as if absent: fall
+      # through as nil so the caller serves a normal 200 instead of 416.
       return nil unless match
 
       first, last = match.captures

data/lib/wsv/cli.rb

@@ -21,7 +21,13 @@ module Wsv
       return 0 if options[:handled]
 
       root = resolve_root(options[:directory])
-      server = Server.new(host: options[:host], port: options[:port], root: root, out: @out, err: @err)
+      tls = resolve_tls(options)
+      server = Server.new(
+        host: options[:host], port: options[:port], root: root,
+        out: @out, err: @err, tls: tls,
+        spa: options[:spa] || false, open: options[:open] || false,
+        cors: options[:cors] || false
+      )
       server.start
       0
     rescue OptionParser::ParseError, ArgumentError => e
@@ -33,14 +39,14 @@ module Wsv
       1
     end
 
-    def parse_options(args)
+    def parse_options(args) # rubocop:disable Metrics/AbcSize
       options = {
         host: DEFAULT_HOST,
         port: DEFAULT_PORT,
         directory: Dir.pwd
       }
 
-      parser = OptionParser.new do |opts|
+      parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
         opts.banner = "Usage: wsv [options] [directory]"
 
         opts.on("-h", "--host HOST", "Bind host (default: #{DEFAULT_HOST})") do |host|
@@ -51,6 +57,30 @@ module Wsv
           options[:port] = validate_port(port)
         end
 
+        opts.on("--tls", "Enable HTTPS (uses ~/.config/wsv/{cert,key}.pem if both present, else self-signed)") do
+          options[:tls] = true
+        end
+
+        opts.on("--cert PATH", "TLS certificate file (PEM); implies --tls") do |path|
+          options[:cert] = path
+        end
+
+        opts.on("--key PATH", "TLS private key file (PEM); implies --tls") do |path|
+          options[:key] = path
+        end
+
+        opts.on("--spa", "Single-page-app mode: fall back to root index.html on 404") do
+          options[:spa] = true
+        end
+
+        opts.on("--open", "Open the served URL in the default browser at startup") do
+          options[:open] = true
+        end
+
+        opts.on("--cors", "Send Access-Control-Allow-Origin: * on every response") do
+          options[:cors] = true
+        end
+
         opts.on("--help", "Show help") do
           @out.puts opts
           options[:handled] = true
@@ -60,6 +90,14 @@ module Wsv
           @out.puts Wsv::VERSION
           options[:handled] = true
         end
+
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "    wsv                  # serve current dir"
+        opts.separator "    wsv _site            # Jekyll / Bridgetown output"
+        opts.separator "    wsv build            # Astro / Hugo output"
+        opts.separator "    wsv --spa dist       # Vite / esbuild / webpack SPA output"
+        opts.separator "    wsv --tls --open     # HTTPS, open browser"
       end
 
       parser.parse!(args)
@@ -84,5 +122,13 @@ module Wsv
 
       port
     end
+
+    def resolve_tls(options)
+      return nil unless options[:tls] || options[:cert] || options[:key]
+
+      TlsContext::Resolver.resolve(cert_path: options[:cert], key_path: options[:key])
+    rescue OpenSSL::OpenSSLError => e
+      raise ArgumentError, "TLS configuration error: #{e.message}"
+    end
   end
 end

data/lib/wsv/cors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "response"
+
+module Wsv
+  class Cors
+    ALLOW_ORIGIN = "*"
+    ALLOW_METHODS = "GET, HEAD, OPTIONS"
+    MAX_AGE = "86400"
+
+    def preflight(request)
+      headers = {
+        "Access-Control-Allow-Origin" => ALLOW_ORIGIN,
+        "Access-Control-Allow-Methods" => ALLOW_METHODS,
+        "Access-Control-Max-Age" => MAX_AGE,
+        "Vary" => "Origin"
+      }
+      requested = request.headers["access-control-request-headers"]
+      headers["Access-Control-Allow-Headers"] = requested if requested
+      Response.new(status: 204, headers: headers)
+    end
+
+    def overlay(response)
+      response.with_headers(
+        "Access-Control-Allow-Origin" => ALLOW_ORIGIN,
+        "Vary" => "Origin"
+      )
+    end
+  end
+end

data/lib/wsv/path_resolver.rb

@@ -50,6 +50,12 @@ module Wsv
       decoded = decode(raw_path)
       return Result.error(400) unless decoded
 
+      # Layered defense:
+      #   1. URL-level: reject `..` traversal and dotfile segments before
+      #      touching the filesystem.
+      #   2. realpath-level: re-check after symlinks resolve, so an internal
+      #      symlink cannot smuggle access to outside-root paths or to
+      #      `.git/` / `.env` etc. via a non-dotfile-looking URL.
       relative = decoded.sub(%r{\A/+}, "")
       return Result.error(403) if hidden_segment?(relative)
 

data/lib/wsv/request/parser.rb

@@ -13,7 +13,7 @@ module Wsv
       end
 
       def parse
-        line = @io.gets(REQUEST_LINE_LIMIT)
+        line = @io.gets("\n", REQUEST_LINE_LIMIT)
         return :empty unless line
         raise TooLarge, 414 if line.bytesize >= REQUEST_LINE_LIMIT && !line.end_with?("\n")
 
@@ -30,7 +30,7 @@ module Wsv
         headers = {}
         total = 0
         count = 0
-        while (line = @io.gets(HEADER_LINE_LIMIT))
+        while (line = @io.gets("\n", HEADER_LINE_LIMIT))
           raise TooLarge, 431 if line.bytesize >= HEADER_LINE_LIMIT && !line.end_with?("\n")
 
           stripped = line.delete_suffix("\r\n").delete_suffix("\n").delete_suffix("\r")

data/lib/wsv/request/too_large.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Request
+    # Raised by Request::Parser when the incoming request line, an individual
+    # header line, the total header bytes, or the header count exceeds the
+    # configured limit. The status_code chooses between 414 (URI Too Long)
+    # and 431 (Request Header Fields Too Large) at the call site.
+    class TooLarge < StandardError
+      attr_reader :status_code
+
+      def initialize(status_code)
+        super("request exceeded size limit (#{status_code})")
+        @status_code = status_code
+      end
+    end
+  end
+end

data/lib/wsv/request.rb

@@ -1,18 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "request/too_large"
 require_relative "request/parser"
 
 module Wsv
   class Request
-    class TooLarge < StandardError
-      attr_reader :status_code
-
-      def initialize(status_code)
-        super("request exceeded size limit (#{status_code})")
-        @status_code = status_code
-      end
-    end
-
     attr_reader :method, :target, :version, :headers
 
     def initialize(method:, target:, version:, headers:)

data/lib/wsv/response/file_builder.rb

@@ -6,17 +6,18 @@ require_relative "../mime_types"
 module Wsv
   class Response
     class FileBuilder
-      def initialize(path, head: false, range: nil)
+      def initialize(path, head: false, range: nil, status: 200)
         @path = path
         @head = head
         @range = range
+        @status = status
       end
 
       def build
         if @range
-          Response.new(status: 206, headers: range_headers, body: range_body)
+          Response.new(status: 206, headers: range_headers, body: body)
         else
-          Response.new(status: 200, headers: full_headers, body: full_body)
+          Response.new(status: @status, headers: full_headers, body: body)
         end
       end
 
@@ -46,17 +47,12 @@ module Wsv
         base_headers.merge("Content-Length" => size.to_s)
       end
 
-      def range_body
+      def body
         return StringBody.new("") if @head
+        return FileBody.new(@path) unless @range
 
         FileBody.new(@path, offset: @range.begin, length: @range.size)
       end
-
-      def full_body
-        return StringBody.new("") if @head
-
-        FileBody.new(@path)
-      end
     end
   end
 end

data/lib/wsv/response.rb

@@ -31,10 +31,19 @@ module Wsv
       Status.reason(status)
     end
 
+    # Returns a new Response with `extra` merged into the headers, sharing the
+    # same body object so streaming (FileBody) is preserved.
+    def with_headers(extra)
+      self.class.new(status: @status, headers: @headers.merge(extra), body: @body)
+    end
+
     def write_to(io)
       io.write "HTTP/1.1 #{status} #{reason}\r\n"
       io.write "Server: #{SERVER_NAME}\r\n"
       io.write "Connection: close\r\n"
+      unless headers.any? { |name, _value| name.to_s.casecmp?("X-Content-Type-Options") }
+        io.write "X-Content-Type-Options: nosniff\r\n"
+      end
       headers.each { |name, value| io.write "#{name}: #{value}\r\n" }
       io.write "\r\n"
       @body.write_to(io)

data/lib/wsv/server/banner.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "url_host"
+
+module Wsv
+  class Server
+    # Renders the startup announcement (the "Serving / Bind / Local / Stop"
+    # block plus warnings about non-loopback binds and self-signed certs).
+    class Banner
+      def initialize(host:, port:, root:, out:, err:, tls:)
+        @host = host
+        @port = port
+        @root = root
+        @out = out
+        @err = err
+        @tls = tls
+      end
+
+      def emit
+        @out.puts "Serving: #{@root}"
+        @out.puts "Bind:    #{url_for(@host)}"
+        @out.puts "Local:   #{url_for('127.0.0.1')}" unless localhost?(@host)
+        @out.puts "Stop:    Ctrl-C"
+        warn_public_bind unless localhost?(@host)
+        warn_ephemeral_cert if @tls&.ephemeral?
+      end
+
+      private
+
+      def warn_public_bind
+        @err.puts "WARNING: binding to #{@host} exposes #{@root} on your network."
+        @err.puts "         Pass --host 127.0.0.1 (or omit --host) for local-only access."
+      end
+
+      def warn_ephemeral_cert
+        @err.puts "WARNING: serving with a self-signed certificate. Browsers will"
+        @err.puts "         show a security warning. Pass --cert / --key for a real cert."
+      end
+
+      def url_for(display_host)
+        "#{scheme}://#{UrlHost.format(display_host)}:#{@port}/"
+      end
+
+      def scheme
+        @tls ? "https" : "http"
+      end
+
+      def localhost?(display_host)
+        ["127.0.0.1", "localhost", "::1"].include?(display_host)
+      end
+    end
+  end
+end