changeset

package
v0.85.0 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultHookTimeout = 30 * time.Second

DefaultHookTimeout is applied when a HookDefinition has a zero Timeout.

Variables

This section is empty.

Functions

func ExecuteHook added in v0.84.0 

func ExecuteHook(
	env fdeployment.Environment,
	def HookDefinition,
	fn func(ctx context.Context) error,
) error

ExecuteHook runs a hook function with the configured timeout and failure policy. The parent context is derived from env.GetContext(); each hook receives a child context with its timeout applied.

Returns nil when the hook succeeds or when the hook fails but the FailurePolicy is Warn. Returns the hook error only when the policy is Abort.

Types

type BaseRegistryProvider added in v0.37.0 

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

BaseRegistryProvider is a base implementation of a RegistryProvider that provides a ChangesetsRegistry.

func NewBaseRegistryProvider added in v0.37.0 

func NewBaseRegistryProvider() *BaseRegistryProvider

NewBaseRegistryProvider is an implementation of a RegistryProvider that provides a struct that can be embedded in domain-specific registry providers.

func (*BaseRegistryProvider) Archive added in v0.37.0 

func (p *BaseRegistryProvider) Archive()

Archive is an empty implementation of archiving changesets in the registry.

This should be overridden by the domain-specific registry provider.

func (*BaseRegistryProvider) Init added in v0.37.0 

func (p *BaseRegistryProvider) Init() error

Init is an empty implementation of adding changesets to the registry.

This should be overridden by the domain-specific registry provider.

func (*BaseRegistryProvider) Registry added in v0.37.0 

func (p *BaseRegistryProvider) Registry() *ChangesetsRegistry

Registry returns the ChangesetsRegistry.

type ChangeSet 

type ChangeSet internalChangeSet

type ChangeSetImpl 

type ChangeSetImpl[C any] struct {

	// Present only when the changeset was wired with
	// Configure(...).WithConfigResolver(...)
	ConfigResolver fresolvers.ConfigResolver
	// contains filtered or unexported fields
}

func (ChangeSetImpl[C]) Apply 

func (ccs ChangeSetImpl[C]) Apply(env fdeployment.Environment) (fdeployment.ChangesetOutput, error)

func (ChangeSetImpl[C]) Configurations 

func (ccs ChangeSetImpl[C]) Configurations() (Configurations, error)

func (ChangeSetImpl[C]) ThenWith 

func (ccs ChangeSetImpl[C]) ThenWith(postProcessor PostProcessor) PostProcessingChangeSet

ThenWith adds post-processing to a configured changeset. Hooks registered before ThenWith are carried forward.

func (ChangeSetImpl[C]) WithPostHooks added in v0.84.0 

func (ccs ChangeSetImpl[C]) WithPostHooks(hooks ...PostHook) ConfiguredChangeSet

WithPostHooks appends post-hooks to this changeset. Multiple calls are additive.

func (ChangeSetImpl[C]) WithPreHooks added in v0.84.0 

func (ccs ChangeSetImpl[C]) WithPreHooks(hooks ...PreHook) ConfiguredChangeSet

WithPreHooks appends pre-hooks to this changeset. Multiple calls are additive.

type ChangesetConfig added in v0.37.0 

type ChangesetConfig struct {
	ChainsToLoad      []uint64 // nil = load all chains, empty = load no chains, populated = load specific chains
	WithoutJD         bool
	OperationRegistry *foperations.OperationRegistry
}

ChangesetConfig holds configuration options for a changeset

type ChangesetOption added in v0.37.0 

type ChangesetOption func(*ChangesetConfig)

ChangesetOption defines an option for configuring a changeset

func OnlyLoadChainsFor added in v0.37.0 

func OnlyLoadChainsFor(chainselectors ...uint64) ChangesetOption

OnlyLoadChainsFor will configure the environment to load only the specified chains. By default, if this option is not specified, all chains are loaded. If user provide empty or nil value, eg OnlyLoadChainsFor(), no chains will be loaded.

func WithOperationRegistry added in v0.37.0 

func WithOperationRegistry(registry *foperations.OperationRegistry) ChangesetOption

WithOperationRegistry will configure the changeset to use the specified operation registry.

