packit

package module
v0.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2020 License: Apache-2.0 Imports: 7 Imported by: 22

README

packit

GoDoc

Package packit provides primitives for implementing a Cloud Native Buildpack according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md.

Buildpack Interface

According to the specification, the buildpack interface is composed of both a detect and build phase. Each of these phases has a corresponding set of packit primitives enable developers to easily implement a buildpack.

Detect Phase

The purpose of the detect phase is for buildpacks to declare dependencies that are provided or required for the buildpack to execute. Implementing the detect phase can be achieved by calling the Detect function and providing a DetectFunc callback to be invoked during that phase. Below is an example of a simple detect phase that provides the "yarn" dependency and requires the "node" dependency.

package main

import (
	"encoding/json"
	"os"
	"path/filepath"

	"github.com/paketo-buildpacks/packit"
)

func main() {
	// The detect phase provides yarn and requires node. When requiring node,
	// a version specified in the package.json file is included to indicate
	// what versions of node are acceptable to the buildpack.

	packit.Detect(func(context packit.DetectContext) (packit.DetectResult, error) {

		// The DetectContext includes a WorkingDir field that specifies the
		// location of the application source code. This field can be combined with
		// other paths to find and inspect files included in the application source
		// code that is provided to the buildpack.
		file, err := os.Open(filepath.Join(context.WorkingDir, "package.json"))
		if err != nil {
			return packit.DetectResult{}, err
		}

		// The package.json file includes a declaration of what versions of node
		// are acceptable. For example:
		//   {
		//     "engines": {
		//       "node": ">=0.10.3 <0.12"
		//     }
		//   }
		var config struct {
			Engines struct {
				Node string `json:"node"`
			} `json:"engines"`
		}

		err = json.NewDecoder(file).Decode(&config)
		if err != nil {
			return packit.DetectResult{}, err
		}

		// Once the package.json file has been parsed, the detect phase can return
		// a result that indicates the provision of yarn and the requirement of
		// node. As can be seen below, the BuildPlanRequirement may also include
		// optional metadata information to such as the source of the version
		// information for a given requirement.
		return packit.DetectResult{
			Plan: packit.BuildPlan{
				Provides: []packit.BuildPlanProvision{
					{Name: "yarn"},
				},
				Requires: []packit.BuildPlanRequirement{
					{
						Name:    "node",
						Version: config.Engines.Node,
						Metadata: map[string]string{
							"version-source": "package.json",
						},
					},
				},
			},
		}, nil
	})
}

Build Phase

The purpose of the build phase is to perform the operation of providing whatever dependencies were declared in the detect phase for the given application code. Implementing the build phase can be achieved by calling the Build function and providing a BuildFunc callback to be invoked during that phase. Below is an example that adds "yarn" as a dependency to the application source code.

package main

import (
	"github.com/paketo-buildpacks/packit"
)

func main() {
	// The build phase includes the yarn cli in a new layer that is made
	// available for subsequent buildpacks during their build phase as well as to
	// the start command during launch.

	packit.Build(func(context packit.BuildContext) (packit.BuildResult, error) {

		// The BuildContext includes a BuildpackPlan with entries that specify a
		// requirement on a dependency provided by the buildpack. This example
		// simply chooses the first entry, but more intelligent resolution
		// processes can and likely shoud be used in real implementations.
		entry := context.Plan.Entries[0]

		// The BuildContext also provides a mechanism whereby a layer can be
		// created to store the results of a given portion of the build process.
		// This example creates a layer called "yarn" that will hold the yarn cli.
		layer, err := context.Layers.Get("yarn", packit.BuildLayer, packit.LaunchLayer)
		if err != nil {
			return packit.BuildResult{}, err
		}

		// At this point we are performing the process of installing the yarn cli.
		// As those details are not important to the explanation of the packit API,
		// they are omitted here.
		err = InstallYarn(entry.Version, layer.Path)
		if err != nil {
			return packit.BuildResult{}, err
		}

		// After the installation of the yarn cli, a BuildResult can be returned
		// that included details of the executed BuildpackPlan, the Layers to
		// provide back to the lifecycle, and the Processes to execute at launch.
		return packit.BuildResult{
			Layers: []packit.Layer{
				layer,
			},
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: "yarn start",
				},
			},
		}, nil
	})
}

// InstallYarn executes the process of installing the yarn cli.
func InstallYarn(version, path string) error {
	// Implemention omitted.
	return nil
}

Summary

These examples show the very basics of what a buildpack implementation using packit might entail. For more details, please consult the documentation of the types and functions declared herein.

