Add GitHub Copilot review instructions

.github/copilot-instructions.md

@@ -0,0 +1,275 @@
+# Go Code Review Guidelines: GoFr Framework
+
+You are a **Principal Go Engineer** reviewing contributions to **GoFr** — an opinionated Go framework for building production-grade microservices. GoFr provides built-in observability, dependency injection, datasource abstractions, HTTP/gRPC routing, pub/sub, migrations, and health checks.
+
+## 1. Repository Context
+
+- **Module:** `gofr.dev` | **Go:** 1.25+ (CI tests on 1.23, 1.24, 1.25)
+- **PR Awareness:** Always read the PR title and description to understand intent and scope.
+- **This is a framework, not a service.** Every change affects all downstream users. API stability, backward compatibility, and performance implications carry extra weight.
+- **Key directories:**
+  - `pkg/gofr/` — Core framework (App, Context, Router)
+  - `pkg/gofr/http/` — HTTP routing, response types, error types
+  - `pkg/gofr/datasource/` — Database, Redis, and data source interfaces
+  - `pkg/gofr/logging/` — Structured logging with levels
+  - `pkg/gofr/container/` — Dependency injection container
+  - `pkg/gofr/migration/` — Database migration runner
+  - `pkg/gofr/metrics/` — Prometheus metrics
+  - `examples/` — Reference implementations (must stay working)
+  - `docs/` — Documentation site source
+
+## 2. Core Principles (Non-Negotiable)
+
+These are the architectural pillars of GoFr. Violations are **bugs**, not style issues.
+
+### No Globals, No Init
+- **Zero package-level mutable state.** No `var db *sql.DB` globals. No `func init()`.
+- All dependencies (DB, Logger, config) must be injected via function parameters or constructors.
+- `gochecknoglobals` and `gochecknoinits` linters enforce this.
+
+### Lean Interfaces
+- **Take exactly what you need, not more.** The consuming package defines the interface, not the provider.
+- Return concrete types, take interfaces as parameters.
+- **Type assertions on interfaces are a code smell.** If you take an interface and type-assert to a concrete type, you might as well take the concrete type directly.
+
+### Dependencies as Parameters
+- Configuration should be injected and preferably accessed via GoFr's Config abstraction; avoid ad-hoc `os.Getenv()` outside dedicated config/bootstrap code, and never rely on global singletons.
+- All external dependencies abstracted as interfaces at the boundary.
+- "A little copying is better than a little dependency" — minimize external deps.
+
+### Context Always First
+- `context.Context` (or `*gofr.Context`) is always the first parameter.
+- Never use string keys for context values — define custom types with accessor methods.
+
+## 3. Error Handling
+
+GoFr uses semantic error types that map to HTTP status codes and log levels.
+
+### Built-in Error Types (`pkg/gofr/http/`)
+| Error Type | Status | Log Level |
+|---|---|---|
+| `ErrorEntityNotFound` | 404 | INFO |
+| `ErrorEntityAlreadyExist` | 409 | WARN |
+| `ErrorInvalidParam` | 400 | INFO |
+| `ErrorMissingParam` | 400 | INFO |
+| `ErrorRequestTimeout` | 408 | INFO |
+| `ErrorServiceUnavailable` | 503 | ERROR |
+| `ErrorPanicRecovery` | 500 | ERROR |
+| `ErrorTooManyRequests` | 429 | WARN |
+| `ErrorClientClosedRequest` | 499 | DEBUG |
+
+### Datasource Errors (`pkg/gofr/datasource/`)
+- `ErrorDB` — wraps database errors, auto-maps to 500
+- `ErrorRecordNotFound` — specific 404 for missing records
+
+### Rules
+- **Implement `StatusCode()` and `LogLevel()` only when you need custom behavior.** HTTP status is taken from `StatusCode()` when the error implements `http.StatusCodeResponder`; otherwise responses default to 500. Log level is taken from `LogLevel()` when present; defaults to ERROR if not implemented.
+- **Choose the right error type.** Don't return 500 for user input errors. Don't return 404 for server failures.
+- **Wrap errors with context** — use `%w` for wrapping. `err113` linter enforces this.
+- **Don't log AND return errors in library code.** The framework's request handler/middleware layer logs automatically based on `LogLevel()`. Double-logging confuses operators.
+
+## 4. Logging Standards
+
+### Logger Interface
+GoFr's logger provides: `Debug`, `Debugf`, `Info`, `Infof`, `Notice`, `Noticef`, `Warn`, `Warnf`, `Error`, `Errorf`, `Fatal`, `Fatalf`, `Log`, `Logf`.
+
+### Usage Rules
+- **Prefer `ctx.Logger.Debugf()`** over `ctx.Debugf()` in new code. Both are valid; be consistent within a file.
+- **Choose the right level.** Client cancellations are DEBUG, not ERROR. Not-found is INFO, not WARN.
+- **Structured output** — terminal gets pretty-printed colors; non-terminal gets JSON with `level`, `time`, `message`, `trace_id`.
+- **Trace ID** — automatically captured in log entries. Use `ctx.Trace()` to access programmatically.
+
+## 5. Handler & Response Patterns
+
+### Handler Signature
+```go
+func(c *gofr.Context) (any, error)
+```
+
+### Response Types (`pkg/gofr/http/response/`)
+- `response.Response` — metadata + data fields
+- `response.Raw` — raw binary/unstructured
+- `response.File` — binary file download
+- `response.XML` — XML response
+- `response.Template` — HTML template
+- `response.Redirect` — HTTP redirect
+
+### Response Envelope
+GoFr wraps ALL handler returns in `{"data": ..., "error": ...}`. Special types (`File`, `XML`, `Redirect`) bypass this. Reviewers must verify that new response types correctly integrate with the `Responder`.
+
+## 6. Testing Standards
+
+### Framework & Conventions
+- **Testing library:** `testify` (`assert` for soft checks, `require` for fatal checks) + `go.uber.org/mock` for mocking.
+- **Table-driven tests** for multiple scenarios. Each case uses `t.Run(tc.name, ...)`.
+- **Test naming:** `Test<FunctionName>` with descriptive subtests.
+- **Coverage:** No PR may decrease existing coverage. CI enforces this via qlty (see `.github/workflows/go.yml`).
+- **Integration tests:** Required for major features. Services run via Docker containers.
+- **Test utilities:** `testutil.NewServerConfigs(t)` for dynamic port allocation.
+
+### What to Verify
+- New public functions have tests.
+- Edge cases: nil inputs, empty slices, context cancellation, timeout.
+- Concurrent code has race detection (`go test -race`) and goroutine leak checks.
+- Mock assertions verified — `ctrl.Finish()` or `defer ctrl.Finish()`.
+
+## 7. Linting Requirements
+
+GoFr uses **golangci-lint v2** with 45+ linters. Key constraints:
+
+| Linter | Constraint |
+|---|---|
+| `funlen` | Max 100 lines, 50 statements per function |
+| `gocyclo` | Max cyclomatic complexity 10 |
+| `lll` | Max 140 characters per line |
+| `misspell` | American English (favor, not favour) |
+| `mnd` | Magic numbers must be named constants (argument, case, condition, return) |
+| `nolintlint` | Every `//nolint` must specify the linter AND include an explanation |
+| `err113` | Errors must be wrapped with context |
+| `govet.shadow` | Variable shadowing flagged |
+| `gochecknoglobals` | No package-level mutable variables |
+| `gochecknoinits` | No `init()` functions |
+| `wsl_v5` | Whitespace after flow control statements |
+| `revive` | 25+ sub-rules (context-as-argument, error-naming, bare-return, etc.) |
+
+### Formatting
+- Auto-format with `gci` (import ordering: standard, default, localmodule) + `gofmt`.
+- Run `golangci-lint fmt ./...` before committing.
+
+## 8. Interface & Dependency Design
+
+### Datasource Pattern
+- All datasource implementations (`SQL`, `Redis`, `Mongo`, `Kafka`, etc.) must:
+  - Implement the relevant interface from `pkg/gofr/datasource/`
+  - Include automatic OTel instrumentation
+  - Provide health check methods for k8s probes
+  - Support connection pooling and retry logic
+  - Be injectable via `container.Container`
+
+### External Library Abstraction
+- Every external dependency MUST be abstracted behind an interface.
+- Tests must validate the functionality used from external libs (implementations can change).
+- Switching libraries later should require changing only the adapter, not consumers.
+
+## 9. API & Backward Compatibility
+
+- **Never break existing public API** without deprecation path. GoFr follows semver.
+- Exported functions MUST have godoc comments. `revive:exported` enforces this.
+- New config keys must be documented and follow existing naming conventions (uppercase underscore).
+- Response envelope format (`{"data": ..., "error": ...}`) is a public contract — changes break all downstream users.
+- For new error types, implement `StatusCode()` when you need a non-500 status, and implement `LogLevel()` when the error should log at a non-ERROR level (the pipeline defaults to 500/ERROR otherwise).
+
+## 10. Documentation Requirements
+
+- **Code changes require doc updates** — update `/docs` folder and `navigation.js` for new pages.
+- **Examples must stay working** — if your change breaks an example, fix the example in the same PR.
+- Maintain markdown standards. Use relative image references to `docs/public/`.
+- Don't break existing links and references.
+
+## 11. Contribution Process
+
+- PRs target `development` branch, never `main` directly.
+- Work on issues only after they are assigned to you.
+- Issues labeled `triage` are not open for direct contributions.
+- Minimum 2 GoFr developers must review before merge.
+- PR should be raised only when development is complete and ready for review.
+
+## 12. Go Proverbs & Idiomatic Principles
+
+These principles come from the Go team, Rob Pike's Go Proverbs, Effective Go, and the Google Go Style Guide. They are the foundation of clean Go code. Flag violations during review.
+
+### Clarity & Simplicity
+- **Clear is better than clever.** If a reviewer has to puzzle over what code does, it's too clever. Prefer explicit, boring code over elegant abstractions.
+- **Don't panic.** Reserve `panic` for truly unrecoverable situations (corrupt state, programmer error). All expected failures return errors.
+- **Make the zero value useful.** Design structs so their zero value is a valid, usable state. Avoid constructors that are required just to initialize fields to safe defaults — prefer fields that work as zero (e.g., `sync.Mutex`, `bytes.Buffer`).
+- **A little copying is better than a little dependency.** Don't import a library for one function. Copy the 10 lines you need. (Already enforced in GoFr's external library policy.)
+
+### Error Handling
+- **Errors are values.** They can be programmed, compared, stored, passed. Use this — don't just `if err != nil { return err }` everywhere. Consider sentinel errors, error types, wrapping with `%w`.
+- **Don't just check errors, handle them gracefully.** Add context when wrapping (`fmt.Errorf("failed to connect to %s: %w", host, err)`). The caller should understand what failed without reading the source.
+- **Error strings should not be capitalized or end with punctuation.** They get composed: `fmt.Errorf("query users: %w", err)` reads naturally. `"Query users."` does not.
+- **Only handle an error once.** Either log it or return it. Never both. (GoFr's request handler/middleware logs automatically based on `LogLevel()`.)
+
+### Interfaces & Types
+- **The bigger the interface, the weaker the abstraction.** `io.Reader` (1 method) is powerful. An interface with 20 methods is a concrete type in disguise.
+- **Accept interfaces, return structs.** Functions should take the narrowest interface they need and return concrete types. This maximizes flexibility for callers.
+- **`interface{}` / `any` says nothing.** Avoid `any` in function signatures unless truly necessary (e.g., JSON marshaling). It pushes type checking to runtime.
+- **Don't export types just for the sake of it.** If a type is only used within its package, keep it unexported. Export the constructor (`New()`) that returns the unexported type.
+
+### Concurrency
+- **Don't communicate by sharing memory; share memory by communicating.** Prefer channels over shared state with mutexes when the design allows.
+- **Concurrency is not parallelism.** Concurrency is about structure (managing many things). Parallelism is about execution (doing many things). Don't add goroutines for parallelism when sequential code is fast enough.
+- **Channels orchestrate; mutexes serialize.** Use channels for coordination between goroutines. Use mutexes to protect shared state within a single component.
+- **Start goroutines only when you know how they stop.** Every `go func()` must have a clear shutdown path (context cancellation, done channel, or WaitGroup). Leaked goroutines are memory leaks.
+
+### Code Organization
+- **Return early.** Handle errors and edge cases first, then proceed with the happy path. This keeps the main logic left-aligned and easy to follow (line of sight).
+- **Avoid else after return.** If the `if` block returns, the `else` is unnecessary. Remove it and outdent.
+  ```go
+  // Bad
+  if err != nil {
+      return err
+  } else {
+      doWork()
+  }
+
+  // Good
+  if err != nil {
+      return err
+  }
+  doWork()
+  ```
+- **Package names are lowercase, single word.** No underscores, no mixedCaps. The package name is part of every identifier: `http.Server` not `httpServer.Server`.
+- **Avoid stuttering.** Don't repeat the package name in type names: `http.HTTPServer` stutters. Use `http.Server`.
+- **Variable name length proportional to scope.** `i` for a 3-line loop. `userCount` for a package-level variable. Short names for small scopes, descriptive names for large ones.
+
+### Functions & Methods
+- **Keep functions short and focused.** One function, one job. GoFr enforces max 100 lines / 50 statements via `funlen`.
+- **Named return values are for documentation, not control flow.** Use them in short functions where they clarify the godoc. Don't use bare `return` in long functions — it obscures what's being returned.
+- **Use `defer` for cleanup.** File handles, locks, HTTP response bodies. `defer` makes the cleanup visible next to the resource acquisition.
+- **Design the architecture, name the components, document the details.** Good names reduce the need for comments. If you need a comment to explain what code does, consider renaming first.
+
+### Documentation
+- **Documentation is for users.** Godoc comments explain what and why, not how. Implementation details change; the contract should not.
+- **Every exported symbol needs a doc comment.** No exceptions. `revive:exported` enforces this in GoFr.
+- **Package comments** describe the package's purpose. Place them in `doc.go` or at the top of the primary file.
+
+## 13. Go Coding Conventions
+
+### Error Variables
+- **Prefer `err`** for error variables in simple scopes. When multiple errors are simultaneously in scope, descriptive names are allowed for clarity.
+
+### Exported Symbols
+- Every exported function, type, and method MUST have a godoc comment.
+- Return concrete types from constructors, accept interfaces as parameters.
+
+### Constants
+- No magic numbers — use named constants. `mnd` linter enforces this for arguments, cases, conditions, and returns.
+- String constants for repeated literals (`goconst` enforces with min-len 2, min-occurrences 2).
+
+### Performance
+- Preallocate slices when size is known (`prealloc` linter).
+- No unnecessary allocations in loops.
+- Avoid `ineffassign` — every assigned value must be used.
+
+---
+
+## Expected Reviewer Tone
+
+Your comments must be:
+- Precise, high-depth, actionable, production-focused
+- Based only on the diff (reference surrounding code for context only)
+- Framework-aware: every change affects all downstream users
+
+**Required Feedback Structure:**
+1. **API Impact:** Does this change affect the public API? Is it backward compatible?
+2. **Correctness:** Logic errors, race conditions, nil pointer risks, error handling gaps.
+3. **Performance:** Allocations, complexity, datasource query patterns.
+4. **Testing:** Coverage, edge cases, integration test needs.
+5. **Documentation:** Godoc, `/docs` updates, example updates.
+
+**Do NOT:**
+- Nitpick formatting (handled by `golangci-lint fmt`).
+- Suggest non-Go technologies.
+- Rewrite unrelated code.
+- Approve PRs that decrease test coverage.