cf-runtime 0.0.1

data/README.md

@@ -0,0 +1,28 @@
+#cf-runtime
+
+A library for interacting with Cloud Foundry services.  Provides methods for obtaining pre-configured connection objects and connection properties.
+
+_Copyright (c) 2011-2012 VMware, Inc. Please see the LICENSE file._
+
+require 'cfruntime'
+
+#Connect to mysql service named 'mysql-test'
+client = CFRuntime::Mysql2Client.create_from_svc 'mysql-test'
+
+#Connect to a single service of type MongoDB
+connection = CFRuntime::MongoClient.create
+db = connection.db
+
+#Obtain connection properties for 'myservice'
+if CFRuntime::CloudApp.running_in_cloud?
+  service_props = CFRuntime::CloudApp.service_props 'myservice'
+end
+
+#Obtain connection properties for single service of type MySQL
+service_props = CFRuntime::CloudApp.service_props 'mysql'
+
+#Other handy methods
+CFRuntime::CloudApp.host
+CFRuntime::CloudApp.port
+CFRuntime::CloudApp.service_names
+CFRuntime::CloudApp.service_names_of_type 'mysql'

data/lib/cfruntime.rb

@@ -0,0 +1,26 @@
+begin
+  require 'cfruntime/amqp'
+rescue LoadError
+end
+begin
+  require 'cfruntime/carrot'
+rescue LoadError
+end
+begin
+  require 'cfruntime/mongodb'
+rescue LoadError
+end
+begin
+  require 'cfruntime/mysql'
+rescue LoadError
+end
+begin
+  require 'cfruntime/postgres'
+rescue LoadError
+end
+begin
+  require 'cfruntime/redis'
+rescue LoadError
+end
+require 'cfruntime/properties'
+require 'cfruntime/version'

data/lib/cfruntime/amqp.rb

@@ -0,0 +1,43 @@
+require 'amqp'
+module CFRuntime
+  class AMQPClient
+
+    # Creates and returns an +AMQP+ connection to a single rabbitmq service.
+    # Passes optional other_options and block arguments to +AMQP.connect+.
+    # Raises +ArgumentError+ If zero or multiple rabbitmq services are found.
+    def self.create(other_options = {}, &block)
+      service_names = CloudApp.service_names_of_type('rabbitmq')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of rabbitmq type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using create_from_svc(service_name) instead.")
+      end
+      create_from_svc(service_names[0],other_options,&block)
+    end
+
+    # Creates and returns an +AMQP+ connection to a rabbitmq service with the
+    # specified name.
+    # Passes optional other_options and block arguments to +AMQP.connect+.
+    # Raises +ArgumentError+ If specified rabbitmq service is not found.
+    def self.create_from_svc(service_name, other_options = {}, &block)
+      AMQP.connect(options_for_svc(service_name), other_options, &block)
+    end
+
+    # Merges provided options with connection options for specified rabbitmq service.
+    # Returns merged Hash containing (:user, :pass, :vhost, :host, :port).
+    # Raises +ArgumentError+ If specified rabbitmq service is not found.
+    def self.options_for_svc(service_name,options={})
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      cfoptions = options
+      cfoptions[:host] = service_props[:host]
+      cfoptions[:port] = service_props[:port]
+      cfoptions[:user] = service_props[:username]
+      cfoptions[:pass] = service_props[:password]
+      cfoptions[:vhost] = service_props[:vhost]
+      cfoptions
+    end
+  end
+end

data/lib/cfruntime/carrot.rb

@@ -0,0 +1,44 @@
+require 'carrot'
+require 'cfruntime/properties'
+module CFRuntime
+  class CarrotClient
+
+    # Creates and returns a +Carrot+ instance connected to a single rabbitmq service.
+    # Passes optional Hash of non-connection-related options to +Carrot.new+.
+    # Raises +ArgumentError+ If zero or multiple rabbitmq services are found.
+    def self.create(options={})
+      service_names = CloudApp.service_names_of_type('rabbitmq')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of rabbitmq type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using create_from_svc(service_name) instead.")
+      end
+      create_from_svc(service_names[0],options)
+    end
+
+    # Creates and returns a +Carrot+ instance connected to a rabbitmq service with the
+    # specified name.
+    # Passes optional Hash of non-connection-related options to +Carrot.new+.
+    # Raises +ArgumentError+ If specified rabbitmq service is not found.
+    def self.create_from_svc(service_name, options={})
+      Carrot.new(options_for_svc(service_name,options))
+    end
+
+    # Merges provided options with connection options for specified rabbitmq service.
+    # Returns merged Hash containing (:user, :pass, :vhost, :host, :port).
+    # Raises +ArgumentError+ If specified rabbitmq service is not found.
+    def self.options_for_svc(service_name,options={})
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      cfoptions = options
+      cfoptions[:host] = service_props[:host]
+      cfoptions[:port] = service_props[:port]
+      cfoptions[:user] = service_props[:username]
+      cfoptions[:pass] = service_props[:password]
+      cfoptions[:vhost] = service_props[:vhost]
+      cfoptions
+    end
+  end
+end

data/lib/cfruntime/mongodb.rb

