Added comments to bark server

cmd/server/main.go

@@ -31,21 +31,38 @@ func Init() string {
 func main() {
 	address := Init()
 	r := router.New()
+
+	// The index endpoint displays information about the bark server.
 	r.GET("/", controllers.IndexController)
+
+	// This is a demo endpoint to ensure bark server is running which will print Hello, `name`!.
 	r.GET("/hello/{name}", Hello)
+
+	// Bark client contains the logic which decides which out of the two (single/multiple) insertion endpoints is called.
+	// This endpoint sends single log entry at a time to the DB.
 	r.POST("/insertSingle", controllers.SendSingleToChannel)
+	// This endpoint handles the batch insertion of logs to the DB.
 	r.POST("/insertMultiple", controllers.SendMultipleToChannel)
+
+	// This endpoint is responsible to initiate server shut down, following which Bark server will not process any new incoming requests.
+	// It will, however, shut down after it has completely sent all the logs received up till that point of time.
 	r.POST("/shutdownServiceAsap", controllers.ShutdownService)
+
+	//InitDB attempts to make a connection to the postgres DB instance using the environment variable value set for `BARK_DATABASE_URL`.
 	err := resources.InitDb()
 	if err != nil {
 		log.Fatal("E#1KDZRP - " + err.Error())
 	}
 	bld := models.NewBarkLogDao()
+
+	// Sends a single log entry to the postgres DB stating Bark server has started successfully.
+	// Returns an error and halts the server boot up in case the connection acquired to the postgres DB is not proper.
 	err = bld.InsertServerStartedLog()
 	if err != nil {
 		log.Fatal("P#1LQ2YQ - Bark server start failed: " + err.Error())
 	}
 
+	// Go routine which writes logs received in the LogChannel to DB.
 	go dbLogWriter.StartWritingLogs()
 	log.Fatal(fasthttp.ListenAndServe(address, r.Handler))
 

controllers/log_ingestion_controller.go

@@ -10,6 +10,11 @@ import (
 	"github.com/techrail/bark/services/ingestion"
 )
 
+// SendSingleToChannel is tasked with handling all the single log insertion requests.
+// It will simply send a response code 503 (service unavailable) if server shut down has already been requested.
+// Response code 400 will be returned in case request body is empty.
+// It will unmarshal the request body and compare the structure with structure of BarkLog struct.
+// Finally, it will spawn a go routine to send the log to LogChannel and will respond with 200 to the client.
 func SendSingleToChannel(ctx *fasthttp.RequestCtx) {
 	if appRuntime.ShutdownRequested.Load() == true {
 		ctx.SetStatusCode(fasthttp.StatusServiceUnavailable)
@@ -32,6 +37,11 @@ func SendSingleToChannel(ctx *fasthttp.RequestCtx) {
 	ctx.SetStatusCode(fasthttp.StatusOK)
 }
 
+// SendMultipleToChannel is tasked with handling all the multiple log insertion requests.
+// It will simply send a response code 503 (service unavailable) if server shut down has already been requested.
+// Response code 400 will be returned in case request body is empty.
+// It will unmarshal the request body and compare the structure with structure of BarkLog struct slice.
+// Finally, it will spawn a go routine to send the logs to LogChannel and will respond with 200 to the client.
 func SendMultipleToChannel(ctx *fasthttp.RequestCtx) {
 	if appRuntime.ShutdownRequested.Load() == true {
 		ctx.SetStatusCode(fasthttp.StatusServiceUnavailable)
@@ -54,6 +64,7 @@ func SendMultipleToChannel(ctx *fasthttp.RequestCtx) {
 	ctx.SetStatusCode(fasthttp.StatusOK)
 }
 
+// ShutdownService will set the value of global variable `ShutdownRequested` to true.
 func ShutdownService(ctx *fasthttp.RequestCtx) {
 	appRuntime.ShutdownRequested.Store(true)
 }

models/barklog.go

@@ -26,6 +26,8 @@ type BarkLog struct {
 	MoreData    jsonObject.Typ `db:"more_data" json:"moreData"`
 }
 
+// ValidateForInsert checks for missing values in the incoming BarkLog's fields.
+// In case a missing value is encountered, a default value is assigned to it.
 func (b BarkLog) ValidateForInsert() (BarkLog, error) {
 	if b.LogTime.IsZero() {
 		b.LogTime = time.Now().UTC()
@@ -96,6 +98,8 @@ func (bld *BarkLogDao) Insert(l BarkLog) error {
 	return nil
 }
 
+// InsertServerStartedLog inserts a log entry in the postgres DB stating that bark server has started successfully.
+// This acts as a checkpoint that everything is working as expected in the DB connection department.
 func (bld *BarkLogDao) InsertServerStartedLog() error {
 	return bld.Insert(BarkLog{
 		LogTime:     time.Now().UTC(),
@@ -108,6 +112,7 @@ func (bld *BarkLogDao) InsertServerStartedLog() error {
 	})
 }
 
+// InsertBatch sends a batch of logs to the DB.
 func (bld *BarkLogDao) InsertBatch(l []BarkLog) error {
 	batchOfBarkLog := [][]any{}
 	for i := 0; i < len(l); i++ {

resources/db.go

@@ -15,6 +15,7 @@ type BarkPostgresDb struct {
 
 var BarkDb *BarkPostgresDb
 
+// InitDb : InitDB returns error (if any) encountered while trying to establish a connection to the postgres DB instance.
 func InitDb() error {
 	// Connect to Postgres DB instance
 	var err error
@@ -27,6 +28,8 @@ func InitDb() error {
 	return nil
 }
 
+// OpenDb : OpenDB returns a pointer to the `BarkPostgresDb` object.
+// BarkPostgresDb struct wraps a pointer to pgx connection pool object.
 func OpenDb() (*BarkPostgresDb, error) {
 	connPool, err := pgxpool.NewWithConfig(context.Background(), Config())
 	if err != nil {
@@ -36,6 +39,7 @@ func OpenDb() (*BarkPostgresDb, error) {
 	return &BarkPostgresDb{Client: connPool}, nil
 }
 
+// CloseDb closes the connection to the DB.
 func (d *BarkPostgresDb) CloseDb() {
 	d.Client.Close()
 }

resources/dbPoolConfig.go

@@ -13,6 +13,10 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 )
 
+// Config retrieves the postgres DB connection url from environment variable named `BARK_DATABASE_URL`.
+// It then parses the connection url and checks for empty and invalid urls, if found, it logs the error and connection is not made.
+// If it passes the checks, the connection is established and function returns object of pgxpool config.
+
 func Config() *pgxpool.Config {
 	const defaultMaxConns = int32(20)
 	const defaultMinConns = int32(5)

services/dbLogWriter/db_log_writer.go

@@ -17,6 +17,9 @@ func init() {
 }
 
 // StartWritingLogs is a go routine to check channel length and commit to DB
+// The routine decides whether a batch or single insert DB call of the logs is needed to be made.
+// Further bifurcation of the batch sizes is done based on the incoming traffic and LogChannel capacity.
+// If appRuntime.ShutdownRequested is set to true, the routine will send a batch of all the remaining logs in the LogChannel to the DB.
 func StartWritingLogs() {
 	logChannelLength := 0
 	for {

services/ingestion/read_from_channel.go

@@ -8,6 +8,9 @@ import (
 	"github.com/techrail/bark/models"
 )
 
+// InsertSingle and InsertMultiple functions have a common functionality - pushing the logs into the LogChannel.
+// The channel capacities are checked beforehand. In case, the channels are full, that message is conveyed.
+// Each log entry's values are validated and then sent to the LogChannel.
 func InsertSingle(logEntry models.BarkLog) {
 	if len(channels.LogChannel) > constants.ServerLogInsertionChannelCapacity-1 {
 		fmt.Printf("E#1KDY0O - Channel is full. Cannot push. Log received: | %v\n", logEntry)