buildpack-support 1.0.0

data/lib/buildpack_support/component/base_component.rb

@@ -0,0 +1,78 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/cache/application_cache'
+require 'buildpack_support/component'
+require 'buildpack_support/component/downloads'
+require 'buildpack_support/format_duration'
+require 'buildpack_support/space_case'
+require 'fileutils'
+
+module BuildpackSupport
+  module Component
+
+    # A convenience base class for all components in the buildpack.  This base class ensures that the contents of the
+    # +context+ are assigned to instance variables matching their keys.  It also ensures that all contract methods are
+    # implemented.
+    class BaseComponent
+      include Downloads
+
+      # Creates an instance.  The contents of +context+ are assigned to the instance variables matching their keys.
+      #
+      # @param [Hash] context a collection of utilities used by components
+      # @option context [BuildpackSupport::Component::Application] :application the application
+      # @option context [Hash] :configuration the component's configuration
+      # @option context [BuildpackSupport::Component::Droplet] :droplet the droplet
+      def initialize(context)
+        @application    = context[:application]
+        @component_name = self.class.to_s.space_case
+        @configuration  = context[:configuration]
+        @droplet        = context[:droplet]
+      end
+
+      # If the component should be used when staging an application
+      #
+      # @return [Array<String>, String, nil] If the component should be used when staging the application, a +String+ or
+      #                                      an +Array<String>+ that uniquely identifies the component (e.g.
+      #                                      +open_jdk=1.7.0_40+).  Otherwise, +nil+.
+      def detect
+        fail "Method 'detect' must be defined"
+      end
+
+      # Modifies the application's file system.  The component is expected to transform the application's file system in
+      # whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
+      # component.  Status output written to +STDOUT+ is expected as part of this invocation.
+      #
+      # @return [Void]
+      def compile
+        fail "Method 'compile' must be defined"
+      end
+
+      # Modifies the application's runtime configuration. The component is expected to transform members of the +context+
+      # (e.g. +@java_home+, +@java_opts+, etc.) in whatever way is necessary to support the function of the component.
+      #
+      # Container components are also expected to create the command required to run the application.  These components
+      # are expected to read the +context+ values and take them into account when creating the command.
+      #
+      # @return [void, String] components other than containers are not expected to return any value.  Container
+      #                        components are expected to return the command required to run the application.
+      def release
+        fail "Method 'release' must be defined"
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/component/base_droplet.rb

@@ -0,0 +1,96 @@
+# Encoding: utf-8
+# # Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+require 'buildpack_support/directory_finder'
+require 'buildpack_support/logging/logger_factory'
+require 'buildpack_support/filtering_pathname'
+require 'fileutils'
+require 'pathname'
+
+module BuildpackSupport
+  module Component
+
+    # An abstraction around the droplet that will be created and used at runtime.  This abstraction is intended to hide
+    # the work done by components within their own sandboxes, while exposing changes made to the user's application.
+    # Think of this as a mutable representation of a component's sandbox and the application that was uploaded.
+    #
+    # A new instance of this type should be created for each component.
+    class BaseDroplet
+      extend BuildpackSupport::DirectoryFinder
+
+      # @!attribute [r] component_id
+      # @return [String] the id of component using this droplet
+      attr_reader :component_id
+
+      # @!attribute [r] root
+      # @return [BuildpackSupport::FilteringPathname] the root of the droplet's fileystem filtered so that it
+      #                                                  excludes files in the sandboxes of other components
+      attr_reader :root
+
+      # @!attribute [r] sandbox
+      # @return [Pathname] the root of the component's sandbox
+      attr_reader :sandbox
+
+      # Creates a new instance of the droplet abstraction
+      #
+      # @param [String] component_id                          the id of the component that will use this +Droplet+
+      # @param [Pathname] root                                the root of the droplet
+      def initialize(component_id, root)
+        @component_id = component_id
+        @logger       = BuildpackSupport::Logging::LoggerFactory.instance.get_logger self.class
+
+        buildpack_root = root + '.buildpack'
+        sandbox_root   = buildpack_root + component_id
+
+        @sandbox = BuildpackSupport::FilteringPathname.new(sandbox_root, ->(path) { in?(path, sandbox_root) }, true)
+        @root    = BuildpackSupport::FilteringPathname.new(root,
+                                                           ->(path) { !in?(path, buildpack_root) || in?(path, @sandbox) },
+                                                           true)
+      end
+
+      # Copy resources from a components resources directory to a directory
+      #
+      # @param [Pathname] target_directory the directory to copy to.  Defaults to the component's +sandbox+.
+      # @return [Void]
+      def copy_resources(target_directory = @sandbox)
+        resources = RESOURCES_DIRECTORY + @component_id
+
+        if resources.exist?
+          FileUtils.mkdir_p target_directory
+          FileUtils.cp_r("#{resources}/.", target_directory)
+          @logger.debug { "Resources #{resources} found" }
+        else
+          @logger.debug { "No resources #{resources} found" }
+        end
+      end
+
+      private
+
+      RESOURCES_DIRECTORY = BaseDroplet.load_path_peer('resources').freeze
+
+      private_constant :RESOURCES_DIRECTORY
+
+      def in?(path, root)
+        path.ascend do |parent|
+          return true if parent == root
+        end
+        false
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/component/downloads.rb

