yahns 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed39f1e1cd058304e952eec64aa936763d1afd90
-  data.tar.gz: 97d35c0cbf569626a2ad5670f558c09736c76d97
+  metadata.gz: 2e1ce64c8f47f927355913c766a4c7cc3d007089
+  data.tar.gz: 29d5d3c75d4b05671d62f30987c71afa544d6950
 SHA512:
-  metadata.gz: bf372119bfdf2226d133e1b0ff4a74f51d2f79811901da42f601f4c92f872c13c2a31fbd872eb38b1f7fa2f34db5871037ebc4d1be282fdc14a690664238fe07
-  data.tar.gz: 5e4af052c543e3154ad7c9a5abdd4af95aa9c711a53236e9cd5b74ada45585e7ae4d6b0fbd279dc6fd19422a946aa1e2de5241c0fd5439d25579029e627a8fb7
+  metadata.gz: 5fdfdb0cf9f3baf831cdf5d8af0f6779f2efc930c6736bdd5f31a18ea4248cf93643476208bfa93e2d43eb9026988b14a084cd708121098489bec599bf55f8d1
+  data.tar.gz: 6c1f462a5a96ae40eed022c339994e2254ddd3fdb9b95a453ddda67ab04b509badf35868a69840b97a28a66a613fc20407f9104ac6eb769d11ca72a1d553d10d

data/Documentation/yahns_config.txt

@@ -208,6 +208,9 @@ Ruby it is running under.
     if input_buffering is false.  This also governs the size of an
     individual read(2) system call when reading a request body.
 
+    There is generally no need to change this value and this directive
+    may be removed in the future.
+
     Default: 8192 bytes (8 kilobytes)
 
 * client_header_buffer_size INTEGER

data/GIT-VERSION-GEN

@@ -4,7 +4,7 @@
 CONSTANT = "Yahns::VERSION"
 RVF = "lib/yahns/version.rb"
 GVF = "GIT-VERSION-FILE"
-DEF_VER = "v1.6.0"
+DEF_VER = "v1.7.0"
 vn = DEF_VER
 
 # First see if there is a version file (included in release tarballs),

data/extras/proxy_pass.rb

@@ -1,5 +1,5 @@
 # -*- encoding: binary -*-
-# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# Copyright (C) 2013-2015 all contributors <yahns-public@yhbt.net>
 # License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
 require 'time'
 require 'socket'
@@ -16,9 +16,6 @@ require 'timeout'
 # cheap on GNU/Linux...
 # This is totally untested but currently doesn't serve anything important.
 class ProxyPass # :nodoc:
-  CHUNK_SIZE = 16384
-  ERROR_502 = [ 502, {'Content-Length'=>'0','Content-Type'=>'text/plain'}, [] ]
-
   class ConnPool
     def initialize
       @mtx = Mutex.new
@@ -115,29 +112,38 @@ class ProxyPass # :nodoc:
 
   def initialize(dest, timeout = 5)
     case dest
