* lib/drb/acl.rb: Add documentation.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31585 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,7 @@
+Mon May 16 05:49:54 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/drb/acl.rb:  Add documentation.
+
 Mon May 16 05:13:20 2011  Martin Bosslet  <Martin.Bosslet@googlemail.com>
 
 	* ext/openssl/ossl_asn1.c: Add documentation.

lib/drb/acl.rb

@@ -1,5 +1,3 @@
-# acl-2.0 - simple Access Control List
-#
 # Copyright (c) 2000,2002,2003 Masatoshi SEKI
 #
 # acl.rb is copyrighted free software by Masatoshi SEKI.
@@ -7,9 +5,50 @@
 
 require 'ipaddr'
 
+##
+# Simple Access Control Lists.
+#
+# Access control lists are composed of "allow" and "deny" halves to control
+# access.  Use "all" or "*" to match any address.  To match a specific address
+# use any address or address mask that IPAddr can understand.
+#
+# Example:
+#
+#   list = %w[
+#     deny all
+#     allow 192.168.1.1
+#     allow ::ffff:192.168.1.2
+#     allow 192.168.1.3
+#   ]
+#
+#   # From Socket#peeraddr, see also ACL#allow_socket?
+#   addr = ["AF_INET", 10, "lc630", "192.168.1.3"]
+#
+#   acl = ACL.new
+#   p acl.allow_addr?(addr) # => true
+#
+#   acl = ACL.new(list, ACL::DENY_ALLOW)
+#   p acl.allow_addr?(addr) # => true
+
 class ACL
+
+  ##
+  # The current version of ACL
+
   VERSION=["2.0.0"]
+
+  ##
+  # An entry in an ACL
+
   class ACLEntry
+
+    ##
+    # Creates a new entry using +str+.
+    #
+    # +str+ may be "*" or "all" to match any address, an IP address string
+    # to match a specific address, an IP address mask per IPAddr, or one
+    # containing "*" to match part of an IPv4 address.
+
     def initialize(str)
       if str == '*' or str == 'all'
 	@pat = [:all]
@@ -25,6 +64,10 @@ class ACL
     end
 
     private
+
+    ##
+    # Creates a regular expression to match IPv4 addresses
+
     def dot_pat_str(str)
       list = str.split('.').collect { |s|
 	(s == '*') ? '.+' : s
@@ -33,12 +76,20 @@ class ACL
     end
 
     private
+
+    ##
+    # Creates a Regexp to match an address.
+
     def dot_pat(str)
       exp = "^" + dot_pat_str(str) + "$"
       Regexp.new(exp)
     end
 
     public
+
+    ##
+    # Matches +addr+ against this entry.
+
     def match(addr)
       case @pat[0]
       when :all
@@ -59,12 +110,24 @@ class ACL
     end
   end
 
+  ##
+  # A list of ACLEntry objects.  Used to implement the allow and deny halves
+  # of an ACL
+
   class ACLList
+
+    ##
+    # Creates an empty ACLList
+
     def initialize
       @list = []
     end
 
     public
+
+    ##
+    # Matches +addr+ against each ACLEntry in this list.
+
     def match(addr)
       @list.each do |e|
 	return true if e.match(addr)
@@ -73,14 +136,39 @@ class ACL
     end
 
     public
+
+    ##
+    # Adds +str+ as an ACLEntry in this list
+
     def add(str)
       @list.push(ACLEntry.new(str))
     end
+
   end
 
+  ##
+  # Default to deny
+
   DENY_ALLOW = 0
+
+  ##
+  # Default to allow
+
   ALLOW_DENY = 1
 
+  ##
+  # Creates a new ACL from +list+ with an evaluation +order+ of DENY_ALLOW or
+  # ALLOW_DENY.
+  #
+  # An ACL +list+ is an Array of "allow" or "deny" and an address or address
+  # mask or "all" or "*" to match any address:
+  #
+  #   %w[
+  #     deny all
+  #     allow 192.0.2.2
+  #     allow 192.0.2.128/26
+  #   ]
+
   def initialize(list=nil, order = DENY_ALLOW)
     @order = order
     @deny = ACLList.new
@@ -89,11 +177,22 @@ class ACL
   end
 
   public
+
+  ##
+  # Allow connections from Socket +soc+?
+
   def allow_socket?(soc)
     allow_addr?(soc.peeraddr)
   end
 
   public
+
+  ##
+  # Allow connections from addrinfo +addr+?  It must be formatted like
+  # Socket#peeraddr:
+  #
+  #   ["AF_INET", 10, "lc630", "192.0.2.1"]
+
   def allow_addr?(addr)
     case @order
     when DENY_ALLOW
@@ -110,6 +209,10 @@ class ACL
   end
 
   public
+
+  ##
+  # Adds +list+ of ACL entries to this ACL.
+
   def install_list(list)
     i = 0
     while i < list.size
@@ -125,6 +228,7 @@ class ACL
       i += 2
     end
   end
+
 end
 
 if __FILE__ == $0