persistence

Documentation

Overview

Package persistence specifies how the framework interacts with a persistence backend.

It defines the interfaces Persister and Restorer that define how channel data is persisted to and restored from a persistence backend.

Index

• type Channel
  • func CloneSource(s Source) *Channel
• type ChannelIterator
• type Persister
• type Restorer
• type Source
• type StateMachine
  • func FromStateMachine(m *channel.StateMachine, pr Persister) StateMachine
  • func (m StateMachine) AddSig(ctx context.Context, idx channel.Index, sig wallet.Sig) error
  • func (m StateMachine) EnableFinal(ctx context.Context) error
  • func (m StateMachine) EnableInit(ctx context.Context) error
  • func (m StateMachine) EnableUpdate(ctx context.Context) error
  • func (m *StateMachine) Init(ctx context.Context, initBals channel.Allocation, initData channel.Data) error
  • func (m StateMachine) SetFunded(ctx context.Context) error
  • func (m StateMachine) SetRegistered(ctx context.Context, reg *channel.RegisteredEvent) error
  • func (m StateMachine) SetRegistering(ctx context.Context) error
  • func (m StateMachine) SetWithdrawing(ctx context.Context) error
  • func (m StateMachine) SetWithdrawn(ctx context.Context) error
  • func (m StateMachine) Sig(ctx context.Context) (sig wallet.Sig, err error)
  • func (m StateMachine) Update(ctx context.Context, stagingState *channel.State, actor channel.Index) error

Types

type Channel

type Channel struct {
	// Peers are the channel network peers of this channel. They must have the
	// same ordering as the Params.Peers, omitting the own peer.
	Peers     []peer.Address
	Idx       channel.Index       // Idx is the own index in the channel.
	Params    *channel.Params     // Params are the channel parameters.
	StagingTX channel.Transaction // StagingTx is the staging transaction.
	CurrentTX channel.Transaction // CurrentTX is the current transaction.
	Phase     channel.Phase       // Phase is the current channel phase.
}

A Channel holds all data that is necessary for restoring a channel controller.

func CloneSource

func CloneSource(s Source) *Channel

CloneSource creates a new Channel object whose fields are clones of the data coming from Source s.

type ChannelIterator

type ChannelIterator interface {
	// Next should restore the next persisted channel. If no channel was found,
	// or the context times out, it should return false.
	Next(context.Context) bool

	// Channel should return the latest channel data that was restored via Next.
	// It is guaranteed by the framework to only be called after Next returned
	// true.
	Channel() *Channel

	// Close is called by the framework when Next returned false, or when
	// prematurely aborting. If an error occurred during the last Next call,
	// this error should be returned. Otherwise, nil should be returned if the
	// iterator was exhausted or closed prematurely by this Close call. This
	// call should free up all resources used by the iterator.
	io.Closer
}

A ChannelIterator is an iterator over Channels, i.e., channel data that is necessary for restoring a channel machine. It needs to be implemented by a persistence backend to allow the framework to restore channels.

type Persister

type Persister interface {
	// ChannelCreated is called by the client when a new channel is created,
	// before funding it. This should fully persist all of the source's data.
	// The current state will be the fully signed version 0 state. The staging
	// state will be empty. The passed peers are the channel network peers,
	// which should also be persisted.
	ChannelCreated(ctx context.Context, source Source, peers []peer.Address) error

	// ChannelRemoved is called by the client when a channel is removed because
	// it has been successfully settled and its data is no longer needed. All
	// data associated with this channel may be discarded.
	ChannelRemoved(ctx context.Context, id channel.ID) error

	// Staged is called when a new valid state got set as the new staging
	// state. It may already contain one valid signature, either by a remote
	// peer or us locally. Hence, this only needs to persist a channel's staged
	// state, all its currently known signatures and the phase.
	Staged(context.Context, Source) error

	// SigAdded is called when a new signature is added to the current staging
	// state. Only the signature for the given index needs to be persisted.
	SigAdded(context.Context, Source, channel.Index) error

	// Enabled is called when the current state is updated to the staging state.
	// The old current state may be discarded. The current state and phase
	// should be persisted.
	Enabled(context.Context, Source) error

	// PhaseChanged is called when a phase change occurred that did not change
	// the current or staging transaction. Only the phase needs to be persisted.
	PhaseChanged(context.Context, Source) error

	// Close is called by the client when it shuts down. No more persistence
	// requests will be made after this call and the Persister should free up
	// all possible resources.
	io.Closer
}

