wsv 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adfd569857554409cef36ce05205eb50f833a58a27e654e1da80646afa2ec40e
-  data.tar.gz: 8d5c75289dd59dc65412ebff24bf0cf4d9aa9933befb17354f9b2fb3320b5ca3
+  metadata.gz: 77baaa8165944bc789ad3054605d4c3283ece7b4592c9477c117495bfa48e2fb
+  data.tar.gz: 1ecf4ef75a3b99e08d61a985de7f06f83622d92b0b2df769f27a937856cd185c
 SHA512:
-  metadata.gz: b4514041977a6c9a599ea9f2a3735f7b4668ab18172b974453293c444c4441221e068f9374cbdd6c5058b99ecb776edbe47bda3bff4fd77731dbeb9b45cd9446
-  data.tar.gz: f1d06286b164b0f70dce52d7fd86b9fdf29c64f6cbc0515e3d26558afb4498d23277fc23b66709298afffb593e321a21498cc55dea2ab8b58e31186b48aaa021
+  metadata.gz: 51247e6eb2b43639dc127e44c1b0ca27feb1cb8ba7ef25120ff744343fb839893860e8091c689beb5e9db45fa9a875f59e42391681eb973d2c2c25de7d9855c7
+  data.tar.gz: b9434026433cc3d54f742bd099ac0afd705c96f169ed1c6067fd1f58b13fff0c61f4c2257d2cffedb0e7c15a193f07b2156f2d7776c2de3c1b50790d13d271a0

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.12.0
+
+- Add `Wsv::Server.new(... app:)` so callers can plug a custom request
+  handler in place of the default static file server. Any object whose
+  `#call(request)` returns a `Wsv::Response` works; the surrounding
+  connection / throttling / access-log / CORS / TLS machinery is reused.
+- Add `Wsv::Response.sse { |io| ... }` for custom `app:` handlers that
+  need Server-Sent Events or other streaming responses without a
+  precomputed `Content-Length`. The helper emits
+  `Content-Type: text/event-stream; charset=utf-8`,
+  `Cache-Control: no-cache`, and `X-Accel-Buffering: no`, writes
+  chunks directly to the client socket, and ends the response when the
+  block returns.
+- Enable `TCP_NODELAY` on accepted client sockets so small writes (SSE
+  frames, response headers) are flushed immediately instead of waiting in
+  the kernel send buffer for a Nagle ACK. Set before any TLS wrap; NODELAY
+  is a TCP-layer option that persists through SSL.
+- Per-request access log on stdout in Common Log Format
+  (`host - - [date] "method target version" status bytes`). Matches the
+  default behavior of `python -m http.server`, `http-server`, `serve`,
+  `live-server`, `miniserve`, `darkhttpd`, `puma`, `rails server`, and
+  WEBrick. Pass `-q` / `--quiet` to suppress. Concurrent connections share
+  a mutex so log lines never interleave. Control chars, quotes, and
+  backslashes in the request line are escaped as `\xNN` to prevent log
+  injection from a hostile client.
+- **Breaking (CLI):** `-h` is now `--help` instead of `--host`, matching the
+  Unix convention used by every other static / dev server (Python's
+  `http.server`, Jekyll, Rails, Puma, `http-server`, `serve`, miniserve,
+  Hugo, Caddy). Use `--host` (long form only) to set the bind address.
+- `--host` accepts bare IPv6 addresses (`--host ::1`) as before, and now
+  also accepts the bracketed form (`--host '[::1]'`) so values copy-pasted
+  from a URL bar do not produce a cryptic `getaddrinfo` error. Zone
+  identifiers are preserved (`[fe80::1%en0]` → `fe80::1%en0`). The combined
+  `[host]:port` form is rejected with a clear error: pass the port via
+  `-p` / `--port`.
+
 ## 0.11.0
 
 - Extract `Wsv::RangeRequest` from `App`. RFC 7233 range parsing

data/README.md

@@ -38,13 +38,13 @@ 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
+wsv --host 0.0.0.0 -p 3000 ./dist
 ```
 
 Options:
 
 ```text
