wsv 0.9.0 → 0.10.1

data/test/app_test.rb

@@ -186,6 +186,124 @@ class AppTest < Minitest::Test
     assert_equal "3", response.headers["Content-Length"]
   end
 
+  def test_spa_fallback_serves_index_for_missing_path
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/users/123"))
+
+    assert_equal 200, response.status
+    assert_equal "<h1>SPA</h1>", response.body
+    assert_equal "text/html; charset=utf-8", response.headers["Content-Type"]
+  end
+
+  def test_spa_fallback_head_serves_index_headers_without_body
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("HEAD", "/users/123"))
+
+    assert_equal 200, response.status
+    assert_equal "", response.body
+    assert_equal "text/html; charset=utf-8", response.headers["Content-Type"]
+    assert_equal "12", response.headers["Content-Length"]
+  end
+
+  def test_spa_disabled_returns_404_for_missing_path
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+
+    response = @app.call(req("GET", "/users/123"))
+
+    assert_equal 404, response.status
+  end
+
+  def test_spa_keeps_403_for_dotfile
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    File.write(File.join(@dir, ".env"), "secret")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/.env"))
+
+    assert_equal 403, response.status
+  end
+
+  def test_spa_keeps_403_for_path_traversal
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/../etc/passwd"))
+
+    assert_equal 403, response.status
+  end
+
+  def test_spa_returns_404_when_no_index_html
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/users/123"))
+
+    assert_equal 404, response.status
+  end
+
+  def test_spa_serves_real_file_when_path_matches
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    File.write(File.join(@dir, "robots.txt"), "User-agent: *")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/robots.txt"))
+
+    assert_equal 200, response.status
+    assert_equal "User-agent: *", response.body
+  end
+
+  def test_custom_404_page_when_404_html_exists
+    File.write(File.join(@dir, "404.html"), "<h1>not found</h1>")
+
+    response = @app.call(req("GET", "/missing.txt"))
+
+    assert_equal 404, response.status
+    assert_equal "<h1>not found</h1>", response.body
+    assert_equal "text/html; charset=utf-8", response.headers["Content-Type"]
+  end
+
+  def test_no_custom_404_falls_back_to_plain_text
+    response = @app.call(req("GET", "/missing.txt"))
+
+    assert_equal 404, response.status
+    assert_includes response.body, "404 Not Found"
+    assert_equal "text/plain; charset=utf-8", response.headers["Content-Type"]
+  end
+
+  def test_custom_404_does_not_apply_to_403
+    File.write(File.join(@dir, "404.html"), "<h1>not found</h1>")
+    File.write(File.join(@dir, ".env"), "secret")
+
+    response = @app.call(req("GET", "/.env"))
+
+    assert_equal 403, response.status
+    refute_includes response.body, "<h1>not found</h1>"
+  end
+
+  def test_spa_mode_takes_precedence_over_custom_404
+    File.write(File.join(@dir, "index.html"), "<h1>SPA</h1>")
+    File.write(File.join(@dir, "404.html"), "<h1>not found</h1>")
+    spa_app = Wsv::App.new(File.realpath(@dir), spa: true)
+
+    response = spa_app.call(req("GET", "/users/123"))
+
+    assert_equal 200, response.status
+    assert_equal "<h1>SPA</h1>", response.body
+  end
+
+  def test_custom_404_works_with_head
+    File.write(File.join(@dir, "404.html"), "<h1>not found</h1>")
+
+    response = @app.call(req("HEAD", "/missing.txt"))
+
+    assert_equal 404, response.status
+    assert_equal "", response.body
+    assert_equal "text/html; charset=utf-8", response.headers["Content-Type"]
+  end
+
   def test_serves_single_byte_range
     File.write(File.join(@dir, "data.bin"), "abcdefghij")
 
@@ -219,6 +337,82 @@ class AppTest < Minitest::Test
     assert_equal "bytes", response.headers["Accept-Ranges"]
   end
 
