fast_send 1.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1df225aaf4d88c9a194879693f2469882fa1acc6
+  data.tar.gz: 8f5eaa3d4a6d4600f7ae01ed2bae972da10f1c3d
+SHA512:
+  metadata.gz: 03e9b6a4439667c658de6cc7f9e377cadd50f7eed94dc4e085b2e5e8cd55f0944ac3794fdcaab1c68785408224fa6d8054ca1263cffa6d405c460c00ce65d7f2
+  data.tar.gz: ed25fcedadd280d9400415190b8c34aa1020f95d4caef80e9a5ead3ff3e3b662f6204ea5f18c9619f0b7b80daa963dadfcbba9b7e3bc59a7b1bcd8865e79e9fd

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem 'rake'
+  gem 'jeweler', '> 2'
+  gem 'rspec', '~> 3'
+  gem 'puma'
+  gem 'sendfile', platforms: :mri
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2016 WeTransfer
+
+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.

data/README.md

@@ -0,0 +1,100 @@
+# FastSend
+
+Is a Rack middleware to send large, long-running Rack responses via _file buffers._
+When you send a lot of data, you can saturate the Ruby GC because you have to pump
+strings to the socket through the runtime. If you already have a file handle with
+the contents that you want to send, you can let the operating system do the socket
+writes at optimum speed, without loading your Ruby VM with all the string
+cleanup. This helps to reduce GC pressure, CPU use and memory use.
+
+## Usage
+
+FastSend is a Rack middleware. Insert it before your application.
+
+    use FastSend
+
+In normal circumstances FastSend will just do nothing. You have to explicitly trigger it
+by returning a special response body object. The convention is that this object must respond
+to `each_file` instead of the standard Rack `each`. Note that you _must_ yield real Ruby `File`
+objects or subclasses, because some fairly low-level operations will be done to them - so a duck-typed
+"file-like" object is not good enough.
+
+    class BigResponse
+      def each_file
+        File.open('/large_file.bin', 'rb'){|fh| yield(fh) }
+      end
+    end
+    
+    # and in your application
+    [200, {'Content-Length' => big_size}, BigResponse.new]
+
+The response object must yield File objects from that method. It is possible to yield an unlimited
+number of files, they will all be sent to the socket in succession. The `yield` will block
+for as long as the file is not sent in full.
+
+## Bandwidth metering and callbacks
+
+Because FastSend uses Rack hijacking, it takes the usual Rack handling out of the response writing.
+So you can effectively do two things if you want to have wrapping actions performed at the start of
+the download, or at the end of the download, or at an abort:
+
+* Make use of the custom fast_send headers. They will be removed by the middleware
+* Add the method calls to your `each_file` method, using `ensure` and `rescue`
+
+For example, to receive a callback every time some bytes get sent to the client
+  
+    bytes_sent_proc = ->(sent,written_so_far_entire_response) {
+      bandwith_metering.increment(sent)
+    }
+    
+    [200, {'fast_send.bytes_sent' => bytes_sent_proc}, large_body]
+
+There are also more callbacks you can use, read the class documentation for more information on them.
+For example, you can subscribe to a callback when the client suddenly disconnects - you will get an idea
+of how much data the client could read/buffer so far before the connection went down.
+
+## Implementation details
+
+Fundamentally, FastSend takes your Ruby File handles, one by one (you can `yield` multiple times from `each_file`)
+and uses the fastest way possible, as available in your Ruby runtime, to send the file to the Rack webserver socket.
+The options it tries are:
+
+* non-blocking `sendfile(2)` call - if you have the "sendfile" gem, only on MRI/Rubinius, only on Linux
+* blocking `sendfile(2)` call - if you have the "sendfile" gem, only on MRI/Rubinius, also works on OSX
+* Java's NIO transferTo() call - if you are on jRuby
+* IO.copy_stream() for all other cases
+
+For the "sendfile" gem to work you need to add it to your application and `require` it before FastSend
+has to dispatch a request (you do not have to `require` these two in a particular order).
+
+## Webserver compatibility
+
+Your webserver (Rack adapter) _must_ support partial Rack hijacking. We use FastSend on Puma pretty much
+exclusively, and it works well. Note that WebBrick only supports partial hijacking using a self-pipe, which
+is not compatible with the socket operations in FastSend. Just like we require _real_ File objects for the
+input, we _require_ a real Rack socket (raw TCP) for the output. Sorry 'bout that.
+
+If those preconditions are not met, FastSend will revert to a standard Rack body that just reads your
+yielded file into the Ruby runtime and yields it's parts to the caller. It does inflate memory and is
+slow, but it helps sometimes
+
+## Without Rack hijacking support or when using rack-test
+
+If you need to test FastSend as part of your application, your custom `each_file`-supporting Body object
+will be wrapped with a `FastSend::NaiveEach` in your `rack-test` test case. This way the response will
+be read into the Rack client buffer, and will use the standard string-pumping that is used for long Rack
+responses. All the callbacks you define for FastSend will work.
+
+## Contributing to fast_send
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2016 WeTransfer. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,38 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+require_relative 'lib/fast_send'
+Jeweler::Tasks.new do |gem|
+  gem.version = FastSend::VERSION
+  gem.name = "fast_send"
+  gem.homepage = "https://github.com/WeTransfer/fast_send"
+  gem.license = "MIT"
+  gem.description = %Q{Send bursts of large files quickly via Rack}
+  gem.summary = %Q{and do so bypassing the Ruby VM}
+  gem.email = "me@julik.nl"
+  gem.authors = ["Julik Tarkhanov"]
+  # dependencies defined in Gemfile
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ["-c"]
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+