Sub Packages

  • cargo

  • fakes

  • fs: Package fs provides a set of filesystem helpers that can be useful when developing Cloud Native Buildpacks.

  • matchers

  • pexec: Package pexec provides a mechanism for invoking a program executable with a varying set of arguments.

  • postal: Package postal provides a service for resolving and installing dependencies for a buildpack.

  • scribe

  • vacation

Readme created from Go doc with goreadme

Documentation

Overview 

	build := func(context packit.BuildContext) (packit.BuildResult, error) {
		return packit.BuildResult{
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: `while true; do nc -l -p $PORT -c 'echo -e "HTTP/1.1 200 OK\n\n Hello, world!\n"'; done`,
				},
			},
		}, nil
	}

	packit.Run(detect, build)
}

Summary

These examples show the very basics of what a buildpack implementation using packit might entail. For more details, please consult the documentation of the types and functions declared herein.

Index

Constants

This section is empty.

Variables

View Source 
var Fail = internal.Fail

Fail is a sentinal value that can be used to indicate a failure to detect during the detect phase. Fail implements the Error interface and should be returned as the error value in the DetectFunc signature.

Functions

func Build 

func Build(f BuildFunc, options ...Option)

Build is an implementation of the build phase according to the Cloud Native Buildpacks specification. Calling this function with a BuildFunc will perform the build phase process.

func Detect 

func Detect(f DetectFunc, options ...Option)

Detect is an implementation of the detect phase according to the Cloud Native Buildpacks specification. Calling this function with a DetectFunc will perform the detect phase process.

func Run added in v0.0.10 

func Run(detect DetectFunc, build BuildFunc, options ...Option)

Run combines the invocation of both build and detect into a single entry point. Calling Run from an executable with a name matching "build" or "detect" will result in the matching DetectFunc or BuildFunc being called.

Types

type BuildContext 

type BuildContext struct {
	// BuildpackInfo includes the details of the buildpack parsed from the
	// buildpack.toml included in the buildpack contents.
	BuildpackInfo BuildpackInfo

	// CNBPath is the absolute path location of the buildpack contents.
	// This path is useful for finding the buildpack.toml or any other
	// files included in the buildpack.
	CNBPath string

	// Layers provides access to layers managed by the buildpack. It can be used
	// to create new layers or retrieve cached layers from previous builds.
	Layers Layers

	// Plan includes the BuildpackPlan provided by the lifecycle as specified in
	// the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#buildpack-plan-toml.
	Plan BuildpackPlan

	// Stack is the value of the chosen stack. This value is populated from the
	// $CNB_STACK_ID environment variable.
	Stack string

	// WorkingDir is the location of the application source code as provided by
	// the lifecycle.
	WorkingDir string
}

BuildContext provides the contextual details that are made available by the buildpack lifecycle during the build phase. This context is populated by the Build function and passed to BuildFunc during execution.

type BuildFunc 

type BuildFunc func(BuildContext) (BuildResult, error)

BuildFunc is the definition of a callback that can be invoked when the Build function is executed. Buildpack authors should implement a BuildFunc that performs the specific build phase operations for a buildpack.

type BuildPlan 

type BuildPlan struct {
	// Provides is a list of BuildPlanProvisions that are provided by this
	// buildpack.
	Provides []BuildPlanProvision `toml:"provides"`

	// Requires is a list of BuildPlanRequirements that are required by this
	// buildpack.
	Requires []BuildPlanRequirement `toml:"requires"`

	// Or is a list of additional BuildPlans that may be selected by the
	// lifecycle
	Or []BuildPlan `toml:"or,omitempty"`
}

BuildPlan is a representation of the Build Plan as specified in the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml. The BuildPlan allows buildpacks to indicate what dependencies they provide or require.

type BuildPlanProvision 

type BuildPlanProvision struct {
	// Name is the identifier whereby buildpacks can coordinate that a dependency
	// is provided or required.
	Name string `toml:"name"`
}

BuildPlanProvision is a representation of a dependency that can be provided by a buildpack.

type BuildPlanRequirement 

