System design fundamentals

package main
 
import "fmt"
 
func human(bytes float64) string {
	units := []string{"B", "KB", "MB", "GB", "TB", "PB"}
	i := 0
	for bytes >= 1000 && i < len(units)-1 {
		bytes /= 1000
		i++
	}
	return fmt.Sprintf("%.1f %s", bytes, units[i])
}
 
func main() {
	// A URL shortener: 100M new links a month, 100 reads per write, 500 bytes per record, kept 5 years.
	const (
		writesPerMonth = 100e6
		readsPerWrite  = 100
		recordBytes    = 500
		years          = 5
		secondsPerDay  = 86_400
	)
	writeQPS := writesPerMonth / 30 / secondsPerDay
	readQPS := writeQPS * readsPerWrite
	records := writesPerMonth * 12 * years
	fmt.Printf("writes: %.0f/s average, %.0f/s at a 3x peak\n", writeQPS, writeQPS*3)
	fmt.Printf("reads:  %.0f/s average, %.0f/s at a 3x peak\n", readQPS, readQPS*3)
	fmt.Printf("records after %d years: %.0f billion, storage %s\n", years, records/1e9, human(records*recordBytes))
	fmt.Printf("read bandwidth: %s/s\n", human(readQPS*recordBytes))
 
	// If 20% of links get 80% of reads, caching that hot 20% of one day's reads:
	hotDaily := readQPS * secondsPerDay * 0.2
	fmt.Printf("cache for the hot 20%% of a day's reads: about %s\n", human(hotDaily*recordBytes))
}

writes: 39/s average, 116/s at a 3x peak
reads:  3858/s average, 11574/s at a 3x peak
records after 5 years: 6 billion, storage 3.0 TB
read bandwidth: 1.9 MB/s
cache for the hot 20% of a day's reads: about 33.3 GB

package main
 
import (
	"fmt"
	"hash/fnv"
)
 
type Backend struct {
	Name   string
	Active int // open connections
	Weight int
}
 
func roundRobin(bs []*Backend) func() *Backend {
	i := -1
	return func() *Backend {
		i = (i + 1) % len(bs)
		return bs[i]
	}
}
 
func leastConnections(bs []*Backend) *Backend {
	best := bs[0]
	for _, b := range bs[1:] {
		if b.Active < best.Active {
			best = b
		}
	}
	return best
}
 
// smoothWeighted is nginx's smooth weighted round robin: heavier backends get more turns, evenly spread.
func smoothWeighted(bs []*Backend) func() *Backend {
	current := make([]int, len(bs))
	total := 0
	for _, b := range bs {
		total += b.Weight
	}
	return func() *Backend {
		best := 0
		for i, b := range bs {
			current[i] += b.Weight
			if current[i] > current[best] {
				best = i
			}
		}
		current[best] -= total
		return bs[best]
	}
}
 
func hashPick(bs []*Backend, key string) *Backend {
	h := fnv.New32a()
	h.Write([]byte(key))
	return bs[h.Sum32()%uint32(len(bs))]
}
 
func main() {
	bs := []*Backend{{Name: "a", Active: 7, Weight: 5}, {Name: "b", Active: 2, Weight: 1}, {Name: "c", Active: 4, Weight: 1}}
 
	rr := roundRobin(bs)
	fmt.Print("round robin: ")
	for range 6 {
		fmt.Print(rr().Name, " ")
	}
	fmt.Println()
 
	fmt.Println("least connections:", leastConnections(bs).Name)
 
	sw := smoothWeighted(bs)
	fmt.Print("smooth weighted 5:1:1: ")
	for range 7 {
		fmt.Print(sw().Name, " ")
	}
	fmt.Println()
 
	fmt.Println("hash user-42 twice:", hashPick(bs, "user-42").Name, hashPick(bs, "user-42").Name)
}

round robin: a b c a b c 
least connections: b
smooth weighted 5:1:1: a a b a c a a 
hash user-42 twice: a a

package main
 
import (
	"fmt"
	"sync"
	"sync/atomic"
	"time"
)
 
type call struct {
	wg  sync.WaitGroup
	val string
}
 
// Group deduplicates concurrent loads of the same key (a tiny singleflight).
type Group struct {
	mu    sync.Mutex
	calls map[string]*call
}
 
func (g *Group) Do(key string, load func() string) string {
	g.mu.Lock()
	if c, ok := g.calls[key]; ok {
		g.mu.Unlock()
		c.wg.Wait() // someone is already loading it: wait for their result
		return c.val
	}
	c := &call{}
	c.wg.Add(1)
	g.calls[key] = c
	g.mu.Unlock()
 
	c.val = load()
	c.wg.Done()
 
	g.mu.Lock()
	delete(g.calls, key)
	g.mu.Unlock()
	return c.val
}
 
type Cache struct {
	mu   sync.RWMutex
	data map[string]string
	sf   Group
}
 
