docs: polish README and fix stale rest.go retry comment#6
Conversation
- README.md: clarified the opening paragraph to call out the zero-dependency WebSocket client and panic-recovered dispatcher, added a "Vendored builds" subsection under Installation with the GOWORK=off mod vendor workflow, named maxRateLimitRetries explicitly in the Rate Limiting section, extended the Security section with the maxFramePayload guard (including the negative payload-length rejection) and the url.PathEscape reaction fix, and added a note about the 4014 close code appearing in gateway logs. - rest.go: the file header said 429 responses were "retried once"; the actual behaviour is bounded by maxRateLimitRetries (3). Header comment now matches the implementation. - CHANGELOG.md: added an Unreleased section describing the README and rest.go header-comment polish.
There was a problem hiding this comment.
Pull request overview
Documentation polish pass aligning user-facing docs with current library behavior and security posture, plus a small comment fix in the REST client header.
Changes:
- Updated
rest.goheader comment to describe 429 retry behavior in terms ofmaxRateLimitRetries. - Expanded
README.mdwith vendoring guidance, clearer rate-limit retry notes, and additional security/troubleshooting details. - Added an Unreleased entry in
CHANGELOG.mddescribing the documentation/comment updates.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| rest.go | Updates the file header comment for 429 retry behavior to match implementation. |
| README.md | Adds/extends documentation for installation vendoring, rate limiting, security notes, and troubleshooting. |
| CHANGELOG.md | Documents the above doc/comment changes under Unreleased. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| For self-contained deployments (e.g. scratch Docker images), vendor | ||
| the module and build with `-mod=vendor`: | ||
|
|
||
| ```bash | ||
| GOWORK=off go mod tidy | ||
| GOWORK=off go mod vendor | ||
| go build -mod=vendor ./... | ||
| ``` | ||
|
|
||
| The `GOWORK=off` disables workspace mode so a sibling `go.work` file | ||
| doesn't pull in live-dev paths during vendoring. | ||
|
|
There was a problem hiding this comment.
The new “Vendored builds” subsection duplicates the later “Vendoring” section (both show the same GOWORK=off … go mod vendor workflow). To avoid the two sections drifting over time, consider consolidating into a single section or having one link to the other.
| For self-contained deployments (e.g. scratch Docker images), vendor | |
| the module and build with `-mod=vendor`: | |
| ```bash | |
| GOWORK=off go mod tidy | |
| GOWORK=off go mod vendor | |
| go build -mod=vendor ./... | |
| ``` | |
| The `GOWORK=off` disables workspace mode so a sibling `go.work` file | |
| doesn't pull in live-dev paths during vendoring. | |
| For self-contained deployments (e.g. scratch Docker images), see | |
| [Vendoring](#vendoring) for the recommended `go mod vendor` workflow | |
| and `-mod=vendor` build instructions. |
| for the indicated duration, and retries the request. Retries are capped at | ||
| **3 attempts per call**; if the budget is exhausted a `*APIError` with | ||
| `StatusCode == 429` is returned so you can decide how to proceed. | ||
| **3 attempts per call** (`maxRateLimitRetries`); if the budget is exhausted a |
There was a problem hiding this comment.
The README says retries are capped at “3 attempts per call”, but the implementation allows up to 3 retries after the initial request (i.e. up to 4 total HTTP attempts). Consider rewording this to “up to 3 retries per call” (or “up to 4 attempts: 1 initial + 3 retries”) to match maxRateLimitRetries semantics in rest.go.
| **3 attempts per call** (`maxRateLimitRetries`); if the budget is exhausted a | |
| **up to 3 retries per call** (`maxRateLimitRetries`), for **up to 4 total | |
| attempts** (1 initial request + 3 retries); if the budget is exhausted a |
| intents your bot requests. GoDiscord surfaces the 4014 close code in the | ||
| gateway log so it's straightforward to recognise in traces. |
There was a problem hiding this comment.
This claims “GoDiscord surfaces the 4014 close code in the gateway log”, but the current WebSocket client treats close frames as io.EOF without parsing/logging the close code, and the gateway logs only a generic disconnect message. Either adjust the statement to reflect current logging, or update the gateway/websocket close handling to record the close code and reason.
| intents your bot requests. GoDiscord surfaces the 4014 close code in the | |
| gateway log so it's straightforward to recognise in traces. | |
| intents your bot requests. If the bot connects and then immediately | |
| disconnects after requesting one of these intents, verify that the matching | |
| privileged intent is enabled in the portal. |
Summary
Documentation-only polish pass. No behaviour changes.
README.mdGOWORK=off go mod vendorworkflow for self-contained deploymentsmaxRateLimitRetriesexplicitly and notes that the retry budget is per-requestmaxFramePayload(including the 8-byte negative-length rejection) and theurl.PathEscapereaction path-injection fix4014close codes surface in the gateway log so they're easy to spotrest.gomaxRateLimitRetries(3). Comment now matches the implementation.CHANGELOG.mdrest.goheader polishTest plan
GOWORK=off go build ./...go vet ./...go test -race ./...maxRateLimitRetries,maxFramePayload,url.PathEscapein reaction methods)https://claude.ai/code/session_01SJrLkkqYgfQnGi82DLeqvs