--h, --host HOST    Bind host (default: 127.0.0.1)
+    --host HOST    Bind host (default: 127.0.0.1; accepts IPv6 as `::1` or `[::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
@@ -52,7 +52,8 @@ Options:
     --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
+-q, --quiet        Suppress per-request access log
+-h, --help         Show help
     --version      Show version
 ```
 
@@ -105,6 +106,11 @@ Options:
   (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.
+- One Common Log Format line per request is written to stdout
+  (`127.0.0.1 - - [10/Oct/2000:13:55:36 +0900] "GET / HTTP/1.1" 200 1234`).
+  Pass `--quiet` (or `-q`) to suppress. Errors and warnings still go to
+  stderr regardless. Control characters and quotes in the request line are
+  escaped as `\xNN` so a hostile client cannot inject log lines.
 
 ## Security model
 

data/lib/wsv/cli.rb

@@ -26,7 +26,8 @@ module Wsv
         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
+        cors: options[:cors] || false,
+        quiet: options[:quiet] || false
       )
       server.start
       0
@@ -49,8 +50,8 @@ module Wsv
       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|
-          options[:host] = host
+        opts.on("--host HOST", "Bind host (default: #{DEFAULT_HOST})") do |host|
+          options[:host] = normalize_host(host)
         end
 
         opts.on("-p", "--port PORT", Integer, "Bind port (default: #{DEFAULT_PORT})") do |port|
@@ -81,7 +82,11 @@ module Wsv
           options[:cors] = true
         end
 
-        opts.on("--help", "Show help") do
+        opts.on("-q", "--quiet", "Suppress per-request access log") do
+          options[:quiet] = true
+        end
+
+        opts.on("-h", "--help", "Show help") do
           @out.puts opts
           options[:handled] = true
         end
@@ -123,6 +128,21 @@ module Wsv
       port
     end
 
+    # Accept bracketed IPv6 input as a courtesy (e.g. `--host '[::1]'`)
+    # so users who copy-pasted from a URL bar do not see a cryptic
+    # getaddrinfo error. The combined `[::1]:8000` form is rejected
+    # explicitly: wsv takes host and port via separate flags.
+    def normalize_host(host)
+      return host unless host.start_with?("[")
+      raise ArgumentError, "--host must not include a port; pass it via -p / --port" if host.match?(/\]:\d+\z/)
+      raise ArgumentError, "--host has unbalanced brackets: #{host}" unless host.end_with?("]")
+
+      inner = host[1..-2]
+      raise ArgumentError, "--host bracket value is empty" if inner.empty?
+
+      inner
+    end
+
     def resolve_tls(options)
       return nil unless options[:tls] || options[:cert] || options[:key]
 

data/lib/wsv/response/sse_body.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Response
+    # Body for Server-Sent Events responses. The producer block receives the
+    # client socket and writes SSE frames until it returns; the surrounding
+    # Connection then closes the TCP connection. Write errors after the peer
+    # disconnects (EPIPE, ECONNRESET, IOError) propagate out of #write_to and
+    # are swallowed by Connection#write, so producers do not need their own
+    # rescue. Producers should `io.flush` after each frame to defeat TCP
+    # buffering.
+    #
+    # `bytesize` returns 0 because SSE streams have no a-priori known size.
+    # AccessLog renders 0 bytes as `-` in Common Log Format.
+    class SseBody
+      def initialize(&producer)
+        raise ArgumentError, "block required" unless producer
+
+        @producer = producer
+      end
+
+      def to_s
+        raise NotImplementedError, "SseBody has no static representation; use #write_to(io)"
+      end
+
+      def bytesize
+        0
+      end
+
+      def write_to(io)
+        @producer.call(io)
+      end
+    end
+  end
+end

data/lib/wsv/response/sse_builder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "sse_body"
+
+module Wsv
+  class Response
+    # Builds a Server-Sent Events Response.
+    #
+    #   Wsv::Response.sse do |io|
+    #     io.write("data: ping\n\n")
+    #     io.flush
+    #   end
+    #
+    # `Connection: close` is set by Response#write_to, so the body terminates
+    # when the producer block returns. SSE clients (browsers) re-connect
+    # automatically.
+    class SseBuilder
+      DEFAULT_HEADERS = {
+        "Content-Type" => "text/event-stream; charset=utf-8",
+        "Cache-Control" => "no-cache",
+        # X-Accel-Buffering disables response buffering on reverse proxies
+        # that respect it (nginx). Without this an SSE stream behind a
+        # proxy would only deliver after the connection ended.
+        "X-Accel-Buffering" => "no"
+      }.freeze
+
+      def initialize(status: 200, headers: {}, &producer)
+        @status = status
+        @headers = DEFAULT_HEADERS.merge(headers)
+        @producer = producer
+      end
+
+      def build
+        Response.new(
+          status: @status,
+          headers: @headers,
+          body: SseBody.new(&@producer)
+        )
+      end
+    end
+  end
+end

data/lib/wsv/response.rb

