Merge pull request #13 from majidgolshadi/doc

add docs

Author: majidgolshadi

cmd/server/main.go

@@ -66,6 +66,8 @@ func runServer() error {
 
 	logger.Info("telemetry initialized")
 
+	// Coordination DB is separate from the app DB so range reservation can be
+	// scaled or failed over independently from URL data storage.
 	coordinationDB, err := sql.NewDBFactory(newDBConfig(cfg.ServiceName, cfg.Coordination.DataStore)).CreateDB()
 	if err != nil {
 		return err
@@ -74,6 +76,8 @@ func runServer() error {
 	coordinationStorage := mysqlRepo.NewCoordinator(coordinationDB, logger.WithField("component", "coordinator"))
 	rangeMng := id.NewDataStoreRangeManager(cfg.Coordination.NodeID, cfg.Coordination.RangeSize, coordinationStorage)
 
+	// ID manager must claim a range before the server starts accepting traffic;
+	// 3s is enough for a healthy DB but short enough to fail fast on startup.
 	startupCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
 	defer cancel()
 
@@ -93,6 +97,7 @@ func runServer() error {
 	customerSrv := customer.NewService(customerRepo, logger.WithField("component", "customer_service"))
 
 	ogFetchTimeout := cfg.OpenGraph.FetchTimeoutSec
+	// A zero value means the field was omitted from config; fall back to a safe default.
 	if ogFetchTimeout <= 0 {
 		ogFetchTimeout = 10
 	}

internal/domain/range.go

@@ -1,5 +1,7 @@
 package domain
 
+// Range is a pre-allocated block of integer IDs assigned exclusively to one node,
+// avoiding per-request DB coordination for ID generation.
 type Range struct {
 	Start uint
 	End   uint

internal/id/generator_integer.go

@@ -2,6 +2,8 @@ package id
 
 import "sync"
 
+// IntegerIdGenerator is a simple monotonic counter.
+// Mutex is required because multiple goroutines may call NewID concurrently.
 type IntegerIdGenerator struct {
 	mux sync.Mutex
 	id  uint

internal/id/rangemanager_datastore.go

@@ -14,8 +14,12 @@ import (
 )
 
 const (
+	// reserveRangeMaxRetry: version mismatch means another node grabbed the range;
+	// retry a few times before giving up to handle burst contention.
 	reserveRangeMaxRetry = 3
 
+	// 200ms gives other nodes time to finish their transaction before we retry,
+	// reducing thundering-herd when many nodes start simultaneously.
 	reserveRangeWaitingTimeMillisecond = 200
 )
 
@@ -78,7 +82,7 @@ func (c *datastoreRangeManager) getNextIDRange(ctx context.Context) (domain.Rang
 
 		// TODO: log the error as warning
 
-		// wait and then retry
+		// version conflict: another node already claimed this range; backoff and retry
 		time.Sleep(reserveRangeWaitingTimeMillisecond * time.Millisecond)
 	}
 

internal/id/rangemanager_inmemory.go

@@ -16,6 +16,8 @@ func NewInMemoryRangeManager(startID uint) RangeManager {
 }
 
 func (c *inMemory) getCurrentRange(ctx context.Context) (domain.Range, error) {
+	// ^uint(0) is max uint — effectively unbounded, for single-node or test mode
+	// where DB coordination is not needed.
 	return domain.Range{
 		Start: c.startID,
 		End:   ^uint(0),

internal/infrastructure/errors/error.go

@@ -23,12 +23,16 @@ const (
 	NotURLOwnerErr = errorStr("not url owner")
 )
 
+// errorStr is a typed string constant so errors.Is() comparisons work without allocation
+// and cannot accidentally match unrelated string errors.
 type errorStr string
 
 func (err errorStr) Error() string {
 	return string(err)
 }
 
+// Is unwraps both pkg/errors and fmt.Errorf chains so callers can use errors.Is()
+// regardless of how the error was wrapped.
 func (err errorStr) Is(target error) bool {
 	targetError, ok := target.(errorStr)
 	if ok {

internal/infrastructure/sql/factory.go

@@ -41,6 +41,7 @@ func (f *DBFactory) CreateDB() (*sqlx.DB, error) {
 	}
 
 	db.SetMaxOpenConns(f.config.MaxOpenConns)
+	// ConnMaxLifetime prevents stale connections after MySQL's wait_timeout drops idle ones.
 	db.SetConnMaxLifetime(f.config.ConnMaxLifetime)
 
 	return db, nil

internal/infrastructure/telemetry/telemetry.go

@@ -116,6 +116,7 @@ func initTracerProvider(ctx context.Context, cfg Config, res *resource.Resource)
 		opts := []otlptracehttp.Option{
 			otlptracehttp.WithEndpoint(cfg.OTLPEndpoint),
 		}
+		// TLS is skipped only in development; staging/production must use a secure collector.
 		if cfg.Environment == "development" {
 			opts = append(opts, otlptracehttp.WithInsecure())
 		}
@@ -145,6 +146,7 @@ func initMeterProvider(ctx context.Context, cfg Config, res *resource.Resource)
 		opts := []otlpmetrichttp.Option{
 			otlpmetrichttp.WithEndpoint(cfg.OTLPEndpoint),
 		}
+		// TLS is skipped only in development; staging/production must use a secure collector.
 		if cfg.Environment == "development" {
 			opts = append(opts, otlpmetrichttp.WithInsecure())
 		}

internal/opengraph/fetcher.go

@@ -57,7 +57,7 @@ func (f *Fetcher) FetchOgHTML(ctx context.Context, targetURL string) string {
 		return ""
 	}
 
-	// Limit reading to 1MB to avoid excessive memory usage
+	// OG tags live in <head>, so 1MB is sufficient; reading the full body would waste memory.
 	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
 	if err != nil {
 		return ""
@@ -139,7 +139,7 @@ func parseOgTags(htmlContent string) ogData {
 				}
 			}
 
-			// Stop parsing after </head> for efficiency
+			// OG meta tags must appear in <head>; stop at <body> to avoid scanning the full document.
 			if tagName == "body" {
 				if og.Title == "" && fallbackTitle != "" {
 					og.Title = fallbackTitle

internal/server/protocol/http/middleware/auth.go

@@ -12,7 +12,8 @@ import (
 // ContextKey is the type used for context keys in this package.
 type ContextKey string
 
-// TestCustomerContextKey is exported so tests in other packages can inject a customer into context.
+// TestCustomerContextKey is exported so integration tests can bypass DB lookup
+// by injecting a customer directly into the request context.
 const TestCustomerContextKey ContextKey = "customer"
 
 const customerContextKey = TestCustomerContextKey