dsl

Documentation

Index

• func EmitEvent(m Module, ev *eventpb.Event)
• func EmitMirEvent(m Module, ev *eventpbtypes.Event)
• func HashOneMessage[C any](m Module, destModule t.ModuleID, data [][]byte, context *C)
• func HashRequest[C any](m Module, destModule t.ModuleID, data [][][]byte, context *C)
• func MirOrigin(contextID ContextID) *dslpbtypes.Origin
• func Origin(contextID ContextID) *dslpb.Origin
• func SendMessage(m Module, destModule t.ModuleID, msg *messagepb.Message, dest []t.NodeID)
• func SignRequest[C any](m Module, destModule t.ModuleID, data [][]byte, context *C)
• func UponCondition(m Module, handler func() error)
• func UponEvent[EvWrapper eventpb.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)
• func UponHashResult[C any](m Module, handler func(hashes [][]byte, context *C) error)
• func UponInit(m Module, handler func() error)
• func UponMessageReceived(m Module, handler func(from t.NodeID, msg *messagepb.Message) error)
• func UponMirEvent[EvWrapper eventpbtypes.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)
• func UponNewRequests(m Module, handler func(requests []*requestpb.Request) error)
• func UponNodeSigsVerified[C any](m Module, ...)
• func UponOneHashResult[C any](m Module, handler func(hash []byte, context *C) error)
• func UponOneNodeSigVerified[C any](m Module, handler func(nodeID t.NodeID, err error, context *C) error)
• func UponOtherEvent(m Module, handler func(ev *eventpb.Event) error)
• func UponSignResult[C any](m Module, handler func(signature []byte, context *C) error)
• func VerifyNodeSigs[C any](m Module, destModule t.ModuleID, data [][][]byte, signatures [][]byte, ...)
• func VerifyOneNodeSig[C any](m Module, destModule t.ModuleID, data [][]byte, signature []byte, ...)
• type ContextID
• type Handle
  • func (h Handle) CleanupContext(id ContextID)
  • func (h Handle) RecoverAndCleanupContext(id ContextID) any
  • func (h Handle) RecoverAndRetainContext(id cs.ItemID) any
  • func (h Handle) StoreContext(context any) ContextID
• type Module
  • func NewModule(moduleID t.ModuleID) Module

Functions

func EmitEvent

func EmitEvent(m Module, ev *eventpb.Event)

EmitEvent adds the event to the queue of output events NB: This function works with the (legacy) protoc-generated types and is likely to be removed in the future, with EmitMirEvent taking its place.

func EmitMirEvent

func EmitMirEvent(m Module, ev *eventpbtypes.Event)

EmitMirEvent adds the event to the queue of output events NB: this function works with the Mir-generated types. For the (legacy) protoc-generated types, EmitEvent can be used.

func HashOneMessage

func HashOneMessage[C any](m Module, destModule t.ModuleID, data [][]byte, context *C)

HashOneMessage emits a request event to compute hash one message. This is a wrapper around HashRequest. May be useful in combination with UponOneHashResult.

func HashRequest

func HashRequest[C any](m Module, destModule t.ModuleID, data [][][]byte, context *C)

HashRequest emits a request event to compute hashes of a batch of messages. The response should be processed using UponHashResult with the same context type C. C can be an arbitrary type and does not have to be serializable.

func MirOrigin

func MirOrigin(contextID ContextID) *dslpbtypes.Origin

MirOrigin creates a dslpb.Origin protobuf.

func Origin

func Origin(contextID ContextID) *dslpb.Origin

Origin creates a dslpb.Origin protobuf.

func SendMessage

func SendMessage(m Module, destModule t.ModuleID, msg *messagepb.Message, dest []t.NodeID)

SendMessage emits a request event to send a message over the network. The message should be processed on the receiving end using UponMessageReceived.

func SignRequest

func SignRequest[C any](m Module, destModule t.ModuleID, data [][]byte, context *C)

SignRequest emits a request event to sign the given message. The response should be processed using UponSignResult with the same context type C. C can be an arbitrary type and does not have to be serializable.

NB: The context is passed by reference in order to prevent the programmer from making a bug where they pass the context by value when they send a request, but accept it by reference in the handler (or vice versa). This would make the handler not match the response event.

func UponCondition

func UponCondition(m Module, handler func() error)

UponCondition registers a special type of handler that will be invoked each time after processing a batch of events. The handler is assumed to represent a conditional action: it is supposed to check some predicate on the state and perform actions if the predicate is satisfied.

func UponEvent

func UponEvent[EvWrapper eventpb.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)

UponEvent registers an event handler for module m. This event handler will be called every time an event of type EvWrapper is received. NB: This function works with the (legacy) protoc-generated types and is likely to be removed in the future, with UponMirEvent taking its place.

