proxy_pac_rb 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1965713a0aecec2df86db7b6b214469d6b8b19a3
-  data.tar.gz: d74100e8339ad216ee5ab2d2d06036478e56a59d
+  metadata.gz: af8baea71f58817f9cdb5f272ee6c185562b178f
+  data.tar.gz: 7ead5006f6d5957b9fa9dd1c317d7668daec7e69
 SHA512:
-  metadata.gz: e88fc56a91184d502bbfdaa926ec0baba657051d77b788cabbc3d8ca91c893bdec5edeffb8a5ee07f5d6b2062e1e9e639492a1a866b3ec1a5522ad101d101c01
-  data.tar.gz: 64ce7df70bf552e6f5c8702960a35fb7f2f6ef8aaff9911c4f7d4bd97cb6dc8b446ac3277ff4a193ba3db831eef9f463a90867574425114e73e74a1b8e35923c
+  metadata.gz: fa68a759f58f146e000ed26a9778bccdac7dc31787ec1e101152dab623050ffc211bfb7342347b48ef51ec8b3a26b6dc40323d82811f27852f1e25f06ba2c633
+  data.tar.gz: fc862d9c7899ad8d9bf4c756895df016f3a16990e71d99a758fc5df1b20d15496b3bb036b7fd03859818f5f26b2153e4b494e6f66c4d0f63588a3921bf7426c3

data/.rubocop.yml

@@ -14,6 +14,9 @@ Metrics/LineLength:
 Metrics/ParameterLists:
   Max: 6
 
+Style/CaseEquality:
+  Enabled: false
+
 Metrics/BlockNesting:
   Max: 4
 
@@ -31,9 +34,6 @@ Metrics/MethodLength:
 Metrics/PerceivedComplexity:
   Max: 8
 
-Style/RegexpLiteral:
-  MaxSlashes: 0
-
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 Style/MethodName:
   Exclude:

data/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+In the spirit of [free software][free-sw], **everyone** is encouraged to help
+improve this project.
+
+[free-sw]: http://www.fsf.org/licensing/essays/free-sw.html
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code ( **no patch is too small** : fix typos, add comments, clean up inconsistent whitespace )
+* by refactoring code
+* by closing [issues][]
+* by reviewing patches
+
+[issues]: https://github.com/fedux-org/proxy_pac_rb/issues
+
+## Submitting an Issue
+
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. 
+
+When submitting a bug report, please include a [Gist][] that includes a *stack
+trace* and any details that may be necessary to reproduce the bug, including
+your *gem version*, *Ruby version*, and *operating system*. Ideally, a bug report
+should include a pull request with failing specs.
+
+[gist]: https://gist.github.com/
+
+## Submitting a Pull Request
+
+1. [Fork the repository.][fork]
+2. Create a topic [branch]. `git checkout -b local_topic_branch`
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake test`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake test`. If your specs fail, return to step 5.
+7. Add, commit, and push your changes. To push your topic branch use `git push -u origin local_topic_branch`.
+8. [Submit a pull request.][pr]
+
+Here are some reasons why a pull request may not be merged:
+
+1. It hasn’t been reviewed.
+2. It doesn’t include specs for new functionality.
+3. It doesn’t include documentation for new functionality.
+4. It changes behavior without changing the relevant documentation, comments, or specs.
+5. It changes behavior of an existing public API, breaking backward compatibility.
+6. It breaks the tests on a supported platform.
+7. It doesn’t merge cleanly (requiring Git rebasing and conflict resolution).
+
+Include this emoji in the top of your ticket to signal to us that you read this
+file: :memo:
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: https://help.github.com/articles/fork-a-repo#create-branches
+[pr]: http://help.github.com/send-pull-requests/

data/Gemfile

@@ -9,8 +9,8 @@ group :debug do
 
   gem 'pry-doc', require: false
   gem 'pry-stack_explorer', require: false
