Microservice Architecture #

// pkg/httpclient/client.go — reusable HTTP client with timeout and retry
package httpclient

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

// Config configures the HTTP client's behavior
type Config struct {
	BaseURL    string
	Timeout    time.Duration
	MaxRetries int
	RetryDelay time.Duration
}

// Client is an opinionated HTTP client for inter-service communication
type Client struct {
	config Config
	http   *http.Client
}

func New(config Config) *Client {
	if config.Timeout == 0 {
		config.Timeout = 5 * time.Second
	}
	if config.MaxRetries == 0 {
		config.MaxRetries = 3
	}
	if config.RetryDelay == 0 {
		config.RetryDelay = 100 * time.Millisecond
	}

	return &Client{
		config: config,
		http:   &http.Client{Timeout: config.Timeout},
	}
}

// Get performs an HTTP GET with automatic retries for transient errors
func (c *Client) Get(ctx context.Context, path string, result interface{}) error {
	url := c.config.BaseURL + path
	var lastErr error

	for attempt := 0; attempt <= c.config.MaxRetries; attempt++ {
		if attempt > 0 {
			select {
			case <-ctx.Done():
				return ctx.Err()
			case <-time.After(c.config.RetryDelay * time.Duration(attempt)):
			}
		}

		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
		if err != nil {
			return fmt.Errorf("failed to create request: %w", err)
		}

		// Propagate the trace ID for distributed tracing
		if traceID := ctx.Value("trace_id"); traceID != nil {
			req.Header.Set("X-Trace-ID", fmt.Sprint(traceID))
		}

		resp, err := c.http.Do(req)
		if err != nil {
			lastErr = err
			continue // retry
		}
		defer resp.Body.Close()

		// Do not retry for client errors (4xx)
		if resp.StatusCode >= 400 && resp.StatusCode < 500 {
			return fmt.Errorf("client error %d from %s", resp.StatusCode, url)
		}

		// Retry for server errors (5xx)
		if resp.StatusCode >= 500 {
			lastErr = fmt.Errorf("server error %d from %s", resp.StatusCode, url)
			continue
		}

		if result != nil {
			if err := json.NewDecoder(resp.Body).Decode(result); err != nil {
				return fmt.Errorf("failed to decode response: %w", err)
			}
		}
		return nil
	}

	return fmt.Errorf("after %d attempts: %w", c.config.MaxRetries, lastErr)
}

// internal/order/user_client.go — client for the User Service
package order

import (
	"context"
	"fmt"

	"myapp/pkg/httpclient"
)

// UserServiceClient is the client for communicating with the User Service
type UserServiceClient struct {
	client *httpclient.Client
}

func NewUserServiceClient(baseURL string) *UserServiceClient {
	return &UserServiceClient{
		client: httpclient.New(httpclient.Config{
			BaseURL:    baseURL,
			Timeout:    3 * time.Second,
			MaxRetries: 2,
		}),
	}
}

type userResponse struct {
	ID       string `json:"id"`
	FullName string `json:"full_name"`
	IsActive bool   `json:"is_active"`
}

// ValidateUserActive calls the User Service to validate a user
func (c *UserServiceClient) ValidateUserActive(ctx context.Context, userID string) error {
	var user userResponse
	if err := c.client.Get(ctx, fmt.Sprintf("/users/%s", userID), &user); err != nil {
		return fmt.Errorf("failed to validate user: %w", err)
	}
	if !user.IsActive {
		return fmt.Errorf("user %s is inactive", userID)
	}
	return nil
}

// pkg/circuitbreaker/breaker.go
package circuitbreaker

import (
	"errors"
	"sync"
	"time"
)

type State int

const (
	StateClosed   State = iota // Normal: requests allowed
	StateOpen                  // Open: requests rejected immediately
	StateHalfOpen              // Half-open: one trial request
)

var ErrCircuitOpen = errors.New("circuit breaker open — service unavailable")