data/config.ru

@@ -0,0 +1,17 @@
+require './lib/fast_send'
+
+THE_F = '/Users/julik/Downloads/3gb.bin'
+SEND_TIMES = 10
+
+class TheBody
+  def each_file(&b)
+    SEND_TIMES.times { File.open(THE_F, 'rb', &b) }
+  end
+end
+
+app = ->(env) {
+  size = File.size(THE_F) * SEND_TIMES
+  [200, {'Content-Length' => size.to_s}, TheBody.new]
+}
+
+run FastSend.new(app)

data/fast_send.gemspec

@@ -0,0 +1,64 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: fast_send 1.1.2 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "fast_send"
+  s.version = "1.1.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Julik Tarkhanov"]
+  s.date = "2016-11-15"
+  s.description = "Send bursts of large files quickly via Rack"
+  s.email = "me@julik.nl"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "config.ru",
+    "fast_send.gemspec",
+    "lib/fast_send.rb",
+    "lib/fast_send/null_logger.rb",
+    "lib/fast_send/socket_handler.rb",
+    "spec/fast_send_with_mocks_spec.rb",
+    "spec/fast_send_with_puma_spec.rb",
+    "spec/test_app.ru"
+  ]
+  s.homepage = "https://github.com/WeTransfer/fast_send"
+  s.licenses = ["MIT"]
+  s.rubygems_version = "2.4.5.1"
+  s.summary = "and do so bypassing the Ruby VM"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, ["> 2"])
+      s.add_development_dependency(%q<rspec>, ["~> 3"])
+      s.add_development_dependency(%q<puma>, [">= 0"])
+      s.add_development_dependency(%q<sendfile>, [">= 0"])
+    else
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<jeweler>, ["> 2"])
+      s.add_dependency(%q<rspec>, ["~> 3"])
+      s.add_dependency(%q<puma>, [">= 0"])
+      s.add_dependency(%q<sendfile>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<jeweler>, ["> 2"])
+    s.add_dependency(%q<rspec>, ["~> 3"])
+    s.add_dependency(%q<puma>, [">= 0"])
+    s.add_dependency(%q<sendfile>, [">= 0"])
+  end
+end
+

data/lib/fast_send/null_logger.rb

@@ -0,0 +1,8 @@
+# Will be used as the logger if Rack passes us no logger at all
+module FastSend::NullLogger
+  [:debug, :info, :warn, :fatal, :error].each do |m|
+    define_method(m) do
+    end
+  end
+  extend self
+end

data/lib/fast_send/socket_handler.rb

