ipaccess 1.2.0 → 1.2.2

data/lib/ipaccess/ghost_doc/ghost_doc.rb

@@ -10,7 +10,7 @@
 # 
 #--
 # 
-# Copyright (C) 2009 by Paweł Wilk. All Rights Reserved.
+# Copyright (C) 2009-2014 by Paweł Wilk. All Rights Reserved.
 # 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of either: 1) the GNU Lesser General Public License

data/lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc

@@ -0,0 +1,54 @@
+This member selects IPAccess::Set object that will be used to
+control IP access for a socket.
+
+=== Setting an access set
+
+You may assign global access set,
+create local access set or use shared set.
+
+- If an argument is +:global+ it uses global access set.
+- If an argument is +:private+ it creates an empty, private access set.
+- If an argument is an IPAccess::Set object then it is used as external, shared set.
+
+==== Global access set
+
+Global access set is an IPAccess::Set object referenced by contant IPAccess::Set.Global
+It cannot be modified by calling +acl+ attribute. To add or remove rules
+use mentioned constant. By default all sockets with enabled IP access control
+are using this set.
+
+==== Private access set
+
+Private access set is an IPAccess::Set object created for socket object.
+You may modify it by referencing to +acl+ member of the socket object.
+
+Under some circumstances it is possible to share private access set
+– you just have to pass the +acl+ member of a socket to initializer
+of new socket object as shared access set.
+
+==== Shared access set
+
+Shared access set is an IPAccess::Set object that more than one socket
+may use to control IP access. It differs from private access set
+only by operation used to create. The private access set is created
+automatically and shared access set exists before socket object is
+formed.
+
+=== Using an access set
+
+This member keeps the information about currently
+used access set. You may use it to do low-level
+operations on IPAccess::Set object associated
+with instance. You cannot however call any
+of global access set operations – to do that
+use IPAccess::Set.Global contant referencing to
+global ACL.
+
+==== Manipulating access lists
+
+You should avoid manipulating an access set directly to add
+or remove rules in lists. It works fine but under some circumstances
+changes made on working (connected) network object may
+not be noticed immediately. You should use direct methods
+(like blacklist, whitelist, blacklist! and whitelist!)
+to control access for existing network objects.

data/lib/ipaccess/ghost_doc/ghost_doc_net_ftp.rb

@@ -28,7 +28,7 @@
 # class but provides special member called +acl+ and a few new
 # instance methods for controlling IP access.
 # 
-#:include:ghost_doc_patched_usage.rb
+# {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
 # 
 # This documentation doesn't cover description of all
 # class and instance methods of the original
@@ -92,29 +92,45 @@
 
 class IPAccess::Net::FTP
   
-  #:include:ghost_doc_p_whitelist_e.rb
-  def whitelist!; end
+  # {include:IPAccess::Socket#whitelist!}
+  # @overload whitelist!(*addresses)
+  # @overload whitelist!(list, *addresses)
+  def whitelist!(*addresses); end
 
-  #:include:ghost_doc_p_whitelist.rb
-  def whitelist; end
+  # {include:IPAccess::Socket#whitelist}
+  # @overload whitelist(*addresses)
+  # @overload whitelist(list, *addresses)
+  def whitelist(*addresses); end
 
-  #:include:ghost_doc_p_blacklist_e.rb
-  def blacklist!; end
+  # {include:IPAccess::Socket#blacklist!}
+  # @overload blacklist!(*addresses)
+  # @overload blacklist!(list, *addresses)
+  def blacklist!(*addresses); end
 
-  #:include:ghost_doc_p_blacklist.rb
-  def blacklist; end
+  # {include:IPAccess::Socket#blacklist}
+  # @overload blacklist(*addresses)
+  # @overload blacklist(list, *addresses)
+  def blacklist(*addresses); end
 
