sudo 0.0.2 → 0.1.0

data/MANIFEST

@@ -0,0 +1,15 @@
+examples/block.rb
+examples/dsl.rb
+examples/new.rb
+libexec/server.rb
+lib/sudo/constants.rb
+lib/sudo/dsl.rb
+lib/sudo/proxy.rb
+lib/sudo.rb
+lib/sudo/support/kernel.rb
+lib/sudo/support/object.rb
+lib/sudo/support/process.rb
+lib/sudo/system.rb
+lib/sudo/wrapper.rb
+MANIFEST
+README.rdoc

data/README.rdoc

@@ -1,4 +1,4 @@
-= Ruby Sudo
+= Ruby \Sudo
 
 Give Ruby objects superuser privileges.
 
@@ -17,53 +17,51 @@ the +NOPASSWD+ options in +/etc/sudoers+.
 
 == USAGE
 
-=== DSL style
+Let's start with a trivial example:
 
-  require 'fileutils'
+  require 'mygem/myclass'
   require 'sudo'
 
-  include Sudo::DSL
+  obj   = MyGem::MyClass.new
 
-  # The String will be passed as options to sudo-ed Ruby interpreter
-  sudo_start "-rfileutils"
 
-  # only readable by root
-  puts sudo(File).read '/etc/shadow'
+Now, create a Sudo::Wrapper object:
 
-  # write into the / 
-  sudo(FileUtils).mkdir_p '/TEST_DIR/SUB_DIR' 
+  sudo  = Sudo::Wrapper.new
 
-  # Stop the dRuby server (whish is running as root), as soon as you can
-  sudo_stop
 
-=== Explicit creation of a Wrapper object, block given
+Start the sudo-ed Ruby process:
 
-  require 'fileutils'
-  require 'sudo'
+  # 'mygem/myclass' will be automatically required in the 
+  # sudo DRb server 
 
