wsv 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 027bb497b4d78e1d58abd8aee91bc4349439c29425dc374b535587da67b09997
-  data.tar.gz: 5692790c2408ad64761358b3d33efccb439edb0e5c75150beed715bbabfc350e
+  metadata.gz: 782b303e2d6eeb0f45f6b3a012523b94611a4991d59ef6669768b21936f47a8e
+  data.tar.gz: 25b99b347007975bac86ccd93c212f5fb0bc85522054c36badac601bae5f3638
 SHA512:
-  metadata.gz: 2d866a94d0f52f01e7ea50f69a2818bf2c367d704274c362863af11c71647aa80120fa72964bec31f6bfb05356ec401ced291875b9f0bc5c55f9b6b1b4b28fd8
-  data.tar.gz: 27cdfaa3126c02c54eeb1268fdec08fc64de82a850e2523865280048f93fbd0d95f5c906eb4da26734a80e36c98570c82ed059d71bbab0459361153a4be1fbb9
+  metadata.gz: b3619a62d69f29a3498081d8174a0a01c61484ede73f9875de9867b4a4dd451f639dcbe0bee99fb3bea00b78c0ba289618ab7eeec3b066705d8ca437a9cea134
+  data.tar.gz: c58379c2eab12176f492d993d1e194dc0f3a33c16ba7d8736134498e4d13ce8031816a5d22688f1639c0ea3127c5787ad4c235874b20929490eac52881c3e9b0

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

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/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,96 @@
+# 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:)
+        @client = client
+        @err = err
+      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
+
+      def write(response)
+        return if @client.closed?
+
+        response.write_to(@client)
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        nil
+      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

data/lib/wsv/server.rb

@@ -3,17 +3,15 @@
 require "openssl"
 require "socket"
 require_relative "app"
-require_relative "request"
-require_relative "response"
 require_relative "server/banner"
 require_relative "server/browser_launcher"
-require_relative "server/deadline_reader"
+require_relative "server/connection"
+require_relative "server/connection_throttle"
 
 module Wsv
   class Server
     DEFAULT_READ_TIMEOUT = 10
     DEFAULT_MAX_CONNECTIONS = 8
-    DRAIN_TIMEOUT = 5
 
     attr_reader :host, :port, :root
 
@@ -36,14 +34,12 @@ module Wsv
       @out = out
       @err = err
       @read_timeout = read_timeout
-      @max_connections = max_connections
       @tls = tls
       @ssl_context = tls&.to_ssl_context
       @open = open
       @app = App.new(@root, spa: spa, cors: cors)
+      @throttle = ConnectionThrottle.new(max: max_connections, err: err)
       @running = false
-      @mutex = Mutex.new
-      @active = 0
     end
 
     def start
@@ -62,74 +58,8 @@ module Wsv
       close
     end
 