@@ -0,0 +1,211 @@
+# Handles the TCP socket within the Rack hijack. Is used instead of a Proc object for better
+# testability and better deallocation
+class FastSend::SocketHandler < Struct.new(:stream, :logger, :started_proc, :aborted_proc, :error_proc, 
+  :done_proc, :written_proc, :cleanup_proc)
+  
+  # How many seconds we will wait before considering a client dead.
+  SOCKET_TIMEOUT = 60
+  
+  # The time between select() calls when a socket is blocking on write
+  SELECT_TIMEOUT_ON_BLOCK = 5
+  
+  # Is raised when it is not possible to send a chunk of data
+  # to the client using non-blocking sends for longer than the preset timeout
+  SlowLoris = Class.new(StandardError)
+  
+  # Whether we are forced to use blocking IO for sendfile()
+  USE_BLOCKING_SENDFILE = !!(RUBY_PLATFORM =~ /darwin/)
+  
+  # The amount of bytes we will try to fit in a single sendfile()/copy_stream() call
+  # We need to send it chunks because otherwise we have no way to have throughput
+  # stats that we need for load-balancing. Also, the sendfile() call is limited to the size
+  # of  off_t, which is platform-specific. In general, it helps to stay small on this for
+  # more control.C
+  SENDFILE_CHUNK_SIZE = 2*1024*1024
+
+  def call(socket)
+    return if socket.closed?
+    
+    writer_method_name = if socket.respond_to?(:sendfile)
+      :sendfile
+    elsif RUBY_PLATFORM == 'java'
+      :copy_nio
+    else
+      :copy_stream
+    end
+    
+    logger.debug { "Will do file-to-socket using %s" % writer_method_name }
+    
+    begin
+      logger.debug { "Starting the response" }
+      
+      bytes_written = 0
+      
+      started_proc.call(bytes_written)
+      
+      stream.each_file do | file |
+        logger.debug { "Sending %s" % file.inspect }
+        # Run the sending method, depending on the implementation
+        send(writer_method_name, socket, file) do |n_bytes_sent|
+          bytes_written += n_bytes_sent
+          logger.debug { "Written %d bytes" % bytes_written }
+          written_proc.call(n_bytes_sent, bytes_written)
+        end
+      end
+      
+      logger.info { "Response written in full - %d bytes" % bytes_written }
+      done_proc.call(bytes_written)
+    rescue *client_disconnect_exeptions => e
+      logger.warn { "Client closed connection: #{e.class}(#{e.message})" }
+      aborted_proc.call(e)
+    rescue Exception => e
+      logger.fatal { "Aborting response due to error: #{e.class}(#{e.message})" }
+      aborted_proc.call(e)
+      error_proc.call(e)
+    ensure
+      # With rack.hijack the consensus seems to be that the hijack
+      # proc is responsible for closing the socket. We also use no-keepalive
+      # so this should not pose any problems.
+      socket.close unless socket.closed?
+      logger.debug { "Performing cleanup" }
+      cleanup_proc.call(bytes_written)
+    end
+  end
+  
+  # Returns an array of Exception classes we can rescue from (using a splat)
+  #
+  # @return [Array<Class>] the classes
+  def client_disconnect_exeptions
+    [SlowLoris] + ::FastSend::CLIENT_DISCONNECTS
+  end
+  
+
+  # This is majorly useful - if the socket is not selectable after a certain
+  # timeout, it might be a slow loris or a connection that hung up on us. So if
+  # the return from select() is nil, we know that we still cannot write into
+  # the socket for some reason. Kill the request, it is dead, jim.
+  #
+  # Note that this will not work on OSX due to a sendfile() bug.
+  def fire_timeout_using_select(writable_socket)
+    at = Time.now
+    loop do
+      _, writeables, errored = IO.select(nil, [writable_socket], [writable_socket], SELECT_TIMEOUT_ON_BLOCK)
+      if writeables && writeables.include?(writable_socket) 
+        return # We can proceed
+      end
+      if errored && errored.include?(writable_socket)
+        raise SlowLoris, "Receiving socket had an error, connection will be dropped"
+      end
+      if (Time.now - at) > SOCKET_TIMEOUT
+        raise SlowLoris, "Receiving socket timed out on sendfile(), probably a dead slow loris"
+      end
+    end
+  end
+
+  # Copies the file to the socket using sendfile().
+  # If we are not running on Darwin we are going to use a non-blocking version of
+  # sendfile(), and send the socket into a select() wait loop. If no data can be written
+  # after 3 minutes the request will be terminated.
+  # On Darwin a blocking sendfile() call will be used instead.
+  #
+  # @param socket[Socket] the socket to write to
+  # @param file[File] the IO you can read from
+  # @yields num_bytes_written[Fixnum] the number of bytes written on each `IO.copy_stream() call`
+  # @return [void]
+  def sendfile(socket, file)
+    chunk = SENDFILE_CHUNK_SIZE
+    remaining = file.size
+  
+    loop do
+      break if remaining < 1
+    
+      # Use exact offsets to avoid boobytraps
+      send_this_time = remaining < chunk ? remaining : chunk
+      read_at_offset = file.size - remaining
+    
+      # We have to use blocking "sendfile" on Darwin because the non-blocking version
+      # is buggy
+      # (in an end-to-end test the number of bytes received varies).
+      written = if USE_BLOCKING_SENDFILE
+        socket.sendfile(file, read_at_offset, send_this_time)
+      else
+        socket.trysendfile(file, read_at_offset, send_this_time)
+      end
+    
+      # Will be only triggered when using non-blocking "trysendfile", i.e. on Linux.
+      if written == :wait_writable
+        fire_timeout_using_select(socket) # Used to evict slow lorises
+      elsif written.nil? # Also only relevant for "trysendfile"
+        return # We are done, nil == EOF
+      else
+        remaining -= written
+        yield(written)
+      end
+    end
+  end
+
+  # Copies the file to the socket using `IO.copy_stream`.
+  # This allows the strings flowing from file to the socket to bypass
+  # the Ruby VM and be managed within the calls without allocations.
+  # This method gets used when Socket#sendfile is not available on the
+  # system we run on (for instance, on Jruby).
+  #
+  # @param socket[Socket] the socket to write to
+  # @param file[File] the IO you can read from
+  # @yields num_bytes_written[Fixnum] the number of bytes written on each `IO.copy_stream() call`
+  # @return [void]
+  def copy_stream(socket, file)
+    chunk = SENDFILE_CHUNK_SIZE
+    remaining = file.size
+  
+    loop do
+      break if remaining < 1
+    
+      # Use exact offsets to avoid boobytraps
+      send_this_time = remaining < chunk ? remaining : chunk
+      num_bytes_written = IO.copy_stream(file, socket, send_this_time)
+    
+      if num_bytes_written.nonzero?
+        remaining -= num_bytes_written
+        yield(num_bytes_written)
+      end
+    end
+  end
+
+  # The closest you can get to sendfile with Java's NIO
+  # http://www.ibm.com/developerworks/library/j-zerocopy
+  #
+  # @param socket[Socket] the socket to write to
+  # @param file[File] the IO you can read from
+  # @yields num_bytes_written[Fixnum] the number of bytes written on each `IO.copy_stream() call`
+  # @return [void]
+  def copy_nio(socket, file)
+    chunk = SENDFILE_CHUNK_SIZE
+    remaining = file.size
+  
+    # We need a Java stream for this, and we cannot really initialize
+    # it from a jRuby File in a convenient way. Since we need it briefly
+    # and we know that the file is on the filesystem at the given path,
+    # we can just open it using the Java means, and go from there
+    input_stream = java.io.FileInputStream.new(file.path)
+    input_channel = input_stream.getChannel
+    output_channel = socket.to_channel
+  
+    loop do
+      break if remaining < 1
+    
+      # Use exact offsets to avoid boobytraps
+      send_this_time = remaining < chunk ? remaining : chunk
+      read_at = file.size - remaining
+      num_bytes_written = input_channel.transferTo(read_at, send_this_time, output_channel)
+    
+      if num_bytes_written.nonzero?
+        remaining -= num_bytes_written
+        yield(num_bytes_written)
+      end
+    end
+  ensure
+    input_channel.close
+    input_stream.close
+  end
+end

