Go Katas

The Katas are organized into six thematic groups. You can choose a challenge based on the specific Go area you wish to master:

• 01) Context, Cancellation, and Fail-Fast Concurrency: Focuses on preventing leaks, enforcing backpressure, and handling cancellation (e.g., 01 - The Fail-Fast Data Aggregator, 10 - Worker Pool with Backpressure).
• 02) Performance, Allocation, and Throughput: Focuses on memory efficiency and high-throughput (e.g., 02 - Concurrent Map with Sharded Locks, 04 - Zero-Allocation JSON Parser).
• 03) HTTP and Middleware Engineering: Focuses on idiomatic HTTP patterns and middleware (e.g., 06 - Interface-Based Middleware Chain).
• 04) Errors: Semantics, Wrapping, and Edge Cases: Focuses on modern error handling and pitfalls (e.g., 08 - Retry Policy That Respects Context, 20 - The “nil != nil” Interface Trap).
• 05) Filesystems, Packaging, and Deployment Ergonomics: Focuses on portable binaries and testable filesystem code (e.g., 13 - Filesystem-Agnostic Config Loader (io/fs)).
• 06) Testing and Quality Gates: Focuses on idiomatic testing patterns like table-driven tests and fuzzing (e.g., 15 - Go Test Harness).

When performing cleanup in a defer block, a common mistake is to ignore errors returned by Close() or Rollback(), or to overwrite the original error.

To implement idiomatic error preservation:

1. Use a named return parameter (e.g., err error) in your function signature.
2. Inside your defer block, check if the cleanup operation returns an error.
3. If the cleanup fails, use errors.Join to combine the existing error with the new cleanup error. This ensures the caller receives both the root cause and the cleanup failure.

Example Pattern

func DoWork() (err error) {
    res, err := acquireResource()
    if err != nil {
        return err
    }
    defer func() {
        if closeErr := res.Close(); closeErr != nil {
            // Join the original error with the cleanup error
            err = errors.Join(err, closeErr)
        }
    }()

    // ... perform work ...
    return nil
}

Each kata in this repository follows a standardized template designed to teach Go-specific idioms through practical challenges. When working through a kata, you should follow this structure:

1. Target Idioms & Difficulty: Identifies the specific Go patterns being tested (e.g., Concurrency Patterns, Interface Pollution) and the expected skill level.
2. The "Why": Explains the rationale behind the challenge, specifically highlighting why non-Go patterns (like those from Java or Python) are inappropriate for the problem.
3. The Scenario: Provides a realistic production context for the problem.
4. The Challenge: Divided into two critical parts:
   • Functional Requirements: The basic features the code must implement.
   • Idiomatic Constraints: The specific Go patterns you must use to pass (e.g., avoiding allocations in loops, using functional options, or error wrapping).
5. Self-Correction: A guide to help you identify if you have implemented a solution in an un-idiomatic or dangerous way and how to fix it.
6. Resources: Links to official Go documentation or blog posts to support your learning.

This kata challenges you to implement a sanitizer function and a robust test suite using idiomatic Go testing patterns.

Scenario

Implement a function func NormalizeHeaderKey(s string) (string, error) that:

• Allows only ASCII letters, digits, and hyphens.
• Normalizes input to canonical header form (e.g., content-type becomes Content-Type).
• Rejects invalid input.

Functional Requirements

• Canonicalize valid inputs.
• Reject invalid characters.
• Ensure stable behavior (the same input must always produce the same output).

Idiomatic Constraints (Pass/Fail Criteria)

To complete the kata successfully, your test suite must meet these criteria:

1. Table-Driven Tests: Use t.Run to organize test cases.
2. Parallel Subtests: Use t.Parallel() correctly within subtests, ensuring you avoid loop variable capture bugs.
3. Fuzz Testing: Implement a fuzz test (go test -fuzz) that verifies:
   • The implementation never panics.
   • The output never contains invalid characters.
   • The operation is idempotent (calling NormalizeHeaderKey twice on the same input returns the same result).

Kata 01 is an intermediate-level Go exercise focused on mastering concurrency control, context propagation, and the functional options pattern. The goal is to build a UserAggregator that fetches data from multiple mock services (e.g., Profile and Order services) in parallel, ensuring that if any single request fails or a timeout occurs, all other pending operations are cancelled immediately to save resources.

Functional Requirements

• The aggregator must be configurable (e.g., timeout, logger) using the Functional Options Pattern to avoid large constructors.
• Services must be queried concurrently.
• The final output must combine results from all services (e.g., "User: Alice | Orders: 5").

Idiomatic Constraints (Pass/Fail Criteria)

To successfully complete this kata, you must follow these Go best practices:

• Use golang.org/x/sync/errgroup: Do not use sync.WaitGroup. errgroup provides the necessary error propagation and context cancellation that WaitGroup lacks.
• Use Functional Options: Implement the constructor using the pattern New(WithTimeout(2s)) instead of passing many parameters.
• Context Propagation: Always pass context.Context as the first argument to methods.
• Immediate Cleanup: Ensure that if one service fails, the context is cancelled so that other service requests abort immediately.
• Structured Logging: Use the log/slog package for logging.

This kata challenges you to implement a streaming NDJSON (Newline Delimited JSON) reader capable of handling arbitrarily large lines (e.g., > 64KB) that would cause a standard bufio.Scanner to fail with bufio.Scanner: token too long.

Implementation Task

Implement the following function signature: func ReadNDJSON(ctx context.Context, r io.Reader, handle func([]byte) error) error

Functional Requirements

• Call handle(line) for each line, providing the line content without the trailing newline.
• Stop execution immediately if handle returns an error.
• Stop execution immediately if the provided context.Context is cancelled (ctx.Done()).

Idiomatic Constraints (Pass/Fail Criteria)

To pass this kata, your implementation must meet these specific Go idioms:

• Avoid bufio.Scanner: Do not rely on the default bufio.Scanner behavior, as it has a fixed buffer limit.
• Use bufio.Reader: Use bufio.Reader and correctly handle the ErrBufferFull error returned by ReadSlice('\n') to manage lines larger than the buffer.
• Low Allocation: Avoid per-line allocations by reusing buffers.
• Error Wrapping: Wrap errors with line number context using the %w verb.

This kata challenges you to implement a configuration loader that is decoupled from the OS filesystem by using the io/fs abstraction. Instead of passing string paths to os.Open, you should design an API that accepts an fs.FS interface. This allows the loader to work seamlessly with local disks, embedded files (via embed), ZIP files, or in-memory filesystems for testing.

Implementation Task

Implement the following function signature: func LoadConfigs(fsys fs.FS, root string) (map[string][]byte, error)

Functional Requirements

• Recursively walk the root directory.
• Identify and read all files ending in .conf.
• Return a map where keys are the file paths and values are the file contents (map[string][]byte).
• Handle invalid paths gracefully by returning an error.

Idiomatic Constraints (Pass/Fail Criteria)

To successfully complete this kata, your implementation must adhere to these Go idioms:

• Use fs.FS abstraction: The core API must accept an fs.FS interface, not raw OS paths.
• Use io/fs primitives: You must use fs.WalkDir and fs.ReadFile.
• Avoid os package coupling: Do NOT use os.Open or filepath.Walk inside the core loader logic.
• Test with fstest.MapFS: Unit tests must be able to run without touching the real filesystem by using testing/fstest.MapFS to mock the filesystem.