sda

package
v0.0.0-...-53feb6c Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2016 License: GPL-2.0 Imports: 20 Imported by: 3

Documentation

Overview

Package sda contains all structs and functions of the sda framework. It provides you with all necessary functionality to write either protocols or simulations (using this protocols).

SDA is the Secure Distributed API which offers a simple framework for generating your own distributed systems. It is based on a description of your protocol and offers sending and receiving messages, handling trees and host-lists, and easy deploying to Localhost, Deterlab or a real-system.

SDA is based on the following pieces:

- Local* - offers the user-interface to the API for deploying your protocol locally and for testing - Node / ProtocolInstance - gives an interface to define your protocol - Host - handles all network-connections - lib/network - uses secured connections between hosts

If you just want to use an existing protocol, usually the SDA-part is enough. If you want to create your own protocol, you have to learn how to use the ProtocolInstance.

topology is a general

Index

Constants

View Source 
const (
	AggregateMessages = 1 << iota
)

aggregateMessages (if set) tells to aggregate messages from all children before sending to the (parent) Node https://golang.org/ref/spec#Iota

View Source 
const SimulationFileName = "simulation.bin"

SimulationFileName is the name of the (binary encoded) file containing the simulation config.

Variables

View Source 
var EntityListTypeID = network.RegisterMessageType(EntityList{})

ID of EntityList message as registered in network

View Source 
var ErrProtocolRegistered = errors.New("A ProtocolInstance already has been registered using this TreeNodeInstance!")

ErrProtocolRegistered is when the protocolinstance is already registered to the overlay

View Source 
var ErrWrongTreeNodeInstance = errors.New("TreeNodeInstance associated with this ProtocolInstance is already registered")

ErrWrongTreeNodeInstance is returned when you already binded a TNI with a PI.

View Source 
var GenericConfigID = network.RegisterMessageType(GenericConfig{})

GenericConfigID is the ID used by the network library for sending / receiving GenericCOnfig

View Source 
var NilServiceID = ServiceID(uuid.Nil)

NilServiceID is the empty ServiceID

View Source 
var RequestEntityListMessageID = network.RegisterMessageType(RequestEntityList{})

ID of RequestEntityList message as registered in network

View Source 
var RequestID = network.RegisterMessageType(ClientRequest{})

RequestID is the type that registered by the network library

View Source 
var RequestTreeMessageID = network.RegisterMessageType(RequestTree{})

ID of RequestTree message as registered in network

View Source 
var SDADataMessageID = network.RegisterMessageType(Data{})

SDAData is to be embedded in every message that is made for a ID of SDAData message as registered in network

View Source 
var SendEntityListMessageID = EntityListTypeID

ID of EntityList message as registered in network

View Source 
var SendTreeMessageID = TreeMarshalTypeID

ID of TreeMarshal message as registered in network

View Source 
var ServiceFactory = serviceFactory{
	// contains filtered or unexported fields
}

ServiceFactory is the global service factory to instantiate Services

View Source 
var ServiceMessageID = network.RegisterMessageType(ServiceMessage{})

ServiceMessageID is the ID of the ServiceMessage struct.

View Source 
var TreeMarshalTypeID = network.RegisterMessageType(TreeMarshal{})

ID of TreeMarshal message as registered in network

Functions

func ErrMsg 

func ErrMsg(em *network.Message, err error) error

ErrMsg converts a combined err and status-message to an error. It returns either the error, or the errormsg, if there is one.

func PrivPub 

func PrivPub() (abstract.Secret, abstract.Point)

PrivPub creates a private/public key pair.

func ProtocolExists 

func ProtocolExists(protoID ProtocolID) bool

ProtocolExists returns whether a certain protocol already has been registered

func ProtocolRegister 

func ProtocolRegister(protoID ProtocolID, protocol NewProtocol)

ProtocolRegister takes a protocol and registers it under a given uuid. As this might be called from an 'init'-function, we need to check the initialisation of protocols here and not in our own 'init'.

func ReadTomlConfig 

func ReadTomlConfig(conf interface{}, filename string, dirOpt ...string) error

* Reads any structure from a toml-file * * Takes a filename and an optional directory-name

func RegisterNewService 

func RegisterNewService(name string, fn NewServiceFunc)

RegisterNewService is a wrapper around service factory

func SimulationRegister 

func SimulationRegister(name string, sim simulationCreate)

SimulationRegister is must to be called to register a simulation. Protocol or simulation developers must not forget to call this function with the protocol's name.

func WriteTomlConfig 

func WriteTomlConfig(conf interface{}, filename string, dirOpt ...string)

* Writes any structure to a toml-file * * Takes a filename and an optional directory-name.

Types

type Client 

type Client struct {
	*network.Entity
	ServiceID ServiceID
	sync.Mutex
	// contains filtered or unexported fields
}

Client for a service

func NewClient 

func NewClient(s string) *Client

NewClient returns a random client using the service s

func (*Client) BinaryMarshaler 

func (c *Client) BinaryMarshaler() ([]byte, error)

BinaryMarshaler can be used to store the client in a configuration-file

func (*Client) BinaryUnmarshaler 

func (c *Client) BinaryUnmarshaler(b []byte) error

BinaryUnmarshaler sets the different values from a byte-slice

func (*Client) Send 

func (c *Client) Send(dst *network.Entity, msg network.ProtocolMessage) (*network.Message, error)

NetworkSend opens the connection to 'dst' and sends the message 'req'. The reply is returned, or an error if the timeout of 10 seconds is reached.

type ClientRequest 

type ClientRequest struct {
	// Name of the service to direct this request to
	Service ServiceID
	// Data containing all the information in the request
	Data []byte
}

ClientRequest is a generic packet to represent any kind of request a Service is ready to process. It is simply a JSON packet containing two fields: * Service: a string representing the name of the service for whom the packet is intended for. * Data: contains all the information of the request

func CreateServiceRequest 

func CreateServiceRequest(service string, r interface{}) (*ClientRequest, error)