+  def test_cors_disabled_omits_acao_header
+    File.write(File.join(@dir, "x.txt"), "hi")
+
+    response = @app.call(req("GET", "/x.txt"))
+
+    refute response.headers.key?("Access-Control-Allow-Origin")
+  end
+
+  def test_cors_adds_acao_to_successful_response
+    File.write(File.join(@dir, "x.txt"), "hi")
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("GET", "/x.txt"))
+
+    assert_equal 200, response.status
+    assert_equal "hi", response.body
+    assert_equal "*", response.headers["Access-Control-Allow-Origin"]
+    assert_equal "Origin", response.headers["Vary"]
+  end
+
+  def test_cors_adds_acao_to_error_response
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("GET", "/missing.txt"))
+
+    assert_equal 404, response.status
+    assert_equal "*", response.headers["Access-Control-Allow-Origin"]
+  end
+
+  def test_cors_preflight_returns_204_with_methods_and_max_age
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("OPTIONS", "/x.txt"))
+
+    assert_equal 204, response.status
+    assert_equal "*", response.headers["Access-Control-Allow-Origin"]
+    assert_equal "GET, HEAD, OPTIONS", response.headers["Access-Control-Allow-Methods"]
+    assert_equal "86400", response.headers["Access-Control-Max-Age"]
+    assert_equal "Origin", response.headers["Vary"]
+    assert_equal "", response.body
+  end
+
+  def test_cors_preflight_echoes_requested_headers
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("OPTIONS", "/x.txt", "access-control-request-headers" => "X-Custom, Authorization"))
+
+    assert_equal 204, response.status
+    assert_equal "X-Custom, Authorization", response.headers["Access-Control-Allow-Headers"]
+  end
+
+  def test_cors_preflight_omits_allow_headers_when_not_requested
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("OPTIONS", "/x.txt"))
+
+    refute response.headers.key?("Access-Control-Allow-Headers")
+  end
+
+  def test_options_without_cors_returns_405
+    response = @app.call(req("OPTIONS", "/x.txt"))
+
+    assert_equal 405, response.status
+    assert_equal "GET, HEAD", response.headers["Allow"]
+  end
+
+  def test_cors_405_advertises_options_in_allow
+    cors_app = Wsv::App.new(File.realpath(@dir), cors: true)
+
+    response = cors_app.call(req("POST", "/x.txt"))
+
+    assert_equal 405, response.status
+    assert_equal "GET, HEAD, OPTIONS", response.headers["Allow"]
+    assert_equal "*", response.headers["Access-Control-Allow-Origin"]
+  end
+
   def test_multipart_range_falls_through_to_200
     File.write(File.join(@dir, "data.bin"), "abcdefghij")
 

data/test/browser_launcher_test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class BrowserLauncherTest < Minitest::Test
+  def test_loopback_host_used_directly
+    launcher = build(host: "127.0.0.1")
+
+    assert_equal "http://127.0.0.1:8000/", launcher.send(:url)
+  end
+
+  def test_wildcard_v4_translated_to_loopback
+    launcher = build(host: "0.0.0.0")
+
+    assert_equal "http://127.0.0.1:8000/", launcher.send(:url)
+  end
+
+  def test_wildcard_v6_translated_to_loopback
+    launcher = build(host: "::")
+
+    assert_equal "http://[::1]:8000/", launcher.send(:url)
+  end
+
+  def test_ipv6_literal_host_is_bracketed
+    launcher = build(host: "::1")
+
+    assert_equal "http://[::1]:8000/", launcher.send(:url)
+  end
+
+  def test_specific_host_passes_through
+    launcher = build(host: "192.168.1.5")
+
+    assert_equal "http://192.168.1.5:8000/", launcher.send(:url)
+  end
+
+  def test_https_scheme_when_tls_present
+    launcher = build(host: "127.0.0.1", tls: Object.new)
+
+    assert_equal "https://127.0.0.1:8000/", launcher.send(:url)
+  end
+
+  def test_logs_when_platform_unsupported
+    err = StringIO.new
+    launcher = build(host: "127.0.0.1", err: err)
+    launcher.define_singleton_method(:platform_command) { nil }
+
+    launcher.launch
+
+    assert_includes err.string, "not supported on this platform"
+  end
+
+  private
+
+  def build(host:, tls: nil, err: StringIO.new)
+    Wsv::Server::BrowserLauncher.new(host: host, port: 8000, tls: tls, err: err)
+  end
+end