func (c *Cache) Get(key string, fromDB func(string) string) string {
	c.mu.RLock()
	v, ok := c.data[key]
	c.mu.RUnlock()
	if ok {
		return v // hit
	}
	return c.sf.Do(key, func() string { // miss: only one goroutine loads
		c.mu.RLock()
		v, ok := c.data[key] // re-check: a load may have finished just before we got here
		c.mu.RUnlock()
		if ok {
			return v
		}
		v = fromDB(key)
		c.mu.Lock()
		c.data[key] = v
		c.mu.Unlock()
		return v
	})
}
 
func main() {
	var dbQueries atomic.Int32
	slowDB := func(k string) string {
		dbQueries.Add(1)
		time.Sleep(20 * time.Millisecond)
		return "value-of-" + k
	}
	c := &Cache{data: map[string]string{}, sf: Group{calls: map[string]*call{}}}
 
	var wg sync.WaitGroup
	for range 100 { // 100 simultaneous requests for a cold, hot key
		wg.Add(1)
		go func() {
			defer wg.Done()
			c.Get("homepage", slowDB)
		}()
	}
	wg.Wait()
	fmt.Println("requests: 100, database queries:", dbQueries.Load())
	fmt.Println(c.Get("homepage", slowDB), "| queries after a warm hit:", dbQueries.Load())
}

requests: 100, database queries: 1
value-of-homepage | queries after a warm hit: 1

package main
 
import (
	"errors"
	"fmt"
	"math/rand/v2"
	"time"
)
 
// backoff returns the wait before attempt n (0-based): exponential, capped, with "full jitter".
func backoff(n int, base, maxWait time.Duration, r *rand.Rand) time.Duration {
	d := min(base<<n, maxWait)
	return time.Duration(r.Int64N(int64(d) + 1)) // anywhere from 0 to d
}
 
type State int
 
const (
	Closed   State = iota // normal: requests flow
	Open                  // failing: reject immediately
	HalfOpen              // probing: let one request test the dependency
)
 
func (s State) String() string { return [...]string{"closed", "open", "half-open"}[s] }
 
var ErrOpen = errors.New("circuit open: failing fast")
 
type Breaker struct {
	state     State
	failures  int
	threshold int
	cooldown  time.Duration
	openedAt  time.Time
}
 
func (b *Breaker) Call(now time.Time, fn func() error) error {
	if b.state == Open {
		if now.Sub(b.openedAt) < b.cooldown {
			return ErrOpen
		}
		b.state = HalfOpen // cooldown over: allow a trial request
	}
	if err := fn(); err != nil {
		b.failures++
		if b.state == HalfOpen || b.failures >= b.threshold {
			b.state, b.openedAt = Open, now
		}
		return err
	}
	b.state, b.failures = Closed, 0
	return nil
}
 
// Idempotency: remember results by key so a retried request is not processed twice.
type Payments struct {
	results map[string]string
	charged int
}
 
func (p *Payments) Charge(idemKey string, amount int) string {
	if r, ok := p.results[idemKey]; ok {
		return r + " (replayed, not charged again)"
	}
	p.charged += amount
	r := fmt.Sprintf("charged %d", amount)
	p.results[idemKey] = r
	return r
}
 
func main() {
	r := rand.New(rand.NewPCG(1, 1))
	fmt.Print("backoff caps: ")
	for n := range 7 {
		fmt.Print(min(100*time.Millisecond<<n, 3*time.Second), " ")
	}
	fmt.Println()
	fmt.Println("one jittered wait for attempt 3 is at most 800ms:", backoff(3, 100*time.Millisecond, 3*time.Second, r) <= 800*time.Millisecond)
 
	b := &Breaker{threshold: 3, cooldown: 10 * time.Second}
	t0 := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
	failing := func() error { return errors.New("upstream 503") }
	for i := range 5 {
		err := b.Call(t0.Add(time.Duration(i)*time.Second), failing)
		fmt.Printf("t=%ds state=%-9s err=%v\n", i, b.state, err)
	}
	err := b.Call(t0.Add(15*time.Second), func() error { return nil }) // after the cooldown, a trial succeeds
	fmt.Printf("t=15s state=%-9s err=%v\n", b.state, err)
 
	p := &Payments{results: map[string]string{}}
	fmt.Println(p.Charge("order-77", 500))
	fmt.Println(p.Charge("order-77", 500)) // the client retried after a timeout
	fmt.Println("total charged:", p.charged)
}

backoff caps: 100ms 200ms 400ms 800ms 1.6s 3s 3s 
one jittered wait for attempt 3 is at most 800ms: true
t=0s state=closed    err=upstream 503
t=1s state=closed    err=upstream 503
t=2s state=open      err=upstream 503
t=3s state=open      err=circuit open: failing fast
t=4s state=open      err=circuit open: failing fast
t=15s state=closed    err=<nil>
charged 500
charged 500 (replayed, not charged again)
total charged: 500

# Build stage: compile a static binary.
FROM golang:1.24 AS build
WORKDIR /src
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /app .
 
# Run stage: a tiny image with just the binary.
FROM gcr.io/distroless/static-debian12
COPY --from=build /app /app
EXPOSE 8080
USER nonroot:nonroot
ENTRYPOINT ["/app"]

docker build -t myapp .
docker run -p 8080:8080 myapp
# then, for example: fly launch   (or push the image to Cloud Run, Railway, Render)