icaprb-server 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c29df2175284d6033e5651bfa7cd4c31b4b22a8b
+  data.tar.gz: eb49631c989580e438dbe18a8f8b64e2f2e5121c
+SHA512:
+  metadata.gz: c9172a8ea5df5842fab74ed6d2b21ad1b72380882d36b8d1602ca0ec50655c576b89fad64ba6fe061dcfc7554a13c23c43e9d0f5a0fb769f18c63f0d563ce5f1
+  data.tar.gz: 6d8f06a8a04715fe4f3469ae060fe9975694119c5c5914b328b39bb7e3cdc731ab35238c2d0486ef9dee6e83a85ea78e1326aa8417f208c73c913772ce880f93

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/html/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in icaprb-server.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2016, Fabian Franz
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.md

@@ -0,0 +1,50 @@
+# ICAPrb::Server
+
+Welcome to my projekt. I tried to implement the server part of the ICAP communication in [Ruby](https://www.ruby-lang.org/de/),
+so the server configuration can load different things and the code may be changed at runtime (for example if you want a high uptime).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'icaprb-server'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install icaprb-server
+
+## Usage
+
+Getting your server running is really easy:
+
+```ruby
+# require it
+require "icaprb/server"
+
+# create an instance of a server
+s = ICAPrb::Server::ICAPServer.new
+
+# add your services
+s.services['echo'] = ICAPrb::Server::Services::EchoService.new
+
+# and run it
+s.run
+
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fabianfrz/ICAPrb-Server, however I may not have enough time to provide fixes soon.
+

data/README.rdoc

@@ -0,0 +1,34 @@
+Welcome to my ICAP server
+=========================
+
+This server has been written as a semester project by Fabian Franz.
+It is fully written in ruby, so it should run on any implementation of ruby in any version >= 2.0.0.
+
+It is really easy to use it and create your own ICAP service and make it available for your proxy.
+
+First of all you need an instance of ICAPrb::Server::ICAPServer, which does not need any parameters but can take a
+hostname and a port, as well as some options which are requred for setting up logging or TLS.
+The default is localhost on port 1344 which usually results in a binding of [::1]:1344 as IPv6
+is preferred on modern systems.
+
+When you created your server, you will have to add some +services+ by writing an instance of them in the services
+property of the server, with the name as key.
+
+When all your services are added to the server, you can simply start it by calling the "run" method.
+Note, that run will +block+ the process and will run until the process is interrupted (for example by pressing ctrl + c).
+
+---
+
+You can write your own services by extending the ServiceBase class which is in ICAPrb::Server::Services.
+Please look at the documentation of this class or just copy the EchoService and use it as a base for your own service.
+
+---
+
+Note: ICAP is a mighty tool and it can do good and evil things.
+It could be illegal to use this kind of software in your country.
+You are encuraged to check if this software and the services running on it are legal
+and don't use this software in case it is not.
+
+---
+
+If you want to know more about ICAP, you should read the RFC 3507.

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
+end
+
+desc 'search for undocumented things'
+task :not_documented do
+  sh 'rdoc --dry-run -V 2> /dev/null | grep "(undocumented)" | sed -E "s/^\\s+//g"'
+end
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "icaprb/server"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+include ICAPrb::Server
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/start_server.rb

@@ -0,0 +1,36 @@
+#
+require "bundler/setup"
+require "icaprb/server"
+require 'logger'
+include ICAPrb::Server
+
+trap('SIGINT') { exit! 0 }
+########################################################################
+#                  DIFFERENT WAYS TO RUN THE SERVER                    #
+########################################################################
+
+# normal socket
+#s = ICAPServer.new
+# puts 'Server is running on port 1344. Press CTRL+C to exit...'
+
+# squid v4 variant
+#options = {secure: true,
+#          certificate: '../cert.pem',
+#          key: '../key.pem',
+#          tls_socket: true}
+#s = ICAPServer.new('localhost',11344,options)
+# puts 'Server is running on port 11344. Press CTRL+C to exit...'
+
+# rfc 3507 variant
+options = {secure: true,
+           certificate: '../cert.pem',
+           key: '../key.pem',
+           tls_socket: false}
+s = ICAPServer.new('localhost',1344,options)
+puts 'Server is running on port 1344. Press CTRL+C to exit...'
+
+########################################################################
+s.logger.level = Logger::INFO
+s.services['echo'] = Services::EchoService.new
+
+s.run

data/icaprb-server.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'icaprb/server/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "icaprb-server"
+  spec.version       = ICAPrb::Server::VERSION
+  spec.authors       = ["Fabian Franz"]
+  spec.email         = ["fabian.franz@students.fh-hagenberg.at"]
+
+  spec.summary       = %q{This project includes an ICAP server fully implemented in Ruby but it does not include services.}
+  spec.homepage      = "https://github.com/fabianfrz/ICAPrb-Server"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/icaprb/icapuri.rb

@@ -0,0 +1,24 @@
+# = icaprb/server/icapuri.rb
+# Author:: Fabian Franz
+#
+# See URI for general documentation
+#
+
+require 'uri/generic'
+
+module URI #:nodoc:
+
+  # Class to represent ICAP URIs
+  class ICAP < Generic
+    # The ICAP default port is 1344
+    DEFAULT_PORT = 1344
+  end
+  # Class to represent ICAP URIs
+  class ICAPS < Generic
+    # The ICAP default port is 11344
+    DEFAULT_PORT = 11344
+  end
+
+  @@schemes['ICAP'] = ICAP
+  @@schemes['ICAPS'] = ICAPS
+end

data/lib/icaprb/server/constants.rb

@@ -0,0 +1,83 @@
+module ICAPrb
+  module Server
+    # Status Codes by IANA / RFC for HTTP
+    HTTP_STATUS_CODES =
+        {100=>'Continue',
+         101=>'Switching Protocols',
+         102=>'Processing',
+         200=>'OK',
+         201=>'Created',
+         202=>'Accepted',
+         203=>'Non-Authoritative Information',
+         204=>'No Content',
+         205=>'Reset Content',
+         206=>'Partial Content',
+         207=>'Multi-Status',
+         208=>'Already Reported',
+         226=>'IM Used',
+         300=>'Multiple Choices',
+         301=>'Moved Permanently',
+         302=>'Found',
+         303=>'See Other',
+         304=>'Not Modified',
+         305=>'Use Proxy',
+         306=>'Unused',
+         307=>'Temporary Redirect',
+         308=>'Permanent Redirect',
+         400=>'Bad Request',
+         401=>'Unauthorized',
+         402=>'Payment Required',
+         403=>'Forbidden',
+         404=>'Not Found',
+         405=>'Method Not Allowed',
+         406=>'Not Acceptable',
+         407=>'Proxy Authentication Required',
+         408=>'Request Timeout',
+         409=>'Conflict',
+         410=>'Gone',
+         411=>'Length Required',
+         412=>'Precondition Failed',
+         413=>'Payload Too Large',
+         414=>'URI Too Long',
+         415=>'Unsupported Media Type',
+         416=>'Range Not Satisfiable',
+         417=>'Expectation Failed',
+         421=>'Misdirected Request',
+         422=>'Unprocessable Entity',
+         423=>'Locked',
+         424=>'Failed Dependency',
+         425=>'Unassigned',
+         426=>'Upgrade Required',
+         427=>'Unassigned',
+         428=>'Precondition Required',
+         429=>'Too Many Requests',
+         430=>'Unassigned',
+         431=>'Request Header Fields Too Large',
+         451=>'Unavailable For Legal Reasons',
+         500=>'Internal Server Error',
+         501=>'Not Implemented',
+         502=>'Bad Gateway',
+         503=>'Service Unavailable',
+         504=>'Gateway Timeout',
+         505=>'HTTP Version Not Supported',
+         506=>'Variant Also Negotiates',
+         507=>'Insufficient Storage',
+         508=>'Loop Detected',
+         509=>'Unassigned',
+         510=>'Not Extended',
+         511=>'Network Authentication Required'}
+    # differences defined in RFC 3507
+    ICAP_STATUS_CODES = HTTP_STATUS_CODES.dup.merge(
+      {
+          100 => 'Continue after ICAP Preview',
+          204 => 'No modifications needed',
+          404 => 'ICAP Service not found',
+          405 => 'Method not allowed for service',
+          408 => 'Request timeout',
+          500 => 'Server error',
+          501 => 'Method not implemented',
+          503 => 'Service overloaded',
+          505 => 'ICAP version not supported by server'
+      })
+  end
+end

data/lib/icaprb/server/data_structures.rb

@@ -0,0 +1,182 @@
+# patch ruby strings
+class String
+  # converts the string to a chunk (chunked encoding)
+  def to_chunk
+    length.to_s(16) + "\r\n" + self + "\r\n"
+  end
+  # extracts a ruby string from a chunk (chunked encoding)
+  def chunk_to_s
+    len_alpha = scan(/\A([\da-fA-F]+)\r\n/).first.first
+    len = len_alpha.to_i(16)
+    offset_data = len_alpha.length + 2 # 2 = CRLF
+    end_of_message = (offset_data+len)
+    str = self[offset_data...end_of_message]
+    raise 'Too many data in chunk' if end_of_message + 2 != length
+    str
+  end
+end
+
+module ICAPrb
+  module Server
+
+    # This class is the base for the HTTP header classes. It is a subclass of +Hash+.
+    class HTTP_Header < Hash
+
+      # Converts the array to a +String+ and which will be the complete HTTP Header,
+      # witch contains the request or status line.
+      #
+      # It will join the headers with \r\n and ends with \r\n\r\n
+      def to_s
+        data = []
+        each do |key, value|
+          data << "#{key}: #{value}"
+        end
+        request_line + data.join("\r\n") + "\r\n\r\n"
+      end
+    end
+
+    # The +RequestHeader+ represents the header information of an HTTP request. It contains the status line as well as
+    # the other headers. The headers are accessible by the array access operator
+    class RequestHeader < HTTP_Header
+      # the path requested by the user
+      attr_accessor :http_path
+      # The HTTP Method (also known as Verb) as a String. For Example GET, POST, PUT, DELETE or OPTIONS
+      attr_accessor :http_method
+      # The HTTP version which is used by the application
+      attr_accessor :http_version
+
+      # Initializes a new Object of +RequestHeader+
+      # Params:
+      # +http_method+:: The HTTP Method (also known as Verb) as a String. For Example GET, POST, PUT, DELETE or OPTIONS
+      # +http_path+:: The Resource which has been requested by the user
+      # +http_version+:: The HTTP version which is used by the application
+      def initialize(http_method, http_path, http_version = '1.1')
+        @http_method = http_method
+        @http_path = http_path
+        @http_version = http_version
+      end
+
+      # The request header is always the first header and it can be included only once in an ICAP response
+      def <=>(value)
+        return 0 if value.class == RequestHeader
+        -1
+      end
+
+      # creates the request line for the request
+      # it will include the method, the path and the used http version.
+      def request_line
+        "#{@http_method} #{@http_path} HTTP/#{@http_version}\r\n"
+      end
+    end
+
+    # This class represents the +Body+ of an HTTP request. It has to come after the headers in ICAP messages.
+    # It will be used if the request contains data (usually POST)
+    #
+    # Use the << operator to concatenate the strings as + would return a string and your ICAP answer would fail.
+    class RequestBody < String
+      # true if we are in the preview
+      attr_accessor :ieof
+
+      # initializes a new RequestBody which is a String but has an ieof tag additionally.
+      def initialize (string, ieof = false)
+        super string
+        @ieof = ieof
+      end
+      # A body comes after the headers
+      def <=>(other)
+        case other
+          when RequestHeader
+            1
+          when ResponseHeader
+            1
+          when RequestBody
+            0
+          when ResponseBody
+            0
+          when NullBody
+            -1
+        end
+      end
+
+    end
+
+    # This class represents the +Header+ of an HTTP response. It includes the headers sent by the web server as well as
+    # the status line
+    class ResponseHeader < HTTP_Header
+      # Params:
+      # +http_version+:: is the version of http to use - usually 1.1
+      # +status_code+:: is the status code of the http protocol. For example 200 for OK
+      def initialize(http_version, status_code)
+        @http_version = http_version
+        @status_code = status_code
+      end
+
+      # creates the response line for the request
+      # it will contain the http version, the status code and the status text from HTTP_STATUS_CODES
+      def request_line
+        "HTTP/#{@http_version} #{@status_code} #{HTTP_STATUS_CODES[@status_code]}\r\n"
+      end
+
+      # The request header has to come first
+      def <=>(other)
+        case other
+          when RequestHeader
+            1
+          when ResponseHeader
+            0
+          else
+            -1
+        end
+      end
+    end
+
+    # This class represents the response body which should be sent to the user.
+    # If it is missing, it could be replaced by a NullBody
+    class ResponseBody < String
+      # if it is in the preview, this will be true, otherwise nil or false
+      attr_accessor :ieof
+
+      # initializes a new RequestBody which is a String but has an ieof tag additionally.
+      def initialize(string, ieof = false)
+        super string
+        @ieof = ieof
+      end
+
+      # compare to sort within an array
+      # Response Bodies are usually at the end
+      def <=>(other)
+        case other
+          when RequestHeader
+            1
+          when ResponseHeader
+            1
+          when RequestBody
+            0
+          when ResponseBody
+            0
+          when NullBody
+            -1
+        end
+      end
+    end
+
+    # The +NullBody+ is a Class to have an Body without content. It exists to let the ICAP client know, that there
+    # will not be any body for this HTTP request. This usually happens when a 204 No Content ist sent.
+    class NullBody
+      # Returns an empty +String+
+      def to_s
+        ''
+      end
+
+      # It is always the last entry in ICAP responses.
+      def <=>(_)
+        1
+      end
+
+      # Show an empty string on the IRB instead of the object id, so it looks like a +ResponseBody+
+      def inspect
+        '""'
+      end
+    end
+  end
+end