* lib/drb/drb.rb: Updated documentation based on patch from Vincent

  Batts.  [ruby-trunk - Bug #7714]
* lib/drb/ssl.rb:  ditto.


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

2 files changed, 194 insertions, 19 deletions

diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb
index f5d4a26906..1d3c413e0c 100644
--- a/lib/drb/drb.rb
+++ b/lib/drb/drb.rb
@@ -514,8 +514,8 @@ module DRb
 
   class DRbArray
 
-    # Creates a new DRbArray that either dumps or wraps all the items in +ary+
-    # so they can be loaded by a remote DRb server.
+    # Creates a new DRbArray that either dumps or wraps all the items in the
+    # Array +ary+ so they can be loaded by a remote DRb server.
 
     def initialize(ary)
       @ary = ary.collect { |obj|
@@ -826,7 +826,12 @@ module DRb
 
     public
 
-    # Open a client connection to +uri+ using configuration +config+.
+    # Open a client connection to +uri+ (DRb URI string) using configuration
+    # +config+.
+    #
+    # This can raise DRb::DRbBadScheme or DRb::DRbBadURI if +uri+ is not for a
+    # recognized protocol.  See DRb::DRbServer.new for information on built-in
+    # URI protocols.
     def self.open(uri, config)
       host, port, = parse_uri(uri)
       host.untaint
@@ -835,6 +840,7 @@ module DRb
       self.new(uri, soc, config)
     end
 
+    # Returns the hostname of this server
     def self.getservername
       host = Socket::gethostname
       begin
@@ -844,6 +850,9 @@ module DRb
       end
     end
 
+    # For the families available for +host+, returns a TCPServer on +port+.
+    # If +port+ is 0 the first available port is used.  IPv4 servers are
+    # preferred over IPv6 servers.
     def self.open_server_inaddr_any(host, port)
       infos = Socket::getaddrinfo(host, nil,
                                   Socket::AF_UNSPEC,
@@ -1023,7 +1032,8 @@ module DRb
       self.new_with(uri, ref)
     end
 
-    # Creates a new DRbObject from a +uri+ and object +ref+.
+    # Creates a DRb::DRbObject given the reference information to the remote
+    # host +uri+ and object +ref+.
 
     def self.new_with(uri, ref)
       it = self.allocate
@@ -1112,6 +1122,7 @@ module DRb
       end
     end
 
+    # Given the +uri+ of another host executes the block provided.
     def self.with_friend(uri) # :nodoc:
       friend = DRb.fetch_server(uri)
       return yield() unless friend
@@ -1123,6 +1134,8 @@ module DRb
       Thread.current['DRb'] = save if friend
     end
 
+    # Returns a modified backtrace from +result+ with the +uri+ where each call
+    # in the backtrace came from.
     def self.prepare_backtrace(uri, result) # :nodoc:
       prefix = "(#{uri}) "
       bt = []
@@ -1254,9 +1267,9 @@ module DRb
       @@load_limit = sz
     end
 
-    # Set the default value for the :acl option.
+    # Set the default access control list to +acl+.  The default ACL is +nil+.
     #
-    # See #new().  The initial default value is nil.
+    # See also DRb::ACL and #new()
     def self.default_acl(acl)
       @@acl = acl
     end
@@ -1268,7 +1281,9 @@ module DRb
       @@idconv = idconv
     end
 
-    # Set the default safe level to +level+
+    # Set the default safe level to +level+.  The default safe level is 0
+    #
+    # See #new for more information.
     def self.default_safe_level(level)
       @@safe_level = level
     end
@@ -1326,6 +1341,9 @@ module DRb
     # :argc_limit :: the maximum number of arguments to a remote
     #                method accepted by the server.  Defaults to
     #                256.
+    # :safe_level :: The safe level of the DRbServer.  The attribute
+    #                sets $SAFE for methods performed in the main_loop.
+    #                Defaults to 0.
     #
     # The default values of these options can be modified on
     # a class-wide basis by the class methods #default_argc_limit,
@@ -1385,7 +1403,10 @@ module DRb
     # The configuration of this DRbServer
     attr_reader :config
 
-    # The safe level for this server
+    # The safe level for this server.  This is a number corresponding to
+    # $SAFE.
+    #
+    # The default safe_level is 0
     attr_reader :safe_level
 
     # Set whether to operate in verbose mode.
@@ -1741,7 +1762,10 @@ module DRb
   end
   module_function :thread
 
-  # Set the default id conv object.
+  # Set the default id conversion object.
+  #
+  # This is expected to be an instance such as DRb::DRbIdConv that responds to
+  # #to_id and #to_obj that can convert objects to and from DRb references.
   #
   # See DRbServer#default_id_conv.
   def install_id_conv(idconv)
@@ -1749,7 +1773,7 @@ module DRb
   end
   module_function :install_id_conv
 
-  # Set the default acl.
+  # Set the default ACL to +acl+.
   #
   # See DRb::DRbServer.default_acl.
   def install_acl(acl)
@@ -1766,7 +1790,16 @@ module DRb
   @server = {}
   # Registers +server+ with DRb.
   #
+  # This is called when a new DRb::DRbServer is created.
+  #
   # If there is no primary server then +server+ becomes the primary server.
+  #
+  # Example:
+  #
+  #  require 'drb'
+  #
+  #  s = DRb::DRbServer.new # automatically calls regist_server
+  #  DRb.fetch_server s.uri #=> #<DRb::DRbServer:0x...>
   def regist_server(server)
     @server[server.uri] = server
     mutex.synchronize do
@@ -1775,13 +1808,15 @@ module DRb
   end
   module_function :regist_server
 
-  # Removes +server+ from the list of servers.
+  # Removes +server+ from the list of registered servers.
   def remove_server(server)
     @server.delete(server.uri)
   end
   module_function :remove_server
 
   # Retrieves the server with the given +uri+.
+  #
+  # See also regist_server and remove_server.
   def fetch_server(uri)
     @server[uri]
   end
diff --git a/lib/drb/ssl.rb b/lib/drb/ssl.rb
index c0dd9c49f4..8651702797 100644
--- a/lib/drb/ssl.rb
+++ b/lib/drb/ssl.rb
@@ -11,9 +11,18 @@ module DRb
   # <code>drbssl://<host>:<port>?<option></code>.  The option is optional
   class DRbSSLSocket < DRbTCPSocket
 
-    # :stopdoc:
+    # SSLConfig handles the needed SSL information for establishing a
+    # DRbSSLSocket connection, including generating the X509 / RSA pair.
+    #
+    # An instance of this config can be passed to DRbSSLSocket.new,
+    # DRbSSLSocket.open and DRbSSLSocket.open_server
+    #
+    # See DRb::DRbSSLSocket::SSLConfig.new for more details
     class SSLConfig
 
+      # Default values for a SSLConfig instance.
+      #
+      # See DRb::DRbSSLSocket::SSLConfig.new for more details
       DEFAULT = {
         :SSLCertificate       => nil,
         :SSLPrivateKey        => nil,
@@ -30,6 +39,90 @@ module DRb
         :SSLCertComment       => "Generated by Ruby/OpenSSL"
       }
 
+      # Create a new DRb::DRbSSLSocket::SSLConfig instance
+      #
+      # The DRb::DRbSSLSocket will take either a +config+ Hash or an instance
+      # of SSLConfg, and will setup the certificate for its session for the
+      # configuration. If want it to generate a generic certificate, the bare
+      # minimum is to provide the :SSLCertName
+      #
+      # === Config options
+      #
+      # From +config+ Hash:
+      #
+      # :SSLCertificate ::
+      #   An instance of OpenSSL::X509::Certificate.  If this is not provided,
+      #   then a generic X509 is generated, with a correspond :SSLPrivateKey
+      #
+      # :SSLPrivateKey ::
+      #   A private key instance, like OpenSSL::PKey::RSA.  This key must be
+      #   the key that signed the :SSLCertificate
+      #
+      # :SSLClientCA ::
+      #   An OpenSSL::X509::Certificate, or Array of certificates that will
+      #   used as ClientCAs in the SSL Context
+      #
+      # :SSLCACertificatePath ::
+      #   A path to the directory of CA certificates.  The certificates must
+      #   be in PEM format.
+      #
+      # :SSLCACertificateFile ::
+      #   A path to a CA certificate file, in PEM format.
+      #
+      # :SSLTmpDhCallback ::
+      #   A DH callback. See OpenSSL::SSL::SSLContext.tmp_dh_callback
+      #
+      # :SSLVerifyMode ::
+      #   This is the SSL verification mode.  See OpenSSL::SSL::VERIFY_* for
+      #   available modes.  The default is OpenSSL::SSL::VERIFY_NONE
+      #
+      # :SSLVerifyDepth ::
+      #   Number of CA certificates to walk, when verifying a certificate
+      #   chain.
+      #
+      # :SSLVerifyCallback ::
+      #   A callback to be used for additional verification.  See
+      #   OpenSSL::SSL::SSLContext.verify_callback
+      #
+      # :SSLCertificateStore ::
+      #   A OpenSSL::X509::Store used for verification of certificates
+      #
+      # :SSLCertName ::
+      #   Issuer name for the certificate.  This is required when generating
+      #   the certificate (if :SSLCertificate and :SSLPrivateKey were not
+      #   given).  The value of this is to be an Array of pairs:
+      #
+      #     [["C", "Raleigh"], ["ST","North Carolina"],
+      #      ["CN","fqdn.example.com"]]
+      #
+      #   See also OpenSSL::X509::Name
+      #
+      # :SSLCertComment ::
+      #   A comment to be used for generating the certificate.  The default is
+      #   "Generated by Ruby/OpenSSL"
+      #
+      #
+      # === Example
+      #
+      # These values can be added after the fact, like a Hash.
+      #
+      #   require 'drb/ssl'
+      #   c = DRb::DRbSSLSocket::SSLConfig.new {}
+      #   c[:SSLCertificate] =
+      #     OpenSSL::X509::Certificate.new(File.read('mycert.crt'))
+      #   c[:SSLPrivateKey] = OpenSSL::PKey::RSA.new(File.read('mycert.key'))
+      #   c[:SSLVerifyMode] = OpenSSL::SSL::VERIFY_PEER
+      #   c[:SSLCACertificatePath] = "/etc/ssl/certs/"
+      #   c.setup_certificate
+      #
+      # or
+      #
+      #   require 'drb/ssl'
+      #   c = DRb::DRbSSLSocket::SSLConfig.new({
+      #           :SSLCertName => [["CN" => DRb::DRbSSLSocket.getservername]]
+      #           })
+      #   c.setup_certificate
+      #
       def initialize(config)
         @config  = config
         @cert    = config[:SSLCertificate]
@@ -37,10 +130,13 @@ module DRb
         @ssl_ctx = nil
       end
 
+      # A convenience method to access the values like a Hash
       def [](key);
         @config[key] || DEFAULT[key]
       end
 
+      # Connect to IO +tcp+, with context of the current certificate
+      # configuration
       def connect(tcp)
         ssl = ::OpenSSL::SSL::SSLSocket.new(tcp, @ssl_ctx)
         ssl.sync = true
@@ -48,6 +144,8 @@ module DRb
         ssl
       end
 
+      # Accept connection to IO +tcp+, with context of the current certificate
+      # configuration
       def accept(tcp)
         ssl = OpenSSL::SSL::SSLSocket.new(tcp, @ssl_ctx)
         ssl.sync = true
@@ -55,6 +153,9 @@ module DRb
         ssl
       end
 
+      # Ensures that :SSLCertificate and :SSLPrivateKey have been provided
+      # or that a new certificate is generated with the other parameters
+      # provided.
       def setup_certificate
         if @cert && @pkey
           return
@@ -100,6 +201,8 @@ module DRb
         @pkey = rsa
       end
 
+      # Establish the OpenSSL::SSL::SSLContext with the configuration
+      # parameters provided.
       def setup_ssl_context
         ctx = ::OpenSSL::SSL::SSLContext.new
         ctx.cert            = @cert
@@ -116,7 +219,12 @@ module DRb
       end
     end
 
-    def self.parse_uri(uri)
+    # Parse the dRuby +uri+ for an SSL connection.
+    #
+    # Expects drbssl://...
+    #
+    # Raises DRbBadScheme or DRbBadURI if +uri+ is not matching or malformed
+    def self.parse_uri(uri) # :nodoc:
       if uri =~ /^drbssl:\/\/(.*?):(\d+)(\?(.*))?$/
         host = $1
         port = $2.to_i
@@ -128,6 +236,15 @@ module DRb
       end
     end
 
+    # Return an DRb::DRbSSLSocket instance as a client-side connection,
+    # with the SSL connected.  This is called from DRb::start_service or while
+    # connecting to a remote object:
+    #
+    #   DRb.start_service 'drbssl://localhost:0', front, config
+    #
+    # +uri+ is the URI we are connected to,
+    # <code>'drbssl://localhost:0'</code> above, +config+ is our
+    # configuration.  Either a Hash or DRb::DRbSSLSocket::SSLConfig
     def self.open(uri, config)
       host, port, = parse_uri(uri)
       host.untaint
@@ -139,6 +256,15 @@ module DRb
       self.new(uri, ssl, ssl_conf, true)
     end
 
+    # Returns a DRb::DRbSSLSocket instance as a server-side connection, with
+    # the SSL connected.  This is called from DRb::start_service or while
+    # connecting to a remote object:
+    #
+    #   DRb.start_service 'drbssl://localhost:0', front, config
+    #
+    # +uri+ is the URI we are connected to,
+    # <code>'drbssl://localhost:0'</code> above, +config+ is our
+    # configuration.  Either a Hash or DRb::DRbSSLSocket::SSLConfig
     def self.open_server(uri, config)
       uri = 'drbssl://:0' unless uri
       host, port, = parse_uri(uri)
@@ -157,19 +283,35 @@ module DRb
       self.new(@uri, soc, ssl_conf, false)
     end
 
-    def self.uri_option(uri, config)
+    # This is a convenience method to parse +uri+ and separate out any
+    # additional options appended in the +uri+.
+    #
+    # Returns an option-less uri and the option => [uri,option]
+    #
+    # The +config+ is completely unused, so passing nil is sufficient.
+    def self.uri_option(uri, config) # :nodoc:
       host, port, option = parse_uri(uri)
       return "drbssl://#{host}:#{port}", option
     end
 
+    # Create a DRb::DRbSSLSocket instance.
+    #
+    # +uri+ is the URI we are connected to.
+    # +soc+ is the tcp socket we are bound to.
+    # +config+ is our configuration. Either a Hash or SSLConfig
+    # +is_established+ is a boolean of whether +soc+ is currenly established
+    #
+    # This is called automatically based on the DRb protocol.
     def initialize(uri, soc, config, is_established)
       @ssl = is_established ? soc : nil
       super(uri, soc.to_io, config)
     end
 
-    def stream; @ssl; end
+    # Returns the SSL stream
+    def stream; @ssl; end # :nodoc:
 
-    def close
+    # Closes the SSL stream before closing the dRuby connection.
+    def close # :nodoc:
       if @ssl
         @ssl.close
         @ssl = nil
@@ -177,7 +319,7 @@ module DRb
       super
     end
 
-    def accept
+    def accept # :nodoc:
       begin
       while true
         soc = @socket.accept
@@ -195,8 +337,6 @@ module DRb
         retry
       end
     end
-
-    # :stopdoc:
   end
 
   DRbProtocol.add_protocol(DRbSSLSocket)