wsv 0.10.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 782b303e2d6eeb0f45f6b3a012523b94611a4991d59ef6669768b21936f47a8e
-  data.tar.gz: 25b99b347007975bac86ccd93c212f5fb0bc85522054c36badac601bae5f3638
+  metadata.gz: 77baaa8165944bc789ad3054605d4c3283ece7b4592c9477c117495bfa48e2fb
+  data.tar.gz: 1ecf4ef75a3b99e08d61a985de7f06f83622d92b0b2df769f27a937856cd185c
 SHA512:
-  metadata.gz: b3619a62d69f29a3498081d8174a0a01c61484ede73f9875de9867b4a4dd451f639dcbe0bee99fb3bea00b78c0ba289618ab7eeec3b066705d8ca437a9cea134
-  data.tar.gz: c58379c2eab12176f492d993d1e194dc0f3a33c16ba7d8736134498e4d13ce8031816a5d22688f1639c0ea3127c5787ad4c235874b20929490eac52881c3e9b0
+  metadata.gz: 51247e6eb2b43639dc127e44c1b0ca27feb1cb8ba7ef25120ff744343fb839893860e8091c689beb5e9db45fa9a875f59e42391681eb973d2c2c25de7d9855c7
+  data.tar.gz: b9434026433cc3d54f742bd099ac0afd705c96f169ed1c6067fd1f58b13fff0c61f4c2257d2cffedb0e7c15a193f07b2156f2d7776c2de3c1b50790d13d271a0

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # 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
+  (suffix / open-ended / bounded ranges, unsatisfiability) now lives
+  in its own class with a `Result` value object (`#full?` /
+  `#partial?` / `#unsatisfiable?` predicates plus `#bounds`),
+  matching the `PathResolver::Result` pattern. Behavior unchanged.
+- Make `Server::Connection` the sole place that adds CORS overlay
+  headers (`Access-Control-Allow-Origin`, `Vary`) on outgoing
+  responses. Previously `App` applied the overlay on its return
+  value, but rescue-path responses (408 / 414 / 431 / 503 / unmapped
+  400) bypassed `App` and therefore lacked CORS headers. Now every
+  response — `App`, parser errors, timeouts, and the 503 rejection —
+  gets the overlay uniformly. `Cors#preflight` no longer includes
+  ACAO/Vary itself, since Connection adds them.
+- `Wsv::App.new(... cors:)` now expects a `Wsv::Cors` instance (or
+  `nil`) instead of a Boolean. `Wsv::Server.new(... cors: true/false)`
+  is unchanged. Per the README's stability statement, the Ruby API
+  under `lib/wsv/` is implementation-only and may change in any
+  release.
+
 ## 0.10.1
 
 - Update gem description and README tagline to position wsv as

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/app.rb

@@ -4,24 +4,23 @@ require "time"
 require "uri"
 require_relative "cors"
 require_relative "path_resolver"
+require_relative "range_request"
 require_relative "response"
 
 module Wsv
   class App
     ALLOWED_METHODS = %w[GET HEAD].freeze
-    RANGE_PATTERN = /\Abytes=(\d+)?-(\d+)?\z/
 
-    def initialize(root, spa: false, cors: false)
+    def initialize(root, spa: false, cors: nil)
       @resolver = PathResolver.new(root)
       @spa = spa
-      @cors = Cors.new if cors
+      @cors = cors
     end
 
     def call(request)
       return @cors.preflight(request) if @cors && request.method == "OPTIONS"
 
-      response = build_response(request)
-      @cors ? @cors.overlay(response) : response
+      build_response(request)
     end
 
     private
@@ -30,7 +29,7 @@ module Wsv
       head = request.head?
 
       unless ALLOWED_METHODS.include?(request.method)
-        return Response.text(405, headers: { "Allow" => allow_methods }, head: head)
+        return Response.text(405, headers: { "Allow" => allow_header }, head: head)
       end
 
       raw_path, query = request.target.split("?", 2)
@@ -51,8 +50,8 @@ module Wsv
       file_response(result.file, request, head: head)
     end
 
-    def allow_methods
-      @cors ? Cors::ALLOW_METHODS : "GET, HEAD"
+    def allow_header
+      (@cors&.allow_methods || ALLOWED_METHODS).join(", ")
     end
 
     def error_response(status, head:)
@@ -69,15 +68,11 @@ module Wsv
       return Response.not_modified if not_modified?(file, request.headers["if-modified-since"])
 
       size = File.size(file)
-      range = parse_range(request.headers["range"], size)
-      case range
-      when :unsatisfiable
-        Response.range_not_satisfiable(size, head: head)
-      when nil
-        Response.file(file, head: head)
-      else
-        Response.file(file, head: head, range: range)
-      end
+      range = RangeRequest.parse(request.headers["range"], size)
+      return Response.range_not_satisfiable(size, head: head) if range.unsatisfiable?
+      return Response.file(file, head: head) if range.full?
+
+      Response.file(file, head: head, range: range.bounds)
     end
 
     def not_modified?(file, header_value)
