protocol-http 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f14e6a0192840efd07d2ba8e8e3a8bd9312eb5fa8b976f1e12baaf14ee49696
-  data.tar.gz: 2548bc880b20a5e162cad7fdcbbece9a0cdfae429861b8a5f1bbd68cf904cb9b
+  metadata.gz: 01dc23ef2870a6572cc986fd3dac2de5902ec3283fb5a380d9f24b1193516d68
+  data.tar.gz: ca6bf9694e01884a6d2c2e9ab5e85c54d64c4f150881cf57fb2ba1ed80fa0b9c
 SHA512:
-  metadata.gz: b1e6692c96818aed1ed11c02b976169598ba9df9afc1f73109745168f62d85a75b6bf9abe530cac1daa39a3a40b5a815e06280581d8912b6c32f7e488f35fac0
-  data.tar.gz: 747e961c97c027258a46fbbd70f9845eead55d0c3dc6d108dae0083b99693bf5384f3868c9d50e5270d06337341879d265dc362a7907a16d22ecca73149e8223
+  metadata.gz: d71145aa0b55861140b181c2351501cd9eec840b747abd4d5d48841a4e8d2df0bb5d2e5fa0c0c83be98a51775e92160cd52690806c5b1443808f7d6386cdc568
+  data.tar.gz: f2f603776458e27ed0b2148fce7c9f9ac419417c001e2ea42270248df651c34f524b6646926847a8aa93139509b8bd72d86c875a3b341e9c16eb0a124ecfd6a5

data/STREAMING.md

@@ -0,0 +1,69 @@
+# Streaming
+
+Streaming is a complex topic given that most server's are not scalable in this respect. A variety of solutions exist to work around limited server implementations, but they impose significant burden on the implementation and are generally incompatible with implementations of HTTP which are not request per connection. We propose to simplify the current Rack implementation to support streaming in a consistent way, but also allow for backwards compatibility with existing servers.
+
+## Current Implementation
+
+Rack currently supports streaming using `rack.hijack`. There are two ways to hijack the underlying socket for a given request: a partial hijack and a full hijack. Not all servers support both modes of operation and neither method is fully compatible with HTTP/2.
+
+### Partial Hijack
+
+A partial hijack allows the web server to respond with the response status, headers, and then yields the stream back to the application code. It does this by using a special `rack.hijack` header:
+
+``` ruby
+def call(env)
+	body = proc do |stream|
+		stream.write("Hello World")
+		stream.close
+	end
+	
+	if env['rack.hijack?']
+		return [200, {'rack.hijack' => body}, nil]
+	end
+end
+```
+
+- It is not clear whether the body needs to handle the formatting of the response, i.e. chunked encoding, compression, transfer encoding, etc.
+- It mixes `rack.` specific headers with normal HTTP headers which is computationally expensive for the server to detect.
+- It's not clear what the returned body should be.
+
+### Full Hijack
+
+A full hijack allows the web server to completely take control of the underlying socket. This occurs at the point the `rack.hijack` is invoked.
+
+``` ruby
+def call(env)
+	if hijack = env['rack.hijack']
+		socket = hijack.call
+		
+		Thread.new do
+			socket.write("Hello World")
+			socket.close
+		end
+		
+		return nil # ???
+	end
+end
+```
+
+- The socket might not actually be a raw socket, if the server is using TLS.
+- Extreme care is required in order to handle the protocol correctly.
+- It's not clear if such a design can work with anything other than HTTP/1.
+- The user code **must** return from the `call(env)` method in order for the server continue handling requests.
+- It's not clear what the response should be.
+
+## Typical Scenarios
+
+There are several typical scenarios where `rack.hijack` has been used.
+
+### ActionCable
+
+ActionCable uses full hijack in order to negotiate and communicate using WebSocket protocol. Such a design requires the ActionCable server to run in the same process as the web server.
+
+### MessageBus
+
+MessageBus uses full hijack in order to keep the socket alive and feed messages occasionally.
+
+## Supporting HTTP/2
+
+It is possible to support partial hijack in HTTP/2. The hijacked stream is multiplexed the same as any other connection. However, such a design cannot be thread safe without significant design trade-offs.

data/lib/protocol/http/body/{streamable.rb → completable.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2020, 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
@@ -25,8 +25,8 @@ require_relative 'wrapper'
 module Protocol
 	module HTTP
 		module Body
-			# Invokes a callback once the body has finished reading.
-			class Streamable < Wrapper
+			# Invokes a callback once the body has completed, either successfully or due to an error.
+			class Completable < Wrapper
 				def self.wrap(message, &block)
 					if body = message&.body and !body.empty?
 						message.body = self.new(message.body, block)

data/lib/protocol/http/body/readable.rb

@@ -60,6 +60,21 @@ module Protocol
 					nil
 				end
 				
+				# Should the internal mechanism prefer to use {call}?
+				# @returns [Boolean]
+				def stream?
+					false
+				end
+				
+				# Write the body to the given stream.
+				def call(stream)
+					while chunk = self.read
+						stream.write(chunk)
+					end
+				ensure
+					stream.close($!)
+				end
+				
 				# Read all remaining chunks into a buffered body and close the underlying input.
 				def finish
 					# Internally, this invokes `self.each` which then invokes `self.close`.

data/lib/protocol/http/body/wrapper.rb

@@ -71,6 +71,14 @@ module Protocol
 				def inspect
 					@body.inspect
 				end
+				
+				def stream?
+					@body.stream?
+				end
+				
+				def call(stream)
+					@body.call(stream)
+				end
 			end
 		end
 	end

data/lib/protocol/http/version.rb

@@ -22,6 +22,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.20.1"
+		VERSION = "0.21.0"
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.20.1
+  version: 0.21.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-19 00:00:00.000000000 Z
+date: 2020-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: covered
@@ -64,11 +64,13 @@ files:
 - ".gitignore"
 - ".rspec"
 - README.md
+- STREAMING.md
 - bake.rb
 - gems.rb
 - lib/protocol/http.rb
 - lib/protocol/http/accept_encoding.rb
 - lib/protocol/http/body/buffered.rb
+- lib/protocol/http/body/completable.rb
 - lib/protocol/http/body/deflate.rb
 - lib/protocol/http/body/digestable.rb
 - lib/protocol/http/body/file.rb
@@ -78,7 +80,6 @@ files:
 - lib/protocol/http/body/reader.rb
 - lib/protocol/http/body/rewindable.rb
 - lib/protocol/http/body/stream.rb
-- lib/protocol/http/body/streamable.rb
 - lib/protocol/http/body/wrapper.rb
 - lib/protocol/http/content_encoding.rb
 - lib/protocol/http/cookie.rb
@@ -121,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
 summary: Provides abstractions to handle HTTP protocols.