data/test/cli_test.rb

@@ -42,6 +42,8 @@ class CLITest < Minitest::Test
     assert_equal 0, code
     assert_includes out.string, "Usage: wsv"
     assert_includes out.string, "--host HOST"
+    assert_includes out.string, "Examples:"
+    assert_includes out.string, "wsv _site"
   end
 
   def test_version
@@ -68,4 +70,66 @@ class CLITest < Minitest::Test
     assert_equal 1, code
     assert_includes err.string, "directory does not exist"
   end
+
+  def test_tls_flag_parses
+    Dir.mktmpdir do |dir|
+      options = Wsv::CLI.new([]).parse_options(["--tls", dir])
+
+      assert options[:tls]
+    end
+  end
+
+  def test_cert_without_key_errors
+    err = StringIO.new
+    Dir.mktmpdir do |dir|
+      code = Wsv::CLI.new(["--cert", "/nonexistent/cert.pem", dir], err: err).run
+
+      assert_equal 1, code
+      assert_includes err.string, "must be provided together"
+    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])
+
+      assert_equal "a.pem", options[:cert]
+      assert_equal "b.pem", options[:key]
+    end
+  end
+
+  def test_spa_flag_parses
+    Dir.mktmpdir do |dir|
+      options = Wsv::CLI.new([]).parse_options(["--spa", dir])
+
+      assert options[:spa]
+      assert_equal dir, options[:directory]
+    end
+  end
+
+  def test_cors_flag_parses
+    Dir.mktmpdir do |dir|
+      options = Wsv::CLI.new([]).parse_options(["--cors", dir])
+
+      assert options[:cors]
+      assert_equal dir, options[:directory]
+    end
+  end
+
+  def test_cors_default_off
+    Dir.mktmpdir do |dir|
+      options = Wsv::CLI.new([]).parse_options([dir])
+
+      refute options[:cors]
+    end
+  end
+
+  def test_open_flag_parses
+    Dir.mktmpdir do |dir|
+      options = Wsv::CLI.new([]).parse_options(["--open", dir])
+
+      assert options[:open]
+      assert_equal dir, options[:directory]
+    end
+  end
 end

data/test/response_test.rb

@@ -46,6 +46,14 @@ class ResponseTest < Minitest::Test
     assert_includes io.string, "HTTP/1.1 404 Not Found"
   end
 
+  def test_write_to_emits_nosniff_header
+    response = Wsv::Response.text(200)
+    io = StringIO.new
+    response.write_to(io)
+
+    assert_includes io.string, "X-Content-Type-Options: nosniff"
+  end
+
   def test_file_response_streams_via_io_copy_stream
     Dir.mktmpdir do |dir|
       path = File.join(dir, "data.bin")

data/test/server_test.rb

@@ -198,6 +198,23 @@ class ServerTest < Minitest::Test
     refute_includes err.string, "WARNING"
   end
 
+  def test_banner_brackets_ipv6_address_in_url
+    out = StringIO.new
+    server = Wsv::Server.new(host: "::1", port: 8000, root: @dir, out: out, err: StringIO.new)
+    server.send(:log_startup)
+
+    assert_includes out.string, "http://[::1]:8000/"
+    refute_includes out.string, "http://::1:8000/"
+  end
+
+  def test_banner_percent_encodes_ipv6_zone_identifier
+    out = StringIO.new
+    server = Wsv::Server.new(host: "fe80::1%eth0", port: 8000, root: @dir, out: out, err: StringIO.new)
+    server.send(:log_startup)
+
+    assert_includes out.string, "http://[fe80::1%25eth0]:8000/"
+  end
+
   def test_accept_loop_survives_transient_accept_error
     File.write(File.join(@dir, "x.txt"), "ok")
     err = StringIO.new
@@ -253,6 +270,37 @@ class ServerTest < Minitest::Test
     assert_equal "304", response.code
   end
 
