Capstone: design a small concurrent service — then count the cost

Sixteen lessons built one tool at a time; this one assembles them into a single working design and then does the thing the whole series has been training you for — it adds up the bill. We will sketch a real service (a bounded, cancellable URL-fetch worker pool that exposes results over HTTP), watch interfaces, errors-as-values, goroutines, channels, context, packages, and tests fall into place because the five questions force them there, and then close with an unflinching account of what Go's bargain actually cost us. The point is not the service. The point is that you can now read any design as a ledger of complexity paid and convenience bought.

1 · The service, and the requirement that makes it real

The toy is this: a service that, given a batch of URLs, fetches them concurrently and returns each one's status and byte-length. Trivial — until you add the requirement every production version of this has: it must be bounded and cancellable. Bounded, because a batch of 10,000 URLs must not open 10,000 sockets at once and exhaust file descriptors. Cancellable, because the HTTP client who asked for the batch may disconnect, or a deadline may pass, and continuing to fetch is wasted money and a goroutine leak. That single requirement — do work concurrently, but with a ceiling and a kill switch — is what turns a for loop into a design, and it is exactly the shape of most real backend work: crawlers, batch enrichers, fan-out RPC aggregators.

Read the diagram with question 2 (who owns the data, how does it move?) already in mind: a jobs channel carries URLs into a fixed pool of W workers, a results channel carries answers back, and a single context threads through everything as the cancellation signal. Nothing is shared and locked; everything is passed. That is the CSP shape from Lesson 09, and the bound — W workers, not N — is the entire reason the pattern exists.

2 · The five questions build the design

Every earlier lesson now arrives because a question demands it. This is the payoff of the dependency chain: you don't reach for features, the problem reaches for them.

Notice question 4 is what makes question 3 testable and question 5 affordable: because the worker depends on a behavior (Fetcher), a test can inject a fake that returns canned errors and never touches the network, so you can verify the failure paths from question 3 deterministically. The questions are not a checklist; they interlock.

3 · The assembled design

First the package boundary (question 1, Lesson 12): the import graph must be acyclic and the public surface tiny. fetch is a library package that knows nothing about HTTP serving; main wires it to an HTTP handler. The library never imports the server — dependencies point inward.

The behavior the pool depends on — one method, the canonical small interface (Lesson 05). The concrete *http.Client satisfies a tiny adapter; a test satisfies it with a struct.

package fetch

import "context"

// Fetcher is the only thing the pool depends on. Accept interfaces.
type Fetcher interface {
	Fetch(ctx context.Context, url string) (status int, n int64, err error)
}

type Result struct {
	URL    string
	Status int
	Bytes  int64
	Err    error // failure is a value in the result, not a panic (L07)
}

The pool itself. Read it as the CSP diagram made literal: jobs in, results out, context as the kill switch, a sync.WaitGroup to know when every worker has drained so we can close results exactly once (Lesson 11 — a WaitGroup coordinates lifetime; channels move the data).

func FetchAll(ctx context.Context, f Fetcher, urls []string, workers int) ([]Result, error) {
	jobs := make(chan string)
	results := make(chan Result)

	var wg sync.WaitGroup
	for i := 0; i < workers; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for url := range jobs { // ranges until jobs is closed
				status, n, err := f.Fetch(ctx, url)
				select {
				case results <- Result{url, status, n, err}:
				case <-ctx.Done(): // don't block forever if cancelled
					return
				}
			}
		}()
	}

	// Feeder: hands out work, stops early on cancellation.
	go func() {
		defer close(jobs)
		for _, u := range urls {
			select {
			case jobs <- u:
			case <-ctx.Done():
				return
			}
		}
	}()

	// Closer: results is closed once, after all workers are done.
	go func() { wg.Wait(); close(results) }()

	out := make([]Result, 0, len(urls))
	for r := range results {
		out = append(out, r)
	}
	if err := ctx.Err(); err != nil {
		return out, err // cancellation is in the signature (L07, L10)
	}
	return out, nil
}

Three details earn their place. The feeder goroutine selects between sending a job and ctx.Done() so cancellation stops dispatch immediately instead of after all N sends — without it you'd leak the feeder if no worker ever reads again. Workers also select on send so a cancelled collector can't deadlock them. And close(results) happens in exactly one place, gated by wg.Wait(); closing a channel twice, or from a sender that doesn't own it, panics — so ownership of the close is assigned to a single goroutine (Lesson 09). This is the whole reason CSP discipline matters: the bugs it prevents are the ones that only appear under load.

The HTTP edge, in main, ties a request's lifetime to the work via r.Context() — when the client disconnects, every goroutine above unwinds for free:

