refactor: improve error handling and domain architecture

- Refactor domain errors: unified error patterns across metadata, link, and bff services
- Add infrastructure DTOs for consistent MQ error handling with retry logic
- Improve MQ consumers: all errors go to DLQ, add raw event archiving
- Split CQRS handlers into separate files (handle_add, handle_update, handle_delete)
- Enhance Links collection: rename field to items, add nil-safety, return copies
- Extract parser use cases into separate files (get.go, set.go)
- Add WithDetail/WithTitle helpers to BFF error domain
- Fix error normalization: use domainerrors.Normalize consistently
- Update LinkBuilder to return domain errors instead of generic errors

Author: batazor

.cursor/rules/go-microservices.mdc

@@ -27,6 +27,7 @@ You are an expert in Go, microservices architecture, and clean backend developme
 
 - Write **short, focused functions** with a single responsibility.
 - Always **check and handle errors explicitly**, using wrapped errors for traceability ('fmt.Errorf("context: %w", err)').
+- **Never return function calls directly**—assign results (especially errors) to variables, handle them, and then return to keep control flow explicit.
 - Avoid **global state**; use constructor functions to inject dependencies.
 - Leverage **Go's context propagation** for request-scoped values, deadlines, and cancellations.
 - Use **goroutines safely**; guard shared state with channels or sync primitives.

.golangci.yml

@@ -10,18 +10,18 @@ linters:
   # Enable every linter, then prune the noisy ones
   default: all
   disable:
-    - importas        # noisy / incorrect results
-    - exhaustruct     # hard to use with current codebase
-    - godox           # incorrect results in our project
+    - exhaustruct # hard to use with current codebase
+    - godox # incorrect results in our project
     - depguard
     - gochecknoglobals
     - wsl # deprecated
+    - gomoddirectives # monorepo boundaries rely on replace directives
 
   exclusions:
     paths:
-      - "ops"                     # Ops manifests, etc.
-      - ".*mocks.+"              # Generated mocks
-      - "wire_gen.go"            # Wire‑generated
+      - "ops" # Ops manifests, etc.
+      - ".*mocks.+" # Generated mocks
+      - "wire_gen.go" # Wire‑generated
     rules:
       - path: "(.+)_test.go"
         linters:
@@ -30,11 +30,10 @@ linters:
           - nilnil
           - gochecknoinits
           - err113
-    generated: strict              # Skip all generated files across linters/formatters
+    generated: strict # Skip all generated files across linters/formatters
 
   # Per‑linter tuning ---------------------------------------------------------
   settings:
-
     wsl_v5:
       allow-first-in-block: true
       allow-whole-block: false
@@ -164,12 +163,12 @@ linters:
           arguments: ["^[a-zA-Z][a-zA-Z0-9_]{0,}$"]
         - name: argument-limit
           severity: warning
-          arguments: [4]
+          arguments: [6]
         - name: function-length
           severity: warning
           arguments: [75, 0]
-        - name: enforce-switch-style   # new in revive v1.11
-          severity: warning           # requires a default as last case
+        - name: enforce-switch-style # new in revive v1.11
+          severity: warning # requires a default as last case
         # Disabled / noisy checks
         - name: var-naming
           disabled: true

boundaries/bff/internal/domain/errors/errors.go

@@ -31,45 +31,36 @@ type Error struct {
 	Cause  error  // underlying technical cause (if any)
 }
 
