requests_ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98c916667505e2bb295cfd13cfd3640a9fb73fe285248115b1f612d2b562a008
+  data.tar.gz: e8dc6c58aa8999fdb4ae84040733b05b801140efcac65b7ab9f834f299c8c4e8
+SHA512:
+  metadata.gz: 102260dfeff2781a3cdd337b9a3771e43ad865a1c2968090268202b3ae915320e84b9b2129e6d6ba4698303638c207aa0b49e814782cfd9ef1914718bec73b97
+  data.tar.gz: 3b3a024c7adc8e3a47d13289b9668d7ee8f1379c98d8e317f718be6b2be5525f4cfb39ab4821e839a2af20ec6645f15d71be04f6d4857e520a2ef4cea06ecc32

data/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 2.1.0
+
+Big cleanup pass. Split the single `lib/requests.rb` file into a proper
+`lib/requests/*` structure, fixed several real bugs, and filled in a bunch
+of gaps vs. the python `requests` API.
+
+### Fixed
+- **`Content-Type` header silently dropped on redirects.** The request body
+  was only built once, but the header carrying its `Content-Type` was set
+  on a headers hash that got thrown away and rebuilt on every redirect hop.
+  A 307/308 redirect that correctly preserved the POST body would send it
+  with no `Content-Type` at all. Body + content type are now computed once
+  and carried through the whole redirect chain.
+- **Binary multipart uploads could raise `Encoding::CompatibilityError`.**
+  The multipart body was being built as a UTF-8 string; appending raw
+  binary file content (an image, a zip, whatever) onto it blew up the
+  moment the bytes weren't valid UTF-8. The body is now built as
+  `ASCII-8BIT` from the start.
+- **Request bodies silently disappeared on GET/DELETE.** The code only
+  attached a body when `request_body_permitted?` was true, which is `false`
+  for GET in net/http. Some APIs (Elasticsearch, various search/query
+  APIs) intentionally send a JSON body with GET - that's now respected.
+- **Confusing `unexpected token` errors from `Response#json`.** Calling
+  `.json` on a response that came back as an HTML error/login page (very
+  common when you hit a WAF, an expired-auth redirect, or the wrong host)
+  raised a bare `JSON::ParserError`-wrapped message with no context. The
+  error now says plainly that it looks like an HTML page, includes the
+  status code, and shows a truncated preview of the body.
+- Deflate-compressed bodies missing the zlib header (some servers send raw
+  deflate) now fall back to a raw inflate instead of raising.
+- `Requests::Timeout` / `ConnectTimeout` / `ReadTimeout` now share a
+  `Requests::Timeoutable` module so you can `rescue Requests::Timeoutable`
+  and catch both connect and read timeouts in one line, closer to python's
+  `except requests.Timeout`.
+
+### Added
+- `Response#status` (alias of `status_code`), `#is_redirect?`,
+  `#is_permanent_redirect?`, `#client_error?`, `#server_error?`.
+- `Response#save_to(path)` to stream a body straight to disk.
+- `Response#request` is now a small `PreparedRequest` object (still
+  supports `resp.request[:url]` hash-style access for old code).
+- `Session#mount(prefix, adapter)` + `Requests::HTTPAdapter` - swap out the
+  transport layer per URL prefix, loosely modeled on python's adapters.
+- Built-in retry support: `retries:`/`Session#retries` and
+  `backoff_factor:` for transient connection errors on idempotent methods.
+- `Session#get!` / `#post!` - like `get`/`post` but raise immediately on
+  a non-2xx/3xx response.
+- `Requests.download(url, to: path)` convenience method.
+- `Requests::InvalidSchema` (scheme present but not http/https) as a
+  companion to the existing `MissingSchema` (no scheme at all).
+- Cross-host redirect now strips the `Authorization` header instead of
+  forwarding your bearer token / basic auth to whatever host the
+  `Location` header pointed at.
+- A real test suite under `spec/` (plain minitest, no network calls).
+- `Makefile` with `test`, `console`, `build`, `install`, `release`, `lint`.
+- `Requests::CaseInsensitiveDict` / `Requests::CookieJar` aliases for
+  people coming from the python naming.
+
+## 1.0.0 / 2.0.0
+
+Initial single-file releases.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 requests_ruby contributors
+
+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,331 @@
+# requests_ruby
+
+A zero-dependency, stdlib-only HTTP client for Ruby, modeled closely on Python's beloved [`requests`](https://requests.readthedocs.io/) library. No `Gemfile`, no C extensions, no transitive dependency tree — just Ruby's own `net/http` wrapped in an API that doesn't make you want to throw your laptop.
+
+[![Gem Version](https://img.shields.io/badge/gem-requests__ruby-red?logo=rubygems)](https://rubygems.org/gems/requests_ruby)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-CC342D?logo=ruby)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](requests_ruby.gemspec)
+
+---
+
+## Table of Contents
+
+- [Why this exists](#-why-this-exists)
+- [Installation](#-installation)
+- [Quick start](#-quick-start)
+- [Feature tour](#-feature-tour)
+  - [Query params](#query-params)
+  - [Sending data (form / JSON / files)](#sending-data-form--json--files)
+  - [Response object](#response-object)
+  - [Sessions](#sessions)
+  - [Authentication](#authentication)
+  - [Errors & exceptions](#errors--exceptions)
+  - [Redirects & history](#redirects--history)
+  - [Timeouts & retries](#timeouts--retries)
+  - [Proxies & SSL](#proxies--ssl)
+  - [Cookies](#cookies)
+  - [Hooks](#hooks)
+  - [Streaming & downloads](#streaming--downloads)
+  - [Custom transport adapters](#custom-transport-adapters)
+  - [Status codes](#status-codes)
+- [API reference](#-api-reference)
+- [Python parity cheat sheet](#-python-parity-cheat-sheet)
+- [Known limitations](#-known-limitations)
+- [Development](#-development)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## Why this exists
+
+Ruby has plenty of great HTTP gems (`Faraday`, `HTTParty`, `httpx`...) but most either pull in dependencies or don't quite match the ergonomics people already know from Python's `requests`. This gem is for the specific case of: *"I want `requests.get(url).json()` energy, in Ruby, using only what ships with Ruby itself."*
+
+If you're coming from Python, the [parity cheat sheet](#-python-parity-cheat-sheet) below will feel like home.
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem 'requests_ruby'
+```
+
+Or install it directly:
+
+```bash
+gem install requests_ruby
+```
+
+Then, in your code — `require 'requests'` works out of the box (matching the ergonomics of the gem's underlying `Requests` module), and so does `require 'requests_ruby'` if you'd rather match the gem name exactly. Both point at the same code:
+
+```ruby
+require 'requests'
+# -- or --
+require 'requests_ruby'
+```
+
+## Quick start
+
+```ruby
+require 'requests'
+
+r = Requests.get('https://api.example.com/users', params: { page: 1 })
+
+r.status_code   #=> 200
+r.ok?           #=> true
+r.json          #=> { "users" => [...] }
+r.text          #=> "{\"users\":[...]}"
+r.headers['content-type']
+```
+
+## Feature tour
+
+### Query params
+
+```ruby
+Requests.get('https://api.example.com/search', params: { q: 'ruby gems', page: 2 })
+# => https://api.example.com/search?q=ruby+gems&page=2
+
+# arrays become repeated params
+Requests.get('https://api.example.com/search', params: { tag: ['ruby', 'http'] })
+# => ...?tag=ruby&tag=http
+```
+
+### Sending data (form / JSON / files)
+
+```ruby
+# JSON body
+Requests.post('https://api.example.com/login', json: { user: 'ali', pass: 'secret' })
+
+# form-encoded body
+Requests.post('https://api.example.com/login', data: { user: 'ali', pass: 'secret' })
+
+# multipart file upload
+Requests.post('https://api.example.com/upload',
+  data: { title: 'my photo' },
+  files: { avatar: ['pic.png', File.read('pic.png'), 'image/png'] })
+```
+
+### Response object
+
+```ruby
+r = Requests.get(url)
+
+r.status_code        # 200
+r.status              # alias for status_code
+r.ok?                 # true if < 400
+r.text                # decoded body as a UTF-8 string
+r.content             # raw body
+r.json                # parsed JSON (raises Requests::JSONDecodeError if it isn't JSON)
+r.headers['etag']     # case-insensitive header access
+r.cookies             # cookie jar collected across the request
+r.elapsed             # Float seconds
+r.url                 # final URL after any redirects
+r.history             # array of intermediate Response objects
+r.links               # parsed Link header, e.g. pagination
+r.request             # PreparedRequest - what was actually sent (method/url/headers/body)
+r.redirect?           # true for 3xx with a Location header
+r.client_error?       # 400-499
+r.server_error?       # 500+
+r.save_to('file.bin') # stream raw_body straight to disk
+```
+
+### Sessions
+
+Sessions persist headers, cookies, and auth across multiple requests to the same service — and reuse is not just convenient, it avoids re-doing DNS/TLS handshakes on every call.
+
+```ruby
+s = Requests::Session.new
+s.headers['Authorization'] = 'Bearer xyz'
+
+s.get('https://api.example.com/me')
+s.get('https://api.example.com/orders')
+
+# raise immediately instead of checking status_code yourself
+s.get!('https://api.example.com/me')
+```
+
+### Authentication
+
+```ruby
+Requests.get(url, auth: Requests::BasicAuth.new('user', 'pass'))
+Requests.get(url, auth: Requests::BearerAuth.new('token'))
+Requests.get(url, auth: Requests::DigestAuth.new('user', 'pass'))
+```
+
+Write your own by implementing `#call(headers)` — anything that responds to it works as an `auth:` value.
+
+### Errors & exceptions
+
+```ruby
+begin
+  r = Requests.get(url)
+  r.raise_for_status
+rescue Requests::HTTPError => e
+  puts e.message           # "404 Client Error: Not Found for url: ..."
+  puts e.response.status_code
+rescue Requests::Timeoutable
+  # catches BOTH Requests::ConnectTimeout and Requests::ReadTimeout
+  puts 'timed out'
+rescue Requests::ConnectionError => e
+  puts e.message
+end
+```
+
+Exception hierarchy at a glance:
+
+```
+Requests::RequestException
+├── Requests::HTTPError
+├── Requests::ConnectionError
+│   ├── Requests::ProxyError
+│   ├── Requests::SSLError
+│   └── Requests::ConnectTimeout   (also includes Requests::Timeoutable)
+├── Requests::Timeout              (also includes Requests::Timeoutable)
+│   └── Requests::ReadTimeout
+├── Requests::URLRequired
+├── Requests::TooManyRedirects
+├── Requests::MissingSchema        (no scheme at all, e.g. "example.com")
+├── Requests::InvalidSchema        (unsupported scheme, e.g. "ftp://")
+├── Requests::InvalidURL
+│   └── Requests::InvalidProxyURL
+├── Requests::ChunkedEncodingError
+├── Requests::ContentDecodingError
+├── Requests::StreamConsumedError
+├── Requests::InvalidHeader
+├── Requests::RetryError
+└── Requests::InvalidJSONError
+    └── Requests::JSONDecodeError
+```
+
+### Redirects & history
+
+```ruby
+r = Requests.get(url)
+r.history          # every intermediate 3xx Response, in order
+r.url              # the final URL you landed on
+
+r = Requests.get(url, allow_redirects: false) # don't follow at all
+```
+
+### Timeouts & retries
+
+```ruby
+Requests.get(url, timeout: 5)          # 5s for both connect and read
+Requests.get(url, timeout: [3, 10])    # [connect, read]
+
+# retry transient connection errors on idempotent methods (GET/HEAD/OPTIONS/PUT/DELETE)
+s = Requests::Session.new
+s.retries = 3
+s.backoff_factor = 0.5   # sleeps 0.5s, 1s, 1.5s between attempts
+s.get(url)
+
+# or per-request
+Requests.get(url, retries: 3)
+```
+
+### Proxies & SSL
+
+```ruby
+Requests.get(url, proxies: { 'http' => 'http://127.0.0.1:8080', 'https' => 'http://127.0.0.1:8080' })
+Requests.get(url, verify: false)               # skip cert verification (careful!)
+Requests.get(url, verify: '/path/to/ca.pem')   # custom CA bundle
+```
+
+A bundled `cacert.pem` (Mozilla's CA bundle) ships with the gem and is used by default. Override it globally with the `REQUESTS_CA_FILE` environment variable.
+
+### Cookies
+
+```ruby
+r = Requests.get(url)
+r.cookies['session_id']
+
+s = Requests::Session.new
+s.cookies.set('theme', 'dark')
+s.get(url) # sent automatically on every request through this session
+```
+
+### Hooks
+
+```ruby
+s = Requests::Session.new
+s.hooks[:response] << ->(resp) { puts "#{resp.request[:method]} #{resp.url} -> #{resp.status_code}" }
+s.get(url)
+```
+
+### Streaming & downloads
+
+```ruby
+r = Requests.get(url)
+r.iter_content(chunk_size: 4096) { |chunk| ... }
+r.iter_lines { |line| ... }
+
+# convenience one-liner for "just save this to disk"
+Requests.download('https://example.com/file.zip', to: 'file.zip')
+```
+
+> ℹ️ Note: unlike Python's `requests`, the body is fully read before `iter_content`/`iter_lines` yield anything — this library deliberately stays stdlib-only, and true lazy streaming would need extra machinery to keep a `net/http` connection open across method calls. See [Known limitations](#-known-limitations).
+
+### Custom transport adapters
+
+Loosely inspired by Python's `Session.mount()` / `HTTPAdapter`:
+
+```ruby
+class LoggingAdapter < Requests::HTTPAdapter
+  def send_once(*args)
+    puts 'sending a request...'
+    super
+  end
+end
+
+s = Requests::Session.new
+s.mount('https://internal.example.com/', LoggingAdapter.new)
+```
+
+### Status codes
+
+```ruby
+Requests.codes.ok         # 200
+Requests.codes.not_found  # 404
+Requests.codes.im_a_teapot # 418, yes really
+```
+
+## API reference
+
+| Module-level | Session | Response |
+|---|---|---|
+| `Requests.get/post/put/patch/delete/head/options` | `session.get/post/put/patch/delete/head/options` | `status_code`, `status` |
+| `Requests.request(method, url, **opts)` | `session.request(method, url, **opts)` | `ok?`, `redirect?` |
+| `Requests.session` → new `Session` | `session.get!/post!` (raise on error) | `text`, `content`, `json` |
+| `Requests.download(url, to:)` | `session.mount(prefix, adapter)` | `headers`, `cookies` |
+| `Requests.codes` | `session.hooks[:response]` | `elapsed`, `history`, `url` |
+|  | `session.headers`, `.cookies`, `.auth`, `.proxies`, `.retries` | `raise_for_status`, `save_to`, `links` |
+
+Every request-level method accepts: `params`, `data`, `json`, `headers`, `cookies`, `files`, `auth`, `timeout`, `allow_redirects`, `proxies`, `verify`, `cert`, `hooks`, `retries`.
+
+
+## 🔧 Development
+
+```bash
+git clone https://github.com/requests-ruby/requests_ruby.git
+cd requests_ruby
+make test       # run the test suite
+make console    # irb with the lib pre-loaded
+make build      # build the .gem into pkg/
+```
+
+See the [Makefile](Makefile) for the full list of targets.
+
+## Contributing
+
+Bug reports and pull requests are welcome. A few ground rules:
+
+1. No new runtime dependencies — this stays stdlib-only, on purpose.
+2. Add a test in `spec/requests_spec.rb` for anything you fix or add.
+3. Keep the Python-parity naming where it makes sense, but don't force it where it doesn't fit Ruby idiom (`?`-suffixed predicates, etc.).
+
+## License
+
+[MIT](LICENSE)