transferhandler

Documentation

Overview

Package transferhandler provides the API for transfer handlers used during the transfer process of an OCM component. There is a common generic transfer functionality in package transfer, which can be used to transfer component versions from one OCM repository to another one. To flexible enough for various use cases this generic handling uses extension points to control the concrete transfer behaviour. These extension points can be implemented by dedicated transfer handlers to influence the transfer process.

For example:

• In a dedicated scenario only components from a dedicated provider should not be transferred per value in a transfer operation.
• Another scenario could require to replace dedicated access methods.

Such specific logic is hard to formalize, but nevertheless the basic transfer flow is always the same. Therefore, it makes no sense to reimplement the flow just because some inner process steps or decisions should look slightly different. Because of this transfer handlers are introduces, which allow to separate such decisions and step implementations form the generic flow and to provided scenario specific implementations with reimplementing the complete transitive transfer handling.

For common use cases two standard handlers are provided, which can be used to formally describe typical transfer scenarios:

• package ocm.software/ocm/api/ocm/tools/transfer/transferhandler/standard provides a standard behaviour configurable by some common options, like transport-by-value.
• package ocm.software/ocm/api/ocm/tools/transfer/transferhandler/spiff provides a handler configurable by a spiff script.

Transfer handlers may accept transfer options to be configured. For operations not taking a transferhandler but only transfer options, the given options are used to find the best matching transfer handling accepting those options. Therefore, standard transfer handles can be registered. Besides this any user defined transfer handler may be used by using operation flavors directly accepting a transfer handler.

Index

• Constants
• func ApplyOptions(set TransferOptions, opts ...TransferOption) error
• func From(ctx config.ContextProvider, opts TransferOptions) error
• func RegisterHandler(prio int, creator TransferOptionsCreator)
• type SpecializedOptionsCreator
  • func (o SpecializedOptionsCreator[P, T]) NewOptions() TransferHandlerOptions
• type TransferHandler
• type TransferHandlerOptions
• type TransferOption
• type TransferOptions
• type TransferOptionsCreator
  • func OrderedTransferOptionCreators() []TransferOptionsCreator

Constants

const KIND_TRANSFEROPTION = "transfer option"

Functions

func ApplyOptions

func ApplyOptions(set TransferOptions, opts ...TransferOption) error

func From

func From(ctx config.ContextProvider, opts TransferOptions) error

func RegisterHandler

func RegisterHandler(prio int, creator TransferOptionsCreator)

RegisterHandler registers handler specific option set types for option based handler detection. Every transfer options provides a method used to create an initial handler option set it is originally defined for. This way, in a first step, by evaluating all given options the detection process tries to find an option set applicable to consume all given options. The set then is responsible to provide an appropriately configured handler.

Option set handlers are used if none of the given options provides an option set applicable to accept all given handler related options. In a second step all such handlers ordered by their priority are used to create an option set. If it matches all given options, it is used to finally create the transfer handler.

Self-contained handlers should use priority 1000. Handlers extending option sets from other handlers should use priority 100. Handlers supporting the union of incompatible option sets should use lower priority according to the order they should be checked.

Types

type SpecializedOptionsCreator

type SpecializedOptionsCreator[P optionsPointer[T], T any] struct{}

SpecializedOptionsCreator is the base implementation for options objects for specialized transfer handlers.

func (SpecializedOptionsCreator[P, T]) NewOptions

func (o SpecializedOptionsCreator[P, T]) NewOptions() TransferHandlerOptions

type TransferHandler

type TransferHandler interface {
	// UpdateVersion decides whether an update of volatile (non-signature relevant) parts of a CV should be updated.
	UpdateVersion(src ocm.ComponentVersionAccess, tgt ocm.ComponentVersionAccess) (bool, error)
	// EnforceTransport decides whether a component version should be transport as it is.
	// This controls whether transport is carried out
	// as if the component version were not present at the destination.
	EnforceTransport(src ocm.ComponentVersionAccess, tgt ocm.ComponentVersionAccess) (bool, error)
	// OverwriteVersion decides whether a modification of non-volatile (signature relevant) parts of a CV should be updated.
	OverwriteVersion(src ocm.ComponentVersionAccess, tgt ocm.ComponentVersionAccess) (bool, error)

	// TransferVersion decides on continuing with a component version (reference).
	TransferVersion(repo ocm.Repository, src ocm.ComponentVersionAccess, meta *compdesc.Reference, tgt ocm.Repository) (ocm.ComponentVersionAccess, TransferHandler, error)
	// TransferResource decides on the value transport of a resource.
	TransferResource(src ocm.ComponentVersionAccess, a ocm.AccessSpec, r ocm.ResourceAccess) (bool, error)
	// TransferSource decides on the value transport of a source.
	TransferSource(src ocm.ComponentVersionAccess, a ocm.AccessSpec, r ocm.SourceAccess) (bool, error)

	// HandleTransferResource technically transfers a resource.
	HandleTransferResource(r ocm.ResourceAccess, m cpi.AccessMethod, hint string, t ocm.ComponentVersionAccess) error
	// HandleTransferSource technically transfers a source.
	HandleTransferSource(r ocm.SourceAccess, m cpi.AccessMethod, hint string, t ocm.ComponentVersionAccess) error
}

TransferHandler controls the transfer of component versions. It can be used to control the value transport of sources and resources on artifact level (by providing specific handling for dedicated artifact attributes), the concrete re/source transfer step, and the way how nested component version are transported. There are two implementations delivered as part of the OCM library:

• package transferhandler.standard: able to select recursive transfer general value artifact transport.
• package transferhandler.spiff: controls transfer using a spiff script.

type TransferHandlerOptions

type TransferHandlerOptions interface {
	TransferOptions
	NewTransferHandler() (TransferHandler, error)
}

TransferHandlerOptions is the general type for a dedicated kind of option set holding options for a dedicated type of transfer handler. Different transfer handler implementations may use different concrete option sets. To support option sets with an overlapping set of accepted options, it is not possible to use fixed structs with explicit fields for every option as target for the apply methods of the option objects. Therefore, every option uses its own option type interfaces. The option's setters/getters MUST be interfaces, which may be implemented by different option set types to enable the option implementations to work with different options sets.

For example the spiff transfer handler options include all the standard handler options.

type TransferOption

type TransferOption interface {
	ApplyTransferOption(TransferOptions) error
}

TransferOption is an option used to configure the transfer process. This interface is used by transfer operations for the optional list of given options. Every option decides on its own, whether it is applicable to the given target, which is given by the generic TransferOptions interface. There are two kinds of options:

• handler specific options additionally implement the TransferOptionsCreator interface.
• operation related option do not implement this interface.

type TransferOptions

type TransferOptions interface{}

TransferOptions is the general interface used by TransferOption implementations as target to apply themselves to.

type TransferOptionsCreator

type TransferOptionsCreator interface {
	NewOptions() TransferHandlerOptions
}

TransferOptionsCreator is an optional interface for a TransferOption. The option may provide a default TransferOptions object if it applies to regular transfer handler options. THis is used to infer an applicable transfer hander for the gicven option set. Options not intended for the transfer handler MUST NOT implement this interface to not hamper the handler detection process.

func OrderedTransferOptionCreators

func OrderedTransferOptionCreators() []TransferOptionsCreator