+  def test_serves_over_tls
+    File.write(File.join(@dir, "x.txt"), "secret")
+    start_server(tls: build_ephemeral_tls)
+
+    response = Net::HTTP.start("127.0.0.1", @server.port, use_ssl: true,
+                                                          verify_mode: OpenSSL::SSL::VERIFY_NONE) do |http|
+      http.get("/x.txt")
+    end
+
+    assert_equal "200", response.code
+    assert_equal "secret", response.body
+  end
+
+  def test_logs_https_scheme_when_tls_enabled
+    out = StringIO.new
+    @server = Wsv::Server.new(host: "127.0.0.1", port: 0, root: @dir,
+                              out: out, err: StringIO.new, tls: build_ephemeral_tls)
+    @server.send(:log_startup)
+
+    assert_includes out.string, "https://"
+  end
+
+  def test_warns_about_self_signed_cert
+    err = StringIO.new
+    @server = Wsv::Server.new(host: "127.0.0.1", port: 0, root: @dir,
+                              out: StringIO.new, err: err, tls: build_ephemeral_tls)
+    @server.send(:log_startup)
+
+    assert_includes err.string, "self-signed"
+  end
+
   def test_unsupported_method
     start_server
 
@@ -264,14 +312,15 @@ class ServerTest < Minitest::Test
 
   private
 
-  def start_server(read_timeout: Wsv::Server::DEFAULT_READ_TIMEOUT)
+  def start_server(read_timeout: Wsv::Server::DEFAULT_READ_TIMEOUT, tls: nil)
     @server = Wsv::Server.new(
       host: "127.0.0.1",
       port: free_port,
       root: @dir,
       out: StringIO.new,
       err: StringIO.new,
-      read_timeout: read_timeout
+      read_timeout: read_timeout,
+      tls: tls
     )
     @thread = Thread.new { @server.start }
     wait_until_ready
@@ -298,6 +347,12 @@ class ServerTest < Minitest::Test
     end
   end
 
+  def build_ephemeral_tls
+    key = OpenSSL::PKey::RSA.new(2048)
+    cert = Wsv::TlsContext::SelfSignedCert.build(key)
+    Wsv::TlsContext.new(cert: cert, key: key, ephemeral: true)
+  end
+
   def free_port
     server = TCPServer.new("127.0.0.1", 0)
     server.addr[1]

