postal

Documentation

Overview

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

Below is an example that show the resolution and installation of a "node" dependency:

package main

import (
	"log"

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

func main() {
	// Here we construct a transport and service so that we can download or fetch
	// dependencies from a cache and install them into a layer.
	transport := cargo.NewTransport()
	service := postal.NewService(transport)

	// The Resolve method can be used to pick a dependency that best matches a
	// set of criteria including id, version constraint, and stack.
	dependency, err := service.Resolve("/cnbs/com.example.nodejs-cnb/buildpack.toml", "node", "10.*", "com.example.stacks.bionic")
	if err != nil {
		log.Fatal(err)
	}

	// The Install method will download or fetch the given dependency and ensure
	// it is expanded into the given layer path as well as validated against its
	// SHA256 checksum.
	err = service.Install(dependency, "/cnbs/com.example.nodejs-cnb", "/layers/com.example.nodejs-cnb/node")
	if err != nil {
		log.Fatal(err)
	}
}

Index

• type Dependency
• type MappingResolver
• type Service
  • func NewService(transport Transport) Service
  • func (s Service) Deliver(dependency Dependency, cnbPath, layerPath, platformPath string) error
  • func (s Service) GenerateBillOfMaterials(dependencies ...Dependency) []packit.BOMEntry
  • func (s Service) Install(dependency Dependency, cnbPath, layerPath string) error
  • func (s Service) Resolve(path, id, version, stack string) (Dependency, error)
  • func (s Service) WithDependencyMappingResolver(mappingResolver MappingResolver) Service
• type Transport

Types

type Dependency

type Dependency struct {
	// CPE is the Common Platform Enumerator for the dependency.
	CPE string `toml:"cpe"`

	// DeprecationDate is the data upon which this dependency is considered deprecated.
	DeprecationDate time.Time `toml:"deprecation_date"`

	// ID is the identifier used to specify the dependency.
	ID string `toml:"id"`

	// Licenses is a list of SPDX license identifiers of licenses in the dependency.
	Licenses []string `toml:"licenses"`

	// Name is the human-readable name of the dependency.
	Name string `toml:"name"`

	// PURL is the package URL for the dependency.
	PURL string `toml:"purl"`

	// SHA256 is the hex-encoded SHA256 checksum of the built dependency.
	SHA256 string `toml:"sha256"`

	// Source is the uri location of the source-code representation of the dependency.
	Source string `toml:"source"`

	// SourceSHA256 is the hex-encoded SHA256 checksum of the source-code representation of the dependency.
	SourceSHA256 string `toml:"source_sha256"`

	// Stacks is a list of stacks for which the dependency is built.
	Stacks []string `toml:"stacks"`

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

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

	// StripComponents behaves like the --strip-components flag on tar command
	// removing the first n levels from the final decompression destination.
	StripComponents int `toml:"strip-components"`
}

Dependency is a representation of a buildpack dependency.

type MappingResolver

type MappingResolver interface {
	FindDependencyMapping(SHA256, bindingPath string) (string, error)
}

MappingResolver serves as the interface that looks up platform binding provided dependency mappings given a SHA256 and a path to search for bindings

type Service

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

Service provides a mechanism for resolving and installing dependencies given a Transport.

func NewService

func NewService(transport Transport) Service

NewService creates an instance of a Servicel given a Transport.

func (Service) Deliver

func (s Service) Deliver(dependency Dependency, cnbPath, layerPath, platformPath string) error

Deliver will fetch and expand a dependency into a layer path location. The location of the CNBPath is given so that dependencies that may be included in a buildpack when packaged for offline consumption can be retrieved. If there is a dependency mapping for the specified dependency, Deliver will use the given dependency mapping URI to fetch the dependency. The dependency is validated against the checksum value provided on the Dependency and will error if there are inconsistencies in the fetched result.

func (Service) GenerateBillOfMaterials

func (s Service) GenerateBillOfMaterials(dependencies ...Dependency) []packit.BOMEntry

GenerateBillOfMaterials will generate a list of BOMEntry values given a collection of Dependency values.

func (Service) Install

func (s Service) Install(dependency Dependency, cnbPath, layerPath string) error

Install will invoke Deliver with a hardcoded value of /platform for the platform path.

Deprecated: Use Deliver instead.

func (Service) Resolve

func (s Service) Resolve(path, id, version, stack string) (Dependency, error)

Resolve will pick the best matching dependency given a path to a buildpack.toml file, and the id, version, and stack value of a dependency. The version value is treated as a SemVer constraint and will pick the version that matches that constraint best. If the version is given as "default", the default version for the dependency with the given id will be used. If there is no default version for that dependency, a wildcard constraint will be used.

func (Service) WithDependencyMappingResolver

func (s Service) WithDependencyMappingResolver(mappingResolver MappingResolver) Service

type Transport

type Transport interface {
	Drop(root, uri string) (io.ReadCloser, error)
}

Transport serves as the interface for types that can fetch dependencies given a location uri using either the http:// or file:// scheme.