libpak

README

github.com/paketo-buildpacks/libpak

libpak is a Go library with useful functionality for building Paketo-style buildpacks.

Usage

go get github.com/paketo-buildpacks/libpak

License

This library is released under version 2.0 of the Apache License.

Documentation

Index

• Constants
• func Build(builder libcnb.Builder, options ...libcnb.Option)
• func Detect(detector libcnb.Detector, options ...libcnb.Option)
• func IsNoValidDependencies(err error) bool
• func Main(detector libcnb.Detector, builder libcnb.Builder, options ...libcnb.Option)
• func ShallowMerge(a, b libcnb.BuildpackPlanEntry) (libcnb.BuildpackPlanEntry, error)
• type BuildpackConfiguration
• type BuildpackDependency
  • func (b BuildpackDependency) AsBOMEntry() libcnb.BOMEntry
• type BuildpackDependencyLicense
• type BuildpackMetadata
  • func NewBuildpackMetadata(metadata map[string]interface{}) (BuildpackMetadata, error)
• type ConfigurationResolver
  • func NewConfigurationResolver(buildpack libcnb.Buildpack, logger *bard.Logger) (ConfigurationResolver, error)
  • func (c *ConfigurationResolver) Resolve(name string) (string, bool)
• type DependenciesFormatter
  • func (d DependenciesFormatter) String() string
• type DependencyCache
  • func NewDependencyCache(context libcnb.BuildContext) (DependencyCache, error)
  • func (d *DependencyCache) Artifact(dependency BuildpackDependency, mods ...RequestModifierFunc) (*os.File, error)
• type DependencyLayerContributor
  • func NewDependencyLayer(dependency BuildpackDependency, cache DependencyCache, types libcnb.LayerTypes) (DependencyLayerContributor, libcnb.BOMEntry)
  • func (d *DependencyLayerContributor) Contribute(layer libcnb.Layer, f DependencyLayerFunc) (libcnb.Layer, error)
  • func (d *DependencyLayerContributor) LayerName() string
  • func (d *DependencyLayerContributor) Name() string
• type DependencyLayerFunc
• type DependencyResolver
  • func NewDependencyResolver(context libcnb.BuildContext) (DependencyResolver, error)
  • func (d *DependencyResolver) Resolve(id string, version string) (BuildpackDependency, error)
• type HelperLayerContributor
  • func NewHelperLayer(buildpack libcnb.Buildpack, names ...string) (HelperLayerContributor, libcnb.BOMEntry)
  • func (h HelperLayerContributor) Contribute(layer libcnb.Layer) (libcnb.Layer, error)
  • func (h HelperLayerContributor) Name() string
• type LayerContributor
  • func NewLayerContributor(name string, expectedMetadata interface{}, expectedTypes libcnb.LayerTypes) LayerContributor
  • func (l *LayerContributor) Contribute(layer libcnb.Layer, f LayerFunc) (libcnb.Layer, error)
• type LayerFunc
• type MergeFunc
• type NoValidDependenciesError
  • func (n NoValidDependenciesError) Error() string
• type PlanEntryResolver
  • func (p *PlanEntryResolver) Resolve(name string) (libcnb.BuildpackPlanEntry, bool, error)
  • func (p *PlanEntryResolver) ResolveWithMerge(name string, f MergeFunc) (libcnb.BuildpackPlanEntry, bool, error)
• type RequestModifierFunc

Constants

const (
	// BionicStackID is the ID for the Cloud Native Buildpacks bionic stack.
	BionicStackID = "io.buildpacks.stacks.bionic"

	// TinyStackID is the ID for the Paketo Buildpacks tiny stack.
	TinyStackID = "io.paketo.stacks.tiny"
)

Functions

func Build

func Build(builder libcnb.Builder, options ...libcnb.Option)

Build is called by the main function of a buildpack, for build.

func Detect

func Detect(detector libcnb.Detector, options ...libcnb.Option)

Detect is called by the main function of a buildpack, for detection.

func IsNoValidDependencies

func IsNoValidDependencies(err error) bool

