wsv 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 027bb497b4d78e1d58abd8aee91bc4349439c29425dc374b535587da67b09997
-  data.tar.gz: 5692790c2408ad64761358b3d33efccb439edb0e5c75150beed715bbabfc350e
+  metadata.gz: adfd569857554409cef36ce05205eb50f833a58a27e654e1da80646afa2ec40e
+  data.tar.gz: 8d5c75289dd59dc65412ebff24bf0cf4d9aa9933befb17354f9b2fb3320b5ca3
 SHA512:
-  metadata.gz: 2d866a94d0f52f01e7ea50f69a2818bf2c367d704274c362863af11c71647aa80120fa72964bec31f6bfb05356ec401ced291875b9f0bc5c55f9b6b1b4b28fd8
-  data.tar.gz: 27cdfaa3126c02c54eeb1268fdec08fc64de82a850e2523865280048f93fbd0d95f5c906eb4da26734a80e36c98570c82ed059d71bbab0459361153a4be1fbb9
+  metadata.gz: b4514041977a6c9a599ea9f2a3735f7b4668ab18172b974453293c444c4441221e068f9374cbdd6c5058b99ecb776edbe47bda3bff4fd77731dbeb9b45cd9446
+  data.tar.gz: f1d06286b164b0f70dce52d7fd86b9fdf29c64f6cbc0515e3d26558afb4498d23277fc23b66709298afffb593e321a21498cc55dea2ab8b58e31186b48aaa021

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 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
+  "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

data/README.md

@@ -1,22 +1,27 @@
 # wsv
 
-`wsv` is a zero-dependency static preview server for Ruby projects.
+`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-*.gem
+gem install wsv
 ```
 
 ## Usage
@@ -55,10 +60,10 @@ Options:
 
 `--tls` enables HTTPS on the chosen `--port`. Three modes:
 
-1. **Ephemeral self-signed** — `wsv --tls` with no cert configured: wsv
+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
+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
@@ -75,7 +80,7 @@ Options:
    wsv --tls           # → https://localhost:8000/ with no warning
    ```
 
-3. **Explicit cert/key files** — `wsv --cert path/to/cert.pem --key path/to/key.pem`
+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
@@ -103,7 +108,9 @@ Options:
 
 ## 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
@@ -162,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).
 

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

@@ -15,9 +15,9 @@ module Wsv
 
       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: @status, headers: full_headers, body: full_body)
+          Response.new(status: @status, headers: full_headers, body: body)
         end
       end
 
@@ -47,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/server/banner.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "url_host"
+
 module Wsv
   class Server
     # Renders the startup announcement (the "Serving / Bind / Local / Stop"
@@ -36,12 +38,7 @@ module Wsv
       end
 
       def url_for(display_host)
-        "#{scheme}://#{format_host(display_host)}:#{@port}/"
-      end
-
-      def format_host(host)
-        # Bracket IPv6 literals per RFC 3986; zone IDs (`%eth0` etc.) need %25 per RFC 6874.
-        host.include?(":") ? "[#{host.gsub('%', '%25')}]" : host
+        "#{scheme}://#{UrlHost.format(display_host)}:#{@port}/"
       end
 
       def scheme

data/lib/wsv/server/browser_launcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rbconfig"
+require_relative "url_host"
 
 module Wsv
   class Server
@@ -32,14 +33,7 @@ module Wsv
 
       def url
         scheme = @tls ? "https" : "http"
-        "#{scheme}://#{url_host}:#{@port}/"
-      end
-
-      def url_host
-        host = display_host
-        # IPv6 literals must be bracketed in URLs per RFC 3986. Scoped IPv6
-        # zone identifiers use `%`, which must be percent-encoded in URLs.
-        host.include?(":") ? "[#{host.gsub('%', '%25')}]" : host
+        "#{scheme}://#{UrlHost.format(display_host)}:#{@port}/"
       end
 
       def display_host

data/lib/wsv/server/connection.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "deadline_reader"
+require_relative "../request"
+require_relative "../response"
+
+module Wsv
+  class Server
+    # Owns a single accepted client socket. `serve` runs the request lifecycle
+    # (parse → app → write → drain → close); `reject` writes 503 (when allowed)
+    # and closes. Both share the safe-write / drain / close primitives so a
+    # broken peer cannot leak a connection or mask errors.
+    class Connection
+      DRAIN_TIMEOUT = 5
+
+      def initialize(client, err:, cors: nil)
+        @client = client
+        @err = err
+        @cors = cors
+      end
+
+      def serve(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
+      rescue Request::TooLarge => e
+        write(Response.text(e.status_code))
+      rescue IO::TimeoutError
+        write(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
+      end
+
+      def reject(reply:)
+        write(Response.text(503)) if reply
+      ensure
+        graceful_close
+      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?
+
+        finalize(response).write_to(@client)
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        nil
+      end
+
+      def finalize(response)
+        @cors ? @cors.overlay(response) : response
+      end
+
+      def graceful_close
+        return if @client.closed?
+
+        drain_recv
+      rescue StandardError
+        nil
+      ensure
+        begin
+          @client.close unless @client.closed?
+        rescue StandardError
+          nil
+        end
+      end
+
+      def drain_recv
+        deadline = Time.now + DRAIN_TIMEOUT
+        loop do
+          return if Time.now >= deadline
+
+          chunk = @client.read_nonblock(8192, exception: false)
+          case chunk
+          when nil, :wait_writable
+            # nil = EOF. :wait_writable can come back from SSLSocket during a
+            # renegotiation (read needs an underlying write). Either way,
+            # there's nothing more we can usefully drain right now.
+            return
+          when :wait_readable
+            remaining = deadline - Time.now
+            return if remaining <= 0
+            return unless @client.wait_readable([remaining, 0.2].min)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wsv/server/connection_throttle.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Server
+    # Caps in-flight connections at `max`. `try_spawn` runs the block in a new
+    # thread when capacity is available and returns true; otherwise returns
+    # false so the caller can reject the client.
+    class ConnectionThrottle
+      def initialize(max:, err:)
+        @max = max
+        @err = err
+        @mutex = Mutex.new
+        @active = 0
+      end
+
+      def try_spawn(&block)
+        return false unless reserve_slot
+
+        begin
+          Thread.new do
+            Thread.current.report_on_exception = false
+            block.call
+          ensure
+            release_slot
+          end
+          true
+        rescue ThreadError => e
+          @err.puts "wsv: thread error: #{e.message}"
+          release_slot
+          false
+        end
+      end
+
+      private
+
+      def reserve_slot
+        @mutex.synchronize do
+          next false if @active >= @max
+
+          @active += 1
+          true
+        end
+      end
+
+      def release_slot
+        @mutex.synchronize { @active -= 1 }
+      end
+    end
+  end
+end

data/lib/wsv/server/url_host.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Server
+    # Formats a host for inclusion in a URL. IPv6 literals are bracketed
+    # (RFC 3986); zone identifiers (`%eth0` etc.) are percent-encoded
+    # (RFC 6874).
+    module UrlHost
+      module_function
+
+      def format(host)
+        host.include?(":") ? "[#{host.gsub('%', '%25')}]" : host
+      end
+    end
+  end
+end