@@ -0,0 +1,86 @@
+require 'mongo'
+require 'cfruntime/properties'
+module CFRuntime
+  class MongoClient
+
+    # Creates and returns a Mongo +Connection+ to a single mongodb service.
+    # Passes optional Hash of non-connection-related options to +Mongo::Connection.new+.
+    # The connection is wrapped in a proxy that adds a no-argument db method to gain access
+    # to the database created by CloudFoundry without having to specify the name.
+    # Raises +ArgumentError+ If zero or multiple mongodb services are found.
+    def self.create(options={})
+      service_names = CloudApp.service_names_of_type('mongodb')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of mongodb type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using create_from_svc(service_name) instead.")
+      end
+      create_from_svc(service_names[0],options)
+    end
+
+    # Creates and returns a Mongo +Connection+ to a mongodb service with the
+    # specified name.
+    # Passes optional Hash of non-connection-related options to +Mongo::Connection.new+.
+    # The connection is wrapped in a proxy that adds a no-argument db method to gain access
+    # to the database created by CloudFoundry without having to specify the name.
+    # Raises +ArgumentError+ If specified mongodb service is not found.
+    def self.create_from_svc(service_name,options={})
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      uri = "mongodb://#{service_props[:username]}:#{service_props[:password]}@#{service_props[:host]}:#{service_props[:port]}/#{service_props[:db]}"
+      conn = Mongo::Connection.from_uri(uri, options)
+      MongoConnection.new(conn, service_props[:db])
+    end
+
+    # Returns the db_name for a single mongodb service.
+    # Raises +ArgumentError+ If zero or multiple mongodb services are found.
+    def self.db_name()
+      service_names = CloudApp.service_names_of_type('mongodb')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of mongodb type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using db_name_from_svc(service_name) instead.")
+      end
+      db_name_from_svc(service_names[0])
+    end
+
+    # Returns the db_name for the mongodb service with the specified name.
+    # Raises +ArgumentError+ If specified mongodb service is not found.
+    def self.db_name_from_svc(service_name)
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      service_props[:db]
+    end
+
+  end
+
+  class MongoConnection
+
+    instance_methods.each { |m| undef_method m unless m =~ /^__|instance_eval|object_id/ }
+
+    def initialize(connection, db_name)
+      @target = connection
+      @dbname = db_name
+    end
+
+    def db(db_name=@dbname, opts={})
+      @target.send('db', db_name, opts)
+    end
+
+    def target()
+      @target
+    end
+
+    protected
+
+      def method_missing(method, *args, &block)
+        @target.send(method, *args, &block)
+      end
+
+  end
+
+end

data/lib/cfruntime/mysql.rb

@@ -0,0 +1,44 @@
+require 'mysql2'
+require 'cfruntime/properties'
+module CFRuntime
+  class Mysql2Client
+
+    # Creates and returns a Mysql2 +Client+ instance connected to a single mysql service.
+    # Passes optional Hash of non-connection-related options to +Mysql2::Client.new+.
+    # Raises +ArgumentError+ If zero or multiple mysql services are found.
+    def self.create(options={})
+      service_names = CloudApp.service_names_of_type('mysql')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of mysql type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using create_from_svc(service_name) instead.")
+      end
+      create_from_svc(service_names[0],options)
+    end
+
+    # Creates and returns a Mysql2 +Client+ instance connected to a mysql service with the
+    # specified name.
+    # Passes optional Hash of non-connection-related options to +Mysql2::Client.new+.
+    # Raises +ArgumentError+ If specified mysql service is not found.
+    def self.create_from_svc(service_name, options={})
+      Mysql2::Client.new(options_for_svc(service_name,options))
+    end
+
+    # Merges provided options with connection options for specified mysql service.
+    # Returns merged Hash containing (:username, :password, :database, :host, :port).
+    # Raises +ArgumentError+ If specified mysql service is not found.
+    def self.options_for_svc(service_name,options={})
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      cfoptions = options
+      cfoptions[:host] = service_props[:host]
+      cfoptions[:port] = service_props[:port]
+      cfoptions[:username] = service_props[:username]
+      cfoptions[:password] = service_props[:password]
+      cfoptions[:database] = service_props[:database]
+      cfoptions
+    end
+  end
+end

data/lib/cfruntime/postgres.rb