CreateServiceRequest creates a Request message out of any message that is destined to a Service. XXX For the moment it uses protobuf, as it is already handling abstract.Secret/Public stuff that json can't do. Later we may want to think on how to change that.

type Context 

type Context interface {
	NewTreeNodeInstance(*Tree, *TreeNode) *TreeNodeInstance
	RegisterProtocolInstance(ProtocolInstance) error
	SendRaw(*network.Entity, interface{}) error
	Address() string
	Entity() *network.Entity
}

Context is the interface that is given to an Service

type Data 

type Data struct {
	// Token uniquely identify the protocol instance this msg is made for
	From *Token
	// The TreeNodeId Where the message goes to
	To *Token
	// NOTE: this is taken from network.NetworkMessage
	Entity *network.Entity
	// MsgType of the underlying data
	MsgType network.MessageTypeID
	// The interface to the actual Data
	Msg network.ProtocolMessage
	// The actual data as binary blob
	MsgSlice []byte
	// Config the actual config
	Config GenericConfig
}

Data is to be embedded in every message that is made for a ProtocolInstance

type EntityList 

type EntityList struct {
	Id EntityListID
	// TODO make that a map so search is O(1)
	// List is the List of actual "entities"
	// Be careful if you access it in go-routines (not safe by default)
	List []*network.Entity
	// Aggregate public key
	Aggregate abstract.Point
}

An EntityList is a list of Entity we choose to run some tree on it ( and therefor some protocols)

func NewEntityList 

func NewEntityList(ids []*network.Entity) *EntityList

NewEntityList creates a new Entity from a list of entities. It also adds a UUID which is randomly chosen.

func (*EntityList) GenerateBigNaryTree 

func (el *EntityList) GenerateBigNaryTree(N, nodes int) *Tree

GenerateBigNaryTree creates a tree where each node has N children. It will make a tree with exactly 'nodes' elements, regardless of the size of the EntityList. If 'nodes' is bigger than the number of elements in the EntityList, it will add some or all elements in the EntityList more than once. If the length of the EntityList is equal to 'nodes', it is guaranteed that all Entities from the EntityList will be used in the tree. However, for some configurations it is impossible to use all Entities from the EntityList and still avoid having a parent and a child from the same host. In this case use-all has preference over not-the-same-host.

func (*EntityList) GenerateBinaryTree 

func (el *EntityList) GenerateBinaryTree() *Tree

GenerateBinaryTree creates a binary tree out of the EntityList out of it. The first element of the EntityList will be the root element.

func (*EntityList) GenerateNaryTree 

func (el *EntityList) GenerateNaryTree(N int) *Tree

GenerateNaryTree creates a tree where each node has N children. The first element of the EntityList will be the root element.

func (*EntityList) Get 

func (el *EntityList) Get(idx int) *network.Entity

Get simply returns the entity that is stored at that index in the entitylist returns nil if index error

func (*EntityList) Publics 

func (el *EntityList) Publics() []abstract.Point

Publics returns the public-keys of the underlying EntityList. It won't modify the underlying list.

func (*EntityList) Search 

func (el *EntityList) Search(eId network.EntityID) (int, *network.Entity)

Search searches the EntityList for the given EntityID and returns the corresponding Entity.

func (*EntityList) Toml 

func (el *EntityList) Toml(suite abstract.Suite) *EntityListToml

Toml returns the toml-writable version of this entityList

type EntityListID 

type EntityListID uuid.UUID

EntityListID uniquely identifies an EntityList

func (EntityListID) String 

func (elId EntityListID) String() string