func WithoutJD added in v0.37.0 

func WithoutJD() ChangesetOption

WithoutJD will configure the environment to not load Job Distributor. By default, if option is not specified, Job Distributor is loaded. This is useful for changesets that do not require Job Distributor to be loaded.

type ChangesetsRegistry added in v0.37.0 

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

ChangesetsRegistry is a registry of changesets that can be applied to a domain environment.

func NewChangesetsRegistry added in v0.37.0 

func NewChangesetsRegistry() *ChangesetsRegistry

NewChangesetsRegistry creates a new ChangesetsRegistry.

func (*ChangesetsRegistry) Add added in v0.37.0 

func (r *ChangesetsRegistry) Add(key string, cs ChangeSet, opts ...ChangesetOption)

Add adds a changeset to the registry. Options can be passed to configure the changeset. - OnlyLoadChainsFor: will configure the environment to load only the specified chains. - WithoutJD: will configure the environment to not load Job Distributor. - WithOperationRegistry: will configure the changeset to use the specified operation registry.

func (*ChangesetsRegistry) AddGlobalPostHooks added in v0.84.0 

func (r *ChangesetsRegistry) AddGlobalPostHooks(hooks ...PostHook)

AddGlobalPostHooks appends post-hooks that run after every changeset in this registry.

func (*ChangesetsRegistry) AddGlobalPreHooks added in v0.84.0 

func (r *ChangesetsRegistry) AddGlobalPreHooks(hooks ...PreHook)

AddGlobalPreHooks appends pre-hooks that run before every changeset in this registry.

func (*ChangesetsRegistry) Apply added in v0.37.0 

func (r *ChangesetsRegistry) Apply(
	key string, e fdeployment.Environment,
) (fdeployment.ChangesetOutput, error)

Apply applies a changeset, running any registered hooks around it.

Execution order:

  1. Global pre-hooks (in order added)
  2. Per-changeset pre-hooks (in order specified)
  3. entry.changeset.Apply(env)
  4. Per-changeset post-hooks
  5. Global post-hooks

If Apply failed, that error is always returned. Post-hook failures after a failed Apply are logged but never mask the Apply error.

func (*ChangesetsRegistry) Archive added in v0.37.0 

func (r *ChangesetsRegistry) Archive(key string, gitSHA string)

Archive buries a changeset in the registry.

func (*ChangesetsRegistry) GetChangesetOptions added in v0.37.0 

func (r *ChangesetsRegistry) GetChangesetOptions(key string) (ChangesetConfig, error)

GetChangesetOptions retrieves the configuration options for a changeset.

func (*ChangesetsRegistry) GetConfigurations added in v0.37.0 

func (r *ChangesetsRegistry) GetConfigurations(key string) (Configurations, error)

GetConfigurations retrieves the configurations for a changeset.

func (*ChangesetsRegistry) LatestKey added in v0.37.0 

func (r *ChangesetsRegistry) LatestKey() (string, error)

LatestKey returns the most recent changeset key.

func (*ChangesetsRegistry) ListKeys added in v0.37.0 

func (r *ChangesetsRegistry) ListKeys() []string

ListKeys returns a copy of all registered changeset keys.

func (*ChangesetsRegistry) SetValidate added in v0.37.0 

func (r *ChangesetsRegistry) SetValidate(validate bool)

SetValidate sets the validate flag for the registry. If set to true, changeset keys will be validated.

type Configurations 

type Configurations struct {
	InputChainOverrides []uint64

	// Present only when the changeset was wired with
	// Configure(...).WithConfigResolver(...)
	ConfigResolver fresolvers.ConfigResolver

	// InputType contains the reflect.Type of the input struct for this changeset
	// This is useful for tools that need to generate templates or analyze the expected input
	InputType reflect.Type
}

Configurations holds options for a configured changeset

type ConfiguredChangeSet 

type ConfiguredChangeSet interface {
	ChangeSet
	ThenWith(postProcessor PostProcessor) PostProcessingChangeSet
	WithPreHooks(hooks ...PreHook) ConfiguredChangeSet
	WithPostHooks(hooks ...PostHook) ConfiguredChangeSet
}

