add missing comments

sxmpp · Jan 8, 2020 · 842d224 · 842d224
1 parent e2c8619
commit 842d224
Show file tree

Hide file tree

Showing 25 changed files with 54 additions and 34 deletions.
diff --git a/model/serializer/serializer.go b/model/serializer/serializer.go
@@ -26,7 +26,7 @@ type Deserializer interface {
 	FromBytes(buf *bytes.Buffer) error
 }
 
-// Serialize converts an slice of Serializer elements into its bytes representation.
+// SerializeSlice converts an slice of Serializer elements into its bytes representation.
 func SerializeSlice(slice interface{}) ([]byte, error) {
 	t := reflect.TypeOf(slice).Elem()
 	if t.Kind() != reflect.Slice {
@@ -58,7 +58,7 @@ func SerializeSlice(slice interface{}) ([]byte, error) {
 	return res, nil
 }
 
-// Deserialize reads an entity slice of Deserilizer elements from its bytes representation.
+// DeserializeSlice reads an entity slice of Deserilizer elements from its bytes representation.
 func DeserializeSlice(b []byte, slice interface{}) error {
 	t := reflect.TypeOf(slice).Elem()
 	if t.Kind() != reflect.Slice {

diff --git a/module/roster/presencehub/presencehub.go b/module/roster/presencehub/presencehub.go
@@ -51,7 +51,7 @@ func New(router *router.Router, capsRep repository.Capabilities) *PresenceHub {
 }
 
 // RegisterPresence keeps track of a new client presence, requesting capabilities when necessary.
-func (x *PresenceHub) RegisterPresence(ctx context.Context, presence *xmpp.Presence) (err error, alreadyRegistered bool) {
+func (x *PresenceHub) RegisterPresence(ctx context.Context, presence *xmpp.Presence) (alreadyRegistered bool, err error) {
 	fromJID := presence.FromJID()
 
 	// check if caps were previously cached
@@ -61,7 +61,7 @@ func (x *PresenceHub) RegisterPresence(ctx context.Context, presence *xmpp.Prese
 		if !ok {
 			caps, err := x.capsRep.FetchCapabilities(ctx, c.Node, c.Ver) // try fetching from disk
 			if err != nil {
-				return err, false
+				return false, err
 			}
 			if caps == nil {
 				x.requestCapabilities(ctx, c.Node, c.Ver, fromJID) // request capabilities
@@ -72,7 +72,7 @@ func (x *PresenceHub) RegisterPresence(ctx context.Context, presence *xmpp.Prese
 	}
 	// store available presence
 	_, loaded := x.availablePresences.LoadOrStore(fromJID, presence)
-	return nil, loaded
+	return loaded, nil
 }
 
 // UnregisterPresence removes a presence from the hub.

diff --git a/module/roster/roster.go b/module/roster/roster.go
@@ -599,7 +599,11 @@ func (x *Roster) processAvailablePresence(ctx context.Context, presence *xmpp.Pr
 		log.Infof("processing 'available' - user: %s", fromJID)
 
 		// register presence
-		if _, alreadyRegistered := x.presenceHub.RegisterPresence(ctx, presence); !alreadyRegistered && replyOnBehalf {
+		alreadyRegistered, err := x.presenceHub.RegisterPresence(ctx, presence)
+		if err != nil {
+			return err
+		}
+		if !alreadyRegistered && replyOnBehalf {
 			if err := x.deliverRosterPresences(ctx, userJID); err != nil {
 				return err
 			}

diff --git a/module/xep0004/field.go b/module/xep0004/field.go
@@ -11,6 +11,7 @@ import (
 	"github.com/ortuman/jackal/xmpp"
 )
 
+// FormType represents form type constant value.
 const FormType = "FORM_TYPE"
 
 const (

diff --git a/module/xep0004/form.go b/module/xep0004/form.go
@@ -11,6 +11,7 @@ import (
 	"github.com/ortuman/jackal/xmpp"
 )
 
+// FormNamespace specifies XEP-0004 namespace constant value.
 const FormNamespace = "jabber:x:data"
 
 const (
@@ -38,8 +39,7 @@ type DataForm struct {
 	Items        []Fields
 }
 
-// NewFormFromElement returns a new data form entity reading it
-// from it's XMPP representation.
+// NewFormFromElement returns a new data form entity reading it from it's XMPP representation.
 func NewFormFromElement(elem xmpp.XElement) (*DataForm, error) {
 	if n := elem.Name(); n != "x" {
 		return nil, fmt.Errorf("invalid form name: %s", n)

diff --git a/router/router.go b/router/router.go
@@ -211,10 +211,10 @@ func (r *Router) Unbind(ctx context.Context, stmJID *jid.JID) {
 	}
 }
 
-// UserStreams returns the stream associated to a user jid.
+// UserStream returns the stream associated to a user jid.
 func (r *Router) UserStream(j *jid.JID) stream.C2S {
-	r.mu.Lock()
-	defer r.mu.Unlock()
+	r.mu.RLock()
+	defer r.mu.RUnlock()
 
 	streams := r.streams[j.Node()]
 	for _, stm := range streams {
@@ -227,8 +227,8 @@ func (r *Router) UserStream(j *jid.JID) stream.C2S {
 
 // UserStreams returns all streams associated to a user.
 func (r *Router) UserStreams(username string) []stream.C2S {
-	r.mu.Lock()
-	defer r.mu.Unlock()
+	r.mu.RLock()
+	defer r.mu.RUnlock()
 	return r.streams[username]
 }
 

diff --git a/storage/badgerdb/badgerdb.go b/storage/badgerdb/badgerdb.go
@@ -27,6 +27,7 @@ type badgerDBContainer struct {
 	db *badger.DB
 }
 
+// New initializes BadgerDB storage and returns associated container.
 func New(cfg *Config) (repository.Container, error) {
 	var c badgerDBContainer
 

diff --git a/storage/badgerdb/block_list_test.go b/storage/badgerdb/block_list_test.go
@@ -52,7 +52,7 @@ func TestBadgerDB_BlockListItems(t *testing.T) {
 
 func newBlockListMock() (*badgerDBBlockList, func()) {
 	t := newT()
-	return &badgerDBBlockList{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBBlockList{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/capabilities_test.go b/storage/badgerdb/capabilities_test.go
@@ -36,7 +36,7 @@ func TestBadgerDB_Capabilities(t *testing.T) {
 
 func newCapabilitiesMock() (*badgerDBCapabilities, func()) {
 	t := newT()
-	return &badgerDBCapabilities{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBCapabilities{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/offline_test.go b/storage/badgerdb/offline_test.go
@@ -53,7 +53,7 @@ func TestBadgerDB_OfflineMessages(t *testing.T) {
 
 func newOfflineMock() (*badgerDBOffline, func()) {
 	t := newT()
-	return &badgerDBOffline{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBOffline{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/private_test.go b/storage/badgerdb/private_test.go
@@ -35,7 +35,7 @@ func TestBadgerDB_PrivateXML(t *testing.T) {
 
 func newPrivateMock() (*badgerDBPrivate, func()) {
 	t := newT()
-	return &badgerDBPrivate{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBPrivate{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/pubsub_test.go b/storage/badgerdb/pubsub_test.go
@@ -200,7 +200,7 @@ func TestBadgerDB_PubSubSubscriptions(t *testing.T) {
 
 func newPubSubMock() (*badgerDBPubSub, func()) {
 	t := newT()
-	return &badgerDBPubSub{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBPubSub{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/roster_test.go b/storage/badgerdb/roster_test.go
@@ -134,7 +134,7 @@ func TestBadgerDB_RosterNotifications(t *testing.T) {
 
 func newRosterMock() (*badgerDBRoster, func()) {
 	t := newT()
-	return &badgerDBRoster{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBRoster{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/testutil.go → storage/badgerdb/testutil_test.go b/storage/badgerdb/testutil.go → storage/badgerdb/testutil_test.go
@@ -15,15 +15,14 @@ import (
 	"github.com/google/uuid"
 )
 
-type T struct {
-	// DB provides the various functions required to interact with Badger.
-	DB *badger.DB
+type bgDBT struct {
+	db *badger.DB
 
 	dataDir string
 }
 
-func newT() *T {
-	t := &T{}
+func newT() *bgDBT {
+	t := &bgDBT{}
 	dir, _ := ioutil.TempDir("", "")
 	t.dataDir = dir + "/com.jackal.tests.badgerdb." + uuid.New().String()
 
@@ -37,11 +36,11 @@ func newT() *T {
 		_, _ = fmt.Fprintf(os.Stderr, "%v", err)
 		os.Exit(1)
 	}
-	t.DB = db
+	t.db = db
 	return t
 }
 
-func (t *T) teardown() {
-	_ = t.DB.Close()
+func (t *bgDBT) teardown() {
+	_ = t.db.Close()
 	_ = os.RemoveAll(t.dataDir)
 }
diff --git a/storage/badgerdb/user_test.go b/storage/badgerdb/user_test.go
@@ -47,7 +47,7 @@ func TestBadgerDB_User(t *testing.T) {
 
 func newUserMock() (*badgerDBUser, func()) {
 	t := newT()
-	return &badgerDBUser{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBUser{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/badgerdb/vcard_test.go b/storage/badgerdb/vcard_test.go
@@ -40,7 +40,7 @@ func TestBadgerDB_VCard(t *testing.T) {
 
 func newVCardMock() (*badgerDBVCard, func()) {
 	t := newT()
-	return &badgerDBVCard{badgerDBStorage: newStorage(t.DB)}, func() {
+	return &badgerDBVCard{badgerDBStorage: newStorage(t.db)}, func() {
 		t.teardown()
 	}
 }
diff --git a/storage/memory/block_list.go b/storage/memory/block_list.go
@@ -17,10 +17,12 @@ type BlockList struct {
 	*memoryStorage
 }
 
+// NewBlockList returns an instance of BlockList in-memory storage.
 func NewBlockList() *BlockList {
 	return &BlockList{memoryStorage: newStorage()}
 }
 
+// InsertBlockListItem inserts a block list item entity into storage if not previously inserted.
 func (m *BlockList) InsertBlockListItem(_ context.Context, item *model.BlockListItem) error {
 	return m.updateInWriteLock(blockListItemKey(item.Username), func(b []byte) ([]byte, error) {
 		var items []model.BlockListItem
@@ -44,6 +46,7 @@ func (m *BlockList) InsertBlockListItem(_ context.Context, item *model.BlockList
 	})
 }
 
+// DeleteBlockListItem deletes a block list item entity from storage.
 func (m *BlockList) DeleteBlockListItem(_ context.Context, item *model.BlockListItem) error {
 	return m.updateInWriteLock(blockListItemKey(item.Username), func(b []byte) ([]byte, error) {
 		var items []model.BlockListItem
@@ -67,6 +70,7 @@ func (m *BlockList) DeleteBlockListItem(_ context.Context, item *model.BlockList
 	})
 }
 
+// FetchBlockListItems retrieves from storage all block list item entities associated to a given user.
 func (m *BlockList) FetchBlockListItems(_ context.Context, username string) ([]model.BlockListItem, error) {
 	var items []model.BlockListItem
 	_, err := m.getEntities(blockListItemKey(username), &items)

diff --git a/storage/memory/memory.go b/storage/memory/memory.go
@@ -22,6 +22,7 @@ type memoryContainer struct {
 	offline   *Offline
 }
 
+// New initializes in-memory storage and returns associated container.
 func New() (repository.Container, error) {
 	var c memoryContainer
 

diff --git a/storage/memory/pubsub.go b/storage/memory/pubsub.go
@@ -68,7 +68,7 @@ func (m *PubSub) UpsertNode(_ context.Context, node *pubsubmodel.Node) error {
 	})
 }
 
-// FetchNode retrieves from storage a pubsub node entity.
+// FetchNodes retrieves from storage all node entities associated with a host.
 func (m *PubSub) FetchNodes(_ context.Context, host string) ([]pubsubmodel.Node, error) {
 	var b []byte
 	if err := m.inReadLock(func() error {
@@ -88,7 +88,7 @@ func (m *PubSub) FetchNodes(_ context.Context, host string) ([]pubsubmodel.Node,
 	return nodes, nil
 }
 
-// FetchNodes retrieves from storage all node entities associated with a host.
+// FetchNode retrieves from storage a pubsub node entity.
 func (m *PubSub) FetchNode(_ context.Context, host, name string) (*pubsubmodel.Node, error) {
 	var b []byte
 	if err := m.inReadLock(func() error {

diff --git a/storage/mysql/mysql.go b/storage/mysql/mysql.go
@@ -30,6 +30,7 @@ type mySQLContainer struct {
 	doneCh chan chan bool
 }
 
+// New initializes MySQL storage and returns associated container.
 func New(cfg *Config) (repository.Container, error) {
 	var err error
 	c := &mySQLContainer{doneCh: make(chan chan bool, 1)}

diff --git a/storage/pgsql/pgsql.go b/storage/pgsql/pgsql.go
@@ -38,6 +38,7 @@ type pgSQLContainer struct {
 	doneCh     chan chan bool
 }
 
+// New initializes PgSQL storage and returns associated container.
 func New(cfg *Config) (repository.Container, error) {
 	c := &pgSQLContainer{doneCh: make(chan chan bool, 1)}
 

diff --git a/storage/repository/block_list.go b/storage/repository/block_list.go
@@ -19,7 +19,6 @@ type BlockList interface {
 	// DeleteBlockListItem deletes a block list item entity from storage.
 	DeleteBlockListItem(ctx context.Context, item *model.BlockListItem) error
 
-	// FetchBlockListItems retrieves from storage all block list item entities
-	// associated to a given user.
+	// FetchBlockListItems retrieves from storage all block list item entities associated to a given user.
 	FetchBlockListItems(ctx context.Context, username string) ([]model.BlockListItem, error)
 }
diff --git a/util/runqueue/mpsc/mpsc.go b/util/runqueue/mpsc/mpsc.go
@@ -17,12 +17,14 @@ type node struct {
 	val  interface{}
 }
 
+// Queue represents a lock-free MPSC queue.
 type Queue struct {
 	head *node
 	tail *node
 	stub node
 }
 
+// New returns an empty Queue.
 func New() *Queue {
 	q := &Queue{}
 	q.head = &q.stub

diff --git a/util/runqueue/runqueue.go b/util/runqueue/runqueue.go
@@ -18,6 +18,7 @@ const (
 	running
 )
 
+// RunQueue represents a lock-free operation queue.
 type RunQueue struct {
 	name         string
 	queue        *mpsc.Queue
@@ -29,13 +30,15 @@ type RunQueue struct {
 type funcMessage struct{ fn func() }
 type stopMessage struct{ stopCb func() }
 
+// New returns an initialized lock-free operation queue.
 func New(name string) *RunQueue {
 	return &RunQueue{
 		name:  name,
 		queue: mpsc.New(),
 	}
 }
 
+// Run pushes a new operation function into the queue.
 func (m *RunQueue) Run(fn func()) {
 	if atomic.LoadInt32(&m.stopped) == 1 {
 		return
@@ -45,6 +48,10 @@ func (m *RunQueue) Run(fn func()) {
 	m.schedule()
 }
 
+// Stop signals the queue to stop running.
+//
+// Callback function represented by 'stopCb' its guaranteed to be immediately executed only if no job has been
+// previously scheduled.
 func (m *RunQueue) Stop(stopCb func()) {
 	if atomic.CompareAndSwapInt32(&m.stopped, 0, 1) {
 		if atomic.LoadInt32(&m.messageCount) > 0 {

diff --git a/xmpp/jid/jid.go b/xmpp/jid/jid.go
@@ -120,7 +120,7 @@ func NewFromBytes(buf *bytes.Buffer) (*JID, error) {
 	return &j, nil
 }
 
-// node returns the node, or empty string if this JID does not contain node information.
+// Node returns the node, or empty string if this JID does not contain node information.
 func (j *JID) Node() string {
 	return j.node
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,6 +11,7 @@ import ( @@
     	"github.com/ortuman/jackal/xmpp"
     )
+    // FormType represents form type constant value.
     const FormType = "FORM_TYPE"
     const (
@@ Expand Down @@