buildpack-support 1.0.0

data/docs/test.md

@@ -0,0 +1 @@
+TODO: Document Test support code

data/lib/buildpack_support.rb

@@ -0,0 +1,18 @@
+# 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.
+
+# A module encapsulating all of the code for the Buildpack Support utilities
+module BuildpackSupport
+end

data/lib/buildpack_support/base_buildpack.rb

@@ -0,0 +1,166 @@
+# 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'
+require 'buildpack_support/space_case'
+require 'buildpack_support/buildpack_version'
+require 'buildpack_support/component/application'
+require 'buildpack_support/logging/logger_factory'
+require 'buildpack_support/snake_case'
+
+module BuildpackSupport
+
+  # A base class for all buildpack implementations to extend from.  This implementation provides a number of utility methods for dealing with components.
+  class BaseBuildpack
+
+    # Iterates over all of the components to detect if this buildpack can be used to run an application
+    #
+    # @return [Array<String>] An array of strings that identify the components and versions that will be used to run
+    #                         this application.  If no container can run the application, the array will be empty
+    #                         (+[]+).
+    def detect
+      fail "Method 'detect' must be defined"
+    end
+
+    # Transforms the application directory such that the engine, and frameworks can run the application
+    #
+    # @return [Void]
+    def compile
+      fail "Method 'compile' must be defined"
+    end
+
+    # Generates the payload required to run the application.  The payload format is defined by the
+    # {Heroku Buildpack API}[https://devcenter.heroku.com/articles/buildpack-api#buildpack-api].
+    #
+    # @return [String] The payload required to run the application.
+    def release
+      fail "Method 'release' must be defined"
+    end
+
+    protected
+
+    # Returns the components that are detected for an application
+    #
+    # @param [String] type the type of components
+    # @param [String] components the candidate components
+    # @param [Boolean] unique whether there must be _exactly_ one component detected
+    # @return [Array<BuildpackSupport::Component::BaseComponent>] the collection of detected components
+    def component_detection(type, components, unique)
+      detected, _tags = detection type, components, unique
+      detected
+    end
+
+    # Returns the components, and the tags from those components that are detected for an application
+    #
+    # @param [String] type the type of components
+    # @param [Array<BuildpackSupport::Component::BaseComponent>] components the candidate components
+    # @param [Boolean] unique whether there must be _exactly_ one component detected
+    # @return [Array<BuildpackSupport::Component::BaseComponent>] the collection of detected components
+    # @return [Array<String>] the collection of tags from the detected components
+    def detection(type, components, unique)
+      detected = []
+      tags     = []
+
+      components.each do |component|
+        result = component.detect
+
+        next unless result
+
+        detected << component
+        tags << result
+      end
+
+      fail "Application can be run by more than one #{type}: #{names detected}" if unique && detected.size > 1
+      [detected, tags]
+    end
+
+    # +require+ a component based on its id
+    #
+    # @param [Pathname] load_root the +$LOAD_ROOT+ to load the component from
+    # @param [String] component the name of the component to load
+    def require_component(load_root, component)
+      file = load_root + "#{component.snake_case}.rb"
+
+      if file.exist?
+        require component.snake_case
+        @logger.debug { "Successfully required #{component}" }
+      else
+        @logger.debug { "Cannot require #{component} because #{file} does not exist" }
+      end
+    end
+
+    # Returns the tags that are detected for an application
+    #
+    # @param [String] type the type of components
+    # @param [String] components the candidate components
+    # @param [Boolean] unique whether there must be _exactly_ one component detected
+    # @return [Array<String>] the collection of tags from the detected components
+    def tag_detection(type, components, unique)
+      _detected, tags = detection type, components, unique
+      tags
+    end
+
+    private_class_method :new
+
+    private
+
+    def initialize(_app_dir, _application)
+      @logger            = Logging::LoggerFactory.instance.get_logger self.class
+      @buildpack_version = BuildpackVersion.new
+
+      @logger.debug { "Environment Variables: #{ENV.to_hash}" }
+    end
+
+    def names(components)
+      components.map { |component| component.class.to_s.space_case }.join(', ')
+    end
+
+    class << self
+
+      # Main entry to the buildpack.  Initializes the buildpack and all of its dependencies and yields a new instance
+      # to any given block.  Any exceptions thrown as part of the buildpack setup or execution are handled
+      #
+      # @param [String] app_dir the path of the application directory
+      # @param [String] message an error message with an insert for the reason for failure
+      # @yield [Buildpack] the buildpack to work with
+      # @return [Object] the return value from the given block
+      def with_buildpack(app_dir, message)
+        app_dir     = Pathname.new(File.expand_path(app_dir))
+        application = Component::Application.new(app_dir)
+        Logging::LoggerFactory.instance.setup app_dir
+
+        yield new(app_dir, application) if block_given?
+      rescue => e
+        handle_error(e, message)
+      end
+
+      private
+
+      def handle_error(e, message)
+        if Logging::LoggerFactory.instance.initialized
+          logger = Logging::LoggerFactory.instance.get_logger BaseBuildpack
+
+          logger.error { message % e.inspect }
+          logger.debug { "Exception #{e.inspect} backtrace:\n#{e.backtrace.join("\n")}" }
+        end
+
+        abort e.message
+      end
+
+    end
+
+  end
+
+end