data/test/tls_context_test.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TlsContextTest < Minitest::Test
+  def test_to_ssl_context_returns_configured_ssl_context
+    key = OpenSSL::PKey::RSA.new(2048)
+    cert = Wsv::TlsContext::SelfSignedCert.build(key)
+    tls = Wsv::TlsContext.new(cert: cert, key: key)
+
+    ssl = tls.to_ssl_context
+
+    assert_kind_of OpenSSL::SSL::SSLContext, ssl
+    assert_equal cert, ssl.cert
+    assert_equal key, ssl.key
+  end
+
+  def test_ephemeral_predicate
+    key = OpenSSL::PKey::RSA.new(2048)
+    cert = Wsv::TlsContext::SelfSignedCert.build(key)
+
+    refute_predicate Wsv::TlsContext.new(cert: cert, key: key), :ephemeral?
+    assert_predicate Wsv::TlsContext.new(cert: cert, key: key, ephemeral: true), :ephemeral?
+  end
+end
+
+class SelfSignedCertTest < Minitest::Test
+  def test_subject_is_localhost
+    cert = build
+
+    assert_equal "/CN=localhost", cert.subject.to_s
+  end
+
+  def test_san_includes_localhost_and_loopback
+    san = build.extensions.find { |ext| ext.oid == "subjectAltName" }.value
+
+    assert_includes san, "DNS:localhost"
+    assert_includes san, "IP Address:127.0.0.1"
+    assert_includes san, "IP Address:0:0:0:0:0:0:0:1"
+  end
+
+  def test_signed_with_provided_key
+    key = OpenSSL::PKey::RSA.new(2048)
+    cert = Wsv::TlsContext::SelfSignedCert.build(key)
+
+    assert cert.verify(key.public_key)
+  end
+
+  private
+
+  def build
+    Wsv::TlsContext::SelfSignedCert.build(OpenSSL::PKey::RSA.new(2048))
+  end
+end
+
+class TlsContextResolverTest < Minitest::Test
+  def test_resolves_explicit_paths
+    Dir.mktmpdir do |dir|
+      cert_path, key_path = write_self_signed(dir)
+
+      tls = Wsv::TlsContext::Resolver.resolve(cert_path: cert_path, key_path: key_path)
+
+      refute_predicate tls, :ephemeral?
+    end
+  end
+
+  def test_requires_both_cert_and_key
+    assert_raises(ArgumentError) do
+      Wsv::TlsContext::Resolver.resolve(cert_path: "/some/cert.pem", key_path: nil)
+    end
+
+    assert_raises(ArgumentError) do
+      Wsv::TlsContext::Resolver.resolve(cert_path: nil, key_path: "/some/key.pem")
+    end
+  end
+
+  def test_uses_xdg_when_present
+    Dir.mktmpdir do |xdg|
+      wsv_dir = File.join(xdg, "wsv")
+      FileUtils.mkdir_p(wsv_dir)
+      write_self_signed(wsv_dir, cert_name: "cert.pem", key_name: "key.pem")
+
+      with_env("XDG_CONFIG_HOME" => xdg) do
+        tls = Wsv::TlsContext::Resolver.resolve
+
+        refute_predicate tls, :ephemeral?
+      end
+    end
+  end
+
+  def test_falls_back_to_ephemeral_when_no_xdg
+    Dir.mktmpdir do |xdg|
+      with_env("XDG_CONFIG_HOME" => xdg) do
+        tls = Wsv::TlsContext::Resolver.resolve
+
+        assert_predicate tls, :ephemeral?
+      end
+    end
+  end
+
+  def test_errors_when_only_one_xdg_file_present
+    Dir.mktmpdir do |xdg|
+      wsv_dir = File.join(xdg, "wsv")
+      FileUtils.mkdir_p(wsv_dir)
+      File.write(File.join(wsv_dir, "cert.pem"), "stub")
+
+      with_env("XDG_CONFIG_HOME" => xdg) do
+        assert_raises(ArgumentError) { Wsv::TlsContext::Resolver.resolve }
+      end
+    end
+  end
+
+  def test_raises_openssl_error_for_malformed_cert
+    Dir.mktmpdir do |dir|
+      _cert_path, key_path = write_self_signed(dir)
+      bad_cert = File.join(dir, "bad-cert.pem")
+      File.write(bad_cert, "this is not a PEM\n")
+
+      assert_raises(OpenSSL::X509::CertificateError) do
+        Wsv::TlsContext::Resolver.resolve(cert_path: bad_cert, key_path: key_path)
+      end
+    end
+  end
+
+  def test_raises_openssl_error_for_malformed_key
+    Dir.mktmpdir do |dir|
+      cert_path, _key_path = write_self_signed(dir)
+      bad_key = File.join(dir, "bad-key.pem")
+      File.write(bad_key, "this is not a PEM\n")
+
+      assert_raises(OpenSSL::PKey::PKeyError) do
+        Wsv::TlsContext::Resolver.resolve(cert_path: cert_path, key_path: bad_key)
+      end
+    end
+  end
+
+  def test_raises_argument_error_when_cert_and_key_do_not_match
+    Dir.mktmpdir do |dir|
+      cert_path, = write_self_signed(dir, cert_name: "a.pem", key_name: "a.key")
+      _, foreign_key = write_self_signed(dir, cert_name: "b.pem", key_name: "b.key")
+
+      err = assert_raises(ArgumentError) do
+        Wsv::TlsContext::Resolver.resolve(cert_path: cert_path, key_path: foreign_key)
+      end
+
+      assert_includes err.message, "does not match"
+    end
+  end
+
+  private
+
+  def write_self_signed(dir, cert_name: "test-cert.pem", key_name: "test-key.pem")
+    key = OpenSSL::PKey::RSA.new(2048)
+    cert = Wsv::TlsContext::SelfSignedCert.build(key)
+    cert_path = File.join(dir, cert_name)
+    key_path = File.join(dir, key_name)
+    File.write(cert_path, cert.to_pem)
+    File.write(key_path, key.to_pem)
+    [cert_path, key_path]
+  end
+
+  def with_env(overrides)
+    original = ENV.to_h
+    overrides.each { |k, v| ENV[k] = v }
+    yield
+  ensure
+    ENV.replace(original)
+  end
+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