-  Sudo::Wrapper.run('-rfileutils) do |su|
-    # here you use square brackets [] :
-    # su is an object, not a (top-level) method.
-    su[FileUtils].mkdir_p '/ONLY/ROOT/CAN/DO/THAT'
-  end
-  # Sockets and processes are closed automatically when the block exits
+  sudo.start! 
 
-=== Explicit creation of a Wrapper object, without block
 
-  require 'mygem/myclass'
-  require 'sudo'
+Use it!
 
-  obj   = MyGem::MyClass.new
-  
-  sudo  = Sudo::Wrapper.new(-rmygem/myclass -rmygem/myclass2)
-  
-  sudo.start!
+  sudo[obj].my_instance_method 
+  sudo[MyClass].my_class_method
 
-  sudo[obj].method # will be run as root (well, a sudo-ed copy) 
 
-  # when you've done:
+When you've done, {stop!}[link:Sudo/Wrapper.html#method-i-stop!] it. 
+Otherwise, that will be done (only) when the +sudo+ object gets 
+garbage-collected.
+
   sudo.stop!
 
+=== With a block
+
+Use Sudo::Wrapper::run in this case.
+
+  require 'fileutils'
+  require 'sudo'
+
+  Sudo::Wrapper.run do |sudo|
+    sudo[FileUtils].mkdir_p '/ONLY/ROOT/CAN/DO/THAT'
+  end
+  # Sockets and processes are closed automatically when the block exits
+
 == PRINCIPLES OF OPERATION
 
 Spawns a sudo-ed Ruby process running a 
@@ -76,10 +74,8 @@ Access control is entirely delegated to +sudo+.
 
 == TODO
 
-* +sudo+ has a +-A+ option to accept password via an external program
-  (maybe graphical): support this feature.
-
-* more options in Sudo::Wrapper.new, maybe a Hash.
++sudo+ has a +-A+ option to accept password via an external program
+(maybe graphical): support this feature.
 
 == THANKS
 
@@ -88,13 +84,35 @@ ruby-talk[http://www.ruby-forum.com/topic/262655].
 
 == AUTHOR
 
-Copyright (c) 2010 {Guido De Rosa}[http://github.com/gderosa/].
+{Guido De Rosa}[http://github.com/gderosa/].
 
 Sponsored by {VEMAR s.a.s.}[http://www.vemarsas.it/] 
 
-== LICENSE
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Guido De Rosa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-Ruby's.
 
 
 

data/examples/block.rb

@@ -1,7 +1,7 @@
 require 'fileutils'
 require 'sudo'
 
-Sudo::Wrapper.run('-rfileutils') do |su|
+Sudo::Wrapper.run do |su|
 
   su[File].open '/TEST', 'w' do |f|
     f.puts "Hello from UID=#{su[Process].uid}!"

data/examples/dsl.rb

@@ -1,4 +1,5 @@
-require 'sudo'
+=begin
+require 'sudo/dsl'
 
 include Sudo::DSL
 
@@ -10,4 +11,4 @@ sudo(FileUtils).mkdir_p '/TEST_DIR/SUB_DIR'
 
 #sudo_stop # automatic clenup, when out of scope, if not explicit
 
-
+=end

data/examples/new.rb

@@ -1,20 +1,24 @@
 require 'fileutils'
+autoload :IPAddr, 'ipaddr'
 require 'sudo'
 
-su = Sudo::Wrapper.new('-rfileutils')
+# Requires and autoloads are inherited by the sudo process.
+
+su = Sudo::Wrapper.new
 
 su.start!
 
 su[File].open '/TEST', 'w' do |f|
   f.puts "Hello from UID=#{su[Process].uid}!"
+  f.puts "#{su[IPAddr].new}"
 end
 
 su[FileUtils].cp '/etc/shadow', '/etc/shadow2'
 
-# i you don't call stop! explicitly, the corresponding process and file
-# cleanup will be done automatically, when the object gets out of scope
+# If you don't call stop! explicitly, the corresponding process and file
+# cleanup will be done when su gets garbage-collected.
 #
-# su.stop!
+su.stop!
 
 
 

data/lib/sudo.rb

@@ -1,44 +1,2 @@
-require 'drb/drb'
-require 'sudo/support/kernel'
-require 'sudo/support/object'
-require 'sudo/support/process'
 require 'sudo/wrapper'
 
-module Sudo
-
-  VERSION       = '0.0.2'
-  ROOTDIR       = File.expand_path File.join File.dirname(__FILE__), '..'
-  LIBDIR        = File.join ROOTDIR, 'lib'
-  SERVER_SCRIPT = File.join ROOTDIR, 'libexec/server.rb'
-
-  class RuntimeError  < RuntimeError; end
-
-  module DSL
-    def sudo_start(*args, &blk)
-      @__default_sudo_wrapper = Sudo::Wrapper.new(*args, &blk).start!
-    end
-    def sudo_stop
-      @__default_sudo_wrapper.stop!
-    end
-    def sudo(object)
-      @__default_sudo_wrapper[object]
-    end
-  end
-
-  class MethodProxy
-    def initialize(object, proxy)
-      @object = object
-      @proxy = proxy
-    end
-    def method_missing(method=:self, *args, &blk)
-      @proxy.proxy @object, method, *args, &blk
-    end
-  end
-
-  class Proxy
-    def proxy(object, method=:self, *args, &blk) 
-      object.send method, *args, &blk
-    end
-  end
-
-end

data/lib/sudo/constants.rb

@@ -0,0 +1,10 @@
+module Sudo
+
+  VERSION       = '0.1.0'
+  ROOTDIR       = File.expand_path File.join File.dirname(__FILE__), '../..'
+  LIBDIR        = File.join ROOTDIR, 'lib'
+  SERVER_SCRIPT = File.join ROOTDIR, 'libexec/server.rb'
+
+  class RuntimeError  < RuntimeError; end
+
+end

data/lib/sudo/dsl.rb

@@ -0,0 +1,27 @@
+=begin
+  DEPRECATED
+
+  It's not clear what the scope of __default_sudo_wrapper should be:
+  local, instance, class? global? and what about thread-safety?
+
+=end
+
+=begin
+require 'sudo/wrapper'
+
+module Sudo
+
+  module DSL
+    def sudo_start(*args, &blk)
+      @__default_sudo_wrapper = Sudo::Wrapper.new(*args, &blk).start!
+    end
+    def sudo_stop
+      @__default_sudo_wrapper.stop!
+    end
+    def sudo(object)
+      @__default_sudo_wrapper[object]
+    end
+  end
+
+end
+=end

data/lib/sudo/proxy.rb

@@ -0,0 +1,21 @@
+require 'sudo/support/object'
+
+module Sudo
+
+  class MethodProxy
+    def initialize(object, proxy)
+      @object = object
+      @proxy = proxy
+    end
+    def method_missing(method=:self, *args, &blk)
+      @proxy.proxy @object, method, *args, &blk
+    end
+  end
+
+  class Proxy
+    def proxy(object, method=:self, *args, &blk) 
+      object.send method, *args, &blk
+    end
+  end
+
+end

data/lib/sudo/system.rb

@@ -0,0 +1,36 @@
+require 'sudo/support/process'
+require 'sudo/constants'
+
+module Sudo
+  module System
+
+    class ProcessStillExists  < RuntimeError; end
+    class FileStillExists     < RuntimeError; end
+
+    class << self
+
+      def kill(pid)
+        if pid and Process.exists? pid
+          system "sudo kill     #{pid}"               or
+          system "sudo kill -9  #{pid}"               or
+          raise ProcessStillExists, 
+            "Couldn't kill sudo process (PID=#{pid})" 
+        end
+      end
+
+      def unlink(file)
+        if file and File.exists? file
+          system "sudo rm -f #{file}"                 or
+          raise FileStillExists,
+              "Couldn't delete #{file}"
+        end
+      end
+
+      # just to check if we can sudo; and we'll receive a sudo token
+      def check
+        raise SudoFailed unless system "sudo ruby -e ''"
+      end
+
+    end
+  end
+end

data/lib/sudo/wrapper.rb

@@ -1,7 +1,9 @@
 require 'drb/drb'
 require 'sudo/support/kernel'
-require 'sudo/support/object'
 require 'sudo/support/process'
+require 'sudo/constants'
+require 'sudo/system'
+require 'sudo/proxy'
 
 begin
   DRb.current_server
@@ -15,10 +17,8 @@ module Sudo
     class RuntimeError              < RuntimeError;       end
     class NotRunning                < RuntimeError;       end
     class SudoFailed                < RuntimeError;       end
-    class SocketStillExists         < RuntimeError;       end
     class SudoProcessExists         < RuntimeError;       end
     class SudoProcessAlreadyExists  < SudoProcessExists;  end
-    class SudoProcessStillExists    < RuntimeError;       end
     class NoValidSocket             < RuntimeError;       end
     class SocketNotFound            < NoValidSocket;      end
     class NoValidSudoPid            < RuntimeError;       end
@@ -26,45 +26,51 @@ module Sudo
 
     class << self
 
-      # with blocks
-      def run(*args)
-        sudo = new(*args)
-        yield sudo.start!
+      # Yields a new running Sudo::Wrapper, and do all the necessary
+      # cleanup when the block exits. 
+      #
+      # ruby_opts:: is passed to Sudo::Wrapper::new .      
+      def run(ruby_opts) # :yields: sudo
+        sudo = new(ruby_opts).start!
+        yield sudo
         sudo.stop!
       end 
 
-      # Not an instance method, so it may act as a finalizer
-      # (as in ObjectSpace.define_finalizer)
+      # currently unused
+      #def load_features
+      #  ObjectSpace.each_object(self).each{|x| x.load_features} 
+      #end
+
+      protected
+
+      # Do the actual resources clean-up.
+      #
+      # Not an instance method, so it may act as a Finalizer
+      # (as in ::ObjectSpace::define_finalizer)
       def cleanup!(h)
-        if h[:pid] and Process.exists? h[:pid]
-          system "sudo kill     #{h[:pid]}"               or
-          system "sudo kill -9  #{h[:pid]}"               or
-          raise SudoProcessStillExists, 
-            "Couldn't kill sudo process (PID=#{h[:pid]})" 
-        end
-        if h[:socket] and File.exists? h[:socket]
-          system "sudo rm -f #{h[:socket]}"               or
-          raise SocketStillExists,
-              "Couldn't delete socket #{h[:socket]}"
-        end
+        Sudo::System.kill   h[:pid]
+        Sudo::System.unlink h[:socket]
       end
 
     end
 
+    # +ruby_opts+ are the command line options to the sudo ruby interpreter;
+    # usually you don't need to specify stuff like "-rmygem/mylib", libraries
+    # will be sorta "inherited". 
     def initialize(ruby_opts='') 
-      @proxy      = nil
-      @socket     = "/tmp/rubysu-#{Process.pid}-#{object_id}" 
-      @sudo_pid   = nil
-      @ruby_opts  = ruby_opts
+      @proxy            = nil
+      @socket           = "/tmp/rubysu-#{Process.pid}-#{object_id}" 
+      @sudo_pid         = nil
+      @ruby_opts        = ruby_opts
+      @loaded_features  = []
+      # @load_path        = [] # currentl unused
     end
 
     def server_uri; "drbunix:#{@socket}"; end
     
+    # Start the sudo-ed Ruby process.
     def start! 
-      # just to check if we can sudo; and we'll receive a sudo token
-      raise SudoFailed unless system "sudo ruby -e ''"
-
-      raise SudoProcessAlreadyExists if @sudo_pid and Process.exists? @sudo_pid
+      Sudo::System.check
       
       @sudo_pid = spawn( 
 "sudo ruby -I#{LIBDIR} #{@ruby_opts} #{SERVER_SCRIPT} #{@socket} #{Process.uid}"
@@ -79,9 +85,34 @@ module Sudo
       else
         raise RuntimeError, "Couldn't create DRb socket #{@socket}"  
       end
+
+      #set_load_path # apparently, we don't need this
+      
+      load_features
+
       self
     end
 
+    # apparently, we don't need this
+    #def set_load_path
+    #  ($LOAD_PATH - @load_path).reverse.each do |dir|
+    #    @proxy.proxy Kernel, :eval, "$LOAD_PATH.unshift #{dir}"
+    #  end
+    #end 
+
+    # Load needed libraries in the DRb server. Usually you don't need
+    # to call this directly.
+    def load_features
+      unless $LOADED_FEATURES == @loaded_features
+        new_features = $LOADED_FEATURES - @loaded_features
+        new_features.each do |feature|
+          @proxy.proxy Kernel, :require, feature
+          @loaded_features << feature
+        end
+        #@loaded_features += new_features
+      end
+    end
+
     def running?
       true if (
         @sudo_pid and Process.exists? @sudo_pid and
@@ -90,21 +121,26 @@ module Sudo
       )
     end
 
+    # Free the resources opened by this Wrapper: e.g. the sudo-ed
+    # ruby process and the Unix-domain socket used to communicate
+    # to it via ::DRb.
     def stop!
       self.class.cleanup!(:pid => @sudo_pid, :socket => @socket)
       @proxy = nil
-
     end
-
+ 
+    # Gives a copy of +object+ with root privileges.
     def [](object)
       if running?
+        load_features
         MethodProxy.new object, @proxy
       else
         raise NotRunning
       end
     end
 
-    # Inspired by Remover class in tmpfile.rb (Ruby std library)
+    # Inspired by Remover class in tmpfile.rb (Ruby std library).
+    # You don't want to use this class directly.
     class Finalizer
       def initialize(h)
         @data = h
@@ -118,3 +154,4 @@ module Sudo
 
   end
 end
+

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Guido De Rosa
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-22 00:00:00 +02:00
+date: 2010-10-25 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -31,15 +31,20 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 files: 
-- lib/sudo/support/object.rb
-- lib/sudo/support/kernel.rb
-- lib/sudo/support/process.rb
-- lib/sudo/wrapper.rb
-- lib/sudo.rb
-- libexec/server.rb
 - examples/block.rb
 - examples/dsl.rb
 - examples/new.rb
+- libexec/server.rb
+- lib/sudo/constants.rb
+- lib/sudo/dsl.rb
+- lib/sudo/proxy.rb
+- lib/sudo.rb
+- lib/sudo/support/kernel.rb
+- lib/sudo/support/object.rb
+- lib/sudo/support/process.rb
+- lib/sudo/system.rb
+- lib/sudo/wrapper.rb
+- MANIFEST
 - README.rdoc
 has_rdoc: true
 homepage: http://github.com/gderosa/rubysu