Documentation
¶
Overview ¶
Package core contains common definitions used by other modules.
Index ¶
- Constants
- Variables
- func UnMarshalResponse(resp []byte, typeHolders []interface{}) ([]interface{}, error)
- type Arguments
- type ArtifactManager
- type Bootstrapper
- type Cascade
- type CaseBind
- type CaseBindReplay
- type CaseRecord
- type CaseRecordType
- type Certificate
- type CodeDescriptor
- type Component
- type Components
- type Entropy
- type JetCoordinator
- type JetRole
- type Ledger
- type Logger
- type LogicCallContext
- type LogicRunner
- type MachineLogicExecutor
- type MachineType
- type Message
- type MessageBus
- type MessageHandler
- type MessageType
- type Network
- type NetworkCoordinator
- type Node
- type NodeNetwork
- type NodeRole
- type NodeState
- type ObjectDescriptor
- type Pulse
- type PulseManager
- type PulseNumber
- type PulseSenderConfirmation
- type RecordID
- type RecordRef
- type RefIterator
- type RemoteProcedure
- type Reply
- type ReplyType
- type Signature
- type SignedMessage
Constants ¶
const ( // RoleVirtualExecutor is responsible for current pulse CPU operations. RoleVirtualExecutor = JetRole(iota + 1) // RoleVirtualValidator is responsible for previous pulse CPU operations. RoleVirtualValidator // RoleLightExecutor is responsible for current pulse Disk operations. RoleLightExecutor // RoleLightValidator is responsible for previous pulse Disk operations. RoleLightValidator // RoleHeavyExecutor is responsible for permanent Disk operations. RoleHeavyExecutor )
const ( // Joined NodeJoined = NodeState(iota + 1) // Prepared NodePrepared // Active NodeActive // Leaved NodeLeaved // Suspended NodeSuspended )
TODO: document all node states
const ( RoleUnknown = NodeRole(iota) RoleVirtual RoleHeavyMaterial RoleLightMaterial )
const ( // PulseNumberSize declares the number of bytes in the pulse number PulseNumberSize = 4 // EntropySize declares the number of bytes in the pulse entropy EntropySize = 64 )
const ( // RecordHashSize is a record hash size. We use 224-bit SHA-3 hash (28 bytes). RecordHashSize = 28 // RecordIDSize is relative record address. RecordIDSize = PulseNumberSize + RecordHashSize // RecordRefSize is absolute records address (including domain ID). RecordRefSize = RecordIDSize * 2 )
const FirstPulseNumber = 65537
FirstPulseNumber is the hardcoded first pulse number. Because first 65536 numbers are saved for the system's needs
Variables ¶
var ( // ErrUnknown returned when error type cannot be defined. ErrUnknown = errors.New("unknown error") // ErrDeactivated returned when requested object is deactivated. ErrDeactivated = errors.New("object is deactivated") // ErrStateNotAvailable returned when requested object is deactivated. ErrStateNotAvailable = errors.New("object state is not available") )
var GenesisPulse = &Pulse{PulseNumber: FirstPulseNumber, Entropy: [EntropySize]byte{}}
GenesisPulse is a first pulse for the system because first 2 bits of pulse number and first 65536 pulses a are used by system needs and pulse numbers are related to the seconds of Unix time for calculation pulse numbers we use the formula = unix.Now() - firstPulseDate + 65536
Functions ¶
func UnMarshalResponse ¶ added in v0.6.0
UnMarshalResponse unmarshals return values by cbor
Types ¶
type Arguments ¶
type Arguments []byte
Arguments is a dedicated type for arguments, that represented as bynary cbored blob
func MarshalArgs ¶ added in v0.6.0
MarshalArgs marshals arguments by cbor
type ArtifactManager ¶
type ArtifactManager interface { // GenesisRef returns the root record reference. // // Root record is the parent for all top-level records. GenesisRef() *RecordRef // RegisterRequest creates or check call request record and returns it RecordRef. // (used by VM on executing side) RegisterRequest(ctx context.Context, message Message) (*RecordID, error) // RegisterValidation marks provided object state as approved or disapproved. // // When fetching object, validity can be specified. RegisterValidation(ctx context.Context, object RecordRef, state RecordID, isValid bool, validationMessages []Message) error // RegisterResult saves VM method call result. RegisterResult(ctx context.Context, request RecordRef, payload []byte) (*RecordID, error) // GetCode returns code from code record by provided reference according to provided machine preference. // // This method is used by VM to fetch code for execution. GetCode(ctx context.Context, ref RecordRef) (CodeDescriptor, error) // GetObject returns descriptor for provided state. // // If provided state is nil, the latest state will be returned (with deactivation check). Returned descriptor will // provide methods for fetching all related data. GetObject(ctx context.Context, head RecordRef, state *RecordID, approved bool) (ObjectDescriptor, error) // GetDelegate returns provided object's delegate reference for provided type. // // Object delegate should be previously created for this object. If object delegate does not exist, an error will // be returned. GetDelegate(ctx context.Context, head, asType RecordRef) (*RecordRef, error) // GetChildren returns children iterator. // // During iteration children refs will be fetched from remote source (parent object). GetChildren(ctx context.Context, parent RecordRef, pulse *PulseNumber) (RefIterator, error) // DeclareType creates new type record in storage. // // Type is a contract interface. It contains one method signature. DeclareType(ctx context.Context, domain, request RecordRef, typeDec []byte) (*RecordID, error) // DeployCode creates new code record in storage. // // Code records are used to activate prototype. DeployCode(ctx context.Context, domain, request RecordRef, code []byte, machineType MachineType) (*RecordID, error) // ActivatePrototype creates activate object record in storage. Provided prototype reference will be used as objects prototype // memory as memory of created object. If memory is not provided, the prototype default memory will be used. // // Request reference will be this object's identifier and referred as "object head". ActivatePrototype( ctx context.Context, domain, request, parent, code RecordRef, memory []byte, ) (ObjectDescriptor, error) // ActivateObject creates activate object record in storage. If memory is not provided, the prototype default // memory will be used. // // Request reference will be this object's identifier and referred as "object head". ActivateObject( ctx context.Context, domain, request, parent, prototype RecordRef, asDelegate bool, memory []byte, ) (ObjectDescriptor, error) // UpdatePrototype creates amend object record in storage. Provided reference should be a reference to the head of // the prototype. Provided memory well be the new object memory. // // Returned reference will be the latest object state (exact) reference. UpdatePrototype( ctx context.Context, domain, request RecordRef, obj ObjectDescriptor, memory []byte, code *RecordRef, ) (ObjectDescriptor, error) // UpdateObject creates amend object record in storage. Provided reference should be a reference to the head of the // object. Provided memory well be the new object memory. // // Returned reference will be the latest object state (exact) reference. UpdateObject( ctx context.Context, domain, request RecordRef, obj ObjectDescriptor, memory []byte, ) (ObjectDescriptor, error) // DeactivateObject creates deactivate object record in storage. Provided reference should be a reference to the head // of the object. If object is already deactivated, an error should be returned. // // Deactivated object cannot be changed. DeactivateObject(ctx context.Context, domain, request RecordRef, obj ObjectDescriptor) (*RecordID, error) }
ArtifactManager is a high level storage interface.
type Bootstrapper ¶ added in v0.2.0
Bootstrapper is the global bootstrapper handler. Other system parts communicate with bootstrapper through it.
type Cascade ¶ added in v0.2.0
type Cascade struct { // NodeIds contains the slice of node identifiers that will receive the message NodeIds []RecordRef // GeneratedEntropy is used for pseudorandom cascade building Entropy Entropy // Replication factor is the number of children nodes of the each node of the cascade ReplicationFactor uint }
Cascade contains routing data for cascade sending
type CaseBind ¶ added in v0.5.0
type CaseBind struct {
Records map[RecordRef][]CaseRecord // ordered cases for each object
}
CaseBinder is a whole result of executor efforts on every object it seen on this pulse
type CaseBindReplay ¶ added in v0.5.0
type CaseBindReplay struct { Pulse Pulse Records []CaseRecord RecordsLen int Step int Fail int }
type CaseRecord ¶ added in v0.5.0
type CaseRecord struct { Type CaseRecordType ReqSig []byte Resp interface{} }
CaseRecord is one record of validateable object calling history
type CaseRecordType ¶ added in v0.5.0
type CaseRecordType int
CaseRecordType is a type of caserecord
const ( CaseRecordTypeStart CaseRecordType CaseRecordTypeResult CaseRecordTypeRequest CaseRecordTypeGetObject CaseRecordTypeSignObject CaseRecordTypeRouteCall CaseRecordTypeSaveAsChild CaseRecordTypeGetObjChildren CaseRecordTypeSaveAsDelegate CaseRecordTypeGetDelegate CaseRecordTypeDeactivateObject )
Types of records
type Certificate ¶ added in v0.6.1
type Certificate interface { GetPublicKey() (string, error) // TODO should be removed GetPrivateKey() (string, error) // TODO should be removed GetEcdsaPrivateKey() *ecdsa.PrivateKey }
Certificate interface provides methods to manage keys
type CodeDescriptor ¶
type CodeDescriptor interface { // Ref returns reference to represented code record. Ref() *RecordRef // MachineType returns code machine type for represented code. MachineType() MachineType // Code returns code data. Code() ([]byte, error) }
CodeDescriptor represents meta info required to fetch all code data.
type Component ¶
type Component interface { Start(ctx context.Context, components Components) error Stop(ctx context.Context) error }
Component controller methods
type Components ¶
type Components struct { Certificate Certificate NodeNetwork NodeNetwork LogicRunner LogicRunner Ledger Ledger Network Network MessageBus MessageBus Metrics Component Bootstrapper Bootstrapper APIRunner Component NetworkCoordinator NetworkCoordinator }
Components is a registry for other core interfaces Fields order are important and represent start and stop order in the daemon
type Entropy ¶ added in v0.2.0
type Entropy [EntropySize]byte
Entropy is 64 random bytes used in every pseudo-random calculations.
type JetCoordinator ¶ added in v0.0.6
type JetCoordinator interface { // IsAuthorized checks for role on concrete pulse for the address. IsAuthorized(ctx context.Context, role JetRole, obj RecordRef, pulse PulseNumber, node RecordRef) (bool, error) // QueryRole returns node refs responsible for role bound operations for given object and pulse. QueryRole(ctx context.Context, role JetRole, obj RecordRef, pulse PulseNumber) ([]RecordRef, error) }
JetCoordinator provides methods for calculating Jet affinity (e.g. to which Jet a message should be sent).
type Ledger ¶
type Ledger interface { // GetArtifactManager returns artifact manager to work with. GetArtifactManager() ArtifactManager // GetJetCoordinator returns jet coordinator to work with. GetJetCoordinator() JetCoordinator // GetPulseManager returns pulse manager to work with. GetPulseManager() PulseManager }
Ledger is the global ledger handler. Other system parts communicate with ledger through it.
type Logger ¶ added in v0.0.6
type Logger interface { // SetLevel sets log level. SetLevel(string) error // GetLevel gets log level. GetLevel() string // Debug logs a message at level Debug. Debug(...interface{}) // Debugln logs a message at level Debug. Debugln(...interface{}) // Debugf formatted logs a message at level Debug. Debugf(string, ...interface{}) // Info logs a message at level Info. Info(...interface{}) // Infoln logs a message at level Info. Infoln(...interface{}) // Infof formatted logs a message at level Info. Infof(string, ...interface{}) // Warn logs a message at level Warn. Warn(...interface{}) // Warnln logs a message at level Warn. Warnln(...interface{}) // Warnf formatted logs a message at level Warn. Warnf(string, ...interface{}) // Error logs a message at level Error. Error(...interface{}) // Errorln logs a message at level Error. Errorln(...interface{}) // Errorf formatted logs a message at level Error. Errorf(string, ...interface{}) // Fatal logs a message at level Fatal and than call os.exit(). Fatal(...interface{}) // Fatalln logs a message at level Fatal and than call os.exit(). Fatalln(...interface{}) // Fatalf formatted logs a message at level Fatal and than call os.exit(). Fatalf(string, ...interface{}) // Panic logs a message at level Panic and than call panic(). Panic(...interface{}) // Panicln logs a message at level Panic and than call panic(). Panicln(...interface{}) // Panicf formatted logs a message at level Panic and than call panic(). Panicf(string, ...interface{}) // SetOutput sets the output destination for the logger. SetOutput(w io.Writer) // WithFields return copy of Logger with predefined fields. WithFields(map[string]interface{}) Logger // WithField return copy of Logger with predefined single field. WithField(string, interface{}) Logger }
Logger is the interface for loggers used in the Insolar components.
type LogicCallContext ¶ added in v0.0.6
type LogicCallContext struct { Callee *RecordRef // Contract that was called Request *RecordRef // ref of request Prototype *RecordRef // Image of the callee Parent *RecordRef // Parent of the callee Caller *RecordRef // Contract that made the call Time time.Time // Time when call was made Pulse Pulse // Number of the pulse TraceID string }
LogicCallContext is a context of contract execution
type LogicRunner ¶
type LogicRunner interface { Execute(context.Context, SignedMessage) (res Reply, err error) ValidateCaseBind(context.Context, SignedMessage) (res Reply, err error) ProcessValidationResults(context.Context, SignedMessage) (res Reply, err error) ExecutorResults(context.Context, SignedMessage) (res Reply, err error) Validate(ref RecordRef, p Pulse, cr []CaseRecord) (int, error) // TODO hide? OnPulse(Pulse) error }
LogicRunner is an interface that should satisfy logic executor
type MachineLogicExecutor ¶
type MachineLogicExecutor interface { CallMethod( ctx context.Context, callContext *LogicCallContext, code RecordRef, data []byte, method string, args Arguments, ) ( newObjectState []byte, methodResults Arguments, err error, ) CallConstructor( ctx context.Context, callContext *LogicCallContext, code RecordRef, name string, args Arguments, ) ( objectState []byte, err error, ) Stop() error }
MachineLogicExecutor is an interface for implementers of one particular machine type
type MachineType ¶
type MachineType int
MachineType is a type of virtual machine
const ( MachineTypeNotExist = 0 MachineTypeBuiltin MachineType = iota + 1 MachineTypeGoPlugin MachineTypesLastID )
Real constants of MachineType
type Message ¶
type Message interface { // Type returns message type. Type() MessageType // Target returns target for this message. If nil, Message will be sent for all actors for the role returned by // Role method. Target() *RecordRef // TargetRole returns jet role to actors of which Message should be sent. TargetRole() JetRole // GetCaller returns initiator of this event. GetCaller() *RecordRef }
Message is a routable packet, ATM just a method call
type MessageBus ¶ added in v0.4.0
type MessageBus interface { // Send an `Message` and get a `Reply` or error from remote host. Send(context.Context, Message) (Reply, error) // Register saves message handler in the registry. Only one handler can be registered for a message type. Register(p MessageType, handler MessageHandler) error // MustRegister is a Register wrapper that panics if an error was returned. MustRegister(p MessageType, handler MessageHandler) }
MessageBus interface
type MessageHandler ¶ added in v0.4.0
type MessageHandler func(context.Context, SignedMessage) (Reply, error)
MessageHandler is a function for message handling. It should be registered via Register method.
type MessageType ¶ added in v0.4.0
type MessageType byte
MessageType is an enum type of message.
const ( // TypeCallMethod calls method and returns result TypeCallMethod MessageType = iota // TypeCallConstructor is a message for calling constructor and obtain its reply TypeCallConstructor // TypeExecutorResults message that goes to new Executor to validate previous Executor actions through CaseBind TypeExecutorResults // TypeValidateCaseBind sends CaseBind form Executor to Validators for redo all actions TypeValidateCaseBind // TypeValidationResults sends from Validator to new Executor with results of validation actions of previous Executor TypeValidationResults // TypeRequestCall registers call on storage. TypeRequestCall // TypeGetCode retrieves code from storage. TypeGetCode // TypeGetObject retrieves object from storage. TypeGetObject // TypeGetDelegate retrieves object represented as provided type. TypeGetDelegate // TypeGetChildren retrieves object's children. TypeGetChildren // TypeUpdateObject amends object. TypeUpdateObject // TypeRegisterChild registers child on the parent object. TypeRegisterChild // TypeJetDrop carries jet drop to validators TypeJetDrop // TypeSetRecord saves record in storage. TypeSetRecord // TypeValidateRecord saves record in storage. TypeValidateRecord // TypeSetBlob saves blob in storage. TypeSetBlob // TypeBootstrapRequest used for bootstrap object generation. TypeBootstrapRequest )
func (MessageType) String ¶ added in v0.5.0
func (i MessageType) String() string
type Network ¶
type Network interface { // SendMessage sends a message. SendMessage(nodeID RecordRef, method string, msg SignedMessage) ([]byte, error) // SendCascadeMessage sends a message. SendCascadeMessage(data Cascade, method string, msg SignedMessage) error // GetAddress returns an origin address. GetAddress() string // RemoteProcedureRegister is remote procedure register func. RemoteProcedureRegister(name string, method RemoteProcedure) // GetNodeID returns current node id. GetNodeID() RecordRef // GetPrivateKey returns a private key. GetPrivateKey() *ecdsa.PrivateKey }
Network is interface for network modules facade.
type NetworkCoordinator ¶ added in v0.6.0
type NetworkCoordinator interface { // Authorize authorizes node by verifying it's signature Authorize(ctx context.Context, nodeRef RecordRef, seed []byte, signatureRaw []byte) (string, []NodeRole, error) // RegisterNode registers node in nodedomain RegisterNode(ctx context.Context, publicKey string, numberOfBootstrapNodes int, majorityRule int, roles []string, ip string) ([]byte, error) // WriteActiveNodes write active nodes to ledger WriteActiveNodes(ctx context.Context, number PulseNumber, activeNodes []*Node) error }
NetworkCoordinator encapsulates logic of network configuration
type Node ¶ added in v0.6.2
type Node struct { // NodeID is the unique identifier of the node NodeID RecordRef // PulseNum is the pulse number after which the new state is assigned to the node PulseNum PulseNumber // State is the node state State NodeState // JetRoles is the set of candidate JetRoles for the node Roles []NodeRole // PublicKey is the public key of the node PublicKey *ecdsa.PublicKey // Addess is the network adress of the node Address string // Version of node software Version string }
type NodeNetwork ¶ added in v0.6.2
type NodeNetwork interface { // GetOrigin get active node for the current insolard. Returns nil if the current insolard is not an active node. GetOrigin() *Node // GetActiveNode get active node by its reference. Returns nil if node is not found. GetActiveNode(ref RecordRef) *Node // GetActiveNodes get active nodes. GetActiveNodes() []*Node // GetActiveNodesByRole get active nodes by role GetActiveNodesByRole(role JetRole) []RecordRef }
type NodeRole ¶ added in v0.6.0
type NodeRole int
NodeRole holds role of node
func GetRoleFromString ¶ added in v0.6.0
GetRoleFromString converts role from string to NodeRole
type ObjectDescriptor ¶
type ObjectDescriptor interface { // HeadRef returns head reference to represented object record. HeadRef() *RecordRef // StateID returns reference to object state record. StateID() *RecordID // Memory fetches object memory from storage. Memory() []byte // IsPrototype determines if the object is a prototype. IsPrototype() bool // Code returns code reference. Code() (*RecordRef, error) // Prototype returns prototype reference. Prototype() (*RecordRef, error) // Children returns object's children references. Children(pulse *PulseNumber) (RefIterator, error) // ChildPointer returns the latest child for this object. ChildPointer() *RecordID // Parent returns object's parent. Parent() *RecordRef }
ObjectDescriptor represents meta info required to fetch all object data.
type Pulse ¶ added in v0.2.0
type Pulse struct { PulseNumber PulseNumber NextPulseNumber PulseNumber Entropy Entropy Signs map[string]PulseSenderConfirmation }
Pulse is base data structure for a pulse.
func (*Pulse) PulseDuration ¶ added in v0.4.0
type PulseManager ¶ added in v0.2.0
type PulseManager interface { // Current returns current pulse structure. Current(context.Context) (*Pulse, error) // Set set's new pulse and closes current jet drop. Set(context.Context, Pulse) error }
PulseManager provides Ledger's methods related to Pulse.
type PulseNumber ¶ added in v0.0.6
type PulseNumber uint32
PulseNumber is a sequential number of Pulse. Upper 2 bits are reserved for use in references (scope), must be zero otherwise. Valid Absolute PulseNum must be >65536. If PulseNum <65536 it is a relative PulseNum
func Bytes2PulseNumber ¶ added in v0.2.0
func Bytes2PulseNumber(buf []byte) PulseNumber
Bytes2PulseNumber deserialize pulse number.
func CalculatePulseNumber ¶ added in v0.4.0
func CalculatePulseNumber(now time.Time) PulseNumber
CalculatePulseNumber is helper for calculating next pulse number, when a network is being started
func (PulseNumber) Bytes ¶ added in v0.2.0
func (pn PulseNumber) Bytes() []byte
Bytes serializes pulse number.
type PulseSenderConfirmation ¶ added in v0.4.0
type PulseSenderConfirmation struct { PulseNumber PulseNumber ChosenPublicKey string Entropy Entropy Signature []byte }
PulseSenderConfirmation contains confirmations of the pulse from other pulsars Because the system is using BFT for consensus between pulsars, because of it All pulsar send to the chosen pulsar their confirmations Every node in the network can verify the signatures
type RecordID ¶ added in v0.4.0
type RecordID [RecordIDSize]byte
RecordID is a unified record ID.
func NewRecordID ¶ added in v0.6.2
func NewRecordID(pulse PulseNumber, hash []byte) *RecordID
NewRecordID generates RecordID byte representation.
func (*RecordID) Pulse ¶ added in v0.6.2
func (id *RecordID) Pulse() PulseNumber
Pulse returns byte slice of RecordID.
type RecordRef ¶
type RecordRef [RecordRefSize]byte
RecordRef is a unified record reference.
func GenRequest ¶ added in v0.5.0
func GenRequest(pn PulseNumber, payload []byte) *RecordRef
GenRequest calculates RecordRef for request message from pulse number and request's payload.
func NewRecordRef ¶ added in v0.6.2
NewRecordRef returns RecordRef composed from domain and record
func NewRefFromBase58 ¶ added in v0.2.0
NewRefFromBase58 deserializes reference from base58 encoded string.
type RefIterator ¶ added in v0.0.6
RefIterator is used for iteration over affined children(parts) of container.
type RemoteProcedure ¶
RemoteProcedure is remote procedure call function.
type Reply ¶ added in v0.4.0
type Reply interface { // Type returns message type. Type() ReplyType }
Reply for an `Message`