forward-proxy 0.1.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3f624058897845408afede390c49b3048ee7a74f
-  data.tar.gz: d2a90df621baefdecc61bba48a44bfdee2180766
+SHA256:
+  metadata.gz: 1d2b9dbd7abcfa81bcdbd29b6dd2045e6d2210e92b303f7cfcdc4ab35ab0b868
+  data.tar.gz: 729d4b7d964c8a5a3bec860f6bceb669a12225900a01b4737de8fdf6ba02a049
 SHA512:
-  metadata.gz: 76d5bffc4db996cdc9578baa97cef6e13eb519cc065a0856cf83724470b27beaf6819b66aaddaf10bc21b1053b269635623ed5b4e9e0f13dff561bc044c7313d
-  data.tar.gz: e085eba75e664a72575920750045ef62334cc0e3c64c72daddc5db5bf571656fb395790c6cb5d0a32bd3b3320fdeb2e0ce50705d59e3a2da0844628ae9b37148
+  metadata.gz: 70c0b51f0313e4ffedd1146ae93035db45bc8fe3a7cee647ea11cb0397d6862e99047befbc39aee6a08b17fd1e3d16394eb59ad9ad092140ea9354da10feadf6
+  data.tar.gz: b0f3587f3c08b255be222f8f59530e19b5fcc6e589f93eafb1eaa21fac832a0f01847dfcf309ed443e51fdafd96a516241143c1a75795b3d09f0ce7088eedac0

data/.github/workflows/cli.yaml

@@ -0,0 +1,25 @@
+name: Command Line Interface
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby: [ '2.3', '2.7' ]
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: gem install forward-proxy
+    - run: |
+        exe/forward-proxy --h
+        exe/forward-proxy --help
+        exe/forward-proxy --binding 127.0.0.1 --port 3001 --threads 2 &
+        sleep 1
+        curl --fail -x http://127.0.0.1:3001 https://google.com/

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## 0.2.0
+
+- Extract errors into module.
+
+## 0.1.5
+
+- stream http proxy requests.
+- call shutdown on `Interrupt`
+- remove waiting for the thread-pool to finish on shutdown and just close the server conn.
+
+## 0.1.4
+
+- `accept` connections via thread pool.
+- catch and throw custom http parse error.
+- `Server:` header added for default error 502 response.
+- rescue and logs socket error `Errno::EBADF`.
+
 ## 0.1.3
 
 - Refine CLI help text.

data/Gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 12.0"
+gem "yard", "~> 0.9"
 gem "minitest", "~> 5.0"
 gem "minitest-reporters", "~> 1.4"
 gem "simplecov", "~> 0.17"

data/README.md

@@ -2,7 +2,7 @@
 
 ![Gem Version][3] ![Gem][1] ![Build Status][2]
 