data/lib/buildpack_support/buildpack_version.rb

@@ -0,0 +1,124 @@
+# 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'
+require 'buildpack_support/configuration_utils'
+require 'buildpack_support/directory_finder'
+require 'buildpack_support/to_b'
+
+module BuildpackSupport
+
+  # A representation of the buildpack's version.  The buildpack's version is determined using the following algorithm:
+  #
+  # 1. using the +config/version.yml+ file if it exists
+  # 2. using +git+ to determine the remote and hash if the buildpack is in a git repository
+  # 3. unknown
+  class BuildpackVersion
+    extend DirectoryFinder
+
+    # @!attribute [r] hash
+    # @return [String, nil] the Git hash of this version, or +nil+ if it cannot be determined
+    attr_reader :hash
+
+    # @!attribute [r] offline
+    # @return [Boolean] +true+ if the buildpack is offline, +false+ otherwise
+    attr_reader :offline
+
+    # @!attribute [r] remote
+    # @return [String, nil] the Git remote of this version, or +nil+ if it cannot be determined
+    attr_reader :remote
+
+    # @!attribute [r] version
+    # @return [String, nil] the version name of this version, or +nil+ if it cannot be determined
+    attr_reader :version
+
+    # Creates a new instance
+    def initialize(should_log = true)
+      configuration = ConfigurationUtils.new(should_log).load 'version'
+      @hash         = configuration['hash'] || hash
+      @offline      = configuration['offline'] || ENV['OFFLINE'].to_b
+      @remote       = configuration['remote'] || remote
+      @version      = configuration['version'] || ENV['VERSION'] || @hash
+
+      return unless should_log
+
+      logger = Logging::LoggerFactory.instance.get_logger BuildpackVersion
+      logger.debug { to_s }
+    end
+
+    # Returns a +Hash+ representation of the buildpack version.
+    #
+    # @return [Hash] a representation of the buildpack version
+    def to_hash
+      h            = {}
+
+      h['hash']    = @hash if @hash
+      h['offline'] = @offline if @offline
+      h['remote']  = @remote if @remote
+      h['version'] = @version if @version
+
+      h
+    end
+
+    # Creates a string representation of the version.  The string representation looks like the following:
+    # +[[<VERSION> [(offline)] | ] <REMOTE>#<HASH>] | [unknown]+.  Some examples:
+    #
+    # +2.1.2 (offline) | https://github.com/cloudfoundry/java-buildpack.git#12345+ (custom version number, offline buildpack)
+    # +abcde | https://github.com/cloudfoundry/java-buildpack.git#abcde+ (default version number, online buildpack)
+    # +https://github.com/cloudfoundry/java-buildpack#12345+ (cloned buildpack)
+    # +unknown+ (un-packaged, un-cloned)
+    #
+    # @param [Boolean] human_readable whether the output should be human readable or machine readable
+    # @return [String] a +String+ representation of the version
+    def to_s(human_readable = true)
+      s = []
+      s << @version if @version
+      s << (human_readable ? '(offline)' : 'offline') if @offline
+      s << '|' if @version && human_readable
+      s << "#{@remote}##{@hash}" if @remote && @hash
+      s << 'unknown' if s.empty?
+
+      s.join(human_readable ? ' ' : '-')
+    end
+
+    private
+
+    GIT_DIR = BuildpackVersion.load_path_peer('.git').freeze
+
+    private_constant :GIT_DIR
+
+    def git(command)
+      `git --git-dir=#{GIT_DIR} #{command}`.chomp if git? && git_dir?
+    end
+
+    def git?
+      system 'which git > /dev/null'
+    end
+
+    def git_dir?
+      GIT_DIR.exist?
+    end
+
+    def hash
+      git 'rev-parse --short HEAD'
+    end
+
+    def remote
+      git 'config --get remote.origin.url'
+    end
+
+  end
+
+end

