http_resource 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae3a2c83649ab50e44f3b85b70e223903788c31b8c1d3e738d87ae4154f1e716
-  data.tar.gz: 4807d9724ace0ad3b1cddedaa74c693454c4f1d0b29591a7f655228ea8a09a71
+  metadata.gz: 6d9fe8b0aeb930b24273f354fa958c855392cbc7169178aff012fc55c9349bc0
+  data.tar.gz: c59a5d2b61d6b759f494fc15619b14a26f1040425c6d1d9eb43c90a67218e2d8
 SHA512:
-  metadata.gz: 5b6bffc9f723e5ad0e7c2c15917dd7a18b9064719c5b1c128f3aebe6f1d601390db7b83ed1c7abffe1e047e2293d3ee7f9524c85c0501d3e08ea2d67f05f7e72
-  data.tar.gz: bed8b7f03efd23d9f52a543bc07e6b0cd16b1429ce5df9f6373f29ab51fbdc100684720e47fb16fcc4c10d7489db70177a471a0cca67b97ae9f2c1e1147a5e78
+  metadata.gz: 882a09948d72787115e9dde41bf305269355f16bc431e929e2b13d7d28372a48fbaa695682b0e73be030412d1e402cde6fe339d946db1991317e3e19be4e16d7
+  data.tar.gz: e12dcb9fbb52ea78a319a1fa19c27f906a88c66079e03f0ec3f97dc358e7dafc48772a329509934c24cc9475809d58915d81614c8c06a10e75af886b9a672868

data/README.md

