docs: add early hints documentation#3697
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Warning Rate limit exceeded@ReneWerner87 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 18 minutes and 49 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (2)
WalkthroughAdds documentation for a new context method SendEarlyHints on fiber.Ctx and expands SendFile docs with a SendFile config type and examples; updates "What's New" to mention SendEarlyHints. Changes are documentation-only and do not modify runtime behavior. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client
participant FiberApp
participant Handler
Client->>FiberApp: HTTP request
activate FiberApp
FiberApp->>Handler: invoke route handler
activate Handler
Note right of Handler #E7F6FF: prepare Link hints (array of headers)
Handler-->>Client: 103 Early Hints (Link: ...)
Note left of Client #F0FFF4: client may preload resources (HTTP/2+ best)
Handler-->>Client: Final response (200/3xx/4xx + body)
deactivate Handler
deactivate FiberApp
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Summary of Changes
Hello @ReneWerner87, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request focuses on enhancing the project's documentation by adding comprehensive details for the SendEarlyHints functionality. It aims to inform users about this feature, which allows servers to send 103 Early Hints responses for preloading resources, thereby improving perceived web performance.
Highlights
- API Documentation for SendEarlyHints: A new section has been added to the ctx API reference (docs/api/ctx.md) detailing the SendEarlyHints method. This includes its purpose, signature, an example of its usage, and a cautionary note regarding its compatibility with HTTP/2 or newer protocols.
- "What's New" Guide Update: The v3 What's New guide (docs/whats_new.md) has been updated to highlight SendEarlyHints as a new Ctx method. This update includes a brief description of its benefits for preloading assets and an example demonstrating its implementation.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for the SendEarlyHints method, which enables servers to send HTTP 103 Early Hints responses to help browsers preload resources. The documentation includes both API reference details and highlights the feature in the v3 What's New guide.
- Added
SendEarlyHintsto the list of new v3 context methods - Created dedicated section explaining Early Hints functionality with code examples
- Added comprehensive API reference documentation with usage examples and cautions
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/whats_new.md | Adds SendEarlyHints to v3 features list and creates detailed section with implementation example |
| docs/api/ctx.md | Adds complete API reference documentation including signature, example, and HTTP/2 requirement warning |
There was a problem hiding this comment.
Code Review
This pull request adds documentation for the new SendEarlyHints feature in both the API reference and the 'What's New' guide. The documentation is well-written, but I've found a small point of confusion in the whats_new.md file regarding how hints are provided to the function. I've left a comment with a suggestion to improve clarity and consistency.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/api/ctx.md (3)
2051-2054: Fix MDN link and tighten wording around Link header(s).Current MDN URL points to a non-existent “Reference” path and “headers” is redundant here.
-[`Link` headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link) +[`Link` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link) - before the final response. This allows the browser to start preloading - resources while the server prepares the full response. + before the final response. This lets browsers start preloading resources + while the server prepares the final response.
2055-2058: Rephrase protocol support caveat (HTTP/1.1 can carry 103 but support is inconsistent).“Requires HTTP/2 or newer” is too strong. 103 can technically be sent over HTTP/1.1; the real pitfall is client/CDN/proxy support. Suggest a more accurate caution.
-:::caution -This feature requires HTTP/2 or newer. Some legacy HTTP/1.1 clients may not -understand or may misbehave when receiving early hints. -::: +:::caution +Early Hints are most effective over HTTP/2 or HTTP/3. While the 103 status can +be sent over HTTP/1.1, many clients and intermediaries ignore or mishandle it. +Validate support in your clients, CDN, and reverse proxy before enabling in production. +:::
2064-2072: Enrich the example with multiple hints and crossorigin; optionally show header-based flow.Demonstrate typical real-world preloads (script + CSS) and include crossorigin when appropriate.
-hints := []string{"<https://cdn.com/app.js>; rel=preload; as=script"} +hints := []string{ + "<https://cdn.com/app.js>; rel=preload; as=script; crossorigin", + "<https://cdn.com/app.css>; rel=preload; as=style", +} app.Get("/early", func(c fiber.Ctx) error { if err := c.SendEarlyHints(hints); err != nil { return err } return c.SendString("done") })If the function instead forwards already-set Link headers, add this alternative example after verification:
// Alternative: pre-set Link headers then call SendEarlyHints app.Get("/early", func(c fiber.Ctx) error { c.Append("Link", "<https://cdn.com/app.js>; rel=preload; as=script; crossorigin") c.Append("Link", "<https://cdn.com/app.css>; rel=preload; as=style") if err := c.SendEarlyHints(nil); err != nil { return err } return c.SendString("done") })docs/whats_new.md (2)
467-469: Link the new method to the API reference for discoverability.Add a direct link to the API section you added in ctx.md.
-- **SendEarlyHints**: Sends `103 Early Hints` with `Link` headers so browsers can preload resources while the final response is being prepared. +- **SendEarlyHints**: Sends `103 Early Hints` with `Link` headers so browsers can preload resources while the final response is being prepared. See [Ctx.SendEarlyHints](./api/ctx.md#sendearlyhints).
509-524: Add references and a brief protocol support note.Provide a standards link and clarify HTTP/1.1 behavior to match the API page caution.
-`SendEarlyHints` enables servers to emit [`103 Early Hints`](https://developer.chrome.com/docs/web-platform/early-hints) so +`SendEarlyHints` enables servers to emit [`103 Early Hints`](https://developer.chrome.com/docs/web-platform/early-hints) ([RFC 8297]) +so @@ -Older HTTP/1.1 clients may ignore these interim responses or handle them inconsistently. +Older HTTP/1.1 clients and some intermediaries may ignore or mishandle these interim responses; validate support in clients, CDN, and reverse proxies.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/api/ctx.md(1 hunks)docs/whats_new.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
docs/**
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Review and update the contents of the
docsfolder if necessary when modifying code
Files:
docs/whats_new.mddocs/api/ctx.md
🪛 LanguageTool
docs/api/ctx.md
[grammar] ~2052-~2052: There might be a mistake here.
Context: ...s allows the browser to start preloading resources while the server prepares the ...
(QB_NEW_EN)
🔇 Additional comments (1)
docs/whats_new.md (1)
509-512: I’ve initiated a search for theSendEarlyHintsimplementation to confirm whether it uses only the provided slice or forwards preset headers. I’ll update you once we have the findings.
| ```go title="Signature" | ||
| func (c fiber.Ctx) SendEarlyHints(hints []string) error | ||
| ``` |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Clarify whether SendEarlyHints uses the passed slice, existing Link headers, or both.
The signature accepts hints []string, but “What’s New” says “Only Link headers written before calling SendEarlyHints are forwarded,” which implies reading from already-set headers. Please align the docs to the actual behavior.
If the implementation sends only the passed slice:
+:::info
+SendEarlyHints forwards only the Link values provided in the `hints` slice.
+Link headers added after calling `SendEarlyHints` are not included in the interim response.
+:::If it forwards pre-set Link headers (e.g., those set via c.Append("Link", ...)) and ignores the slice, update the signature and examples accordingly, or document that both sources are combined and how conflicts are resolved. To verify, please run:
🏁 Script executed:
#!/bin/bash
# Locate the implementation and usage of SendEarlyHints
rg -n --type go '\bSendEarlyHints\s*\(' -C3
# Inspect whether it reads from c.GetRespHeaders()/c.Response() or only uses the argumentLength of output: 2661
🏁 Script executed:
#!/bin/bash
# Locate the res.go file in the repository
fd . -type f -name res.goLength of output: 198
🏁 Script executed:
#!/bin/bash
# Locate the implementation file and print the SendEarlyHints method body
file=$(rg -l 'func \(r \*DefaultRes\) SendEarlyHints' -t go)
echo "Found in: $file"
sed -n '680,760p' "$file"Length of output: 2743
Align documentation to actual behavior of SendEarlyHints
The implementation of SendEarlyHints appends every value in the hints slice as a Link header and then calls fasthttp.EarlyHints(), which transmits all Link headers currently set on the response (both those you’d previously added via c.Append("Link", …) and those passed in hints). We should update the docs and inline comments to reflect this merged behavior.
• In docs/api/ctx.md (around the “What’s New” section and the signature example), change:
- Only Link headers written before calling SendEarlyHints are forwarded.
+ Link headers written before calling SendEarlyHints, as well as those provided in the `hints` slice, are all forwarded as Early Hints.• In res.go (and similarly in ctx_interface_gen.go) update the GoDoc above SendEarlyHints:
- // SendEarlyHints allows the server to hint to the browser what resources a page would need
- // so the browser can preload them while waiting for the server's full response. Only Link
- // headers already written to the response will be transmitted as Early Hints.
+ // SendEarlyHints allows the server to hint to the browser what resources a page would need
+ // so the browser can preload them while waiting for the server's full response.
+ // It adds each value in the `hints` slice as a Link header, then forwards all Link headers
+ // currently set on the response (both pre-existing and newly added) as Early Hints.Please apply these doc updates so that the behavior and documentation are fully in sync.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docs/api/ctx.md around lines 2060–2062, update the Signature example and
nearby “What’s New” text to state that SendEarlyHints appends each entry in the
hints slice as a Link header and then calls fasthttp.EarlyHints which transmits
all Link headers currently set on the response (including any previously
appended via c.Append("Link", ...)); in res.go and ctx_interface_gen.go update
the GoDoc above SendEarlyHints to the same effect — explicitly document that
hints are appended as Link headers and EarlyHints will send the merged set of
Link headers already present on the response.
Summary
Testing
make audit(fails: EncodeMsg passes lock by value)make generatemake betteralign(fails: package requires newer Go version go1.25)make modernize(fails: package requires newer Go version go1.25)make formatmake test(fails: Test_App_BodyLimit_Zero i/o timeout)https://chatgpt.com/codex/tasks/task_e_68a6be9f88548326944b0a5c9eb7c49d