forward-proxy 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6af22f5d41a5a3b702233f8a13b67533451a411b
-  data.tar.gz: 850669c9081a84975689e17d0e92b6b9adb5f29a
+SHA256:
+  metadata.gz: 628359d25536c4190014c9e082fff41b2adef209f04a62d8a6b217c078f3b58b
+  data.tar.gz: 7834932b7242fd66c120d270a922e385a6a58ab63c65e8ce2b7957da43ba5a11
 SHA512:
-  metadata.gz: 0eba287e90bd3369421aa16401b2958203058047900f1b496e5c690bb15b5b58c018340118a76d18a39c3dcb054f5b034b2a5c3c6a94bc1a95a71b1f5ace78fd
-  data.tar.gz: c71b4cb6d19cdf9e9bad3605b03d4a8d2cc73933bb3b575ddf3be75d4408d266627dc97421b50c71578ede837a24417d00f243e5ad05cabebbd1c21c2d3a2d4f
+  metadata.gz: 8c47ab1d691807a23ba779f1ae8d4feecd32300f8d840044f66a5cc2f40ccd33c095db60ca9e3f99fb3c8fd60c02ae46d5d8d07b6a4de6298bef24731fb57cb4
+  data.tar.gz: 609a35651496d98e4977f3691c7834efd58fe736615b3b4594e0bc61d11dad0088f11f535f6b287db85f95c1cc8ab55ea2a536447028b690d92ffd0aa3e60669

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

@@ -0,0 +1,26 @@
+# 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.
+
+## 0.1.2
+
+- Wrap ThreadPool in ForwardProxy module.

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

@@ -1,6 +1,8 @@
 # ForwardProxy
 
-Ruby Forward Proxy implemented with only standard libraries.
+![Gem Version][3] ![Gem][1] ![Build Status][2]
+
+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
@@ -35,9 +37,9 @@ forward-proxy
 ```
 Usage: forward-proxy [options]
     -p, --port=PORT                  Bind to specified port. Default: 9292
-    -b, --binding=BINDING            Bind to the specified IP. Default: 127.0.0.1
+    -b, --binding=BINDING            Bind to the specified ip. Default: 127.0.0.1
     -t, --threads=THREADS            Specify the number of client threads. Default: 32
-    -h, --help                       Prints this help
+    -h, --help                       Prints this help.
 ```
 
 ### Library
@@ -70,3 +72,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the ForwardProxy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jamesmoriarty/forward-proxy/blob/master/CODE_OF_CONDUCT.md).
+
+[1]: https://img.shields.io/gem/dt/forward-proxy
+[2]: https://github.com/jamesmoriarty/forward-proxy/workflows/Continuous%20Integration/badge.svg?branch=main
+[3]: https://img.shields.io/gem/v/forward-proxy

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,11 +7,11 @@ 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
 
-  parser.on("-bBINDING", "--binding=BINDING", String, "Bind to the specified IP. Default: 127.0.0.1") do |bind_address|
+  parser.on("-bBINDING", "--binding=BINDING", String, "Bind to the specified ip. Default: 127.0.0.1") do |bind_address|
     options[:bind_address] = bind_address
   end
 
@@ -19,13 +19,12 @@ OptionParser.new do |parser|
     options[:threads] = threads
   end
 
-  parser.on("-h", "--help", "Prints this help") do
+  parser.on("-h", "--help", "Prints this help.") do
     puts parser
     exit
   end
 end.parse!
 
 require_relative '../lib/forward_proxy'
-
 server = ForwardProxy::Server.new(options)
 server.start

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,11 +1,11 @@
-require 'forward_proxy/thread_pool'
 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
 
@@ -16,16 +16,14 @@ module ForwardProxy
     end
 
     def start
-      @server = TCPServer.new(bind_address, bind_port)
-
       thread_pool.start
 
+      @socket = TCPServer.new(bind_address, bind_port)
+
       log("Listening #{bind_address}:#{bind_port}")
 
       loop do
-        client = server.accept
-
-        thread_pool.schedule(client) do |client_conn|
+        thread_pool.schedule(socket.accept) do |client_conn|
           begin
             req = parse_req(client_conn)
 
@@ -35,11 +33,12 @@ module ForwardProxy
             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
+              Via: #{HEADER_VIA}
             eos
 
             puts e.message
@@ -50,24 +49,38 @@ module ForwardProxy
         end
       end
     rescue Interrupt
+      shutdown
+    rescue IOError, Errno::EBADF => e
+      log(e.message, "ERROR")
     end
 
     def shutdown
-      log("Closing client connections...")
-      thread_pool.shutdown
+      if socket
+        log("Shutting down")
 
-      log("Stoping server...")
-      server.close if server
+        socket.close 
+      end
     end
 
     private
 
-    attr_reader :server, :thread_pool
+    attr_reader :socket, :thread_pool
 
     METHOD_CONNECT = "CONNECT"
     METHOD_GET = "GET"
     METHOD_POST = "POST"
 
+    # 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"
@@ -104,22 +117,25 @@ 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|
+          client_conn.puts <<~eos.chomp
+            HTTP/1.1 #{resp.code}
+            Via: #{[HEADER_VIA, resp['Via']].compact.join(', ')}
+            #{resp.each.map { |header, value| "#{header}: #{value}" }.join("\n")}\n\n
+          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
-
-      # 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.
-      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}
-      eos
     end
 
     def map_webrick_to_net_http_req(req)
@@ -129,13 +145,13 @@ 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")
@@ -145,6 +161,8 @@ module ForwardProxy
       WEBrick::HTTPRequest.new(WEBrick::Config::HTTP).tap do |req|
         req.parse(client_conn)
       end
+    rescue => e
+      throw Errors::HTTPParseError.new(e.message)
     end
 
     def log(str, level = 'INFO')

data/lib/forward_proxy/thread_pool.rb

@@ -1,34 +1,36 @@
-class ThreadPool
-  attr_reader :queue, :threads, :size
+module ForwardProxy
+  class ThreadPool
+    attr_reader :queue, :threads, :size
 
-  def initialize(size)
-    @size    = size
-    @queue   = Queue.new
-    @threads = []
-  end
+    def initialize(size)
+      @size    = size
+      @queue   = Queue.new
+      @threads = []
+    end
 
-  def start
-    size.times do
-      threads << Thread.new do
-        catch(:exit) do
-          loop do
-            job, args = queue.pop
-            job.call(*args)
+    def start
+      size.times do
+        threads << Thread.new do
+          catch(:exit) do
+            loop do
+              job, args = queue.pop
+              job.call(*args)
+            end
           end
         end
       end
     end
-  end
-
-  def schedule(*args, &block)
-    queue.push([block, args])
-  end
 
-  def shutdown
-    threads.each do
-      schedule { throw :exit }
+    def schedule(*args, &block)
+      queue.push([block, args])
     end
 
-    threads.each(&:join)
+    def shutdown
+      threads.each do
+        schedule { throw :exit }
+      end
+
+      threads.each(&:join)
+    end
   end
 end

data/lib/forward_proxy/version.rb

@@ -1,3 +1,3 @@
 module ForwardProxy
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: forward-proxy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - James Moriarty
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-01-14 00:00:00.000000000 Z
+date: 2021-05-06 00:00:00.000000000 Z
 dependencies: []
 description: Forward proxy using just Ruby standard libraries.
 email:
@@ -19,7 +19,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yaml"
+- ".github/workflows/cli.yaml"
 - ".gitignore"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -30,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
@@ -55,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.