@@ -54,6 +54,7 @@ client = HttpResource::Client.new(
 
 client.get(["api", "contacts", id])          # GET, id escaped as ONE path segment
 client.post(["api", "actions"], { foo: 1 })  # POST a JSON body
+client.put(["api", "contacts", id], { name: "Anna" })
 client.patch(["api", "contacts", email], { name: "Anna" })
 client.delete(["api", "contacts", id])
 ```
@@ -65,6 +66,37 @@ Reads return parsed JSON (a `Hash`/`Array`, or `nil` on an empty body). Every
 call raises an `HttpResource::ApiError` subclass on a non-2xx response or a
 transport failure.
 
+### Form-encoded bodies (OAuth)
+
+`post`/`put`/`patch` take a `form:` keyword to send an
+`application/x-www-form-urlencoded` body instead of JSON — for the form-encoded
+endpoints OAuth consumers hit (RFC 6749 token, RFC 7662 introspection, …):
+
+```ruby
+token = client.post(["oauth", "token"], form: {
+  grant_type: "client_credentials",
+  scope: "read write"
+})
+token["access_token"]   # a 2xx still returns parsed JSON
+```
+
+The response side is identical to a JSON call — parsed JSON on a 2xx, a typed
+`ApiError` on a non-2xx — so an OAuth failure is just a rescue-able error whose
+`#body` carries the payload:
+
+```ruby
+begin
+  client.post(["oauth", "token"], form: { grant_type: "authorization_code", code: bad })
+rescue HttpResource::ClientError => e
+  e.status                    # => 400
+  JSON.parse(e.body)["error"] # => "invalid_grant"
+end
+```
+
+Pass **either** a JSON `payload` **or** `form:`, never both (it raises
+`ArgumentError`). Form keys/values are percent-encoded, so untrusted input can't
+inject a header or an extra field.
+
 ### A process-wide default client
 
 ```ruby
@@ -213,6 +245,22 @@ A **`String`** path is the trusted escape hatch and is sent **verbatim** — so
 let the framework encode it. The guarantee is covered by a dedicated,
 adversarial spec (`spec/escape_safety_spec.rb`).
 
+## Changelog
+
+### 0.2.0
+
+- Add a `form:` keyword to `post`/`put`/`patch` for `application/x-www-form-urlencoded`
+  bodies (OAuth token/introspection and other form-encoded endpoints). Responses
+  stay resty: parsed JSON on a 2xx, a typed `ApiError` (with `#body`) on a non-2xx.
+- Add a first-class `put` verb (JSON or `form:` body).
+- Passing both a JSON `payload` and `form:` raises `ArgumentError`; the bodyless
+  verbs (`get`/`delete`) reject `form:`.
+
+### 0.1.0
+
+- Initial release: Net::HTTP transport, typed `ApiError` hierarchy, bang/non-bang
+  resources, pluggable auth, per-call timeouts, escape-safe URL building.
+
 ## Development
 
 ```sh

data/lib/http_resource/client.rb

@@ -8,13 +8,14 @@ require "openssl"
 
 module HttpResource
   # Net::HTTP transport for a single REST host. Resource-oriented: the verbs
-  # (get/post/patch/delete) are the primitives a Resource is built on, and also
-  # an escape hatch for endpoints not yet modelled.
+  # (get/post/put/patch/delete) are the primitives a Resource is built on, and
+  # also an escape hatch for endpoints not yet modelled.
   #
   #   client = HttpResource::Client.new(base_url: "https://api.example.org",
   #                                     auth: HttpResource::Auth.bearer(token))
-  #   client.get(["api", "contacts", id])         # GET, id escaped as one segment
-  #   client.post(["api", "actions"], { ... })    # POST a JSON body
+  #   client.get(["api", "contacts", id])            # GET, id escaped as one segment
+  #   client.post(["api", "actions"], { ... })       # POST a JSON body
+  #   client.post(["oauth", "token"], form: { ... }) # POST a form body (OAuth, RFC 6749)
   #
   # Reads return parsed JSON (a Hash/Array, or nil on an empty body). Every call
   # raises an HttpResource::ApiError subclass on a non-2xx response or a transport
@@ -45,31 +46,45 @@ module HttpResource
     # an Array of segments (["api", "contacts", email]) each individually escaped.
     # Each verb accepts open_timeout:/read_timeout: to override the client's
     # budget for that one call (e.g. a short read_timeout on a synchronous read).
-    def get(path, params: nil, **timeouts)
-      request(:get, path, params:, **timeouts)
+    #
+    # The body-bearing verbs (post/put/patch) send EITHER a JSON body — the
+    # positional `payload` — or a form body — `form: {...}`, encoded as
+    # application/x-www-form-urlencoded (for the form-encoded endpoints OAuth
+    # consumers hit: RFC 6749 token, RFC 7662 introspection, …). Passing both is
+    # a caller bug and raises ArgumentError. The response side is identical either
+    # way: parsed JSON on a 2xx, a typed ApiError (with #status + #body) on a
+    # non-2xx — so a "400 invalid_grant" is a rescue-able ClientError whose #body
+    # carries the error payload.
+    def get(path, params: nil, open_timeout: nil, read_timeout: nil)
+      request(:get, path, params:, open_timeout:, read_timeout:)
     end
 
-    def post(path, payload = nil, **timeouts)
-      request(:post, path, body: payload, **timeouts)
+    def post(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:post, path, body: payload, form:, open_timeout:, read_timeout:)
     end
 
-    def patch(path, payload = nil, **timeouts)
-      request(:patch, path, body: payload, **timeouts)
+    def put(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:put, path, body: payload, form:, open_timeout:, read_timeout:)
     end
 
-    def delete(path, **timeouts)
-      request(:delete, path, **timeouts)
+    def patch(path, payload = nil, form: nil, open_timeout: nil, read_timeout: nil)
+      request(:patch, path, body: payload, form:, open_timeout:, read_timeout:)
+    end
+
+    def delete(path, open_timeout: nil, read_timeout: nil)
+      request(:delete, path, open_timeout:, read_timeout:)
     end
 
     private
 
-    def request(method, path, body: nil, params: nil, open_timeout: nil, read_timeout: nil)
+    def request(method, path, body: nil, form: nil, params: nil, open_timeout: nil, read_timeout: nil)
       # Build the URI + request OUTSIDE the network rescue: a URI::InvalidURIError
-      # (bad path) or JSON::GeneratorError (un-serializable payload, e.g. a NaN
-      # amount) is a deterministic caller bug, and must NOT be masked as a
-      # retryable TransportError — that would have a worker retry it forever.
+      # (bad path), JSON::GeneratorError (un-serializable payload, e.g. a NaN
+      # amount) or an ArgumentError (both a JSON and a form body) is a
+      # deterministic caller bug, and must NOT be masked as a retryable
+      # TransportError — that would have a worker retry it forever.
       uri = build_uri(path, params)
-      req = build_request(method, uri, body)
+      req = build_request(method, uri, body, form)
       connection = http(uri, open_timeout:, read_timeout:)
       begin
         handle(connection.request(req))
@@ -116,19 +131,32 @@ module HttpResource
       ERB::Util.url_encode(str)
     end
 
-    def build_request(method, uri, body)
+    def build_request(method, uri, body, form = nil)
       klass = {
-        get: Net::HTTP::Get, post: Net::HTTP::Post,
+        get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put,
         patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
       }.fetch(method)
       request = klass.new(uri)
       @auth&.apply(request)
       request["Accept"] = "application/json"
-      if body
+      apply_body(request, body, form)
+      request
+    end
+
+    # A request carries EITHER a JSON body (`payload`) or a form body (`form:`),
+    # never both — passing both is a caller bug. Form values are percent-encoded
+    # by URI.encode_www_form (the same encoder used for query params), so an
+    # untrusted key/value can't inject a header, a second field, or CRLF.
+    def apply_body(request, body, form)
+      raise ArgumentError, "pass either a JSON payload or form:, not both" if body && form
+
+      if form
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+        request.body = URI.encode_www_form(form)
+      elsif body
         request["Content-Type"] = "application/json"
         request.body = JSON.generate(body)
       end
-      request
     end
 
     def http(uri, open_timeout: nil, read_timeout: nil)

data/lib/http_resource/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HttpResource
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http_resource
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Skiftet