type BuildPlanRequirement struct {
	// Name is the identifier whereby buildpacks can coordinate that a dependency
	// is provided or required.
	Name string `toml:"name"`

	// Version allows a requirement to include a constraint describing what
	// versions of the dependency are considered acceptable.
	Version string `toml:"version"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about their requirement. Examples of this type of metadata might
	// include details about what source was used to decide the Version
	// constraint for a requirement.
	Metadata interface{} `toml:"metadata"`
}

type BuildResult 

type BuildResult struct {
	// Plan is the set of refinements to the Buildpack Plan that were performed
	// during the build phase.
	Plan BuildpackPlan

	// Layers is a list of layers that will be persisted by the lifecycle at the
	// end of the build phase. Layers not included in this list will not be made
	// available to the lifecycle.
	Layers []Layer

	// Processes is a list of processes that will be returned to the lifecycle to
	// be executed during the launch phase.
	Processes []Process
}

BuildResult allows buildpack authors to indicate the result of the build phase for a given buildpack. This result, returned in a BuildFunc callback, will be parsed and persisted by the Build function and returned to the lifecycle at the end of the build phase execution.

type BuildpackInfo 

type BuildpackInfo struct {
	// ID is the identifier specified in the `buildpack.id` field of the buildpack.toml.
	ID string `toml:"id"`

	// Name is the identifier specified in the `buildpack.name` field of the buildpack.toml.
	Name string `toml:"name"`

	// Version is the identifier specified in the `buildpack.version` field of the buildpack.toml.
	Version string `toml:"version"`
}

BuildpackInfo is a representation of the basic information for a buildpack provided in its buildpack.toml file as described in the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#buildpacktoml-toml.

type BuildpackPlan 

type BuildpackPlan struct {
	// Entries is a list of BuildpackPlanEntry fields that are declared in the
	// buildpack plan TOML file.
	Entries []BuildpackPlanEntry `toml:"entries"`
}

BuildpackPlan is a representation of the buildpack plan provided by the lifecycle and defined in the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#buildpack-plan-toml. It is also used to return a set of refinements to the plan at the end of the build phase.

type BuildpackPlanEntry 

type BuildpackPlanEntry struct {
	// Name is the name of the dependency the the buildpack should provide.
	Name string `toml:"name"`

	// Version if the version contraint that defines what would be an acceptable
	// dependency provided by the buildpack.
	Version string `toml:"version"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about their requirement. Examples of this type of metadata might
	// include details about what source was used to decide the Version
	// constraint for a requirement.
	Metadata map[string]interface{} `toml:"metadata"`
}

BuildpackPlanEntry is a representation of a single buildpack plan entry specified by the lifecycle.

type DetectContext 

type DetectContext struct {
	// WorkingDir is the location of the application source code as provided by
	// the lifecycle.
	WorkingDir string

	// CNBPath is the absolute path location of the buildpack contents.
	// This path is useful for finding the buildpack.toml or any other
	// files included in the buildpack.
	CNBPath string

	// BuildpackInfo includes the details of the buildpack parsed from the
	// buildpack.toml included in the buildpack contents.
	BuildpackInfo BuildpackInfo
}

DetectContext provides the contextual details that are made available by the buildpack lifecycle during the detect phase. This context is populated by the Detect function and passed to the DetectFunc during execution.

type DetectFunc 

type DetectFunc func(DetectContext) (DetectResult, error)

DetectFunc is the definition of a callback that can be invoked when the Detect function is executed. Buildpack authors should implement a DetectFunc that performs the specific detect phase operations for a buildpack.

type DetectResult 

type DetectResult struct {
	// Plan is the set of Build Plan provisions and requirements that are
	// detected during the detect phase of the lifecycle.
	Plan BuildPlan
}

DetectResult allows buildpack authors to indicate the result of the detect phase for a given buildpack. This result, returned in a DetectFunc callback, will be parsed and persisted by the Detect function and returned to the lifecycle at the end of the detect phase execution.

type Environment 

type Environment map[string]string

Environment provides a key-value store for declaring environment variables.

func (Environment) Append 

func (e Environment) Append(name, value, delim string)

Append adds a key-value pair to the environment as an appended value according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#append.

func (Environment) Default 

func (e Environment) Default(name, value string)

Default adds a key-value pair to the environment as a default value according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#default.

func (Environment) Override 

func (e Environment) Override(name, value string)

Override adds a key-value pair to the environment as an overridden value according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#override.

func (Environment) Prepend 

func (e Environment) Prepend(name, value, delim string)

Prepend adds a key-value pair to the environment as a prepended value according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#prepend.

type EnvironmentWriter 

type EnvironmentWriter interface {
	Write(dir string, env map[string]string) error
}

EnvironmentWriter serves as the interface for types that can write an Environment to a directory on disk according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#provided-by-the-buildpacks.

type ExitHandler 

type ExitHandler interface {
	Error(error)
}

ExitHandler serves as the interface for types that can handle an error during the Detect or Build functions. ExitHandlers are responsible for translating error values into exit codes according the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#detection and https://github.com/buildpacks/spec/blob/master/buildpack.md#build.

type Layer 

