buildpack-support 1.0.0

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

data/NOTICE

@@ -0,0 +1,2 @@
+Cloud Foundry Buildpack Support
+Copyright 2014 the original author or authors.

data/docs/cache.md

@@ -0,0 +1,77 @@
+# Caches
+Many buildpack components will want to cache large files that are downloaded for applications.  `buildpack-support` provides a cache abstraction to encapsulate this behavior.  The cache abstraction is comprised of two cache types, each with the same signature.
+
+```ruby
+# Retrieves an item from the cache.  Retrieval of the item uses the following algorithm:
+#
+# 1. Obtain an exclusive lock based on the URI of the item. This allows concurrency for different items, but not for
+#    the same item.
+# 2. If the the cached item does not exist, download from +uri+ and cache it, its +Etag+, and its +Last-Modified+
+#    values if they exist.
+# 3. If the cached file does exist, and the original download had an +Etag+ or a +Last-Modified+ value, attempt to
+#    download from +uri+ again.  If the result is +304+ (+Not-Modified+), then proceed without changing the cached
+#    item.  If it is anything else, overwrite the cached file and its +Etag+ and +Last-Modified+ values if they exist.
+# 4. Downgrade the lock to a shared lock as no further mutation of the cache is possible.  This allows concurrency for
+#    read access of the item.
+# 5. Yield the cached file (opened read-only) to the passed in block. Once the block is complete, the file is closed
+#    and the lock is released.
+#
+# @param [String] uri the uri to download if the item is not already in the cache.  Also used in the case where the
+#                     item is already in the cache, to validate that the item is up to date
+# @yieldparam [File] file the file representing the cached item. In order to ensure that the file is not changed or
+#                    deleted while it is being used, the cached item can only be accessed as part of a block.
+# @return [Void]
+def get(uri)
+
+# Remove an item from the cache
+#
+# @param [String] uri the URI of the item to remove
+# @return [Void]
+def evict(uri)
+```
+
+Use of a cache might look like the following:
+
+```ruby
+require 'buildpack_support/cache/download_cache'
+
+BuildpackSupport::Cache::DownloadCache.new.get(uri) do |file|
+  YAML.load_file(file)
+end
+```
+
+## Configuration
+For general information on configuration using `buildpack-support`, refer to the [configuration documentation][c].
+
+Caching can be configured by modifying the `config/cache.yml` file in a buildpack.
+
+| Name | Description
+| ---- | -----------
+| `remote_downloads` | This property can take the value `enabled` or `disabled`. <p>The default value of `enabled` means that the buildpack will check the internet connection and remember the result for the remainder of the buildpack invocation. If the internet is available, it will then be used to download files. If the internet is not available, cache will be consulted instead. <p>Alternatively, the property may be set to `disabled` which avoids the check for an internet connection, does not attempt downloads, and consults the cache instead.
+
+## `BuildpackSupport::Cache::ApplicationCache`
+The `ApplicationCache` is a cache that persists files into the application cache passed to the `compile` script.  It examines `ARGV[1]` for the cache location and configures itself accordingly.  The constructor signature looks the following:
+
+```ruby
+# 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
+```
+
+## `BuildpackSupport::Cache::DownloadCache`
+The `DownloadCache` is the more generic of the two caches.  It allows you to create a cache that persists files anywhere that write access is available.  The constructor signature looks the following:
+
+```ruby
+# Creates an instance of the cache that is backed by a number of filesystem locations.  The first argument
+# (+mutable_cache_root+) is the only location that downloaded files will be stored in.
+#
+# @param [Pathname] mutable_cache_root the filesystem location in which find cached files in.  This will also be
+#                                      the location that all downloaded files are written to.
+# @param [Pathname] immutable_cache_roots other filesystem locations to find cached files in.  No files will be
+#                                         written to these locations.
+def initialize(mutable_cache_root = Pathname.new(Dir.tmpdir), *immutable_cache_roots)
+```
+
+[c]: configuration.md

data/docs/component.md

@@ -0,0 +1 @@
+TODO: Document component support

data/docs/configuration.md

