CHANGELOG.md

Rama main · réplica de lectura del repositorio original.

# Changelog

## v0.11.5 (2026-11-10)

- The documentation is published at https://psyb0t.github.io/docker-proxq/, and the reference material from the README and the OpenAI client README moved there.
- Every branch push runs lint, the tests with the coverage gate, and govulncheck. A version tag promotes the image already built for that main commit instead of rebuilding it, and the skill goes to ClawHub only after the GitHub release exists. Every make target runs Go in a pinned container, including the new `make sec`, so the host needs only Docker, Make and Bash.
- The file-server upstream in `config.yaml.example` sets `directProxyThreshold: -1`, which queues every body. The old `0` fell back to the 10 MiB default instead of the "always queue" its comment promised. The agent skill's configuration reference had the same mistake and is corrected.
- The image builds on Go 1.26.10, and the `github.com/klauspost/compress` test dependency moves to v1.20.2.
- Buy Me a Coffee is in the funding links, and `AGENTS.md` plus project rules in `.agents/rules/` are committed for coding agents.

## v0.11.4 (2026-10-10)

CI fix only. v0.11.3 was tagged but its checks failed before building, so no v0.11.3 image or GitHub release exists; this release publishes its Go 1.26.9 change.

- The pipeline asks the Go workflow for Go 1.26.9 instead of "1.26". The workflow runs with `GOTOOLCHAIN=local`, so "1.26" picked the runner's cached Go 1.26.8, which refuses a `go.mod` that requires 1.26.9.

## v0.11.3 (2026-10-10)

Builds with Go 1.26.9, which fixes standard library vulnerabilities the security scan reports as reachable. v0.11.2 was tagged but its build stopped at that scan, so no v0.11.2 image or GitHub release exists; this release also carries its README change.

- `go.mod` moves to Go 1.26.9, which fixes HTTP/2 server crashes and resource exhaustion in `net/http`, unbounded header parsing in `mime/multipart`, malformed ECH handling in `crypto/tls`, and two `html/template` issues (GO-2026-6599, GO-2026-6600, GO-2026-6603, GO-2026-6605, GO-2026-6607 through GO-2026-6613, and GO-2026-6617).
- The image builds on `golang:1.26.9-alpine` and runs on `alpine:3.24`, both pinned by digest. The runtime image was the floating `alpine:latest` before.

## v0.11.2 (2026-10-10)

Documentation only. The README's agent integrations section names [peen](https://github.com/psyb0t/peen) as an example of an agent that reads `.agents/skills/`.

## v0.11.1 (2026-09-26)

Security dependency update. v0.11.0 was tagged but its release build stopped at the vulnerability scan, so no v0.11.0 image or GitHub release exists. Use v0.11.1 for the `redis.username` support.

- `golang.org/x/crypto` v0.54.0 to v0.57.0 (GO-2026-6354, GO-2026-6355).
- `github.com/moby/go-archive` v0.2.0 to v0.3.3 (GO-2026-6253), through testcontainers-go v0.42.0 to v0.44.0.
- Transitive updates pulled in by those bumps, including OpenTelemetry v1.44.0 and `golang.org/x/{sys,text,sync,mod,tools}`.

## v0.11.0 (2026-09-26)

Adds Redis ACL user support.

- New `redis.username` config field. proxq sends it with `redis.password` for both the job queue and the `redis` cache mode, so proxq can run against a Redis server that disables the `default` user and gives proxq its own ACL user.
- An empty or missing `redis.username` keeps the old behavior: password-only authentication as the `default` user. Existing configs need no change.
- A least-privilege proxq user needs access to asynq's keys and channels (`~asynq:*` and `&asynq:*`) plus the cache key prefix (`~proxq:*` by default).
- Integration tests run the production queue and cache setup against a real Redis with the `default` user disabled and a restricted ACL user, and check that a wrong password is rejected.

## v0.10.13 — 2026-08-08

Documentation. No code change.

- The env-var table documented `PUID` / `PGID` as switching the runtime user via
  `su-exec`. The image does not do that: the Dockerfile creates `proxq` at build
  time and sets `USER proxq`, with no `su-exec` anywhere. Anyone setting those
  variables got silence, not a different uid.
- Documented the `X-Proxq-Timeout` request header
  (`HeaderNameXProxqTimeout` in `pkg/types/headers.go`), which overrides the
  matched upstream's timeout for a single submitted request and answers `400`
  on an unparseable value. It was implemented but undocumented.

## v0.10.12 — 2026-08-08

Dependency bump only. No behaviour changed.

- `slogging` v1.6.1 → v1.7.0, which rebuilt its handler API. Nothing here needed editing: this uses the blank import, so it never names a handler type. The stdout/stderr split, the level and the format still come from the same environment variables. Vendor tree updated to match.

## v0.10.11 — 2026-08-08

Dependency rename only. No behaviour changed.