A Persister is used by the framework to persist channel data during different steps of a channel's lifetime. It is guaranteed by the framework that, per channel, only one of those methods is called concurrently. However, for different channels, several calls may be made concurrently and independently.

var NonPersister Persister = nonPersister{}

NonPersister is a Persister that doesn't to anything. All its methods return nil.

type Restorer

type Restorer interface {
	// RestoreAll should return an iterator over all persisted channels.
	RestoreAll() (ChannelIterator, error)

	// RestorePeer should return an iterator over all persisted channels which
	// the given peer is a part of.
	RestorePeer(peer.Address) (ChannelIterator, error)
}

A Restorer allows a Client to restore channel machines. It has methods that return iterators over channel data.

type Source

type Source interface {
	ID() channel.ID                 // ID is the channel ID of this source. It is the same as Params().ID().
	Idx() channel.Index             // Idx is the own index in the channel.
	Params() *channel.Params        // Params are the channel parameters.
	StagingTX() channel.Transaction // StagingTX is the staged transaction (State+incomplete list of sigs).
	CurrentTX() channel.Transaction // CurrentTX is the current transaction (State+complete list of sigs).
	Phase() channel.Phase           // Phase is the phase in which the channel is currently in.
}

Source is a source of channel data. It allows access to all information needed for persistence. The ID, Idx and Params only need to be persisted once per channel as they stay constant during a channel's lifetime.

type StateMachine

type StateMachine struct {
	*channel.StateMachine
	// contains filtered or unexported fields
}

A StateMachine is a wrapper around a channel.StateMachine that forwards calls to it and, if successful, persists changed data using a Persister.

func FromStateMachine

func FromStateMachine(m *channel.StateMachine, pr Persister) StateMachine

FromStateMachine creates a persisting StateMachine wrapper around the passed StateMachine using the Persister pr.

func (StateMachine) AddSig

func (m StateMachine) AddSig(ctx context.Context, idx channel.Index, sig wallet.Sig) error

AddSig calls AddSig on the channel.StateMachine and then persists the added signature.

func (StateMachine) EnableFinal

func (m StateMachine) EnableFinal(ctx context.Context) error

EnableFinal calls EnableFinal on the channel.StateMachine and then persists the enabled transaction.

func (StateMachine) EnableInit

func (m StateMachine) EnableInit(ctx context.Context) error

EnableInit calls EnableInit on the channel.StateMachine and then persists the enabled transaction.

func (StateMachine) EnableUpdate

func (m StateMachine) EnableUpdate(ctx context.Context) error

EnableUpdate calls EnableUpdate on the channel.StateMachine and then persists the enabled transaction.

func (*StateMachine) Init

func (m *StateMachine) Init(ctx context.Context, initBals channel.Allocation, initData channel.Data) error

Init calls Init on the channel.StateMachine and then persists the changed staging state.

func (StateMachine) SetFunded

func (m StateMachine) SetFunded(ctx context.Context) error

SetFunded calls SetFunded on the channel.StateMachine and then persists the changed phase.

func (StateMachine) SetRegistered

func (m StateMachine) SetRegistered(ctx context.Context, reg *channel.RegisteredEvent) error

SetRegistered calls SetRegistered on the channel.StateMachine and then persists the changed phase.

func (StateMachine) SetRegistering

func (m StateMachine) SetRegistering(ctx context.Context) error

SetRegistering calls SetRegistering on the channel.StateMachine and then persists the changed phase.

func (StateMachine) SetWithdrawing

func (m StateMachine) SetWithdrawing(ctx context.Context) error

SetWithdrawing calls SetWithdrawing on the channel.StateMachine and then persists the changed phase.

func (StateMachine) SetWithdrawn

func (m StateMachine) SetWithdrawn(ctx context.Context) error

SetWithdrawn calls SetWithdrawn on the channel.StateMachine and then persists the changed phase.

func (StateMachine) Sig

func (m StateMachine) Sig(ctx context.Context) (sig wallet.Sig, err error)

Sig calls Sig on the channel.StateMachine and then persists the added signature.

func (StateMachine) Update

func (m StateMachine) Update(
	ctx context.Context,
	stagingState *channel.State,
	actor channel.Index,
) error

Update calls Update on the channel.StateMachine and then persists the changed staging state.