dot_net_services 0.0.1

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2008, ThoughtWorks
+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 name of the ThoughtWorks 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 ThoughtWorks ''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 THOUGHTWORKS 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.

data/README

@@ -0,0 +1,52 @@
+= .NET Services for Ruby
+
+* Project homepage: http://dotnetservicesruby.com
+* Download: http://rubyforge.org/frs/?group_id=7155
+* Demo application: http://dotnetservicesruby.com/billboard
+* Source code: http://rubyforge.org/frs/?group_id=7155
+* Documentation: http://dotnetservicesruby.com/documentation/index.html
+
+== What's this?
+
+.NET Services for Ruby is an open source library that helps Ruby programs communicate with Microsoft's .NET Services
+using plain HTTP. It was developed by a small team in ThoughtWorks, while Microsoft provided funding, management and
+technical guidance for the project.
+
+== Installation
+
+The library can be installed as a 'dot_net_services' gem, from RubyForge gem repository:
+
+ $ gem install dot_net_services
+
+or downloaded as an archive from RubyForge [http://rubyforge.org/frs/?group_id=7155].
+
+<i>NOTE: Version number 0.1.0 tells you that the API will have backwards-incompatible changes in future, so
+Vendor Everything! [http://errtheblog.com/posts/50-vendor-everything]</i>
+
+== Documentation
+
+API: http://dotnetservicesruby.com/documentation/classes/DotNetServices.html
+
+.NET Services: http://go.microsoft.com/fwlink/?LinkID=129428
+
+== Demo application
+
+To provide an example of our interop API in action, we have implemented a small Rails application called BillBoard.
+We were working on the API while building the app, which helped us study the technology and discover the right
+abstractions.
+
+You can see BillBoard in action at http://dotnetservicesruby.com/billboard and download BillBoard source code from
+RubyForge [http://rubyforge.org/frs/?group_id=7155].
+
+== Contacts
+
+Users maillist: http://rubyforge.org/mailman/listinfo/dotnetsrv-ruby-users
+ThoughtWorks: info-us@thoughtworks.com
+
+== License
+
+BSD license. See [LICENSE].
+
+== Copyright
+
+(c) ThoughtWorks, Inc 2008

data/lib/dot_net_services/authentication.rb

@@ -0,0 +1,168 @@
+require 'cgi'
+require 'net/http'
+require 'net/https'
+
+module DotNetServices
+  # This stores the token and expiration time.  The default expiration
+  # time is 1 day.
+  module Authentication # :nodoc:
+    @cache = {}
+
+    # Authentication token.
+    class Token # :nodoc:
+
+      attr_reader :value, :expiry
+
+      # Create a new authentication token; defaults to expire in one day.
+      def initialize(value, expiry = Time.now + 24 *60 * 60)
+        # workaround for a known bug
+        match = value.match(/^([^=]+==).*/)
+        if match
+          @value = match[1]
+          @expiry = expiry
+        else
+          raise AuthenticationError,
+                "Response from access control service doesn't seem to contain a valid authentication token:\n" +
+                value.inspect
+        end
+      end
+
+      def expired?
+        @expiry < Time.now
+      end
+
+      def to_s
+        @value
+      end
+    end
+
+    # Standard Username and Password authenticator.
+    class UsernamePassword # :nodoc:
+
+      attr_reader :token, :username, :password
+
+      def initialize(username, password, token = nil)
+        @username, @password = username, password
+        @token = token
+      end
+
+      def authenticate
+        return if @token and not @token.expired?
+        @token = acquire_token
+      end
+
+      # Enhance the request with the identity token provided by the identity service.
+      def enhance(request)
+        authenticate
+        request['X-MS-Identity-Token'] = token.value
+      end
+
+      def ==(other)
+        other.is_a?(Authentication::UsernamePassword) && @username == other.username && @password == other.password
+      end
+      alias :eql?  :==
+      
+      def hash
+        @hash ||= @username.hash & @password.hash
+      end
+
+      # Retrieve a token from the DotNetServices token issuing service.
+      def acquire_token
+        http = Net::HTTP.new(DotNetServices.identity_host, 443)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+        escaped_username = CGI.escape(@username)
+        escaped_password = CGI.escape(@password)
+        begin
+          response = http.get("/issuetoken.aspx?u=#{escaped_username}&p=#{escaped_password}")
+        rescue => e
+          raise AuthenticationError, "Failed to obtain authentication token. Original error of type #{e.class} " +
+                "was overridden to prevent logging security-sensitive data"
+        end
+
+        unless response.is_a?(Net::HTTPOK)
+          raise AuthenticationError, "Failed to obtain a security token from the identity service. HTTP response was #{response.class.name}"
+        end
+
+        Token.new(response.body)
+      end
+    end
+
+    # Certificate authenticator.  NOT YET IMPLEMENTED
+    class Certificate # :nodoc:
+      def authenticate
+        raise "not implemented"
+      end
+
+      def enhance(request)
+        raise "not implemented"
+      end
+
+      def hash
+        1
+      end
+
+      def ==(other)
+        other.is_a?(Certificate)
+      end
+      alias :eql?  :==
+    end
+
+    # An anonymous authenticator.  It is used as a stand-in for
+    # services which do not require authentication.
+    class Anonymous # :nodoc:
+      def authenticate() end
+      def enhance(request) end
+      def ==(another) another.is_a?(Anonymous) end
+      alias :eql?  :==
+      def hash() -1 end
+    end
+
+    class << self
+      def setup(auth_data)
+        authenticator = create_authenticator(auth_data)
+        @cache[authenticator] ||= authenticator
+      end
+
+      # Create an authenticator based on the data provided.
+      def create_authenticator(auth_data)
+        if auth_data.nil?
+          Authentication::Anonymous.new
+        elsif !auth_data.is_a? Hash
+          auth_data
+        elsif auth_data.empty?
+          Authentication::Anonymous.new
+        else
+          auth_data_copy = auth_data.dup
+          username = auth_data_copy.delete(:username)
+          password = auth_data_copy.delete(:password)
+          certificate = auth_data_copy.delete(:certificate)
+
+          unless auth_data_copy.empty?
+            raise ArgumentError, "Auth data contains unknown options: #{auth_data.keys.inspect}"
+          end
+
+          if username && !password
+            raise ArgumentError, "Auth data specifies username, but no password."
+          elsif password && !username
+            raise ArgumentError, "Auth data specifies password, but no username."
+          elsif (username || password) && certificate
+            raise ArgumentError, "Cannot determine authentication type from auth data."
+          elsif username && password
+            Authentication::UsernamePassword.new(username, password)
+          elsif certificate
+            Authentication::Certificate.new
+          else
+            raise "Internal error. Unable to setup authenticator from #{auth_data.inspect}"
+          end
+        end
+      end
+
+      def clear_cache!
+        @cache.clear
+      end
+    end
+
+  end
+end

data/lib/dot_net_services/error.rb

@@ -0,0 +1,4 @@
+module DotNetServices
+  class AuthenticationError < StandardError  # :nodoc:
+  end
+end

data/lib/dot_net_services/message_buffer.rb

@@ -0,0 +1,269 @@
+require 'date'
+
+module DotNetServices
+
+  # The MessageBuffer class is used for creating Volatile Message Buffer (VMB) endpoints on the .NET Services bus, and
+  # retrieving messages from them.
+  #
+  # A VMB is a temporary message buffer that can be used for asynchronous communications between senders and receivers
+  # of messages. A process may request creation of a VMB on any URL within a solution namespace. Any HTTP requests
+  # (other than GETs) to that URL are stored in the buffer, until some process retrieves them by sending an HTTP
+  # X-RETRIEVE request to the management endpoint.
+  #
+  # VMB can exist by itself, not tied to the lifecycle of a process that originally created it. Further information
+  # about VMBs can be found in .NET Services portal [http://go.microsoft.com/fwlink/?LinkID=129428].
+  #
+  # == Usage examples
+  #
+  # MessageBuffer instance represents a VMB endpoint. Typical usage looks as follows:
+  #
+  #  error_handler = lambda { |error| logger.error(error) }
+  #
+  #  buffer = DotNetServices::MessageBuffer.open_and_poll(
+  #          "MySolution/MyVMB",
+  #          {:username => 'MySolution', :password => 'my_password'},
+  #          error_handler) do
+  #    |message|
+  #    ... process the message
+  #  end
+  #
+  # This invocation does all of the following:
+  #
+  # * Creates a MessageBuffer instance associated with a specified endpoint (/MySolution/MyVMB)
+  # * obains a security token from trhe Identity service (see Session for details on that).
+  # * Creates a VMB on the .NET Services bus if it doesn't exist yet
+  # * immediately starts polling it
+  # * if it retrieves a message, it passes it to the block. The message is an instance of Net::HTTP::Request that
+  #   looks exactly the same as what the sender originally sent to the bus.
+  # * if an error occurs while polling, the error is passed to the error_handler block. Polling then continues.
+  #
+  # == Guidelines
+  #
+  # In cases where an application (which in this case means a process) needs to process multiple types of messages,
+  # Microsoft recommends to create a single VMB per application, route all message types through the same VMB, and
+  # route messages to appropriate processors within the application itself.
+  #
+  # In the current version of the API, we provide no explicit support for clustering message processors. If you use
+  # MessageBuffer#open_and_poll(), it's recommended that you only run one cipy of a message processor. If clustering
+  # is required (for high availability reasons), you can use lower-level MessageBuffer methods to do it.
+  #
+  # .NET Services VMBs provide pub-sub and multicast functionality which can be used even over plain HTTP. Which is
+  # amazing. However, we don't support this functionality in the current version of our library.
+  class MessageBuffer
+
+    attr_reader :session
+
+    class << self
+
+      # Creates a MessageBuffer instance, acquires a security token, registers a VMB if necessary.
+      # Unlike Session#open, +auth_data+ is mandatory here.
+      # If given a block, passes the MessageBuffer instance to the block, and closes it at the end of the block
+      # returns the result of the block (if called with a block), or the buffer instance opened
+      def open(name, auth_data, &block)
+        buffer = MessageBuffer.new(name, auth_data).open
+        if block_given?
+          begin
+            return yield(buffer)
+          ensure
+            # TODO gracefully close the buffer
+          end
+        else
+          return buffer
+        end
+      end
+
+      # Invoke MessageBuffer#open to create a MessageBuffer instance, subscribe the buffer to receive messages
+      # posted to the +subscription_endpoint+, then poll it until the containing thread or process is terminated.
+      #
+      # Whenever a message is retrieved from the buffer, this method passes it to the block. When an error occurs
+      # (while polling, or raised by the block), it is passed to +error_handler+, which should be a lambda, or an
+      # object with handle(error) public method. If no +error_handler+ is provided, the error is printed out
+      # to STDERR and then ignored.
+      def open_and_poll(name, subscription_endpoint, auth_data, error_handler=nil, &block)
+        MessageBuffer.new(name, auth_data).open_and_poll(subscription_endpoint, error_handler, &block)
+      end
+    end
+
+    # Initializes a new MessageBuffer instance.
+    # Does not create a VMB on the .NET Services bus (use #open for that)
+    def initialize(name, auth_data)
+      @name = name
+      @session = Session.new(name, auth_data)
+    end
+
+    # Register the message buffer (by sending X-CREATEMB to the management endpoint).
+    #
+    # Returns the buffer. Raises an exception if the creation is not successful.
+    def register
+      createmb_response = @session.createmb
+
+      unless createmb_response.is_a?(Net::HTTPCreated)
+        # the buffer may already be there
+        unless @session.get_from_relay.is_a?(Net::HTTPSuccess)
+          raise "Creating VMB failed. Service responded with #{createmb_response.class.name}"
+        end
+      end
+      self
+    end
+
+    # Initiates a VMB session by:
+    # * acquiring a security token
+    # * checks if there is already a VMB at the endpoint
+    # * creating a VMB if necessary
+    def open
+      register unless @session.get_from_relay.is_a?(Net::HTTPSuccess)
+      self
+    end
+
+    # Open the buffer (see #open), subscribe the buffer to receive messages
+    # posted to the +subscription_endpoint+, then poll it until the containing thread or
+    # process is terminated.
+    #
+    # Whenever a message is retrieved from the buffer, this method passes it to the block. When an error occurs
+    # (while polling, or raised by the block), it is passed to +error_handler+, which should be a lambda, or an
+    # object with handle(error) public method. If no +error_handler+ is provided, the error is printed out
+    # to STDERR and then ignored.
+    def open_and_poll(subscription_endpoint, error_handler=nil, &block)
+      raise "MessageBuffer#open_and_poll requires a block" unless block_given?
+
+      @subscription_endpoint = subscription_endpoint 
+
+      open
+      subscribe(@subscription_endpoint)
+
+      begin
+        loop do
+          begin
+            message = poll
+            block.call(message) if message
+          rescue Object => error
+            if error_handler
+              if error_handler.is_a?(Proc)
+                error_handler.call(error)
+              else
+                error_handler.handle(error)
+              end
+            else
+              STDERR.puts
+              STDERR.puts "Message Buffer Error"
+              STDERR.puts error.message
+              STDERR.puts error.backtrace.map { |line| "  #{line}"}
+              STDERR.puts
+            end
+          end
+        end
+      ensure
+        @subscription_endpoint = nil
+      end
+    end
+
+    # Poll VMB endpoint for new messages; return the message if one was retrieved, or nil if it wasn't.
+    #
+    # Raises an exception if the response from the bus contains an error code (which usually means that the VMB is
+    # not registered, but may mean other things, for example if the bus itself is not accessible for some reason).
+    #
+    # +timeout+ parameter regulates how long a polling request will be held by the bus if there are no messages.
+    #
+    # An HTTP server that holds HTTP connections because it has nothing to respond with is somewhat uncommon, so a
+    # more detailed explanation is due.
+    #
+    # Normally, any HTTP interaction begins by opening of a TCP socket from the client to the server. The client
+    # then writes the HTTP request into that socket and waits until the server responds back and closes the socket.
+    # If the server doesn't respond for a long time (a minute, usually), the client drops the socket
+    # and declares timeout.
+    #
+    # Many times, when you poll a VMB endpoint, it will have no messages. If the bus simply came back immediately with
+    # "No Content" response, this would cause a VMB subscriber needs to constantly poll the buffer, abusing the bus
+    # infrastructure.
+    #
+    # .NET Services gets around this problem by making the client connection hang for some time, either until there
+    # is a message, or a certain number of seconds has passed, and there is still no message. That number of seconds is
+    # what the +timeout+ parameter specifies. Microsoft suggested that 10-20 seconds is reasonable for
+    # production purposes. #open_and_poll() loop uses 15.
+    def poll(timeout=nil)
+      response = @session.retrieve(:encoding => 'asreply', :timeout => timeout)
+      case response
+      when Net::HTTPNoContent
+        return nil
+      when Net::HTTPNotFound
+        register
+        subscribe(@subscription_endpoint) if @subscription_endpoint
+        return nil
+      when Net::HTTPSuccess
+        return response
+      else
+        raise "Retrieving messages failed. Response was #{response.class.name}" unless response.is_a?(Net::HTTPSuccess)
+      end
+    end
+
+    # Delete the message buffer.  This removes the buffer entirely
+    # from the bus, not just the local reference to it.
+    def delete
+      response = @session.delete
+
+      unless response.is_a?(Net::HTTPNoContent)
+        raise "Deleting VMB failed. Response was #{response.class.name}"
+      end
+      self
+    end
+
+    # Queries the VMB management endpoint for the VMB expiry time. With every #poll (HTTP X-RETRIEVE to the VMB management
+    # endpoint) the bus sets the expiry time of this VMB to 30 minutes later. If 30 minutes pass and there are no
+    # further polls, the bus automatically delets the buffer.
+    def expires
+      response = @session.get_from_relay
+
+      unless response.is_a?(Net::HTTPOK)
+        raise "Querying expiry status of VMB failed. Response was #{response.class}"
+      end
+      
+      expires_header = response["expires"]
+      raise "Querying expiry status of VMB failed. Response doesn't have expires: header" unless expires_header
+      DateTime.parse(expires_header)
+    end
+
+    # Performs an empty POST to the VMB management endpoint, which extends the VMB expiry time without retrieving any
+    # messages.
+    def keep_alive
+      # if we don't pass a linefeed as a body to the VMB management endpoint, it responds with HTTP 411 Length Required
+      response = @session.post_to_relay "\n"
+      case response
+      when Net::HTTPSuccess
+        self
+      else
+        raise "POST to the VMB management endpoint failed. Response was #{response.class}"
+      end
+    end
+
+    # Subscribe to an endpoint.
+    #
+    # HTTP messages sent to the +endpoint+ will be routed to this message buffer
+    def subscribe(target_path)
+      subscription_endpoint_url = DotNetServices.root_url + "/" + target_path
+      subscribe_response = @session.subscribe(:target => subscription_endpoint_url)
+      case subscribe_response
+      when Net::HTTPSuccess
+        return self
+      when Net::HTTPConflict
+        unsubscribe(target_path)
+        resubscribe_response = @session.subscribe(:target => subscription_endpoint_url)
+        unless resubscribe_response.is_a?(Net::HTTPSuccess)
+          raise "Second X-SUBSCRIBE to VMB management endpoint failed. Response was #{resubscribe_response.class}"
+        end
+      else
+        raise "X-SUBSCRIBE to VMB management endpoint failed. Response was #{subscribe_response.class}"
+      end
+    end
+
+    # Unsubscribe from an endpoint.
+    def unsubscribe(target_path)
+      subscription_endpoint_url = DotNetServices.root_url + "/" + target_path
+      unsubscribe_response = @session.unsubscribe(:target => subscription_endpoint_url)
+      unless unsubscribe_response.is_a?(Net::HTTPSuccess)
+        raise "X-UNSUBSCRIBE to VMB management endpoint failed. Response was #{subscribe_response.class}"
+      end
+      self
+    end
+
+  end
+end