-Ruby Forward Proxy implemented with only standard libraries.
+Minimal forward proxy using 150LOC and only standard libraries. Useful for development, testing, and learning.
 
 ```
 $ forward-proxy --binding 0.0.0.0 --port 3182 --threads 2

data/Rakefile

@@ -1,5 +1,12 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb', 'README', 'CHANGELOG', 'CODE_OF_CONDUCT']
+  t.options = []
+  t.stats_options = ['--list-undoc']
+end
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -7,4 +14,16 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+namespace :gh do
+  desc "Deploy yard docs to github pages"
+  task :pages => :yard do
+    `git add -f doc`
+    `git commit -am "update: $(date)"`
+    `git subtree split --prefix doc -b gh-pages`
+    `git push -f origin gh-pages:gh-pages`
+    `git branch -D gh-pages`
+    `git reset head~1`
+  end
+end
+
 task :default => :test

data/exe/forward-proxy

@@ -7,7 +7,7 @@ options = {}
 OptionParser.new do |parser|
   parser.banner = "Usage: forward-proxy [options]"
 
-  parser.on("-pPORT", "--port=PORT", "Bind to specified port. Default: 9292", String) do |bind_port|
+  parser.on("-pPORT", "--port=PORT", String, "Bind to specified port. Default: 9292") do |bind_port|
     options[:bind_port] = bind_port
   end
 
@@ -26,6 +26,5 @@ OptionParser.new do |parser|
 end.parse!
 
 require_relative '../lib/forward_proxy'
-
 server = ForwardProxy::Server.new(options)
 server.start

data/lib/forward_proxy.rb

@@ -1,4 +1,4 @@
-$:.unshift File.dirname(__FILE__)
+$LOAD_PATH.unshift File.dirname(__FILE__)
 
 require 'forward_proxy/version'
 require 'forward_proxy/server'

data/lib/forward_proxy/errors/http_method_not_implemented.rb

@@ -0,0 +1,5 @@
+module ForwardProxy
+  module Errors
+    class HTTPMethodNotImplemented < StandardError; end
+  end
+end

data/lib/forward_proxy/errors/http_parse_error.rb

@@ -0,0 +1,5 @@
+module ForwardProxy
+  module Errors
+    class HTTPParseError < StandardError; end
+  end
+end

data/lib/forward_proxy/server.rb

@@ -1,73 +1,90 @@
-require 'forward_proxy/thread_pool'
+require 'logger'
 require 'socket'
 require 'webrick'
 require 'net/http'
+require 'forward_proxy/errors/http_method_not_implemented'
+require 'forward_proxy/errors/http_parse_error'
+require 'forward_proxy/thread_pool'
 
 module ForwardProxy
-  class HTTPMethodNotImplemented < StandardError; end
-
   class Server
-    attr_reader :bind_address, :bind_port
+    attr_reader :bind_address, :bind_port, :logger
 
-    def initialize(bind_address: "127.0.0.1", bind_port: 9292, threads: 32)
+    def initialize(bind_address: "127.0.0.1", bind_port: 9292, threads: 32, logger: Logger.new(STDOUT, level: :info))
+      @logger = logger
       @thread_pool = ThreadPool.new(threads)
       @bind_address = bind_address
       @bind_port = bind_port
     end
 
     def start
-      @server = TCPServer.new(bind_address, bind_port)
-
       thread_pool.start
 
-      log("Listening #{bind_address}:#{bind_port}")
+      @socket = TCPServer.new(bind_address, bind_port)
 
-      loop do
-        client = server.accept
+      logger.info("Listening #{bind_address}:#{bind_port}")
 
-        thread_pool.schedule(client) do |client_conn|
+      loop do
+        thread_pool.schedule(socket.accept) do |client_conn|
           begin
             req = parse_req(client_conn)
 
-            log(req.request_line)
+            logger.info(req.request_line)
 
             case req.request_method
             when METHOD_CONNECT then handle_tunnel(client_conn, req)
             when METHOD_GET, METHOD_POST then handle(client_conn, req)
             else
-              raise HTTPMethodNotImplemented
+              raise Errors::HTTPMethodNotImplemented
             end
-          rescue => e
-            client_conn.puts <<~eos.chomp
-              HTTP/1.1 502
-            eos
-
-            puts e.message
-            puts e.backtrace.map { |line| "  #{line}" }
+          rescue => err
+            handle_error(err, client_conn)
           ensure
             client_conn.close
           end
         end
       end
     rescue Interrupt
+      shutdown
+    rescue IOError, Errno::EBADF => e
+      logger.error(e.message)
     end
 
     def shutdown
-      log("Closing client connections...")
-      thread_pool.shutdown
+      if socket
+        logger.info("Shutting down")
 
-      log("Stoping server...")
-      server.close if server
+        socket.close
+      end
     end
 
     private
 
-    attr_reader :server, :thread_pool
+    attr_reader :socket, :thread_pool
+
+    # The following comments are from the IETF document
+    # "Hypertext Transfer Protocol -- HTTP/1.1: Basic Rules"
+    # https://datatracker.ietf.org/doc/html/rfc2616#section-2.2
 
     METHOD_CONNECT = "CONNECT"
     METHOD_GET = "GET"
     METHOD_POST = "POST"
 
+    # HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
+    # protocol elements except the entity-body.
+    HEADER_EOP = "\r\n"
+
+    # The following comments are from the IETF document
+    # "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"
+    # https://tools.ietf.org/html/rfc7231#section-4.3.6
+
+    # A proxy MUST send an appropriate Via header field, as described
+    # below, in each message that it forwards.  An HTTP-to-HTTP gateway
+    # MUST send an appropriate Via header field in each inbound request
+    # message and MAY send a Via header field in forwarded response
+    # messages.
+    HEADER_VIA = "HTTP/1.1 ForwardProxy"
+
     def handle_tunnel(client_conn, req)
       # The following comments are from the IETF document
       # "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"
@@ -89,7 +106,10 @@ module ForwardProxy
       # blank line that concludes the successful response's header section;
       # data received after that blank line is from the server identified by
       # the request-target.
-      client_conn.write "HTTP/1.1 200 OK\n\n"
+      client_conn.write <<~eos.chomp
+        HTTP/1.1 200 OK
+        #{HEADER_EOP}
+      eos
 
       # The CONNECT method requests that the recipient establish a tunnel to
       # the destination origin server identified by the request-target and,
@@ -104,22 +124,57 @@ module ForwardProxy
     end
 
     def handle(client_conn, req)
-      resp = Net::HTTP.start(req.host, req.port) do |http|
-        http.request map_webrick_to_net_http_req(req)
+      Net::HTTP.start(req.host, req.port) do |http|
+        http.request(map_webrick_to_net_http_req(req)) do |resp|
+          # The following comments are from the IETF document
+          # "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"
+          # https://tools.ietf.org/html/rfc7231#section-4.3.6
+
+          #  An intermediary MAY combine an ordered subsequence of Via header
+          #  field entries into a single such entry if the entries have identical
+          #  received-protocol values.  For example,
+          #
+          #    Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
+          #
+          #  could be collapsed to
+          #
+          #    Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
+          #
+          #  A sender SHOULD NOT combine multiple entries unless they are all
+          #  under the same organizational control and the hosts have already been
+          #  replaced by pseudonyms.  A sender MUST NOT combine entries that have
+          #  different received-protocol values.
+          headers = resp.to_hash.merge(Via: [HEADER_VIA, resp['Via']].compact.join(', '))
+
+          client_conn.puts <<~eos.chomp
+            HTTP/1.1 #{resp.code}
+            #{headers.map { |header, value| "#{header}: #{value}" }.join("\n")}
+            #{HEADER_EOP}
+          eos
+
+          # The following comments are taken from:
+          # https://docs.ruby-lang.org/en/2.0.0/Net/HTTP.html#class-Net::HTTP-label-Streaming+Response+Bodies
+
+          # By default Net::HTTP reads an entire response into memory. If you are
+          # handling large files or wish to implement a progress bar you can
+          # instead stream the body directly to an IO.
+          resp.read_body do |chunk|
+            client_conn << chunk
+          end
+        end
       end
+    end
 
-      # A proxy MUST send an appropriate Via header field, as described
-      # below, in each message that it forwards.  An HTTP-to-HTTP gateway
-      # MUST send an appropriate Via header field in each inbound request
-      # message and MAY send a Via header field in forwarded response
-      # messages.
+    def handle_error(err, client_conn)
       client_conn.puts <<~eos.chomp
-        HTTP/1.1 #{resp.code}
-        Via: #{["1.1 ForwardProxy", resp['Via']].compact.join(', ')}
-        #{resp.each.map { |header, value| "#{header}: #{value}" }.join("\n")}
-
-        #{resp.body}
+        HTTP/1.1 502
+        Via: #{HEADER_VIA}
+        #{HEADER_EOP}
       eos
+
+      logger.error(err.message)
+
+      logger.debug(err.backtrace.join("\n"))
     end
 
     def map_webrick_to_net_http_req(req)
@@ -129,26 +184,24 @@ module ForwardProxy
               when METHOD_GET then Net::HTTP::Get
               when METHOD_POST then Net::HTTP::Post
               else
-                raise HTTPMethodNotImplemented
+                raise Errors::HTTPMethodNotImplemented
               end
 
       klass.new(req.path, req_headers)
     end
 
-    def transfer(dest_conn, src_conn)
+    def transfer(src_conn, dest_conn)
       IO.copy_stream(src_conn, dest_conn)
     rescue => e
-      log(e.message, "WARNING")
+      logger.warn(e.message)
     end
 
     def parse_req(client_conn)
       WEBrick::HTTPRequest.new(WEBrick::Config::HTTP).tap do |req|
         req.parse(client_conn)
       end
-    end
-
-    def log(str, level = 'INFO')
-      puts "[#{Time.now}] #{level} #{str}"
+    rescue => e
+      throw Errors::HTTPParseError.new(e.message)
     end
   end
 end

data/lib/forward_proxy/version.rb

@@ -1,3 +1,3 @@
 module ForwardProxy
-  VERSION = "0.1.3"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: forward-proxy
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.4.0
 platform: ruby
 authors:
 - James Moriarty
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-01-14 00:00:00.000000000 Z
+date: 2021-07-04 00:00:00.000000000 Z
 dependencies: []
 description: Forward proxy using just Ruby standard libraries.
 email:
@@ -19,6 +19,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yaml"
+- ".github/workflows/cli.yaml"
 - ".gitignore"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -31,6 +32,8 @@ files:
 - exe/forward-proxy
 - forward-proxy.gemspec
 - lib/forward_proxy.rb
+- lib/forward_proxy/errors/http_method_not_implemented.rb
+- lib/forward_proxy/errors/http_parse_error.rb
 - lib/forward_proxy/server.rb
 - lib/forward_proxy/thread_pool.rb
 - lib/forward_proxy/version.rb
@@ -56,8 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Forward proxy.