type EnvInputOption 

type EnvInputOption[C any] func(options *envInputOptions[C])

EnvInputOption is a function that configures WithEnvInput.

func InputModifierFunc 

func InputModifierFunc[C any](modifier func(c C) (C, error)) EnvInputOption[C]

InputModifierFunc allows providing a custom function to update the input. The return value of the modifier function is used as the final input for the changeset.

type FailurePolicy added in v0.84.0 

type FailurePolicy int

FailurePolicy determines how a hook error affects the pipeline. 

const (
	// Abort causes a hook error to fail the pipeline.
	Abort FailurePolicy = iota
	// Warn causes a hook error to be logged while the pipeline continues.
	Warn
)

func (FailurePolicy) String added in v0.84.0 

func (fp FailurePolicy) String() string

String returns the string representation of a FailurePolicy.

type HookDefinition added in v0.84.0 

type HookDefinition struct {
	Name          string
	FailurePolicy FailurePolicy
	Timeout       time.Duration // zero means DefaultHookTimeout (30s)
}

HookDefinition holds the metadata common to all hooks.

type HookEnv added in v0.84.0 

type HookEnv struct {
	Name   string
	Logger logger.Logger
}

HookEnv is the restricted environment surface exposed to hooks. Additional fields may be added in future versions as needs arise.

type PostHook added in v0.84.0 

type PostHook struct {
	HookDefinition
	Func PostHookFunc
}

PostHook pairs a HookDefinition with a PostHookFunc.

type PostHookFunc added in v0.84.0 

type PostHookFunc func(ctx context.Context, params PostHookParams) error

PostHookFunc is the signature for functions that run after changeset Apply. The context is derived from env.GetContext() with the hook's timeout applied.

type PostHookParams added in v0.84.0 

type PostHookParams struct {
	Env          HookEnv
	ChangesetKey string
	Config       any
	Output       fdeployment.ChangesetOutput
	Err          error
}

PostHookParams is passed to post-hooks. All fields must be treated as read-only.

type PostProcessingChangeSet 

type PostProcessingChangeSet interface {
	WithPreHooks(hooks ...PreHook) PostProcessingChangeSet
	WithPostHooks(hooks ...PostHook) PostProcessingChangeSet
	// contains filtered or unexported methods
}

type PostProcessingChangeSetImpl 

type PostProcessingChangeSetImpl[C any] struct {
	// contains filtered or unexported fields
}

func (PostProcessingChangeSetImpl[C]) Apply 

func (ccs PostProcessingChangeSetImpl[C]) Apply(env fdeployment.Environment) (fdeployment.ChangesetOutput, error)

func (PostProcessingChangeSetImpl[C]) Configurations 

func (ccs PostProcessingChangeSetImpl[C]) Configurations() (Configurations, error)

func (PostProcessingChangeSetImpl[C]) WithPostHooks added in v0.84.0 

func (ccs PostProcessingChangeSetImpl[C]) WithPostHooks(hooks ...PostHook) PostProcessingChangeSet

WithPostHooks appends post-hooks to this changeset. Multiple calls are additive.

func (PostProcessingChangeSetImpl[C]) WithPreHooks added in v0.84.0 

func (ccs PostProcessingChangeSetImpl[C]) WithPreHooks(hooks ...PreHook) PostProcessingChangeSet

WithPreHooks appends pre-hooks to this changeset. Multiple calls are additive.

type PostProcessor 

type PostProcessor func(e fdeployment.Environment, config fdeployment.ChangesetOutput) (fdeployment.ChangesetOutput, error)

type PreHook added in v0.84.0 

type PreHook struct {
	HookDefinition
	Func PreHookFunc
}

PreHook pairs a HookDefinition with a PreHookFunc.

type PreHookFunc added in v0.84.0 

type PreHookFunc func(ctx context.Context, params PreHookParams) error

PreHookFunc is the signature for functions that run before changeset Apply. The context is derived from env.GetContext() with the hook's timeout applied.

type PreHookParams added in v0.84.0 

type PreHookParams struct {
	Env          HookEnv
	ChangesetKey string
	Config       any
}

PreHookParams is passed to pre-hooks. All fields must be treated as read-only.

