devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/go/references/concurrency.md

@@ -0,0 +1,335 @@
+# Go Concurrency Patterns
+
+Advanced concurrency patterns for Go. Reference from main SKILL.md.
+Sources in `sources.md`.
+
+Go's concurrency model derives from Hoare's Communicating Sequential Processes (CSP) [9].
+Goroutines are independently-executing functions; channels are typed conduits for communication.
+The guiding principle: "Do not communicate by sharing memory; share memory by communicating." [10]
+
+---
+
+## errgroup for Structured Concurrency [22][13]
+
+`errgroup` (golang.org/x/sync) provides structured concurrency: a group of goroutines
+where the first error cancels the group. [22]
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    responses := make([]Response, len(urls))
+
+    for i, url := range urls {
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return fmt.Errorf("fetching %s: %w", url, err)
+            }
+            responses[i] = resp // Safe: each goroutine writes to unique index
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return responses, nil
+}
+```
+
+### errgroup with Concurrency Limit [22][13]
+
+```go
+func ProcessItems(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(10) // Maximum 10 concurrent goroutines
+
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+---
+
+## Worker Pool [13][10]
+
+Channel-based worker pool following the CSP communication model [9][10].
+Channels pass ownership of data; `context.Done()` cancels work cooperatively. [16]
+
+```go
+func WorkerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
+    results := make(chan Result, workers)
+
+    var wg sync.WaitGroup
+    for range workers {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for {
+                select {
+                case job, ok := <-jobs:
+                    if !ok {
+                        return
+                    }
+                    results <- process(ctx, job)
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+
+// Usage
+jobs := make(chan Job, 100)
+results := WorkerPool(ctx, jobs, 5)
+
+go func() {
+    defer close(jobs)
+    for _, j := range allJobs {
+        jobs <- j
+    }
+}()
+
+for r := range results {
+    fmt.Println(r)
+}
+```
+
+---
+
+## Fan-Out / Fan-In [13][9]
+
+Pipeline pattern from CSP theory [9]: fan-out distributes one input stream across
+multiple workers; fan-in merges multiple streams back into one. [13]
+
+```go
+// Fan-out: one source, multiple workers
+func fanOut(ctx context.Context, input <-chan int, workers int) []<-chan int {
+    channels := make([]<-chan int, workers)
+    for i := range workers {
+        channels[i] = worker(ctx, input)
+    }
+    return channels
+}
+
+func worker(ctx context.Context, input <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for n := range input {
+            select {
+            case out <- n * n:
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+
+// Fan-in: multiple sources, one destination
+func fanIn(ctx context.Context, channels ...<-chan int) <-chan int {
+    merged := make(chan int)
+    var wg sync.WaitGroup
+
+    for _, ch := range channels {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for val := range ch {
+                select {
+                case merged <- val:
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(merged)
+    }()
+
+    return merged
+}
+```
+
+---
+
+## Select with Timeout [16][13]
+
+`select` implements the alternation operator from CSP [9]: choose the first
+ready channel. `context.WithTimeout` integrates deadline propagation. [16]
+
+```go
+func fetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    ch := make(chan result, 1)
+    go func() {
+        data, err := doFetch(ctx, url)
+        ch <- result{data, err}
+    }()
+
+    select {
+    case r := <-ch:
+        return r.data, r.err
+    case <-ctx.Done():
+        return nil, fmt.Errorf("fetch %s: %w", url, ctx.Err())
+    }
+}
+
+type result struct {
+    data []byte
+    err  error
+}
+```
+
+### Select for Multiple Sources [8][9]
+
+```go
+func merge(ctx context.Context, primary, fallback <-chan Event) <-chan Event {
+    out := make(chan Event)
+    go func() {
+        defer close(out)
+        for {
+            select {
+            case e, ok := <-primary:
+                if !ok {
+                    return
+                }
+                out <- e
+            case e, ok := <-fallback:
+                if !ok {
+                    return
+                }
+                out <- e
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+---
+
+## Mutex vs Channels [8][10]
+
+Go proverb: "channels orchestrate; mutexes serialize." [7] The Go Memory Model
+defines the happens-before rules for both synchronization primitives. [8]
+
+### Use Mutex When [8]
+
+```go
+// Protecting shared state with simple read/write [8]
+type SafeCounter struct {
+    mu sync.RWMutex
+    v  map[string]int
+}
+
+func (c *SafeCounter) Inc(key string) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.v[key]++
+}
+
+func (c *SafeCounter) Get(key string) int {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    return c.v[key]
+}
+```
+
+### Use Channels When [10][9]
+
+```go
+// Communicating between goroutines / coordinating work [10]
+func pipeline(ctx context.Context, input []int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for _, n := range input {
+            select {
+            case out <- transform(n):
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+### Decision Guide [8][10][13]
+
+| Scenario | Use | Source |
+|----------|-----|--------|
+| Guarding shared state | `sync.Mutex` or `sync.RWMutex` | [8] |
+| Passing ownership of data | Channels | [10][9] |
+| Coordinating goroutine lifecycle | `context.Context` + channels | [16] |
+| Waiting for N goroutines | `sync.WaitGroup` or `errgroup` | [22] |
+| One-time initialization | `sync.Once` | [8] |
+| Concurrent map access | `sync.Map` (high read, low write) | [8] |
+
+---
+
+## sync.Once for Initialization [8][12]
+
+`sync.Once` guarantees a function runs exactly once, regardless of concurrent callers.
+The Go Memory Model guarantees visibility of the function's effects to all goroutines. [8]
+
+```go
+type Client struct {
+    once sync.Once
+    conn *grpc.ClientConn
+    err  error
+}
+
+func (c *Client) connection() (*grpc.ClientConn, error) {
+    c.once.Do(func() {
+        c.conn, c.err = grpc.Dial("localhost:50051",
+            grpc.WithTransportCredentials(insecure.NewCredentials()))
+    })
+    return c.conn, c.err
+}
+```
+
+---
+
+## Rate Limiting [13]
+
+```go
+// golang.org/x/time/rate implements the token bucket algorithm [13]
+func rateLimited(ctx context.Context, items []Item, rps int) error {
+    limiter := rate.NewLimiter(rate.Limit(rps), 1)
+
+    for _, item := range items {
+        if err := limiter.Wait(ctx); err != nil {
+            return fmt.Errorf("rate limiter: %w", err)
+        }
+        if err := process(ctx, item); err != nil {
+            return fmt.Errorf("processing item %s: %w", item.ID, err)
+        }
+    }
+    return nil
+}
+```

package/src/assets/skills/go/references/patterns.md

@@ -0,0 +1,278 @@
+# Go Correct Patterns
+
+Extended correct patterns for Go development. Reference from main SKILL.md.
+Sources in `sources.md`.
+
+## Table-Driven Tests [18]
+
+The idiomatic Go testing approach: define cases in a struct slice, range over them
+with `t.Run`. Fuzzing and benchmarks use the same `testing.T` conventions. [18]
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -1, -2, -3},
+        {"zero", 0, 0, 0},
+        {"mixed signs", -1, 3, 2},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+---
+
+## Functional Options [1][12]
+
+Enables optional configuration without breaking API changes. Preferred over config
+structs when options have non-trivial defaults. [12]
+
+```go
+type Server struct {
+    addr    string
+    timeout time.Duration
+    logger  *slog.Logger
+}
+
+type Option func(*Server)
+
+func WithAddr(addr string) Option {
+    return func(s *Server) { s.addr = addr }
+}
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) { s.timeout = d }
+}
+
+func WithLogger(l *slog.Logger) Option {
+    return func(s *Server) { s.logger = l }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{
+        addr:    ":8080",          // sensible default
+        timeout: 30 * time.Second, // sensible default
+        logger:  slog.Default(),
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+srv := NewServer(
+    WithAddr(":9090"),
+    WithTimeout(60*time.Second),
+)
+```
+
+---
+
+## Custom Error Types [1][6]
+
+Use custom types when callers need to inspect error fields. Use `errors.As` for
+type-based unwrapping, `errors.Is` for sentinel values. [6]
+
+```go
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+type NotFoundError struct {
+    Resource string
+    ID       string
+}
+
+func (e *NotFoundError) Error() string {
+    return fmt.Sprintf("%s %s not found", e.Resource, e.ID)
+}
+
+// Usage with errors.As
+func handleErr(err error) {
+    var validErr *ValidationError
+    if errors.As(err, &validErr) {
+        log.Printf("bad input: field=%s msg=%s", validErr.Field, validErr.Message)
+        return
+    }
+    var notFound *NotFoundError
+    if errors.As(err, &notFound) {
+        log.Printf("missing: %s/%s", notFound.Resource, notFound.ID)
+        return
+    }
+    log.Printf("unexpected: %v", err)
+}
+```
+
+---
+
+## Middleware Pattern [1][3]
+
+HTTP middleware chains following the `func(http.Handler) http.Handler` convention.
+Standard library `net/http` uses this pattern natively. [1]
+
+```go
+type Middleware func(http.Handler) http.Handler
+
+func Logging(logger *slog.Logger) Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            start := time.Now()
+            next.ServeHTTP(w, r)
+            logger.Info("request",
+                "method", r.Method,
+                "path", r.URL.Path,
+                "duration", time.Since(start),
+            )
+        })
+    }
+}
+
+func Recovery() Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            defer func() {
+                if err := recover(); err != nil {
+                    w.WriteHeader(http.StatusInternalServerError)
+                    slog.Error("panic recovered", "error", err)
+                }
+            }()
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+
+// Chain composes middleware in order
+func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
+    for i := len(middlewares) - 1; i >= 0; i-- {
+        handler = middlewares[i](handler)
+    }
+    return handler
+}
+
+mux := http.NewServeMux()
+mux.HandleFunc("/api/users", handleUsers)
+handler := Chain(mux, Recovery(), Logging(logger))
+```
+
+---
+
+## Graceful Shutdown [1][16]
+
+Context-aware shutdown propagation. `context.WithTimeout` ensures the shutdown
+completes within a deadline. [16]
+
+```go
+func main() {
+    srv := &http.Server{Addr: ":8080", Handler: mux}
+
+    go func() {
+        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
+            slog.Error("server error", "error", err)
+        }
+    }()
+
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    if err := srv.Shutdown(ctx); err != nil {
+        slog.Error("shutdown error", "error", err)
+    }
+    slog.Info("server stopped")
+}
+```
+
+---
+
+## Constructor Pattern [1][2]
+
+Enforce invariants at construction time. Return an error rather than a zero-value
+struct that might be used incorrectly. [1][2]
+
+```go
+// Validate at construction — enforce invariants
+func NewUser(name, email string) (*User, error) {
+    if name == "" {
+        return nil, &ValidationError{Field: "name", Message: "required"}
+    }
+    if !strings.Contains(email, "@") {
+        return nil, &ValidationError{Field: "email", Message: "invalid format"}
+    }
+    return &User{
+        ID:        uuid.New().String(),
+        Name:      name,
+        Email:     email,
+        CreatedAt: time.Now(),
+    }, nil
+}
+```
+
+---
+
+## Structured Logging with slog [19]
+
+`slog` (Go 1.21+) is the standard structured logging package. Use `slog.With` to
+attach request-scoped context once, then log with key-value pairs throughout. [19]
+
+```go
+func ProcessOrder(ctx context.Context, orderID string) error {
+    logger := slog.With("order_id", orderID, "trace_id", traceID(ctx))
+
+    logger.Info("processing order")
+
+    items, err := fetchItems(ctx, orderID)
+    if err != nil {
+        logger.Error("failed to fetch items", "error", err)
+        return fmt.Errorf("fetching items for order %s: %w", orderID, err)
+    }
+
+    logger.Info("items fetched", "count", len(items))
+    return nil
+}
+```
+
+---
+
+## Generics — Type Constraints [11]
+
+Go 1.18+ generics use type constraints to express which types are valid. Prefer
+concrete constraints over `any` when possible. [11]
+
+```go
+type Number interface {
+    ~int | ~int64 | ~float64
+}
+
+func Sum[T Number](values []T) T {
+    var total T
+    for _, v := range values {
+        total += v
+    }
+    return total
+}
+
+// Usage — type inferred from arguments
+total := Sum([]int{1, 2, 3})         // 6
+total64 := Sum([]float64{1.1, 2.2})  // 3.3
+```

package/src/assets/skills/go/references/sources.md

@@ -0,0 +1,41 @@
+# Go — Sources
+
+## Primary References
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 1 | Effective Go | Go Team | 2024 | [Free](https://go.dev/doc/effective_go) | Error handling, interfaces, concurrency, naming, package design |
+| 2 | Go Code Review Comments | Go Wiki | 2024 | [Free](https://go.dev/wiki/CodeReviewComments) | Idiomatic Go review guidelines, error strings, context usage |
+| 3 | Google Go Style Guide | Google | 2024 | [Free](https://google.github.io/styleguide/go/) | Best practices, decisions, style, naming |
+| 4 | Uber Go Style Guide | Uber | 2024 | [Free](https://github.com/uber-go/guide) | Production Go patterns, error handling, performance |
+| 5 | "Errors are values" | Rob Pike | 2015 | [Free](https://go.dev/blog/errors-are-values) | Error handling philosophy, errors as first-class values |
+| 6 | "Don't just check errors, handle them gracefully" | Dave Cheney | 2016 | [Free](https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully) | Error wrapping, sentinel errors, behavior-based checking |
+| 7 | Go Proverbs | Rob Pike | 2015 | [Free](https://go-proverbs.github.io) | Core Go philosophy: interface size, concurrency, clarity |
+| 8 | Go Memory Model | Go Team | 2024 | [Free](https://go.dev/ref/mem) | Happens-before, synchronization guarantees, channel rules |
+| 9 | "Communicating Sequential Processes" | C.A.R. Hoare | 1978 | [Free](https://doi.org/10.1145/359576.359585) | CSP theory — foundation for goroutines and channels |
+| 10 | "Share Memory By Communicating" | Go Blog | 2010 | [Free](https://go.dev/blog/codelab-share) | Channel-first concurrency philosophy |
+| 11 | Go Generics Tutorial | Go Team | 2024 | [Free](https://go.dev/doc/tutorial/generics) | Type parameters, constraints, generic functions |
+| 12 | "100 Go Mistakes and How to Avoid Them" | Teiva Harsanyi | 2022 | Purchase | Comprehensive catalog of common Go pitfalls |
+| 13 | "Concurrency in Go" | Katherine Cox-Buday | 2017 | Purchase | Concurrency patterns, pipelines, context, goroutine management |
+| 14 | "Accept Interfaces, Return Structs" | Jack Lindamood | 2016 | [Free](https://medium.com/@cep21/what-accept-interfaces-return-structs-means-in-go-2fe879e25ee8) | Interface design principle, producer vs consumer interfaces |
+| 15 | Go Package Layout | Ben Johnson | 2016 | [Free](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1) | Standard project structure, domain-oriented packages |
+| 16 | context package documentation | Go Team | 2024 | [Free](https://pkg.go.dev/context) | Context propagation, cancellation, deadlines, values |
+| 17 | "Organizing Go code" | Andrew Gerrand | 2012 | [Free](https://go.dev/blog/organizing-go-code) | Package design, naming, public APIs |
+| 18 | Go testing package | Go Team | 2024 | [Free](https://pkg.go.dev/testing) | Table-driven tests, benchmarks, fuzzing, subtests |
+| 19 | Structured Logging with slog | Go Team | 2023 | [Free](https://go.dev/blog/slog) | slog package patterns, structured key-value logging |
+| 20 | "Practical Go" | Dave Cheney | 2020 | [Free](https://dave.cheney.net/practical-go/presentations/qcon-china.html) | Idiomatic Go: naming, packages, error handling, concurrency |
+
+## Standards & Style Guides
+
+| # | Source | Org | Access | Topics |
+|---|--------|-----|--------|--------|
+| 21 | Go Spec — Type System | Go Team | [Free](https://go.dev/ref/spec) | Interface satisfaction, type assertions, embedding |
+| 22 | errgroup package | golang.org/x/sync | [Free](https://pkg.go.dev/golang.org/x/sync/errgroup) | Structured concurrency, goroutine groups, error propagation |
+| 23 | golang.org/x/sync documentation | Go Team | [Free](https://pkg.go.dev/golang.org/x/sync) | Advanced synchronization primitives |
+
+## Academic & Research
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 24 | "Towards a Theory of Type Structure" | John C. Reynolds | 1974 | Free | Foundational types as proofs of properties |
+| 25 | "Go at Google: Language Design in the Service of Software Engineering" | Rob Pike | 2012 | [Free](https://go.dev/talks/2012/splash.article) | Go design rationale, simplicity, dependency management |