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