ipaccess 0.0.4 → 1.2.0

data/docs/LGPL

@@ -0,0 +1,166 @@
+
+= GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. < http://fsf.org/ >
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+=== 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+=== 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+=== 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+=== 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+=== 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+0) Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+
+1) Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that (a) uses at run time
+a copy of the Library already present on the user's computer
+system, and (b) will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+=== 5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+=== 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

data/docs/TODO

@@ -1,18 +1,161 @@
+== IPAccess
 
-Specification:
+
+
+- neet to be callable like x[:input] or x[:output] which allows more generic access to lists
+- make it an array-like!
+
+== new logic
+
+- universal bus for storing objects
+
+0. bus belongs to a list
+1. bus contains object id-s of sockets
+2. each socket object contains a list of useables inside
+3. useables is a collection of references to objects that are using sockets
+4. useables are added just after socket has been created
+5. useables are present only when some socket caused the exception (otherwise we whould count on an originator)
+
+adding useables:
+
+when arming, add a useable if object is a socket
+
+
+adding to bus:
+
+socket is added to bus when armed (be aware of inpu/output lists!)
+
+removing from bus:
+
+finalizer
+
+
+changing the acl of high-level object:
+
+if the acl is really changed:
+
+if the list is really changed:
+
+ - for all previous lists (input and output) do:
+   - take a bus and for each socket
+     - remove useable (self) from socket 
+   - remove socket from thet bus if there are no useables in a socket
+
+ - for all new lists (input and output) do:
+   - take a bus
+   - add useable to a socket's useables
+   - add socket to a bus
+
+rechecking all during access list manipulation
+
+in context: list
+for each socket on a bus
+  call access checking method ipcheck_socket passing a list and an exception (input or output)
+  
+
+
+
+
+
+exception:
+
+useables		-	all object's id-s that are using it
+originator		-	an object that had been using it when exception happened (by re-raising an exception)
+socket			- socket object that caused the exception to happened (may be nil)
+
+
+
+
+
+- sprawdzic ile razy sie wola przeszukiwanie przy nowym obiekcie, czy nie za wiele razy
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+- Where to register in a bus? In initializer or during patching (ipa_singleton_hook) and acl changing method
+- what about duplicates in case of auto-armed sockets in higher-level objects? some option that prevents it
+- when adding to a bus store originator!!!!!!!!! (requires acl= overload and supercall since different sockets are in network classes)
+
+
+- gdy wyjatek rzuci socket podczas uzytkowania obiektu wysokiej klasy to co zamknie obiekt wysokiej klasy?
+  - try_terminate zlapane gdzies tam w opakowaniu albo rezygnujemy z automagicznego zamykania
+
+jak gniazdo sie zarejestruje na szynie z parentem?
+ - przy try_arm_and_check_socket w self.acl=
+
+a jak zmieni sie przyporzadkowanie, gdy ktos da: ftp.acl = inny
+ - to musimy przepisac duzo bo acl to jakies listy!!!! te listy zmienia sie w stosunku do obiektu i do jego obiektow gniazd
+   najpierw dodac do nowych
+   - co dodac?
+     - zarejestrowac obiekt macierzysty i jego gniazda
+     - gdzie? w busach nowego acl
+       - a jesli juz tam cos jest? czy sie nie skasuje? nie powinno. idy sa unikatowe.
+
+   poetm wyrypac ze starych
+   - a jak acl jest shared i jeszcze w nim siedzi obiekt inny ktorego gniazdo jest wspolne?
+     - zbadac to potem
+ - potem sprawdzamy wszystkie sockety ZWIAZANE Z OBIEKTEM na ktorym ACL sie zmienia i ew. cal
+ 
+
+a jak zmieni sie cos w external acl-u?
+ - to sprawdzamy wszystkie sockety W OGOLE i ew. call
+
+
+
+
+- JUST-SOCKETS approach??? YES
+
+- add examples with blocks
+- check all overloaded class methods that take blocks for bugs
+
+=== Specification
 
 - add missing rspec examples
 
-Ruby 1.9 sockets:
+== Documentation
+
+- rewrite docs and examples for patches to use proxy methods like .blacklist !!!
+- write a manual how to arm you own objects in an easy way (like include IPAccess::Patches::ACL)
+- add a doco with an example of a block that disables throwing an exception but closes connection and does stuff
+- insert hints in documentation: acl.output.blacklist before object is created and obj.blacklist when it exists as a good example!
+- add IPAccess::Net ghost-doc
+- sockets: document initializers and other stuff that takes :opened_on_deny
+
+== Other
 
-- overload Ruby 1.9 socket methods
+- inspect methods?
 
-Documentation:
+== Ruby 1.8
 
-- add more documentation describing access checking workflow
+- ok
 
-Other:
+== Future
 
+- ability to react on greylisted entries? :)
+- some Ruby 1.9-specific socket methods
+- utilize @debug_mode in certain network objects to pring access denied message
 - maybe some day: test input lists even if socket is a client socket - local socket address permit/deny
-- inspect methods?
+- to speed up ACL seeks maybe a small, fast buffer for up to 128 IP matches cleaned when something will change?
+
+
 