-// ============================================================
-// Behavior
-// ============================================================
-
-// Error implements the standard error interface.
-func (e *Error) Error() string {
-	if e == nil {
-		return "<nil>"
+var (
+	// ErrSessionNotFound is a sentinel error for missing user sessions.
+	ErrSessionNotFound = &Error{
+		Code:   CodeSessionNotFound,
+		Title:  "Session expired",
+		Detail: "Session expired. Please sign in again.",
+		Action: "LOGIN",
 	}
-	if e.Cause == nil {
-		return fmt.Sprintf("[%s] %s: %s", e.Code, e.Title, e.Detail)
+	// ErrUserNotIdentified is a sentinel error for anonymous requests.
+	ErrUserNotIdentified = &Error{
+		Code:   CodeUserNotIdentified,
+		Title:  "User not identified",
+		Detail: "Unable to resolve your account. Please sign in again.",
+		Action: "LOGIN",
 	}
-	return fmt.Sprintf("[%s] %s: %s → cause: %v", e.Code, e.Title, e.Detail, e.Cause)
-}
-
-// Unwrap allows integration with errors.Is / errors.As.
-func (e *Error) Unwrap() error {
-	return e.Cause
-}
-
-// WithCause returns a shallow copy with a new cause attached.
-// Keeps the domain semantics intact while layering infra or app details.
-func (e *Error) WithCause(cause error) *Error {
-	if e == nil {
-		return nil
+	// ErrSessionMetadataMissing is a sentinel error for missing auth metadata.
+	ErrSessionMetadataMissing = &Error{
+		Code:   CodeSessionMetadataMissing,
+		Title:  "Authentication metadata missing",
+		Detail: "Request is missing authentication metadata.",
+		Action: "LOGIN",
 	}
-	cp := *e
-	cp.Cause = cause
-	return &cp
-}
-
-// IsCode checks if an error (possibly wrapped) matches a given domain code.
-func IsCode(err error, code string) bool {
-	var de *Error
-	if errors.As(err, &de) {
-		return de.Code == code
+	// ErrUnknown is a sentinel error for unexpected states.
+	ErrUnknown = &Error{
+		Code:   CodeUnknown,
+		Title:  "Unexpected error",
+		Detail: "Unexpected error occurred.",
+		Action: "NONE",
 	}
-	return false
-}
+)
 
 // ============================================================
 // Factory Functions (ubiquitous, intention-revealing)
@@ -110,3 +101,86 @@ func NewUnknown(detail string) *Error {
 		Action: "NONE",
 	}
 }
+
+// ============================================================
+// Behavior
+// ============================================================
+
+// Error implements the standard error interface.
+func (e *Error) Error() string {
+	if e == nil {
+		return "<nil>"
+	}
+
+	if e.Cause == nil {
+		return fmt.Sprintf("[%s] %s: %s", e.Code, e.Title, e.Detail)
+	}
+
+	return fmt.Sprintf("[%s] %s: %s → cause: %v", e.Code, e.Title, e.Detail, e.Cause)
+}
+
+// Unwrap allows integration with errors.Is / errors.As.
+func (e *Error) Unwrap() error {
+	return e.Cause
+}
+
+// Is allows errors.Is to compare domain errors by code only.
+func (e *Error) Is(target error) bool {
+	if e == nil {
+		return target == nil
+	}
+
+	t, ok := target.(*Error)
+	if !ok || t == nil {
+		return false
+	}
+
+	return e.Code == t.Code
+}
+
+// WithCause returns a shallow copy with a new cause attached.
+// Keeps the domain semantics intact while layering infra or app details.
+func (e *Error) WithCause(cause error) *Error {
+	if e == nil {
+		return nil
+	}
+
+	cp := *e
+	cp.Cause = cause
+
+	return &cp
+}
+
+// WithDetail returns a shallow copy with an overridden detail message.
+func (e *Error) WithDetail(detail string) *Error {
+	if e == nil {
+		return nil
+	}
+
+	cp := *e
+	cp.Detail = detail
+
+	return &cp
+}
+
+// WithTitle returns a shallow copy with an overridden title.
+func (e *Error) WithTitle(title string) *Error {
+	if e == nil {
+		return nil
+	}
+
+	cp := *e
+	cp.Title = title
+
+	return &cp
+}
+
+// IsCode checks if an error (possibly wrapped) matches a given domain code.
+func IsCode(err error, code string) bool {
+	var de *Error
+	if errors.As(err, &de) {
+		return de.Code == code
+	}
+
+	return false
+}

boundaries/bff/internal/domain/errors/errors_test.go

@@ -46,21 +46,22 @@ func TestErrorConstructors(t *testing.T) {
 			require.Equal(t, tt.wantTitle, err.Title)
 			require.NotEmpty(t, err.Detail)
 			require.Equal(t, tt.wantAction, err.Action)
-			require.Nil(t, err.Cause)
+			require.NoError(t, err.Cause)
 		})
 	}
 }
 
 func TestNewUnknown(t *testing.T) {
 	const detail = "unexpected I/O failure"
+
 	err := NewUnknown(detail)
 
 	require.NotNil(t, err)
 	require.Equal(t, CodeUnknown, err.Code)
 	require.Equal(t, "Unexpected error", err.Title)
 	require.Equal(t, detail, err.Detail)
 	require.Equal(t, "NONE", err.Action)
-	require.Nil(t, err.Cause)
+	require.NoError(t, err.Cause)
 }
 
 func TestWithCause(t *testing.T) {

boundaries/bff/internal/infrastructure/http/controllers/cqrs/cqrs.go

@@ -3,10 +3,9 @@ package cqrs
 import (
 	"net/http"
 
+	link_cqrs "buf.build/gen/go/shortlink-org/shortlink-link-link/grpc/go/infrastructure/rpc/cqrs/link/v1/linkv1grpc"
 	"github.com/go-chi/chi/v5"
 	"google.golang.org/protobuf/encoding/protojson"
-
-	link_cqrs "buf.build/gen/go/shortlink-org/shortlink-link-link/grpc/go/infrastructure/rpc/cqrs/link/v1/linkv1grpc"
 )
 
 var jsonpb protojson.MarshalOptions
@@ -78,7 +77,6 @@ func (c *LinkCQRSController) GetLinksByCQRS(w http.ResponseWriter, r *http.Reque
 	//
 	// 	return
 	// }
-
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(nil) //nolint:errcheck
 }

boundaries/bff/internal/infrastructure/http/controllers/link/addLink.go

@@ -3,9 +3,8 @@ package link
 import (
 	"net/http"
 
-	"github.com/segmentio/encoding/json"
-
 	v1 "buf.build/gen/go/shortlink-org/shortlink-link-link/protocolbuffers/go/infrastructure/rpc/link/v1"
+	"github.com/segmentio/encoding/json"
 
 	"github.com/shortlink-org/shortlink/boundaries/link/bff/internal/infrastructure/http/api"
 	"github.com/shortlink-org/shortlink/boundaries/link/bff/internal/infrastructure/http/controllers/link/dto"
@@ -15,6 +14,7 @@ import (
 func (c *Controller) AddLink(w http.ResponseWriter, r *http.Request) {
 	// Parse request
 	var request api.AddLink
+
 	err := json.NewDecoder(r.Body).Decode(&request)
 	if err != nil {
 		w.WriteHeader(http.StatusBadRequest)
@@ -42,6 +42,7 @@ func (c *Controller) AddLink(w http.ResponseWriter, r *http.Request) {
 	}
 
 	w.WriteHeader(http.StatusCreated)
+
 	err = json.NewEncoder(w).Encode(response)
 	if err != nil {
 		c.log.Error(err.Error())

boundaries/bff/internal/infrastructure/http/controllers/link/deleteLink.go

@@ -13,6 +13,5 @@ func (c *Controller) DeleteLink(w http.ResponseWriter, r *http.Request, hash str
 	//
 	// 	return
 	// }
-
 	w.WriteHeader(http.StatusNoContent)
 }

boundaries/bff/internal/infrastructure/http/controllers/link/error.go

@@ -5,12 +5,11 @@ import (
 	"strings"
 
 	"github.com/segmentio/encoding/json"
+	"github.com/shortlink-org/go-sdk/auth/session"
 	"google.golang.org/genproto/googleapis/rpc/errdetails"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 
-	"github.com/shortlink-org/go-sdk/auth/session"
-
 	domainerrors "github.com/shortlink-org/shortlink/boundaries/link/bff/internal/domain/errors"
 )
 
@@ -42,6 +41,7 @@ func ErrMessages(err error) *ErrorResponse {
 	if !ok {
 		// Not a gRPC status — wrap as unknown domain error
 		domainErr := domainerrors.NewUnknown(err.Error())
+
 		return &ErrorResponse{
 			Messages: []ErrorDetail{{
 				Code:   domainErr.Code,
@@ -60,11 +60,13 @@ func ErrMessages(err error) *ErrorResponse {
 
 	// Include any additional gRPC error details (for diagnostics)
 	var grpcDetails []string
+
 	for _, d := range st.Details() {
 		raw, err := json.Marshal(d)
 		if err != nil {
 			continue
 		}
+
 		grpcDetails = append(grpcDetails, string(raw))
 	}
 
@@ -112,7 +114,7 @@ func mapStatusToResponse(st *status.Status) *domainerrors.Error {
 		return domainerrors.NewUserNotIdentified()
 	case strings.Contains(message, session.ErrMetadataNotFound.Error()):
 		return domainerrors.NewSessionMetadataMissing()
-		default:
+	default:
 		return domainerrors.NewUnknown(message)
 	}
 }

boundaries/bff/internal/infrastructure/http/controllers/link/error_test.go

@@ -3,13 +3,12 @@ package link
 import (
 	"testing"
 
+	"github.com/shortlink-org/go-sdk/auth/session"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/genproto/googleapis/rpc/errdetails"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 
-	"github.com/shortlink-org/go-sdk/auth/session"
-
 	domainerrors "github.com/shortlink-org/shortlink/boundaries/link/bff/internal/domain/errors"
 )
 

boundaries/bff/internal/infrastructure/http/controllers/link/getLinks.go

@@ -3,17 +3,15 @@ package link
 import (
 	"net/http"
 
-	"github.com/segmentio/encoding/json"
-
 	v1 "buf.build/gen/go/shortlink-org/shortlink-link-link/protocolbuffers/go/infrastructure/rpc/link/v1"
+	"github.com/segmentio/encoding/json"
 
 	"github.com/shortlink-org/shortlink/boundaries/link/bff/internal/infrastructure/http/api"
 )
 
 // GetLinks - get links
 func (c *Controller) GetLinks(w http.ResponseWriter, r *http.Request, params api.GetLinksParams) {
 	// TODO: add mapper for filter
-
 	request := &v1.ListRequest{}
 
 	if params.Cursor != nil {
@@ -48,6 +46,7 @@ func (c *Controller) GetLinks(w http.ResponseWriter, r *http.Request, params api
 	}
 
 	w.WriteHeader(http.StatusOK)
+
 	err = json.NewEncoder(w).Encode(response)
 	if err != nil {
 		c.log.Error(err.Error())