t2-server 0.9.1 → 0.9.2

data/CHANGES.rdoc

@@ -1,5 +1,22 @@
 = Changes log for the T2 Ruby Gem
 
+== Version 0.9.2
+
+* Cleanup of the README and some delete additions.
+* Complete documentation coverage.
+* Update the parsing of the server version.
+* Optimize Server object creation.
+* Add URI manipulating methods to T2Server::Util.
+* Internal updates to use full URIs rather than relative paths.
+* Updates to the administrator interface to use full URIs.
+* URI code updates for secure workflow and permissions support.
+* Remove (deprecate) Server#delete_run.
+* Support direct PUT of data for newer versions of server.
+* Update the documentation of the Connection classes.
+* Minor updates to the top-level README.
+* Cleanup of t2-server-info script.
+* t2-run-workflow: Only print outputs if there are any.
+
 == Version 0.9.1
 
 * Update unit test code for Ruby 1.9 compatibility.

data/README.rdoc

@@ -1,7 +1,7 @@
 = Taverna[http://www.taverna.org.uk/] 2 Server Interaction Gem
 
 Authors::     Robert Haines
-Contact::     mailto:rhaines@manchester.ac.uk
+Contact::     mailto:support@mygrid.org.uk
 URL::         http://www.taverna.org.uk/
 Licence::     BSD (See LICENCE or http://www.opensource.org/licenses/bsd-license.php)
 Copyright::   (c) 2010-2012 The University of Manchester, UK
@@ -37,8 +37,8 @@ This version of the library should be compatible with any Ruby code that you
 may have already written against earlier versions but you may see some warnings
 about API deprecations. These are clearly marked [DEPRECATION] and will appear
 on your console output. Anything marked as deprecated will be removed in
-version 1.0.0 so you are advised to update your code at your earliest
-convenience.
+version 1.0.0 (and are not guaranteed to continue working even until then) so
+you are advised to update your code at your earliest convenience.
 
 == Compatibility with Ruby versions
 
@@ -49,7 +49,7 @@ This library is known to work with the following versions of Ruby:
 * jruby 1.6.4 (in Ruby 1.8 mode)
 
 Those marked with an asterisk (*) are supported and bugs found against them
-will be fixed. Other versions may work but are not supported.
+will be fixed. Other versions may work but are not tested or supported.
 
 == Usage
 
@@ -60,7 +60,7 @@ There are two entry points for the T2Server API:
 
 In both cases the gem should be initialized by requiring the top level ruby
 file:
-  require 't2-server.rb'
+  require 't2-server'
 
 === Configuring a Server connection
 
@@ -71,11 +71,11 @@ connection.
 
 Connection configuration settings are passed in to various methods using the
 +ConnectionParameters+ class. Parameters that can be set are:
-* <tt>:ca_file</tt>
-* <tt>:ca_path</tt>
-* <tt>:verify_peer</tt>
-* <tt>:client_certificate</tt>
-* <tt>:client_password</tt>
+* <tt>:ca_file</tt> - A file to use as a Certificate Authority (CA) for self-signed server certificates.
+* <tt>:ca_path</tt> - Path or list of paths to directories of CA certificates.
+* <tt>:verify_peer</tt> - Use a CA to verify that the Taverna Server you are connecting to has a valid server certificate and that it is the correct one.
+* <tt>:client_certificate</tt> - A certificate to use for client certificate authentication.
+* <tt>:client_password</tt> - The password to unlock the private key of the client certificate.
 
 And can be set like this for a standard https connection:
 
@@ -83,7 +83,7 @@ And can be set like this for a standard https connection:
   conn_params[:verify_peer] = true
 
 This will ensure that the identity of the Taverna Server you are connecting to
-will be verified using the set of certificates in <tt>/etc/ssl/certs</tt>.
+will be verified using the default set of certificates for your platform.
 <tt>:ca_path</tt> can also be set to a list of paths if required. You do not
 need to include your platform's default certificate paths as these are included
 automatically.
@@ -117,6 +117,21 @@ Note that credentials are not required by default to simply connect to a
 Taverna Server. Further operations (such as creating and starting runs) may
 require authorization depending on how your server has been set up.
 
+To create a Run on a Server simply pass the workflow you wish to run and your
+credentials:
+
+  server.create_run(workflow, credentials) do |run|
+    ...
+  end
+
+An individual run can be deleted with its own <tt>delete</tt> method (see below)
+but all runs on a server can be deleted in one go:
+
+  server.delete_all_runs(credentials)
+
+Note that you can only delete runs for which your credentials have delete
+authorization. See later for details.
+
 === Run API example
 
 You can bypass the Server API if you know you are only going to be dealing with
@@ -169,6 +184,10 @@ But make sure you request baclava output *before* starting the run:
   run.wait
   output = run.baclava_output
 
+A run can be deleted when no longer needed, like so:
+
+  run.delete
+
 See the rdoc for more information. Many methods and classes have much more
 functionality than the defaults described above. Please note that anything
 which does not appear in the documentation is not intended to be part of the
@@ -239,9 +258,9 @@ WSDL address of the service with your username and password:
 
 ==== R Servers (via Rshells)
 
-You can authenticate to R Servers in almost exactly the same as for
+You can authenticate to R Servers in almost exactly the same way as for
 REST services - only the protocol scheme is different. So instead of
-http or https it is rserve:
++http+ or +https+ it is +rserve+:
 
  run.add_password_credential("rserve://example.com:6311", "username", "password")
 

data/bin/t2-run-workflow

@@ -175,13 +175,16 @@ begin
         puts "Zip file written to '#{options[:zip_out]}'"
       else
         # go through the outputs and print them out
-        puts "Outputs:"
-        run.output_ports.each_value do |port|
-          print "    #{port.name} (#{port.depth}) -> "
-          if options[:output_refs]
-            p port.reference
-          else
-            p port.value
+        outputs = run.output_ports
+        unless outputs.empty?
+          puts "Outputs:"
+          outputs.each_value do |port|
+            print "    #{port.name} (#{port.depth}) -> "
+            if options[:output_refs]
+              p port.reference
+            else
+              p port.value
+            end
           end
         end
       end

data/bin/t2-server-info

@@ -56,11 +56,11 @@ uri, creds = parse_address(ARGV.shift, creds)
 # connect to server and output information
 begin
   T2Server::Server.new(uri, conn_params) do |server|
-    print "     Server: #{server.uri}\n"
-    print "    Version: #{server.version}\n"
-    print "  Run limit: #{server.run_limit(creds)}\n"
+    puts "     Server: #{server.uri}"
+    puts "    Version: #{server.version}"
+    puts "  Run limit: #{server.run_limit(creds)}"
     runs = server.runs(creds)
-    print "No. of runs: #{runs.length}\n"
+    puts "No. of runs: #{runs.length}"
     if options[:list] && runs.length > 0
       puts (Hirb::Helpers::ObjectTable.render runs,
         :fields=>[:identifier, :status, :expiry],

data/lib/t2-server.rb

@@ -49,6 +49,8 @@ require 't2-server/admin'
 # * T2Server::Server - Use this if you are providing a web interface to a
 #   Taverna 2 Server instance.
 module T2Server
+
+  # Library version information.
   module Version
     # Version information in a Hash
     INFO = YAML.load_file(File.join(File.dirname(__FILE__), "..",

data/lib/t2-server/admin.rb

@@ -46,11 +46,14 @@ module T2Server
     attr_reader :resources
 
     # :stopdoc:
+    ADMIN_ENDPOINT = "admin"
+
     def initialize(server, credentials = nil)
       @server = server
+      @uri = Util.append_to_uri_path(server.uri, ADMIN_ENDPOINT)
       @credentials = credentials
 
-      admin_description = xml_document(@server.get_admin_attribute("",
+      admin_description = xml_document(@server.read(@uri, "application/xml",
         @credentials))
       @resources = get_resources(admin_description)
       #@resources.each {|key, value| puts "#{key}: #{value}"}
@@ -68,12 +71,12 @@ module T2Server
     end
 
     # :stopdoc:
-    def get_resource_value(path)
-      @server.get_admin_attribute(path, @credentials)
+    def get_resource_value(uri)
+      @server.read(uri, "text/plain", @credentials)
     end
 
-    def set_resource_value(path, val)
-      @server.set_admin_attribute(path, val.to_s, @credentials)
+    def set_resource_value(uri, val)
+      @server.update(uri, val.to_s, "text/plain", @credentials)
     end
     # :startdoc:
 
@@ -82,10 +85,9 @@ module T2Server
       links = {}
 
       xml_children(doc.root) do |res|
-        path = xml_node_attribute(res, 'href').split('/')[-1]
-        write = @server.admin_resource_writable?(path, @credentials)
-        links[res.name.downcase] = AdminResource.new(res.name, path,
-          write, self)
+        uri = URI.parse(xml_node_attribute(res, 'href'))
+        write = @server.is_resource_writable?(uri, @credentials)
+        links[res.name.downcase] = AdminResource.new(res.name, uri, write, self)
       end
 
       links
@@ -100,13 +102,13 @@ module T2Server
       # The name of this resource.
       attr_reader :name
 
-      # The path to this resource on the server.
-      attr_reader :path
+      # The URI of this resource on the server.
+      attr_reader :uri
 
       # :stopdoc:
-      def initialize(name, path, writeable, parent)
+      def initialize(name, uri, writeable, parent)
         @name = name
-        @path = path
+        @uri = uri
         @admin = parent
         @writeable = writeable
 
@@ -123,7 +125,7 @@ module T2Server
       #
       # The resource can only be set if it is writable.
       def value
-        @admin.get_resource_value(@path)
+        @admin.get_resource_value(@uri)
       end
 
       # :call-seq:
@@ -138,7 +140,7 @@ module T2Server
       def make_writable
         (class << self; self; end).instance_eval do
           define_method "value=" do |value|
-            @admin.set_resource_value(@path, value)
+            @admin.set_resource_value(@uri, value)
           end
         end
       end

data/lib/t2-server/exceptions.rb

@@ -66,6 +66,8 @@ module T2Server
   # way. This could be due to the server not accepting the connection, the
   # connection being dropped unexpectedly or a timeout of some sort.
   class ConnectionError < T2ServerError
+
+    # The internal cause of this connection error.
     attr_reader :cause
 
     # Create a new ConnectionError with the specified cause. The cause to be
@@ -94,6 +96,8 @@ module T2Server
   # expectation is that the run exists then it could have been destroyed by
   # a timeout or another user.
   class RunNotFoundError < T2ServerError
+
+    # The identifier of the run that was not found on the server.
     attr_reader :identifier
 
     # Create a new RunNotFoundError with the specified identifier.
@@ -106,6 +110,8 @@ module T2Server
   # Indicates that the attribute that the user is trying to read/change does
   # not exist. The attribute could be a server or run attribute.
   class AttributeNotFoundError < T2ServerError
+
+    # The path of the attribute that was not found on the server.
     attr_reader :path
 
     # Create a new AttributeNotFoundError with the path to the erroneous
@@ -128,6 +134,8 @@ module T2Server
   # Access to the entity (run or attribute) is denied. The credentials
   # supplied are not sufficient or the server does not allow the operation.
   class AccessForbiddenError < T2ServerError
+
+    # The path of the attribute that the user is forbidden to access.
     attr_reader :path
 
     # Create a new AccessForbiddenError with the path to the restricted
@@ -142,6 +150,8 @@ module T2Server
 
   # Access to the server is denied to this username
   class AuthorizationError < T2ServerError
+
+    # The username that has failed authorization.
     attr_reader :username
 
     # Create a new AuthorizationError with the rejected username

data/lib/t2-server/net/connection.rb

@@ -98,84 +98,18 @@ module T2Server
     end
 
     # :call-seq:
-    #   POST_run(path, value, credentials) -> String
+    #   GET(uri, type, range, credentials) -> String
     #
-    # Initialize a T2Server::Run on a server by uploading its workflow.
-    # The new run's identifier (in String form) is returned.
-    def POST_run(path, value, credentials)
-      response = _POST(path, value, "application/xml", credentials)
-
-      case response
-      when Net::HTTPCreated
-        # return the identifier of the newly created run
-        path_leaf_from_uri(response['location'])
-      when Net::HTTPForbidden
-        raise ServerAtCapacityError.new
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
-      else
-        raise UnexpectedServerResponse.new(response)
-      end
-    end
-
-    # :call-seq:
-    #   POST_file(path, value, run, credentials) -> bool
-    #
-    # Upload a file to a run. If successful, true is returned.
-    def POST_file(path, value, run, credentials)
-      response = _POST(path, value, "application/xml", credentials)
-
-      case response
-      when Net::HTTPCreated
-        # OK, carry on...
-        true
-      when Net::HTTPNotFound
-        raise RunNotFoundError.new(run)
-      when Net::HTTPForbidden
-        raise AccessForbiddenError.new("run #{run}")
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
-      else
-        raise UnexpectedServerResponse.new(response)
-      end
-    end
-
-    # :call-seq:
-    #   POST_dir(path, value, run, dir, credentials) -> bool
-    #
-    # Create a directory in the scratch space of a run. If successful, true
-    # is returned.
-    def POST_dir(path, value, run, dir, credentials)
-      response = _POST(path, value, "application/xml", credentials)
-
-      case response
-      when Net::HTTPCreated
-        # OK, carry on...
-        true
-      when Net::HTTPNotFound
-        raise RunNotFoundError.new(run)
-      when Net::HTTPForbidden
-        raise AccessForbiddenError.new("#{dir} on run #{run}")
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
-      else
-        raise UnexpectedServerResponse.new(response)
-      end
-    end
-
-    # :call-seq:
-    #   GET(path, type, range, credentials) -> String
-    #
-    # HTTP GET a resource at _path_ of _type_ from the server. If successful
+    # HTTP GET a resource at _uri_ of _type_ from the server. If successful
     # the body of the response is returned. A portion of the data can be
     # retrieved by specifying a byte range, start..end, with the _range_
     # parameter.
-    def GET(path, type, range, credentials)
-      get = Net::HTTP::Get.new(path)
+    def GET(uri, type, range, credentials)
+      get = Net::HTTP::Get.new(uri.path)
       get["Accept"] = type
       get["Range"] = "bytes=#{range.min}-#{range.max}" unless range.nil?
 
-      response = submit(get, path, credentials)
+      response = submit(get, uri, credentials)
 
       case response
       when Net::HTTPOK, Net::HTTPPartialContent
@@ -186,9 +120,9 @@ module T2Server
         new_conn = redirect(response["location"])
         raise ConnectionRedirectError.new(new_conn)
       when Net::HTTPNotFound
-        raise AttributeNotFoundError.new(path)
+        raise AttributeNotFoundError.new(uri.path)
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("attribute #{path}")
+        raise AccessForbiddenError.new("attribute #{uri.path}")
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
@@ -197,25 +131,37 @@ module T2Server
     end
 
     # :call-seq:
-    #   PUT(path, value, type, credentials) -> bool
+    #   PUT(uri, value, type, credentials) -> bool
+    #   PUT(uri, value, type, credentials) -> URI
     #
-    # Perform a HTTP PUT of _value_ to a path on the server. If successful
-    # true is returned.
-    def PUT(path, value, type, credentials)
-      put = Net::HTTP::Put.new(path)
+    # Perform a HTTP PUT of _value_ to a location on the server specified by
+    # _uri_ . If successful _true_ , or a URI to the PUT resource, is returned
+    # depending on whether the operation has set a parameter (true) or uploaded
+    # data (URI).
+    def PUT(uri, value, type, credentials)
+      put = Net::HTTP::Put.new(uri.path)
       put.content_type = type
       put.body = value
 
-      response = submit(put, path, credentials)
+      response = submit(put, uri, credentials)
 
       case response
       when Net::HTTPOK
-        # OK, so carry on
+        # We've set a parameter so we get 200 back from the server. Return
+        # true to indicate success.
         true
+      when Net::HTTPCreated
+        # We've uploaded data so we get 201 back from the server. Return the
+        # uri of the created resource.
+        URI.parse(response['location'])
+      when Net::HTTPNoContent
+        # We've modified data so we get 204 back from the server. Return the
+        # uri of the modified resource.
+        uri
       when Net::HTTPNotFound
-        raise AttributeNotFoundError.new(path)
+        raise AttributeNotFoundError.new(uri.path)
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("attribute #{path}")
+        raise AccessForbiddenError.new("attribute #{uri.path}")
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
@@ -224,21 +170,29 @@ module T2Server
     end
 
     # :call-seq:
-    #   POST(path, value, type, credentials)
+    #   POST(uri, value, type, credentials)
     #
-    # Perform an HTTP POST of _value_ to a path on the server and return the
-    # identifier of the created attribute as a string.
-    def POST(path, value, type, credentials)
-      response = _POST(path, value, type, credentials)
+    # Perform an HTTP POST of _value_ to a location on the server specified by
+    # _uri_ and return the URI of the created attribute.
+    def POST(uri, value, type, credentials)
+      post = Net::HTTP::Post.new(uri.path)
+      post.content_type = type
+      post.body = value
+
+      response = submit(post, uri, credentials)
 
       case response
       when Net::HTTPCreated
-        # return the identifier of the newly created item
-        path_leaf_from_uri(response['location'])
+        # return the URI of the newly created item
+        URI.parse(response['location'])
       when Net::HTTPNotFound
-        raise AttributeNotFoundError.new(path)
+        raise AttributeNotFoundError.new(uri.path)
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("attribute #{path}")
+        if response.body.chomp.include? "server load exceeded"
+          raise ServerAtCapacityError.new
+        else
+          raise AccessForbiddenError.new("attribute #{uri.path}")
+        end
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
@@ -247,24 +201,23 @@ module T2Server
     end
 
     # :call-seq:
-    #   DELETE(path, credentials) -> bool
+    #   DELETE(uri, credentials) -> bool
     #
-    # Perform an HTTP DELETE on a path on the server. If successful true
+    # Perform an HTTP DELETE on a _uri_ on the server. If successful true
     # is returned.
-    def DELETE(path, credentials)
-      run = path.split("/")[-1]
-      delete = Net::HTTP::Delete.new(path)
+    def DELETE(uri, credentials)
+      delete = Net::HTTP::Delete.new(uri.path)
 
-      response = submit(delete, path, credentials)
+      response = submit(delete, uri, credentials)
 
       case response
       when Net::HTTPNoContent
         # Success, carry on...
         true
       when Net::HTTPNotFound
-        raise RunNotFoundError.new(run)
+        false
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("run #{run}")
+        raise AccessForbiddenError.new(uri)
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
@@ -273,20 +226,20 @@ module T2Server
     end
 
     # :call-seq:
-    #   OPTIONS(path, credentials) -> Hash
+    #   OPTIONS(uri, credentials) -> Hash
     #
-    # Perform the HTTP OPTIONS command on the given _path_ and return a hash
+    # Perform the HTTP OPTIONS command on the given _uri_ and return a hash
     # of the headers returned.
-    def OPTIONS(path, credentials)
-      options = Net::HTTP::Options.new(path)
+    def OPTIONS(uri, credentials)
+      options = Net::HTTP::Options.new(uri.path)
 
-      response = submit(options, path, credentials)
+      response = submit(options, uri, credentials)
 
       case response
       when Net::HTTPOK
         response.to_hash
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("resource #{path}")
+        raise AccessForbiddenError.new("resource #{uri.path}")
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
@@ -295,26 +248,13 @@ module T2Server
     end
 
     private
-    def _POST(path, value, type, credentials)
-      post = Net::HTTP::Post.new(path)
-      post.content_type = type
-      post.body = value
-
-      submit(post, path, credentials)
-    end
-
-    def path_leaf_from_uri(uri)
-      URI.parse(uri).path.split('/')[-1]
-    end
 
-    def submit(request, path, credentials)
-      full_uri = @uri.clone
-      full_uri.path = path
+    def submit(request, uri, credentials)
 
       credentials.authenticate(request) unless credentials.nil?
 
       begin
-        @http.request(full_uri, request)
+        @http.request(uri, request)
       rescue InternalHTTPError => e
         raise ConnectionError.new(e)
       end