+begin
+	a.blacklist '127.0.0.1'
+rescue
+	
+end

data/docs/rdoc.css

@@ -0,0 +1,22 @@
+@import "rdoc_base.css";
+
+#documentation > ul:first-of-type {
+  padding-bottom: 2em;
+  padding-top: 1.5em;
+  background-image: url(images/ipaccess_logo.png);
+  background-position: 20em 0%;
+  background-repeat: no-repeat;
+  }
+
+#documentation .method-description > p:first-of-type + p {
+  margin-top: 0.5em;
+}
+
+#documentation .method-description > ul {
+  margin-left: 1.2em;
+}
+
+#documentation .method-description > p + ul {
+  margin-left: 1.8em;
+}
+

data/examples/ftp.rb

@@ -0,0 +1,62 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/ftp'
+
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist 'randomseed.pl'
+
+# Create custom access set with one blacklisted IP
+acl = IPAccess::Set.new
+acl.output.blacklist 'randomseed.pl'
+
+#===== Example cases
+
+begin
+  IPAccess::Net::FTP.open('ftp.icm.edu.pl', acl) { |ftp|
+    ftp.passive = true
+    ftp.blacklist! 'ftp.icm.edu.pl'
+    files = ftp.list('li*')
+    puts files
+  }
+
+rescue IPAccessDenied => e
+
+  puts e.show
+  puts "Connection is " + (e.originator.closed? ? "closed" : "opened")
+  
+end
+
+# Using IPAccess::Net::FTP variant instead of Net::FTP
+
+ftp = IPAccess::Net::FTP.new('ftp.pld-linux.org', :private) # private access set
+ftp.passive = true
+ftp.login
+files = ftp.chdir('/')
+ftp.blacklist 'ftp.pld-linux.org'                           # blacklisting
+files = ftp.list('n*') # this command opens socket so there is no need to call acl_recheck
+ftp.close
+
+# Using patched Net::FTP object
+
+acl = IPAccess::Set.new
+acl.output.blacklist 'ftp.pld-linux.org'
+ftp = Net::FTP.new('ftp.pld-linux.org')
+ftp.passive = true
+ftp.login
+IPAccess.arm ftp, acl
+files = ftp.chdir('/')
+files = ftp.list('n*')
+ftp.close
+
+# Using patched Net::FTP class
+
+acl = IPAccess::Set.new
+IPAccess.arm Net::FTP
+ftp = Net::FTP.new('ftp.pld-linux.org')
+ftp.acl = acl
+ftp.passive = true
+ftp.login
+files = ftp.chdir('/')
+acl.output.blacklist 'ftp.pld-linux.org'
+files = ftp.list('n*')
+ftp.close

data/examples/http.rb

@@ -0,0 +1,81 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/http'
+require 'uri'
+
+url = URI.parse('http://randomseed.pl/index.html')
+
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist 'randomseed.pl'
+
+# Create custom access set with one blacklisted IP
+acl = IPAccess::Set.new
+acl.output.blacklist 'randomseed.pl'
+
+#===== Example cases
+
+# Case 0: custom access set and patched single instance
+
+req = Net::HTTP::Get.new("/")
+
+begin
+
+  htt = Net::HTTP.new(url.host, url.port)
+  IPAccess.arm htt
+
+  res = htt.start { |http|
+    http.request(req)
+  }
+
+rescue IPAccessDenied => e
+
+  puts "Message:\t#{e.message}"
+  puts
+  puts "ACL:\t\t#{e.acl}"
+  puts "Exception:\t#{e.inspect}"
+  puts "Remote IP:\t#{e.peer_ip}"
+  puts "Rule:\t\t#{e.rule}"
+  puts "Originator:\t#{e.originator}"
+  puts "CIDR's Origin:\t#{e.peer_ip.tag[:Originator]}\n\n"
+  
+end
+
+# Case 1: simple setup with custom ACL
+res = IPAccess::Net::HTTP.start(url.host, url.port, acl) { |http|
+  http.get("/#{url.path}")
+}
+
+# Case 2: custom access set with Net::HTTP variant
+
+req = Net::HTTP::Get.new(url.path)
+htt = IPAccess::Net::HTTP.new(url.host, url.port, acl)
+res = htt.start { |http|
+  http.request(req)
+}
+
+# Case 3: global access set with Net::HTTP variant
+
+req = Net::HTTP::Get.new(url.path)
+htt = IPAccess::Net::HTTP.new(url.host, url.port)
+res = htt.start { |http|
+  http.request(req)
+}
+
+# Case 4: global access set with Net::HTTP variant
+
+req = Net::HTTP::Get.new(url.path)
+res = IPAccess::Net::HTTP.start(url.host, url.port) { |http|
+  http.request(req)
+}
+
+# Case 5: get_print with custom ACL
+
+IPAccess::Net::HTTP.get_print 'randomseed.pl', '/index.html', acl
+
+# Case 6: arming Net::HTTP class
+
+# Arm Net::HTTP class of Ruby
+IPAccess.arm Net::HTTP
+# Call Net::HTTP.get_print
+Net::HTTP.get_print 'randomseed.pl', '/index.html'
+