@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lit-code/references/go/concurrency.md

@@ -0,0 +1,362 @@
+# Concurrency
+
+Goroutines, context, errgroup, channels, locks, and the discipline that keeps them from leaking. Go makes concurrency *easy to start* and *easy to get wrong*. This document is the boring rule set.
+
+---
+
+## The four non-negotiables
+
+1. **`ctx context.Context` is the first parameter of every public function that does I/O or can be cancelled.**
+2. **No goroutine without a shutdown path.** Every `go` keyword must answer "how does this stop?".
+3. **`-race` on every test run.** The `Taskfile.yml` and CI both enforce it.
+4. **`goleak` in `TestMain`** for every package that spawns goroutines. Catches leaks the race detector cannot.
+
+---
+
+## `context.Context` — the cancellation backbone
+
+```go
+// GOOD — ctx as first param, propagated through
+func (s *UserService) Create(ctx context.Context, email Email) (User, error) {
+    user, err := s.store.Insert(ctx, email)
+    if err != nil {
+        return User{}, fmt.Errorf("insert: %w", err)
+    }
+    if err := s.notifier.Welcome(ctx, user); err != nil {
+        return User{}, fmt.Errorf("notify: %w", err)
+    }
+    return user, nil
+}
+
+// BAD — creates a fresh ctx, breaks request cancellation
+func (s *UserService) Create(email Email) (User, error) {
+    ctx := context.Background()  // ← contextcheck linter rejects this
+    // ...
+}
+```
+
+The `contextcheck` linter (enabled in `golangci-strict.md`) refuses any function that has `ctx context.Context` available but uses `context.Background()` instead.
+
+### `context.Value` — use sparingly
+
+```go
+// Typed key — never use a bare string
+type ctxKey struct{ name string }
+var requestIDKey = ctxKey{"request_id"}
+
+func WithRequestID(ctx context.Context, id string) context.Context {
+    return context.WithValue(ctx, requestIDKey, id)
+}
+
+func RequestID(ctx context.Context) string {
+    v, _ := ctx.Value(requestIDKey).(string)
+    return v
+}
+```
+
+**Rules**:
+- Keys are unexported struct types, not strings. Prevents collisions across packages.
+- `context.Value` is for *request-scoped metadata* (request ID, auth subject, trace span), NEVER for application-scoped dependencies.
+- Dependencies (loggers, DB pools, config) go in your service struct, not in `context.Value`.
+
+### `WithTimeout` / `WithCancel` — always pair with `defer cancel()`
+
+```go
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()  // ← MUST be deferred. fatcontext linter catches misses.
+
+if err := slow(ctx); err != nil { ... }
+```
+
+Forgetting `defer cancel()` leaks a context goroutine until the parent expires — the `lostcancel` vet check catches it.
+
+---
+
+## `errgroup` — the structured concurrency primitive
+
+`golang.org/x/sync/errgroup` is Go's answer to Python's `asyncio.TaskGroup` or Rust's `JoinSet`. Use it instead of raw `go` for any group of related goroutines.
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(8)  // concurrency cap — leave unbounded = production outage
+
+    results := make([][]byte, len(urls))
+    for i, u := range urls {
+        g.Go(func() error {
+            body, err := fetch(ctx, u)
+            if err != nil {
+                return fmt.Errorf("fetch %s: %w", u, err)
+            }
+            results[i] = body
+            return nil
+        })
+    }
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return results, nil
+}
+```
+
+Properties:
+
+- `WithContext(parent)` returns a child ctx that gets cancelled on **first non-nil error**. All in-flight goroutines see `ctx.Done()` and bail.
+- `SetLimit(n)` blocks `g.Go(...)` when the in-flight count hits `n`. **Always set this.** Unbounded fan-out is how services die.
+- `g.Wait()` returns the **first** non-nil error. Others are dropped. If you need all errors, accumulate them manually:
+  ```go
+  var mu sync.Mutex
+  var errs []error
+  // inside g.Go:
+  //   mu.Lock(); errs = append(errs, err); mu.Unlock()
+  // after Wait, errors.Join(errs...)
+  ```
+
+---
+
+## Goroutine leaks — `goleak`
+
+```go
+package store_test
+
+import (
+    "testing"
+    "go.uber.org/goleak"
+)
+
+func TestMain(m *testing.M) {
+    goleak.VerifyTestMain(m)
+}
+```
+
+This single line at the top of `*_test.go` runs goleak's check after every test in the package. If a test leaks a goroutine, the run fails — pointing at which goroutine.
+
+**The bug it catches**: starting a goroutine in `setUp` and never joining it. Common in DB connection pools, background workers, ticker loops. The race detector does NOT catch this.
+
+If you have a known long-lived goroutine (a singleton background worker, a metrics exporter), use `goleak.IgnoreTopFunction`:
+
+```go
+goleak.VerifyTestMain(m,
+    goleak.IgnoreTopFunction("github.com/example/metrics.(*Registry).Push"),
+)
+```
+
+---
+
+## Channels — the rules that hold
+
+### Direction
+
+```go
+// GOOD — direction in signatures
+func produce(out chan<- Item)
+func consume(in <-chan Item)
+func pipeline(in <-chan Item, out chan<- Item)
+```
+
+Direction restricts misuse. A consumer cannot close the producer's channel.
+
+### Closing
+
+- **The sender closes.** Always. Never the receiver, never multiple senders.
+- **Multiple senders → use a `sync.WaitGroup` + one closer.**
+- **Closing a closed channel panics.** Closing a `nil` channel panics. Sending on a closed channel panics. Receiving from a closed channel returns zero value with `ok = false`.
+
+```go
+// Canonical fan-in: multiple producers, one closer
+func fanIn(ctx context.Context, sources ...<-chan Item) <-chan Item {
+    out := make(chan Item)
+    var wg sync.WaitGroup
+    wg.Add(len(sources))
+    for _, src := range sources {
+        go func() {
+            defer wg.Done()
+            for item := range src {
+                select {
+                case out <- item:
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+    go func() { wg.Wait(); close(out) }()
+    return out
+}
+```
+
+### Selecting
+
+```go
+select {
+case msg := <-incoming:
+    handle(msg)
+case <-ctx.Done():
+    return ctx.Err()
+case <-time.After(5 * time.Second):
+    return ErrTimeout
+}
+```
+
+- `time.After` allocates a timer each call — fine for occasional selects, **NOT for hot loops**. Use `time.NewTimer` + `timer.Reset` for repeat selects.
+- A `default:` case makes `select` non-blocking. Use deliberately, not by accident.
+
+### Buffered vs unbuffered
+
+- **Unbuffered** (`make(chan T)`) = synchronous handoff. Sender blocks until receiver is ready. Use for *coordination*.
+- **Buffered** (`make(chan T, n)`) = asynchronous up to `n`. Use for *decoupling producer rate from consumer rate*.
+
+A buffered channel of size 1 acts as a **non-blocking signal**:
+
+```go
+ready := make(chan struct{}, 1)
+// Producer
+select {
+case ready <- struct{}{}:  // signal once, non-blocking
+default:                    // already signaled, skip
+}
+// Consumer
+<-ready
+```
+
+---
+
+## Locks — the pyramid
+
+```
+Highest level (preferred)
+  channels (message passing — "share memory by communicating")
+  errgroup / wait group
+
+  sync.RWMutex (many readers, occasional writer)
+  sync.Mutex   (mutual exclusion)
+
+  atomic.Int64 / atomic.Pointer  (single-word lock-free)
+
+Lowest level (rare)
+  unsafe.Pointer + barriers  (custom lock-free; needs -race AND review)
+```
+
+### `sync.Mutex` — embed, don't expose
+
+```go
+type Cache struct {
+    mu    sync.RWMutex
+    items map[string]Entry
+}
+
+func (c *Cache) Get(key string) (Entry, bool) {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    e, ok := c.items[key]
+    return e, ok
+}
+
+func (c *Cache) Set(key string, e Entry) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.items[key] = e
+}
+```
+
+- `sync.Mutex` is **not** copyable. The `copylocks` vet check catches `var c2 = c1` where `c1` has a mutex.
+- Always `defer mu.Unlock()` immediately after `Lock()`. Forgetting is the #1 deadlock cause.
+- Never call user code (callbacks, listener notifications) while holding the lock. Drop the lock, snapshot the data, release, then call out.
+
+### `sync.OnceValue` / `sync.OnceFunc` (Go 1.21+)
+
+Replacement for `sync.Once` for typed lazy init:
+
+```go
+var loadConfig = sync.OnceValue(func() Config {
+    var cfg Config
+    if err := env.Parse(&cfg); err != nil { panic(err) }
+    return cfg
+})
+
+func handler() { cfg := loadConfig(); ... }
+```
+
+Type-safe, no `sync.Once` + global variable boilerplate.
+
+### Atomics — the typed API only
+
+```go
+// Go 1.19+ — use the typed atomic.* family
+var counter atomic.Int64
+counter.Add(1)
+n := counter.Load()
+
+// NEVER — the old function-style is type-unsafe
+atomic.AddInt64(&counter, 1)  // ← rejected
+```
+
+---
+
+## Time — inject a clock for testability
+
+```go
+type Clock interface {
+    Now() time.Time
+}
+
+type realClock struct{}
+func (realClock) Now() time.Time { return time.Now() }
+
+type Service struct {
+    clock Clock
+}
+
+// Tests
+import "github.com/benbjohnson/clock"
+fake := clock.NewMock()
+fake.Set(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))
+svc := &Service{clock: fake}
+```
+
+**Never call `time.Now()` in domain or service code.** The `time` package becomes a hidden dependency — tests become flaky, retries become time-of-day-dependent, expirations cannot be tested.
+
+`time.Sleep` in production code is a code smell. Use:
+- `time.NewTicker` for periodic work (and a `<-ctx.Done()` exit).
+- `time.NewTimer` for one-shot delays.
+- `time.After` ONLY in select statements, ONLY in non-hot paths.
+
+---
+
+## Race detector — non-negotiable in CI
+
+```bash
+go test -race -shuffle=on -count=1 ./...
+```
+
+- `-race` instruments memory accesses; catches data races at runtime. ~10x slow-down — acceptable for tests, not production.
+- `-shuffle=on` randomizes test order; catches hidden ordering dependencies.
+- `-count=1` defeats the test cache. Without it, "passing" might mean "ran 3 weeks ago".
+
+If a test ONLY fails under `-race`, the bug is real. Don't disable the test; fix the race.
+
+---
+
+## Common antipatterns
+
+| Bad | Why | Good |
+|---|---|---|
+| `go func() { ... }()` with no `ctx` plumbing | Leaks on shutdown | `errgroup.WithContext` or pass ctx |
+| Bare `time.Sleep(d)` in production | Untestable, blocks | `time.NewTimer` + select with `ctx.Done()` |
+| Channel of `interface{}` | Loses type | Typed channel; use sealed interface if variants needed |
+| `sync.Mutex` in a struct passed by value | Locked copies, undefined behavior | Embed in pointer-receiver type; copylocks catches it |
+| Locking around an entire request handler | Serializes the whole API | Lock only the smallest critical section |
+| `for { select { ... } }` without `<-ctx.Done()` | Cannot stop | Add ctx case in every long-lived select |
+| `sync.WaitGroup.Add(1)` inside the goroutine | Race: Wait can return before Add | Add **before** `go` |
+
+---
+
+## Sources
+
+- Go memory model: https://go.dev/ref/mem
+- `errgroup` package: https://pkg.go.dev/golang.org/x/sync/errgroup
+- `goleak`: https://github.com/uber-go/goleak
+- "Go concurrency patterns" (Pike): https://go.dev/blog/pipelines
+- Sync.OnceValue blog: https://go.dev/blog/synctest (1.24+ note: `testing/synctest` for time-controlled tests is now experimental)

package/marketplace/plugins/litcodex/skills/lit-code/references/go/data-modeling.md

@@ -0,0 +1,329 @@
+# Data Modeling — Three Layers of Validation
+
+Go has no Pydantic. Go has no Zod. **You do not need them**, but only if you wire three layers correctly. This document is the canonical pattern.
+
+## The three layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    HTTP / RPC / CLI                          │
+│  Raw bytes, strings, untrusted input                         │
+│                                                              │
+│   Layer 1: validator/v10 (struct tags)   ◄── parse-once     │
+│           OR protovalidate (proto)                           │
+│                                                              │
+└──────────────────────────┬──────────────────────────────────┘
+                           │  raw req → domain.X
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Domain (internal/domain)                  │
+│                                                              │
+│   Layer 2: Smart constructors + unexported fields            │
+│           NewEmail(s) → (Email, error)                       │
+│           NewUserID(s) → (UserID, error)                     │
+│                                                              │
+│           Once inside this layer, NO further validation.     │
+│           The types prove correctness.                       │
+└──────────────────────────┬──────────────────────────────────┘
+                           │  domain.X (proven valid)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Storage (internal/store)                  │
+│                                                              │
+│   Layer 3: sqlc-generated row structs ↔ domain types         │
+│           Hand-written mappers, NOT struct tags              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Each layer parses once, into the next layer's types. **A function in the domain layer should never receive a raw string and validate it.** If it does, the boundary above failed.
+
+---
+
+## Layer 1: HTTP boundary — `go-playground/validator/v10`
+
+```go
+package handlers
+
+import (
+    "github.com/gin-gonic/gin"
+    "github.com/go-playground/validator/v10"
+)
+
+// CreateUserRequest is the wire format. Tags drive validation.
+type CreateUserRequest struct {
+    Email    string `json:"email"    binding:"required,email"`
+    Username string `json:"username" binding:"required,alphanum,min=3,max=32"`
+    Age      int    `json:"age"      binding:"required,gte=13,lte=130"`
+    Country  string `json:"country"  binding:"required,iso3166_1_alpha2"`
+}
+
+func (h *Handler) CreateUser(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        // validator returns ValidationErrors with field-by-field detail
+        var vErr validator.ValidationErrors
+        if errors.As(err, &vErr) {
+            c.JSON(400, gin.H{"errors": fieldErrors(vErr)})
+            return
+        }
+        c.JSON(400, gin.H{"error": "invalid json"})
+        return
+    }
+
+    // Cross into domain — single point of failure
+    email, err := domain.NewEmail(req.Email)
+    if err != nil {
+        c.JSON(400, gin.H{"error": err.Error()})
+        return
+    }
+    username, err := domain.NewUsername(req.Username)
+    if err != nil {
+        c.JSON(400, gin.H{"error": err.Error()})
+        return
+    }
+
+    user, err := h.svc.Create(c.Request.Context(), email, username, req.Age)
+    if err != nil {
+        h.writeServiceError(c, err)
+        return
+    }
+    c.JSON(201, user)
+}
+
+func fieldErrors(vErr validator.ValidationErrors) map[string]string {
+    out := make(map[string]string, len(vErr))
+    for _, fe := range vErr {
+        out[fe.Field()] = fe.Tag() + "(" + fe.Param() + ")"
+    }
+    return out
+}
+```
+
+**Tag reference — the tags you actually use**:
+
+| Tag | Meaning |
+|---|---|
+| `required` | Non-zero value |
+| `omitempty` (json) | Skip if zero |
+| `min=N` / `max=N` | Length (strings/slices) or value (numbers) |
+| `gte=N` / `lte=N` / `gt=N` / `lt=N` | Numeric comparison |
+| `email` | RFC 5322-ish email |
+| `url` | Valid URL |
+| `uuid` / `uuid4` / `uuid7` | UUID format |
+| `alphanum` / `alpha` / `numeric` | Character class |
+| `iso3166_1_alpha2` | Country code (US, KR, JP) |
+| `iso4217` | Currency code (USD, KRW) |
+| `oneof=a b c` | Enum of literal values |
+| `dive` | Apply rules to each element of slice/map |
+| `eqfield=Field` | Cross-field equality (e.g., password confirm) |
+
+### Custom validators — register at startup
+
+```go
+func init() {
+    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
+        _ = v.RegisterValidation("strongpassword", validateStrongPassword)
+    }
+}
+
+func validateStrongPassword(fl validator.FieldLevel) bool {
+    s := fl.Field().String()
+    return len(s) >= 12 && hasUpper(s) && hasDigit(s) && hasSymbol(s)
+}
+```
+
+Use sparingly. Most domain rules belong in smart constructors, not validators.
+
+---
+
+## Layer 2: Domain — smart constructors
+
+Covered in detail in `type-patterns.md`. Recap:
+
+```go
+package domain
+
+type Username struct{ raw string }
+
+func NewUsername(s string) (Username, error) {
+    s = strings.TrimSpace(s)
+    if len(s) < 3 || len(s) > 32 {
+        return Username{}, ErrInvalidUsername
+    }
+    if !isAlphanum(s) {
+        return Username{}, ErrInvalidUsername
+    }
+    return Username{raw: s}, nil
+}
+
+func (u Username) String() string { return u.raw }
+```
+
+**Rule**: every domain type that has invariants has:
+
+1. An unexported field holding the raw form.
+2. A `New<Type>(raw) (<Type>, error)` constructor as the sole entry point.
+3. A `String() string` for printing.
+4. `MarshalJSON` / `UnmarshalJSON` if it crosses a JSON boundary outside HTTP handlers (e.g., logging payloads, queue messages).
+5. Optionally: `Scan` and `Value` for `database/sql` interop (rare with sqlc).
+
+---
+
+## Layer 3: Storage — sqlc rows ↔ domain types
+
+sqlc generates row structs from `.sql` files. **Do not put validation tags on them.** Map between sqlc rows and domain types explicitly:
+
+```go
+// internal/store/user_store.go
+package store
+
+import "myservice/internal/domain"
+
+func (s *UserStore) Get(ctx context.Context, id domain.UserID) (domain.User, error) {
+    row, err := s.q.GetUser(ctx, string(id))
+    if err != nil {
+        return domain.User{}, err
+    }
+    return rowToUser(row)
+}
+
+func rowToUser(r sqlc.UserRow) (domain.User, error) {
+    email, err := domain.NewEmail(r.Email)
+    if err != nil {
+        // DB invariant broken — this is a programmer error, not a user error
+        return domain.User{}, fmt.Errorf("db invariant: invalid email for user %s: %w", r.ID, err)
+    }
+    username, err := domain.NewUsername(r.Username)
+    if err != nil {
+        return domain.User{}, fmt.Errorf("db invariant: invalid username: %w", err)
+    }
+    return domain.User{
+        ID:       domain.UserID(r.ID),
+        Email:    email,
+        Username: username,
+        Created:  r.CreatedAt,
+    }, nil
+}
+```
+
+The mapping is verbose. **That is the point.** Each field is a deliberate choice; refactors flag every site.
+
+---
+
+## Discriminated unions (sum types) at the boundary
+
+When a wire payload has variants (e.g., `{"type": "user.created", ...}` vs `{"type": "user.deleted", ...}`):
+
+```go
+// Wire DTO with raw discriminator
+type EventDTO struct {
+    Type    string          `json:"type"    binding:"required,oneof=created deleted updated"`
+    Payload json.RawMessage `json:"payload" binding:"required"`
+}
+
+// Parse into the sealed domain type
+func ParseEvent(dto EventDTO) (event.Event, error) {
+    switch dto.Type {
+    case "created":
+        var c event.Created
+        if err := json.Unmarshal(dto.Payload, &c); err != nil {
+            return nil, fmt.Errorf("decode created: %w", err)
+        }
+        return c, nil
+    case "deleted":
+        var d event.Deleted
+        if err := json.Unmarshal(dto.Payload, &d); err != nil {
+            return nil, fmt.Errorf("decode deleted: %w", err)
+        }
+        return d, nil
+    case "updated":
+        var u event.Updated
+        if err := json.Unmarshal(dto.Payload, &u); err != nil {
+            return nil, fmt.Errorf("decode updated: %w", err)
+        }
+        return u, nil
+    default:
+        return nil, fmt.Errorf("unknown event type %q", dto.Type)
+    }
+}
+```
+
+The `exhaustive` linter on the switch + the `oneof` validation tag together cover both "unknown type" and "unhandled variant".
+
+---
+
+## Enums — typed string consts, not iota
+
+```go
+// GOOD — string-based, JSON-serializes correctly, debuggable
+type Status string
+
+const (
+    StatusPending Status = "pending"
+    StatusActive  Status = "active"
+    StatusClosed  Status = "closed"
+)
+
+func (s Status) IsValid() bool {
+    switch s {
+    case StatusPending, StatusActive, StatusClosed:
+        return true
+    }
+    return false
+}
+
+func (s *Status) UnmarshalJSON(data []byte) error {
+    var raw string
+    if err := json.Unmarshal(data, &raw); err != nil { return err }
+    parsed := Status(raw)
+    if !parsed.IsValid() { return fmt.Errorf("invalid status %q", raw) }
+    *s = parsed
+    return nil
+}
+```
+
+**Never use `iota` enums for anything that crosses a wire boundary.** They serialize as integers, which (a) breaks debuggability, (b) makes reordering enum values a silent breaking change.
+
+Use the validator tag `binding:"oneof=pending active closed"` to enforce at the HTTP boundary.
+
+---
+
+## Nullable fields — `*T` vs sentinel
+
+Three choices, in order of preference:
+
+1. **Sentinel zero value**: `Age int` with `0` meaning "unknown". Works when zero is genuinely unreachable as a valid value.
+2. **`sql.Null<T>`** for DB columns: `sql.NullString`, `sql.NullInt64`, `sql.NullTime`. sqlc generates these for nullable columns.
+3. **`*T`**: only when you need to distinguish "not provided" from "set to zero" in a JSON payload (PATCH semantics).
+
+```go
+// PATCH payload — `*string` discriminates absent vs empty
+type UpdateUserRequest struct {
+    Email    *string `json:"email,omitempty"`
+    Username *string `json:"username,omitempty"`
+}
+```
+
+Avoid `*T` in domain types — it bloats every consumer with nil checks. Keep `*T` at the boundary, unwrap on the way in.
+
+---
+
+## Common AI-generated antipatterns this rejects
+
+| Bad | Why | Good |
+|---|---|---|
+| `func handle(req map[string]any)` | No types, no validation | Define a struct, parse with `validator` |
+| `if email != "" { ... }` inside domain | Validation in the wrong layer | Make `email Email`, no check needed |
+| `type Status int` with `iota` for wire field | Silent breaking on reorder | `type Status string` with const literals |
+| Struct tags `json:"email,string"` (the `,string` coercion) | Magic coercion hides bad input | Strict parsing, fail-fast |
+| `json.Unmarshal` then range-check after | Two-step "validate after parse" | Use `validator` tags or custom `UnmarshalJSON` |
+| Reusing handler DTO as the domain type | Couples wire format to business logic | Two distinct types, explicit mapping |
+
+---
+
+## Sources
+
+- go-playground/validator: https://github.com/go-playground/validator
+- gin binding internals: https://github.com/gin-gonic/gin/blob/master/binding/json.go
+- Parse, don't validate: https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
+- sqlc with custom types: https://docs.sqlc.dev/en/latest/howto/overrides.html