keyset

Documentation

Overview

Package keyset provides a saga mapping strategy that maps messages to instances by looking up which instance is associated with a key derived from the message.

Index

• func Validate(ks []string) ([]string, error)
• type Mapper
  • func ByField(r Repository, f ...string) *Mapper
  • func (m *Mapper) DeleteMapping(ctx context.Context, sg saga.Saga, tx persistence.Tx, i saga.Instance) error
  • func (m *Mapper) MapMessageToInstance(ctx context.Context, sg saga.Saga, tx persistence.Tx, env ax.Envelope) (saga.InstanceID, bool, error)
  • func (m *Mapper) UpdateMapping(ctx context.Context, sg saga.Saga, tx persistence.Tx, i saga.Instance) error
• type Repository
• type Resolver

Functions

func Validate

func Validate(ks []string) ([]string, error)

Validate returns a copy of ks with duplicate keys removed. It returns an error of any of the keys is the empty string.

Types

type Mapper

type Mapper struct {
	Repository Repository
	Resolver   Resolver
}

Mapper is an implementation of saga.Mapper that maps messages to saga instances using disjoint "key sets".

This is a flexible mapping strategy that allows the saga precise control over which instance to load on a per-message basis.

The saga must implement the keyset.Saga interface to use key set mapping.

func ByField

func ByField(r Repository, f ...string) *Mapper

ByField returns a mapper that maps messages to instances using a set of fields within the message.

IDs for new saga instances are produced by generating a random UUID.

All fields must be strings. If any of the fields are empty, the message is not routed to any instance.

The saga data must contain fields of the same name. If any of the data fields are empty, an empty keyset is produced, which results in a keyset validation error while handling the message.

func (*Mapper) DeleteMapping

func (m *Mapper) DeleteMapping(
	ctx context.Context,
	sg saga.Saga,
	tx persistence.Tx,
	i saga.Instance,
) error

DeleteMapping notifies the mapper that an instance has been completed, allowing it to remove it's mapping information, if necessary.

func (*Mapper) MapMessageToInstance

func (m *Mapper) MapMessageToInstance(
	ctx context.Context,
	sg saga.Saga,
	tx persistence.Tx,
	env ax.Envelope,
) (saga.InstanceID, bool, error)

MapMessageToInstance returns the ID of the saga instance that is the target of the given message.

It returns false if the message should be ignored.

func (*Mapper) UpdateMapping

func (m *Mapper) UpdateMapping(
	ctx context.Context,
	sg saga.Saga,
	tx persistence.Tx,
	i saga.Instance,
) error

UpdateMapping notifies the mapper that an instance has been modified, allowing it to update it's mapping information, if necessary.

type Repository

type Repository interface {
	// FindByKey returns the ID of a saga instance that has a specific key in
	// its key set.
	//
	// pk is the saga's persistence key, mk is the mapping key.
	// ok is false if no saga instance has a key set containing mk.
	FindByKey(
		ctx context.Context,
		tx persistence.Tx,
		pk, mk string,
	) (i saga.InstanceID, ok bool, err error)

	// SaveKeys associates a set of mapping keys with a saga instance.
	//
	// Key sets must be disjoint. That is, no two instances of the same saga
	// may share any keys.
	//
	// pk is the saga's persistence key. ks is the set of mapping keys.
	//
	// SaveKeys() may panic if ks contains duplicate keys.
	SaveKeys(
		ctx context.Context,
		tx persistence.Tx,
		pk string,
		ks []string,
		id saga.InstanceID,
	) error

	// DeleteKeys removes any mapping keys associated with a saga instance.
	//
	// pk is the saga's persistence key.
	DeleteKeys(
		ctx context.Context,
		tx persistence.Tx,
		pk string,
		id saga.InstanceID,
	) error
}

Repository is an interface for storing and querying saga instances "key sets".

type Resolver

type Resolver interface {
	// GenerateInstanceID returns the saga ID to use for a new instance.
	//
	// It is called when a "trigger" message is received and there is no
	// existing saga instance. env contains the "trigger" message.
	GenerateInstanceID(ctx context.Context, env ax.Envelope) (id saga.InstanceID, err error)

	// MappingKeyForMessage returns the key used to locate the saga instance
	// to which the given message is routed, if any.
	//
	// If ok is false the message is ignored; otherwise, the message is routed
	// to the saga instance that contains k in its associated key set.
	//
	// New saga instances are created when no matching instance can be found
	// and the message is declared as a "trigger" by the saga's MessageTypes()
	// method; otherwise, HandleNotFound() is called.
	MappingKeyForMessage(ctx context.Context, env ax.Envelope) (k string, ok bool, err error)

	// MappingKeysForInstance returns the set of mapping keys associated with
	// the given instance.
	//
	// When a message is received, a mapping key is produced by calling
	// MappingKeyForMessage(). The message is routed to the saga instance that
	// contains this key in its key set.
	//
	// Key sets must be disjoint. That is, no two instances of the same saga
	// may share any keys.
	//
	// The key set is rebuilt whenever a message is received. It is persisted
	// alongside the saga instance by the Repository.
	//
	// Extra care must be taken when introducing a new key to the set, as the key
	// set for existing saga instances will not be updated until they next receive
	// a message.
	MappingKeysForInstance(context.Context, saga.Instance) ([]string, error)
}

Resolver is an interface that provides the application-defined logic for mapping a message to its target saga instance.