Boundaries — Find the Bug¶

12 snippets where the bug lives at a boundary — the seam between your code and a third party (a library, an SDK, an external API, the OS clock). The code compiles, the tests pass, and yet production breaks. The root cause is almost always the same: an assumption about the other side that was never true, or stopped being true on an upgrade. Find it first; the fix is almost always an abstraction layer you control.

Table of Contents¶

1. Snippet 1 — The mock that ignores pagination (Go)
2. Snippet 2 — Library default flips on upgrade (Python)
3. Snippet 3 — Shared SDK client, no thread safety (Java)
4. Snippet 4 — Wrapper swallows the error code (Go)
5. Snippet 5 — Library timezone leaks into domain logic (Python)
6. Snippet 6 — Library mutates the slice you still hold (Go)
7. Snippet 7 — Hyrum's Law: relying on undocumented ordering (Java)
8. Snippet 8 — Connection pool exhaustion: the resource never closes (Python)
9. Snippet 9 — Leaked library type changes a default field (Go)
10. Snippet 10 — Stubbing a return that the real API never returns (Java)
11. Snippet 11 — Locale-sensitive parsing at the boundary (Java)
12. Snippet 12 — JSON number becomes float, money loses cents (Python)
13. Scorecard
14. Related Topics

How to Use¶

For each snippet:

1. Read the code and the surrounding context (the caller, the test, the upgrade note).
2. Ask the boundary question: "What does my code assume about the other side — and is that assumption guaranteed?" A guarantee comes from a documented contract, not from "it worked when I tried it."
3. Locate the exact line where the assumption is made.
4. Open the answer. Confirm the bug, the root cause at the boundary, and the fix.

The recurring lesson: boundaries are where two sets of assumptions meet. The bug is rarely a typo — it is a contract you imagined. Mocks encode your imagination; production runs the real contract.

Snippet 1 — The mock that ignores pagination (Go)¶

Difficulty: ⭐⭐ Medium

// Production code that lists every active subscription for a customer.
type BillingAPI interface {
    ListSubscriptions(ctx context.Context, customerID string) ([]Subscription, error)
}

func CountActive(ctx context.Context, api BillingAPI, customerID string) (int, error) {
    subs, err := api.ListSubscriptions(ctx, customerID)
    if err != nil {
        return 0, err
    }
    active := 0
    for _, s := range subs {
        if s.Status == "active" {
            active++
        }
    }
    return active, nil
}

// Test
type fakeBilling struct{ subs []Subscription }

func (f *fakeBilling) ListSubscriptions(ctx context.Context, id string) ([]Subscription, error) {
    return f.subs, nil
}

func TestCountActive(t *testing.T) {
    api := &fakeBilling{subs: []Subscription{
        {Status: "active"}, {Status: "active"}, {Status: "canceled"},
    }}
    n, _ := CountActive(context.Background(), api, "cus_1")
    if n != 2 {
        t.Fatalf("want 2, got %d", n)
    }
}

The real Stripe-style client behind BillingAPI returns at most 100 items per page and sets a has_more flag; you must follow a cursor to get the rest.

What's wrong?

// The wrapper you own hides the cursor; the domain sees "all of them".
type StripeBilling struct{ client *stripe.Client }

func (s *StripeBilling) ListSubscriptions(ctx context.Context, customerID string) ([]Subscription, error) {
    var out []Subscription
    cursor := ""
    for {
        page, err := s.client.Subscriptions.List(ctx, customerID, cursor)
        if err != nil {
            return nil, err
        }
        out = append(out, page.Items...)
        if !page.HasMore {
            return out, nil
        }
        cursor = page.NextCursor
    }
}

Snippet 2 — Library default flips on upgrade (Python)¶

Difficulty: ⭐⭐ Medium

import requests

def fetch_report(report_id: str) -> dict:
    # Internal reporting service, slow on big reports.
    resp = requests.get(f"https://reports.internal/v1/{report_id}")
    resp.raise_for_status()
    return resp.json()