-    when %r{\Ahttp://([^/]+)(/.*)\z}
+    when %r{\Aunix:([^:]+)(?::(/.*))?\z}
+      path = $2
+      @sockaddr = Socket.sockaddr_un($1)
+    when %r{\Ahttp://([^/]+)(/.*)?\z}
       path = $2
       host, port = $1.split(':')
       @sockaddr = Socket.sockaddr_in(port || 80, host)
-
-      # methods from Rack::Request we want:
-      allow = %w(fullpath host_with_port host port url path)
-      @path = path
-      want = path.scan(/\$(\w+)/).flatten! || []
-      diff = want - allow
-      diff.empty? or
-               raise ArgumentError, "vars not allowed: #{diff.uniq.join(' ')}"
     else
-      raise ArgumentError, "destination must be an HTTP URL"
+      raise ArgumentError, "destination must be an HTTP URL or unix: path"
     end
+    init_path_vars(path)
     @pool = ConnPool.new
     @timeout = timeout
   end
 
+  def init_path_vars(path)
+    path ||= '$fullpath'
+    # methods from Rack::Request we want:
+    allow = %w(fullpath host_with_port host port url path)
+    want = path.scan(/\$(\w+)/).flatten! || []
+    diff = want - allow
+    diff.empty? or
+             raise ArgumentError, "vars not allowed: #{diff.uniq.join(' ')}"
+
+    # kill leading slash just in case...
+    @path = path.gsub(%r{\A/(\$(?:fullpath|path))}, '\1')
+  end
+
   def call(env)
     request_method = env['REQUEST_METHOD']
     req = Rack::Request.new(env)
-    path = @path.gsub(/\$(\w+)/) { req.__send__($1.to_sym) }
+    path = @path.gsub(/\$(\w+)/) { req.__send__($1) }
     req = "#{request_method} #{path} HTTP/1.1\r\n" \
           "X-Forwarded-For: #{env["REMOTE_ADDR"]}\r\n"
 
@@ -188,7 +194,7 @@ class ProxyPass # :nodoc:
       logger = env['rack.logger'] and
         Yahns::Log.exception(logger, 'proxy_pass', e)
     end
-    ERROR_502
+    [ 502, { 'Content-Length' => '0', 'Content-Type' => 'text/plain' }, [] ]
   end
 
   def send_body(input, ures, chunked)

data/lib/yahns/client_expire_tcpi.rb

@@ -38,4 +38,4 @@ module Yahns::ClientExpireTCPI # :nodoc:
   end
 # FreeBSD has "struct tcp_info", too, but does not support all the fields
 # Linux does as of FreeBSD 9 (haven't checked FreeBSD 10, yet).
-end if RUBY_PLATFORM =~ /linux/
+end if RUBY_PLATFORM.include?('linux')

data/lib/yahns/config.rb

@@ -18,8 +18,8 @@ class Yahns::Config # :nodoc:
   end
 
   def _check_in_block(ctx, var)
-    if ctx == nil
-      return var if @block == nil
+    if ctx.nil?
+      return var if @block.nil?
       msg = "#{var} must be called outside of #{@block.type}"
     else
       ctx = Array(ctx)
@@ -236,7 +236,7 @@ class Yahns::Config # :nodoc:
   def canonicalize_tcp(addr, port)
     packed = Socket.pack_sockaddr_in(port, addr)
     port, addr = Socket.unpack_sockaddr_in(packed)
-    /:/ =~ addr ? "[#{addr}]:#{port}" : "#{addr}:#{port}"
+    addr.include?(':') ? "[#{addr}]:#{port}" : "#{addr}:#{port}"
   end
 
   def queue(*args, &block)
@@ -400,9 +400,8 @@ class Yahns::Config # :nodoc:
     var = _check_in_block(:app, :errors)
     if String === val
       # we've already bound working_directory by the time we get here
-      val = File.open(File.expand_path(val), "a")
+      val = File.open(File.expand_path(val), "ab")
       val.close_on_exec = val.sync = true
-      val.binmode
     else
       rt = [ :puts, :write, :flush ] # match Rack::Lint
       rt.all? { |m| val.respond_to?(m) } or raise ArgumentError,

data/lib/yahns/fdmap.rb

@@ -59,6 +59,15 @@ class Yahns::Fdmap # :nodoc:
     end
   end
 
+  # used by proxy to re-enable an existing client
+  def remember(io)
+    fd = io.fileno
+    @fdmap_mtx.synchronize do
+      @count += 1
+      @fdmap_ary[fd] = io
+    end
+  end
+
   # this is only called in Errno::EMFILE/Errno::ENFILE situations
   # and graceful shutdown
   def desperate_expire(timeout)

data/lib/yahns/http_client.rb

@@ -57,7 +57,7 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
             "Content-Length:#{len} too large (>#{mbs})", []
     end
     @state = :body
-    @input = k.tmpio_for(len)
+    @input = k.tmpio_for(len, @hs.env)
 
     rbuf = Thread.current[:yahns_rbuf]
     @hs.filter_body(rbuf, @hs.buf)
@@ -179,8 +179,9 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
     handle_error(e)
   end
 
+  # only called when buffering slow clients
   # returns :wait_readable, :wait_writable, :ignore, or nil for epoll
-  # returns false to keep looping inside yahns_step
+  # returns true to keep looping inside yahns_step
   def r100_done
     k = self.class
     case k.input_buffering
@@ -193,7 +194,9 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
       mkinput_preread # keep looping (@state == :body)
       true
     else # :lazy, false
-      http_response_write(*k.app.call(@hs.env))
+      r = k.app.call(env = @hs.env)
+      return :ignore if env.include?(RACK_HIJACK_IO)
+      http_response_write(*r)
     end
   end
 
@@ -205,7 +208,7 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
     # check_client_connection
     if input
       env[REMOTE_ADDR] = @kgio_addr
-      env[RACK_HIJACK] = hijack_proc(env)
+      env[RACK_HIJACK] = self
       env[RACK_INPUT] = input
 
       if k.check_client_connection && @hs.headers?
@@ -225,14 +228,6 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
     http_response_write(status, headers, body)
   end
 
-  # this is the env["rack.hijack"] callback exposed to the Rack app
-  def hijack_proc(env)
-    proc do
-      hijack_cleanup
-      env[RACK_HIJACK_IO] = self
-    end
-  end
-
   # called automatically by kgio_write
   def kgio_wait_writable(timeout = self.class.client_timeout)
     super timeout
@@ -256,14 +251,19 @@ class Yahns::HttpClient < Kgio::Socket # :nodoc:
   end
 
   # allow releasing some memory if rack.hijack is used
+  # n.b. we no longer issue EPOLL_CTL_DEL because it becomes more expensive
+  # (and complicated) as our hijack support will allow "un-hijacking"
+  # the socket.
   def hijack_cleanup
-    # we must issue EPOLL_CTL_DEL before hijacking (if we issue it at all),
-    # because the hijacker may close use before we get back to the epoll worker
-    # loop.  EPOLL_CTL_DEL saves about 200 bytes of unswappable kernel memory,
-    # so it can matter if we have lots of hijacked sockets.
-    self.class.queue.queue_del(self) # EPOLL_CTL_DEL
-    @input = @input.close if @input
-    @hs = nil # no need for the HTTP parser anymore
+    # prevent socket from holding process up
+    Thread.current[:yahns_fdmap].forget(self)
+    @input = nil # keep env["rack.input"] accessible, though
+  end
+
+  # this is the env["rack.hijack"] callback exposed to the Rack app
+  def call
+    hijack_cleanup
+    @hs.env[RACK_HIJACK_IO] = self
   end
 
   def response_hijacked(fn)

data/lib/yahns/http_context.rb

@@ -18,7 +18,7 @@ module Yahns::HttpContext # :nodoc:
   attr_reader :app
   attr_reader :app_defaults
   attr_writer :input_buffer_tmpdir
-  attr_writer :output_buffer_tmpdir
+  attr_accessor :output_buffer_tmpdir
 
   def http_ctx_init(yahns_rack)
     @yahns_rack = yahns_rack
@@ -46,7 +46,7 @@ module Yahns::HttpContext # :nodoc:
 
   def __wrap_app(app)
     # input_buffering == false is handled in http_client
-    return app if @client_max_body_size == nil
+    return app if @client_max_body_size.nil?
 
     require_relative 'cap_input'
     return app if @input_buffering == true
@@ -77,22 +77,15 @@ module Yahns::HttpContext # :nodoc:
     @app_defaults["rack.errors"]
   end
 
-  def tmpio_for(len)
-    if len # Content-Length given
-      len <= @client_body_buffer_size ? StringIO.new("")
-           : Yahns::TmpIO.new(input_buffer_tmpdir)
-    else # chunked, unknown length
-      mbs = @client_max_body_size
-      tmpdir = input_buffer_tmpdir
-      mbs ? Yahns::CapInput.new(mbs, tmpdir) : Yahns::TmpIO.new(tmpdir)
-    end
-  end
-
-  def input_buffer_tmpdir
-    @input_buffer_tmpdir || Dir.tmpdir
-  end
+  def tmpio_for(len, env)
+    # short requests are most common
+    return StringIO.new('') if len && len <= @client_body_buffer_size;
 
-  def output_buffer_tmpdir
-    @output_buffer_tmpdir || Dir.tmpdir
+    # too big or chunked, unknown length
+    tmp = @input_buffer_tmpdir
+    mbs = @client_max_body_size
+    tmp = mbs ? Yahns::CapInput.new(mbs, tmp) : Yahns::TmpIO.new(tmp)
+    (env['rack.tempfiles'] ||= []) << tmp
+    tmp
   end
 end

data/lib/yahns/http_response.rb

@@ -67,7 +67,7 @@ module Yahns::HttpResponse # :nodoc:
       alive = Yahns::StreamFile.new(body, alive, offset, count)
       body = nil
     end
-    wbuf = Yahns::Wbuf.new(body, alive, self.class.output_buffer_tmpdir)
+    wbuf = Yahns::Wbuf.new(body, alive, self.class.output_buffer_tmpdir, ret)
     rv = wbuf.wbuf_write(self, header)
     body.each { |chunk| rv = wbuf.wbuf_write(self, chunk) } if body
     wbuf_maybe(wbuf, rv)
@@ -199,7 +199,7 @@ module Yahns::HttpResponse # :nodoc:
           chunk = rv # hope the skb grows when we loop into the trywrite
         when :wait_writable, :wait_readable
           if k.output_buffering
-            wbuf = Yahns::Wbuf.new(body, alive, k.output_buffer_tmpdir)
+            wbuf = Yahns::Wbuf.new(body, alive, k.output_buffer_tmpdir, rv)
             rv = wbuf.wbuf_write(self, chunk)
             break
           else

data/lib/yahns/openssl_client.rb

@@ -8,6 +8,31 @@ require_relative 'sendfile_compat'
 module Yahns::OpenSSLClient # :nodoc:
   include Yahns::SendfileCompat
 
+  def self.included(cls)
+    # Forward these methods to OpenSSL::SSL::SSLSocket so hijackers
+    # can rely on stdlib methods instead of ugly kgio stuff that
+    # we hope to phase out.
+    # This is a bit weird, since OpenSSL::SSL::SSLSocket wraps
+    # our actual socket, too, so we must take care to not blindly
+    # use method_missing and cause infinite recursion
+    %w(sync= read write readpartial write_nonblock read_nonblock
+       print printf puts gets readlines readline getc
+       readchar ungetc eof eof? << flush
+       sysread syswrite).map!(&:to_sym).each do |m|
+      cls.__send__(:define_method, m) { |*a| @ssl.__send__(m, *a) }
+    end
+
+    # block captures, ugh, but nobody really uses them
+    %w(each each_line each_byte).map!(&:to_sym).each do |m|
+      cls.__send__(:define_method, m) { |*a, &b| @ssl.__send__(m, *a, &b) }
+    end
+  end
+
+  # this is special, called during IO initialization in Ruby
+  def sync
+    defined?(@ssl) ? @ssl.sync : super
+  end
+
   def yahns_init_ssl(ssl_ctx)
     @need_accept = true
     @ssl = OpenSSL::SSL::SSLSocket.new(self, ssl_ctx)
@@ -42,13 +67,8 @@ module Yahns::OpenSSLClient # :nodoc:
     @ssl.read_nonblock(len, buf, exception: false)
   end
 
-  def shutdown(*args)
-    @ssl.shutdown(*args)
-    super # BasicSocket#shutdown
-  end
-
   def close
-    @ssl.close
+    @ssl.close # flushes SSLSocket
     super # IO#close
   end
 end

data/lib/yahns/proxy_http_response.rb

@@ -0,0 +1,293 @@
+# -*- encoding: binary -*-
+# Copyright (C) 2015 all contributors <yahns-public@yhbt.net>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# loaded by yahns/proxy_pass, this relies on Yahns::HttpResponse for
+# constants.
+module Yahns::HttpResponse # :nodoc:
+
+  # write everything in buf to our client socket (or wbuf, if it exists)
+  # it may return a newly-created wbuf or nil
+  def proxy_write(wbuf, buf, alive)
+    unless wbuf
+      # no write buffer, try to write directly to the client socket
+      case rv = String === buf ? kgio_trywrite(buf) : kgio_trywritev(buf)
+      when nil then return # done writing buf, likely
+      when String, Array # partial write, hope the skb grows
+        buf = rv
+      when :wait_writable, :wait_readable
+        wbuf = Yahns::Wbuf.new(nil, alive, self.class.output_buffer_tmpdir, rv)
+        buf = buf.join if Array === buf
+        break
+      end while true
+    end
+
+    wbuf.wbuf_write(self, buf)
+    wbuf.busy ? wbuf : nil
+  end
+
+  def proxy_err_response(code, req_res, exc, wbuf)
+    logger = @hs.env['rack.logger']
+    case exc
+    when nil
+      logger.error('premature upstream EOF')
+    when Kcar::ParserError
+      logger.error("upstream response error: #{exc.message}")
+    else
+      Yahns::Log.exception(logger, 'upstream error', exc)
+    end
+    # try to write something, but don't care if we fail
+    Integer === code and
+      kgio_trywrite("HTTP/1.1 #{CODES[code]}\r\n\r\n") rescue nil
+
+    shutdown rescue nil
+    req_res.shutdown rescue nil
+    nil # signal close of req_res from yahns_step in yahns/proxy_pass.rb
+  ensure
+    wbuf.wbuf_abort if wbuf
+  end
+
+  def wait_on_upstream(req_res, alive, wbuf)
+    req_res.resbuf = wbuf || Yahns::Wbuf.new(nil, alive,
+                                             self.class.output_buffer_tmpdir,
+                                             false)
+    :wait_readable # self remains in :ignore, wait on upstream
+  end
+
+  # returns :wait_readable if we need to read more from req_res
+  # returns :ignore if we yield control to the client(self)
+  # returns nil if completely done
+  def proxy_response_start(res, tip, kcar, req_res)
+    status, headers = res
+    si = status.to_i
+    status = CODES[si] || status
+    env = @hs.env
+    have_body = !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(si) &&
+                env[REQUEST_METHOD] != HEAD
+    flags = MSG_DONTWAIT
+    alive = @hs.next? && self.class.persistent_connections
+
+    res = "HTTP/1.1 #{status}\r\n"
+    headers.each do |key,value| # n.b.: headers is an Array of 2-element Arrays
+      case key
+      when /\A(?:Connection|Keep-Alive)\z/i
+        next # do not let some upstream headers leak through
+      when %r{\AContent-Length\z}i
+        flags |= MSG_MORE if have_body && value.to_i > 0
+      end
+
+      res << "#{key}: #{value}\r\n"
+    end
+
+    # For now, do not add a Date: header, assume upstream already did it
+    # but do not care if they did not
+    res << (alive ? CONN_KA : CONN_CLOSE)
+
+    # send the headers
+    case rv = kgio_syssend(res, flags)
+    when nil then break # all done, likely
+    when String # partial write, highly unlikely
+      flags = MSG_DONTWAIT
+      res = rv # hope the skb grows
+    when :wait_writable, :wait_readable # highly unlikely in real apps
+      wbuf = proxy_write(nil, res, alive)
+      break # keep buffering as much as possible
+    end while true
+
+    rbuf = Thread.current[:yahns_rbuf]
+    tip = tip.empty? ? [] : [ tip ]
+
+    if have_body
+      if len = kcar.body_bytes_left
+
+        case tmp = tip.shift || req_res.kgio_tryread(0x2000, rbuf)
+        when String
+          len = kcar.body_bytes_left -= tmp.size
+          wbuf = proxy_write(wbuf, tmp, alive)
+        when nil # premature EOF
+          return proxy_err_response(nil, req_res, nil, wbuf)
+        when :wait_readable
+          return wait_on_upstream(req_res, alive, wbuf)
+        end until len == 0
+
+      elsif kcar.chunked? # nasty chunked body
+        req_res.proxy_trailers = nil # define to avoid warnings for now
+        buf = ''
+        case tmp = tip.shift || req_res.kgio_tryread(0x2000, rbuf)
+        when String
+          kcar.filter_body(buf, tmp)
+          wbuf = proxy_write(wbuf, chunk_out(buf), alive) unless buf.empty?
+        when nil # premature EOF
+          return proxy_err_response(nil, req_res, nil, wbuf)
+        when :wait_readable
+          return wait_on_upstream(req_res, alive, wbuf)
+        end until kcar.body_eof?
+
+        buf = tmp
+        req_res.proxy_trailers = [ buf, tlr = [] ]
+        rbuf = Thread.current[:yahns_rbuf] = ''
+        until kcar.trailers(tlr, buf)
+          case rv = req_res.kgio_tryread(0x2000, rbuf)
+          when String
+            buf << rv
+          when :wait_readable
+            return wait_on_upstream(req_res, alive, wbuf)
+          when nil # premature EOF
+            return proxy_err_response(nil, req_res, nil, wbuf)
+          end # no loop here
+        end
+        wbuf = proxy_write(wbuf, trailer_out(tlr), alive)
+
+      else # no Content-Length or Transfer-Encoding: chunked, wait on EOF!
+
+        case tmp = tip.shift || req_res.kgio_tryread(0x2000, rbuf)
+        when String
+          wbuf = proxy_write(wbuf, tmp, alive)
+        when nil
+          req_res.shutdown
+          break
+        when :wait_readable
+          return wait_on_upstream(req_res, alive, wbuf)
+        end while true
+
+      end
+    end
+
+    return proxy_busy_mod_done(alive) unless wbuf
+    req_res.resbuf = wbuf
+    proxy_busy_mod_blocked(wbuf, wbuf.busy)
+  rescue => e
+    proxy_err_response(502, req_res, e, wbuf)
+  end
+
+  def proxy_response_finish(kcar, wbuf, req_res)
+    rbuf = Thread.current[:yahns_rbuf]
+    if len = kcar.body_bytes_left
+
+      case tmp = req_res.kgio_tryread(0x2000, rbuf)
+      when String
+        len = kcar.body_bytes_left -= tmp.size
+        wbuf.wbuf_write(self, tmp)
+      when nil # premature EOF
+        return proxy_err_response(nil, req_res, nil, wbuf)
+      when :wait_readable
+        return :wait_readable # self remains in :ignore, wait on upstream
+      end while len != 0
+
+    elsif kcar.chunked? # nasty chunked body
+      buf = ''
+
+      unless req_res.proxy_trailers
+        # are we done dechunking the main body, yet?
+        case tmp = req_res.kgio_tryread(0x2000, rbuf)
+        when String
+          kcar.filter_body(buf, tmp)
+          buf.empty? or wbuf.wbuf_write(self, chunk_out(buf))
+        when nil # premature EOF
+          return proxy_err_response(nil, req_res, nil, wbuf)
+        when :wait_readable
+          return :wait_readable # self remains in :ignore, wait on upstream
+        end until kcar.body_eof?
+        req_res.proxy_trailers = [ tmp, [] ] # onto trailers!
+        rbuf = Thread.current[:yahns_rbuf] = ''
+      end
+
+      buf, tlr = *req_res.proxy_trailers
+      until kcar.trailers(tlr, buf)
+        case rv = req_res.kgio_tryread(0x2000, rbuf)
+        when String
+          buf << rv
+        when :wait_readable
+          return :wait_readable
+        when nil # premature EOF
+          return proxy_err_response(nil, req_res, nil, wbuf)
+        end # no loop here
+      end
+      wbuf.wbuf_write(self, trailer_out(tlr))
+
+    else # no Content-Length or Transfer-Encoding: chunked, wait on EOF!
+
+      case tmp = req_res.kgio_tryread(0x2000, rbuf)
+      when String
+        wbuf.wbuf_write(self, tmp)
+      when nil
+        req_res.shutdown
+        break
+      when :wait_readable
+        return :wait_readable # self remains in :ignore, wait on upstream
+      end while true
+
+    end
+
+    busy = wbuf.busy and return proxy_busy_mod_blocked(wbuf, busy)
+    proxy_busy_mod_done(wbuf.wbuf_persist) # returns nil
+  end
+
+  def proxy_wait_next(qflags)
+    Thread.current[:yahns_fdmap].remember(self)
+    # We must allocate a new, empty request object here to avoid a TOCTTOU
+    # in the following timeline
+    #
+    # original thread:                                 | another thread
+    # HttpClient#yahns_step                            |
+    # r = k.app.call(env = @hs.env)  # socket hijacked into epoll queue
+    # <thread is scheduled away>                       | epoll_wait readiness
+    #                                                  | ReqRes#yahns_step
+    #                                                  | proxy dispatch ...
+    #                                                  | proxy_busy_mod_done
+    # ************************** DANGER BELOW ********************************
+    #                                                  | HttpClient#yahns_step
+    #                                                  | # clears env
+    # sees empty env:                                  |
+    # return :ignore if env.include?('rack.hijack_io') |
+    #
+    # In other words, we cannot touch the original env seen by the
+    # original thread since it must see the 'rack.hijack_io' value
+    # because both are operating in the same Yahns::HttpClient object.
+    # This will happen regardless of GVL existence
+    hs = Unicorn::HttpRequest.new
+    hs.buf.replace(@hs.buf)
+    @hs = hs
+
+    # n.b. we may not touch anything in this object once we call queue_mod,
+    # another thread is likely to take it!
+    Thread.current[:yahns_queue].queue_mod(self, qflags)
+  end
+
+  def proxy_busy_mod_done(alive)
+    case http_response_done(alive)
+    when :wait_readable then proxy_wait_next(Yahns::Queue::QEV_RD)
+    when :wait_writable then proxy_wait_next(Yahns::Queue::QEV_WR)
+    when :close then close
+    end
+
+    nil # close the req_res, too
+  end
+
+  def proxy_busy_mod_blocked(wbuf, busy)
+    q = Thread.current[:yahns_queue]
+    # we are completely done reading and buffering the upstream response,
+    # but have not completely written the response to the client,
+    # yield control to the client socket:
+    @state = wbuf
+    case busy
+    when :wait_readable then q.queue_mod(self, Yahns::Queue::QEV_RD)
+    when :wait_writable then q.queue_mod(self, Yahns::Queue::QEV_WR)
+    else
+      abort "BUG: invalid wbuf.busy: #{busy.inspect}"
+    end
+    # no touching self after queue_mod
+    :ignore
+  end
+
+  # n.b.: we can use String#size for optimized dispatch under YARV instead
+  # of String#bytesize because all the IO read methods return a binary
+  # string when given a maximum read length
+  def chunk_out(buf)
+    [ "#{buf.size.to_s(16)}\r\n", buf, "\r\n".freeze ]
+  end
+
+  def trailer_out(tlr)
+    "0\r\n#{tlr.map! do |k,v| "#{k}: #{v}\r\n" end.join}\r\n"
+  end
+end