@@ -89,45 +84,6 @@ module Wsv
       false
     end
 
-    def parse_range(header_value, file_size)
-      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
-      if first.nil? && last.nil?
-        nil
-      elsif first.nil?
-        suffix_range(last.to_i, file_size)
-      elsif last.nil?
-        open_range(first.to_i, file_size)
-      else
-        bounded_range(first.to_i, last.to_i, file_size)
-      end
-    end
-
-    def suffix_range(suffix, file_size)
-      return :unsatisfiable if suffix.zero? || file_size.zero?
-
-      [file_size - suffix, 0].max..(file_size - 1)
-    end
-
-    def open_range(first, file_size)
-      return :unsatisfiable if first >= file_size
-
-      first..(file_size - 1)
-    end
-
-    def bounded_range(first, last, file_size)
-      return :unsatisfiable if first > last || first >= file_size
-
-      last = file_size - 1 if last >= file_size
-      first..last
-    end
-
     def redirect_location(raw_path, query)
       path = URI(raw_path.to_s).path
       path = "/" if path.empty?

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/cors.rb

@@ -5,15 +5,17 @@ require_relative "response"
 module Wsv
   class Cors
     ALLOW_ORIGIN = "*"
-    ALLOW_METHODS = "GET, HEAD, OPTIONS"
+    ALLOW_METHODS = %w[GET HEAD OPTIONS].freeze
     MAX_AGE = "86400"
 
+    def allow_methods
+      ALLOW_METHODS
+    end
+
     def preflight(request)
       headers = {
-        "Access-Control-Allow-Origin" => ALLOW_ORIGIN,
-        "Access-Control-Allow-Methods" => ALLOW_METHODS,
-        "Access-Control-Max-Age" => MAX_AGE,
-        "Vary" => "Origin"
+        "Access-Control-Allow-Methods" => ALLOW_METHODS.join(", "),
+        "Access-Control-Max-Age" => MAX_AGE
       }
       requested = request.headers["access-control-request-headers"]
       headers["Access-Control-Allow-Headers"] = requested if requested

data/lib/wsv/range_request.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Wsv
+  # Parses an HTTP `Range` header (RFC 7233) against a known file size.
+  class RangeRequest
+    PATTERN = /\Abytes=(\d+)?-(\d+)?\z/
+
+    class Result
+      attr_reader :bounds
+
+      def initialize(kind:, bounds: nil)
+        @kind = kind
+        @bounds = bounds
+      end
+
+      def full?
+        @kind == :full
+      end
+
+      def partial?
+        @kind == :partial
+      end
+
+      def unsatisfiable?
+        @kind == :unsatisfiable
+      end
+
+      def self.full
+        new(kind: :full)
+      end
+
+      def self.partial(bounds)
+        new(kind: :partial, bounds: bounds)
+      end
+
+      def self.unsatisfiable
+        new(kind: :unsatisfiable)
+      end
+    end
+
+    def self.parse(header_value, file_size)
+      new(header_value, file_size).parse
+    end
+
+    def initialize(header_value, file_size)
+      @header_value = header_value
+      @file_size = file_size
+    end
+
+    def parse
+      return Result.full if @header_value.nil? || @header_value.empty?
+
+      match = @header_value.match(PATTERN)
+      # Per RFC 7233, an unparseable Range is treated as if absent: return
+      # full so the caller serves a normal 200 instead of 416.
+      return Result.full unless match
+
+      first, last = match.captures
+      if first.nil? && last.nil?
+        Result.full
+      elsif first.nil?
+        suffix_range(last.to_i)
+      elsif last.nil?
+        open_range(first.to_i)
+      else
+        bounded_range(first.to_i, last.to_i)
+      end
+    end
+
+    private
+
+    def suffix_range(suffix)
+      return Result.unsatisfiable if suffix.zero? || @file_size.zero?
+
+      Result.partial([@file_size - suffix, 0].max..(@file_size - 1))
+    end
+
+    def open_range(first)
+      return Result.unsatisfiable if first >= @file_size
+
+      Result.partial(first..(@file_size - 1))
+    end
+
+    def bounded_range(first, last)
+      return Result.unsatisfiable if first > last || first >= @file_size
+
+      last = @file_size - 1 if last >= @file_size
+      Result.partial(first..last)
+    end
+  end
+end

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,51 +14,88 @@ module Wsv
     class Connection
       DRAIN_TIMEOUT = 5
 
-      def initialize(client, err:)
+      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.
       def write(response)
         return if @client.closed?
 
-        response.write_to(@client)
+        finalize(response).write_to(@client)
       rescue Errno::EPIPE, Errno::ECONNRESET, IOError
         nil
       end
 
+      def finalize(response)
+        @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?