okay 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ceda0f08f007df66075a65e62027f501453550d
-  data.tar.gz: f9e49212259bdf78ebfb1a034de5f840c379bced
+  metadata.gz: 821cdf5fa5035a799e732e2988fee9ec3666155a
+  data.tar.gz: dd1f9595882d529f39e18e6bb7205637b555c05d
 SHA512:
-  metadata.gz: 79ce047f2afccc37bdaef98c5a353dd66c5c665f9746ef7f9713dfb31b17f57832f72726a66258e4e5b8bc444ad2007123dd2fe870435a277fcaea2221b65c21
-  data.tar.gz: 922a324c08fdc04e1113472511f64698950bbe206ade914a63584011f70e66fd8e1765d9ac9a7b09ea62f36ad5a9a1771f5acebb3d2d029f3fee93c27c02391c
+  metadata.gz: df138d22cd54965b5c7e788a99a5c09d4b8952dc13026e0f6d3190529e503f50e34798e4c37f21b2976384dc6977b31bdb519d6d987ac2d910180cda102c0bfb
+  data.tar.gz: f5bde4d3e7b9863580717bdd3c5c892c88e518eae484a5892ae3fd61e778d06bd7fcb6d4bd50655a630e93fd97f83ce851aedfef672eab6bb18d0e9e2917d8ca

data/README.md

@@ -59,7 +59,17 @@ require 'okay/http'
 
 Okay::HTTP.get("https://smallest.dog") #=> #<Net::HTTPOK 200 OK readbody=true>
 Okay::HTTP.get("https://smallest.dog").body # => returns the page contents.
-# TODO: document Okay::HTTP.post().
+
+# Generates a query string based on +parameters+, ultimately requesting
+# https://httpbin.org/get?foo=bar
+Okay::HTTP.get("https://httpbin.org/get", parameters: { "foo" => "bar" })
+
+# Encodes +form_data+ as though it were a form, and sets the result of
+# that as the request body.
+Okay::HTTP.post("https://httpbin.org/post", form_data: { "foo" => "bar" })
+
+# Uses +data+ as the request body.
+Okay::HTTP.post("https://httpbin.org/post", data: "hello, world!")
 ```
 
 ## Development

data/lib/okay/http.rb

@@ -3,48 +3,80 @@ require 'net/https'
 
 class Okay
   module HTTP
-    MethodError = Class.new(ArgumentError)
     RedirectLimitError = Class.new(StandardError)
 
     DEFAULT_REDIRECT_LIMIT = 10
 
-    # A mapping of HTTP request methods to Net::HTTP methods.
-    # (Yay overlapping terminology.)
+    # Make an HTTP GET request.
     #
-    # Also, what are consistent APIs even?
-    METHODS = {
-      get:  'get_response',
-      post: 'post_form',
-    }
-
-    def self.get(url, parameters = {})
-      send_request(METHODS[:get], url, parameters)
+    # @param url [String] The URL to request.
+    # @param parameters [Hash] A hash representing a query string.
+    def self.get(url, parameters: {})
+      send_request(:Get, url, parameters, nil)
     end
 
-    def self.post(url, parameters = {})
-      send_request(METHODS[:post], url, parameters)
-    end
+    # Make an HTTP POST request.
+    #
+    # @param url [String] The URL to request.
+    # @param data [String] Raw data to for the body of the POST request.
+    # @param form_data [Hash] Form data, treated as though.
+    def self.post(url, data: nil, form_data: nil)
+      if !data.nil? && !form_data.nil?
+        raise ArgumentError, "cannot specify data and form_data arguments simultaneously."
+      end
 
-    private
+      if form_data.nil?
+        body = data
+      else
+        body = URI.encode_www_form(form_data)
+      end
 
-    def self.send_request(http_method, url, parameters, limit = DEFAULT_REDIRECT_LIMIT)
+      send_request(:Post, url, nil, body)
+    end
+
+    def self.send_request(http_method, url, parameters, body, limit = DEFAULT_REDIRECT_LIMIT)
       if limit <= 0
         raise RedirectLimitError, "request exceeded redirect limit"
       end
 
+      # Convert the URL (a String) into a URI object.
       uri = URI.parse(url)
-      uri.query = URI.encode_www_form(parameters)
 
-      options = { use_ssl: (uri.scheme == 'https') }
+      # Set the query string for the request.
+      uri.query = URI.encode_www_form(parameters) unless parameters.nil?
+
+      options = {
+        # If the URI starts with "https://", enable SSL/TLS.
+        use_ssl: (uri.scheme == 'https')
+      }
 
+      # Net::HTTP.start() keeps a connection to the host alive
+      # for all requests that occur inside the block.
       Net::HTTP.start(uri.host, uri.port, options) do |http|
-        response = Net::HTTP.send(http_method, uri)
+        # Get a reference to the class for the specified request type.
+        # E.g., if it's a post request, this returns Net::HTTP::Post.
+        request_class = Net::HTTP.const_get(http_method)
+
+        # Create the request object, but don't send it yet.
+        request  = request_class.new(uri)
+        # Set the request body, if there is one.
+        request.body = body unless body.nil?
+
+        # Send the request, storing the result in +response+.
+        response = http.request(request)
 
+        # Handle responses.
         case response
         when Net::HTTPSuccess
+          # Request succeeded; return the result.
           response
         when Net::HTTPRedirection
-          send_request(METHODS[:get], response['location'], parameters, limit - 1)
+          # Follow a redirect.
+          # Decrements +limit+ while doing so, to avoid redirect loops.
+          #
+          # NOTE: This does not handle HTTP 307 correctly, as it always
+          #       changes to a GET request. https://httpstatuses.com/307
+          send_request(:Get, response['location'], parameters, body, limit - 1)
         else
           # This seemingly-innocent method raises an exception if the request
           # isn't successful.
@@ -52,5 +84,6 @@ class Okay
         end
       end
     end
+    private_class_method :send_request
   end
 end

data/lib/okay/version.rb

@@ -1,3 +1,3 @@
 module Okay
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okay
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Ellen Marie Dash