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/v2/cargo"
	"github.com/paketo-buildpacks/packit/v2/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 Checksum
• type Dependency
• type ErrNoDeps
  • func (e *ErrNoDeps) Error() string
• type MappingResolver
• type MirrorResolver
• 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) Resolve(path, id, version, stack string) (Dependency, error)
  • func (s Service) WithDependencyMappingResolver(mappingResolver MappingResolver) Service
  • func (s Service) WithDependencyMirrorResolver(mirrorResolver MirrorResolver) Service
• type Transport

Types

type Checksum

type Checksum = cargo.Checksum

type Dependency

type Dependency struct {
	// CPE is the Common Platform Enumerator for the dependency. Used in legacy
	// image label SBOM (GenerateBillOfMaterials).
	//
	// Deprecated: use CPEs instead.
	CPE string `toml:"cpe"`

	// CPEs are the Common Platform Enumerators for the dependency. Used in Syft
	// and SPDX JSON SBOMs. If unset, falls back to CPE.
	CPEs []string `toml:"cpes"`

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

	// Checksum is a string that includes an algorithm and the hex-encoded hash
	// of the built dependency separated by a colon. Example
	// sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
	Checksum string `toml:"checksum"`

	// 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.
	//
	// Deprecated: use Checksum instead.
	SHA256 string `toml:"sha256"`

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

	// SourceChecksum is a string that includes an algorithm and the hex-encoded
	// hash of the source representation of the dependency separated by a colon.
	// Example sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
	SourceChecksum string `toml:"source-checksum"`

	// SourceSHA256 is the hex-encoded SHA256 checksum of the source-code
	// representation of the dependency.
	//
	// Deprecated: use SourceChecksum instead.
	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 ErrNoDeps

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

ErrNoDeps is a typed error indicating that no dependencies were resolved during Service.Resolve()

errors can be tested against this type with: errors.As()

func (*ErrNoDeps) Error

func (e *ErrNoDeps) Error() string

Error implements the error.Error interface

type MappingResolver

type MappingResolver interface {
	FindDependencyMapping(checksum, platformDir string) (string, error)
}

MappingResolver serves as the interface that looks up platform binding provided dependency mappings given a SHA256

type MirrorResolver

type MirrorResolver interface {
	FindDependencyMirror(uri, platformDir string) (string, error)
}

MirrorResolver serves as the interface that looks for a dependency mirror via environment variable or binding

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 Service 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. If there is a dependency mirror for the specified dependency, Deliver will use the mirror URI to fetch the dependency. If both a dependency mapping and mirror are BOTH present, the mapping will take precedence over the mirror.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.

Deprecated: use sbom.GenerateFromDependency 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

func (Service) WithDependencyMirrorResolver

func (s Service) WithDependencyMirrorResolver(mirrorResolver MirrorResolver) 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.