type Breaker struct {
	mu           sync.Mutex
	state        State
	failures     int
	maxFailures  int
	successCount int
	lastFailure  time.Time
	openDuration time.Duration
}

func New(maxFailures int, openDuration time.Duration) *Breaker {
	return &Breaker{
		maxFailures:  maxFailures,
		openDuration: openDuration,
	}
}

// Execute runs fn through the circuit breaker
func (b *Breaker) Execute(fn func() error) error {
	b.mu.Lock()
	state := b.currentState()
	b.mu.Unlock()

	if state == StateOpen {
		return ErrCircuitOpen // ✓ fail fast — no attempt at all
	}

	err := fn()

	b.mu.Lock()
	defer b.mu.Unlock()

	if err != nil {
		b.recordFailure()
	} else {
		b.recordSuccess()
	}
	return err
}

func (b *Breaker) currentState() State {
	if b.state == StateOpen {
		if time.Since(b.lastFailure) > b.openDuration {
			b.state = StateHalfOpen
			b.successCount = 0
		}
	}
	return b.state
}

func (b *Breaker) recordFailure() {
	b.failures++
	b.lastFailure = time.Now()
	if b.failures >= b.maxFailures {
		b.state = StateOpen
	}
}

func (b *Breaker) recordSuccess() {
	b.failures = 0
	if b.state == StateHalfOpen {
		b.successCount++
		if b.successCount >= 2 {
			b.state = StateClosed // ✓ recovered
		}
	}
}

// internal/order/handler.go — structured logging with trace IDs
package order

import (
	"encoding/json"
	"log/slog"
	"net/http"
	"time"

	"github.com/google/uuid"
)

// Middleware to inject trace IDs and structured logging
func TracingMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Generate or propagate the trace ID
		traceID := r.Header.Get("X-Trace-ID")
		if traceID == "" {
			traceID = uuid.New().String()
		}

		// Inject into the context for propagation to downstream calls
		ctx := context.WithValue(r.Context(), "trace_id", traceID)

		// Set in the response header
		w.Header().Set("X-Trace-ID", traceID)

		start := time.Now()
		rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}

		next.ServeHTTP(rw, r.WithContext(ctx))

		// Structured log for every request
		slog.InfoContext(ctx, "request completed",
			"trace_id", traceID,
			"method", r.Method,
			"path", r.URL.Path,
			"status", rw.statusCode,
			"duration_ms", time.Since(start).Milliseconds(),
			"service", "order-service",
		)
	})
}

type responseWriter struct {
	http.ResponseWriter
	statusCode int
}

func (rw *responseWriter) WriteHeader(code int) {
	rw.statusCode = code
	rw.ResponseWriter.WriteHeader(code)
}

// Handler with structured logging
func (h *Handler) CreateOrder(w http.ResponseWriter, r *http.Request) {
	traceID := r.Context().Value("trace_id")

	var req CreateOrderRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		slog.WarnContext(r.Context(), "invalid request body",
			"trace_id", traceID,
			"error", err.Error(),
		)
		http.Error(w, "invalid request", http.StatusBadRequest)
		return
	}

	slog.InfoContext(r.Context(), "creating order",
		"trace_id", traceID,
		"customer_id", req.CustomerID,
		"item_count", len(req.Items),
	)

	output, err := h.service.CreateOrder(r.Context(), req.toInput())
	if err != nil {
		slog.ErrorContext(r.Context(), "failed to create order",
			"trace_id", traceID,
			"customer_id", req.CustomerID,
			"error", err.Error(),
		)
		http.Error(w, err.Error(), http.StatusUnprocessableEntity)
		return
	}

	slog.InfoContext(r.Context(), "order created successfully",
		"trace_id", traceID,
		"order_id", output.OrderID,
	)

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(output)
}

// internal/order/saga_handler.go — handling results from other services
package order

import (
	"context"
	"log/slog"

	"myapp/internal/shared/eventbus"
)

// PaymentFailedEvent is received from the Payment Service
type PaymentFailedEvent struct {
	OrderID string
	Reason  string
}