@@ -0,0 +1,27 @@
+# Configuration
+Many buildpack components will need to read user configuration in order to operate.  `buildpack-support` provides a utility class to encapsulate the reading of this configuration in a uniform way from a centralized location.  Configuration is located in the `config` directory of a buildpack, and is read from files matching the `<COMPONENT-ID>.yml` pattern.
+
+```ruby
+# Loads a configuration file from the buildpack configuration directory.  If the configuration file does not exist,
+# returns an empty hash.
+#
+# @param [String] identifier the identifier of the configuration
+# @return [Hash] the configuration or an empty hash if the configuration file does not exist
+def load(identifier)
+```
+
+Use of the configuration utility might look like the following:
+
+```ruby
+require 'buildpack_support/configuration_utils'
+
+BuildpackSupport::ConfigurationUtils.new.load('cache')['remote_downloads']
+```
+
+## Configuring an existing buildpack
+Buildpack configuration is supported through the use of Git repository forking.  The easiest way to accomplish this is to use [GitHub's forking functionality][f] to create a copy of this repository.  Make the required configuration changes in this copy of the repository and then specify the URL of the new repository when pushing applications to Cloud Foundry.  If the modifications are generally applicable to the Cloud Foundry community, please submit a [pull request][p] with the changes.
+
+To lean how to configuration various properties of the buildpack, check the "Configuration" documentation for each component.
+
+[f]: https://help.github.com/articles/fork-a-repo
+[p]: https://help.github.com/articles/using-pull-requests

data/docs/logging.md

@@ -0,0 +1,54 @@
+# Logging
+Many buildpack components will want to log output for the users to see.  `buildpack-support` provides support for this functionality by reusing the [Ruby `Logger` API][l] and adding with a new API for initialzing the logger.
+
+```ruby
+# Sets up the logger factory
+#
+# @param [Pathname] app_dir the application directory
+# @return [Void]
+def setup(app_dir)
+
+# Returns a configured logger for a given +Class+.  The +Class+ that is passed in is used as the +progname+, for all
+# messages logged by the logger. If this is called before the +setup()+ method, a failure will be generated.
+#
+# @param [Class] klass the class that the logger is created for
+# @return [Logger] the logger that was requested
+def get_logger(klass)
+
+# Returns the location of the log file.  If this is called before the +setup()+ method, a failure will be generated.
+#
+# @return [Pathname] the location of the log file
+def log_file
+
+# Resets the configuration of the factory
+#
+# @return [Void]
+def reset
+```
+Use of a cache might look like the following:
+
+```ruby
+require 'buildpack_support/logging/logger_factory'
+
+@logger = BuildpackSupport::Logging::LoggerFactory.instance.get_logger BuildpackVersion
+
+@logger.info 'simple message'
+@logger.debug { generate_costly_message }
+```
+
+`buildpack-support` logs all messages, regardless of severity to `<APP-DIR>/.buildpack.log`.  It also logs messages to `$stderr`, filtered by a configured severity.
+
+The `BuildpackSupport::Logging::LoggerFactory` class manages instances that meet the contract of the standard Ruby `Logger`. In normal usage, the `BuildpackSupport::BaseBuildpack` class configures the `LoggerFactory`.  `Logger` instances are then retrieved for classes that require them.
+
+## Configuration
+For general information on configuration using `buildpack-support`, refer to the [configuration documentation][c].
+
+The console logging severity filter is set to `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` using the following strategies in descending priority:
+
+1. `$BP_LOG_LEVEL` environment variable.  This can be set using the `cf set-env <app name> BP_LOG_LEVEL DEBUG` command.
+2. Ruby `--verbose` and `--debug` flags.  Setting either of these is the equivalent of setting the log severity level to `DEBUG`.
+3. `default_log_level` value in `config/logging.yml` in a buildpack
+4. Fallback to `INFO` if none of the above are set
+
+[c]: configuration.md
+[l]: http://www.rubydoc.info/stdlib/logger/Logger

data/docs/other.md

@@ -0,0 +1 @@
+TODO: Document other utilities

data/docs/rake.md

@@ -0,0 +1 @@
+TODO: Document Rake tasks

data/docs/repository.md

@@ -0,0 +1,116 @@
+# Repositories
+Many buildpack components will want to provide multiple versions of binaries.  `buildpack-support` provides a repository abstraction to encapsulate version resolution and download URI creation.
+
+```ruby
+# Finds an instance of the file based on the configuration and wraps any exceptions
+# to identify the component.
+#
+# @param [String] component_name the name of the component
+# @param [Hash] configuration the configuration
+# @option configuration [String] :repository_root the root directory of the repository
+# @option configuration [String] :version the version of the file to resolve
+# @yield the version to a block for validation.  An error should be raised if the version is not valid
+# @yieldparam version [BuildpackSupport::TokenizedVersion] the version to validate
+# @return [String] the URI of the chosen version of the file
+# @return [TokenizedVersion] the chosen version of the file
+def find_item(component_name, configuration)
+```
+
+Use of a repository might look like the following:
+
+```ruby
+require 'buildpack_support/repository/configured_item'
+
+configured_item = BuildpackSupport::Repository::ConfiguredItem.new
+version, uri = configured_item.find_item component_name, configuration
+```
+
+or with version validation:
+
+```ruby
+require 'buildpack_support/repository/configured_item'
+
+configured_item = BuildpackSupport::Repository::ConfiguredItem.new
+version, uri = configured_item.find_item component_name, configuration { |version| validate_version version }
+```
+
+## Repository Structure
+The repository is an HTTP-accessible collection of files.  The repository root must contain an `index.yml` file ([example][i]) that is a mapping of concrete versions to absolute URIs consisting of a series of lines of the form:
+
+```yaml
+<version>: <URI>
+```
+
+The collection of files may be stored alongside the index file or elsewhere.
+
+An example filesystem might look like:
+
+```
+/index.yml
+/openjdk-1.6.0_27.tar.gz
+/openjdk-1.7.0_21.tar.gz
+/openjdk-1.8.0_M7.tar.gz
+```
+
+## Wildcards
+`repository_root` declarations in component configuration files can have variables in them.  These variables are replaced by the repository infrastructure and the resulting URI is used when retrieving the repository index.
+
+| Variable | Description |
+| -------- | ----------- |
+| `{default.repository.root}` | The common root for all repositories.  Currently defaults to `http://download.run.pivotal.io`.
+| `{platform}` | The platform that the application is running on.  Currently detects `centos6`, `lucid`, `mountainlion`, `precise`, and `trusty`.
+| `{architecture}` | The architecture of the system as returned by Ruby.  The value is typically one of `x86_64` or `x86`.
+
+## Version Syntax and Ordering
+Versions are composed of major, minor, micro, and optional qualifier parts (`<major>.<minor>.<micro>[_<qualifier>]`).  The major, minor, and micro parts must be numeric.  The qualifier part is composed of letters, digits, and hyphens.  The lexical ordering of the qualifier is:
+
+1. hyphen
+2. lowercase letters
+3. uppercase letters
+4. digits
+
+## Configuration
+For general information on configuration using `buildpack-support`, refer to the [configuration documentation][c].
+
+Repositories can be configured by modifying the `config/repository.yml` file in a buildpack.
+
+| Name | Description
+| ---- | -----------
+| `default_repository_root` | This property can take a URI that is used as a common root for all of the repositories used by the buildpack.  The value is substituted for the `{default.repository.root}` variable in `repository_root` declarations.
+
+## `BuildpackSupport::Repository::ConfiguredItem`
+The `ConfiguredItem` class is responsible for downloading (and caching) a repository index and using provided configuration to resolve the version and download URI of a dependency.  The constructor signature looks the following:
+
+```ruby
+# Creates a new instance
+#
+# @param [VersionResolver] version_resolver the version resolver to use when finding items
+def initialize(version_resolver = WildcardVersionResolver.new)
+```
+
+## Version Resolvers
+`VersionResolvers` are an abstraction that allows different version resolution strategies to be plugged into the `ConfiguredItem`.  The API for a `VersionResolver` looks like the following
+
+```ruby
+# Resolves a version from a collection of versions.  The +candidate_version+ must be structured as up to three numeric
+# components, followed by an optional string component.  The resolution returns the maximum of the versions that match
+# the candidate version
+#
+# @param [TokenizedVersion] candidate_version the version to resolve
+# @param [Array<String>] versions the collection of versions to resolve against
+# @return [TokenizedVersion] the resolved version
+# @raise if no version can be resolved
+def resolve(candidate_version, versions)
+```
+
+## `BuildpackSupport::Repository::WildcardVersionResolver`
+The default `VersionResolver` that allows you to specify a bounded range of versions to use, in addition to a specific version.  Appending the `+` symbol to a version prefix chooses the latest version that begins with the prefix.
+
+| Example | Description
+| ------- | -----------
+| `1.+`   	| Selects the greatest available version less than `2.0.0`.
+| `1.7.+` 	| Selects the greatest available version less than `1.8.0`.
+| `1.7.0_+` | Selects the greatest available version less than `1.7.1`. Use this syntax to stay up to date with the latest security releases in a particular version.
+
+[c]: configuration.md
+[i]: http://download.pivotal.io.s3.amazonaws.com/openjdk/lucid/x86_64/index.yml