finished docs

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

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,

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
 }

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
 }

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)
 }

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