t2-server 0.9.3 → 1.0.0

data/lib/t2-server-cli.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2013 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -50,27 +50,8 @@ module T2Server
         end
 
         # SSL options
-        opt.on("-E CERT_FILE:PASSWORD", "--cert=CERT_FILE:PASSWORD", "Use " +
-          "the specified certificate file for client authentication. If the " +
-          "optional password is not provided it will be asked for on the " +
-          "command line. Must be in PEM format.") do |val|
-            cert, cpass = val.chomp.split(":", 2)
-            conn_params[:client_certificate] = cert
-            conn_params[:client_password] = cpass if cpass
-        end
-        opt.on("--cacert=CERT_FILE", "Use the specified certificate file to " +
-          "verify the peer. Must be in PEM format.") do |val|
-            conn_params[:ca_file] = val.chomp
-        end
-        opt.on("--capath=CERTS_PATH", "Use the specified certificate " +
-          "directory to verify the peer. Certificates must be in PEM " +
-          "format") do |val|
-            conn_params[:ca_path] = val.chomp
-        end
-        opt.on("-k", "--insecure", "Allow insecure connections: no peer " +
-          "verification.") do
-            conn_params[:verify_peer] = false
-        end
+        ssl_auth_opts(opt, conn_params)
+        ssl_transport_opts(opt, conn_params)
 
         # common options
         opt.on_tail("-u", "--username=USERNAME", "The username to use for " +
@@ -100,7 +81,7 @@ module T2Server
 
     # separate the creds if they are supplied in the uri
     def parse_address(address, creds)
-      if address == nil or address == ""
+      if address == nil || address == ""
         puts @opts
         exit 1
       end
@@ -112,5 +93,49 @@ module T2Server
     def opts
       @opts
     end
+
+    private
+
+    # The SSL authentication and peer verification options.
+    def ssl_auth_opts(opt, conn_params)
+      opt.on("-E CERT_FILE:PASSWORD", "--cert=CERT_FILE:PASSWORD", "Use " +
+        "the specified certificate file for client authentication. If the " +
+        "optional password is not provided it will be asked for on the " +
+        "command line. Must be in PEM format.") do |val|
+          cert, cpass = val.chomp.split(":", 2)
+          conn_params[:client_certificate] = cert
+          conn_params[:client_password] = cpass if cpass
+      end
+      opt.on("--cacert=CERT_FILE", "Use the specified certificate file to " +
+        "verify the peer. Must be in PEM format.") do |val|
+          conn_params[:ca_file] = val.chomp
+      end
+      opt.on("--capath=CERTS_PATH", "Use the specified certificate " +
+        "directory to verify the peer. Certificates must be in PEM " +
+        "format") do |val|
+          conn_params[:ca_path] = val.chomp
+      end
+      opt.on("-k", "--insecure", "Allow insecure connections: no peer " +
+        "verification.") do
+          conn_params[:verify_peer] = false
+      end
+    end
+
+    # The SSL transport options.
+    def ssl_transport_opts(opt, conn_params)
+      opt.on("-1", "--tlsv1", "Use TLS version 1 when negotiating with " +
+        "the remote Taverna Server server.") do
+          conn_params[:ssl_version] = :TLSv1
+      end
+      opt.on("-2", "--sslv2", "Use SSL version 2 when negotiating with " +
+        "the remote Taverna Server server.") do
+          conn_params[:ssl_version] = :SSLv23
+      end
+      opt.on("-3", "--sslv3", "Use SSL version 3 when negotiating with " +
+        "the remote Taverna Server server.") do
+          conn_params[:ssl_version] = :SSLv3
+      end
+    end
+
   end
 end

data/lib/t2-server.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2013 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -38,6 +38,7 @@ require 't2-server/net/credentials'
 require 't2-server/net/connection'
 require 't2-server/net/parameters'
 require 't2-server/port'
+require 't2-server/interaction'
 require 't2-server/server'
 require 't2-server/run'
 require 't2-server/admin'

data/lib/t2-server/admin.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2013 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -30,7 +30,11 @@
 #
 # Author: Robert Haines
 
+# :stopdoc:
+# This comment is needed to stop the above licence from being included in the
+# documentation multiple times. Sigh.
 module T2Server
+# :startdoc:
 
   # This call provides access to the administrative interface of a Taverna
   # Server instance.
@@ -56,7 +60,6 @@ module T2Server
       admin_description = xml_document(@server.read(@uri, "application/xml",
         @credentials))
       @resources = get_resources(admin_description)
-      #@resources.each {|key, value| puts "#{key}: #{value}"}
 
       yield(self) if block_given?
     end
@@ -117,7 +120,7 @@ module T2Server
       # :startdoc:
 
       # :call-seq:
-      #   value -> String
+      #   value -> string
       #   value=
       #
       # Get or set the value held by this resource. This call always queries
@@ -129,7 +132,7 @@ module T2Server
       end
 
       # :call-seq:
-      #   writable? -> bool
+      #   writable? -> true or false
       #
       # Is this resource writable?
       def writable?

data/lib/t2-server/exceptions.rb

@@ -83,12 +83,31 @@ module T2Server
   # not necessarily indicate a problem with the server.
   class UnexpectedServerResponse < T2ServerError
 
-    # Create a new UnexpectedServerResponse with the specified unexpected
+    # The method that was called to produce this error.
+    attr_reader :method
+
+    # The path of the URI that returned this error.
+    attr_reader :path
+
+    # The HTTP error code of this error.
+    attr_reader :code
+
+    # The response body of this error. If the server did not supply one then
+    # this will be "<none>".
+    attr_reader :body
+
+    # Create a new UnexpectedServerResponse with details of which HTTP method
+    # was called, the path that it was called on and the specified unexpected
     # response. The response to be passed in is that which was returned by a
     # call to Net::HTTP#request.
-    def initialize(response)
-      body = response.body ? "\n#{response.body}" : ""
-      super "Unexpected server response: #{response.code}\n#{body}"
+    def initialize(method, path, response)
+      @method = method
+      @path = path
+      @code = response.code
+      @body = response.body.empty? ? "<none>" : "#{response.body}"
+      message = "Unexpected server response:\n  Method: #{@method}\n  Path: "\
+        "#{@path}\n  Code: #{@code}\n  Body: #{@body}"
+      super message
     end
   end
 

data/lib/t2-server/interaction.rb

@@ -0,0 +1,241 @@
+# Copyright (c) 2010-2013 The University of Manchester, UK.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  * Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  * Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  * Neither the names of The University of Manchester nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# Author: Robert Haines
+
+require 'rubygems'
+require 'atom'
+require 'uri'
+
+module T2Server
+
+  # The Interaction module provides access to Taverna workflow notifications
+  # as supplied by the Interaction Service. These are read from an Atom feed
+  # and returned as Notification objects. For more information about the
+  # Interaction Service, see
+  # http://dev.mygrid.org.uk/wiki/display/taverna/Interaction+service
+  module Interaction
+
+    # :stopdoc:
+    FEED_NS = "http://ns.taverna.org.uk/2012/interaction"
+
+    class Feed
+      def initialize(run)
+        @run = run
+        @cache = {:requests => {}, :replies => {}}
+      end
+
+      # Get all new notification requests since they were last checked.
+      #
+      # Here we really only want new unanswered notifications, but polling
+      # returns all requests new to *us*, even those that have been replied to
+      # elsewhere. Filter out answered requests here.
+      def new_requests
+        poll(:requests).select { |i| !i.has_reply? }
+      end
+
+      # Get all notifications, or all of a particular type.
+      def notifications(type = :all)
+        poll
+
+        case type
+        when :requests, :replies
+          @cache[type].values
+        else
+          @cache[:requests].values + @cache[:replies].values
+        end
+      end
+
+      private
+
+      def entries(&block)
+        feed = Atom::Feed.load_feed(@run.read_notification_feed)
+        feed.each_entry(:paginate => true, &block)
+      end
+
+      # Poll for all notification types and update the caches.
+      #
+      # Returns any new notifications, [] otherwise. If you are only
+      # interested in knowing about new notifications of a specific type you
+      # can use the type parameter to specify this. Use :requests, :replies or
+      # :all (default).
+      def poll(type = :all)
+        updates = []
+        requests = @cache[:requests]
+        replies = @cache[:replies]
+
+        entries do |entry|
+          # It's worth noting what happens here.
+          #
+          # This connection to a run's notification feed may not be the only
+          # one, or it might be a reconnection. As a result we might see a
+          # reply before we see the original request; atom feeds are last in
+          # first out.
+          #
+          # So if we see a reply, we should check to see if we have the
+          # request before setting the request to "replied". And if we see a
+          # request we should check to see if we have a reply for it already;
+          # we may have seen the reply the previous time through the loop.
+          note = Notification.new(entry, @run)
+          if note.is_reply?
+            next if replies.has_key? note.reply_to
+            requests[note.reply_to].has_reply unless requests[note.reply_to].nil?
+            replies[note.reply_to] = note
+            updates << note if type == :replies || type == :all
+          else
+            next if requests.has_key? note.id
+            note.has_reply unless replies[note.id].nil?
+            requests[note.id] = note
+            updates << note if type == :requests || type == :all
+          end
+        end
+
+        updates
+      end
+
+    end
+    # :startdoc:
+
+    # This class represents a Taverna notification.
+    class Notification
+
+      # The identifier of this notification.
+      attr_reader :id
+
+      # If this notification is a reply then this is the identifier of the
+      # notification that it is a reply to.
+      attr_reader :reply_to
+
+      # The URI of the notification page to show.
+      attr_reader :uri
+
+      # The serial number of a notification. This identifies a notification
+      # within a workflow.
+      attr_reader :serial
+
+      # :stopdoc:
+      def initialize(entry, run)
+        @run = run
+        reply_to = entry[FEED_NS, "in-reply-to"]
+        if reply_to.empty?
+          @is_reply = false
+          @has_reply = false
+          @id = entry[FEED_NS, "id"][0]
+          @is_notification = entry[FEED_NS, "progress"].empty? ? false : true
+          @uri = get_link(entry.links)
+          @serial = "#{entry[FEED_NS, 'path'][0]}-#{entry[FEED_NS, 'count'][0]}"
+        else
+          @is_reply = true
+          @is_notification = false
+          @reply_to = reply_to[0]
+        end
+      end
+      # :startdoc:
+
+      # :call-seq:
+      #   is_reply? -> true or false
+      #
+      # Is this notification a reply to another notification?
+      def is_reply?
+        @is_reply
+      end
+
+      # :call-seq:
+      #   is_notification? -> true or false
+      #
+      # Is this notification a pure notification only? There is no user
+      # response to a pure notification, it is for information only.
+      def is_notification?
+        @is_notification
+      end
+
+      # :stopdoc:
+      def has_reply
+        @has_reply = true
+      end
+      # :startdoc:
+
+      # :call-seq:
+      #   has_reply? -> true or false
+      #
+      # Does this notification have a reply? This only makes sense for
+      # notifications that are not replies or pure notifications.
+      def has_reply?
+        @has_reply
+      end
+
+      # :call-seq:
+      #   input_data -> data
+      #
+      # Get the input data associated with this notification. Returns an empty
+      # string if this notification is a reply.
+      def input_data
+        return "" if is_reply?
+
+        data_name = "interaction#{@id}InputData.json"
+        @run.read_interaction_data(data_name)
+      rescue AttributeNotFoundError
+        # It does not matter if the file doesn't exist.
+        ""
+      end
+
+      # :call-seq:
+      #   reply(status, data)
+      #
+      # Given a status and some data this method uploads the data and
+      # publishes an interaction reply on the run's notification feed.
+      def reply(status, data)
+        data_name = "interaction#{@id}OutputData.json"
+
+        notification = Atom::Entry.new do |entry|
+          entry.title = "A reply to #{@id}"
+          entry.id = "#{@id}reply"
+          entry.content = ""
+          entry[FEED_NS, "run-id"] << @run.id
+          entry[FEED_NS, "in-reply-to"] << @id
+          entry[FEED_NS, "result-status"] << status
+        end.to_xml
+
+        @run.write_interaction_data(data_name, data)
+        @run.write_notification(notification)
+      end
+
+      private
+
+      def get_link(links)
+        links.each do |l|
+          return URI.parse(l.to_s) if l.rel == "presentation"
+        end
+      end
+    end
+
+  end
+
+end

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

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2013 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -59,7 +59,7 @@ module T2Server
       end
 
       # if we're given params they must be of the right type
-      if !params.nil? and !params.is_a? ConnectionParameters
+      if !params.nil? && !params.is_a?(ConnectionParameters)
         raise ArgumentError, "Parameters must be ConnectionParameters", caller
       end
 
@@ -93,23 +93,27 @@ module T2Server
       @uri = uri
       @params = params || DefaultConnectionParameters.new
 
-      # set up persistent http connection
+      # Open a persistent HTTP connection.
       @http = Net::HTTP::Persistent.new("Taverna_Server_Ruby_Client")
+
+      # Set timeouts if specified.
+      @http.open_timeout = @params[:open_timeout] if @params[:open_timeout]
+      @http.read_timeout = @params[:read_timeout] if @params[:read_timeout]
     end
 
     # :call-seq:
-    #   GET(uri, type, range, credentials) -> String
+    #   GET(uri, type, range, credentials) -> string
     #
     # 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(uri, type, range, credentials)
+    def GET(uri, type, range, credentials, &block)
       get = Net::HTTP::Get.new(uri.path)
       get["Accept"] = type
       get["Range"] = "bytes=#{range.min}-#{range.max}" unless range.nil?
 
-      response = submit(get, uri, credentials)
+      response = submit(get, uri, credentials, &block)
 
       case response
       when Net::HTTPOK, Net::HTTPPartialContent
@@ -119,36 +123,35 @@ module T2Server
       when Net::HTTPMovedTemporarily
         new_conn = redirect(response["location"])
         raise ConnectionRedirectError.new(new_conn)
-      when Net::HTTPNotFound
-        raise AttributeNotFoundError.new(uri.path)
-      when Net::HTTPForbidden
-        raise AccessForbiddenError.new("attribute #{uri.path}")
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
       else
-        raise UnexpectedServerResponse.new(response)
+        report_error("GET", uri.path, response, credentials)
       end
     end
 
     # :call-seq:
-    #   PUT(uri, value, type, credentials) -> bool
+    #   PUT(uri, value, type, credentials) -> true or false
     #   PUT(uri, value, type, credentials) -> URI
+    #   PUT(uri, stream, type, credentials) -> URI
+    #
+    # Upload data via HTTP PUT. Data may be specified as a value or as a
+    # stream. The stream can be any object that has a read(length) method;
+    # instances of File or IO, for example.
     #
-    # 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)
+    # If successful _true_ or a URI to the uploaded resource is returned
+    # depending on whether the operation has altered a parameter (true) or
+    # uploaded new data (URI).
+    def PUT(uri, data, type, credentials)
       put = Net::HTTP::Put.new(uri.path)
       put.content_type = type
-      put.body = value
+
+      set_upload_body(put, data)
 
       response = submit(put, uri, credentials)
 
       case response
-      when Net::HTTPOK
-        # We've set a parameter so we get 200 back from the server. Return
-        # true to indicate success.
+      when Net::HTTPOK, Net::HTTPAccepted
+        # We've either set a parameter or started a run so we get 200 or 202
+        # back from the server, respectively. Return true to indicate success.
         true
       when Net::HTTPCreated
         # We've uploaded data so we get 201 back from the server. Return the
@@ -158,26 +161,27 @@ module T2Server
         # 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(uri.path)
-      when Net::HTTPForbidden
-        raise AccessForbiddenError.new("attribute #{uri.path}")
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
+      when Net::HTTPServiceUnavailable
+        raise ServerAtCapacityError.new
       else
-        raise UnexpectedServerResponse.new(response)
+        report_error("PUT", uri.path, response, credentials)
       end
     end
 
     # :call-seq:
-    #   POST(uri, value, type, credentials)
+    #   POST(uri, value, type, credentials) -> URI
+    #   POST(uri, stream, type, credentials) -> URI
+    #
+    # Upload data via HTTP POST. Data may be specified as a value or as a
+    # stream. The stream can be any object that has a read(length) method;
+    # instances of File or IO, for example.
     #
-    # 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)
+    # If successful the URI of the uploaded resource is returned.
+    def POST(uri, data, type, credentials)
       post = Net::HTTP::Post.new(uri.path)
       post.content_type = type
-      post.body = value
+
+      set_upload_body(post, data)
 
       response = submit(post, uri, credentials)
 
@@ -185,23 +189,15 @@ module T2Server
       when Net::HTTPCreated
         # return the URI of the newly created item
         URI.parse(response['location'])
-      when Net::HTTPNotFound
-        raise AttributeNotFoundError.new(uri.path)
-      when Net::HTTPForbidden
-        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)
+      when Net::HTTPServiceUnavailable
+        raise ServerAtCapacityError.new
       else