- `github.com/psyb0t/slog-configurator` became `github.com/psyb0t/slogging`, with the configurator now at `slogging/slogconf`. The blank import in `cmd/main.go` follows it, and the vendor tree moves with it. Logging is configured by exactly the same env vars as before.
- The submit-a-job example in `.agents/skills/proxq/SKILL.md` now writes its auth header as `Bearer $UPSTREAM_TOKEN` rather than a literal placeholder, matching the `$PROXQ_URL` on the line above. Secret scanners read a credential-shaped literal in a curl header as a real finding regardless of the word chosen, and a copy-pasteable variable is the better example anyway.

## v0.10.10 — 2026-08-01

CI plumbing only. No code in this repo changed — every commit in this release touches `.github/workflows/`.

- The pipeline was split: building and publishing stay in `pipeline.yml`, and everything that leaves the host now lives beside it in `mirror-and-archive.yml`.
- The repo is mirrored to Codeberg as well as GitLab.
- It is archived to the Wayback Machine, Software Heritage and archive.org.
- Issues opened on either mirror are copied back to GitHub every six hours, and closed here when the original closes.
- Pull requests are switched off on the mirrors — they are force-pushed from GitHub, so anything merged there would be destroyed by the next sync. Issues and forking stay enabled.

## v0.10.9 — 2026-07-27

- The Codex subsection of the `## Agent integrations` README section was missing its install command — it told readers to run `codex plugin marketplace add psyb0t/agents` and stopped there. Added the missing `codex plugin add proxq@psyb0t` line.
- Clarified that the invocation form depends on how the skill was picked up: installed via the marketplace it invokes as `$proxq:proxq`, while Codex's automatic pickup from a repo's own `.agents/skills/` (no install needed) invokes it as plain `$proxq`.

## v0.10.8 — 2026-07-27

- Added `.agents/.claude-plugin/plugin.json` and `.agents/.codex-plugin/plugin.json` manifests, making the existing `.agents/skills/proxq` skill installable natively via `claude plugin install proxq@psyb0t` and `codex plugin marketplace add psyb0t/agents`.
- Added a `## Agent integrations` README section (with Table of Contents entry) documenting the Claude Code, Codex, and OpenClaw install commands.

## v0.10.7 — 2026-07-27

- Added a GitHub Actions CI status badge to the README.

## v0.10.6 — 2026-07-27

- Fix badges CI job — add needs dependency so the coverage badge waits for the coverage artifact.

## v0.10.5 — 2026-07-27

- Go 1.26; `make lint` now runs `go fix -diff ./...` first (fails with a fix hint before golangci-lint even runs) and `make lint-fix` applies `go fix` before the golangci-lint auto-fix pass.
- Coverage badge: `make test-coverage` now also writes the total coverage percentage to `coverage-percent.txt`; `pipeline.yml`'s `go` job reads it via `coverage_file`, and the `badges` job now generates the coverage badge alongside version/license.
- `internal/testinfra/redis.go` (testcontainers Redis setup used by the integration tests) switched from `fmt.Errorf` to `ctxerrors.Wrap`/`ctxerrors.Wrapf`, and its sentinel error moved into `internal/testinfra/errors.go`. No behavior change — error messages are unchanged, wrapping now carries file/line/function context.
- Logging (structured `log/slog` via `slog-configurator`) and the rest of the error wrapping (`ctxerrors` + sentinel `errors.go` files) were already in place across the codebase — verified, no further changes needed.

## v0.10.4 — 2026-07-27

- Added self-hosted version and license badges plus a Docker Hub pulls badge; wired a badges job into pipeline.yml.

## v0.10.3 — 2026-07-26

Skill docs de-duplicated. Documentation only, no behavior change.

- Collapsed the two repeated `DELETE /__jobs/{id}` cancellation warnings in `.agents/skills/proxq/SKILL.md` into a single Security & safety note plus the API reference, instead of restating the same guidance twice.

## v0.10.2 — 2026-07-26

### Changed
- **Agent skill docs hardened.** Strengthened the `DELETE /__jobs/{id}` guidance in `.agents/skills/proxq/SKILL.md` with an explicit destructive-operation guardrail: no ownership check exists, so an agent must only cancel a job it just submitted or one the user explicitly named, and must never enumerate job IDs and bulk-cancel. No behavior change — documentation only, additive to the existing SSRF and no-auth warnings.

## v0.10.1 — 2026-07-25

### Fixed
- **`govulncheck` (CI security scan).** Bumped `golang.org/x/crypto` v0.50.0 → v0.54.0 to clear the reachable `crypto/ssh` advisories (GO-2026-5013…5020, fixed in v0.52.0) that `govulncheck` flagged via the testcontainers teardown path in `internal/testinfra/redis.go`. Vendored deps refreshed. No production-code or API change.

## v0.10.0 — 2026-07-25

### Added
- **Agent skill + ClawHub publish.** Added `.agents/skills/proxq/` (SKILL.md + `references/setup.md`) documenting the async submit → poll (`GET /__jobs/{id}`) → fetch-content (`GET /__jobs/{id}/content`) → cancel (`DELETE /__jobs/{id}`) flow, the `config.yaml` schema, and the no-built-in-auth posture. The pipeline now publishes the skill to ClawHub on tag pushes, after the image build + release.