data/lib/fast_send.rb

@@ -0,0 +1,158 @@
+# A Rack middleware that sends the response using file buffers. If the response body
+# returned by the upstream application supports "each_file", then the middleware will
+# call this method, grab each yielded file in succession and use the fastest possible
+# way to send it to the client (using a response wrapper or Rack hijacking). If
+# sendfile support is available on the client socket, sendfile() will be used to stream
+# the file via the OS.
+# 
+# A sample response body object will look like this:
+#
+#     class Files
+#       def each_file
+#         File.open('data1.bin','r') {|f| yield(f) }
+#         File.open('data2.bin','r') {|f| yield(f) }
+#       end
+#     end
+#     
+#     # and then in your Rack app
+#     return [200, {'Content-Type' => 'binary/octet-stream'}, Files.new]
+#
+# Note that the receiver of `each_file` is responsbble for closing and deallocating
+# the file if necessary.
+#
+#
+# You can also supply the following response headers that will be used as callbacks
+# during the response send on the way out.
+#
+#    `fast_send.started' => ->(zero_bytes) { } # When the response is started
+#    `fast_send.bytes_sent' => ->(sent_this_time, sent_total) { } # Called on each sent chunk
+#    `fast_send.complete' => ->(sent_total) { } # When response completes without exceptions
+#    `fast_send.aborted' => ->(exception) { } # When the response is not sent completely, both for exceptions and client closes
+#    `fast_send.error' => ->(exception) { } # the response is not sent completely due to an error in the application
+#    `fast_send.cleanup' => ->(sent_total) { } # Called at the end of the response, in an ensure block
+class FastSend
+  require_relative 'fast_send/socket_handler'
+  require_relative 'fast_send/null_logger'
+  
+  VERSION = '1.1.2'
+  
+  # All exceptions that get raised when the client closes a connection before receiving the entire response
+  CLIENT_DISCONNECTS = [Errno::EPIPE, Errno::ECONNRESET, Errno::ENOTCONN, Errno::EPROTOTYPE]
+  
+  if RUBY_PLATFORM =~ /java/
+    require 'java'
+    CLIENT_DISCONNECTS << Java::JavaIo::IOException
+  end
+  
+  
+  # Gets raised if a fast_send.something is mentioned in
+  # the response headers but is not supported as a callback
+  # (the dangers of hashmaps as datastructures is that you
+  # can sometimes mistype keys)
+  UnknownCallback = Class.new(StandardError)
+
+  # Gets used as a response body wrapper if the server does not support Rack hijacking.
+  # The wrapper will be automatically applied by FastSend and will also ensure that all the
+  # callbacks get executed.
+  class NaiveEach < Struct.new(:body_with_each_file, :started, :aborted, :error, :complete, :sent, :cleanup)
+    def each
+      written = 0
+      started.call(0)
+      body_with_each_file.each_file do | file |
+        while data = file.read(64 * 1024)
+          written += data.bytesize
+          yield(data)
+          sent.call(data.bytesize, written)
+        end
+      end
+      complete.call(written)
+    rescue *CLIENT_DISCONNECTS => e
+      aborted.call(e)
+    rescue Exception => e
+      aborted.call(e)
+      error.call(e)
+      raise e
+    ensure
+      cleanup.call(written)
+    end
+  end
+  
+  NOOP = ->(*){}.freeze
+  C_Connection = 'Connection'.freeze
+  C_close = 'close'.freeze
+  C_rack_hijack = 'rack.hijack'.freeze
+  C_dispatch = 'X-Fast-Send-Dispatch'.freeze
+  C_hijack = 'hijack'.freeze
+  C_naive = 'each'.freeze
+  C_rack_logger = 'rack.logger'.freeze
+  C_SERVER_SOFTWARE = 'SERVER_SOFTWARE'.freeze
+  
+  private_constant :NullLogger
+  private_constant :C_Connection, :C_close, :C_rack_hijack, :C_dispatch, :C_hijack, :C_naive, :NOOP,
+    :C_rack_logger, :C_SERVER_SOFTWARE
+  
+  CALLBACK_HEADER_NAMES = %w( 
+    fast_send.started
+    fast_send.aborted
+    fast_send.error
+    fast_send.complete
+    fast_send.bytes_sent
+    fast_send.cleanup
+  ).freeze
+  
+  def initialize(with_rack_app)
+    @app = with_rack_app
+  end
+  
+  def call(env)
+    s, h, b = @app.call(env)
+    return [s, h, b] unless b.respond_to?(:each_file) 
+    
+    @logger = env.fetch(C_rack_logger) { NullLogger }
+    
+    server = env[C_SERVER_SOFTWARE]
+    
+    if has_robust_hijack_support?(env)
+      @logger.debug { 'Server (%s) allows partial hijack, setting up Connection: close'  % server }
+      h[C_Connection] = C_close
+      h[C_dispatch] = C_hijack
+      response_via_hijack(s, h, b)
+    else
+      @logger.warn {
+        msg = 'Server (%s) has no hijack support or hijacking is broken. Unwanted buffering possible.'
+        msg % server
+      }
+      h[C_dispatch] = C_naive
+      response_via_naive_each(s, h, b)
+    end
+  end
+  
+  private
+  
+  def has_robust_hijack_support?(env)
+    return false unless env['rack.hijack?']
+    return false if env['SERVER_SOFTWARE'] =~ /^WEBrick/ # WEBrick implements hijack using a pipe
+    true
+  end
+    
+  def response_via_naive_each(s, h, b)
+    body = NaiveEach.new(b, *callbacks_from_headers(h))
+    [s, h, body]
+  end
+  
+  def callbacks_from_headers(h)
+    headers_related = h.keys.grep(/^fast\_send\./i)
+    headers_related.each do | header_name |
+      unless CALLBACK_HEADER_NAMES.include?(header_name)
+        msg = "Unknown callback #{header_name.inspect} (supported: #{CALLBACK_HEADER_NAMES.join(', ')})"
+        raise UnknownCallback, msg
+      end
+    end 
+    CALLBACK_HEADER_NAMES.map{|cb_name| h.delete(cb_name) || NOOP }
+  end
+    
+  def response_via_hijack(status, headers, each_file_body)
+    headers[C_rack_hijack] = SocketHandler.new(each_file_body, @logger, *callbacks_from_headers(headers))
+    [status, headers, []]
+  end
+end