This shipped on requests==2.x and ran fine for a year. The team bumped a transitive dependency, which pulled in a new HTTP client used elsewhere, and someone "modernized" this call to the team's shared client wrapper:

# shared_http.py  (new internal wrapper, built on httpx)
import httpx

_client = httpx.Client()  # default timeout in httpx is 5 seconds

def get(url: str) -> httpx.Response:
    return _client.get(url)

def fetch_report(report_id: str) -> dict:
    resp = shared_http.get(f"https://reports.internal/v1/{report_id}")
    resp.raise_for_status()
    return resp.json()

What's wrong?

# shared_http.py
import httpx

# Choose deliberately; document the why. Reports can be slow.
DEFAULT_TIMEOUT = httpx.Timeout(connect=5.0, read=30.0, write=5.0, pool=5.0)

def get(url: str, *, timeout: httpx.Timeout = DEFAULT_TIMEOUT) -> httpx.Response:
    with httpx.Client(timeout=timeout) as client:
        return client.get(url)

Snippet 3 — Shared SDK client, no thread safety (Java)¶

Difficulty: ⭐⭐⭐ Hard

public final class S3Uploader {
    // Reuse one client for performance — recommended by the SDK docs.
    private static final AmazonS3 S3 = AmazonS3ClientBuilder.standard().build();

    public void upload(String bucket, String key, InputStream data, long length) {
        ObjectMetadata meta = new ObjectMetadata();
        meta.setContentLength(length);
        // The SDK's transfer config lives on a shared mutable field.
        meta.setSSEAlgorithm(currentTenant().requiresEncryption() ? "aws:kms" : null);
        S3.putObject(bucket, key, data, meta);
    }
}

Called concurrently from a request-handling thread pool, one call per upload, each with its own ObjectMetadata.

What's wrong?

public final class S3Uploader {
    private static final AmazonS3 S3 = AmazonS3ClientBuilder.standard().build();
    private final ObjectMetadata meta = new ObjectMetadata(); // hoisted "to avoid allocation"

    public void upload(String bucket, String key, InputStream data, long length) {
        meta.setContentLength(length);
        meta.setSSEAlgorithm(currentTenant().requiresEncryption() ? "aws:kms" : null);
        S3.putObject(bucket, key, data, meta); // shared mutable state across threads
    }
}

public final class S3Uploader {
    private final AmazonS3 s3; // injected, shared, thread-safe — OK

    public void upload(String bucket, String key, InputStream data,
                       long length, boolean encrypt) {
        ObjectMetadata meta = new ObjectMetadata(); // always per-call
        meta.setContentLength(length);
        if (encrypt) meta.setSSEAlgorithm("aws:kms");
        s3.putObject(bucket, key, data, meta);
    }
}

Snippet 4 — Wrapper swallows the error code (Go)¶

Difficulty: ⭐⭐ Medium

// A thin wrapper around the payments SDK.
func (p *Payments) Charge(ctx context.Context, amount Money, card string) error {
    _, err := p.sdk.CreateCharge(ctx, &sdk.ChargeRequest{
        Amount: amount.Cents(),
        Source: card,
    })
    if err != nil {
        return fmt.Errorf("charge failed: %w", err)
    }
    return nil
}

// Caller
func (s *OrderService) Pay(ctx context.Context, o *Order) error {
    if err := s.payments.Charge(ctx, o.Total, o.Card); err != nil {
        // Network blip or declined card — retry a few times.
        return s.retry(ctx, func() error {
            return s.payments.Charge(ctx, o.Total, o.Card)
        })
    }
    return nil
}

The SDK distinguishes a card declined (sdk.ErrCardDeclined, terminal — do not retry) from a transient gateway error (sdk.ErrGatewayTimeout, safe to retry).

What's wrong?

var (
    ErrPaymentDeclined  = errors.New("payment declined")  // terminal
    ErrPaymentTransient = errors.New("payment transient")  // retryable
)