## v0.8.0 — 2026-04-24

### Fixed
- **Upstream timeout was silently ignored.** The worker's `http.Client.Timeout` was hardcoded to 5 minutes regardless of what was set in per-upstream config. Requests hit exactly 5m every time. Root cause: `WorkerConfig.UpstreamTimeout` was never passed in `app.go`, falling back to `defaultUpstreamTimeout = 5 * time.Minute`. Fix: remove the fallback, default `http.Client.Timeout` to 0, rely on the asynq task timeout (already wired correctly per-upstream) cancelling via context through `http.NewRequestWithContext`.

### Changed
- Go module renamed from `github.com/psyb0t/proxq` to `github.com/psyb0t/docker-proxq`.

### Added
- `TestWorker_ProcessTask_ContextDeadlineKillsRequest`: slow upstream, no `http.Client.Timeout`, context deadline fires at ~200ms.
- `TestWorker_ProcessTask_UpstreamTimeoutKillsRequest`: slow upstream, explicit `UpstreamTimeout`, fires at ~200ms.

---

## v0.7.0 — 2026-04-21

### Changed
- Module name corrected in `go.mod` and all import paths (was mismatched after initial rename).

---

## v0.6.0 — 2026-04-18

### Added
- **Per-upstream `cacheKeyExcludeHeaders`**: configure which request headers are excluded from the cache key hash per upstream. Non-empty list replaces the defaults entirely; empty list keeps defaults (`X-Request-ID`, `X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Proto`).
- Stored in `taskEnvelope`, applied per-task in worker via `buildExcludeHeaders()`.
- `TestHandler_CacheKeyExcludeHeaders` integration test.
- `TestBuildExcludeHeaders` table-driven unit test (4 cases).
- Config parse tests for `cacheKeyExcludeHeaders`.

### Changed
- Handler: warn log on no upstream match; debug log on successful enqueue (job ID, upstream, method, URL).
- Worker: debug log on task pickup and completion (method, URL, status code).
- `buildEnvelope()` extracted from `enqueueRequest()` to satisfy funlen lint limit.
- README fully rewritten with complete API reference, config tables, routing rules, header reference.

---

## v0.5.1 — 2026-04-18

### Changed
- All error assertions in tests switched from string matching to `errors.Is` with sentinels or `require.Error`.
- Additional OpenAI client unit tests covering constructor and error paths.

---

## v0.5.0 — 2026-04-18

### Added
- **Per-upstream `maxRetries` and `retryDelay`** with configurable retry delay function (`RetryDelayFunc`).
- `taskEnvelope` payload format wrapping `RequestPayload` + `RetryDelay` (replaces bare payload).
- `X-Proxq-Source: proxq` header on all proxq-generated responses (accepted, errors, redirects, job endpoints). Never set on responses proxied from upstream.
- **`pkg/clients/openai`**: drop-in replacement for the `openai-go` SDK. Swap one line — all SDK calls (chat completions, embeddings, images, audio) route through the proxq async queue transparently.

---

## v0.4.1 — 2026-04-18

### Fixed
- Lint errors.

---

## v0.4.0 — 2026-04-18

### Added
- **YAML config file** (`PROXQ_CONFIG` env var or `--config` flag) replacing individual env vars for upstream configuration.
- **Multi-upstream routing**: define multiple upstreams, each with its own prefix, URL, timeout, and rules.
- Per-upstream `directProxyThreshold`: response body size below which sync/direct proxy is used instead of queuing.
- Per-upstream `directProxyMode`: `proxy` (reverse proxy, default) or `redirect` (307 to upstream URL).
- Per-upstream `maxBodySize`: maximum accepted request body size.

---

## v0.3.0 — 2026-04-18

### Added
- **Path filter** with `blacklist` and `whitelist` modes per upstream.
  - Blacklist (default): matching paths bypass the queue and go direct.
  - Whitelist: only matching paths get queued; everything else bypasses.
- Replaced `PROXQ_DIRECT_PROXY_PATHS` with `PROXQ_PATH_FILTER` + `PROXQ_PATH_FILTER_MODE`.

---

## v0.2.0 — 2026-04-18

### Added
- **Direct proxy mode switch**: responses below `directProxyThreshold` are returned synchronously instead of being queued. Configurable via `directProxyMode` (`proxy` or `redirect`).
- e2e test suite refactored into focused test files (`jobs_test.go`, `cache_test.go`, `content_test.go`, `edge_cases_test.go`, `bypass_test.go`).
- Upstream fixture server (`tests/.fixtures/upstream.js`).

---

## v0.1.0 — 2026-04-18

Initial release.

### Features
- HTTP reverse proxy with async queue via Redis + asynq.
- Requests accepted immediately with `202 Accepted` and a job ID.
- Job status polling endpoint.
- Response caching with configurable TTL and Redis key prefix.
- Regex-based upstream URL routing.
- Concurrency control via asynq worker pool.
- Docker Compose setup with Redis.