async-rest 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a22ad3fd143a7cbe87a92c2653ab5c5aa5ed88fc2f3aba5154d1e2f6c365f7b6
-  data.tar.gz: e89ffc8cd141a113ef605e6857288cf266fd2867e32eee179212c642c31d8dab
+  metadata.gz: b348ab4bc1a06560f1f075791ddc9859f7b9148ea9df6befebc7bb228caee779
+  data.tar.gz: 596bad25fb27370bceb0eef0825a3af51ac34dcf27ff97a84e345aeb77d7aac0
 SHA512:
-  metadata.gz: 86b0c063038301619aacb0923a2ce50f5876c39ce5473e2109e22d19a3b8e6887090632c40e9d7f54c36869cc1a4a3fa0b26b779e4d0f135a81e58f8c805c2a6
-  data.tar.gz: 9b97aa0f0efc50931ed535bf64eac34f43f7b380bbe916a404c2effc1409f2847d6907f3449949b9478b25c8f2184876463e44cf13ea8f376961dc5f00a15336
+  metadata.gz: d6998bb2e970995d1e09033ad118097cd4dcfb5af7b0cd95bafb6c0e205649cccc4ad84eef951b797ce5b7e59a3328e0269ae660b8d9e4ce70f4cbc0abc04223
+  data.tar.gz: ae37524edc67a1ee70c3cb884e9b4bbfc0000a0d24dc90f572965e2e3e9a22be334c71ff6ce5a2b4fc048a6d26cfc15a8c7b8a12a5bc5b5970fd442c7e1ba5a3

data/.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 2
+

data/README.md

@@ -1,6 +1,11 @@
 # Async::REST
 
