async-rest 0.10.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7532e90b101d5977772c3471fcbe2e9981677e2459e90f0c385c6ffab0c7c48c
-  data.tar.gz: 36d2b5804bcfde6a3938752fc7b68f0b1af011fdfc6b9910d032431e76b90bb4
+  metadata.gz: bb987666810a3a57e687ffd7a3bdc84fa1d1202d9d175793c233d6fa7fd4f601
+  data.tar.gz: fd8512c49fc42b9c1d19be516f245f833731f293ebaed31656a6b7d29f1d6d44
 SHA512:
-  metadata.gz: 6b9d994df5534243476a9fc4cb02d523f1a12ad12310ff4b637574543d37288f142b3909dfc01725a5ba5978abb0e0d1ea8d8767110c14a7a376c5e9f6a0a2dc
-  data.tar.gz: fb8ac27b1b95768dbb89638a2f13c48865360e8f15b11df0991c712a0fdebc912d24d487e3191b8223952948b4c8a389fc1c794b01b32b74760e3294888e07ad
+  metadata.gz: 5e514f403513ee3886568b073ac2881af75de114b665d868874939aace962da6dcc8fefbb57f1fbcea3735e2705d3f7c17d82c25cfcb091f7b3356a56b45a9db
+  data.tar.gz: 2c08eb8becbabc19a0c1f6760722735f86a2fa659faf63c3fc6a4aabd998408aa9e0beb6bf0ecd8780dd6c8e94167d2678411baffd82040e352dfe88e6d6ace4

data/.travis.yml

@@ -7,13 +7,15 @@ matrix:
     - rvm: 2.4
     - rvm: 2.5
     - rvm: 2.6
+    - rvm: 2.6
+      gemfile: gems/event.gemfile
+    - rvm: 2.6
+      env: COVERAGE=PartialSummary,Coveralls
     - rvm: jruby-head
       env: JRUBY_OPTS="--debug -X+O"
     - rvm: truffleruby
     - rvm: ruby-head
-    - rvm: rbx-3
   allow_failures:
+    - rvm: truffleruby
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-3
-    - rvm: truffleruby

data/README.md

@@ -7,7 +7,7 @@ Roy Thomas Fielding's thesis [Architectural Styles and the Design of Network-bas
 
 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)