-        raise UnexpectedServerResponse.new(response)
+        report_error("POST", uri.path, response, credentials)
       end
     end
 
     # :call-seq:
-    #   DELETE(uri, credentials) -> bool
+    #   DELETE(uri, credentials) -> true or false
     #
     # Perform an HTTP DELETE on a _uri_ on the server. If successful true
     # is returned.
@@ -214,19 +210,13 @@ module T2Server
       when Net::HTTPNoContent
         # Success, carry on...
         true
-      when Net::HTTPNotFound
-        false
-      when Net::HTTPForbidden
-        raise AccessForbiddenError.new(uri)
-      when Net::HTTPUnauthorized
-        raise AuthorizationError.new(credentials)
       else
-        raise UnexpectedServerResponse.new(response)
+        report_error("DELETE", uri.path, response, credentials)
       end
     end
 
     # :call-seq:
-    #   OPTIONS(uri, credentials) -> Hash
+    #   OPTIONS(uri, credentials) -> hash
     #
     # Perform the HTTP OPTIONS command on the given _uri_ and return a hash
     # of the headers returned.
@@ -238,23 +228,59 @@ module T2Server
       case response
       when Net::HTTPOK
         response.to_hash
+      else
+        report_error("OPTIONS", uri.path, response, credentials)
+      end
+    end
+
+    private
+
+    # If one of the expected responses for a HTTP method is not received then
+    # handle the error condition here.
+    def report_error(method, path, response, credentials)
+      case response
+      when Net::HTTPNotFound
+        raise AttributeNotFoundError.new(path)
       when Net::HTTPForbidden