IsNoValidDependencies indicates whether an error is a NoValidDependenciesError.

func Main

func Main(detector libcnb.Detector, builder libcnb.Builder, options ...libcnb.Option)

Main is called by the main function of a buildpack, encapsulating both detection and build in the same binary.

func ShallowMerge

func ShallowMerge(a, b libcnb.BuildpackPlanEntry) (libcnb.BuildpackPlanEntry, error)

ShallowMerge merges two BuildpackPlanEntry's together. Declared versions are combined with a comma delimiter and metadata is combined with the values for b taking priority over the values of a when the keys are duplicated.

Types

type BuildpackConfiguration

type BuildpackConfiguration struct {

	// Build indicates whether the configuration is for build-time.  Optional.
	Build bool `toml:"build"`

	// Default is the default value of the configuration parameter.  Optional.
	Default string `toml:"default"`

	// Description is the description of the configuration parameter.
	Description string `toml:"description"`

	// Launch indicates whether the configuration is for launch-time.  Optional.
	Launch bool `toml:"launch"`

	// Name is the environment variable name of the configuration parameter.
	Name string `toml:"name"`
}

BuildpackConfiguration represents a build or launch configuration parameter.

type BuildpackDependency

type BuildpackDependency struct {
	// ID is the dependency ID.
	ID string `toml:"id"`

	// Name is the dependency name.
	Name string `toml:"name"`

	// Version is the dependency version.
	Version string `toml:"version"`

	// URI is the dependency URI.
	URI string `toml:"uri"`

	// SHA256 is the hash of the dependency.
	SHA256 string `toml:"sha256"`

	// Stacks are the stacks the dependency is compatible with.
	Stacks []string `toml:"stacks"`

	// Licenses are the stacks the dependency is distributed under.
	Licenses []BuildpackDependencyLicense `toml:"licenses"`
}

BuildpackDependency describes a dependency known to the buildpack.

func (BuildpackDependency) AsBOMEntry

func (b BuildpackDependency) AsBOMEntry() libcnb.BOMEntry

AsBOMEntry renders a bill of materials entry describing the dependency.

type BuildpackDependencyLicense

type BuildpackDependencyLicense struct {

	// Type is the type of the license.  This is typically the SPDX short identifier.
	Type string `toml:"type"`

	// URI is the location where the license can be found.
	URI string `toml:"uri"`
}

BuildpackDependencyLicense represents a license that a BuildpackDependency is distributed under. At least one of Name or URI MUST be specified.

type BuildpackMetadata

type BuildpackMetadata struct {

	// Configurations are environment variables that can be used at build time to configure the buildpack and launch
	// time to configure the application.
	Configurations []BuildpackConfiguration

	// Dependencies are the dependencies known to the buildpack.
	Dependencies []BuildpackDependency

	// IncludeFiles describes the files to include in the package.
	IncludeFiles []string

	// PrePackage describes a command to invoke before packaging.
	PrePackage string
}

BuildpackMetadata is an extension to libcnb.Buildpack's metadata with opinions.

func NewBuildpackMetadata

func NewBuildpackMetadata(metadata map[string]interface{}) (BuildpackMetadata, error)

NewBuildpackMetadata creates a new instance of BuildpackMetadata from the contents of libcnb.Buildpack.Metadata

type ConfigurationResolver

type ConfigurationResolver struct {

	// Configurations are the configurations to resolve against
	Configurations []BuildpackConfiguration
}

ConfigurationResolver provides functionality for resolving a configuration value.

func NewConfigurationResolver

func NewConfigurationResolver(buildpack libcnb.Buildpack, logger *bard.Logger) (ConfigurationResolver, error)

NewConfigurationResolver creates a new instance from buildpack metadata. Logs configuration options to the body level int the form 'Set $Name to configure $Description[. Default <i>$Default</i>.]'.

func (*ConfigurationResolver) Resolve

func (c *ConfigurationResolver) Resolve(name string) (string, bool)

Resolve resolves the value for a configuration option, returning the default value and false if it was not set.

