wsv 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3439ce5afffd7bfe4dc3e2a18da2d3f9d15ffd10b28e9cc4bb33f5c3e14ada12
+  data.tar.gz: 98e65904c83834cc8e910931f1884f52e652346bad94612a8ba31933e607ff8c
+SHA512:
+  metadata.gz: 382457dc4151007dca51ab8a550021b06bfe4f4127d5ff40c3c9da7e566b3987ec16b57838b8ce5e30a210d538b87231b9f0f0e5e8b5ef91ef20cc5fdc8f9395
+  data.tar.gz: 2b6210d0c5063c4ba5a8b6c3d723cfe5db3abe9c41b20b6c56a99d64cac0a9b961d694fe2a7b2458250441102ed959034f13f7be169fa0a8102ef46405d8a4f4

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Unreleased
+
+- Bound request size: 8 KiB request line, 8 KiB per header line, 16 KiB total
+  headers, 100 header lines. Returns 414 / 431 when exceeded.
+- Per-request read deadline (default 10s) for slow/idle clients. Returns 408
+  on timeout. Configurable via `Server.new(... read_timeout:)`.
+- Reject CR/LF in response header values to prevent header injection.
+- Drain receive buffer before closing to deliver error responses cleanly
+  instead of resetting the connection.
+- Minimum Ruby version raised to 3.2 (uses `IO#timeout=`).
+- Apply the dotfile filter to the resolved real path so a symlink inside the
+  root cannot smuggle access to `.git/`, `.env`, etc. Symlink loops and
+  permission errors now resolve to 404 cleanly.
+- Concurrent connection handling: a thread is spawned per accepted client up
+  to `max_connections` (default 8). Idle servers hold no worker threads.
+  Connections beyond the cap receive 503 and are closed.
+- Print a `WARNING` to stderr when binding to a non-loopback address so
+  exposing the served directory to the network is intentional, not silent.
+- Cap the post-response receive drain at 5 seconds so a malicious or stuck
+  client cannot tie up a worker indefinitely while sending body bytes after
+  the response has been written.
+- Make the accept loop resilient to transient errors: per-connection failures
+  (`ECONNABORTED`, `EMFILE`, `ENOMEM`, etc.) are logged and skipped instead of
+  killing the server. A 50 ms backoff prevents tight error loops.
+- Add RuboCop with `rubocop-minitest` / `rubocop-rake` plugins. `rake` now
+  runs both `test` and `rubocop`.
+- Add GitHub Actions CI: tests on Ruby 3.2 / 3.3 / 3.4 plus a separate
+  RuboCop job.
+- Document the security model in README (what `wsv` protects against and
+  what is explicitly out of scope).
+
+## 0.1.0
+
+- Initial release.
+- Requests to dotfiles and dot-directories (e.g. `/.git/...`, `/.env`) return 403.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 takahashim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,97 @@
+# wsv
+
+`wsv` is a minimal static web server for local previews.
+
+It has no runtime dependencies outside Ruby's standard library. Run `wsv` in a directory and it serves that directory over HTTP.
+
+## Installation
+
+```sh
+gem install wsv
+```
+
+For local development:
+
+```sh
+gem build wsv.gemspec
+gem install ./wsv-0.1.0.gem
+```
+
+## Usage
+
+```sh
+wsv [options] [directory]
+```
+
+Examples:
+
+```sh
+wsv
+wsv public
+wsv -h 0.0.0.0 -p 3000 ./dist
+```
+
+Options:
+
+```text
+-h, --host HOST    Bind host (default: 127.0.0.1)
+-p, --port PORT    Bind port (default: 8000)
+    --help         Show help
+    --version      Show version
+```
+
+## Behavior
+
+- Serves files from the selected directory.
+- Serves `index.html` for directories that contain it.
+- Does not render directory listings.
+- Supports `GET` and `HEAD`.
+- Rejects paths that resolve outside the served directory.
+- Sends `Cache-Control: no-cache` for local development.
+
+## Security model
+
+`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
+
+- Path traversal — `..`, absolute paths, and URL-encoded forms (`%2e%2e`) are
+  resolved and rejected if they escape the served directory.
+- Symlink-based escape — symlinks pointing outside the served directory are
+  rejected (403). Symlinks that resolve inside the directory are followed.
+- Symlink-to-dotfile bypass — even if a non-dotfile name is requested, the
+  resolved real path is checked again so an internal symlink cannot smuggle
+  access to `.git/`, `.env`, etc.
+- Dotfile exposure — any path segment beginning with `.` is rejected (403),
+  whether at the URL layer or after symlinks resolve.
+- Unintended LAN exposure — the default bind is `127.0.0.1`. Passing
+  `--host 0.0.0.0` (or any non-loopback address) prints a `WARNING` to
+  stderr so the choice is explicit.
+- Resource exhaustion from oversized requests — request line, header line,
+  total header bytes, and header count are bounded; offending clients receive
+  `414` or `431` and are disconnected.
+- Slow / idle clients — each request has a per-request read deadline
+  (default 10s, configurable). Stalled connections receive `408`.
+- Header injection — CR/LF in response header values is rejected at
+  construction time, so user-derived strings cannot inject extra headers.
+- Single-client monopolisation — connections are handled by a thread pool
+  capped at `max_connections` (default 8). Excess clients receive `503`.
+- Transient `accept(2)` errors — per-connection failures (`ECONNABORTED`,
+  `EMFILE`, etc.) are logged and skipped instead of killing the server.
+
+### What `wsv` does NOT do
+
+- Authentication, authorization, or rate limiting.
+- TLS / HTTPS.
+- Range requests, conditional `GET`, or HTTP keep-alive.
+- Production-grade DoS resistance under hostile network load.
+- Protect a directory you should not be sharing in the first place. The
+  bound is the directory you pass on the command line; if it contains
+  secrets, do not run `wsv` against it.
+
+If you need any of the above, use a real production server.
+
+## License
+
+MIT

data/bin/wsv

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "wsv"
+
+exit Wsv::CLI.new(ARGV).run

data/lib/wsv/app.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "path_resolver"
+require_relative "response"
+
+module Wsv
+  class App
+    ALLOWED_METHODS = %w[GET HEAD].freeze
+
+    def initialize(root)
+      @resolver = PathResolver.new(root)
+    end
+
+    def call(request)
+      head = request.head?
+
+      unless ALLOWED_METHODS.include?(request.method)
+        return Response.text(405, headers: { "Allow" => "GET, HEAD" }, head: head)
+      end
+
+      raw_path, query = request.target.split("?", 2)
+      result = @resolver.resolve(raw_path)
+
+      return Response.text(result.status, head: head) if result.error?
+      return Response.redirect(redirect_location(raw_path, query), head: head) if result.redirect?
+
+      Response.file(result.file, head: head)
+    end
+
+    private
+
+    def redirect_location(raw_path, query)
+      location = raw_path.end_with?("/") ? raw_path : "#{raw_path}/"
+      location += "?#{query}" if query && !query.empty?
+      location
+    end
+  end
+end

data/lib/wsv/cli.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "pathname"
+
+module Wsv
+  class CLI
+    DEFAULT_HOST = "127.0.0.1"
+    DEFAULT_PORT = 8000
+
+    attr_reader :argv
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @out = out
+      @err = err
+    end
+
+    def run
+      options = parse_options(argv)
+      return 0 if options[:handled]
+
+      root = resolve_root(options[:directory])
+      server = Server.new(host: options[:host], port: options[:port], root: root, out: @out, err: @err)
+      server.start
+      0
+    rescue OptionParser::ParseError, ArgumentError => e
+      @err.puts "wsv: #{e.message}"
+      @err.puts "Try `wsv --help` for usage."
+      1
+    rescue SystemCallError => e
+      @err.puts "wsv: #{e.message}"
+      1
+    end
+
+    def parse_options(args)
+      options = {
+        host: DEFAULT_HOST,
+        port: DEFAULT_PORT,
+        directory: Dir.pwd
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: wsv [options] [directory]"
+
+        opts.on("-h", "--host HOST", "Bind host (default: #{DEFAULT_HOST})") do |host|
+          options[:host] = host
+        end
+
+        opts.on("-p", "--port PORT", Integer, "Bind port (default: #{DEFAULT_PORT})") do |port|
+          options[:port] = validate_port(port)
+        end
+
+        opts.on("--help", "Show help") do
+          @out.puts opts
+          options[:handled] = true
+        end
+
+        opts.on("--version", "Show version") do
+          @out.puts Wsv::VERSION
+          options[:handled] = true
+        end
+      end
+
+      parser.parse!(args)
+      raise ArgumentError, "too many directories" if args.length > 1
+
+      options[:directory] = args.first if args.first
+      options
+    end
+
+    private
+
+    def resolve_root(directory)
+      path = Pathname.new(directory).expand_path
+      raise ArgumentError, "directory does not exist: #{directory}" unless path.exist?
+      raise ArgumentError, "not a directory: #{directory}" unless path.directory?
+
+      path.realpath.to_s
+    end
+
+    def validate_port(port)
+      raise ArgumentError, "port must be between 1 and 65535" unless port.between?(1, 65_535)
+
+      port
+    end
+  end
+end

data/lib/wsv/mime_types.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wsv
+  module MimeTypes
+    DEFAULT = "application/octet-stream"
+
+    TABLE = {
+      ".css" => "text/css; charset=utf-8",
+      ".gif" => "image/gif",
+      ".html" => "text/html; charset=utf-8",
+      ".htm" => "text/html; charset=utf-8",
+      ".ico" => "image/x-icon",
+      ".jpeg" => "image/jpeg",
+      ".jpg" => "image/jpeg",
+      ".js" => "text/javascript; charset=utf-8",
+      ".json" => "application/json; charset=utf-8",
+      ".mjs" => "text/javascript; charset=utf-8",
+      ".pdf" => "application/pdf",
+      ".png" => "image/png",
+      ".svg" => "image/svg+xml; charset=utf-8",
+      ".txt" => "text/plain; charset=utf-8",
+      ".wasm" => "application/wasm",
+      ".webp" => "image/webp",
+      ".woff" => "font/woff",
+      ".woff2" => "font/woff2"
+    }.freeze
+
+    def self.for_file(file)
+      TABLE.fetch(File.extname(file).downcase, DEFAULT)
+    end
+  end
+end

data/lib/wsv/path_resolver.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Wsv
+  class PathResolver
+    class Result
+      attr_reader :status, :file
+
+      def initialize(kind:, status: nil, file: nil)
+        @kind = kind
+        @status = status
+        @file = file
+      end
+
+      def file?
+        @kind == :file
+      end
+
+      def redirect?
+        @kind == :redirect
+      end
+
+      def error?
+        @kind == :error
+      end
+
+      def self.file(path)
+        new(kind: :file, status: 200, file: path)
+      end
+
+      def self.redirect
+        new(kind: :redirect, status: 301)
+      end
+
+      def self.error(status)
+        new(kind: :error, status: status)
+      end
+    end
+
+    def initialize(root)
+      @root = root
+    end
+
+    def resolve(raw_path)
+      decoded = decode(raw_path)
+      return Result.error(400) unless decoded
+
+      relative = decoded.sub(%r{\A/+}, "")
+      return Result.error(403) if hidden_segment?(relative)
+
+      candidate = File.expand_path(relative, @root)
+      return Result.error(403) unless within?(candidate)
+      return Result.error(404) unless File.exist?(candidate)
+
+      real = File.realpath(candidate)
+      return Result.error(403) unless within?(real)
+      return Result.error(403) if hidden_under_root?(real)
+
+      if File.directory?(real)
+        return Result.redirect unless decoded.end_with?("/")
+
+        index = File.join(real, "index.html")
+        return Result.error(404) unless File.file?(index)
+
+        return Result.file(index)
+      end
+
+      return Result.error(404) unless File.file?(real)
+
+      Result.file(real)
+    rescue Errno::ENOENT, Errno::ELOOP, Errno::EACCES
+      Result.error(404)
+    end
+
+    private
+
+    def decode(raw_path)
+      path = URI(raw_path.to_s).path
+      percent_decode(path)
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def percent_decode(string)
+      decoded = string.gsub(/%([0-9a-fA-F]{2})/) { ::Regexp.last_match(1).hex.chr }
+      decoded.force_encoding(Encoding::UTF_8)
+      return nil unless decoded.valid_encoding?
+
+      decoded
+    end
+
+    def hidden_segment?(relative)
+      relative.split("/").any? do |segment|
+        next false if segment.empty? || segment == "." || segment == ".."
+
+        segment.start_with?(".")
+      end
+    end
+
+    def within?(path)
+      path == @root || path.start_with?("#{@root}#{File::SEPARATOR}")
+    end
+
+    def hidden_under_root?(real)
+      return false if real == @root
+
+      hidden_segment?(real[(@root.length + 1)..])
+    end
+  end
+end

data/lib/wsv/request.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Wsv
+  class Request
+    REQUEST_LINE_LIMIT = 8192
+    HEADER_LINE_LIMIT = 8192
+    HEADER_COUNT_LIMIT = 100
+    HEADER_TOTAL_LIMIT = 16384
+
+    class TooLarge < StandardError
+      attr_reader :status_code
+
+      def initialize(status_code)
+        super("request exceeded size limit (#{status_code})")
+        @status_code = status_code
+      end
+    end
+
+    attr_reader :method, :target, :version, :headers
+
+    def initialize(method:, target:, version:, headers:)
+      @method = method
+      @target = target
+      @version = version
+      @headers = headers
+    end
+
+    def head?
+      method == "HEAD"
+    end
+
+    def self.parse(io)
+      line = io.gets(REQUEST_LINE_LIMIT)
+      return :empty unless line
+      raise TooLarge, 414 if line.bytesize >= REQUEST_LINE_LIMIT && !line.end_with?("\n")
+
+      method, target, version = line.split(/\s+/, 3)
+      version = version&.strip
+      return :malformed unless method && target && version&.start_with?("HTTP/")
+
+      headers = read_headers(io)
+      new(method: method, target: target, version: version, headers: headers)
+    end
+
+    def self.read_headers(io)
+      headers = {}
+      total = 0
+      count = 0
+      while (line = io.gets(HEADER_LINE_LIMIT))
+        raise TooLarge, 431 if line.bytesize >= HEADER_LINE_LIMIT && !line.end_with?("\n")
+
+        stripped = line.delete_suffix("\r\n").delete_suffix("\n").delete_suffix("\r")
+        break if stripped.empty?
+
+        count += 1
+        raise TooLarge, 431 if count > HEADER_COUNT_LIMIT
+
+        total += line.bytesize
+        raise TooLarge, 431 if total > HEADER_TOTAL_LIMIT
+
+        name, value = stripped.split(":", 2)
+        headers[name.downcase] = value.strip if name && value
+      end
+      headers
+    end
+    private_class_method :read_headers
+  end
+end

data/lib/wsv/response.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "mime_types"
+require_relative "status"
+require_relative "version"
+
+module Wsv
+  class Response
+    SERVER_NAME = "wsv/#{Wsv::VERSION}".freeze
+
+    INVALID_HEADER_NAME = /[\s:]/
+    INVALID_HEADER_VALUE = /[\r\n]/
+
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers: {}, body: "")
+      headers.each do |name, value|
+        raise ArgumentError, "invalid header name: #{name.inspect}" if name.to_s.match?(INVALID_HEADER_NAME)
+        raise ArgumentError, "invalid header value: #{value.inspect}" if value.to_s.match?(INVALID_HEADER_VALUE)
+      end
+      @status = status
+      @headers = headers
+      @body = body
+    end
+
+    def reason
+      Status.reason(status)
+    end
+
+    def write_to(io)
+      io.write "HTTP/1.1 #{status} #{reason}\r\n"
+      io.write "Server: #{SERVER_NAME}\r\n"
+      io.write "Connection: close\r\n"
+      headers.each { |name, value| io.write "#{name}: #{value}\r\n" }
+      io.write "\r\n"
+      io.write body
+    end
+
+    def self.text(status, headers: {}, head: false)
+      body = "#{status} #{Status.reason(status)}\n"
+      base = {
+        "Content-Type" => "text/plain; charset=utf-8",
+        "Content-Length" => body.bytesize.to_s,
+        "Cache-Control" => "no-cache"
+      }
+      new(status: status, headers: base.merge(headers), body: head ? "" : body)
+    end
+
+    def self.file(path, head: false)
+      new(
+        status: 200,
+        headers: {
+          "Content-Type" => MimeTypes.for_file(path),
+          "Content-Length" => File.size(path).to_s,
+          "Last-Modified" => File.mtime(path).httpdate,
+          "Cache-Control" => "no-cache"
+        },
+        body: head ? "" : File.binread(path)
+      )
+    end
+
+    def self.redirect(location, head: false)
+      text(301, headers: { "Location" => location }, head: head)
+    end
+  end
+end