wintertc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d89343a04cf6097d2229ad2d14423636f3909bc5e101e07d2d3d0787ac0f272
+  data.tar.gz: ff8a77f280384bcf57b63763173dffa1fa7f29fd2edd6d3654f18cf9490ed50a
+SHA512:
+  metadata.gz: a1ac56ebd31fa3411fb4cfa34ed461d0207a5c5a67f0fdc0f8f9e85d3a8ee96a19d349738921a5ffee12a82f46a5370bc4b89b2c01bd505e8c52e59d1530734d
+  data.tar.gz: ac43fdc877c54158e05ded060284a2d5700e66539bf9af887bd8d4e58787f977cd1dab9f5fe4cd4bfd96f04f8332021fb9b8a5aae6eb297b32573a6cb3fad9c4

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-08
+
+### Added
+- Initial release.
+- `WinterTc::Headers` — case-insensitive HTTP header map.
+- `WinterTc::Request` — immutable HTTP request object.
+- `WinterTc::Response` — HTTP response with `#text`, `#json`, `#ok` helpers, and `.json` static constructor.
+- `WinterTc.fetch` — synchronous Fetch-API-compatible HTTP client.
+- RBS type signatures in `sig/wintertc.rbs`.
+- GitHub Actions CI for Ruby 3.3, 3.4, and head.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kuboon
+
+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,137 @@
+# wintertc.rb
+
+[![CI](https://github.com/kuboon/wintertc.rb/actions/workflows/ci.yml/badge.svg)](https://github.com/kuboon/wintertc.rb/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/wintertc.svg)](https://badge.fury.io/rb/wintertc)
+
+A Ruby HTTP client whose interface mirrors the JavaScript
+[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) as
+closely as possible.
+
+**No runtime gem dependencies** — only Ruby's built-in `net/http`, `uri`, and
+`json` standard-library modules are used.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "wintertc"
+```
+
+or install directly:
+
+```
+gem install wintertc
+```
+
+## Quick Start
+
+```ruby
+require "wintertc"
+
+# Simple GET
+response = WinterTc.fetch("https://httpbin.org/get")
+puts response.status        # => 200
+puts response.ok            # => true
+puts response.json["url"]   # => "https://httpbin.org/get"
+
+# POST with a JSON body
+response = WinterTc.fetch(
+  "https://httpbin.org/post",
+  method:  "POST",
+  headers: { "Content-Type" => "application/json" },
+  body:    JSON.generate({ hello: "world" })
+)
+puts response.json["json"]  # => {"hello"=>"world"}
+
+# Re-use a Request object
+req = WinterTc::Request.new("https://httpbin.org/get")
+response = WinterTc.fetch(req)
+```
+
+## API Reference
+
+### `WinterTc.fetch(input, **options) → Response`
+
+Performs a synchronous HTTP request and returns a `Response`.
+
+| Option     | Type                              | Default    | Description                                         |
+|------------|-----------------------------------|------------|-----------------------------------------------------|
+| `method`   | `String`                          | `"GET"`    | HTTP verb (GET, POST, PUT, PATCH, DELETE, …)        |
+| `headers`  | `Hash` / `WinterTc::Headers`      | `{}`       | Request headers                                     |
+| `body`     | `String` / `nil`                  | `nil`      | Request body                                        |
+| `redirect` | `:follow` / `:manual` / `:error`  | `:follow`  | Redirect strategy                                   |
+
+Redirects on 301/302/303 change the method to `GET`; 307/308 preserve the
+original method — consistent with browser behaviour.
+
+### `WinterTc::Headers`
+
+A case-insensitive header map.
+
+```ruby
+h = WinterTc::Headers.new("Content-Type" => "text/html")
+h.get("content-type")   # => "text/html"
+h.has("Content-Type")   # => true
+h.set("Accept", "application/json")
+h.append("Accept", "text/plain")
+h.get("accept")         # => "application/json, text/plain"
+h.delete("accept")
+h.to_h                  # => {}
+```
+
+### `WinterTc::Request`
+
+```ruby
+req = WinterTc::Request.new(
+  "https://api.example.com/items",
+  method:  "POST",
+  headers: { "Authorization" => "Bearer token" },
+  body:    JSON.generate({ name: "widget" })
+)
+req.url     # => "https://api.example.com/items"
+req.method  # => "POST"
+req.headers # => #<WinterTc::Headers ...>
+req.body    # => '{"name":"widget"}'
+
+# Clone with overrides
+updated = WinterTc::Request.new(req, body: JSON.generate({ name: "gadget" }))
+```
+
+### `WinterTc::Response`
+
+```ruby
+response.status       # => 200
+response.ok           # => true  (status 200–299)
+response.ok?          # alias for ok
+response.status_text  # => "OK"
+response.headers      # => #<WinterTc::Headers ...>
+response.text         # => raw body string
+response.json         # => parsed JSON (raises JSON::ParserError on invalid JSON)
+response.url          # => final URL after redirects
+```
+
+## Error Classes
+
+| Class                          | Raised when                                       |
+|--------------------------------|---------------------------------------------------|
+| `WinterTc::Error`              | Base class for all WinterTc errors                |
+| `WinterTc::TooManyRedirectsError` | More than `WinterTc::MAX_REDIRECTS` redirects  |
+| `WinterTc::RedirectError`      | `redirect: :error` and a redirect is received     |
+| `WinterTc::UnsupportedMethodError` | An unknown HTTP verb is requested             |
+
+## Type Signatures (RBS)
+
+RBS signatures are shipped in `sig/wintertc.rbs` and are compatible with
+[Steep](https://github.com/soutaro/steep) and other RBS-aware tools.
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/wintertc/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module WinterTc
+  # Base class for all WinterTc errors.
+  class Error < StandardError; end
+
+  # Raised when more redirects than {WinterTc::MAX_REDIRECTS} are encountered.
+  class TooManyRedirectsError < Error; end
+
+  # Raised when a redirect is encountered and `redirect: :error` is set.
+  class RedirectError < Error; end
+
+  # Raised when an unsupported HTTP method is requested.
+  class UnsupportedMethodError < Error; end
+end

data/lib/wintertc/fetch.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module WinterTc
+  # The default maximum number of redirects that {WinterTc.fetch} will follow
+  # before raising {TooManyRedirectsError}.
+  MAX_REDIRECTS = 20
+
+  # @api private
+  # Maps HTTP method strings to Net::HTTP request classes.
+  NET_HTTP_METHOD_MAP = {
+    "GET"     => Net::HTTP::Get,
+    "POST"    => Net::HTTP::Post,
+    "PUT"     => Net::HTTP::Put,
+    "PATCH"   => Net::HTTP::Patch,
+    "DELETE"  => Net::HTTP::Delete,
+    "HEAD"    => Net::HTTP::Head,
+    "OPTIONS" => Net::HTTP::Options,
+  }.freeze
+  private_constant :NET_HTTP_METHOD_MAP
+
+  class << self
+    # Performs an HTTP request, mirroring the JavaScript
+    # {https://developer.mozilla.org/en-US/docs/Web/API/fetch fetch()} function.
+    #
+    # Unlike the JavaScript version this method is *synchronous* — it blocks
+    # until the server returns a complete response (no Promise / async / await).
+    #
+    # Redirects are followed automatically by default (up to {MAX_REDIRECTS}
+    # hops).  On 301 / 302 / 303 responses the method is changed to GET, while
+    # 307 / 308 preserve the original method — consistent with browser behaviour.
+    #
+    # @param input    [String, Request]  target URL string or a {Request} object.
+    # @param method   [String, nil]      HTTP method (default: +"GET"+).  Ignored
+    #   when +input+ is a Request and +method+ is not explicitly provided.
+    # @param headers  [Hash, Headers, nil]  request headers.
+    # @param body     [String, nil]      request body.
+    # @param redirect [Symbol]           redirect handling strategy:
+    #   * +:follow+ (default) — follow redirects transparently.
+    #   * +:manual+ — return the 3xx response as-is without following.
+    #   * +:error+  — raise {RedirectError} when a redirect is encountered.
+    # @return [Response]
+    # @raise [ArgumentError]          if the URL scheme is not http or https.
+    # @raise [TooManyRedirectsError]  if more than {MAX_REDIRECTS} redirects
+    #   are encountered.
+    # @raise [RedirectError]          if +redirect: :error+ and a redirect
+    #   response is returned.
+    #
+    # @example Simple GET
+    #   response = WinterTc.fetch("https://example.com")
+    #   puts response.status   #=> 200
+    #   puts response.ok       #=> true
+    #   puts response.text     #=> "<html>..."
+    #
+    # @example POST with a JSON body
+    #   response = WinterTc.fetch(
+    #     "https://api.example.com/items",
+    #     method:  "POST",
+    #     headers: { "Content-Type" => "application/json" },
+    #     body:    JSON.generate({ name: "widget" })
+    #   )
+    #   item = response.json   #=> { "id" => 42, "name" => "widget" }
+    #
+    # @example Re-using a Request object
+    #   req = WinterTc::Request.new("https://api.example.com/items", method: "GET")
+    #   response = WinterTc.fetch(req)
+    def fetch(input, method: nil, headers: nil, body: nil, redirect: :follow, **_opts)
+      request = build_request(input, method: method, headers: headers, body: body)
+      perform(request, redirect: redirect, hops: 0)
+    end
+
+    private
+
+    # Builds a {Request} from a URL string or existing Request, applying
+    # any extra keyword-argument overrides.
+    def build_request(input, method:, headers:, body:)
+      if input.is_a?(Request)
+        Request.new(input, method: method, headers: headers, body: body)
+      else
+        Request.new(input.to_s, method: method, headers: headers, body: body)
+      end
+    end
+
+    # Executes the HTTP request, handling redirects recursively.
+    def perform(request, redirect:, hops:)
+      uri     = parse_uri(request.url)
+      net_req = build_net_request(request, uri)  # validate method before opening a socket
+
+      net_response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(net_req)
+      end
+
+      if net_response.is_a?(Net::HTTPRedirection)
+        handle_redirect(net_response, request, redirect: redirect, hops: hops)
+      else
+        build_response(net_response, url: request.url)
+      end
+    end
+
+    # Parses a URL string into a URI, raising ArgumentError for non-HTTP(S) URLs.
+    def parse_uri(url)
+      uri = URI.parse(url)
+      unless uri.is_a?(URI::HTTP)
+        raise ArgumentError, "Only http and https URLs are supported; got: #{url.inspect}"
+      end
+
+      uri
+    end
+
+    # Builds a Net::HTTP request object from a {Request}.
+    def build_net_request(request, uri)
+      klass = NET_HTTP_METHOD_MAP[request.method] ||
+        raise(UnsupportedMethodError, "Unsupported HTTP method: #{request.method}")
+
+      net_req = klass.new(uri.request_uri)
+      request.headers.each { |name, value| net_req[name] = value }
+      net_req.body = request.body if request.body
+      net_req
+    end
+
+    # Handles a 3xx redirect response according to the +redirect+ strategy.
+    def handle_redirect(net_response, original_request, redirect:, hops:)
+      case redirect
+      when :follow
+        if hops >= MAX_REDIRECTS
+          raise TooManyRedirectsError,
+                "Too many redirects (maximum is #{MAX_REDIRECTS})"
+        end
+
+        location = net_response["location"]
+        unless location
+          raise RedirectError,
+                "Redirect response (#{net_response.code}) is missing a Location header"
+        end
+        new_url  = resolve_url(location, original_request.url)
+
+        # 301/302/303 → change to GET; 307/308 → preserve original method.
+        new_method = case net_response.code.to_i
+                     when 307, 308 then original_request.method
+                     else "GET"
+                     end
+        request_kwargs = { method: new_method, headers: original_request.headers }
+        request_kwargs[:body] = original_request.body if new_method == original_request.method && original_request.body
+        new_request = Request.new(new_url, **request_kwargs)
+        perform(new_request, redirect: :follow, hops: hops + 1)
+
+      when :error
+        raise RedirectError,
+              "Unexpected redirect (#{net_response.code}) to #{net_response["location"]}"
+
+      when :manual
+        build_response(net_response, url: original_request.url)
+
+      else
+        raise ArgumentError, "Unknown redirect option: #{redirect.inspect}"
+      end
+    end
+
+    # Converts a Net::HTTPResponse into a {Response}.
+    def build_response(net_response, url:)
+      headers = Headers.new
+      net_response.each_header { |k, v| headers.set(k, v) }
+      Response.new(
+        status:  net_response.code.to_i,
+        headers: headers,
+        body:    net_response.body,
+        url:     url,
+      )
+    end
+
+    # Resolves a (possibly relative) redirect location against the base URL.
+    def resolve_url(location, base_url)
+      if location.start_with?("http://", "https://")
+        location
+      else
+        URI.join(base_url, location).to_s
+      end
+    end
+  end
+end

data/lib/wintertc/headers.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module WinterTc
+  # A case-insensitive map of HTTP headers, mirroring the JavaScript
+  # {https://developer.mozilla.org/en-US/docs/Web/API/Headers Headers} interface.
+  #
+  # Header names are normalised to lowercase internally so that lookups are
+  # always case-insensitive, just like the browser implementation.
+  #
+  # @example Basic usage
+  #   headers = WinterTc::Headers.new("Content-Type" => "application/json")
+  #   headers.get("content-type")   #=> "application/json"
+  #   headers.has("CONTENT-TYPE")   #=> true
+  #   headers.set("Accept", "text/html")
+  #   headers.append("Accept", "application/xhtml+xml")
+  #   headers.get("accept")         #=> "text/html, application/xhtml+xml"
+  class Headers
+    include Enumerable
+
+    # Creates a new Headers object.
+    #
+    # @param init [Hash, Array<Array<String>>, Headers, nil]
+    #   Initial headers.  Accepts a Hash (String => String), an Array of
+    #   two-element [name, value] arrays, another Headers object, or nil for
+    #   an empty collection.
+    # @raise [TypeError] when init is not one of the accepted types
+    def initialize(init = nil)
+      @data = {}
+      case init
+      when Hash    then init.each { |k, v| set(k, v) }
+      when Array   then init.each { |(k, v)| set(k, v) }
+      when Headers then init.each { |k, v| @data[k] = v }
+      when nil     then # empty
+      else raise TypeError, "init must be a Hash, Array, Headers, or nil"
+      end
+    end
+
+    # Returns the first value associated with the given header name, or +nil+
+    # if the header is not present.
+    #
+    # @param name [String] header name (case-insensitive)
+    # @return [String, nil]
+    def get(name)
+      @data[normalize(name)]
+    end
+
+    # Sets a header, replacing any existing value.
+    #
+    # @param name  [String] header name (case-insensitive)
+    # @param value [String] header value
+    # @return [void]
+    def set(name, value)
+      @data[normalize(name)] = value.to_s
+      nil
+    end
+
+    # Returns +true+ if a header with the given name exists.
+    #
+    # @param name [String] header name (case-insensitive)
+    # @return [Boolean]
+    def has(name)
+      @data.key?(normalize(name))
+    end
+
+    # Removes the header with the given name.
+    #
+    # @param name [String] header name (case-insensitive)
+    # @return [void]
+    def delete(name)
+      @data.delete(normalize(name))
+      nil
+    end
+
+    # Appends a value to an existing header.  If the header is not yet
+    # present it is created.  Multiple values are joined with +", "+,
+    # following the HTTP specification.
+    #
+    # @param name  [String] header name (case-insensitive)
+    # @param value [String] value to append
+    # @return [void]
+    def append(name, value)
+      key = normalize(name)
+      if @data.key?(key)
+        @data[key] = "#{@data[key]}, #{value}"
+      else
+        @data[key] = value.to_s
+      end
+      nil
+    end
+
+    # Yields each +[name, value]+ pair.  Names are in lowercase.
+    #
+    # @yieldparam name  [String]
+    # @yieldparam value [String]
+    # @return [Enumerator] if no block is given
+    # @return [self]       otherwise
+    def each
+      return to_enum(:each) unless block_given?
+
+      @data.each do |name, value|
+        yield name, value
+      end
+      self
+    end
+
+    # Returns all header names (lowercase).
+    #
+    # @return [Array<String>]
+    def keys
+      @data.keys
+    end
+
+    # Returns all header values.
+    #
+    # @return [Array<String>]
+    def values
+      @data.values
+    end
+
+    # Returns a plain +Hash+ copy of all headers.
+    #
+    # @return [Hash{String => String}]
+    def to_h
+      @data.dup
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@data.inspect}>"
+    end
+
+    private
+
+    # Normalises a header name to lowercase.
+    def normalize(name)
+      name.to_s.downcase
+    end
+  end
+end

data/lib/wintertc/request.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module WinterTc
+  # Represents an HTTP request, mirroring the JavaScript
+  # {https://developer.mozilla.org/en-US/docs/Web/API/Request Request} interface.
+  #
+  # A Request object can be passed directly to {WinterTc.fetch} instead of a
+  # plain URL string.  It can also be used to clone an existing request while
+  # overriding individual fields.
+  #
+  # @example Creating a POST request
+  #   req = WinterTc::Request.new(
+  #     "https://example.com/api",
+  #     method:  "POST",
+  #     headers: { "Content-Type" => "application/json" },
+  #     body:    JSON.generate({ key: "value" })
+  #   )
+  #   response = WinterTc.fetch(req)
+  #
+  # @example Cloning a request with a different body
+  #   cloned = WinterTc::Request.new(req, body: JSON.generate({ key: "new" }))
+  class Request
+    # The absolute URL of the request.
+    # @return [String]
+    attr_reader :url
+
+    # The HTTP method in uppercase, e.g. +"GET"+ or +"POST"+.
+    # @return [String]
+    attr_reader :method
+
+    # The request headers.
+    # @return [Headers]
+    attr_reader :headers
+
+    # The request body, or +nil+ for requests without a body.
+    # @return [String, nil]
+    attr_reader :body
+
+    # Creates a new Request.
+    #
+    # @param input   [String, Request] the target URL or an existing Request to
+    #   clone.
+    # @param method  [String, nil]  HTTP method.  Defaults to +"GET"+, or to
+    #   the method of the cloned request.
+    # @param headers [Hash, Headers, nil]  Additional headers.  When cloning a
+    #   request the headers are merged: these values take precedence.
+    # @param body    [String, nil]  Request body.  Defaults to +nil+, or to the
+    #   body of the cloned request.
+    # @raise [TypeError] when input is not a String or Request
+    def initialize(input, method: nil, headers: nil, body: nil)
+      case input
+      when Request
+        @url     = input.url
+        @method  = (method || input.method).to_s.upcase
+        @headers = merge_headers(input.headers, headers)
+        @body    = body.nil? ? input.body : body
+      when String
+        @url     = input
+        @method  = (method || "GET").to_s.upcase
+        @headers = Headers.new(headers)
+        @body    = body
+      else
+        raise TypeError, "input must be a String URL or a Request; got #{input.class}"
+      end
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@method} #{@url}>"
+    end
+
+    private
+
+    # Merges base headers with optional overrides, returning a new Headers.
+    def merge_headers(base, extra)
+      h = Headers.new(base)
+      return h unless extra
+
+      case extra
+      when Headers then extra.each { |k, v| h.set(k, v) }
+      when Hash    then extra.each { |k, v| h.set(k, v) }
+      end
+      h
+    end
+  end
+end

data/lib/wintertc/response.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module WinterTc
+  # Represents an HTTP response, mirroring the JavaScript
+  # {https://developer.mozilla.org/en-US/docs/Web/API/Response Response} interface.
+  #
+  # Response objects are returned by {WinterTc.fetch}.  The raw body can be
+  # read as a plain string with {#text}, or parsed as JSON with {#json}.
+  #
+  # @example
+  #   response = WinterTc.fetch("https://api.example.com/users")
+  #   if response.ok
+  #     users = response.json   # => Array of user hashes
+  #   else
+  #     puts "Error: #{response.status} #{response.status_text}"
+  #   end
+  class Response
+    # Mapping of common HTTP status codes to their standard reason phrases.
+    STATUS_TEXTS = {
+      100 => "Continue",
+      101 => "Switching Protocols",
+      102 => "Processing",
+      200 => "OK",
+      201 => "Created",
+      202 => "Accepted",
+      203 => "Non-Authoritative Information",
+      204 => "No Content",
+      205 => "Reset Content",
+      206 => "Partial Content",
+      301 => "Moved Permanently",
+      302 => "Found",
+      303 => "See Other",
+      304 => "Not Modified",
+      307 => "Temporary Redirect",
+      308 => "Permanent Redirect",
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      402 => "Payment Required",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      406 => "Not Acceptable",
+      409 => "Conflict",
+      410 => "Gone",
+      411 => "Length Required",
+      413 => "Content Too Large",
+      415 => "Unsupported Media Type",
+      422 => "Unprocessable Content",
+      429 => "Too Many Requests",
+      500 => "Internal Server Error",
+      501 => "Not Implemented",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+      504 => "Gateway Timeout",
+    }.freeze
+
+    # The HTTP status code (e.g. +200+, +404+).
+    # @return [Integer]
+    attr_reader :status
+
+    # The response headers.
+    # @return [Headers]
+    attr_reader :headers
+
+    # The URL that produced this response (the final URL after any redirects).
+    # @return [String, nil]
+    attr_reader :url
+
+    # Creates a {Response} whose body is the JSON serialisation of +data+ and
+    # whose +Content-Type+ header is set to +application/json+.  This mirrors
+    # the JavaScript
+    # {https://developer.mozilla.org/en-US/docs/Web/API/Response/json_static
+    # Response.json()} static method.
+    #
+    # @param data   [Object]  any JSON-serialisable value (Hash, Array, String, …)
+    # @param status [Integer] HTTP status code (default: +200+)
+    # @param headers [Hash, Headers, nil] additional response headers
+    # @return [Response]
+    #
+    # @example
+    #   res = WinterTc::Response.json({ message: "hello" })
+    #   res.status                          #=> 200
+    #   res.headers.get("content-type")     #=> "application/json"
+    #   res.json                            #=> { "message" => "hello" }
+    def self.json(data, status: 200, headers: nil)
+      body = JSON.generate(data)
+      merged = Headers.new(headers)
+      merged.set("Content-Type", "application/json")
+      new(status: status, headers: merged, body: body)
+    end
+
+    # Creates a new Response.
+    #
+    # @param status  [Integer]            HTTP status code
+    # @param headers [Hash, Headers]      response headers
+    # @param body    [String, nil]        raw response body
+    # @param url     [String, nil]        the URL that produced the response
+    def initialize(status:, headers:, body:, url: nil)
+      @status  = Integer(status)
+      @headers = headers.is_a?(Headers) ? headers : Headers.new(headers)
+      @body    = body.to_s
+      @url     = url
+    end
+
+    # Returns +true+ if the HTTP status code indicates success (200–299).
+    #
+    # @return [Boolean]
+    def ok
+      @status >= 200 && @status < 300
+    end
+
+    # Alias for {#ok} for idiomatic Ruby usage.
+    alias ok? ok
+
+    # Returns the response body as a plain +String+.
+    #
+    # @return [String]
+    def text
+      @body
+    end
+
+    # Parses the response body as JSON and returns the result.
+    #
+    # @return [Object] the parsed JSON value (Hash, Array, String, etc.)
+    # @raise [JSON::ParserError] if the body is not valid JSON
+    def json
+      JSON.parse(@body)
+    end
+
+    # Returns the standard HTTP reason phrase for the {#status} code
+    # (e.g. +"OK"+ for 200, +"Not Found"+ for 404).  Returns an empty
+    # string for unrecognised codes.
+    #
+    # @return [String]
+    def status_text
+      STATUS_TEXTS[@status] || ""
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@status} #{status_text}>"
+    end
+  end
+end

data/lib/wintertc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module WinterTc
+  # The current version of the wintertc gem.
+  VERSION = "0.1.0"
+end

data/lib/wintertc.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "wintertc/version"
+require_relative "wintertc/error"
+require_relative "wintertc/headers"
+require_relative "wintertc/request"
+require_relative "wintertc/response"
+require_relative "wintertc/fetch"
+
+# WinterTc is a Ruby HTTP client library that provides an interface as close as
+# possible to the JavaScript
+# {https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}.
+#
+# The three primary building blocks mirror their JavaScript counterparts:
+#
+# * {WinterTc::Headers} — a case-insensitive map of HTTP header fields.
+# * {WinterTc::Request} — an immutable description of an HTTP request.
+# * {WinterTc::Response} — the server's response, with helpers for reading the
+#   body as text or JSON.
+# * {WinterTc.fetch} — the main entry point; performs the request and returns a
+#   {WinterTc::Response}.
+#
+# The library has **no runtime dependencies** beyond Ruby's standard library
+# (`net/http`, `uri`, `json`).
+#
+# @example Quick start
+#   require "wintertc"
+#
+#   # Simple GET
+#   res = WinterTc.fetch("https://httpbin.org/get")
+#   puts res.status        #=> 200
+#   puts res.ok            #=> true
+#   puts res.json["url"]   #=> "https://httpbin.org/get"
+#
+#   # POST with JSON
+#   res = WinterTc.fetch(
+#     "https://httpbin.org/post",
+#     method:  "POST",
+#     headers: { "Content-Type" => "application/json" },
+#     body:    JSON.generate({ hello: "world" })
+#   )
+#   puts res.json["json"]  #=> { "hello" => "world" }
+module WinterTc
+end

data/sig/wintertc.rbs

@@ -0,0 +1,110 @@
+module WinterTc
+  VERSION: String
+  MAX_REDIRECTS: Integer
+
+  # ---------------------------------------------------------------------------
+  # Error classes
+  # ---------------------------------------------------------------------------
+
+  class Error < StandardError
+  end
+
+  class TooManyRedirectsError < Error
+  end
+
+  class RedirectError < Error
+  end
+
+  class UnsupportedMethodError < Error
+  end
+
+  # ---------------------------------------------------------------------------
+  # Headers
+  # ---------------------------------------------------------------------------
+
+  # A case-insensitive map of HTTP header fields, mirroring the JavaScript
+  # Headers interface.
+  class Headers
+    include Enumerable[[String, String]]
+
+    def initialize: (?Hash[String, String] | Array[[String, String]] | Headers | nil) -> void
+    def get: (String name) -> String?
+    def set: (String name, String value) -> nil
+    def has: (String name) -> bool
+    def delete: (String name) -> nil
+    def append: (String name, String value) -> nil
+    def each: () { ([String, String]) -> void } -> self
+    def keys: () -> Array[String]
+    def values: () -> Array[String]
+    def to_h: () -> Hash[String, String]
+    def inspect: () -> String
+  end
+
+  # ---------------------------------------------------------------------------
+  # Request
+  # ---------------------------------------------------------------------------
+
+  # An immutable description of an HTTP request.
+  class Request
+    attr_reader url: String
+    attr_reader method: String
+    attr_reader headers: Headers
+    attr_reader body: String?
+
+    def initialize: (
+      String | Request input,
+      ?method: String?,
+      ?headers: Hash[String, String] | Headers | nil,
+      ?body: String?
+    ) -> void
+
+    def inspect: () -> String
+  end
+
+  # ---------------------------------------------------------------------------
+  # Response
+  # ---------------------------------------------------------------------------
+
+  # The server's HTTP response.
+  class Response
+    STATUS_TEXTS: Hash[Integer, String]
+
+    attr_reader status: Integer
+    attr_reader headers: Headers
+    attr_reader url: String?
+
+    def self.json: (
+      untyped data,
+      ?status: Integer,
+      ?headers: Hash[String, String] | Headers | nil
+    ) -> Response
+
+    def initialize: (
+      status: Integer,
+      headers: Hash[String, String] | Headers,
+      body: String?,
+      ?url: String?
+    ) -> void
+
+    def ok: () -> bool
+    def ok?: () -> bool
+    def text: () -> String
+    def json: () -> untyped
+    def status_text: () -> String
+    def inspect: () -> String
+  end
+
+  # ---------------------------------------------------------------------------
+  # fetch
+  # ---------------------------------------------------------------------------
+
+  # Performs an HTTP request and returns the response.  Synchronous.
+  def self.fetch: (
+    String | Request input,
+    ?method: String?,
+    ?headers: Hash[String, String] | Headers | nil,
+    ?body: String?,
+    ?redirect: :follow | :manual | :error,
+    **untyped
+  ) -> Response
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: wintertc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kuboon
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: |
+  WinterTc provides a Ruby HTTP client whose interface mirrors the JavaScript
+  Fetch API as closely as possible.  It exposes WinterTc::Request,
+  WinterTc::Response, WinterTc::Headers, and WinterTc.fetch — all with the
+  same semantics as their browser counterparts.  No runtime gem dependencies:
+  only Ruby's built-in net/http, uri, and json are used.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/wintertc.rb
+- lib/wintertc/error.rb
+- lib/wintertc/fetch.rb
+- lib/wintertc/headers.rb
+- lib/wintertc/request.rb
+- lib/wintertc/response.rb
+- lib/wintertc/version.rb
+- sig/wintertc.rbs
+homepage: https://github.com/kuboon/wintertc.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kuboon/wintertc.rb
+  source_code_uri: https://github.com/kuboon/wintertc.rb
+  changelog_uri: https://github.com/kuboon/wintertc.rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: JavaScript-like Fetch API for Ruby
+test_files: []