func handler(f fetch.Fetcher) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		var urls []string
		if err := json.NewDecoder(r.Body).Decode(&urls); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		// r.Context() is cancelled when the client disconnects (L10)
		results, err := fetch.FetchAll(r.Context(), f, urls, 16)
		if err != nil {
			http.Error(w, err.Error(), http.StatusRequestTimeout)
			return
		}
		json.NewEncoder(w).Encode(results)
	}
}

And the test that question 4 made possible — no network, deterministic, table-driven (Lesson 15). Because the pool accepts a Fetcher interface, the fake is ten lines and the failure path is exercised on purpose:

type fakeFetcher struct{ fail map[string]error }

func (ff fakeFetcher) Fetch(_ context.Context, url string) (int, int64, error) {
	if err := ff.fail[url]; err != nil {
		return 0, 0, err
	}
	return 200, 42, nil
}

func TestFetchAll(t *testing.T) {
	ff := fakeFetcher{fail: map[string]error{"bad": errTimeout}}
	got, err := FetchAll(context.Background(), ff, []string{"ok", "bad"}, 4)
	if err != nil {
		t.Fatalf("unexpected: %v", err)
	}
	if len(got) != 2 {
		t.Fatalf("want 2 results, got %d", len(got))
	}
	// run `go test -race` — the pool must be clean under the detector (L11)
}

4 · The honest accounting — what the bargain cost

The service works, reads cleanly, and a stranger could change it. Now the part the series exists for: the bill. Every line below is a real cost of a real Go decision, stated the way the C++ track states its honest scope. None of these is a reason not to use Go; all of them are reasons to know what you bought.

Two costs deserve their own line because they bite when you least expect it. The nil-interface trap (L05, L07): if a worker returned a *MyError that is nil through a function typed to return error, the returned interface is non-nil — a (type, nil-data) pair — and err != nil is true even though "nothing went wrong." It is the single most-stepped-on rake in the language, and a concurrent service that wraps errors across goroutines is exactly where it hides. No inheritance (L06): there is no base Worker class to extend; if you want a retrying fetcher you wrap the Fetcher interface (a decorator), you don't subclass it. That is usually better — but it is genuinely a different muscle, and engineers arriving from Java reach for a hierarchy that Go simply will not give them.

Checkpoint exercise

Where this points next

This is the last lesson, so the handoff is back to the whole map. Return to the series index and re-read the spine of five movements now that you have assembled it once end to end — the joints (02→04→05→06 building abstraction without inheritance; 08→09→10→11 building concurrency on top of values) read differently when you've felt them snap together in one design. The real continuation, though, is not another Go lesson: it is the next codebase you read in any language, where you will now reflexively ask who owns this data, how does it fail, what could be left out, and who pays — which was the point of learning Go all along.

Interview prompts

• Why a worker pool of W goroutines instead of one goroutine per URL? (§1, §4 — to bound resources: N goroutines means N open sockets/FDs and N×2 KB of stack; a fixed W caps memory and concurrency while channels still feed all N jobs through.)
• How does cancellation propagate through the design, and what breaks without it? (§3 — one context threads from r.Context() through feeder and workers; each selects on ctx.Done(). Without it the feeder leaks if collectors stop reading, and workers keep fetching after the client is gone — a goroutine leak.)
• Why does the pool depend on a Fetcher interface rather than *http.Client? (§2, §3 — "accept interfaces": a one-method behavior makes the pool testable with a fake (no network, deterministic failure paths) and swappable without a rewrite.)
• Who is allowed to close the results channel, and why does it matter? (§3 — exactly one goroutine, gated by wg.Wait(); closing twice or closing from a non-owning sender panics, so close-ownership is assigned to a single closer goroutine — CSP discipline from L09.)
• Give the honest GC cost of this service. (§4 — result slices are collected by a concurrent tri-color mark-sweep with sub-ms STW pauses, but the GC cannot be disabled, only tuned via GOGC; under a large live heap the p99.9 latency still shows it — a bounded but unavoidable cost, L03.)
• Explain the nil-interface trap and why a concurrent service is where it bites. (§4 — a typed nil pointer (*MyError) returned through an error interface becomes a non-nil (type, nil) pair, so err != nil is unexpectedly true; wrapping errors across goroutines is exactly where this hides, L05/L07.)
• You need retries; how do you add them without touching the pool? (Checkpoint, §4 — wrap the Fetcher interface in a decorator struct that retries internally (composition, not inheritance, L06); the pool is unchanged because it depends on the behavior, and you re-run go test -race.)