-    def handle(client)
-      reader = DeadlineReader.new(client, Time.now + @read_timeout)
-      request = Request.parse(reader)
-      case request
-      when :empty
-        nil
-      when :malformed
-        write_response(client, Response.text(400))
-      else
-        write_response(client, @app.call(request))
-      end
-    rescue Request::TooLarge => e
-      write_response(client, Response.text(e.status_code))
-    rescue IO::TimeoutError
-      write_response(client, 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(client, Response.text(400))
-    ensure
-      graceful_close(client)
-    end
-
     private
 
-    def write_response(client, response)
-      return if client.closed?
-
-      response.write_to(client)
-    rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-      nil
-    end
-
-    def graceful_close(client)
-      return if client.closed?
-
-      drain_recv(client)
-    rescue StandardError
-      nil
-    ensure
-      begin
-        client.close unless client.closed?
-      rescue StandardError
-        nil
-      end
-    end
-
-    def drain_recv(client)
-      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
-
     def accept_loop
       while @running
         client = nil
@@ -157,38 +87,25 @@ module Wsv
     end
 
     def spawn_handler(client)
-      accepted = @mutex.synchronize do
-        next false if @active >= @max_connections
-
-        @active += 1
-        true
-      end
-
-      return spawn_rejection(client) unless accepted
-
-      begin
-        Thread.new do
-          Thread.current.report_on_exception = false
-          handle(maybe_wrap_tls(client))
-        ensure
-          @mutex.synchronize { @active -= 1 }
-        end
-      rescue ThreadError => e
-        @err.puts "wsv: thread error: #{e.message}"
-        @mutex.synchronize { @active -= 1 }
-        spawn_rejection(client)
+      accepted = @throttle.try_spawn do
+        Connection.new(maybe_wrap_tls(client), err: @err).serve(@app, read_timeout: @read_timeout)
       end
+      spawn_rejection(client) unless accepted
     end
 
     # Reject in a separate thread so a slow client cannot block accept_loop
-    # via graceful_close's drain_recv (up to DRAIN_TIMEOUT seconds).
+    # via Connection#graceful_close (up to Connection::DRAIN_TIMEOUT seconds).
+    # In TLS mode `client` is the raw TCPSocket before any handshake; writing
+    # a plaintext 503 would corrupt the TLS handshake the client is about to
+    # start, so suppress the reply in that case.
     def spawn_rejection(client)
+      reply = !@ssl_context
       Thread.new do
         Thread.current.report_on_exception = false
-        reject(client)
+        Connection.new(client, err: @err).reject(reply: reply)
       end
     rescue ThreadError
-      reject(client)
+      Connection.new(client, err: @err).reject(reply: reply)
     end
 
     def maybe_wrap_tls(client)
@@ -200,7 +117,7 @@ module Wsv
       ssl.accept
       ssl
     rescue StandardError
-      # If wrapping or the handshake failed, `handle` is never called and
+      # If wrapping or the handshake failed, `serve` is never called and
       # its ensure does not get a chance to close the underlying socket.
       # Close it here so we do not leak a TCPSocket per failed handshake.
       begin
@@ -211,15 +128,6 @@ module Wsv
       raise
     end
 
-    def reject(client)
-      # In TLS mode `client` is the raw TCPSocket before any handshake.
-      # Writing a plaintext 503 over it would corrupt the TLS handshake
-      # the client is about to start, so just close in that case.
-      write_response(client, Response.text(503)) unless @ssl_context
-    ensure
-      graceful_close(client)
-    end
-
     def close
       @server&.close unless @server&.closed?
     end

data/lib/wsv/version.rb

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

data/wsv.gemspec

@@ -8,15 +8,16 @@ Gem::Specification.new do |spec|
   spec.authors = ["takahashim"]
   spec.email = ["takahashimm@gmail.com"]
 
-  spec.summary = "A tiny static web server for local previews."
-  spec.description = "wsv serves a local directory over HTTP from a zero-config CLI."
-  spec.homepage = "https://rubygems.org/gems/wsv"
+  spec.summary = "A zero-dependency static preview server for Ruby projects."
+  spec.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, ships with TLS and CORS."
+  spec.homepage = "https://github.com/takahashim/wsv"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"
 
   spec.metadata = {
     "homepage_uri" => spec.homepage,
-    "source_code_uri" => "https://github.com/takahashim/wsv",
     "changelog_uri" => "https://github.com/takahashim/wsv/blob/main/CHANGELOG.md",
     "rubygems_mfa_required" => "true"
   }
@@ -25,12 +26,12 @@ Gem::Specification.new do |spec|
     "CHANGELOG.md",
     "LICENSE.txt",
     "README.md",
-    "bin/wsv",
+    "exe/wsv",
     "lib/**/*.rb",
     "test/**/*.rb",
     "wsv.gemspec"
   ]
-  spec.bindir = "bin"
+  spec.bindir = "exe"
   spec.executables = ["wsv"]
   spec.require_paths = ["lib"]
 end

metadata

@@ -1,15 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: wsv
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - takahashim
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 2026-05-07 00:00:00.000000000 Z
 dependencies: []
-description: wsv serves a local directory over HTTP from a zero-config CLI.
+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,
+  ships with TLS and CORS.'
 email:
 - takahashimm@gmail.com
 executables:
@@ -20,7 +22,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- bin/wsv
+- exe/wsv
 - lib/wsv.rb
 - lib/wsv/app.rb
 - lib/wsv/cli.rb
@@ -38,7 +40,10 @@ files:
 - lib/wsv/server.rb
 - lib/wsv/server/banner.rb
 - lib/wsv/server/browser_launcher.rb
+- lib/wsv/server/connection.rb
+- lib/wsv/server/connection_throttle.rb
 - lib/wsv/server/deadline_reader.rb
+- lib/wsv/server/url_host.rb
 - lib/wsv/status.rb
 - lib/wsv/tls_context.rb
 - lib/wsv/tls_context/resolver.rb
@@ -54,12 +59,11 @@ files:
 - test/test_helper.rb
 - test/tls_context_test.rb
 - wsv.gemspec
-homepage: https://rubygems.org/gems/wsv
+homepage: https://github.com/takahashim/wsv
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://rubygems.org/gems/wsv
-  source_code_uri: https://github.com/takahashim/wsv
+  homepage_uri: https://github.com/takahashim/wsv
   changelog_uri: https://github.com/takahashim/wsv/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -78,5 +82,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: A tiny static web server for local previews.
+summary: A zero-dependency static preview server for Ruby projects.
 test_files: []