@@ -0,0 +1,50 @@
+require 'pg'
+require 'cfruntime/properties'
+module CFRuntime
+  class PGClient
+
+    # Creates and returns a +PGconn+ connecting to a single postgresql service.
+    # Passes optional Hash of non-connection-related options to +PGconn.open+.
+    # Raises +ArgumentError+ If zero or multiple postgresql services are found.
+    def self.create(options={})
+      service_names = CloudApp.service_names_of_type('postgresql')
+      if service_names.length != 1
+        raise ArgumentError.new("Expected 1 service of postgresql type, " +
+          "but found #{service_names.length}.  " +
+          "Consider using create_from_svc(service_name) instead.")
+      end
+      cfoptions = options_for_svc(service_names[0],options)
+      #Pass back the options for verification
+      yield cfoptions if block_given?
+      PGconn.open(cfoptions)
+    end
+
+    # Creates and returns a +PGconn+ connecting to a postgresql service with the
+    # specified name.
+    # Passes optional Hash of non-connection-related options to +PGconn.open+.
+    # Raises +ArgumentError+ If specified postgresql service is not found.
+    def self.create_from_svc(service_name,options={})
+      cfoptions = options_for_svc(service_name,options)
+      #Pass back the options for verification
+      yield cfoptions if block_given?
+      PGconn.open(cfoptions)
+    end
+
+    # Merges provided options with connection options for specified postgresql service.
+    # Returns merged Hash containing (:user, :password, :dbname, :host, :port).
+    # Raises +ArgumentError+ If specified postgresql service is not found.
+    def self.options_for_svc(service_name,options={})
+      service_props = CFRuntime::CloudApp.service_props(service_name)
+      if service_props.nil?
+        raise ArgumentError.new("Service with name #{service_name} not found")
+      end
+      cfoptions = options
+      cfoptions[:host] = service_props[:host]
+      cfoptions[:port] = service_props[:port]
+      cfoptions[:user] = service_props[:username]
+      cfoptions[:password] = service_props[:password]
+      cfoptions[:dbname] = service_props[:database]
+      cfoptions
+    end
+  end
+end

data/lib/cfruntime/properties.rb

@@ -0,0 +1,124 @@
+module CFRuntime
+
+  require 'crack/json'
+  require 'uri'
+
+  class CloudApp
+
+    class << self
+      # Returns true if this code is running on Cloud Foundry
+      def running_in_cloud?()
+        !ENV['VCAP_APPLICATION'].nil?
+      end
+
+      # Returns the application host name
+      def host
+        ENV['VCAP_APP_HOST']
+      end
+
+      # Returns the port bound to the application
+      def port
+        ENV['VCAP_APP_PORT']
+      end
+
+      # Parses the VCAP_SERVICES environment variable and returns a Hash of properties
+      # for the specified service name.  If only one service of a particular type is bound
+      # to the application, service_props(type) will also work.
+      # Example: service_props('mysql').
+      # Returns nil if service with specified name is not found or if zero or multiple services
+      # of a specified type are found.
+      def service_props(service_name)
+        registered_svcs = {}
+        if ENV['VCAP_SERVICES']
+          svcs = Crack::JSON.parse(ENV['VCAP_SERVICES'])
+        else
+          svcs = {}
+        end
+        svcs.each do |key,list|
+          label, version = key.split('-')
+          list.each do |svc|
+            name = svc["name"]
+            serviceopts = {}
+            serviceopts[:label] = label
+            serviceopts[:version] = version
+            serviceopts[:name] = name
+            cred = svc["credentials"]
+            if label =~ /rabbitmq/
+              if cred['url']
+                #The RabbitMQ default vhost
+                vhost = '/'
+                # The new "srs" credentials format
+                uri=URI.parse(cred['url'])
+                user=URI.unescape(uri.user) if uri.user
+                passwd=URI.unescape(uri.password) if uri.password
+                host=uri.host
+                port=uri.port
+                if uri.path =~ %r{^/(.*)}
+                  raise ArgumentError.new("multiple segments in path of amqp URI: #{uri}") if $1.index('/')
+                  vhost = URI.unescape($1)
+                end
+                serviceopts[:url] = cred['url']
+              else
+                # The "old" credentials format
+                user,passwd,host,port,vhost = %w(user pass hostname port vhost).map {|key|
+                  cred[key]}
+              end
+              serviceopts[:vhost] = vhost
+            else
+              user,passwd,host,port,dbname,db = %w(username password hostname port name db).map {|key|
+                cred[key]}
+              if label == "mongodb"
+                serviceopts[:db] = db
+              else
+                serviceopts[:database] = dbname
+              end
+            end
+            serviceopts[:username] = user
+            serviceopts[:password] = passwd
+            serviceopts[:host] = host
+            serviceopts[:port] = port
+            registered_svcs[name] = serviceopts
+            if list.count == 1
+              registered_svcs[label] = serviceopts
+            end
+          end
+        end
+        registered_svcs[service_name]
+      end
+
+      # Parses the VCAP_SERVICES environment variable and returns an array of Service
+      # names bound to the current application.
+      def service_names
+        service_names = []
+        if ENV['VCAP_SERVICES']
+          Crack::JSON.parse(ENV['VCAP_SERVICES']).each do |key,list|
+            list.each do |svc|
+              service_names << svc["name"]
+            end
+          end
+        end
+        service_names
+      end
+
+      # Parses the VCAP_SERVICES environment variable and returns an array of Service
+      # names of the specified type bound to the current application.
+      # Example: service_names_of_type('mysql')
+      def service_names_of_type(type)
+        service_names = []
+        if ENV['VCAP_SERVICES']
+          Crack::JSON.parse(ENV['VCAP_SERVICES']).each do |key,list|
+            label, version = key.split('-')
+            list.each do |svc|
+              if label == type
+                service_names << svc["name"]
+              end
+            end
+          end
+        end
+        service_names
+      end
+    end
+
+  end
+
+end