-        raise AccessForbiddenError.new("resource #{uri.path}")
+        raise AccessForbiddenError.new("resource #{path}")
       when Net::HTTPUnauthorized
         raise AuthorizationError.new(credentials)
       else
-        raise UnexpectedServerResponse.new(response)
+        raise UnexpectedServerResponse.new(method, path, response)
       end
     end
 
-    private
+    # If we have a stream then we need to set body_stream and then either
+    # supply a content length or set the transfer encoding to "chunked". A
+    # file object can supply its size, a bare IO object cannot. If we have a
+    # simple value we can set body directly.
+    def set_upload_body(request, data)
+      if data.respond_to? :read
+        request.body_stream = data
+        if data.respond_to? :size
+          request.content_length = data.size
+        else
+          request["Transfer-encoding"] = "chunked"
+        end
+      else
+        request.body = data
+      end
+    end
 
-    def submit(request, uri, credentials)
+    # If a block is passed in here then the response is returned in chunks
+    # (streamed). If no block is passed in the whole response is read into
+    # memory and returned.
+    def submit(request, uri, credentials, &block)
 
       credentials.authenticate(request) unless credentials.nil?
 
+      response = nil
       begin
-        @http.request(uri, request)
+        @http.request(uri, request) do |r|
+          r.read_body(&block)
+          response = r
+        end
+        response
       rescue InternalHTTPError => e
         raise ConnectionError.new(e)
       end
@@ -276,6 +302,10 @@ module T2Server
     def initialize(uri, params = nil)
       super(uri, params)
 
+      if OpenSSL::SSL::SSLContext::METHODS.include? @params[:ssl_version]
+        @http.ssl_version = @params[:ssl_version]
+      end
+
       # Peer verification
       if @params[:verify_peer]
         if @params[:ca_file]