func (p *Payments) Charge(ctx context.Context, amount Money, card string) error {
    _, err := p.sdk.CreateCharge(ctx, &sdk.ChargeRequest{Amount: amount.Cents(), Source: card})
    switch {
    case err == nil:
        return nil
    case errors.Is(err, sdk.ErrCardDeclined):
        return fmt.Errorf("%w: %v", ErrPaymentDeclined, err)
    case errors.Is(err, sdk.ErrGatewayTimeout):
        return fmt.Errorf("%w: %v", ErrPaymentTransient, err)
    default:
        return fmt.Errorf("charge failed: %w", err) // unknown → do not retry by default
    }
}

// Caller retries only the transient class.
func (s *OrderService) Pay(ctx context.Context, o *Order) error {
    err := s.payments.Charge(ctx, o.Total, o.Card)
    if errors.Is(err, ErrPaymentTransient) {
        return s.retry(ctx, func() error { return s.payments.Charge(ctx, o.Total, o.Card) })
    }
    return err
}

Snippet 5 — Library timezone leaks into domain logic (Python)¶

Difficulty: ⭐⭐⭐ Hard

from datetime import datetime

def is_within_business_day(scheduled_at: datetime) -> bool:
    """Reject orders scheduled outside Mon-Fri."""
    return scheduled_at.weekday() < 5  # 0=Mon ... 4=Fri

def parse_scheduled(payload: dict) -> datetime:
    # The client sends ISO 8601, e.g. "2026-06-13T22:30:00-06:00"
    return datetime.fromisoformat(payload["scheduled_at"])

# Usage
dt = parse_scheduled({"scheduled_at": "2026-06-13T22:30:00-06:00"})
ok = is_within_business_day(dt)

The business runs on UTC. Customers send timestamps with their local offset.

What's wrong?

from datetime import datetime, timezone

BUSINESS_TZ = timezone.utc  # the calendar the business actually runs on

def parse_scheduled(payload: dict) -> datetime:
    dt = datetime.fromisoformat(payload["scheduled_at"])
    if dt.tzinfo is None:
        raise ValueError("scheduled_at must include a timezone offset")
    return dt.astimezone(BUSINESS_TZ)  # normalize once, at the edge

def is_within_business_day(scheduled_at: datetime) -> bool:
    assert scheduled_at.tzinfo == BUSINESS_TZ, "must be normalized before domain use"
    return scheduled_at.weekday() < 5

Snippet 6 — Library mutates the slice you still hold (Go)¶

Difficulty: ⭐⭐⭐ Hard

import "sort"

func TopThree(scores []Score) []Score {
    // The caller still uses `scores` after this for an audit log,
    // and expects it in original (insertion) order.
    sort.Slice(scores, func(i, j int) bool {
        return scores[i].Value > scores[j].Value
    })
    if len(scores) > 3 {
        return scores[:3]
    }
    return scores
}

// Caller
func Report(scores []Score) {
    top := TopThree(scores)
    render(top)
    auditLog(scores) // expects original order, original length conceptually
}

What's wrong?

func TopThree(scores []Score) []Score {
    sorted := make([]Score, len(scores))
    copy(sorted, scores) // do not touch the caller's slice
    sort.Slice(sorted, func(i, j int) bool { return sorted[i].Value > sorted[j].Value })
    n := 3
    if len(sorted) < n {
        n = len(sorted)
    }
    return sorted[:n:n] // three-index slice: cap == len, no accidental aliasing
}

Snippet 7 — Hyrum's Law: relying on undocumented ordering (Java)¶

Difficulty: ⭐⭐⭐ Hard

// Build a canonical signature string from request params, then HMAC it.
public String sign(Map<String, String> params, String secret) {
    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, String> e : params.entrySet()) {
        sb.append(e.getKey()).append('=').append(e.getValue()).append('&');
    }
    return hmacSha256(sb.toString(), secret);
}