-An asynchronous client and server implementation of RESTful interfaces.
+Roy Thomas Fielding's thesis [Architectural Styles and the Design of Network-based Software Architectures](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) describes [Representational State Transfer](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) which comprises several core concepts:
+
+- `Resource`: A conceptual mapping to one or more entities.
+- `Representation`: An instance of a resource at a given point in time.
+
+This gem models these abstractions as closely and practically as possible and serves as a basis for building asynchronous web clients.
 
 [![Build Status](https://secure.travis-ci.org/socketry/async-rest.svg)](http://travis-ci.org/socketry/async-rest)
 [![Code Climate](https://codeclimate.com/github/socketry/async-rest.svg)](https://codeclimate.com/github/socketry/async-rest)
@@ -28,22 +33,43 @@ Or install it yourself as:
 
 ## Usage
 
-### GET a remote resource
+Generally speaking, you want to create a representation class for each endpoint. This class is responsible for negotiating content type and processing the response, and traversing related endpoints.
+
+### DNS over HTTP
+
+This simple example shows how to use a custom representation to access DNS over HTTP.
 
 ```ruby
-require 'async'
+require 'async/http/server'
+require 'async/http/url_endpoint'
+
 require 'async/rest/resource'
+require 'async/rest/representation'
+
+module DNS
+	class Query < Async::REST::Representation
+		def initialize(*args)
+			# This is the old/weird content-type used by Google's DNS resolver. It's obsolete.
+			super(*args, wrapper: Async::REST::Wrapper::JSON.new("application/x-javascript"))
+		end
+		
+		def question
+			value[:Question]
+		end
+		
+		def answer
+			value[:Answer]
+		end
+	end
+end
 
-API_URL = "https://reqres.in/api"
+URL = 'https://dns.google.com/resolve'
+Async::REST::Resource.for(URL) do |resource|
+	# Specify the representation class as the first argument (client side negotiation):
+	query = resource.get(DNS::Query, name: 'example.com', type: 'AAAA')
 
-Async.run do
-	api = Async::REST::Resource.for(API_URL)
-	
-	response = api.with(path: "users").get(page: 2)
-	
-	pp response.read
-	
-	api.close
+	pp query.metadata
+	pp query.value
 end
 ```
 

data/lib/async/rest/representation.rb

@@ -0,0 +1,110 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+require_relative 'resource'
+require_relative 'wrapper/json'
+
+module Async
+	module REST
+		class RequestFailure < StandardError
+		end
+		
+		# REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.
+		# 
+		# A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity). Metadata is in the form of name-value pairs, where the name corresponds to a standard that defines the value's structure and semantics. Response messages may include both representation metadata and resource metadata: information about the resource that is not specific to the supplied representation.
+		class Representation
+			def self.for(*args)
+				self.new(Resource.for(*args))
+			end
+			
+			# @param resource [Resource] the RESTful resource that this representation is of.
+			# @param metadata [Hash | HTTP::Headers] the metadata associated wtih teh representation.
+			# @param value [Object] the value of the representation.
+			# @param wrapper [#prepare_request, #process_response] the wrapper for encoding/decoding the request/response body.
+			def initialize(resource, metadata: {}, value: nil, wrapper: Wrapper::JSON.new)
+				@resource = resource
+				@wrapper = wrapper
+				
+				@metadata = metadata
+				@value = value
+			end
+			
+			def with(**parameters)
+				self.class.new(@resource.with(parameters: parameters), wrapper: @wrapper)
+			end
+			
+			def close
+				@resource.close
+			end
+			
+			attr :resource
+			attr :wrapper
+			
+			def prepare_request(verb, payload)
+				@resource.prepare_request(verb, payload, &@wrapper.method(:prepare_request))
+			end
+			
+			def process_response(request, response)
+				@wrapper.process_response(request, response)
+			end
+			
+			HTTP::VERBS.each do |verb|
+				# TODO when Ruby 3.0 lands, convert this to |payload = nil, **parameters|
+				# Blocked by https://bugs.ruby-lang.org/issues/14183
+				define_method(verb.downcase) do |payload = nil|
+					request = prepare_request(verb, payload)
+					
+					response = @resource.call(request)
+					
+					process_response(request, response)
+				end
+			end
+			
+			attr :metadata
+			
+			def value!
+				response = self.get
+				
+				if response.success?
+					@metadata = response.headers
+					@value = response.read
+				else
+					raise RequestFailure, "Could not fetch remote resource #{@resource}: #{response.status}!"
+				end
+			end
+			
+			def value
+				@value ||= value!
+			end
+			
+			def value= value
+				if @value = value
+					self.post(value)
+				else
+					self.delete
+				end
+			end
+			
+			def inspect
+				"\#<#{self.class} #{@resource.inspect}: value=#{@value.inspect}>"
+			end
+		end
+	end
+end

data/lib/async/rest/resource.rb

@@ -18,8 +18,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative 'wrapper/json'
-
+require 'async'
 require 'async/http/client'
 require 'async/http/accept_encoding'
 require 'async/http/reference'
@@ -27,17 +26,16 @@ require 'async/http/url_endpoint'
 
 module Async
 	module REST
+		# The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
 		class Resource < HTTP::Middleware
 			# @param delegate [Async::HTTP::Middleware] the delegate that will handle requests.
-			# @param reference [Async::HTTP::Reference] the base request path/parameters.
+			# @param reference [Async::HTTP::Reference] the resource identifier (base request path/parameters).
 			# @param headers [Async::HTTP::Headers] the default headers that will be supplied with the request.
-			# @param wrapper [#prepare_request, #process_response] the wrapper for encoding/decoding the request/response body.
-			def initialize(delegate, reference = HTTP::Reference.parse, headers = HTTP::Headers.new, wrapper = Wrapper::JSON.new)
+			def initialize(delegate, reference = HTTP::Reference.parse, headers = HTTP::Headers.new)
 				super(delegate)
 				
 				@reference = reference
 				@headers = headers
-				@wrapper = wrapper
 			end
 			
 			def self.connect(url)
@@ -56,55 +54,50 @@ module Async
 				
 				return resource unless block_given?
 				
-				begin
-					yield resource
-				ensure
-					resource.close
+				Async.run do
+					begin
+						yield resource
+					ensure
+						resource.close
+					end
 				end
 			end
 			
 			attr :reference
 			attr :headers
-			attr :wrapper
 			
-			def self.with(parent, *args, headers: {}, parameters: nil, path: nil, wrapper: parent.wrapper)
-				self.new(*args, parent.delegate, parent.reference.dup(path, parameters), parent.headers.merge(headers), wrapper)
+			def self.with(parent, *args, headers: {}, parameters: nil, path: nil)
+				self.new(*args, parent.delegate, parent.reference.dup(path, parameters), parent.headers.merge(headers))
 			end
 			
 			def with(*args, **options)
 				self.class.with(self, *args, **options)
 			end
 			
-			def prepare_request(verb, payload = nil, **parameters)
-				if parameters.empty?
-					reference = @reference
-				else
-					reference = @reference.dup(nil, parameters)
-				end
-				
-				headers = @headers.dup
-				
+			def get(klass = Representation, **parameters)
+				klass.new(self.with(parameters: parameters)).tap(&:value)
+			end
+			
+			# @param verb [String] the HTTP verb to use.
+			# @param payload [Object] the object which will used to generate the body of the request.
+			def prepare_request(verb, payload)
 				if payload
-					body = @wrapper.prepare_request(payload, headers)
+					headers = @headers.dup
+					body = yield payload, headers
 				else
+					headers = @headers
 					body = nil
 				end
 				
-				return HTTP::Request[verb, reference, headers, body]
+				return HTTP::Request[verb, @reference, headers, body]
 			end
 			
-			def process_response(response)
-				@wrapper.process_response(response)
+			def inspect
+				"\#<#{self.class} #{@reference.inspect} #{@headers.inspect}>"
 			end
 			
-			HTTP::VERBS.each do |verb|
-				define_method(verb.downcase) do |*args|
-					request = prepare_request(verb, *args)
-					
-					response = self.call(request)
-					
-					process_response(response)
-				end
+			def to_s
+				"\#<#{self.class} #{@reference.to_s}>"
 			end
 		end
 	end

data/lib/async/rest/version.rb

@@ -20,6 +20,6 @@
 
 module Async
 	module REST
-		VERSION = "0.5.2"
+		VERSION = "0.6.0"
 	end
 end

data/lib/async/rest/wrapper/json.rb

@@ -44,17 +44,22 @@ module Async
 					if payload
 						headers['content-type'] = @content_type
 						
+						# TODO dump incrementally to IO?
 						HTTP::Body::Buffered.new([
 							::JSON.dump(payload)
 						])
 					end
 				end
 				
-				def process_response(response)
-					# We expect all responses to be valid JSON.
-					# I tried inspecting content-type, but too many servers do the wrong thing.
-					if body = response.body
-						response.body = Parser.new(body)
+				def process_response(request, response)
+					if content_type = response.headers['content-type']
+						if content_type.start_with? @content_type
+							if body = response.body
+								response.body = Parser.new(body)
+							end
+						else
+							warn "Unknown content type: #{content_type}!"
+						end
 					end
 					
 					return response

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-rest
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-01 00:00:00.000000000 Z
+date: 2018-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -87,6 +87,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -95,6 +96,7 @@ files:
 - Rakefile
 - async-rest.gemspec
 - lib/async/rest.rb
+- lib/async/rest/representation.rb
 - lib/async/rest/resource.rb
 - lib/async/rest/version.rb
 - lib/async/rest/wrapper/json.rb
@@ -116,8 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: A library for RESTful clients (and hopefully servers).