-  gem 'pry-exception_explorer', require: false
-  gem 'pry-rescue', require: false
+  # gem 'pry-exception_explorer', require: false
+  # gem 'pry-rescue', require: false
   gem 'pry-byebug', require: false
 end
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    proxy_pac_rb (0.4.1)
+    proxy_pac_rb (0.4.2)
       activesupport
       addressable
       uglifier
@@ -28,7 +28,7 @@ GEM
       debug_inspector (>= 0.0.1)
     blockenspiel (0.4.5)
     builder (3.2.2)
-    byebug (4.0.4)
+    byebug (4.0.5)
       columnize (= 0.9.0)
     childprocess (0.5.5)
       ffi (~> 1.0, >= 1.0.11)
@@ -38,7 +38,7 @@ GEM
       activesupport
       smart_colored
       xml-simple
-    coveralls (0.7.12)
+    coveralls (0.8.0)
       multi_json (~> 1.10)
       rest-client (>= 1.6.8, < 2)
       simplecov (~> 0.9.1)
@@ -61,7 +61,7 @@ GEM
     domain_name (0.5.23)
       unf (>= 0.0.5, < 1.0.0)
     erubis (2.7.0)
-    execjs (2.4.0)
+    execjs (2.5.0)
     fedux_org-stdlib (0.7.33)
       activesupport
     ffi (1.9.8)
@@ -86,7 +86,6 @@ GEM
       sparkr (>= 0.2.0)
       term-ansicolor
       yard (~> 0.8.7.5)
-    interception (0.5)
     json (1.8.2)
     launchy (2.4.3)
       addressable (~> 2.3)
@@ -116,11 +115,6 @@ GEM
     pry-doc (0.6.0)
       pry (~> 0.9)
       yard (~> 0.8)
-    pry-exception_explorer (0.2.3)
-      pry-stack_explorer (>= 0.4.6)
-    pry-rescue (1.4.1)
-      interception (>= 0.5)
-      pry
     pry-stack_explorer (0.4.9.2)
       binding_of_caller (>= 0.7)
       pry (>= 0.9.11)
@@ -150,7 +144,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.2.0)
     rspec-support (3.2.2)
-    rubocop (0.29.1)
+    rubocop (0.30.0)
       astrolabe (~> 1.3)
       parser (>= 2.2.0.1, < 3.0)
       powerpack (~> 0.1)
@@ -196,7 +190,7 @@ GEM
     unf_ext (0.0.6)
     versionomy (0.4.4)
       blockenspiel (>= 0.4.5)