type DependenciesFormatter

type DependenciesFormatter []BuildpackDependency

DependenciesFormatter is the formatter for a []BuildpackDependency.

func (DependenciesFormatter) String

func (d DependenciesFormatter) String() string

type DependencyCache

type DependencyCache struct {

	// CachePath is the location where the buildpack has cached its dependencies.
	CachePath string

	// DownloadPath is the location of all downloads during this execution of the build.
	DownloadPath string

	// Logger is the logger used to write to the console.
	Logger bard.Logger

	// UserAgent is the User-Agent string to use with requests.
	UserAgent string

	// Mappings optionally provides URIs mapping for BuildpackDependencies
	Mappings map[string]string
}

DependencyCache allows a user to get an artifact either from a buildpack's cache, a previous download, or to download directly.

func NewDependencyCache

func NewDependencyCache(context libcnb.BuildContext) (DependencyCache, error)

NewDependencyCache creates a new instance setting the default cache path (<BUILDPACK_PATH>/dependencies) and user agent (<BUILDPACK_ID>/<BUILDPACK_VERSION>). Mappings will be read from any libcnb.Binding in the context with type "dependency-mappings"

func (*DependencyCache) Artifact

func (d *DependencyCache) Artifact(dependency BuildpackDependency, mods ...RequestModifierFunc) (*os.File, error)

Artifact returns the path to the artifact. Resolution of that path follows three tiers:

1. CachePath 2. DownloadPath 3. Download from URI

If the BuildpackDependency's SHA256 is not set, the download can never be verified to be up to date and will always download, skipping all the caches.

type DependencyLayerContributor

type DependencyLayerContributor struct {

	// Dependency is the dependency being contributed.
	Dependency BuildpackDependency

	// DependencyCache is the cache to use to get the dependency.
	DependencyCache DependencyCache

	// ExpectedTypes indicates the types that should be set on the layer.
	ExpectedTypes libcnb.LayerTypes

	// ExpectedMetadata contains metadata describing the expected layer
	ExpectedMetadata interface{}

	// Logger is the logger to use.
	Logger bard.Logger

	// RequestModifierFuncs is an optional Request Modifier to use when downloading the dependency.
	RequestModifierFuncs []RequestModifierFunc
}

DependencyLayerContributor is a helper for implementing a libcnb.LayerContributor for a BuildpackDependency in order to get consistent logging and avoidance.

func NewDependencyLayer

func NewDependencyLayer(dependency BuildpackDependency, cache DependencyCache, types libcnb.LayerTypes) (DependencyLayerContributor, libcnb.BOMEntry)

NewDependencyLayer returns a new DependencyLayerContributor for the given BuildpackDependency and a BOMEntry describing the layer contents.

func (*DependencyLayerContributor) Contribute

func (d *DependencyLayerContributor) Contribute(layer libcnb.Layer, f DependencyLayerFunc) (libcnb.Layer, error)

Contribute is the function to call whe implementing your libcnb.LayerContributor.

func (*DependencyLayerContributor) LayerName

func (d *DependencyLayerContributor) LayerName() string

LayerName returns the conventional name of the layer for this contributor

func (*DependencyLayerContributor) Name

func (d *DependencyLayerContributor) Name() string

Name returns the human readable name of the layer

type DependencyLayerFunc

type DependencyLayerFunc func(artifact *os.File) (libcnb.Layer, error)

DependencyLayerFunc is a callback function that is invoked when a dependency needs to be contributed.

type DependencyResolver

type DependencyResolver struct {

	// Dependencies are the dependencies to resolve against.
	Dependencies []BuildpackDependency

	// StackID is the stack id of the build.
	StackID string
}

DependencyResolver provides functionality for resolving a dependency given a collection of constraints.

func NewDependencyResolver

func NewDependencyResolver(context libcnb.BuildContext) (DependencyResolver, error)

NewDependencyResolver creates a new instance from the buildpack metadata and stack id.

func (*DependencyResolver) Resolve