+[![Build Status](https://secure.travis-ci.com/socketry/async-rest.svg)](http://travis-ci.com/socketry/async-rest)
 [![Code Climate](https://codeclimate.com/github/socketry/async-rest.svg)](https://codeclimate.com/github/socketry/async-rest)
 [![Coverage Status](https://coveralls.io/repos/socketry/async-rest/badge.svg)](https://coveralls.io/r/socketry/async-rest)
 
@@ -33,7 +33,7 @@ Or install it yourself as:
 
 ## Usage
 
-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.
+Generally speaking, you want to create a representation class for each remote resource. This class is responsible for negotiating content type and processing the response, and traversing related resources.
 
 ### DNS over HTTP
 

data/examples/github/feed.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+
+require 'async'
+require 'async/rest'
+require 'async/rest/wrapper/form'
+
+require 'date'
+
+URL = "https://api.github.com"
+ENDPOINT = Async::HTTP::Endpoint.parse(URL)
+
+module GitHub
+	class Wrapper < Async::REST::Wrapper::Form
+		DEFAULT_CONTENT_TYPES = {
+			"application/vnd.github.v3+json" => Async::REST::Wrapper::JSON::Parser
+		}
+		
+		def initialize
+			super(DEFAULT_CONTENT_TYPES)
+		end
+		
+		def parser_for(response)
+			if content_type = response.headers['content-type']
+				if content_type.start_with? "application/json"
+					return Async::REST::Wrapper::JSON::Parser
+				end
+			end
+			
+			return super
+		end
+	end
+	
+	class Representation < Async::REST::Representation[Wrapper]
+	end
+	
+	class User < Representation
+	end
+	
+	class Client < Representation
+		def user(name)
+			self.with(User, path: "users/#{name}")
+		end
+	end
+	
+	module Paginate
+		include Enumerable
+		
+		def represent(metadata, attributes)
+			resource = @resource.with(path: attributes[:id])
+			
+			representation.new(resource, metadata: metadata, value: attributes)
+		end
+		
+		def each(page: 1, per_page: 50, **parameters)
+			return to_enum(:each, page: page, per_page: per_page, **parameters) unless block_given?
+			
+			while true
+				items = @resource.get(self.class, page: page, per_page: per_page, **parameters)
+				
+				break if items.empty?
+				
+				Array(items.value).each do |item|
+					yield represent(items.metadata, item)
+				end
+				
+				page += 1
+				
+				# Was this the last page?
+				break if items.value.size < per_page
+			end
+		end
+		
+		def empty?
+			self.value.empty?
+		end
+	end
+	
+	class Event < Representation
+		def created_at
+			DateTime.parse(value[:created_at])
+		end
+	end
+	
+	class Events < Representation
+		include Paginate
+		
+		def representation
+			Event
+		end
+	end
+	
+	class User < Representation
+		def public_events
+			self.with(Events, path: "events/public")
+		end
+	end
+end
+
+puts "Connecting..."
+headers = Protocol::HTTP::Headers.new
+headers['user-agent'] = "async-rest/GitHub v#{Async::REST::VERSION}"
+
+GitHub::Client.for(ENDPOINT, headers) do |client|
+	user = client.user("ioquatix")
+	
+	events = user.public_events.to_a
+	pp events.first.created_at
+	pp events.last.created_at
+end
+
+puts "done"

data/examples/xkcd/comic.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+require_relative '../../lib/async/rest'
+require_relative '../../lib/async/rest/wrapper/url_encoded'
+
+require 'nokogiri'
+
+Async.logger.debug!
+
+module XKCD
+	module Wrapper
+		# This defines how we interact with the XKCD service.
+		class HTML < Async::REST::Wrapper::URLEncoded
+			TEXT_HTML = "text/html"
+			
+			# How to process the response body.
+			class Parser < ::Protocol::HTTP::Body::Wrapper
+				def join
+					Nokogiri::HTML(super)
+				end
+			end
+			
+			# We wrap the response body with the parser (it could incrementally parse the body).
+			def wrap_response(response)
+				if body = response.body
+					response.body = Parser.new(body)
+				end
+			end
+			
+			def process_response(request, response)
+				if content_type = response.headers['content-type']
+					if content_type.start_with? TEXT_HTML
+						wrap_response(response)
+					else
+						raise Error, "Unknown content type: #{content_type}!"
+					end
+				end
+				
+				return response
+			end
+		end
+	end
+	
+	# A comic representation.
+	class Comic < Async::REST::Representation[Wrapper::HTML]
+		def image_url
+			self.value.css("#comic img").attribute("src").text
+		end
+	end
+end
+
+Async do
+	URL = 'https://xkcd.com/'
+	
+	Async::REST::Resource.for(URL) do |resource|
+		(2000..2010).each do |id|
+			Async do
+				representation = resource.with(path: "/#{id}/").get(XKCD::Comic)
+				
+				p representation.image_url
+			end
+		end
+	end
+end

data/lib/async/rest/error.rb

@@ -23,7 +23,10 @@ module Async
 		class Error < StandardError
 		end
 		
-		class RequestFailure < Error
+		class RequestError < Error
+		end
+		
+		class ResponseError < Error
 		end
 	end
 end

data/lib/async/rest/representation.rb

@@ -28,15 +28,35 @@ module Async
 		# 
 		# 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.[] wrapper
+				klass = Class.new(Representation)
+				
+				klass.const_set(:WRAPPER, wrapper)
+				
+				return klass
+			end
+			
 			def self.for(*args, **options)
-				self.new(Resource.for(*args), **options)
+				representation = self.new(Resource.for(*args), **options)
+				
+				return representation unless block_given?
+				
+				Async do
+					begin
+						yield representation
+					ensure
+						representation.close
+					end
+				end
 			end
 			
+			WRAPPER = Wrapper::JSON
+			
 			# @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)
+			def initialize(resource, metadata: {}, value: nil, wrapper: self.class::WRAPPER.new)
 				@resource = resource
 				@wrapper = wrapper
 				
@@ -63,6 +83,7 @@ module Async
 				@resource.prepare_request(verb, payload, &@wrapper.method(:prepare_request))
 			end
 			
+			# If an exception propagates out of this method, the response will be closed.
 			def process_response(request, response)
 				@wrapper.process_response(request, response)
 			end

data/lib/async/rest/version.rb

@@ -20,6 +20,6 @@
 
 module Async
 	module REST
-		VERSION = "0.10.1"
+		VERSION = "0.12.0"
 	end
 end

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

@@ -0,0 +1,61 @@
+# 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 'json'
+require_relative 'url_encoded'
+
+module Async
+	module REST
+		module Wrapper
+			class Form < Generic
+				DEFAULT_CONTENT_TYPES = {
+					JSON::APPLICATION_JSON => JSON::Parser,
+					URLEncoded::APPLICATION_FORM_URLENCODED => URLEncoded::Parser,
+				}
+				
+				def initialize(content_types = DEFAULT_CONTENT_TYPES)
+					@content_types = content_types
+				end
+				
+				def prepare_request(payload, headers)
+					headers['accept'] ||= @content_types.keys
+					
+					if payload
+						headers['content-type'] = URLEncoded::APPLICATION_FORM_URLENCODED
+						
+						::Protocol::HTTP::Body::Buffered.new([
+							::Protocol::HTTP::URL.encode(payload)
+						])
+					end
+				end
+				
+				def parser_for(response)
+					if content_type = response.headers['content-type']
+						if parser = @content_types[content_type]
+							return parser
+						end
+					end
+					
+					return super
+				end
+			end
+		end
+	end
+end

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

@@ -32,8 +32,27 @@ module Async
 				# @param response [Protocol::HTTP::Response] the response that was received.
 				# @return [Object] some application specific representation of the response.
 				def process_response(request, response)
+					wrap_response(response)
+				end
+				
+				def parser_for(response)
+					return Unsupported
+				end
+				
+				# Wrap the response body in the given klass.
+				def wrap_response(response)
+					if body = response.body
+						response.body = parser_for(response).new(body)
+					end
+					
 					return response
 				end
+				
+				class Unsupported < HTTP::Body::Wrapper
+					def join
+						raise ResponseError, super
+					end
+				end
 			end
 		end
 	end

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

@@ -48,7 +48,6 @@ module Async
 					if payload
 						headers['content-type'] = @content_type
 						
-						# TODO dump incrementally to IO?
 						HTTP::Body::Buffered.new([
 							::JSON.dump(payload)
 						])
@@ -61,22 +60,14 @@ module Async
 					end
 				end
 				
-				def wrap_response(response)
-					if body = response.body
-						response.body = Parser.new(body)
-					end
-				end
-				
-				def process_response(request, response)
+				def parser_for(response)
 					if content_type = response.headers['content-type']
 						if content_type.start_with? @content_type
-							wrap_response(response)
-						else
-							raise Error, "Unknown content type: #{content_type}!"
+							return Parser
 						end
 					end
 					
-					return response
+					return super
 				end
 			end
 		end

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

@@ -59,22 +59,14 @@ module Async
 					end
 				end
 				
-				def wrap_response(response)
-					if body = response.body
-						response.body = Parser.new(body)
-					end
-				end
-				
-				def process_response(request, response)
+				def parser_for(response)
 					if content_type = response.headers['content-type']
 						if content_type.start_with? @content_type
-							wrap_response(response)
-						else
-							raise Error, "Unknown content type: #{content_type}!"
+							return Parser
 						end
 					end
 					
-					return response
+					return super
 				end
 			end
 		end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-rest
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-13 00:00:00.000000000 Z
+date: 2019-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -123,12 +123,15 @@ files:
 - README.md
 - Rakefile
 - async-rest.gemspec
+- examples/github/feed.rb
 - examples/slack/clean.rb
+- examples/xkcd/comic.rb
 - lib/async/rest.rb
 - lib/async/rest/error.rb
 - lib/async/rest/representation.rb
 - lib/async/rest/resource.rb
 - lib/async/rest/version.rb
+- lib/async/rest/wrapper/form.rb
 - lib/async/rest/wrapper/generic.rb
 - lib/async/rest/wrapper/json.rb
 - lib/async/rest/wrapper/url_encoded.rb
@@ -150,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: A library for RESTful clients (and hopefully servers).