func (e PaymentFailedEvent) EventName() string { return "payment.failed" }

// SagaHandler handles compensating transactions
type SagaHandler struct {
	repo     Repository
	eventBus *eventbus.EventBus
}

// HandlePaymentFailed is the compensating transaction for an order
func (h *SagaHandler) HandlePaymentFailed(ctx context.Context, event eventbus.Event) error {
	e, ok := event.(PaymentFailedEvent)
	if !ok {
		return nil
	}

	slog.InfoContext(ctx, "payment failed, cancelling order",
		"order_id", e.OrderID,
		"reason", e.Reason,
	)

	order, err := h.repo.FindByID(ctx, e.OrderID)
	if err != nil {
		return err
	}

	// Compensating transaction: cancel the order
	if err := order.Cancel("payment failed: " + e.Reason); err != nil {
		return err
	}

	if err := h.repo.Save(ctx, order); err != nil {
		return err
	}

	// Publish the compensation event
	return h.eventBus.Publish(ctx, OrderCancelledEvent{
		OrderID: e.OrderID,
		Reason:  "payment failed",
	})
}

// ✗ Shared database between services — distributed monolith
// The Order Service queries the User Service's database directly
func (r *OrderRepo) GetOrderWithUser(ctx context.Context, orderID string) (*OrderWithUser, error) {
	// ✗ JOIN into another service's database — the most dangerous coupling
	return r.db.QueryContext(ctx, `
		SELECT o.id, u.full_name
		FROM order_db.orders o
		JOIN user_db.users u ON u.id = o.customer_id
		WHERE o.id = $1
	`, orderID)
}

// ✓ Each service only accesses its own database
// Data from other services is fetched via API calls
func (s *OrderService) GetOrderWithUser(ctx context.Context, orderID string) (*OrderDisplay, error) {
	order, err := s.repo.FindByID(ctx, orderID)
	if err != nil {
		return nil, err
	}

	// Fetch the user's name from the User Service via HTTP
	user, err := s.userClient.GetUser(ctx, order.CustomerID)
	if err != nil {
		// Graceful degradation: show the order even if the user is unavailable
		return &OrderDisplay{OrderID: orderID, CustomerName: "Unknown"}, nil
	}

	return &OrderDisplay{OrderID: orderID, CustomerName: user.FullName}, nil
}

// ✗ Overly long synchronous chains — cascade failure
// Order → Inventory → Warehouse → Supplier (all sync)
func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderInput) error {
	// ✗ 4 sync hops — if Supplier is slow, the whole order creation is slow
	inventory := s.inventoryClient.CheckStock(ctx, req.Items)
	warehouse := s.warehouseClient.Reserve(ctx, inventory)
	supplier := s.supplierClient.Confirm(ctx, warehouse)
	_ = supplier
	return s.repo.Save(ctx, buildOrder(req))
}

// ✓ Only critical validation is sync, the rest is async via events
func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderInput) error {
	// ✓ Only user validation is sync (needs an immediate response)
	if err := s.userClient.ValidateActive(ctx, req.CustomerID); err != nil {
		return err
	}

	order := buildOrder(req)
	if err := s.repo.Save(ctx, order); err != nil {
		return err
	}

	// ✓ The rest is async — Inventory, Warehouse, Supplier respond via events
	return s.eventBus.Publish(ctx, OrderCreatedEvent{OrderID: order.ID, Items: req.Items})
}

// ✗ No timeout on inter-service calls — goroutines wait forever
func (s *Service) getUser(ctx context.Context, id string) (*User, error) {
	resp, err := http.Get("http://user-service/users/" + id) // ✗ no timeout!
	// ...
}

// ✓ Always use a context with a timeout
func (s *Service) getUser(ctx context.Context, id string) (*User, error) {
	ctx, cancel := context.WithTimeout(ctx, 2*time.Second) // ✓ bounded timeout
	defer cancel()
	return s.userClient.Get(ctx, id)
}