-    webmock (1.20.4)
+    webmock (1.21.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
     xml-simple (1.1.5)
@@ -227,8 +221,6 @@ DEPENDENCIES
   pry
   pry-byebug
   pry-doc
-  pry-exception_explorer
-  pry-rescue
   pry-stack_explorer
   rack
   rack-test

data/README.md

@@ -70,7 +70,7 @@ pprb find proxy -c 127.0.0.1 -t "2014-03-09 12:00:00" -p sample.pac -u https://g
 You can compress a proxy.pac with `pprb` to reduce the amount of data
 transferred to download the proxy.pac.
 
-```
+```bash
 # Download pac
 curl -L -o sample.pac https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample.pac
 
@@ -82,7 +82,7 @@ pprb compress proxy_pac -p sample.pac
 
 You can lint a proxy.pac with `pprb` to check a proxy.pac before deploying it.
 
-```
+```bash
 # Download pac
 curl -L -o sample.pac https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample.pac
 
@@ -90,10 +90,46 @@ curl -L -o sample.pac https://github.com/fedux-org/proxy_pac_rb/raw/master/files
 pprb lint proxy_pac -p sample.pac
 ```
 
-### Rack-based servers
+#### Init new proxy.pac
+
+You can use the following command to start a new proxy.pac:
+
+*Plain*
+
+```bash
+pprb init proxy_pac
+```
+
+*Add rspec*
+
+To test your proxy.pac you can use `rspec`.
+
+```bash
+pprb init proxy_pac --test rspec
 ```
 
-*Warning*
+*Add middleman*
+
+To build your proxy.pac you can use `middleman`.
+
+```bash
+pprb init proxy_pac --build middleman
+```
+
+### "rack"-middleware
+
+The middleware which comes with `proxy_pac_rb` is compliant with the
+`rack`-specification - tested via
+[`rack/lint`](https://github.com/rack/rack/blob/master/lib/rack/lint.rb) and
+should work with every `rack`-compliant-server.
+
+#### Prerequisites
+
+Make sure the content is served with `"Content-Type":
+'application/x-ns-proxy-autoconfig'`. Otherwise the content is ignored by both
+middlewares.
+
+#### Warning
 
 The linter-`rack`-middleware needs to be activated before ANY other
 middleman-extension, `rack`-middleware or whatever framework you are using
@@ -122,18 +158,52 @@ Error
 There were errors during this build
 ```
 
-*Linter Middleware*
+
+#### Linter Middleware
 
 ```ruby
 require 'proxy_pac_rb/rack/proxy_pac_linter'
 use ProxyPacRb::Rack::ProxyPacLinter
 ```
 
-*Compressor Middleware*
+#### Compressor Middleware
 
 ```ruby
 require 'proxy_pac_rb/rack/proxy_pac_compressor'
 use ProxyPacRb::Rack::ProxyPacCompressor
+```
+
+#### Using "rack"-middleware with "middleman"
+
+If you want to use the `rack`-middleware with `middleman` look at the following
+code snippet captured from the `middleman`-configuration file `config.rb`:
+
+* `config.rb`:
+
+  ```ruby
+  # Important needs to come first
+  # See Warning above for a full explanation
+  require 'proxy_pac_rb/rack/proxy_pac_linter'
+  use ProxyPacRb::Rack::ProxyPacLinter
+
+  require 'proxy_pac_rb/rack/proxy_pac_compressor'
+  use ProxyPacRb::Rack::ProxyPacCompressor
+
+  # The middleware works on content served with 
+  # "Content-Type" 'application/x-ns-proxy-autoconfig'
+  page "*.pac", content_type: 'application/x-ns-proxy-autoconfig'
+
+  # This provides an uncompressed copy of the proxy.pac to make it
+  # possible for your support to review it by hand
+  Dir.glob(File.join(source_dir, '**', '*.pac')).each do |f|
+    # Path should be relative to source dir
+    relative_path = Pathname.new(f).relative_path_from(Pathname.new(source_dir))
+
+    # "text/plain" prevents the middlewares to handle it
+    proxy(format('%s.raw', relative_path), relative_path.to_s, content_type: 'text/plain')
+  end
+
+  ```
 
 ### Ruby
 
@@ -142,7 +212,7 @@ use ProxyPacRb::Rack::ProxyPacCompressor
 ```ruby
 require 'proxy_pac_rb'
 
-file = ProxyPacRb::Parser.new.load('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample.pac')
+file = ProxyPacRb::Parser.new.parse('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample.pac')
 file.find('https://github.com')        # => "DIRECT"
 ```
 
@@ -155,7 +225,7 @@ curl -L -o sample.pac https://github.com/fedux-org/proxy_pac_rb/raw/master/files
 ```ruby
 require 'proxy_pac_rb'
 
-file = ProxyPacRb::Parser.new.read("sample.pac")
+file = ProxyPacRb::Parser.new.parse("sample.pac")
 file.find('https://github.com')        # => "DIRECT"
 ```
 
@@ -164,7 +234,7 @@ file.find('https://github.com')        # => "DIRECT"
 ```ruby
 require 'proxy_pac_rb'
 
-file = ProxyPacRb::Parser.new.source <<-JS
+file = ProxyPacRb::Parser.new.parse <<-JS
   function FindProxyForURL(url, host) {
     return "DIRECT";
   }
@@ -179,11 +249,11 @@ file.find('http://localhost') # => "DIRECT"
 require 'proxy_pac_rb'
 
 environment = ProxyPacRb::Environment.new(client_ip: '127.0.0.1')
-file = ProxyPacRb::Parser.new(environment).load('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample2.pac')
+file = ProxyPacRb::Parser.new(environment).parse('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample2.pac')
 file.find('https://github.com')        # => "PROXY localhost:8080"
 
 environment = ProxyPacRb::Environment.new(client_ip: '127.0.0.2')
-file = ProxyPacRb::Parser.new(environment).load('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample2.pac')
+file = ProxyPacRb::Parser.new(environment).parse('https://github.com/fedux-org/proxy_pac_rb/raw/master/files/sample2.pac')
 file.find('https://github.com')        # => "DIRECT"
 ```
 
@@ -203,11 +273,11 @@ function FindProxyForURL(url, host) {
 EOS
 
 environment = ProxyPacRb::Environment.new(time: Time.parse('2014-07-06 12:00'))
-file = ProxyPacRb::Parser.new(environment).source(string)
+file = ProxyPacRb::Parser.new(environment).parse(string)
 file.find('http://localhost') # => 'PROXY localhost:8080'
 
 environment = ProxyPacRb::Environment.new(time: Time.parse('2014-03-08 6:00'))
-file = ProxyPacRb::Parser.new(environment).source(string)
+file = ProxyPacRb::Parser.new(environment).parse(string)
 file.find('http://localhost') # => 'DIRECT'
 ```
 
@@ -227,11 +297,246 @@ file.find('http://localhost') # => 'DIRECT'
 * timeRange(*args)
 * alert(msg) (output on stderr by default)
 
+## RSpec-integration
+
+`proxy_pac_rb` comes with helpers and matchers for `rspec`. To make those
+helpers and matchers available in your project, add this code snippet in your
+project:
+
+```
+require 'proxy_pac_rb/rspec'
+```
+
+### Helpers
+
+* `proxy_pac`:
+
+    This helper makes a proxy.pac available. It requires a source for your
+    proxy.pac given in `subject { }` - e.g. a file, a string, or a url. It
+    represents a [`ProxyPacFile`](lib/proxy_pac_rb/proxy_pac_file.rb).
+
+* `time`:
+
+    The `time`-helper makes `1970-01-01 00:00:00` as time available. Overwrite
+    this helper at will with another time string or a time-object - e.g
+    `let(:time) { Time.now }`.
+
+* `client_ip`:
+
+    The `client_ip`-helper makes `127.0.0.1` available. Overwrite it with a
+    different ip-address as string or an object which returns an ip-address on
+    `#to_s`.
+
+* `root_path`:
+
+    The `root_path`-helper is meant for overriding. It is used to find your
+    "proxy.pac"-files. By default its value is `Dir.getwd` which is set by
+    `rspec`.
+
+### Examples
+
+To make it easier for you to start, you find some examples below.
+
+**Type for specs**
+
+It is important that you flag your specs with `type: :proxy_pac`. Otherwise the
+helpers are not included and not available in your examples.
+
+```ruby
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+```
+
+**Supported sources**
+
+*String*
+
+```ruby
+RSpec.describe 'String', type: :proxy_pac do
+  subject do
+    <<-EOS.strip_heredoc.chomp
+      function FindProxyForURL(url, host) {
+        return "DIRECT";
+      }
+    EOS
+  end
+end
+```
+
+*Local File*
+
+```ruby
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  subject { 'proxy.pac' }
+end
+```
+
+*URL*
+
+```ruby
+RSpec.describe 'http://server/proxy.pac', type: :proxy_pac do
+  subject { 'http://server/proxy.pac' }
+end
+```
+
+**Matchers**
+
+*Readable*
+
+To check if a proxy.pac could be read from filesystem or downloaded via HTTP,
+check `be_readable`.
+
+```ruby
+require 'proxy_pac_rb/rspec'
+
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  context 'when proxy pac exist' do
+    context 'when is file' do
+      subject { 'proxy.pac' }
+      it { expect(proxy_pac).to be_readable }
+    end
+
+    context 'when is url' do
+      subject { 'http://www.example.com/proxy.pac' }
+      it { expect(proxy_pac).to be_readable }
+    end
+  end
+end
+```
+
+*Equal*
+
+If you want to check if a proxy.pac is the same you can use the
+`be_the_same_proxy_pac_file`-matcher.
+
+```ruby
+require 'proxy_pac_rb/rspec'
+
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  subject do
+    <<-EOS.strip_heredoc.chomp
+      function FindProxyForURL(url, host) {
+        return "DIRECT";
+      }
+    EOS
+  end
+  context 'Check equality of proxy pac' do
+    context 'when proxy.pac is eq' do
+      it { expect(proxy_pac).to be_the_same_proxy_pac_file 'proxy.pac' }
+    end
+
+    context 'when proxy.pac is not eq' do
+      it { expect(proxy_pac).not_to be_the_same_proxy_pac_file 'proxy.pac' }
+    end
+  end
+end
+```
+
+This is quite handy to compare a local proxy.pac with a remote one - e.g. a
+deployed one.
+
+```ruby
+require 'proxy_pac_rb/rspec'
+
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  let(:local_proxy_pac) { ProxyPacRb::ProxyPacFile.new(source: file) }
+
+  before(:each) do
+    ProxyPacRb::ProxyPacLoader.new.load(local_proxy_pac)
+    ProxyPacRb::ProxyPacCompressor.new.compress(local_proxy_pac) if local_proxy_pac.readable?
+  end
+
+  context 'when no proxy.pac is given' do
+    subject { 'http://server.example.com/proxy.pac' }
+    let(:file) { 'source/proxy.pac' }
+
+    it { expect(proxy_pac).to be_the_same_proxy_pac_file(local_proxy_pac) }
+  end
+end
+```
+
+*Valid*
+
+You want to check if your proxy.pac is valid. This will find `reference errors`
+(e.g. unknown variables) and `syntax errors`.
+
+```ruby
+require 'proxy_pac_rb/rspec'
+
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  subject do
+    <<-EOS.strip_heredoc.chomp
+      function FindProxyForURL(url, host) {
+        return "DIRECT";
+      }
+    EOS
+  end
+  context 'Check validity of proxy pac' do
+    context 'when proxy.pac is valid' do
+      it { expect(proxy_pac).to be_valid }
+    end
+
+    context 'when proxy.pac is not valid' do
+      subject do
+        <<-EOS.strip_heredoc.chomp
+          function FindProxyForURL(url, host) {
+            return adsf;
+          }
+        EOS
+      end
+      it { expect(proxy_pac).not_to be_valid }
+    end
+  end
+end
+```
+
+*Parse proxy.pac*
+
+To make some logic checks use the `be_downloaded_via`-matcher. This will parse
+the proxy.pac and returns the proxy to be used for a given url.
+
+```ruby
+require 'proxy_pac_rb/rspec'
+RSpec.describe 'proxy.pac', type: :proxy_pac do
+  subject do
+    <<-EOS.strip_heredoc.chomp
+      function FindProxyForURL(url, host) {
+        if (dnsDomainIs(host, 'www1.example.com'')) {
+          return "PROXY proxy1.example.com:8080";
+        } else {
+          return "PROXY proxy2.example.net:8080";
+        }
+      }
+    EOS
+  end
+  context 'Parse Proxy Pac' do
+    context 'when url is forwarded via' do
+      let(:url) { 'http://www1.example.com' }
+      it { expect(url).to be_downloaded_via 'PROXY proxy.example.com:8080' }
+    end
+
+    context 'when url is not forwarded via' do
+      let(:url) { 'http://www2.example.com' }
+      it { expect(url).not_to be_downloaded_via 'PROXY proxy.example.com:8080' }
+    end
+  end
+end
+```
+
 ## Developers
 
+After checking out the repo, run `script/bootstrap` to install dependencies. Then, run
+`script/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake gem:install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake gem:release` to create a git tag for the version, push git
+commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
 ### Contributing
 
-If you want to contribute: fork, branch & pull request.
+If you want to contribute: fork, branch & pull request and please see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ### Running Tests