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

• func CloneSource(s channel.Source) channel.Source
• type Channel
  • func FromSource(s channel.Source, ps []wire.Address, parent *channel.ID) *Channel
  • func NewChannel() *Channel
  • func (c *Channel) CurrentTX() channel.Transaction
  • func (c *Channel) ID() channel.ID
  • func (c *Channel) Idx() channel.Index
  • func (c *Channel) Params() *channel.Params
  • func (c *Channel) Phase() channel.Phase
  • func (c *Channel) StagingTX() channel.Transaction
• type ChannelIterator
• type PersistRestorer
• type Persister
• type Restorer
• 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) DiscardUpdate(ctx context.Context) 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) ForceUpdate(ctx context.Context, stagingState *channel.State, actor channel.Index) 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) SetProgressed(ctx context.Context, e *channel.ProgressedEvent) error
  • func (m StateMachine) SetProgressing(ctx context.Context, s *channel.State) error
  • func (m StateMachine) SetRegistered(ctx context.Context) 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

Functions

func CloneSource

func CloneSource(s channel.Source) channel.Source

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

Types

type Channel

type Channel struct {
	PeersV []wire.Address
	Parent *channel.ID
	// contains filtered or unexported fields
}

Channel holds all data that is necessary to restore a channel controller and additionally the related peers for this channel. If the channel is a sub-channel, also holds the parent channel's ID.

func FromSource

func FromSource(s channel.Source, ps []wire.Address, parent *channel.ID) *Channel

FromSource creates a new Channel object from given `channel.Source`, the channel's network peers, and the parent channel ID, if it exists.

func NewChannel

func NewChannel() *Channel

NewChannel creates a new Channel object whose fields are initialized. The peers and parent field are unset.

func (*Channel) CurrentTX

func (c *Channel) CurrentTX() channel.Transaction

CurrentTX is the current transaction (State+complete list of sigs).

func (*Channel) ID

func (c *Channel) ID() channel.ID

ID is the channel ID of this source. It is the same as Params().ID().

func (*Channel) Idx

func (c *Channel) Idx() channel.Index

Idx is the own index in the channel.

func (*Channel) Params

func (c *Channel) Params() *channel.Params

Params are the channel parameters.

func (*Channel) Phase

func (c *Channel) Phase() channel.Phase

Phase is the phase in which the channel is currently in.

func (*Channel) StagingTX

func (c *Channel) StagingTX() channel.Transaction

StagingTX is the staged transaction (State+incomplete list of sigs).

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 PersistRestorer

type PersistRestorer interface {
	Persister
	Restorer
}

PersistRestorer is a Persister and Restorer on the same data source and data sink.

var NonPersistRestorer PersistRestorer = nonPersistRestorer{}

NonPersistRestorer is a PersistRestorer that doesn't do anything. All Persistence methods return nil and all Restorer methods return an empty iterator.

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. The parent field is the parent
	// channel's ID, or nil, if it is a ledger channel.
	ChannelCreated(ctx context.Context, source channel.Source, peers []wire.Address, parent *channel.ID) 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, channel.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, channel.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, channel.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, channel.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.

type Restorer

type Restorer interface {
	// ActivePeers should return a list of all peers with which any channel is
	// persisted.
	ActivePeers(context.Context) ([]wire.Address, error)

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

	// RestoreChannel should return the channel with the requested ID.
	RestoreChannel(context.Context, channel.ID) (*Channel, error)
}

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

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) DiscardUpdate

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

DiscardUpdate calls DiscardUpdate on the channel.StateMachine and then removes the state machine's staged state from persistence.

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) ForceUpdate

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

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

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) SetProgressed

func (m StateMachine) SetProgressed(ctx context.Context, e *channel.ProgressedEvent) error

SetProgressed calls SetProgressed on the channel.StateMachine and then persists the changed state.

func (StateMachine) SetProgressing

func (m StateMachine) SetProgressing(ctx context.Context, s *channel.State) error

SetProgressing calls SetProgressing on the channel.StateMachine and then persists the changed state.

func (StateMachine) SetRegistered

func (m StateMachine) SetRegistered(ctx context.Context) 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.