func (d *DependencyResolver) Resolve(id string, version string) (BuildpackDependency, error)

Resolve returns the latest version of a dependency within the collection of Dependencies. The candidate set is first filtered by the constraints, then the remaining candidates are sorted for the latest result by semver semantics. Version can contain wildcards and defaults to "*" if not specified.

type HelperLayerContributor

type HelperLayerContributor struct {

	// Path is the path to the helper application.
	Path string

	// BuildpackInfo describes the buildpack that provides the helper
	BuildpackInfo libcnb.BuildpackInfo

	// Logger is the logger to use.
	Logger bard.Logger

	// Names are the names of the helpers to create
	Names []string
}

HelperLayerContributor is a helper for implementing a libcnb.LayerContributor for a buildpack helper application in order to get consistent logging and avoidance.

func NewHelperLayer

func NewHelperLayer(buildpack libcnb.Buildpack, names ...string) (HelperLayerContributor, libcnb.BOMEntry)

NewHelperLayer returns a new HelperLayerContributor and a BOMEntry describing the layer contents.

func (HelperLayerContributor) Contribute

func (h HelperLayerContributor) Contribute(layer libcnb.Layer) (libcnb.Layer, error)

Contribute is the function to call whe implementing your libcnb.LayerContributor.

func (HelperLayerContributor) Name

func (h HelperLayerContributor) Name() string

Name returns the conventional name of the layer for this contributor

type LayerContributor

type LayerContributor struct {

	// ExpectedMetadata is the metadata to compare against any existing layer metadata.
	ExpectedMetadata interface{}

	// Logger is the logger to use.
	Logger bard.Logger

	// Name is the user readable name of the contribution.
	Name string

	// ExpectedTypes indicates the types that should be set on the layer.
	ExpectedTypes libcnb.LayerTypes
}

LayerContributor is a helper for implementing a libcnb.LayerContributor in order to get consistent logging and avoidance.

func NewLayerContributor

func NewLayerContributor(name string, expectedMetadata interface{}, expectedTypes libcnb.LayerTypes) LayerContributor

NewLayerContributor creates a new instance.

func (*LayerContributor) Contribute

func (l *LayerContributor) Contribute(layer libcnb.Layer, f LayerFunc) (libcnb.Layer, error)

Contribute is the function to call when implementing your libcnb.LayerContributor.

type LayerFunc

type LayerFunc func() (libcnb.Layer, error)

LayerFunc is a callback function that is invoked when a layer needs to be contributed.

type MergeFunc

type MergeFunc func(a, b libcnb.BuildpackPlanEntry) (libcnb.BuildpackPlanEntry, error)

MergeFunc takes two BuildpackPlanEntry's and returns a merged entry.

type NoValidDependenciesError

type NoValidDependenciesError struct {
	// Message is the error message
	Message string
}

NoValidDependenciesError is returned when the resolver cannot find any valid dependencies given the constraints.

func (NoValidDependenciesError) Error

func (n NoValidDependenciesError) Error() string

type PlanEntryResolver

type PlanEntryResolver struct {

	// Plan is the BuildpackPlan to resolve against.
	Plan libcnb.BuildpackPlan
}

PlanEntryResolver provides functionality for resolving a Buildpack Plan Entry given a name.

func (*PlanEntryResolver) Resolve

func (p *PlanEntryResolver) Resolve(name string) (libcnb.BuildpackPlanEntry, bool, error)

Resolve calls ResolveWithMerge function passing in the ShallowMerge function as the merge strategy.

func (*PlanEntryResolver) ResolveWithMerge

func (p *PlanEntryResolver) ResolveWithMerge(name string, f MergeFunc) (libcnb.BuildpackPlanEntry, bool, error)

ResolveWithMerge returns a single BuildpackPlanEntry that is a merged version of all entries that have a given name. A merge function is used to describe how two entries are merged together.

type RequestModifierFunc

type RequestModifierFunc func(request *http.Request) (*http.Request, error)

RequestModifierFunc is a callback that enables modification of a download request before it is sent. It is often used to set Authorization headers.