@@ -0,0 +1,88 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+require 'buildpack_support/component/with_timing'
+require 'buildpack_support/shell'
+
+module BuildpackSupport
+  module Component
+
+    # A mixin that provides methods for downloading, caching, and unpacking files
+    module Downloads
+      include BuildpackSupport::Shell
+      include WithTiming
+
+      # Downloads an item with the given name and version from the given URI, then yields the resultant file to the given
+      # block.
+      #
+      # @param [BuildpackSupport::TokenizedVersion] version
+      # @param [String] uri
+      # @param [String] name an optional name for the download.  Defaults to +@component_name+.
+      # @return [Void]
+      def download(version, uri, name = @component_name)
+        download_start_time = Time.now
+        print "-----> Downloading #{name} #{version} from #{uri} "
+
+        BuildpackSupport::Cache::ApplicationCache.new.get(uri) do |file, downloaded|
+          puts downloaded ? "(#{(Time.now - download_start_time).duration})" : '(found in cache)'
+          yield file
+        end
+      end
+
+      # Downloads a given TAR file and expands it.
+      #
+      # @param [String] version the version of the download
+      # @param [String] uri the uri of the download
+      # @param [Pathname] target_directory the directory to expand the TAR file to.  Defaults to the component's sandbox.
+      # @param [String] name an optional name for the download and expansion.  Defaults to +@component_name+.
+      # @return [Void]
+      def download_tar(version, uri, target_directory = @droplet.sandbox, name = @component_name)
+        download(version, uri, name) do |file|
+          with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
+            FileUtils.mkdir_p target_directory
+            shell "tar xzf #{file.path} -C #{target_directory} --strip 1 2>&1"
+          end
+        end
+      end
+
+      # Downloads a given ZIP file and expands it.
+      #
+      # @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
+      # @param [Pathname] target_directory the directory to expand the ZIP file to.  Defaults to the component's sandbox.
+      # @param [String] name an optional name for the download.  Defaults to +@component_name+.
+      # @return [Void]
+      def download_zip(version, uri, strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
+        download(version, uri, name) do |file|
+          with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
+            if strip_top_level
+              Dir.mktmpdir do |root|
+                shell "unzip -qq #{file.path} -d #{root} 2>&1"
+
+                FileUtils.mkdir_p target_directory.parent
+                FileUtils.mv Pathname.new(root).children.first, target_directory
+              end
+            else
+              FileUtils.mkdir_p target_directory
+              shell "unzip -qq #{file.path} -d #{target_directory} 2>&1"
+            end
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/component/services.rb

@@ -0,0 +1,84 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+require 'buildpack_support/logging/logger_factory'
+
+module BuildpackSupport
+  module Component
+
+    # An abstraction encapsulating the +VCAP_SERVICES+ of an application.
+    #
+    # A new instance of this type should be created once for the application.
+    class Services < Array
+
+      def initialize(raw)
+        concat raw.values.flatten
+      end
+
+      # Compares the name, label, and tags of each service to the given +filter+.  The method returns +true+ if the
+      # +filter+ matches exactly one service, +false+ otherwise.
+      #
+      # @param [Regexp, String] filter a +RegExp+ or +String+ to match against the name, label, and tags of the services
+      # @param [String] required_credentials an optional list of keys that must exist in the credentials payload of
+      #                                             the candidate service
+      # @return [Boolean] +true+ if the +filter+ matches exactly one service with the required credentials, +false+
+      #                   otherwise.
+      def one_service?(filter, *required_credentials)
+        candidates = select(&matcher(filter))
+
+        match = false
+        if candidates.one?
+          if credentials?(candidates.first['credentials'], required_credentials)
+            match = true
+          else
+            logger = BuildpackSupport::Logging::LoggerFactory.instance.get_logger Services
+            logger.warn do
+              "A service with a name label or tag matching #{filter} was found, but was missing one of the required" \
+            " credentials #{required_credentials}"
+            end
+          end
+        end
+
+        match
+      end
+
+      # Compares the name, label, and tags of each service to the given +filter+.  The method returns the first service
+      # that the +filter+ matches.  If no service matches, returns +nil+
+      #
+      # @param [Regexp, String] filter a +RegExp+ or +String+ to match against the name, label, and tags of the services
+      # @return [Hash, nil] the first service that +filter+ matches.  If no service matches, returns +nil+.
+      def find_service(filter)
+        find(&matcher(filter))
+      end
+
+      private
+
+      def credentials?(candidate, required_keys)
+        required_keys.all? { |k| candidate.key? k }
+      end
+
+      def matcher(filter)
+        filter = Regexp.new(filter) unless filter.kind_of?(Regexp)
+
+        lambda do |service|
+          service['name'] =~ filter || service['label'] =~ filter || service['tags'].any? { |tag| tag =~ filter }
+        end
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/component/versioned_dependency_component.rb

@@ -0,0 +1,71 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+require 'buildpack_support/component/base_component'
+require 'buildpack_support/component/versioned_downloads'
+require 'buildpack_support/dash_case'
+require 'buildpack_support/repository/configured_item'
+require 'fileutils'
+require 'tmpdir'
+
+module BuildpackSupport
+  module Component
+
+    # A convenience base class for all components that have a versioned dependency.  In addition to the functionality
+    # inherited from +BaseComponent+ this class also ensures that managed dependencies are handled in a uniform manner.
+    class VersionedDependencyComponent < BaseComponent
+      include VersionedDownloads
+
+      # Creates an instance.  In addition to the functionality inherited from +BaseComponent+, +@version+ and +@uri+
+      # instance variables are exposed.
+      #
+      # @param [Hash] context a collection of utilities used by components
+      # @param [Block, nil] version_validator an optional version validation block
+      def initialize(context, configured_item = BuildpackSupport::Repository::ConfiguredItem.new, &version_validator)
+        super(context)
+
+        if supports?
+          @version, @uri = configured_item.find_item(@component_name, @configuration, &version_validator)
+        else
+          @version = nil
+          @uri     = nil
+        end
+      end
+
+      # (see BuildpackSupport::Component::BaseComponent#detect)
+      def detect
+        @version ? id(@version) : nil
+      end
+
+      protected
+
+      # Whether or not this component supports this application
+      #
+      # @return [Boolean] whether or not this component supports this application
+      def supports?
+        fail "Method 'supports?' must be defined"
+      end
+
+      private
+
+      def id(version)
+        "#{self.class.to_s.dash_case}=#{version}"
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/component/versioned_downloads.rb

@@ -0,0 +1,57 @@
+# Encoding: utf-8
+# Copyright 2013-2014 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'buildpack_support/component'
+require 'buildpack_support/component/downloads'
+require 'buildpack_support/shell'
+
+module BuildpackSupport
+  module Component
+
+    # A mixin that provides methods for downloading, caching, and unpacking files where a version and uri are available
+    module VersionedDownloads
+      include BuildpackSupport::Shell
+      include Downloads
+
+      private
+
+      alias_method :super_download_tar, :download_tar
+      alias_method :super_download_zip, :download_zip
+
+      public
+
+      # Downloads a given TAR file and expands it.
+      #
+      # @param [Pathname] target_directory the directory to expand the TAR file to.  Defaults to the component's sandbox.
+      # @param [String] name an optional name for the download and expansion.  Defaults to +@component_name+.
+      # @return [Void]
+      def download_tar(target_directory = @droplet.sandbox, name = @component_name)
+        super_download_tar @version, @uri, target_directory, name
+      end
+
+      # Downloads a given ZIP file and expands it.
+      #
+      # @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
+      # @param [Pathname] target_directory the directory to expand the ZIP file to.  Defaults to the component's sandbox.
+      # @param [String] name an optional name for the download.  Defaults to +@component_name+.
+      # @return [Void]
+      def download_zip(strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
+        super_download_zip @version, @uri, strip_top_level, target_directory, name
+      end
+
+    end
+
+  end
+end