data/lib/buildpack_support/cache.rb

@@ -0,0 +1,24 @@
+# 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'
+
+module BuildpackSupport
+
+  # A module encapsulating all of the code for the cache utilities
+  module Cache
+  end
+
+end

data/lib/buildpack_support/cache/application_cache.rb

@@ -0,0 +1,41 @@
+# 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'
+require 'buildpack_support/cache/download_cache'
+
+module BuildpackSupport
+  module Cache
+
+    # An extension of {DownloadCache} that is configured to use the application cache.  The application
+    # cache location is defined by the second argument (<tt>ARGV[1]</tt>) to the +compile+ script.
+    #
+    # <b>WARNING: This cache should only by used by code run by the +compile+ script</b>
+    class ApplicationCache < DownloadCache
+
+      # Creates an instance that is configured to use the application cache.  The application cache location is defined
+      # by the second argument (<tt>ARGV[1]</tt>) to the +compile+ script.
+      #
+      # @raise if the second argument (<tt>ARGV[1]</tt>) to the +compile+ script is +nil+
+      def initialize
+        application_cache_directory = ARGV[1]
+        fail 'Application cache directory is undefined' if application_cache_directory.nil?
+        super(Pathname.new(application_cache_directory), CACHED_RESOURCES_DIRECTORY)
+      end
+
+    end
+
+  end
+end

data/lib/buildpack_support/cache/cached_file.rb

@@ -0,0 +1,103 @@
+# 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 'fileutils'
+require 'buildpack_support/cache'
+
+module BuildpackSupport
+  module Cache
+
+    # Represents a file cached on a filesystem
+    #
+    # Note: this class is thread-safe, however access to the cached files is not
+    class CachedFile
+
+      # Creates an instance of the cached file.  Files created and expected by this class will all be rooted at
+      # +cache_root+.
+      #
+      # @param [Pathname] cache_root the filesystem root for the file created and expected by this class
+      # @param [String] uri a uri which uniquely identifies the file in the cache
+      def initialize(cache_root, uri)
+        FileUtils.mkdir_p cache_root
+
+        key            = URI.escape(uri, '/')
+        @cached        = cache_root + "#{key}.cached"
+        @etag          = cache_root + "#{key}.etag"
+        @last_modified = cache_root + "#{key}.last_modified"
+      end
+
+      # Opens the cached file
+      #
+      # @param [String, integer] mode_enc the mode to open the file in.  Can be a string like +"r"+ or an integer like
+      #                                   +File::CREAT | File::WRONLY+.
+      # @param [Array] additional_args any additional arguments to be passed to the block
+      # @yield [file, additional_args] the cached file and any additional arguments passed in
+      # @return [Void]
+      def cached(mode_enc, *additional_args, &block)
+        @cached.open(mode_enc) { |f| block.call f, *additional_args }
+      end
+
+      # Returns whether or not data is cached.
+      #
+      # @return [Boolean] +true+ if and only if data is cached
+      def cached?
+        @cached.exist?
+      end
+
+      # Destroys the cached file
+      def destroy
+        [@cached, @etag, @last_modified].each { |f| f.delete if f.exist? }
+      end
+
+      # Opens the etag file
+      #
+      # @param [String, integer] mode_enc the mode to open the file in.  Can be a string like +"r"+ or an integer like
+      #                                   +File::CREAT | File::WRONLY+.
+      # @param [Array] additional_args any additional arguments to be passed to the block
+      # @yield [file] the etag file
+      # @return [Void]
+      def etag(mode_enc, *additional_args, &block)
+        @etag.open(mode_enc) { |f| block.call f, *additional_args }
+      end
+
+      # Returns whether or not an etag is stored.
+      #
+      # @return [Boolean] +true+ if and only if an etag is stored
+      def etag?
+        @etag.exist?
+      end
+
+      # Opens the last modified file
+      #
+      # @param [String, integer] mode_enc the mode to open the file in.  Can be a string like +"r"+ or an integer like
+      #                                   +File::CREAT | File::WRONLY+.
+      # @param [Array] additional_args any additional arguments to be passed to the block
+      # @yield [file] the last modified file
+      # @return [Void]
+      def last_modified(mode_enc, *additional_args, &block)
+        @last_modified.open(mode_enc) { |f| block.call f, *additional_args }
+      end
+
+      # Returns whether or not a last modified time stamp is stored.
+      #
+      # @return [Boolean] +true+ if and only if a last modified time stamp is stored
+      def last_modified?
+        @last_modified.exist?
+      end
+
+    end
+
+  end
+end