String returns the default representation of the ID (wrapper around uuid.UUID.String()

type EntityListToml 

type EntityListToml struct {
	Id   EntityListID
	List []*network.EntityToml
}

EntityListToml is the struct can can embedded EntityToml to be written in a toml file

func (*EntityListToml) EntityList 

func (elt *EntityListToml) EntityList(suite abstract.Suite) *EntityList

EntityList returns the Id list from this toml read struct

type EntityListUnknown 

type EntityListUnknown struct {
}

EntityListUnknown is used in case the entity list is unknown

type GenericConfig 

type GenericConfig struct {
	Type uuid.UUID
}

GenericConfig is a config that can withhold any type of specific configs for protocols. It is passed down to the service NewProtocol function.

type Host 

type Host struct {
	// Our entity (i.e. identity over the network)
	Entity *network.Entity

	// tell processMessages to quit
	ProcessMessagesQuit chan bool
	// contains filtered or unexported fields
}

Host is the structure responsible for holding information about the current state

func GenLocalHosts 

func GenLocalHosts(n int, connect bool, processMessages bool) []*Host

GenLocalHosts will create n hosts with the first one being connected to each of the other nodes if connect is true.

func NewHost 

func NewHost(e *network.Entity, pkey abstract.Secret) *Host

NewHost starts a new Host that will listen on the network for incoming messages. It will store the private-key.

func NewLocalHost 

func NewLocalHost(port int) *Host

NewLocalHost creates a new host with the given address and registers it.

func SetupHostsMock 

func SetupHostsMock(s abstract.Suite, addresses ...string) []*Host

SetupHostsMock can be used to create a Host mock for testing.

func (*Host) AddEntityList 

func (h *Host) AddEntityList(el *EntityList)

AddEntityList registers the given EntityList in the underlying overlay. Useful for unit-testing only. XXX probably move into the tests.

func (*Host) AddTree 

func (h *Host) AddTree(t *Tree)

AddTree registers the given Tree struct in the underlying overlay. Useful for unit-testing only. XXX probably move into the tests.

func (*Host) Address 

func (h *Host) Address() string

Address is the addres where this host is listening

func (*Host) Close 

func (h *Host) Close() error

Close shuts down all network connections and closes the listener.

func (*Host) Connect 

func (h *Host) Connect(id *network.Entity) (network.SecureConn, error)

Connect takes an entity where to connect to

func (*Host) Listen 

func (h *Host) Listen()

Listen only starts listening and returns without waiting for the listening to be active.

func (*Host) ListenAndBind 

func (h *Host) ListenAndBind()

ListenAndBind starts listening and returns once it could connect to itself. This can fail in the case of running inside a container or virtual machine using port-forwarding to an internal IP.

func (*Host) Rx 

func (h *Host) Rx() uint64

Rx() to implement monitor/CounterIO

func (*Host) SendRaw 

func (h *Host) SendRaw(e *network.Entity, msg network.ProtocolMessage) error

SendRaw sends to an Entity without wrapping the msg into a SDAMessage

func (*Host) StartProcessMessages 

func (h *Host) StartProcessMessages()

StartProcessMessages start the processing of incoming messages. Mostly it used internally (by the cothority's simulation for instance). Protocol/simulation developers usually won't need it.

func (*Host) Suite 

func (h *Host) Suite() abstract.Suite

Suite can (and should) be used to get the underlying abstract.Suite. Currently the suite is hardcoded into the network library. Don't use network.Suite but Host's Suite function instead if possible.

func (*Host) Tx 

func (h *Host) Tx() uint64

Tx() to implement monitor/CounterIO

func (*Host) WaitForClose 

func (h *Host) WaitForClose()

WaitForClose returns only once all connections have been closed

type LocalTest 

type LocalTest struct {
	// A map of Entity.Id to Hosts
	Hosts map[network.EntityID]*Host
	// A map of Entity.Id to Overlays
	Overlays map[network.EntityID]*Overlay
	// A map of Entity.Id to Services
	Services map[network.EntityID]map[ServiceID]Service
	// A map of EntityList.Id to EntityLists
	EntityLists map[EntityListID]*EntityList
	// A map of Tree.Id to Trees
	Trees map[TreeID]*Tree
	// All single nodes
	Nodes []*TreeNodeInstance
}

LocalTest represents all that is needed for a local test-run

func NewLocalTest 

func NewLocalTest() *LocalTest

NewLocalTest creates a new Local handler that can be used to test protocols locally

func (*LocalTest) AddPendingTreeMarshal 

func (l *LocalTest) AddPendingTreeMarshal(h *Host, tm *TreeMarshal)

AddPendingTreeMarshal takes a treeMarshal and adds it to the list of the known trees, also triggering dispatching of SDA-messages waiting for that tree

func (*LocalTest) CheckPendingTreeMarshal 

func (l *LocalTest) CheckPendingTreeMarshal(h *Host, el *EntityList)

CheckPendingTreeMarshal looks whether there are any treeMarshals to be called

func (*LocalTest) CloseAll 

func (l *LocalTest) CloseAll()

CloseAll takes a list of hosts that will be closed

func (*LocalTest) CreateProtocol 

func (l *LocalTest) CreateProtocol(name string, t *Tree) (ProtocolInstance, error)

CreateNewNodeName takes a name and a tree and will create a new Node with the protocol 'name' without running it

func (*LocalTest) GenBigTree 

func (l *LocalTest) GenBigTree(nbrTreeNodes, nbrHosts, bf int, connect bool, register bool) ([]*Host, *EntityList, *Tree)

GenBigTree will create a tree of n hosts. If connect is true, they will be connected to the root host. If register is true, the EntityList and Tree will be registered with the overlay. 'nbrHosts' is how many hosts are created 'nbrTreeNodes' is how many TreeNodes are created nbrHosts can be smaller than nbrTreeNodes, in which case a given host will be used more than once in the tree.

func (*LocalTest) GenEntityListFromHost 

func (l *LocalTest) GenEntityListFromHost(hosts ...*Host) *EntityList

GenEntityListFromHosts takes a number of hosts as arguments and creates an EntityList.

func (*LocalTest) GenLocalHosts 

func (l *LocalTest) GenLocalHosts(n int, connect, processMsg bool) []*Host

GenLocalHost returns a slice of 'n' Hosts. If 'connect' is true, the hosts will be connected between each other. If 'processMsg' is true, the ProcessMsg-method will be called.

func (*LocalTest) GenTree 

func (l *LocalTest) GenTree(n int, connect, processMsg, register bool) ([]*Host, *EntityList, *Tree)

GenTree will create a tree of n hosts. If connect is true, they will be connected to the root host. If register is true, the EntityList and Tree will be registered with the overlay.

func (*LocalTest) GetNodes 

func (l *LocalTest) GetNodes(tn *TreeNode) []*TreeNodeInstance

GetNodes returns all Nodes that belong to a treeNode

func (*LocalTest) GetPrivate 

func (l *LocalTest) GetPrivate(h *Host) abstract.Secret

GetPrivate returns the private key of a host

func (*LocalTest) GetTree 

func (l *LocalTest) GetTree(tn *TreeNode) *Tree

GetTree returns the tree of the given TreeNode

func (*LocalTest) NewTreeNodeInstance 

func (l *LocalTest) NewTreeNodeInstance(tn *TreeNode, protName string) (*TreeNodeInstance, error)

NewNode creates a new node on a TreeNode

func (*LocalTest) SendTreeNode 

func (l *LocalTest) SendTreeNode(proto string, from, to *TreeNodeInstance, msg network.ProtocolMessage) error

SendTreeNode injects a message directly in the Overlay-layer, bypassing Host and Network

func (*LocalTest) StartProtocol 

func (l *LocalTest) StartProtocol(name string, t *Tree) (ProtocolInstance, error)

StartProtocol takes a name and a tree and will create a new Node with the protocol 'name' running from the tree-root

type MsgHandler 

type MsgHandler func([]*interface{})

MsgHandler is called upon reception of a certain message-type

type NewProtocol 

type NewProtocol func(*TreeNodeInstance) (ProtocolInstance, error)

NewProtocol is the function-signature needed to instantiate a new protocol

type NewServiceFunc 

type NewServiceFunc func(c Context, path string) Service

NewServiceFunc is the type of a function that is used to instantiate a given Service A service is initialized with a Host (to send messages to someone), the overlay (to register a Tree + EntityList + start new node), and a path where it can finds / write everything it needs

type Overlay 

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

Overlay keeps all trees and entity-lists for a given host. It creates Nodes and ProtocolInstances upon request and dispatches the messages.

func NewOverlay 

func NewOverlay(h *Host) *Overlay

NewOverlay creates a new overlay-structure

func (*Overlay) Close 

func (o *Overlay) Close()

Close calls all nodes, deletes them from the list and closes them

func (*Overlay) CreateProtocol 

func (o *Overlay) CreateProtocol(t *Tree, name string) (ProtocolInstance, error)

CreateProtocol returns a fresh Protocol Instance with an attached TreeNodeInstance

func (*Overlay) EntityList 

func (o *Overlay) EntityList(elid EntityListID) *EntityList

EntityList returns the entityList given by EntityListID

func (*Overlay) EntityListFromToken 

func (o *Overlay) EntityListFromToken(tok *Token) *EntityList

EntityListFromToken returns the entitylist corresponding to a token

func (*Overlay) NewTreeNodeInstanceFromProtoName 

func (o *Overlay) NewTreeNodeInstanceFromProtoName(t *Tree, name string) *TreeNodeInstance

NewTreeNodeInstanceFromProtoName takes a protocol name and a tree and instantiate a TreeNodeInstance for this protocol.

func (*Overlay) NewTreeNodeInstanceFromProtocol 

func (o *Overlay) NewTreeNodeInstanceFromProtocol(t *Tree, tn *TreeNode, protoID ProtocolID) *TreeNodeInstance

NewTreeNodeInstanceFromProtocol takes a tree and a treenode (normally the root) and and protocolID and returns a fresh TreeNodeInstance.

func (*Overlay) NewTreeNodeInstanceFromService 

func (o *Overlay) NewTreeNodeInstanceFromService(t *Tree, tn *TreeNode, servID ServiceID) *TreeNodeInstance

NewTreeNodeInstanceFromService takes a tree, a TreeNode and a service ID and returns a TNI.

func (*Overlay) RegisterEntityList 

func (o *Overlay) RegisterEntityList(el *EntityList)

RegisterEntityList puts an entityList in the map

func (*Overlay) RegisterProtocolInstance 

func (o *Overlay) RegisterProtocolInstance(pi ProtocolInstance) error

RegisterProtocolInstance takes a PI and stores it for dispatching the message to it.

func (*Overlay) RegisterTree 

func (o *Overlay) RegisterTree(t *Tree)

RegisterTree takes a tree and puts it in the map

func (*Overlay) SendToTreeNode 

func (o *Overlay) SendToTreeNode(from *Token, to *TreeNode, msg network.ProtocolMessage) error

SendToTreeNode sends a message to a treeNode

func (*Overlay) StartProtocol 

func (o *Overlay) StartProtocol(t *Tree, name string) (ProtocolInstance, error)

StartProtocol will create and start a P.I.

func (*Overlay) TransmitMsg 

func (o *Overlay) TransmitMsg(sdaMsg *Data) error

TransmitMsg takes a message received from the host and treats it. It might - ask for the identityList - ask for the Tree - create a new protocolInstance - pass it to a given protocolInstance

func (*Overlay) Tree 

func (o *Overlay) Tree(tid TreeID) *Tree

Tree returns the tree given by treeId or nil if not found

func (*Overlay) TreeFromToken 

func (o *Overlay) TreeFromToken(tok *Token) *Tree

TreeFromToken searches for the tree corresponding to a token.

func (*Overlay) TreeNodeFromToken 

func (o *Overlay) TreeNodeFromToken(t *Token) (*TreeNode, error)

TreeNodeFromToken returns the treeNode corresponding to a token

type ProtocolID 

type ProtocolID uuid.UUID

ProtocolID uniquely identifies a protocol

func ProtocolNameToID 

func ProtocolNameToID(name string) ProtocolID

ProtocolNameToID returns the ProtocolID corresponding to the given name

func ProtocolRegisterName 

func ProtocolRegisterName(name string, protocol NewProtocol) ProtocolID

ProtocolRegisterName is a convenience function to automatically generate a UUID out of the name.

func (ProtocolID) String 

func (pid ProtocolID) String() string

String returns canonical string representation of the ID

type ProtocolInstance 

type ProtocolInstance interface {
	// Start is called when a leader has created its tree configuration and
	// wants to start a protocol, it calls host.StartProtocol(protocolID), that
	// in turns instantiate a new protocol (with a fresh token), and then call
	// Start on it.
	Start() error
	// Dispatch is called at the beginning by SDA for listening on the channels
	// XXX Should remove that => not using ncessarily channels
	Dispatch() error

	// DispatchMsg is a method that is called each time a message arrive for
	// this protocolInstance. TreeNodeInstance implements that method for you
	// using channels or handlers.
	DispatchMsg(*Data)
	// ProtocolInstance must be using a TreeNodeInstance so SDA knows how to
	// route the message from / to this PI.
	//TreeNodeInstance() *TreeNodeInstance
	// XXX TEMP SOLUTION
	Token() *Token
	// Shutdown cleans up the resources used by this protocol instance
	Shutdown() error
}

ProtocolInstance is the interface that instances have to use in order to be recognized as protocols

func ProtocolInstantiate 

func ProtocolInstantiate(protoID ProtocolID, tni *TreeNodeInstance) (ProtocolInstance, error)

ProtocolInstantiate instantiate a protocol from its ID

type RequestEntityList 

type RequestEntityList struct {
	EntityListID EntityListID
}

RequestEntityList is used to ask the parent for a given EntityList

type RequestTree 

type RequestTree struct {
	// The treeID of the tree we want
	TreeID TreeID
}

RequestTree is used to ask the parent for a given Tree

type RoundID 

type RoundID uuid.UUID

RoundID uniquely identifies a round of a protocol run

func (RoundID) String 

func (rId RoundID) String() string

String returns the canonical representation of the rounds ID (wrapper around uuid.UUID.String())

type SendEntity 

type SendEntity struct {
	Name string
}

SendEntity is the first message we send on creation of a link

type Service 

type Service interface {
	NewProtocol(*TreeNodeInstance, *GenericConfig) (ProtocolInstance, error)
	// ProcessRequest is the function that will be called when a external client
	// using the CLI will contact this service with a request packet.
	// Each request has a field ServiceID, so each time the Host (dispatcher)
	// receives a request, it looks whether it knows the Service it is for and
	// then dispatch it through ProcessRequest.
	ProcessClientRequest(*network.Entity, *ClientRequest)
	// ProcessServiceRequest takes a message from another Service
	ProcessServiceMessage(*network.Entity, *ServiceMessage)
}

Service is a generic interface to define any type of services.

type ServiceID 

type ServiceID uuid.UUID

ServiceID is a type to represent a uuid for a Service

func (*ServiceID) String 

func (s *ServiceID) String() string

String returns the string representation of this ServiceID

type ServiceMessage 

type ServiceMessage struct {
	// Service is the ID of the Service it's destined
	Service ServiceID
	// Data is the data encoded using protobuf for the moment.
	Data []byte
}

ServiceMessage is a generic struct that contains any data destined to a Service that has been created .. by a Service. => Intra-Service communications.

func CreateServiceMessage 

func CreateServiceMessage(service string, r interface{}) (*ServiceMessage, error)

CreateServiceMessage takes a service name and some data and encodes the whole as a ServiceMessage.

type ServiceProcessor 

type ServiceProcessor struct {
	Context
	// contains filtered or unexported fields
}

ServiceProcessor allows for an easy integration of external messages into the Services. You have to embed it into your Service-structer, then it will offer an 'RegisterMessage'-method that takes a message of type 

func ReceiveMsg(e *network.Entity, msg *anyMessageType)(error, *replyMsg)

where 'ReceiveMsg' is any name and 'anyMessageType' will be registered with the network. Once 'anyMessageType' is received by the service, the function 'ReceiveMsg' should return an error and any 'replyMsg' it wants to send.

func NewServiceProcessor 

func NewServiceProcessor(c Context) *ServiceProcessor

NewServiceProcessor initializes your ServiceProcessor.

func (*ServiceProcessor) GetReply 

func (p *ServiceProcessor) GetReply(e *network.Entity, cr *ClientRequest) network.ProtocolMessage

GetReply takes a clientRequest and passes it to the corresponding handler-function.

func (*ServiceProcessor) ProcessClientRequest 

func (p *ServiceProcessor) ProcessClientRequest(e *network.Entity,
	cr *ClientRequest)

ProcessClientRequest takes a request from a client, calculates the reply and sends it back.

func (*ServiceProcessor) ProcessServiceMessage 

func (p *ServiceProcessor) ProcessServiceMessage(e *network.Entity,
	s *ServiceMessage)

ProcessServiceMessage is to implement the Service interface.

func (*ServiceProcessor) RegisterMessage 

func (p *ServiceProcessor) RegisterMessage(f interface{}) error

RegisterMessage puts a new message in the message-handler

type Simulation 

type Simulation interface {
	// This has to initialise all necessary files and copy them to the
	// 'dir'-directory. This directory will be accessible to all simulated
	// hosts.
	// Setup also gets a slice of all available hosts. In turn it has
	// to return a tree using one or more of these hosts. It can create
	// the EntityList as desired, putting more than one Entity/Host on the same host.
	// The 'config'-argument holds all arguments read from the runfile in
	// toml-format.
	Setup(dir string, hosts []string) (*SimulationConfig, error)

	// Node will be run for every node and might be used to setup load-
	// creation. It is started once the Host is set up and running, but before
	// 'Run'
	Node(config *SimulationConfig) error

	// Run will begin with the simulation or return an error. It is sure
	// to be run on the host where 'tree.Root' is. It should only return
	// when all rounds are done.
	Run(config *SimulationConfig) error
}

Simulation is an interface needed by every protocol that wants to be available to be used in a simulation.

func NewSimulation 

func NewSimulation(name string, conf string) (Simulation, error)

NewSimulation returns a simulation and decodes the 'conf' into the simulation-structure

type SimulationBFTree 

type SimulationBFTree struct {
	Rounds     int
	BF         int
	Hosts      int
	SingleHost bool
	Depth      int
}

SimulationBFTree is the main struct storing the data for all the simulations which use a tree with a certain branching factor or depth.

func (*SimulationBFTree) CreateEntityList 

func (s *SimulationBFTree) CreateEntityList(sc *SimulationConfig, addresses []string, port int)

CreateEntityLists creates an EntityList with the host-names in 'addresses'. It creates 's.Hosts' entries, starting from 'port' for each round through 'addresses'

func (*SimulationBFTree) CreateTree 

func (s *SimulationBFTree) CreateTree(sc *SimulationConfig) error

Creates the tree as defined in SimulationBFTree and stores the result in 'sc'

func (*SimulationBFTree) Node 

func (s *SimulationBFTree) Node(sc *SimulationConfig) error

Node - standard registers the entityList and the Tree with that Overlay, so we don't have to pass that around for the experiments.

type SimulationConfig 

type SimulationConfig struct {
	// Represents the tree that has to be used
	Tree *Tree
	// The EntityList used by the tree
	EntityList *EntityList
	// All private keys generated by 'Setup', indexed by the complete addresses
	PrivateKeys map[string]abstract.Secret
	// If non-nil, points to our overlay
	Overlay *Overlay
	// If non-nil, points to our host
	Host *Host
	// Additional configuration used to run
	Config string
}

SimulationConfig has to be returned from 'Setup' and will be passed to 'Run'.

func LoadSimulationConfig 

func LoadSimulationConfig(dir, ha string) ([]*SimulationConfig, error)

Load gets all configuration from dir + SimulationFileName and instantiates the corresponding host 'ha'.

func (SimulationConfig) GetSingleHost 

func (sc SimulationConfig) GetSingleHost() bool

GetSingleHost returns the 'SingleHost'-flag

func (*SimulationConfig) Save 

func (sc *SimulationConfig) Save(dir string) error

Save takes everything in the SimulationConfig structure and saves it to dir + SimulationFileName

type SimulationConfigFile 

type SimulationConfigFile struct {
	TreeMarshal *TreeMarshal
	EntityList  *EntityList
	PrivateKeys map[string]abstract.Secret
	Config      string
}

SimulationConfigFile stores the state of the simulation's config. Only used internally.

type StatusRet 

type StatusRet struct {
	Status string
}

StatusRet is used when a status is returned - mostly an error

type Token 

type Token struct {
	EntityListID EntityListID
	TreeID       TreeID
	// TO BE REMOVED
	ProtoID   ProtocolID
	ServiceID ServiceID
	RoundID   RoundID
	// TreeNodeID is defined by the
	TreeNodeID TreeNodeID
	// contains filtered or unexported fields
}

A Token contains all identifiers needed to uniquely identify one protocol instance. It gets passed when a new protocol instance is created and get used by every protocol instance when they want to send a message. That way, the host knows how to create the SDAData message around the protocol's message with the right fields set.

func (*Token) ChangeTreeNodeID 

func (t *Token) ChangeTreeNodeID(newid TreeNodeID) *Token

ChangeTreeNodeID return a new Token containing a reference to the given TreeNode

func (*Token) Clone 

func (t *Token) Clone() *Token

Clone returns a new token out of this one

func (*Token) Id 

func (t *Token) Id() TokenID

Id returns the TokenID which can be used to identify by token in map

type TokenID 

type TokenID uuid.UUID

TokenID uniquely identifies the start and end-point of a message by an ID (see Token struct)

func (*TokenID) String 

func (t *TokenID) String() string

type Tree 

type Tree struct {
	Id         TreeID
	EntityList *EntityList
	Root       *TreeNode
}

Tree is a topology to be used by any network layer/host layer It contains the peer list we use, and the tree we use

func NewTree 

func NewTree(el *EntityList, r *TreeNode) *Tree

NewTree creates a new tree using the entityList and the root-node. It also generates the id.

func NewTreeFromMarshal 

func NewTreeFromMarshal(buf []byte, el *EntityList) (*Tree, error)

NewTreeFromMarshal takes a slice of bytes and an EntityList to re-create the original tree

func (*Tree) BinaryMarshaler 

func (t *Tree) BinaryMarshaler() ([]byte, error)

BinaryMarshaler does the same as Marshal

func (*Tree) BinaryUnmarshaler 

func (t *Tree) BinaryUnmarshaler(b []byte) error

BinaryUnmarshaler takes a TreeMarshal and stores it in the tree

func (*Tree) Dump 

func (t *Tree) Dump() string

Dump returns string about the tree

func (*Tree) Equal 

func (t *Tree) Equal(t2 *Tree) bool

Equal verifies if the given tree is equal

func (*Tree) IsBinary 

func (t *Tree) IsBinary(root *TreeNode) bool

IsBinary returns true if every node has two or no children

func (*Tree) IsNary 

func (t *Tree) IsNary(root *TreeNode, N int) bool

IsNary returns true if every node has two or no children

func (*Tree) List 

func (t *Tree) List() (ret []*TreeNode)

List returns a list of TreeNodes generated by DFS-iterating the Tree

func (*Tree) MakeTreeMarshal 

func (t *Tree) MakeTreeMarshal() *TreeMarshal

MakeTreeMarshal creates a replacement-tree that is safe to send: no parent (creates loops), only sends ids (not send the entityList again)

func (*Tree) Marshal 

func (t *Tree) Marshal() ([]byte, error)

Marshal creates a simple binary-representation of the tree containing only the ids of the elements. Use NewTreeFromMarshal to get back the original tree

func (*Tree) Search 

func (t *Tree) Search(tn TreeNodeID) (ret *TreeNode)

Search searches the Tree for the given TreeNodeID and returns the corresponding TreeNode

func (*Tree) Size 

func (t *Tree) Size() int

Size returns the number of all TreeNodes

func (*Tree) String 

func (t *Tree) String() string

String writes the definition of the tree

func (*Tree) UsesList 

func (t *Tree) UsesList() bool

UsesList returns true if all Entities of the list are used at least once in the tree

type TreeID 

type TreeID uuid.UUID

TreeID uniquely identifies a Tree struct in the sda framework.

func (TreeID) Equals 

func (tId TreeID) Equals(tId2 TreeID) bool

Equals returns true if and only if the given TreeID equals the current one.

func (TreeID) String 

func (tId TreeID) String() string

String returns a canonical representation of the TreeID.

type TreeMarshal 

type TreeMarshal struct {
	// This is the UUID of the corresponding TreeNode
	TreeNodeId TreeNodeID
	// TreeId identifies the Tree for the top-node
	TreeId TreeID
	// This is the UUID of the Entity, except
	EntityId network.EntityID
	// for the top-node this contains the EntityList's ID
	EntityListID EntityListID
	// All children from this tree. The top-node only has one child, which is
	// the root
	Children []*TreeMarshal
}

TreeMarshal is used to send and receive a tree-structure without having to copy the whole nodelist

func TreeMarshalCopyTree 

func TreeMarshalCopyTree(tr *TreeNode) *TreeMarshal

TreeMarshalCopyTree takes a TreeNode and returns a corresponding TreeMarshal

func (TreeMarshal) MakeTree 

func (tm TreeMarshal) MakeTree(el *EntityList) (*Tree, error)

MakeTree creates a tree given an EntityList

func (*TreeMarshal) MakeTreeFromList 

func (tm *TreeMarshal) MakeTreeFromList(parent *TreeNode, el *EntityList) *TreeNode

MakeTreeFromList creates a sub-tree given an EntityList

func (*TreeMarshal) String 

func (tm *TreeMarshal) String() string

type TreeNode 

type TreeNode struct {
	// The Id represents that node of the tree
	Id TreeNodeID
	// The Entity points to the corresponding host. One given host
	// can be used more than once in a tree.
	Entity *network.Entity
	// EntityIdx is the index in the EntityList where the `Entity` is located
	EntityIdx int
	// Parent link
	Parent *TreeNode
	// Children links
	Children []*TreeNode
	// Aggregate public key for *this* subtree,i.e. this node's public key + the
	// aggregate of all its children's aggregate public key
	PublicAggregateSubTree abstract.Point
}

TreeNode is one node in the tree

func NewTreeNode 

func NewTreeNode(entityIdx int, ni *network.Entity) *TreeNode

NewTreeNode creates a new TreeNode with the proper Id

func (*TreeNode) AddChild 

func (t *TreeNode) AddChild(c *TreeNode)

AddChild adds a child to this tree-node.

func (*TreeNode) Equal 

func (t *TreeNode) Equal(t2 *TreeNode) bool

Equal tests if that node is equal to the given node

func (*TreeNode) IsConnectedTo 

func (t *TreeNode) IsConnectedTo(e *network.Entity) bool

IsConnectedTo checks if the TreeNode can communicate with its parent or children.

func (*TreeNode) IsInTree 

func (t *TreeNode) IsInTree(tree *Tree) bool

IsInTree - verifies if the TreeNode is in the given Tree

func (*TreeNode) IsLeaf 

func (t *TreeNode) IsLeaf() bool

IsLeaf returns true for a node without children

func (*TreeNode) IsRoot 

func (t *TreeNode) IsRoot() bool

IsRoot returns true for a node without a parent

func (*TreeNode) Name 

func (t *TreeNode) Name() string

Name returns a human readable representation of the TreeNode (IP address).

func (*TreeNode) String 

func (t *TreeNode) String() string

String returns the current treenode's Id as a string.

func (*TreeNode) Visit 

func (t *TreeNode) Visit(firstDepth int, fn func(depth int, n *TreeNode))

Visit is a recursive function that allows for depth-first calling on all nodes

type TreeNodeCache 

type TreeNodeCache struct {
	Entries map[TreeID]map[TreeNodeID]*TreeNode
	sync.Mutex
}

TreeNodeCache is a cache that maps from token to treeNode. Since the mapping is not 1-1 (many Token can point to one TreeNode, but one token leads to one TreeNode), we have to do certain lookup, but that's better than searching the tree each time.

func NewTreeNodeCache 

func NewTreeNodeCache() *TreeNodeCache

Returns a new TreeNodeCache

func (TreeNodeCache) Cache 

func (tnc TreeNodeCache) Cache(tree *Tree, treeNode *TreeNode)

Cache a TreeNode that relates to the Tree It will also cache the parent and children of the treenode since that's most likely what we are going to query.

func (TreeNodeCache) GetFromToken 

func (tnc TreeNodeCache) GetFromToken(tok *Token) *TreeNode

GetFromToken returns the TreeNode that the token is pointing at, or nil if there is none for this token.

type TreeNodeID 

type TreeNodeID uuid.UUID

TreeNodeID identifies a given TreeNode struct in the sda framework.

func (TreeNodeID) Equals 

func (tId TreeNodeID) Equals(tId2 TreeNodeID) bool

Equals returns true if and only if the given TreeNodeID equals the current one.

func (TreeNodeID) String 

func (tId TreeNodeID) String() string

String returns a canonical representation of the TreeNodeID.

type TreeNodeInstance 

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

TreeNodeInstance represents a protocol-instance in a given TreeNode. It embeds an Overlay where all the tree-structures are stored.

func (*TreeNodeInstance) Broadcast 

func (n *TreeNodeInstance) Broadcast(msg interface{}) error

Broadcast sends a given message from the calling node directly to all other TreeNodes

func (*TreeNodeInstance) Children 

func (n *TreeNodeInstance) Children() []*TreeNode

Children returns the children of ourselves

func (*TreeNodeInstance) ClearFlag 

func (n *TreeNodeInstance) ClearFlag(mt network.MessageTypeID, f uint32)

ClearFlag makes sure a given flag is removed

func (*TreeNodeInstance) Close 

func (n *TreeNodeInstance) Close() error

Close shuts down the go-routine and calls the protocolInstance-shutdown

func (*TreeNodeInstance) CloseHost 

func (n *TreeNodeInstance) CloseHost() error

CloseHost closes the underlying sda.Host (which closes the overlay and sends Shutdown to all protocol instances)

func (*TreeNodeInstance) Dispatch 

func (n *TreeNodeInstance) Dispatch() error

Dispatch - the standard dispatching function is empty

func (*TreeNodeInstance) DispatchChannel 

func (n *TreeNodeInstance) DispatchChannel(msgSlice []*Data) error

DispatchChannel takes a message and sends it to a channel

func (*TreeNodeInstance) DispatchMsg 

func (n *TreeNodeInstance) DispatchMsg(msg *Data)

DispatchMsg takes a message and puts it into a queue for later processing. This allows a protocol to have a backlog of messages.

func (*TreeNodeInstance) Done 

func (n *TreeNodeInstance) Done()

Done calls onDoneCallback if available and only finishes when the return- value is true.

func (*TreeNodeInstance) Entity 

func (n *TreeNodeInstance) Entity() *network.Entity

Entity returns our entity

func (*TreeNodeInstance) EntityList 

func (n *TreeNodeInstance) EntityList() *EntityList

EntityList returns the entity-list

func (*TreeNodeInstance) HasFlag 

func (n *TreeNodeInstance) HasFlag(mt network.MessageTypeID, f uint32) bool

HasFlag returns true if the given flag is set

func (*TreeNodeInstance) Host 

func (n *TreeNodeInstance) Host() *Host

Host returns the underlying Host of this node. WARNING: you should not play with that feature unless you know what you are doing. This feature is mean to access the low level parts of the API. For example it is used to add a new tree config / new entity list to the host.

func (*TreeNodeInstance) Index 

func (n *TreeNodeInstance) Index() int

Index returns the index of the node in the EntityList

func (*TreeNodeInstance) Info 

func (n *TreeNodeInstance) Info() string

Info returns a human readable representation name of this Node (IP address and TokenID).

func (*TreeNodeInstance) IsLeaf 

func (n *TreeNodeInstance) IsLeaf() bool

IsLeaf returns whether whether we are at the bottom of the tree

func (*TreeNodeInstance) IsRoot 

func (n *TreeNodeInstance) IsRoot() bool

IsRoot returns whether whether we are at the top of the tree

func (*TreeNodeInstance) List 

func (n *TreeNodeInstance) List() []*TreeNode

List returns the list of TreeNodes cached in the node (creating it if necessary)

func (*TreeNodeInstance) Name 

func (n *TreeNodeInstance) Name() string

Name returns a human readable name of this Node (IP address).

func (*TreeNodeInstance) OnDoneCallback 

func (n *TreeNodeInstance) OnDoneCallback(fn func() bool)

OnDoneCallback should be called if we want to control the Done() of the node. It is used by protocols that uses others protocols inside and that want to control when the final Done() should be called. the function should return true if the real Done() has to be called otherwise false.

func (*TreeNodeInstance) Parent 

func (n *TreeNodeInstance) Parent() *TreeNode

Parent returns the parent-TreeNode of ourselves

func (*TreeNodeInstance) Private 

func (n *TreeNodeInstance) Private() abstract.Secret

Private returns the private key of the entity

func (*TreeNodeInstance) ProtocolInstance 

func (n *TreeNodeInstance) ProtocolInstance() ProtocolInstance

ProtocolInstance returns the instance of the running protocol

func (*TreeNodeInstance) Public 

func (n *TreeNodeInstance) Public() abstract.Point

Public returns the public key of the entity

func (*TreeNodeInstance) RegisterChannel 

func (n *TreeNodeInstance) RegisterChannel(c interface{}) error

RegisterChannel takes a channel with a struct that contains two elements: a TreeNode and a message. It will send every message that are the same type to this channel. This function handles also

  • registration of the message-type
  • aggregation or not of messages: if you give a channel of slices, the messages will be aggregated, else they will come one-by-one

func (*TreeNodeInstance) RegisterHandler 

func (n *TreeNodeInstance) RegisterHandler(c interface{}) error

RegisterChannel takes a channel with a struct that contains two elements: a TreeNode and a message. It will send every message that are the same type to this channel. This function handles also

  • registration of the message-type
  • aggregation or not of messages: if you give a channel of slices, the messages will be aggregated, else they will come one-by-one

func (*TreeNodeInstance) RegisterHandlers 

func (n *TreeNodeInstance) RegisterHandlers(handlers ...interface{}) error

RegisterHandlers registers a list of given handlers by calling RegisterHandler above

func (*TreeNodeInstance) Root 

func (n *TreeNodeInstance) Root() *TreeNode

Root returns the root-node of that tree

func (*TreeNodeInstance) SendTo 

func (n *TreeNodeInstance) SendTo(to *TreeNode, msg interface{}) error

SendTo sends to a given node

func (*TreeNodeInstance) SendToChildren 

func (n *TreeNodeInstance) SendToChildren(msg interface{}) error

SendToChildren sends a given message to all children of the calling node. It stops sending if sending to one of the children fails. In that case it returns an error. If the underlying node is a leaf node this function does nothing.

func (*TreeNodeInstance) SendToChildrenInParallel 

func (n *TreeNodeInstance) SendToChildrenInParallel(msg interface{}) error

SendToChildrenInParallel sends a given message to all children of the calling node. It has the following differences to node.SendToChildren: The actual sending happens in a go routine (in parallel). It continues sending to the other nodes if sending to one of the children fails. In that case it will collect all errors (separated by '\n'.) If the underlying node is a leaf node this function does nothing.

func (*TreeNodeInstance) SendToParent 

func (n *TreeNodeInstance) SendToParent(msg interface{}) error

SendToParent sends a given message to the parent of the calling node (unless it is the root)

func (*TreeNodeInstance) SetFlag 

func (n *TreeNodeInstance) SetFlag(mt network.MessageTypeID, f uint32)

SetFlag makes sure a given flag is set

func (*TreeNodeInstance) Shutdown 

func (n *TreeNodeInstance) Shutdown() error

Shutdown - standard Shutdown implementation. Define your own in your protocol (if necessary)

func (*TreeNodeInstance) StartProtocol 

func (n *TreeNodeInstance) StartProtocol() error

StartProtocol calls the Start() on the underlying protocol which in turn will initiate the first message to its children

func (*TreeNodeInstance) Suite 

func (n *TreeNodeInstance) Suite() abstract.Suite

Suite can be used to get the current abstract.Suite (currently hardcoded into the network library).

func (*TreeNodeInstance) Token 

func (n *TreeNodeInstance) Token() *Token

Token returns a CLONE of the underlying sda.Token struct. Useful for unit testing.

func (*TreeNodeInstance) TokenID 

func (n *TreeNodeInstance) TokenID() TokenID

TokenID returns the TokenID of the given node (to uniquely identify it)

func (*TreeNodeInstance) Tree 

func (n *TreeNodeInstance) Tree() *Tree

Tree returns the tree of that node

func (*TreeNodeInstance) TreeNode 

func (n *TreeNodeInstance) TreeNode() *TreeNode

TreeNode gets the treeNode of this node. If there is no TreeNode for the Token of this node, the function will return nil

func (*TreeNodeInstance) TreeNodeInstance 

func (n *TreeNodeInstance) TreeNodeInstance() *TreeNodeInstance

TreeNodeInstance returns itself (XXX quick hack for this services2 branch version for the tests)

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.