// Caller built the map like this and it always worked:
Map<String, String> params = new HashMap<>();
params.put("amount", "100");
params.put("currency", "USD");
params.put("nonce", "abc");
String sig = sign(params, secret);

Both client and server use this exact code to sign and verify. It has matched for two years on Java 8. The team upgrades the JVM.

What's wrong?

public String sign(Map<String, String> params, String secret) {
    // Specify the order; do not inherit it from the map implementation.
    StringBuilder sb = new StringBuilder();
    new TreeMap<>(params).forEach((k, v) ->
        sb.append(k).append('=').append(v).append('&'));
    return hmacSha256(sb.toString(), secret);
}

Snippet 8 — Connection pool exhaustion: the resource never closes (Python)¶

Difficulty: ⭐⭐ Medium

import psycopg2.pool

pool = psycopg2.pool.SimpleConnectionPool(minconn=1, maxconn=10, dsn=DSN)

def get_user(user_id: int) -> dict | None:
    conn = pool.getconn()
    cur = conn.cursor()
    cur.execute("SELECT id, email FROM users WHERE id = %s", (user_id,))
    row = cur.fetchone()
    if row is None:
        return None          # early return
    return {"id": row[0], "email": row[1]}

This endpoint gets ~50 requests/second. After a few minutes under load, every request hangs.

What's wrong?

from contextlib import contextmanager

@contextmanager
def borrow_conn():
    conn = pool.getconn()
    try:
        yield conn
    finally:
        pool.putconn(conn)   # always returned, even on exception/early return

def get_user(user_id: int) -> dict | None:
    with borrow_conn() as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT id, email FROM users WHERE id = %s", (user_id,))
            row = cur.fetchone()
    if row is None:
        return None
    return {"id": row[0], "email": row[1]}

Snippet 9 — Leaked library type changes a default field (Go)¶

Difficulty: ⭐⭐⭐ Hard

import "github.com/some/jwtlib"

// jwtlib.Claims is the library's struct; we pass it around the whole codebase.
func IssueToken(userID string) (string, error) {
    claims := jwtlib.Claims{
        Subject: userID,
        // ExpiresAt left as zero value
    }
    return jwtlib.Sign(claims, signingKey)
}

func Authorize(token string) (string, error) {
    claims, err := jwtlib.Verify(token, signingKey)
    if err != nil {
        return "", err
    }
    return claims.Subject, nil
}

On jwtlib v1, an unset ExpiresAt (zero value) meant "no expiry" and Verify accepted it. The team upgrades to jwtlib v2, where the maintainers — citing security — changed Verify to reject tokens without an ExpiresAt by default.

What's wrong?

type Token struct {
    UserID string
    TTL    time.Duration
}

func (t Token) sign(key []byte) (string, error) {
    if t.TTL <= 0 {
        return "", errors.New("token TTL must be set") // your policy, explicit
    }
    claims := jwtlib.Claims{
        Subject:   t.UserID,
        ExpiresAt: time.Now().Add(t.TTL).Unix(), // always set
    }
    return jwtlib.Sign(claims, key)
}

Snippet 10 — Stubbing a return that the real API never returns (Java)¶

Difficulty: ⭐⭐ Medium

public interface GeocodingClient {
    Coordinates geocode(String address); // returns coordinates for an address
}

public class DeliveryRouter {
    private final GeocodingClient geocoder;

    public Route planRoute(String fromAddress, String toAddress) {
        Coordinates from = geocoder.geocode(fromAddress);
        Coordinates to = geocoder.geocode(toAddress);
        return Route.between(from, to); // uses from.lat, from.lng, ...
    }
}

// Test
@Test
void planRoute_buildsRouteBetweenCoordinates() {
    GeocodingClient stub = mock(GeocodingClient.class);
    when(stub.geocode(anyString()))
        .thenReturn(new Coordinates(40.0, -73.0)); // always a valid result
    Route route = new DeliveryRouter(stub).planRoute("A St", "B Ave");
    assertNotNull(route);
}

