Distributed Systems in Go

Preface

1. Why Cloud-Native Distributed Systems?
2. Who This Book Is For
3. How to Read This Book
4. About the Code
5. What This Book Is Not

Introduction

1. The Problem with Distributed Systems Books
2. The Mental Model
3. The Company SDK
4. The System We Build
5. The Code Style
6. Before You Begin

Chapter 1: Why Distributed? The Cost of Coordination

1. The Limits of One
2. The Eight Things You Cannot Assume
3. When You Have To
4. The Hidden Tax
5. The Struct-to-Service Progression
6. Go’s Fit
7. The Monolith-First Principle
8. What You Will Build
9. Q&A

Chapter 2: Concurrency as Distributed Systems in Miniature

1. Goroutines
2. Channels
3. select
4. sync.WaitGroup
5. context.Context
6. Putting It Together: A Worker Pool
7. Graceful Shutdown
8. The Concurrency Mental Model
9. Q&A
10. What Goes in the SDK

Chapter 3: Two Services, One Queue

1. Why a Queue and Not an HTTP Call?
2. NATS for a First Example
3. The Interfaces
4. The Producer
5. The Consumer
6. Running It
7. Loose Coupling in Practice
8. Error Handling and Reconnection
9. The Complete Picture
10. What Goes in the SDK

Chapter 4: HTTP Services and Middleware Chains

1. net/http in Go 1.22
2. The Handler Interface
3. Building a Middleware Chain
4. The Essential Middleware
5. Structured Error Responses
6. JSON Request Binding
7. Health Check Patterns
8. The Complete Service
9. Testing HTTP Handlers
10. What Frameworks Add
11. Q&A
12. What Goes in the SDK

Chapter 5: Authentication and JWT Across Services

1. What a JWT Is
2. HMAC vs RSA vs ECDSA
3. Generating and Validating Tokens with ECDSA
4. The JWKS Endpoint
5. Auth Middleware
6. Scope-Based Authorization
7. The Auth Service
8. Pluggable Authentication Agents
9. Token Propagation Between Services
10. Adding Auth to the Service Chain
11. Testing Auth
12. Q&A
13. What Goes in the SDK

Chapter 6: Database Access and Migrations

1. pgx: PostgreSQL Done Right
2. The Repository Pattern
3. Transactions
4. sqlc: Type-Safe SQL Without an ORM
5. Schema Migrations
6. Zero-Downtime Migrations
7. One Database Per Service
8. Observability for Database Operations
9. Q&A
10. What Goes in the SDK

Chapter 7: Context Propagation — The Thread Connecting Everything

1. How the Context Tree Fails
2. The Context Discipline
3. Deadline Propagation
4. Narrowing Deadlines
5. Context Values in Practice
6. The Context Anti-Patterns
7. Connecting the Layers
8. Q&A
9. What Goes in the SDK

Chapter 8: Message Queues in Depth — Kafka, Backpressure, and Consumer Groups

1. How Kafka Works
2. Writing a Kafka Producer
3. Writing a Kafka Consumer
4. Backpressure
5. Consumer Groups in Action
6. Dynamic Topic Subscriptions
7. Message Schema Management
8. Q&A
9. What Goes in the SDK

Chapter 9: Service-to-Service Calls — gRPC, Protobuf, Retries, and Circuit Breakers

1. Why gRPC for Internal Communication
2. Defining a Service with Protocol Buffers
3. Generating Go Code with buf
4. Implementing the gRPC Server
5. Running the gRPC Server
6. The gRPC Client with Interceptors
7. Service Token Authentication
8. The Dual API Pattern: Management vs Consumption
9. Timeouts and Retries
10. The Circuit Breaker
11. Choosing: HTTP vs gRPC
12. Q&A
13. What Goes in the SDK

Chapter 10: Orchestration — Parallel Flows and Fan-Out

1. The Sequential Problem
2. Fan-Out with errgroup
3. Partial Failure Handling
4. Pipeline Composition
5. Fan-Out to Dynamic Targets
6. Timeout Budget Across a Multi-Step Flow
7. Measuring the Impact
8. What Goes in the SDK
9. Q&A

Chapter 11: Distributed Consistency in Practice

1. The CAP Theorem, Applied
2. Eventual Consistency
3. Idempotency Keys
4. Optimistic Locking
5. The Saga Pattern
6. Event-Driven Consistency
7. Detecting Inconsistency
8. The Outbox Pattern
9. Reconciliation in Practice
10. What Goes in the SDK
11. Q&A

Chapter 12: Observability — Logging, Metrics, and Tracing

1. Structured Logging with slog
2. Metrics with Prometheus
3. Distributed Tracing with OpenTelemetry
4. Alerting: When Metrics Become Alarms
5. Q&A
6. What Goes in the SDK

Chapter 13: Testing Distributed Systems

1. The Testing Pyramid for Distributed Systems
2. Testing with Real Databases: testcontainers
3. The -race Flag
4. Testing with Fake Implementations
5. Testing Idempotency
6. Chaos Testing: Kill a Dependency Mid-Test
7. goleak: Finding Goroutine Leaks
8. Table-Driven Tests for Edge Cases
9. Q&A
10. What Goes in the SDK

Chapter 14: Configuration and Secrets

1. The Twelve-Factor Principle
2. Configuration With Struct Tags
3. Viper for Complex Configuration
4. Configuration Validation at Startup
5. Secrets Management
6. Conditional Secret Exposure
7. Live Reload via Signal Handler
8. Configuration in a Multi-Service System
9. Configuration Testing
10. Q&A
11. What Goes in the SDK

Chapter 15: Capstone — One Complete System

1. The Design
2. The Data Flows
3. The Repository Structure
4. Implementing the Core: The Order Service
5. The docker-compose
6. The API Gateway
7. Service Discovery
8. Two-Phase Service Startup
9. Deploying to Kubernetes
10. Tracing a Request
11. Running It
12. The Integration Test
13. What You Have Built
14. Production Hardening Checklist
15. Q&A

Appendix A: Go Concurrency Quick Reference

1. Goroutines
2. Channels
3. select
4. context.Context
5. sync.WaitGroup
6. sync.Mutex / sync.RWMutex
7. sync/atomic
8. errgroup
9. signal.NotifyContext (graceful shutdown)
10. Common Patterns

Appendix B: File and Object Storage Abstraction

1. The Storage Interface
2. The S3 Adapter
3. The Local Filesystem Adapter
4. Wiring It Up
5. The Platform SDK Package
6. When to Reach for Afero

Appendix C: CLI Tooling for Operations

1. The CLI Structure
2. The Migration Runner
3. The Health Checker
4. Admin Commands
5. Testing CLI Commands
6. What Goes in the SDK
7. Beyond CLI: Operational TUIs

Glossary

Acknowledgements

Credits

1. Further Reading