type Layer struct {
	// Path is the absolute location of the layer on disk.
	Path string `toml:"-"`

	// Name is the descriptive name of the layer.
	Name string `toml:"-"`

	// Build indicates whether the layer is available to subsequent buildpacks
	// during their build phase according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#build-layers.
	Build bool `toml:"build"`

	// Launch indicates whether the layer is exported into the application image
	// and made available during the launch phase according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#launch-layers.
	Launch bool `toml:"launch"`

	// Cache indicates whether the layer is persisted and made available to
	// subsequent builds of the same application according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#launch-layers
	// and
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#build-layers.
	Cache bool `toml:"cache"`

	// SharedEnv is the set of environment variables attached to the layer and
	// made available during both the build and launch phases according to the
	// specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#provided-by-the-buildpacks.
	SharedEnv Environment `toml:"-"`

	// BuildEnv is the set of environment variables attached to the layer and
	// made available during the build phase according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#provided-by-the-buildpacks.
	BuildEnv Environment `toml:"-"`

	// LaunchEnv is the set of environment variables attached to the layer and
	// made available during the launch phase according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#provided-by-the-buildpacks.
	LaunchEnv Environment `toml:"-"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about the layer. Examples of this type of metadata might include
	// details about what versions of software are included in the layer such
	// that subsequent builds can inspect that metadata and choose to reuse the
	// layer if suitable. The Metadata field ultimately fills the metadata field
	// of the Layer Content Metadata TOML file according to the specification:
	// https://github.com/buildpacks/spec/blob/master/buildpack.md#layer-content-metadata-toml.
	Metadata map[string]interface{} `toml:"metadata"`
}

Layer provides a representation of a layer managed by a buildpack as described by the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#layers.

func (*Layer) Reset 

func (l *Layer) Reset() error

Reset clears the state of a layer such that the layer can be replaced with new content and metadata. It clears all environment variables, and removes the content of the layer directory on disk.

type LayerType 

type LayerType uint8

LayerType defines the set of layer types that can be declared according to the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#layer-types. 

const (
	// BuildLayer indicates that the layer will be made available during the
	// build phase.
	BuildLayer LayerType = iota

	// LaunchLayer indicates that the layer will be made available during the
	// launch phase.
	LaunchLayer

	// CacheLayer indicates that the layer will be cached and made available to
	// the buildpack on subsequent rebuilds.
	CacheLayer
)

type Layers 

type Layers struct {
	// Path is the absolute location of the set of layers managed by a buildpack
	// on disk.
	Path string
}

Layers represents the set of layers managed by a buildpack.

func (Layers) Get 

func (l Layers) Get(name string, layerTypes ...LayerType) (Layer, error)

Get will either create a new layer with the given name and layer types. If a layer already exists on disk, then the layer metadata will be retrieved from disk and returned instead.

type Option 

type Option func(config OptionConfig) OptionConfig

Option declares a function signature that can be used to define optional modifications to the behavior of the Detect and Build functions.

func WithArgs 

func WithArgs(args []string) Option

WithArgs is an Option that overrides the value of os.Args for a given invocation of Build or Detect.

func WithExitHandler 

func WithExitHandler(exitHandler ExitHandler) Option

WithExitHandler is an Option that overrides the ExitHandler for a given invocation of Build or Detect.

type OptionConfig 

type OptionConfig struct {
	// contains filtered or unexported fields
}

OptionConfig is the set of configurable options for the Build and Detect functions.

type Process 

type Process struct {
	// Type is an identifier to describe the type of process to be executed, eg.
	// "web".
	Type string `toml:"type"`

	// Command is the start command to be executed at launch.
	Command string `toml:"command"`

	// Args is a list of arguments to be passed to the command at launch.
	Args []string `toml:"args"`

	// Direct indicates whether the process should bypass the shell when invoked.
	Direct bool `toml:"direct"`
}

Process represents a process to be run during the launch phase as described in the specification: https://github.com/buildpacks/spec/blob/master/buildpack.md#launch. The fields of the process are describe in the specification of the launch.toml file: https://github.com/buildpacks/spec/blob/master/buildpack.md#launchtoml-toml.

type TOMLWriter 

type TOMLWriter interface {
	Write(path string, value interface{}) error
}

TOMLWriter serves as the interface for types that can handle the writing of TOML files. TOMLWriters take a path to a file location on disk and a datastructure to marshal.

Source Files

View all Source files

Directories

Path Synopsis
fakes
jam
jam/commands
jam/commands/fakes
jam/internal
some-executable
Package fs provides a set of filesystem helpers that can be useful when developing Cloud Native Buildpacks.
 Package fs provides a set of filesystem helpers that can be useful when developing Cloud Native Buildpacks.
Package pexec provides a mechanism for invoking a program executable with a varying set of arguments.
 Package pexec provides a mechanism for invoking a program executable with a varying set of arguments.
Package postal provides a service for resolving and installing dependencies for a buildpack.
 Package postal provides a service for resolving and installing dependencies for a buildpack.
fakes

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.