The real geocoding service returns null (or an empty result) when an address is not found — a routine outcome for typos and PO boxes, not an exception.

What's wrong?

public interface GeocodingClient {
    Optional<Coordinates> geocode(String address); // not-found is in the type
}

public Route planRoute(String fromAddress, String toAddress) {
    Coordinates from = geocoder.geocode(fromAddress)
        .orElseThrow(() -> new AddressNotFound(fromAddress));
    Coordinates to = geocoder.geocode(toAddress)
        .orElseThrow(() -> new AddressNotFound(toAddress));
    return Route.between(from, to);
}

Snippet 11 — Locale-sensitive parsing at the boundary (Java)¶

Difficulty: ⭐⭐⭐ Hard

// Parse a price from an incoming partner CSV feed.
public BigDecimal parsePrice(String raw) {
    // raw looks like "1,234.56"
    NumberFormat nf = NumberFormat.getInstance(); // uses the JVM default locale
    return new BigDecimal(nf.parse(raw).toString());
}

The integration was developed and tested on machines configured with the US locale. The service is later deployed to a region where the host's default locale is German (de-DE), where . is the thousands separator and , is the decimal separator.

What's wrong?

public BigDecimal parsePrice(String raw) {
    // The partner feed is documented as en-US numeric format. Pin it.
    DecimalFormat fmt = (DecimalFormat) NumberFormat.getInstance(Locale.US);
    fmt.setParseBigDecimal(true);
    try {
        return (BigDecimal) fmt.parse(raw);
    } catch (ParseException e) {
        throw new IllegalArgumentException("malformed price: " + raw, e);
    }
}

Snippet 12 — JSON number becomes float, money loses cents (Python)¶

Difficulty: ⭐⭐ Medium

import json

def total_from_payload(body: bytes) -> float:
    data = json.loads(body)
    total = 0.0
    for line in data["lines"]:
        total += line["price"] * line["qty"]
    return total

# Incoming payload (from an upstream service that sends money as JSON numbers)
# {"lines": [{"price": 0.10, "qty": 3}, {"price": 0.20, "qty": 1}]}

What's wrong?

import json
from decimal import Decimal

def total_from_payload(body: bytes) -> Decimal:
    data = json.loads(body, parse_float=Decimal)  # JSON floats -> Decimal at the edge
    total = Decimal("0")
    for line in data["lines"]:
        total += Decimal(line["price"]) * Decimal(line["qty"])
    return total

Scorecard¶

Tally what you caught before opening each answer.

Scoring (caught before the answer):

• 11–12 — You think in contracts, not in code that "worked once." You instinctively ask what the other side guarantees.
• 8–10 — Strong boundary instincts. Tighten up on defaults and zero-value semantics, the quietest of the failure modes.
• 5–7 — You catch the loud ones (resources, errors). Study the silent ones: defaults, timezones, ordering, lossy types.
• 0–4 — Re-read junior.md and tasks.md. The pattern to internalize: every boundary is a contract, and you only control your half.

The throughline across all twelve: the bug was never in the third party. It was in an assumption your code made about the third party — a contract you imagined, a default you inherited, a mock that agreed with your imagination instead of reality. The fix is always the same shape: own a thin layer at the boundary that makes every assumption explicit, translates the real contract into your domain's terms, and confines the third party's quirks to one place you can test and change.

Related Topics¶

• README.md — the positive rules: separation, learning tests, adapters, and the boundary interface you own.
• junior.md — the beginner-level walkthrough of what a boundary is and why it matters.
• tasks.md — exercises: wrap a real SDK, write a learning test, and replace a leaked type with an adapter.
• ../../anti-patterns/README.md — boundary-adjacent anti-patterns to recognize and avoid.
• ../../refactoring/README.md — refactoring techniques (Extract Class, Introduce Adapter) used to retrofit a boundary onto code that leaked a third-party type.