-  #:include:ghost_doc_p_unwhitelist.rb
-  def unwhitelist; end
-
-  #:include:ghost_doc_p_unwhitelist_e.rb
-  def unwhitelist!; end
+  # {include:IPAccess::Socket#unwhitelist!}
+  # @overload unwhitelist!(*addresses)
+  # @overload unwhitelist!(list, *addresses)
+  def unwhitelist!(*addresses); end
+  
+  # {include:IPAccess::Socket#unwhitelist}
+  # @overload unwhitelist(*addresses)
+  # @overload unwhitelist(list, *addresses)
+  def unwhitelist(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist_e.rb
-  def unblacklist!; end
+  #{include:IPAccess::Socket#unblacklist!}
+  # @overload unblacklist!(*addresses)
+  # @overload unblacklist!(list, *addresses)
+  def unblacklist!(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist.rb
-  def unblacklist; end
+  #{include:IPAccess::Socket#unblacklist}
+  # @overload unblacklist(*addresses)
+  # @overload unblacklist(list, *addresses)
+  def unblacklist(*addresses); end
   
   alias_method :unblock!,   :unblacklist!
   alias_method :del_black!, :unblacklist!
@@ -145,7 +161,7 @@ class IPAccess::Net::FTP
   # allows to set reason.
   def blacklist_reasonable(reason, *addresses); end
   
-  #:include:ghost_doc_acl.rb
+  #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
   #  
   # === Example
   # 

data/lib/ipaccess/ghost_doc/ghost_doc_net_http.rb

@@ -28,7 +28,7 @@
 # provides special member called +acl+ and a few new
 # instance methods for controlling IP access.
 # 
-#:include:ghost_doc_patched_usage.rb
+# {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
 # 
 # This documentation doesn't cover description of all
 # class and instance methods of the original
@@ -133,29 +133,45 @@
 
 class IPAccess::Net::HTTP
 
-  #:include:ghost_doc_p_whitelist_e.rb
-  def whitelist!; end
+  # {include:IPAccess::Socket#whitelist!}
+  # @overload whitelist!(*addresses)
+  # @overload whitelist!(list, *addresses)
+  def whitelist!(*addresses); end
 
-  #:include:ghost_doc_p_whitelist.rb
-  def whitelist; end
+  # {include:IPAccess::Socket#whitelist}
+  # @overload whitelist(*addresses)
+  # @overload whitelist(list, *addresses)
+  def whitelist(*addresses); end
 
-  #:include:ghost_doc_p_blacklist_e.rb
-  def blacklist!; end
+  # {include:IPAccess::Socket#blacklist!}
+  # @overload blacklist!(*addresses)
+  # @overload blacklist!(list, *addresses)
+  def blacklist!(*addresses); end
 
-  #:include:ghost_doc_p_blacklist.rb
-  def blacklist; end
+  # {include:IPAccess::Socket#blacklist}
+  # @overload blacklist(*addresses)
+  # @overload blacklist(list, *addresses)
+  def blacklist(*addresses); end
 
-  #:include:ghost_doc_p_unwhitelist_e.rb
-  def unwhitelist!; end
+  # {include:IPAccess::Socket#unwhitelist!}
+  # @overload unwhitelist!(*addresses)
+  # @overload unwhitelist!(list, *addresses)
+  def unwhitelist!(*addresses); end
   
-  #:include:ghost_doc_p_unwhitelist.rb
-  def unwhitelist; end
+  # {include:IPAccess::Socket#unwhitelist}
+  # @overload unwhitelist(*addresses)
+  # @overload unwhitelist(list, *addresses)
+  def unwhitelist(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist_e.rb
-  def unblacklist!; end
+  #{include:IPAccess::Socket#unblacklist!}
+  # @overload unblacklist!(*addresses)
+  # @overload unblacklist!(list, *addresses)
+  def unblacklist!(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist.rb
-  def unblacklist; end
+  #{include:IPAccess::Socket#unblacklist}
+  # @overload unblacklist(*addresses)
+  # @overload unblacklist(list, *addresses)
+  def unblacklist(*addresses); end
 
   alias_method :unblock!,   :unblacklist!
   alias_method :del_black!, :unblacklist!
@@ -186,7 +202,7 @@ class IPAccess::Net::HTTP
   # allows to set reason.
   def blacklist_reasonable(reason, *addresses); end
     
-  #:include:ghost_doc_acl.rb
+  #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
   #  
   # === Example
   # 

data/lib/ipaccess/ghost_doc/ghost_doc_net_smtp.rb

@@ -28,7 +28,7 @@
 # class but provides special member called +acl+ and a few new
 # instance methods for controlling IP access.
 # 
-#:include:ghost_doc_patched_usage.rb
+# {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
 #
 # This documentation doesn't cover description of all
 # class and instance methods of the original
@@ -58,29 +58,45 @@
    
 class IPAccess::Net::SMTP
   
-  #:include:ghost_doc_p_whitelist_e.rb
-  def whitelist!; end
+  # {include:IPAccess::Socket#whitelist!}
+  # @overload whitelist!(*addresses)
+  # @overload whitelist!(list, *addresses)
+  def whitelist!(*addresses); end
 
-  #:include:ghost_doc_p_whitelist.rb
-  def whitelist; end
+  # {include:IPAccess::Socket#whitelist}
+  # @overload whitelist(*addresses)
+  # @overload whitelist(list, *addresses)
+  def whitelist(*addresses); end
 
-  #:include:ghost_doc_p_blacklist_e.rb
-  def blacklist!; end
+  # {include:IPAccess::Socket#blacklist!}
+  # @overload blacklist!(*addresses)
+  # @overload blacklist!(list, *addresses)
+  def blacklist!(*addresses); end
 
-  #:include:ghost_doc_p_blacklist.rb
-  def blacklist; end
+  # {include:IPAccess::Socket#blacklist}
+  # @overload blacklist(*addresses)
+  # @overload blacklist(list, *addresses)
+  def blacklist(*addresses); end
 
-  #:include:ghost_doc_p_unwhitelist.rb
-  def unwhitelist; end
-
-  #:include:ghost_doc_p_unwhitelist_e.rb
-  def unwhitelist!; end
+  # {include:IPAccess::Socket#unwhitelist!}
+  # @overload unwhitelist!(*addresses)
+  # @overload unwhitelist!(list, *addresses)
+  def unwhitelist!(*addresses); end
+  
+  # {include:IPAccess::Socket#unwhitelist}
+  # @overload unwhitelist(*addresses)
+  # @overload unwhitelist(list, *addresses)
+  def unwhitelist(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist_e.rb
-  def unblacklist!; end
+  #{include:IPAccess::Socket#unblacklist!}
+  # @overload unblacklist!(*addresses)
+  # @overload unblacklist!(list, *addresses)
+  def unblacklist!(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist.rb
-  def unblacklist; end
+  #{include:IPAccess::Socket#unblacklist}
+  # @overload unblacklist(*addresses)
+  # @overload unblacklist(list, *addresses)
+  def unblacklist(*addresses); end
   
   alias_method :unblock!,   :unblacklist!
   alias_method :del_black!, :unblacklist!
@@ -111,7 +127,7 @@ class IPAccess::Net::SMTP
   # allows to set reason.
   def blacklist_reasonable(reason, *addresses); end
   
-  #:include:ghost_doc_acl.rb
+  #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
   #  
   # === Example
   # 

data/lib/ipaccess/ghost_doc/ghost_doc_net_telnet.rb

@@ -28,7 +28,7 @@
 # provides provides special member called +acl+ and a few new
 # instance methods for controlling IP access.
 # 
-#:include:ghost_doc_patched_usage.rb
+# {include:file:lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc}
 # 
 # This documentation doesn't cover description of all
 # class and instance methods of the original
@@ -117,29 +117,45 @@
 
 class IPAccess::Net::Telnet
   
-  #:include:ghost_doc_p_whitelist_e.rb
-  def whitelist!; end
+  # {include:IPAccess::Socket#whitelist!}
+  # @overload whitelist!(*addresses)
+  # @overload whitelist!(list, *addresses)
+  def whitelist!(*addresses); end
 
-  #:include:ghost_doc_p_whitelist.rb
-  def whitelist; end
+  # {include:IPAccess::Socket#whitelist}
+  # @overload whitelist(*addresses)
+  # @overload whitelist(list, *addresses)
+  def whitelist(*addresses); end
 
-  #:include:ghost_doc_p_blacklist_e.rb
-  def blacklist!; end
+  # {include:IPAccess::Socket#blacklist!}
+  # @overload blacklist!(*addresses)
+  # @overload blacklist!(list, *addresses)
+  def blacklist!(*addresses); end
 
-  #:include:ghost_doc_p_blacklist.rb
-  def blacklist; end
+  # {include:IPAccess::Socket#blacklist}
+  # @overload blacklist(*addresses)
+  # @overload blacklist(list, *addresses)
+  def blacklist(*addresses); end
 
-  #:include:ghost_doc_p_unwhitelist.rb
-  def unwhitelist; end
-
-  #:include:ghost_doc_p_unwhitelist_e.rb
-  def unwhitelist!; end
+  # {include:IPAccess::Socket#unwhitelist!}
+  # @overload unwhitelist!(*addresses)
+  # @overload unwhitelist!(list, *addresses)
+  def unwhitelist!(*addresses); end
+  
+  # {include:IPAccess::Socket#unwhitelist}
+  # @overload unwhitelist(*addresses)
+  # @overload unwhitelist(list, *addresses)
+  def unwhitelist(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist_e.rb
-  def unblacklist!; end
+  #{include:IPAccess::Socket#unblacklist!}
+  # @overload unblacklist!(*addresses)
+  # @overload unblacklist!(list, *addresses)
+  def unblacklist!(*addresses); end
 
-  #:include:ghost_doc_p_unblacklist.rb
-  def unblacklist; end
+  #{include:IPAccess::Socket#unblacklist}
+  # @overload unblacklist(*addresses)
+  # @overload unblacklist(list, *addresses)
+  def unblacklist(*addresses); end
   
   alias_method :unblock!,   :unblacklist!
   alias_method :del_black!, :unblacklist!
@@ -170,7 +186,7 @@ class IPAccess::Net::Telnet
   # allows to set reason.
   def blacklist_reasonable(reason, *addresses); end
    
-  #:include:ghost_doc_acl.rb
+  #{include:file:lib/ipaccess/ghost_doc/ghost_doc_acl.rdoc}
   #  
   # === Example
   # 

data/lib/ipaccess/ghost_doc/ghost_doc_patched_usage.rdoc

@@ -0,0 +1,65 @@
+Access checks are lazy,
+which means they are performed when
+a real connection is going to happend.
+
+Instances of this class will also
+internally use patched versions of Ruby's network
+socket objects to avoid access leaks.
+
+You can pass access set in various ways: while
+creating a new object or while a communication is
+already started. You can also rely on a global
+access set, which is used by default.
+
+=== Usage
+
+There are 3 ways to enable access control:
+
+* by patching original class (see IPAccess.arm) – use it in code that you cannot modify
+* by patching single instance (see IPAccess.arm) – use it occasionally
+* by using instances of this class directly – use it in your own code
+
+There are also 4 ways to manage access rules:
+
+* by using direct methods like blacklist and whitelist – preferred
+* by using +acl+ member – low-level
+* by using <tt>IPAccess::Set.Global</tt> constant – controls a global access set
+* by using methods of an external IPAccess::Set object associated with an instance
+
+==== Using direct methods
+
+Patched network objects and variants have methods to control access.
+You should use them since they are most reliable way to perform
+modifications on an working instance. These methods (documented
+below) are: whitelist, blacklist, whitelist! and blacklist!.
+Each of the methods ensures that needed safety checks are made
+when detecting some change in access lists.
+
+==== Using +acl+ member
+
+The +acl+ member gives you direct access to internal IPAccess::Set
+instance that an object uses to control an access. However,
+by accessing this member you may only modify private and shared
+access sets, and you have to manually re-check connection against lists
+(e.g. by using method acl_recheck).
+
+==== Using IPAccess::Set.Global
+
+You may use IPAccess::Set.Global to add or remove rules
+conatined in lists of a global access set. You should use
+it before some network objects are created and if it's not
+possible call acl_recheck for any object that is using it
+when some changes in rules are made. It is also possible
+to manipulate global access set from object's scope using
+whitelist! and blacklist! methods. For working
+objects you should use them.
+
+==== Using external access set
+
+External access sets are simply IPAccess::Set objects
+that were associated with an instance during initialization
+or by assigning it to +acl+ member. You may manipulate their
+access rules safely before a networking object is in
+a connected state. After it happens it is safer to use
+direct controlling methods that network object provides.
+