From 421749f90a18b04cb6b9ffceece0c99c7a2a44c3 Mon Sep 17 00:00:00 2001
From: Janos Guljas <janos@resenje.org>
Date: Thu, 31 Jan 2019 15:03:47 +0100
Subject: [PATCH] cmd/swarm/global-store: add comments

---
 cmd/swarm/global-store/global_store.go      |  7 ++++++
 cmd/swarm/global-store/global_store_test.go | 24 +++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/cmd/swarm/global-store/global_store.go b/cmd/swarm/global-store/global_store.go
index 9d763d5762..a44ab22ed6 100644
--- a/cmd/swarm/global-store/global_store.go
+++ b/cmd/swarm/global-store/global_store.go
@@ -29,6 +29,8 @@ import (
 	cli "gopkg.in/urfave/cli.v1"
 )
 
+// startHTTP starts a global store with HTTP RPC server.
+// It is used for "http" cli command.
 func startHTTP(ctx *cli.Context) (err error) {
 	server, cleanup, err := newServer(ctx)
 	if err != nil {
@@ -45,6 +47,8 @@ func startHTTP(ctx *cli.Context) (err error) {
 	return http.Serve(listener, server)
 }
 
+// startWS starts a global store with WebSocket RPC server.
+// It is used for "websocket" cli command.
 func startWS(ctx *cli.Context) (err error) {
 	server, cleanup, err := newServer(ctx)
 	if err != nil {
@@ -62,6 +66,8 @@ func startWS(ctx *cli.Context) (err error) {
 	return http.Serve(listener, server.WebsocketHandler(origins))
 }
 
+// newServer creates a global store and returns its RPC server.
+// Returned cleanup function should be called only if err is nil.
 func newServer(ctx *cli.Context) (server *rpc.Server, cleanup func(), err error) {
 	log.PrintOrigins(true)
 	log.Root().SetHandler(log.LvlFilterHandler(log.Lvl(ctx.Int("verbosity")), log.StreamHandler(os.Stdout, log.TerminalFormat(true))))
@@ -86,6 +92,7 @@ func newServer(ctx *cli.Context) (server *rpc.Server, cleanup func(), err error)
 
 	server = rpc.NewServer()
 	if err := server.RegisterName("mockStore", globalStore); err != nil {
+		cleanup()
 		return nil, nil, err
 	}
 
diff --git a/cmd/swarm/global-store/global_store_test.go b/cmd/swarm/global-store/global_store_test.go
index 9a71739b29..c0589c618b 100644
--- a/cmd/swarm/global-store/global_store_test.go
+++ b/cmd/swarm/global-store/global_store_test.go
@@ -30,10 +30,14 @@ import (
 	mockRPC "github.com/ethereum/go-ethereum/swarm/storage/mock/rpc"
 )
 
+// TestHTTP_InMemory tests in-memory global store that exposes
+// HTTP server.
 func TestHTTP_InMemory(t *testing.T) {
 	testHTTP(t, true)
 }
 
+// TestHTTP_Database tests global store with persisted database
+// that exposes HTTP server.
 func TestHTTP_Database(t *testing.T) {
 	dir, err := ioutil.TempDir("", "swarm-global-store-")
 	if err != nil {
@@ -41,11 +45,18 @@ func TestHTTP_Database(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
+	// create a fresh global store
 	testHTTP(t, true, "--dir", dir)
 
+	// check if data saved by the previous global store instance
 	testHTTP(t, false, "--dir", dir)
 }
 
+// testWebsocket starts global store binary with HTTP server
+// and validates that it can store and retrieve data.
+// If put is false, no data will be stored, only retrieved,
+// giving the possibility to check if data is present in the
+// storage directory.
 func testHTTP(t *testing.T, put bool, args ...string) {
 	addr := findFreeTCPAddress(t)
 	testCmd := runGlobalStore(t, append([]string{"http", "--addr", addr}, args...)...)
@@ -94,10 +105,14 @@ func testHTTP(t *testing.T, put bool, args ...string) {
 	}
 }
 
+// TestWebsocket_InMemory tests in-memory global store that exposes
+// WebSocket server.
 func TestWebsocket_InMemory(t *testing.T) {
 	testWebsocket(t, true)
 }
 
+// TestWebsocket_Database tests global store with persisted database
+// that exposes HTTP server.
 func TestWebsocket_Database(t *testing.T) {
 	dir, err := ioutil.TempDir("", "swarm-global-store-")
 	if err != nil {
@@ -105,11 +120,18 @@ func TestWebsocket_Database(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
+	// create a fresh global store
 	testWebsocket(t, true, "--dir", dir)
 
+	// check if data saved by the previous global store instance
 	testWebsocket(t, false, "--dir", dir)
 }
 
+// testWebsocket starts global store binary with WebSocket server
+// and validates that it can store and retrieve data.
+// If put is false, no data will be stored, only retrieved,
+// giving the possibility to check if data is present in the
+// storage directory.
 func testWebsocket(t *testing.T, put bool, args ...string) {
 	addr := findFreeTCPAddress(t)
 	testCmd := runGlobalStore(t, append([]string{"ws", "--addr", addr}, args...)...)
@@ -154,6 +176,8 @@ func testWebsocket(t *testing.T, put bool, args ...string) {
 	}
 }
 
+// findFreeTCPAddress returns a local address (IP:Port) to which
+// global store can listen on.
 func findFreeTCPAddress(t *testing.T) (addr string) {
 	t.Helper()