From 0c7763ba99cc63e16e4efc3fc2cd03a28eed1295 Mon Sep 17 00:00:00 2001 From: Benjamin Wenger <ben@elixxir.ioo> Date: Mon, 29 Aug 2022 13:45:26 -0700 Subject: [PATCH] finished docs --- channels/adminListener.go | 2 ++ channels/eventModel.go | 5 ++++- channels/interface.go | 45 +++++++++++++++++++++++++++++++++++++-- channels/nameService.go | 3 ++- channels/send.go | 8 +++---- channels/userListener.go | 2 ++ 6 files changed, 57 insertions(+), 8 deletions(-) diff --git a/channels/adminListener.go b/channels/adminListener.go index c19e8fadc..8a4d5cabd 100644 --- a/channels/adminListener.go +++ b/channels/adminListener.go @@ -10,6 +10,8 @@ import ( "gitlab.com/xx_network/primitives/id" ) +// the adminListener adheres to the broadcast listener interface and is used +// when admin messages are received on the channel type adminListener struct { name NameService events *events diff --git a/channels/eventModel.go b/channels/eventModel.go index 7b49b3bd5..6aa889e3a 100644 --- a/channels/eventModel.go +++ b/channels/eventModel.go @@ -204,7 +204,10 @@ func (e *events) receiveTextMessage(ChannelID *id.ID, // receiveReaction is the internal function which handles the reception of // Reactions. -// It does edge chaling +// It does edge checking to ensure the received reaction is just a single emoji. +// If the received reaction is not, the reaction is dropped. +// If the messageID for the message the reaction is to is malformed, the reaction +// is dropped. func (e *events) receiveReaction(ChannelID *id.ID, MessageID cryptoChannel.MessageID, messageType MessageType, SenderUsername string, Content []byte, timestamp time.Time, diff --git a/channels/interface.go b/channels/interface.go index f3a62ca7a..ee5f385ae 100644 --- a/channels/interface.go +++ b/channels/interface.go @@ -13,21 +13,62 @@ import ( var ValidForever = time.Duration(math.MaxInt64) type Manager interface { + // SendGeneric is used to send a raw message over a channel. In general, it + // should be wrapped in a function which defines the wire protocol + // If the final message, before being sent over the wire, is too long, this will + // return an error. Due to the underlying encoding using compression, it isn't + // possible to define the largest payload that can be sent, but + // it will always be possible to send a payload of 802 bytes at minimum + // Them meaning of validUntil depends on the use case. SendGeneric(channelID *id.ID, messageType MessageType, msg []byte, validUntil time.Duration, params cmix.CMIXParams) ( cryptoChannel.MessageID, id.Round, ephemeral.Id, error) + + // SendAdminGeneric is used to send a raw message over a channel encrypted + // with admin keys, identifying it as sent by the admin. In general, it + // should be wrapped in a function which defines the wire protocol + // If the final message, before being sent over the wire, is too long, this will + // return an error. The message must be at most 510 bytes long. SendAdminGeneric(privKey *rsa.PrivateKey, channelID *id.ID, msg []byte, validUntil time.Duration, messageType MessageType, params cmix.CMIXParams) (cryptoChannel.MessageID, id.Round, ephemeral.Id, error) + // SendMessage is used to send a formatted message over a channel. + // Due to the underlying encoding using compression, it isn't + // possible to define the largest payload that can be sent, but + // it will always be possible to send a payload of 798 bytes at minimum + // The message will auto delete validUntil after the round it is sent in, + // lasting forever if ValidForever is used SendMessage(channelID *id.ID, msg string, validUntil time.Duration, params cmix.CMIXParams) ( cryptoChannel.MessageID, id.Round, ephemeral.Id, error) + + // SendReply is used to send a formatted message over a channel. + // Due to the underlying encoding using compression, it isn't + // possible to define the largest payload that can be sent, but + // it will always be possible to send a payload of 766 bytes at minimum. + // If the message ID the reply is sent to doesnt exist, the other side will + // post the message as a normal message and not a reply. + // The message will auto delete validUntil after the round it is sent in, + // lasting forever if ValidForever is used SendReply(channelID *id.ID, msg string, replyTo cryptoChannel.MessageID, validUntil time.Duration, params cmix.CMIXParams) ( cryptoChannel.MessageID, id.Round, ephemeral.Id, error) + + // SendReaction is used to send a reaction to a message over a channel. + // The reaction must be a single emoji with no other characters, and will + // be rejected otherwise. + // Clients will drop the reaction if they do not recognize the reactTo message SendReaction(channelID *id.ID, reaction string, reactTo cryptoChannel.MessageID, - validUntil time.Duration, params cmix.CMIXParams) ( - cryptoChannel.MessageID, id.Round, ephemeral.Id, error) + params cmix.CMIXParams) (cryptoChannel.MessageID, id.Round, + ephemeral.Id, error) + + // RegisterReceiveHandler is used to register handlers for non default message + // types s they can be processed by modules. it is important that such modules + // sync up with the event model implementation. + // There can only be one handler per message type, and this will return an error + // on a multiple registration. + RegisterReceiveHandler(messageType MessageType, + listener MessageTypeReceiveMessage) error } diff --git a/channels/nameService.go b/channels/nameService.go index 9b772486c..4ac03eb0b 100644 --- a/channels/nameService.go +++ b/channels/nameService.go @@ -23,7 +23,8 @@ type NameService interface { // given message. SignChannelMessage(message []byte) (signature []byte, err error) - // ValidateChannelMessage + // ValidateChannelMessage validates that a received channel message's + // username lease is signed by the NameService ValidateChannelMessage(username string, lease time.Time, pubKey ed25519.PublicKey, authorIDSignature []byte) bool } diff --git a/channels/send.go b/channels/send.go index 636fe6633..aa8a25cf6 100644 --- a/channels/send.go +++ b/channels/send.go @@ -206,9 +206,8 @@ func (m *manager) SendReply(channelID *id.ID, msg string, // be rejected otherwise. // Clients will drop the reaction if they do not recognize the reactTo message func (m *manager) SendReaction(channelID *id.ID, reaction string, - reactTo cryptoChannel.MessageID, validUntil time.Duration, - params cmix.CMIXParams) (cryptoChannel.MessageID, id.Round, ephemeral.Id, - error) { + reactTo cryptoChannel.MessageID, params cmix.CMIXParams) ( + cryptoChannel.MessageID, id.Round, ephemeral.Id, error) { if err := ValidateReaction(reaction); err != nil { return cryptoChannel.MessageID{}, 0, ephemeral.Id{}, err @@ -225,5 +224,6 @@ func (m *manager) SendReaction(channelID *id.ID, reaction string, return cryptoChannel.MessageID{}, 0, ephemeral.Id{}, err } - return m.SendGeneric(channelID, Reaction, reactMarshaled, validUntil, params) + return m.SendGeneric(channelID, Reaction, reactMarshaled, ValidForever, + params) } diff --git a/channels/userListener.go b/channels/userListener.go index 20a3eb149..d81c54857 100644 --- a/channels/userListener.go +++ b/channels/userListener.go @@ -11,6 +11,8 @@ import ( "time" ) +// the userListener adheres to the broadcast listener interface and is used +// when user messages are received on the channel type userListener struct { name NameService events *events -- GitLab