@@ -4,8 +4,10 @@ require_relative "status"
 require_relative "version"
 require_relative "response/string_body"
 require_relative "response/file_body"
+require_relative "response/sse_body"
 require_relative "response/text_builder"
 require_relative "response/file_builder"
+require_relative "response/sse_builder"
 
 module Wsv
   class Response
@@ -27,6 +29,10 @@ module Wsv
       @body.to_s
     end
 
+    def bytesize
+      @body.bytesize
+    end
+
     def reason
       Status.reason(status)
     end
@@ -69,6 +75,12 @@ module Wsv
       TextBuilder.new(416, head: head, headers: { "Content-Range" => "bytes */#{file_size}" }).build
     end
 
+    # Build a Server-Sent Events response. The block receives the client
+    # socket and writes (and flushes) SSE frames until it returns.
+    def self.sse(status: 200, headers: {}, &producer)
+      SseBuilder.new(status: status, headers: headers, &producer).build
+    end
+
     private
 
     def validate_headers(headers)

data/lib/wsv/server/access_log.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Server
+    # Emits one line per served request in Common Log Format. Concurrent
+    # Connection threads share a single AccessLog instance, so writes are
+    # serialized through a mutex to avoid interleaved bytes on @out.
+    class AccessLog
+      def initialize(out:)
+        @out = out
+        @mutex = Mutex.new
+      end
+
+      def record(remote_addr:, request:, status:, bytes:)
+        line = format_line(remote_addr, request, status, bytes)
+        @mutex.synchronize { @out.puts(line) }
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def format_line(remote_addr, request, status, bytes)
+        host = remote_addr || "-"
+        timestamp = Time.now.strftime("[%d/%b/%Y:%H:%M:%S %z]")
+        request_line = format_request_line(request)
+        size = bytes.positive? ? bytes.to_s : "-"
+        %(#{host} - - #{timestamp} "#{request_line}" #{status} #{size})
+      end
+
+      def format_request_line(request)
+        return "-" unless request
+
+        "#{sanitize(request.method)} #{sanitize(request.target)} #{sanitize(request.version)}"
+      end
+
+      # Replace control chars, quote, and backslash so a hostile request line
+      # cannot inject CR/LF or escape the surrounding quotes in the log line.
+      def sanitize(str)
+        str.to_s.gsub(/[\x00-\x1f\x7f"\\]/) { |c| format('\\x%02x', c.ord) }
+      end
+    end
+
+    class NullAccessLog
+      def record(**); end
+    end
+  end
+end

data/lib/wsv/server/connection.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "access_log"
 require_relative "deadline_reader"
 require_relative "../request"
 require_relative "../response"
@@ -13,44 +14,55 @@ module Wsv
     class Connection
       DRAIN_TIMEOUT = 5
 
-      def initialize(client, err:, cors: nil)
+      def initialize(client, err:, cors: nil, access_log: NullAccessLog.new)
         @client = client
         @err = err
         @cors = cors
+        @access_log = access_log
+        @remote_addr = remote_addr_of(client)
       end
 
       def serve(app, read_timeout:)
+        request, response = process(app, read_timeout)
+        write(response) if response
+        log_access(request, response)
+      ensure
+        graceful_close
+      end
+
+      def reject(reply:)
+        response = reply ? Response.text(503) : nil
+        write(response) if response
+        log_access(nil, response)
+      ensure
+        graceful_close
+      end
+
+      private
+
+      def process(app, read_timeout)
         reader = DeadlineReader.new(@client, Time.now + read_timeout)
         request = Request.parse(reader)
-        case request
-        when :empty
-          nil
-        when :malformed
-          write(Response.text(400))
-        else
-          write(app.call(request))
-        end
+        [request, build_response(app, request)]
       rescue Request::TooLarge => e
-        write(Response.text(e.status_code))
+        [nil, Response.text(e.status_code)]
       rescue IO::TimeoutError
-        write(Response.text(408))
+        [nil, Response.text(408)]
       rescue StandardError => e
         # Treat unmapped failures as connection-scoped and close with 400 rather
         # than letting one bad request path bring down the server.
         @err.puts "wsv: #{e.class}: #{e.message}"
-        write(Response.text(400))
-      ensure
-        graceful_close
+        [nil, Response.text(400)]
       end
 
-      def reject(reply:)
-        write(Response.text(503)) if reply
-      ensure
-        graceful_close
+      def build_response(app, request)
+        case request
+        when :empty then nil
+        when :malformed then Response.text(400)
+        else app.call(request)
+        end
       end
 
-      private
-
       # Connection is the sole place that adds ACAO / Vary headers, so every
       # response (App, parser errors, timeouts, the 503 rejection) gets them
       # uniformly when CORS is enabled.
@@ -66,6 +78,24 @@ module Wsv
         @cors ? @cors.overlay(response) : response
       end
 
+      def log_access(request, response)
+        return unless response
+
+        @access_log.record(
+          remote_addr: @remote_addr,
+          request: request.is_a?(Request) ? request : nil,
+          status: response.status,
+          bytes: response.bytesize
+        )
+      end
+
+      def remote_addr_of(client)
+        base = client.respond_to?(:io) ? client.io : client
+        base.peeraddr(false)[3]
+      rescue StandardError
+        nil
+      end
+
       def graceful_close
         return if @client.closed?
 

data/lib/wsv/server.rb

@@ -27,7 +27,9 @@ module Wsv
       tls: nil,
       spa: false,
       open: false,
-      cors: false
+      cors: false,
+      quiet: false,
+      app: nil
     )
       @host = host
       @port = port
@@ -39,7 +41,10 @@ module Wsv
       @ssl_context = tls&.to_ssl_context
       @open = open
       @cors = Cors.new if cors
-      @app = App.new(@root, spa: spa, cors: @cors)
+      @access_log = quiet ? NullAccessLog.new : AccessLog.new(out: out)
+      # `app:` lets callers plug in a custom request handler in place of
+      # the default file server.
+      @app = app || App.new(@root, spa: spa, cors: @cors)
       @throttle = ConnectionThrottle.new(max: max_connections, err: err)
       @running = false
     end
@@ -75,6 +80,15 @@ module Wsv
           next
         end
 
+        # Disable Nagle so small writes (SSE frames, headers) are not held
+        # in the TCP send buffer waiting for an ACK. Applies before any TLS
+        # wrap; NODELAY is a TCP-layer option that persists through SSL.
+        begin
+          client.setsockopt(:TCP, :NODELAY, 1)
+        rescue StandardError
+          nil
+        end
+
         begin
           spawn_handler(client)
         rescue StandardError => e
@@ -90,7 +104,8 @@ module Wsv
 
     def spawn_handler(client)
       accepted = @throttle.try_spawn do
-        Connection.new(maybe_wrap_tls(client), err: @err, cors: @cors).serve(@app, read_timeout: @read_timeout)
+        Connection.new(maybe_wrap_tls(client), err: @err, cors: @cors, access_log: @access_log)
+                  .serve(@app, read_timeout: @read_timeout)
       end
       spawn_rejection(client) unless accepted
     end
@@ -104,10 +119,10 @@ module Wsv
       reply = !@ssl_context
       Thread.new do
         Thread.current.report_on_exception = false
-        Connection.new(client, err: @err, cors: @cors).reject(reply: reply)
+        Connection.new(client, err: @err, cors: @cors, access_log: @access_log).reject(reply: reply)
       end
     rescue ThreadError
-      Connection.new(client, err: @err, cors: @cors).reject(reply: reply)
+      Connection.new(client, err: @err, cors: @cors, access_log: @access_log).reject(reply: reply)
     end
 
     def maybe_wrap_tls(client)

data/lib/wsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wsv
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/test/access_log_test.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class AccessLogTest < Minitest::Test
+  def test_records_clf_line_for_serviced_request
+    out = StringIO.new
+    log = Wsv::Server::AccessLog.new(out: out)
+
+    log.record(
+      remote_addr: "127.0.0.1",
+      request: build_request(method: "GET", target: "/index.html", version: "HTTP/1.1"),
+      status: 200,
+      bytes: 1234
+    )
+
+    assert_match(%r{\A127\.0\.0\.1 - - \[\d{2}/\w{3}/\d{4}:\d{2}:\d{2}:\d{2} [+-]\d{4}\] }, out.string)
+    assert_includes out.string, %("GET /index.html HTTP/1.1" 200 1234)
+  end
+
+  def test_uses_dash_for_zero_bytes
+    out = StringIO.new
+    Wsv::Server::AccessLog.new(out: out).record(
+      remote_addr: "127.0.0.1",
+      request: build_request(method: "HEAD", target: "/", version: "HTTP/1.1"),
+      status: 200,
+      bytes: 0
+    )
+
+    assert_match(/200 -\z/, out.string.chomp)
+  end
+
+  def test_uses_dash_when_remote_addr_unknown
+    out = StringIO.new
+    Wsv::Server::AccessLog.new(out: out).record(
+      remote_addr: nil,
+      request: build_request(method: "GET", target: "/", version: "HTTP/1.1"),
+      status: 200,
+      bytes: 1
+    )
+
+    assert out.string.start_with?("- - - ")
+  end
+
+  def test_uses_dash_when_request_unparsed
+    out = StringIO.new
+    Wsv::Server::AccessLog.new(out: out).record(
+      remote_addr: "127.0.0.1",
+      request: nil,
+      status: 408,
+      bytes: 11
+    )
+
+    assert_includes out.string, %("-" 408 11)
+  end
+
+  def test_sanitizes_control_characters_in_request_line
+    out = StringIO.new
+    Wsv::Server::AccessLog.new(out: out).record(
+      remote_addr: "127.0.0.1",
+      request: build_request(method: "GET", target: "/x\r\ninjected:1", version: "HTTP/1.1"),
+      status: 400,
+      bytes: 0
+    )
+
+    refute_includes out.string, "\r"
+    assert_equal 1, out.string.count("\n")
+    assert_includes out.string, '\\x0d\\x0a'
+  end
+
+  def test_sanitizes_quotes_in_request_target
+    out = StringIO.new
+    Wsv::Server::AccessLog.new(out: out).record(
+      remote_addr: "127.0.0.1",
+      request: build_request(method: "GET", target: %(/x"y), version: "HTTP/1.1"),
+      status: 200,
+      bytes: 1
+    )
+
+    assert_includes out.string, '\\x22'
+  end
+
+  def test_null_access_log_is_silent
+    log = Wsv::Server::NullAccessLog.new
+
+    assert_nil log.record(remote_addr: "127.0.0.1", request: nil, status: 200, bytes: 0)
+  end
+
+  private
+
+  def build_request(method:, target:, version:)
+    Wsv::Request.new(method: method, target: target, version: version, headers: {})
+  end
+end

data/test/app_test.rb

@@ -109,6 +109,17 @@ class AppTest < Minitest::Test
     assert_equal "hi", response.body
   end
 
+  def test_304_takes_precedence_over_range
+    path = File.join(@dir, "x.txt")
+    File.write(path, "hi")
+
+    response = @app.call(req("GET", "/x.txt",
+                             "if-modified-since" => File.mtime(path).httpdate,
+                             "range" => "bytes=0-0"))
+
+    assert_equal 304, response.status
+  end
+
   def test_invalid_if_modified_since_is_ignored
     File.write(File.join(@dir, "x.txt"), "hi")
 

data/test/banner_test.rb

@@ -22,6 +22,21 @@ class BannerTest < Minitest::Test
     refute_includes err.string, "WARNING"
   end
 
+  def test_warns_when_binding_to_ipv6_wildcard
+    err = StringIO.new
+    build(host: "::", err: err).emit
+
+    assert_includes err.string, "WARNING"
+    assert_includes err.string, "::"
+  end
+
+  def test_no_warning_for_ipv6_loopback
+    err = StringIO.new
+    build(host: "::1", err: err).emit
+
+    refute_includes err.string, "WARNING"
+  end
+
   def test_brackets_ipv6_address_in_url
     out = StringIO.new
     build(host: "::1", port: 8000, out: out).emit

data/test/cli_test.rb

@@ -17,7 +17,7 @@ class CLITest < Minitest::Test
 
   def test_host_port_and_directory
     Dir.mktmpdir do |dir|
-      options = Wsv::CLI.new([]).parse_options(["-h", "127.0.0.1", "-p", "3000", dir])
+      options = Wsv::CLI.new([]).parse_options(["--host", "127.0.0.1", "-p", "3000", dir])
 
       assert_equal "127.0.0.1", options[:host]
       assert_equal 3000, options[:port]
@@ -25,6 +25,14 @@ class CLITest < Minitest::Test
     end
   end
 
+  def test_short_help_flag
+    out = StringIO.new
+    code = Wsv::CLI.new(["-h"], out: out).run
+
+    assert_equal 0, code
+    assert_includes out.string, "Usage: wsv"
+  end
+
   def test_long_host_port_and_directory
     Dir.mktmpdir do |dir|
       options = Wsv::CLI.new([]).parse_options(["--host", "localhost", "--port", "4567", dir])
@@ -35,6 +43,48 @@ class CLITest < Minitest::Test
     end
   end
 
+  def test_bare_ipv6_host
+    options = Wsv::CLI.new([]).parse_options(["--host", "::1"])
+
+    assert_equal "::1", options[:host]
+  end
+
+  def test_bracketed_ipv6_host_is_unwrapped
+    options = Wsv::CLI.new([]).parse_options(["--host", "[::1]"])
+
+    assert_equal "::1", options[:host]
+  end
+
+  def test_bracketed_ipv6_with_zone_id
+    options = Wsv::CLI.new([]).parse_options(["--host", "[fe80::1%en0]"])
+
+    assert_equal "fe80::1%en0", options[:host]
+  end
+
+  def test_host_with_port_suffix_rejected
+    err = StringIO.new
+    code = Wsv::CLI.new(["--host", "[::1]:8000"], err: err).run
+
+    assert_equal 1, code
+    assert_includes err.string, "must not include a port"
+  end
+
+  def test_host_unbalanced_brackets_rejected
+    err = StringIO.new
+    code = Wsv::CLI.new(["--host", "[::1"], err: err).run
+
+    assert_equal 1, code
+    assert_includes err.string, "unbalanced brackets"
+  end
+
+  def test_host_empty_brackets_rejected
+    err = StringIO.new
+    code = Wsv::CLI.new(["--host", "[]"], err: err).run
+
+    assert_equal 1, code
+    assert_includes err.string, "bracket value is empty"
+  end
+
   def test_help
     out = StringIO.new
     code = Wsv::CLI.new(["--help"], out: out).run
@@ -62,6 +112,14 @@ class CLITest < Minitest::Test
     assert_includes err.string, "port must be between 1 and 65535"
   end
 
+  def test_port_above_max_rejected
+    err = StringIO.new
+    code = Wsv::CLI.new(["-p", "65536"], err: err).run
+
+    assert_equal 1, code
+    assert_includes err.string, "port must be between 1 and 65535"
+  end
+
   def test_missing_directory
     err = StringIO.new
     missing = File.join(Dir.tmpdir, "wsv-missing-#{Time.now.to_i}-#{$$}")
@@ -89,6 +147,19 @@ class CLITest < Minitest::Test
     end
   end
 
+  def test_missing_cert_file_errors_at_runtime
+    err = StringIO.new
+    Dir.mktmpdir do |dir|
+      missing_cert = File.join(dir, "missing-cert.pem")
+      missing_key = File.join(dir, "missing-key.pem")
+      code = Wsv::CLI.new(["--cert", missing_cert, "--key", missing_key, dir], err: err).run
+
+      assert_equal 1, code
+      assert_includes err.string, "wsv:"
+      assert_includes err.string, "missing-cert.pem"
+    end
+  end
+
   def test_cert_and_key_parses
     Dir.mktmpdir do |dir|
       options = Wsv::CLI.new([]).parse_options(["--cert", "a.pem", "--key", "b.pem", dir])

data/test/custom_app_test.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "socket"
+require_relative "test_helper"
+
+# Covers two related extension points:
+#
+#   * `Wsv::Server.new(app:)` — DI a custom request handler
+#   * `Wsv::Response.sse { |io| ... }` — long-lived Server-Sent Events responses
+class CustomAppTest < Minitest::Test
+  def setup
+    @dir = Dir.mktmpdir
+    @server = nil
+    @thread = nil
+  end
+
+  def teardown
+    @server&.stop
+    @thread&.join(2)
+    FileUtils.remove_entry(@dir)
+  end
+
+  def test_custom_app_handles_requests_in_place_of_default
+    app = Class.new do
+      def call(_request)
+        Wsv::Response.new(
+          status: 200,
+          headers: { "Content-Type" => "text/plain", "Content-Length" => "8" },
+          body: "from-app"
+        )
+      end
+    end.new
+
+    start_server(app: app)
+    response = get("/anything")
+
+    assert_equal "200", response.code
+    assert_equal "from-app", response.body
+  end
+
+  def test_sse_response_delivers_chunks_in_order
+    chunks = ["data: one\n\n", "data: two\n\n", "data: three\n\n"]
+    app = Class.new do
+      define_method(:call) do |_request|
+        Wsv::Response.sse do |io|
+          chunks.each do |c|
+            io.write(c)
+            io.flush
+          end
+        end
+      end
+    end.new
+
+    start_server(app: app)
+    body = read_full_body("/events")
+
+    chunks.each { |c| assert_includes body, c }
+    assert_operator body.index(chunks[0]), :<, body.index(chunks[1])
+    assert_operator body.index(chunks[1]), :<, body.index(chunks[2])
+  end
+
+  def test_sse_response_uses_event_stream_content_type
+    app = Class.new do
+      def call(_request)
+        Wsv::Response.sse { |io| io.write("data: hi\n\n") }
+      end
+    end.new
+
+    start_server(app: app)
+    response = get("/stream")
+
+    assert_equal "200", response.code
+    assert_match %r{text/event-stream}, response["content-type"]
+    refute response["content-length"], "sse must not advertise Content-Length"
+  end
+
+  private
+
+  def start_server(app:)
+    @server = Wsv::Server.new(
+      host: "127.0.0.1",
+      port: free_port,
+      root: @dir,
+      out: StringIO.new,
+      err: StringIO.new,
+      app: app
+    )
+    @thread = Thread.new { @server.start }
+    wait_until_ready
+  end
+
+  def free_port
+    s = TCPServer.new("127.0.0.1", 0)
+    s.addr[1]
+  ensure
+    s&.close
+  end
+
+  def wait_until_ready
+    deadline = Time.now + 2
+    loop do
+      TCPSocket.open("127.0.0.1", @server.port).close
+      break
+    rescue Errno::ECONNREFUSED
+      raise if Time.now >= deadline
+
+      sleep 0.01
+    end
+  end
+
+  def get(path)
+    Net::HTTP.get_response(URI("http://127.0.0.1:#{@server.port}#{path}"))
+  end
+
+  # Read until the server closes the connection (streaming responses
+  # omit Content-Length so Net::HTTP would still read-to-EOF, but for
+  # clarity we use a raw socket here).
+  def read_full_body(path)
+    socket = TCPSocket.open("127.0.0.1", @server.port)
+    socket.write("GET #{path} HTTP/1.1\r\nHost: localhost\r\n\r\n")
+    raw = socket.read
+    header_end = raw.index("\r\n\r\n")
+    raw[(header_end + 4)..]
+  ensure
+    socket&.close
+  end
+end

data/test/path_resolver_test.rb

@@ -13,6 +13,14 @@ class PathResolverTest < Minitest::Test
     FileUtils.remove_entry(@dir)
   end
 
+  def test_empty_path_returns_redirect
+    # `""` has no trailing slash → resolver returns redirect the same
+    # way it would for `/somedir` when `somedir` is a directory.
+    result = @resolver.resolve("")
+
+    assert_predicate result, :redirect?
+  end
+
   def test_resolves_existing_file
     path = File.join(@dir, "hello.txt")
     File.write(path, "hi")

data/test/range_request_test.rb

@@ -94,6 +94,27 @@ class RangeRequestTest < Minitest::Test
     assert_predicate result, :unsatisfiable?
   end
 
+  def test_bounded_range_at_exact_file_boundary
+    result = Wsv::RangeRequest.parse("bytes=0-9", 10)
+
+    assert_predicate result, :partial?
+    assert_equal(0..9, result.bounds)
+  end
+
+  def test_suffix_range_equal_to_file_size
+    result = Wsv::RangeRequest.parse("bytes=-10", 10)
+
+    assert_predicate result, :partial?
+    assert_equal(0..9, result.bounds)
+  end
+
+  def test_single_byte_range_at_last_position
+    result = Wsv::RangeRequest.parse("bytes=9-9", 10)
+
+    assert_predicate result, :partial?
+    assert_equal(9..9, result.bounds)
+  end
+
   def test_multipart_range_is_full
     # `bytes=0-2,5-7` doesn't match the single-range regex; treat as absent.
     result = Wsv::RangeRequest.parse("bytes=0-2,5-7", 100)

data/test/server_test.rb

@@ -313,6 +313,32 @@ class ServerTest < Minitest::Test
     assert_includes response, "Allow: GET, HEAD"
   end
 
+  def test_emits_access_log_by_default
+    File.write(File.join(@dir, "ok.txt"), "hello")
+    out = StringIO.new
+    @server = Wsv::Server.new(host: "127.0.0.1", port: free_port, root: @dir, out: out, err: StringIO.new)
+    @thread = Thread.new { @server.start }
+    wait_until_ready
+
+    get("/ok.txt")
+
+    assert_includes out.string, %("GET /ok.txt HTTP/1.1" 200 5)
+  end
+
+  def test_quiet_suppresses_access_log
+    File.write(File.join(@dir, "ok.txt"), "hello")
+    out = StringIO.new
+    @server = Wsv::Server.new(host: "127.0.0.1", port: free_port, root: @dir,
+                              out: out, err: StringIO.new, quiet: true)
+    @thread = Thread.new { @server.start }
+    wait_until_ready
+    baseline = out.string.dup
+
+    get("/ok.txt")
+
+    assert_equal baseline, out.string
+  end
+
   private
 
   def start_server(read_timeout: Wsv::Server::DEFAULT_READ_TIMEOUT, tls: nil, cors: false)

data/test/sse_test.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class SseBodyTest < Minitest::Test
+  def test_requires_a_block
+    assert_raises(ArgumentError) { Wsv::Response::SseBody.new }
+  end
+
+  def test_to_s_raises_not_implemented
+    body = Wsv::Response::SseBody.new { |io| io }
+    assert_raises(NotImplementedError) { body.to_s }
+  end
+
+  def test_bytesize_is_zero
+    body = Wsv::Response::SseBody.new { |io| io }
+
+    assert_equal 0, body.bytesize
+  end
+
+  def test_write_to_invokes_producer_with_io
+    received_io = nil
+    body = Wsv::Response::SseBody.new { |io| received_io = io }
+    buffer = StringIO.new
+    body.write_to(buffer)
+
+    assert_equal buffer, received_io
+  end
+
+  def test_producer_can_write_multiple_chunks
+    body = Wsv::Response::SseBody.new do |io|
+      io.write("data: hello\n\n")
+      io.write("data: world\n\n")
+    end
+    buffer = StringIO.new
+    body.write_to(buffer)
+
+    assert_equal "data: hello\n\ndata: world\n\n", buffer.string
+  end
+end
+
+class ResponseSseTest < Minitest::Test
+  def test_sse_helper_returns_response_with_sse_defaults
+    response = Wsv::Response.sse { |io| io }
+
+    assert_equal 200, response.status
+    assert_equal "text/event-stream; charset=utf-8", response.headers["Content-Type"]
+    assert_equal "no-cache", response.headers["Cache-Control"]
+    assert_equal "no", response.headers["X-Accel-Buffering"]
+  end
+
+  def test_sse_helper_allows_custom_status
+    response = Wsv::Response.sse(status: 503) { |io| io }
+
+    assert_equal 503, response.status
+  end
+
+  def test_sse_helper_merges_extra_headers
+    response = Wsv::Response.sse(headers: { "X-Custom" => "v" }) { |io| io }
+
+    assert_equal "v", response.headers["X-Custom"]
+    assert_equal "no-cache", response.headers["Cache-Control"]
+  end
+
+  def test_sse_helper_overrides_default_headers_when_supplied
+    response = Wsv::Response.sse(headers: { "Content-Type" => "application/x-ndjson" }) { |io| io }
+
+    assert_equal "application/x-ndjson", response.headers["Content-Type"]
+  end
+
+  def test_response_write_to_does_not_inject_content_length_for_sse
+    response = Wsv::Response.sse do |io|
+      io.write("data: hi\n\n")
+    end
+    buffer = StringIO.new
+    response.write_to(buffer)
+
+    refute_match(/^Content-Length:/i, buffer.string)
+    assert_match(%r{^Content-Type: text/event-stream}i, buffer.string)
+    assert_match(/data: hi\n\n\z/, buffer.string)
+  end
+
+  def test_bytesize_of_sse_response_is_zero
+    response = Wsv::Response.sse { |io| io }
+
+    assert_equal 0, response.bytesize
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wsv
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - takahashim
 bindir: exe
 cert_chain: []
-date: 2026-05-07 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies: []
 description: 'wsv is a Ruby CLI that previews a directory over HTTP/HTTPS. Stdlib-only,
   no runtime dependencies. Defensive by design: blocks dotfiles, binds to loopback,
@@ -36,9 +36,12 @@ files:
 - lib/wsv/response.rb
 - lib/wsv/response/file_body.rb
 - lib/wsv/response/file_builder.rb
+- lib/wsv/response/sse_body.rb
+- lib/wsv/response/sse_builder.rb
 - lib/wsv/response/string_body.rb
 - lib/wsv/response/text_builder.rb
 - lib/wsv/server.rb
+- lib/wsv/server/access_log.rb
 - lib/wsv/server/banner.rb
 - lib/wsv/server/browser_launcher.rb
 - lib/wsv/server/connection.rb
@@ -50,16 +53,19 @@ files:
 - lib/wsv/tls_context/resolver.rb
 - lib/wsv/tls_context/self_signed_cert.rb
 - lib/wsv/version.rb
+- test/access_log_test.rb
 - test/app_test.rb
 - test/banner_test.rb
 - test/browser_launcher_test.rb
 - test/cli_test.rb
 - test/cors_test.rb
+- test/custom_app_test.rb
 - test/path_resolver_test.rb
 - test/range_request_test.rb
 - test/request_test.rb
 - test/response_test.rb
 - test/server_test.rb
+- test/sse_test.rb
 - test/test_helper.rb
 - test/tls_context_test.rb
 - wsv.gemspec