type RegistryProvider added in v0.37.0 

type RegistryProvider interface {
	// Init initializes the changeset registry by adding changesets specific to the domain
	// environment using the `Add` method on the ChangesetsRegistry.
	Init() error

	// Archive archives a changeset in the registry. This is intended for changesets that have
	// already been applied and are retained only for historical purposes.
	Archive()

	// Registry retrieves the initialized ChangesetsRegistry.
	Registry() *ChangesetsRegistry
}

RegistryProvider defines an interface for initializing and managing the changeset registry for a domain environment. It provides methods to initialize the registry, archive changesets, and retrieve the initialized ChangesetsRegistry.

type TypedJSON 

type TypedJSON struct {
	Payload        json.RawMessage `json:"payload"`
	ChainOverrides []uint64        `json:"chainOverrides"` // Optional field for chain overrides
}

inputObject is a JSON object with a "payload" field that contains the actual input data for a Durable Pipeline.

type WrappedChangeSet 

type WrappedChangeSet[C any] struct {
	// contains filtered or unexported fields
}

WrappedChangeSet simply wraps a fdeployment.ChangeSetV2 to use it in the fluent interface, which hosts the "With" function, so you can write `ConfigureLegacy(myChangeSet).With(aConfig)` in a typesafe way, and pass that into the ChangeSets.Add() function.

func Configure 

func Configure[C any](operation fdeployment.ChangeSetV2[C]) WrappedChangeSet[C]

Configure begins a chain of functions that pairs a fdeployment.ChangeSetV2 to a config, for registration as a changeset.

func ConfigureLegacy deprecated 

func ConfigureLegacy[C any](operation fdeployment.ChangeSet[C]) WrappedChangeSet[C]

ConfigureLegacy begins a chain of functions that pairs a legacy (pure function) fdeployment.ChangeSet to a config, for registration as a changeset.

Deprecated: This wraps the deprecated fdeployment.ChangeSet. Should use fdeployment.ChangeSetV2

func (WrappedChangeSet[C]) With 

func (f WrappedChangeSet[C]) With(config C) ConfiguredChangeSet

With returns a fully configured changeset, which pairs a fdeployment.ChangeSet with its configuration. It also allows extensions, such as a PostProcessing function.

func (WrappedChangeSet[C]) WithConfigFrom 

func (f WrappedChangeSet[C]) WithConfigFrom(configProvider func() (C, error)) ConfiguredChangeSet

WithConfigFrom takes a provider function which returns a config or an error, and stores the error (if any) in the configured changeset. This is then used to abort execution with a cleaner message than a panic. This allows for more robust error handling to happen for complex configs, factored into a function, without needing to use the "mustGetConfig" pattern

func (WrappedChangeSet[C]) WithConfigResolver 

func (f WrappedChangeSet[C]) WithConfigResolver(resolver fresolvers.ConfigResolver) ConfiguredChangeSet

WithConfigResolver uses a registered config resolver to generate the configuration. It reads input from the DURABLE_PIPELINE_INPUT environment variable (JSON format) and uses the specified resolver to generate the typed configuration.

func (WrappedChangeSet[C]) WithEnvInput 

func (f WrappedChangeSet[C]) WithEnvInput(opts ...EnvInputOption[C]) ConfiguredChangeSet

WithEnvInput returns a fully configured changeset, which pairs a fdeployment.ChangeSet with its configuration based on the input defined in durable_pipelines/inputs for durable pipelines. It also allows extensions, such as a PostProcessing function. Options: - InputModifierFunc: allows providing a custom function to update the input.

func (WrappedChangeSet[C]) WithJSON 

func (f WrappedChangeSet[C]) WithJSON(_ C, inputStr string) ConfiguredChangeSet

WithJSON returns a fully configured changeset, which pairs a fdeployment.ChangeSet with its configuration based a JSON input. It also allows extensions, such as a PostProcessing function. InputStr must be a JSON object with a "payload" field that contains the actual input data for a Durable Pipeline. Example: 

{
  "payload": {
    "chainSelector": 123456789,
    "value": 100
  }
}

Note: Prefer WithEnvInput for durable_pipelines.go

Source Files

View all Source files

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.