func UponHashResult

func UponHashResult[C any](m Module, handler func(hashes [][]byte, context *C) error)

UponHashResult invokes handler when the module receives a response to a request made by HashRequest with the same context type C.

func UponInit

func UponInit(m Module, handler func() error)

UponInit invokes handler when the module is initialized.

func UponMessageReceived

func UponMessageReceived(m Module, handler func(from t.NodeID, msg *messagepb.Message) error)

UponMessageReceived invokes handler when the module receives a message over the network.

func UponMirEvent

func UponMirEvent[EvWrapper eventpbtypes.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)

UponMirEvent registers an event handler for module m. This event handler will be called every time an event of type EvWrapper is received. NB: this function works with the Mir-generated types. For the (legacy) protoc-generated types, UponEvent can be used.

func UponNewRequests

func UponNewRequests(m Module, handler func(requests []*requestpb.Request) error)

UponNewRequests invokes handler when the module receives a NewRequests event.

func UponNodeSigsVerified

func UponNodeSigsVerified[C any](
	m Module,
	handler func(nodeIDs []t.NodeID, errs []error, allOK bool, context *C) error,
)

UponNodeSigsVerified invokes handler when the module receives a response to a request made by VerifyNodeSigs with the same context type C.

func UponOneHashResult

func UponOneHashResult[C any](m Module, handler func(hash []byte, context *C) error)

UponOneHashResult is a wrapper around UponHashResult that invokes handler on each response in a batch separately. May be useful in combination with HashOneMessage.

func UponOneNodeSigVerified

func UponOneNodeSigVerified[C any](m Module, handler func(nodeID t.NodeID, err error, context *C) error)

UponOneNodeSigVerified is a wrapper around UponNodeSigsVerified that invokes handler on each response in a batch separately. May be useful in combination with VerifyOneNodeSig.

func UponOtherEvent

func UponOtherEvent(m Module, handler func(ev *eventpb.Event) error)

func UponSignResult

func UponSignResult[C any](m Module, handler func(signature []byte, context *C) error)

UponSignResult invokes handler when the module receives a response to a request made by SignRequest with the same context type C.

func VerifyNodeSigs

func VerifyNodeSigs[C any](
	m Module,
	destModule t.ModuleID,
	data [][][]byte,
	signatures [][]byte,
	nodeIDs []t.NodeID,
	context *C,
)

VerifyNodeSigs emits a signature verification request event for a batch of signatures. The response should be processed using UponNodeSigsVerified with the same context type C. C can be an arbitrary type and does not have to be serializable.

func VerifyOneNodeSig

func VerifyOneNodeSig[C any](
	m Module,
	destModule t.ModuleID,
	data [][]byte,
	signature []byte,
	nodeID t.NodeID,
	context *C,
)

VerifyOneNodeSig emits a signature verification request event for one signature. This is a wrapper around VerifyNodeSigs. May be useful in combination with UponOneNodeSigVerified.

Types

type ContextID

type ContextID = cs.ItemID

ContextID is used to address the internal context store of the dsl module.

type Handle

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

Handle is used to manage internal state of the dsl module.

func (Handle) CleanupContext

func (h Handle) CleanupContext(id ContextID)

CleanupContext schedules a disposal of context with the given id after the current batch of events is processed. NB: the context cannot be disposed of immediately because there may be more event handlers for this event that may need this context.

func (Handle) RecoverAndCleanupContext

func (h Handle) RecoverAndCleanupContext(id ContextID) any

RecoverAndCleanupContext recovers the context with te given id and schedules a disposal of this context after the current batch of events is processed. NB: the context cannot be disposed of immediately because there may be more event handlers for this event that may need this context.

func (Handle) RecoverAndRetainContext

func (h Handle) RecoverAndRetainContext(id cs.ItemID) any

RecoverAndRetainContext recovers the context with the given id and retains it in the internal context store so that it can be recovered again later. Only use this function when expecting to receive multiple events with the same context. In case of a typical request-response semantic, use RecoverAndCleanupContext.

func (Handle) StoreContext

func (h Handle) StoreContext(context any) ContextID

StoreContext stores the given data and returns an automatically deterministically generated unique id. The data can be later recovered or disposed of using this id.

type Module

type Module interface {
	modules.PassiveModule

	// DslHandle is used to manage internal state of the dsl module.
	DslHandle() Handle

	// ModuleID returns the identifier of the module.
	// TODO: consider moving this method to modules.Module.
	ModuleID() t.ModuleID
}

Module allows creating passive modules in a very natural declarative way.

func NewModule

func NewModule(moduleID t.ModuleID) Module

NewModule creates a new dsl module with a given id.