fix: address review - add docstrings, deep stack test, log dropped notifications

- Add docstrings to all customError methods for coverage threshold
- Add TestStackDepthCappedDeep with recursive calls exceeding 64 frames
  to exercise the capping logic
- Log at debug level when async notifications are dropped due to
  semaphore capacity, aiding observability during sustained bursts

Author: ankurs

errors.go

@@ -54,37 +54,42 @@ type customError struct {
 	status       *grpcstatus.Status
 }
 
-// implements notifier.NotifyExt
+// ShouldNotify returns true if the error should be reported to notifiers.
 func (c *customError) ShouldNotify() bool {
 	return c.shouldNotify
 }
 
-// implements notifier.NotifyExt
+// Notified marks the error as having been notified (or not).
 func (c *customError) Notified(status bool) {
 	c.shouldNotify = !status
 }
 
-// implements error
+// Error returns the error message.
 func (c customError) Error() string {
 	return c.Msg
 }
 
+// Callers returns the program counters of the call stack when the error was created.
 func (c customError) Callers() []uintptr {
 	return c.stack[:]
 }
 
+// StackTrace returns the program counters of the call stack (alias for Callers).
 func (c customError) StackTrace() []uintptr {
 	return c.Callers()
 }
 
+// StackFrame returns the structured stack frames for the error.
 func (c customError) StackFrame() []StackFrame {
 	return c.frame
 }
 
+// Cause returns the root cause error that originated this error chain.
 func (c customError) Cause() error {
 	return c.cause
 }
 
+// GRPCStatus returns the gRPC status for this error.
 func (c customError) GRPCStatus() *grpcstatus.Status {
 	if c.status != nil {
 		// use latest error message and keep other data (e.g. details)
@@ -121,6 +126,7 @@ func (c *customError) generateStack(skip int) []StackFrame {
 	return stack
 }
 
+// Unwrap returns the immediate parent error for use with errors.Is and errors.As.
 func (c customError) Unwrap() error {
 	return c.wrapped
 }

errors_test.go

@@ -112,3 +112,22 @@ func TestStackDepthCapped(t *testing.T) {
 	}
 }
 
+func TestStackDepthCappedDeep(t *testing.T) {
+	var createDeepError func(depth int) ErrorExt
+	createDeepError = func(depth int) ErrorExt {
+		if depth == 0 {
+			return New("deep error")
+		}
+		return createDeepError(depth - 1)
+	}
+
+	// Create error from a stack deeper than 64
+	err := createDeepError(100)
+	if len(err.StackFrame()) > 64 {
+		t.Errorf("stack depth %d exceeds max 64", len(err.StackFrame()))
+	}
+	if len(err.StackFrame()) == 0 {
+		t.Error("stack should not be empty")
+	}
+}
+

notifier/notifier.go

@@ -65,6 +65,7 @@ func NotifyAsync(err error, rawData ...interface{}) error {
 		}(sem)
 	default:
 		// drop notification to prevent goroutine explosion
+		log.Debug(context.Background(), "msg", "async notification dropped due to capacity", "err", err)
 	}
 	return err
 }