data/spec/fast_send_with_mocks_spec.rb

@@ -0,0 +1,451 @@
+require_relative '../lib/fast_send'
+require 'logger'
+describe 'FastSend when used with a mock Socket' do
+  let(:logger) {
+    Logger.new(nil).tap{|l| l.level = Logger::DEBUG }
+  }
+  let(:described_class) { FastSend }
+  
+  class FakeSocket
+    def initialize(with_output)
+      @out = with_output
+    end
+    
+    def closed?
+      !!@closed
+    end
+    
+    def close
+      @closed = true
+    end
+    
+    def write(data)
+      raise 'closed' if @closed
+      @out << data
+      data.bytesize
+    end
+  end
+  
+  class FakeSocketWithSendfile < FakeSocket
+    def sendfile(file, read_at_offset, send_this_time)
+      raise 'closed' if @closed
+      file.pos = read_at_offset
+      @out << file.read(send_this_time)
+      send_this_time 
+    end
+    
+    def trysendfile(file, read_at_offset, send_this_time)
+      raise 'closed' if @closed
+      file.pos = read_at_offset
+      @out << file.read(send_this_time)
+      send_this_time
+    end
+    
+    undef :write
+  end
+  
+  class EachFileResponse
+    def each_file
+      f1 = Tempfile.new('x').tap{|f| 64.times{ f << Random.new.bytes(1024 * 1024)}; f.flush; f.rewind }
+      f2 = Tempfile.new('x').tap{|f| 54.times{ f << Random.new.bytes(1024 * 1024)}; f.flush; f.rewind }
+      yield f1
+      yield f2
+    end
+  end
+  
+  class FailingResponse
+    def initialize(err_class = RuntimeError)
+      @err = err_class
+    end
+    
+    def each_file
+      raise @err.new("This should not happen")
+    end
+  end
+  
+  it 'returns the upstream response with a response that does not support each_file' do
+  
+    app = ->(env) { [200, {}, ["Hello"]] }
+    
+    handler = described_class.new(app)
+    res = handler.call({})
+    expect(res[0]).to eq(200)
+    expect(res[2]).to eq(["Hello"])
+  end
+  
+  context 'within a server that has no hijack support (using NaiveEach)' do
+    it 'sets the X-Fast-Send-Dispatch header to "each"' do
+      source_size = (64 + 54) * 1024 * 1024
+      app = ->(env) { [200, {}, EachFileResponse.new] }
+      handler = described_class.new(app)
+      
+      s, h, b = handler.call({})
+      expect(h['X-Fast-Send-Dispatch']).to eq('each')
+    end
+    
+    it 'returns a naive each wrapper' do
+      source_size = (64 + 54) * 1024 * 1024
+      app = ->(env) { [200, {}, EachFileResponse.new] }
+      handler = described_class.new(app)
+      
+      s, h, b = handler.call({})
+      expect(s).to eq(200)
+      
+      tf = Tempfile.new('out')
+      b.each{|data| tf << data }
+      expect(tf.size).to eq((64 + 54) * 1024 * 1024)
+    end
+    
+    it 'executes the aborted callback, the error callback and the cleanup callback if the response raises during reads' do
+      source_size = (64 + 54) * 1024 * 1024
+      aborted_cb = ->(e) { expect(e).to be_kind_of(StandardError) }
+      error_cb = ->(e) { expect(e).to be_kind_of(StandardError) }
+      cleanup_cb = ->(sent) { expect(sent).to be_zero }
+      
+      app = ->(env) {
+        [200, {'fast_send.aborted' => aborted_cb, 'fast_send.error' => error_cb, 'fast_send.cleanup' => cleanup_cb},
+          FailingResponse.new]
+      }
+      
+      handler = described_class.new(app)
+      
+      s, h, b = handler.call({})
+      expect(s).to eq(200)
+      expect(h.keys.grep(/fast\_send/)).to be_empty
+      
+      expect(error_cb).to receive(:call)
+      expect(aborted_cb).to receive(:call)
+      expect(cleanup_cb).to receive(:call)
+      
+      tf = Tempfile.new('out')
+      expect {
+        b.each{|data| tf << data }
+      }.to raise_error(RuntimeError)
+    end
+    
+    it 'executes the aborted callback and the cleanup callback, but not the error callback on an EPIPE' do
+      source_size = (64 + 54) * 1024 * 1024
+      aborted_cb = ->(e) { expect(e).to be_kind_of(StandardError) }
+      error_cb = ->(e) { raise "Should never be called" }
+      cleanup_cb = ->(sent) { expect(sent).to be_zero }
+      
+      app = ->(env) { [200, {'fast_send.aborted' => aborted_cb, 'fast_send.error' => error_cb, 'fast_send.cleanup' => cleanup_cb},
+          FailingResponse.new(Errno::EPIPE)] }
+      
+      handler = described_class.new(app)
+      
+      s, h, b = handler.call({})
+      expect(s).to eq(200)
+      expect(h.keys.grep(/fast\_send/)).to be_empty
+      
+      expect(error_cb).not_to receive(:call)
+      expect(aborted_cb).to receive(:call)
+      expect(cleanup_cb).to receive(:call)
+      
+      tf = Tempfile.new('out')
+      b.each{|data| tf << data } # Raises an exception but it gets suppressed
+    end
+    
+    it 'executes the bytes sent callback on each send of 64 kilobytes' do
+      source_size = (64 + 54) * 1024 * 1024
+      
+      callbacks = []
+      sent_cb = ->(written, total_so_far) { callbacks << [written, total_so_far] }
+      
+      app = ->(env) { [200, {'fast_send.bytes_sent' => sent_cb},
+          EachFileResponse.new] }
+      
+      handler = described_class.new(app)
+      
+      s, h, b = handler.call({})
+      
+      expect(s).to eq(200)
+      expect(h.keys.grep(/fast\_send/)).to be_empty
+      
+      b.each{|data| }
+      
+      expect(callbacks).not_to be_empty
+      expect(callbacks.length).to eq(1888)
+    end
+  end
+  
+  it 'raises about an unknown callback in the response headers if it finds one' do
+    app = ->(env) { [200, {'fast_send.mistyped_header'=> Proc.new{} }, EachFileResponse.new] }
+    handler = described_class.new(app)
+    
+    expect {
+      handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    }.to raise_error(/Unknown callback \"fast_send\.mistyped\_header\"/)
+  end
+  
+  it 'sets the X-Fast-Send-Dispatch header to "hijack"' do
+    source_size = (64 + 54) * 1024 * 1024
+    app = ->(env) { [200, {}, EachFileResponse.new] }
+    
+    handler = described_class.new(app)
+    
+    status, headers, body = handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    expect(headers['X-Fast-Send-Dispatch']).to eq('hijack')
+  end
+  
+  it 'sends the files to the socket using sendfile()' do
+    source_size = (64 + 54) * 1024 * 1024
+    app = ->(env) { [200, {}, EachFileResponse.new] }
+    
+    handler = described_class.new(app)
+    
+    status, headers, body = handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    output = Tempfile.new('response_body')
+    
+    fake_socket = FakeSocketWithSendfile.new(output)
+    if described_class::SocketHandler::USE_BLOCKING_SENDFILE
+      expect(fake_socket).to receive(:sendfile).at_least(:once).and_call_original
+    else
+      expect(fake_socket).to receive(:trysendfile).at_least(:once).and_call_original
+    end
+    
+    # The socket MUST get closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+    
+    expect(output.size).to eq(source_size)
+  end
+  
+  it 'sends the files to the socket using write()' do
+    source_size = (64 + 54) * 1024 * 1024
+    app = ->(env) { [200, {}, EachFileResponse.new] }
+    
+    handler = described_class.new(app)
+    
+    status, headers, body = handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    output = Tempfile.new('response_body')
+    
+    fake_socket = FakeSocket.new(output)
+    # The socket MUST get closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+    
+    expect(output.size).to eq(source_size)
+  end
+  
+  
+  it 'can execute the hijack proc twice without resending the data' do
+    source_size = (64 + 54) * 1024 * 1024
+    app = ->(env) { [200, {}, EachFileResponse.new] }
+    
+    handler = described_class.new(app)
+    
+    status, headers, body = handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    output = Tempfile.new('response_body')
+    
+    fake_socket = FakeSocket.new(output)
+    # The socket MUST get closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    
+    hijack.call(fake_socket)
+    hijack.call(fake_socket)
+  end
+  
+  it 'sets up the hijack proc and sends the file to the socket using write()' do
+    source_size = (64 + 54) * 1024 * 1024
+    app = ->(env) { [200, {}, EachFileResponse.new] }
+    
+    handler = described_class.new(app)
+    
+    status, headers, body = handler.call({'rack.hijack?' => true, 'rack.logger' => logger})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    output = Tempfile.new('response_body')
+    
+    fake_socket = FakeSocketWithSendfile.new(output)
+    # The socket MUST get closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+    
+    expect(output.size).to eq(source_size)
+  end
+  
+  it 'calls all the supplied callback procs set in the headers' do
+    source_size = (64 + 54) * 1024 * 1024
+    callbacks = []
+    
+    app = ->(env) {
+      [200, {
+        'fast_send.started' => ->(b){ callbacks << [:started, b] },
+        'fast_send.complete' => ->(b){ callbacks << [:complete, b] },
+        'fast_send.bytes_sent' => ->(now, total) { callbacks << [:bytes_sent, now, total] },
+        'fast_send.cleanup' => ->(b){ callbacks << [:cleanup, b] },
+      }, EachFileResponse.new]
+    }
+    
+    handler = described_class.new(app)
+    status, headers, body = handler.call({'rack.hijack?' => true})
+    
+    keys = headers.keys
+    expect(keys.grep(/fast\_send/)).to be_empty # The callback headers should be removed
+    
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    fake_socket = double('Socket')
+    
+    allow(fake_socket).to receive(:respond_to?).with(:sendfile) { false }
+    allow(fake_socket).to receive(:respond_to?).with(:to_path) { false } # called by IO.copy_stream
+    
+    expect(fake_socket).to receive(:closed?) { false }
+    allow(fake_socket).to receive(:write) {|data| data.bytesize }
+    
+    expect(fake_socket).to receive(:closed?) { false }
+    expect(fake_socket).to receive(:close) # The socket MUST be closed at the end of hijack
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+    
+    expect(callbacks.length).to eq(62)
+    
+    expect(callbacks[0]).to eq([:started, 0])
+    expect(callbacks[-2]).to eq([:complete, 123731968])
+    expect(callbacks[-1]).to eq([:cleanup, 123731968])
+    
+    bytes_sent_cbs = callbacks[1..-3]
+    bytes_sent_cbs.each_with_index do | c, i |
+      expect(c[1]).to be_kind_of(Fixnum)
+      expect(c[2]).to be_kind_of(Fixnum)
+    end
+  end
+  
+  it 'closes the socket even when the cleanup proc raises' do
+    source_size = (64 + 54) * 1024 * 1024
+    callbacks = []
+    
+    app = ->(env) {
+      [200, {
+        'fast_send.cleanup' => ->(b){ raise "Failed when executing the cleanup callbacks" },
+      }, EachFileResponse.new]
+    }
+    
+    handler = described_class.new(app)
+    status, headers, body = handler.call({'rack.hijack?' => true})
+    
+    keys = headers.keys
+    expect(keys.grep(/fast\_send/)).to be_empty # The callback headers should be removed
+    
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    fake_socket = double('Socket')
+    
+    allow(fake_socket).to receive(:respond_to?).with(:sendfile) { false }
+    allow(fake_socket).to receive(:respond_to?).with(:to_path) { false } # called by IO.copy_stream
+    
+    expect(fake_socket).to receive(:closed?) { false }
+    allow(fake_socket).to receive(:write) {|data| data.bytesize }
+    
+    expect(fake_socket).to receive(:closed?) { false }
+    expect(fake_socket).to receive(:close) # The socket MUST be closed at the end of hijack
+    
+    hijack = headers.fetch('rack.hijack')
+    expect {
+      hijack.call(fake_socket)
+    }.to raise_error(/Failed when executing the cleanup callback/)
+  end
+  
+  it 'passes the exception to the fast_send.error proc' do
+    source_size = (64 + 54) * 1024 * 1024
+    
+    error_proc = ->(e){ expect(e).to be_kind_of(RuntimeError) }
+    expect(error_proc).to receive(:call).and_call_original
+    
+    app = ->(env) {
+      [200, {
+        'Content-Length' => source_size.to_s,
+        'fast_send.error' => error_proc,
+      }, FailingResponse.new]
+    }
+    
+    handler = described_class.new(app)
+    status, headers, body = handler.call({'rack.hijack?' => true})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    fake_socket = FakeSocketWithSendfile.new(Tempfile.new('tt'))
+    # The socket MUST be closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+  end
+  
+  it 'does not pass an EPIPE to the fast_send.error proc' do
+    source_size = (64 + 54) * 1024 * 1024
+    
+    error_proc = ->(*){ throw :no }
+    expect(error_proc).not_to receive(:call)
+    
+    app = ->(env) {
+      [200, {
+        'Content-Length' => source_size.to_s,
+        'fast_send.error' => error_proc,
+      }, FailingResponse.new(Errno::EPIPE)]
+    }
+    
+    handler = described_class.new(app)
+    status, headers, body = handler.call({'rack.hijack?' => true})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    fake_socket = FakeSocketWithSendfile.new(Tempfile.new('tt'))
+    # The socket MUST be closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+  end
+  
+  it 'passes the exception to the fast_send.aborted proc' do
+    source_size = (64 + 54) * 1024 * 1024
+    
+    abort_proc = ->(e){ expect(e).to be_kind_of(RuntimeError) }
+    expect(abort_proc).to receive(:call).and_call_original
+    
+    app = ->(env) {
+      [200, {
+        'Content-Length' => source_size.to_s,
+        'fast_send.aborted' => abort_proc,
+      }, FailingResponse.new]
+    }
+    
+    handler = described_class.new(app)
+    status, headers, body = handler.call({'rack.hijack?' => true})
+    expect(status).to eq(200)
+    expect(body).to eq([])
+    
+    fake_socket = FakeSocketWithSendfile.new(Tempfile.new('tt'))
+    # The socket MUST be closed at the end of hijack
+    expect(fake_socket).to receive(:close).and_call_original
+    
+    hijack = headers.fetch('rack.hijack')
+    hijack.call(fake_socket)
+  end
+  
+  it 'halts the response when the socket times out in IO.select'
+  it 'halts the response when the socket errors in IO.select'
+end

data/spec/fast_send_with_puma_spec.rb

@@ -0,0 +1,63 @@
+require_relative '../lib/fast_send'
+require 'net/http'
+
+describe 'FastSend when used in combination with Puma' do
+  before :all do
+#   @server = Thread.new {
+#     ``
+#   }
+    command = 'bundle exec puma --port 9293 %s/test_app.ru' % __dir__
+    @server_pid = spawn(command)
+  end
+
+  it 'offers the file for download, sends the entire file' do
+    begin
+      require 'sendfile'
+    rescue LoadError # jruby et al
+    end
+    
+    tries = 0
+    begin
+      headers = {}
+      uri = URI('http://127.0.0.1:9293')
+      conn = Net::HTTP.new(uri.host, uri.port)
+      conn.read_timeout = 1
+      conn.open_timeout = 1
+      conn.start do |http|
+        req = Net::HTTP::Get.new(uri.request_uri)
+        http.request(req) do |res|
+        
+          dispatch = res.header['X-Fast-Send-Dispatch']
+          expect(dispatch).to eq('hijack')
+        
+          downloaded_copy = Tempfile.new('cpy')
+          downloaded_copy.binmode
+          
+          res.read_body {|chunk| downloaded_copy << chunk }
+          downloaded_copy.rewind
+          
+          expect(downloaded_copy.size).to eq(res.header['Content-Length'].to_i)
+          
+          File.open(res.header['X-Source-Path'], 'rb') do |source_file|
+            loop do
+              pos = source_file.pos
+              from_source = source_file.read(5)
+              downloaded = downloaded_copy.read(5)
+              break if from_source
+              expect(downloaded.unpack("C*")).to eq(from_source.unpack("C*"))
+            end
+          end
+        end
+      end
+    rescue Errno::ECONNREFUSED => e # Puma hasn't started yet
+      raise e if (tries += 1) > 100
+      sleep 0.5
+      retry
+    end
+  end
+  
+  after :all do
+    Process.kill('TERM', @server_pid)
+    Process.wait(@server_pid)
+  end
+end

data/spec/test_app.ru

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/../lib/fast_send'
+
+require 'bundler'
+Bundler.require(:development)
+
+TF = Tempfile.new('xx')
+TF.binmode
+64.times { TF << Random.new.bytes(1024*1024) }
+TF.flush
+TF.rewind
+
+use FastSend
+
+class Eacher
+  def each_file
+    yield(TF)
+  ensure
+    TF.rewind
+  end
+end
+
+run ->(env) {
+  [200, {'Content-Length' => TF.size.to_s, 'X-Source-Path' => TF.path}, Eacher.new]
+}

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: fast_send
+version: !ruby/object:Gem::Version
+  version: 1.1.2
+platform: ruby
+authors:
+- Julik Tarkhanov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sendfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Send bursts of large files quickly via Rack
+email: me@julik.nl
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- config.ru
+- fast_send.gemspec
+- lib/fast_send.rb
+- lib/fast_send/null_logger.rb
+- lib/fast_send/socket_handler.rb
+- spec/fast_send_with_mocks_spec.rb
+- spec/fast_send_with_puma_spec.rb
+- spec/test_app.ru
+homepage: https://github.com/WeTransfer/fast_send
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: and do so bypassing the Ruby VM
+test_files: []