Skip to content

docs: add early hints documentation#3697

Merged
ReneWerner87 merged 4 commits intomainfrom
codex/2025-08-21-07-07-46
Aug 21, 2025
Merged

docs: add early hints documentation#3697
ReneWerner87 merged 4 commits intomainfrom
codex/2025-08-21-07-07-46

Conversation

@ReneWerner87
Copy link
Member

Summary

  • document SendEarlyHints in ctx API reference
  • highlight SendEarlyHints in v3 What's New guide with example

Testing

  • make audit (fails: EncodeMsg passes lock by value)
  • make generate
  • make betteralign (fails: package requires newer Go version go1.25)
  • make modernize (fails: package requires newer Go version go1.25)
  • make format
  • make test (fails: Test_App_BodyLimit_Zero i/o timeout)

https://chatgpt.com/codex/tasks/task_e_68a6be9f88548326944b0a5c9eb7c49d

Copilot AI review requested due to automatic review settings August 21, 2025 07:07
@ReneWerner87 ReneWerner87 requested a review from a team as a code owner August 21, 2025 07:07
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Aug 21, 2025

Note

Other AI code review bot(s) detected

CodeRabbit 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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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.

📥 Commits

Reviewing files that changed from the base of the PR and between 6cbdfb0 and bb9ef7c.

📒 Files selected for processing (2)
  • docs/api/ctx.md (1 hunks)
  • docs/whats_new.md (2 hunks)

Walkthrough

Adds 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

Cohort / File(s) Summary
Context API & SendFile docs
docs/api/ctx.md
Adds func (c fiber.Ctx) SendEarlyHints(hints []string) error documentation (signature, HTTP/2+ caveat, examples) and introduces type SendFile struct { FS fs.FS; Compress bool; ByteRange bool; Download bool; CacheDuration time.Duration; MaxAge int } with updated SendFile usage examples.
What’s New / release notes
docs/whats_new.md
Adds entries describing SendEarlyHints (usage, 103 Early Hints semantics, client caveats) and includes duplicated SendEarlyHints blocks; documentation-only 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
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Suggested reviewers

  • gaby
  • sixcolors
  • efectn

Poem

A nibble of hints before the feast,
103 whispers to fetch at least;
Links hop ahead while pages bake,
my paws tap fast for goodness’ sake.
When the final carrots render through—
early hints made dreams come true. 🥕🐇

✨ Finishing Touches
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch codex/2025-08-21-07-07-46

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.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

  • Visit our Status Page to check the current availability of CodeRabbit.
  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. 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.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 SendEarlyHints to 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

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

ReneWerner87 and others added 3 commits August 21, 2025 09:11
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>
@ReneWerner87 ReneWerner87 added this to v3 Aug 21, 2025
@ReneWerner87 ReneWerner87 added this to the v3 milestone Aug 21, 2025
@ReneWerner87 ReneWerner87 merged commit 57164ca into main Aug 21, 2025
1 check passed
@ReneWerner87 ReneWerner87 deleted the codex/2025-08-21-07-07-46 branch August 21, 2025 07:12
@github-project-automation github-project-automation bot moved this to Done in v3 Aug 21, 2025
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

📥 Commits

Reviewing files that changed from the base of the PR and between f121fd3 and 6cbdfb0.

📒 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 docs folder if necessary when modifying code

Files:

  • docs/whats_new.md
  • docs/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 the SendEarlyHints implementation to confirm whether it uses only the provided slice or forwards preset headers. I’ll update you once we have the findings.

Comment on lines +2060 to +2062
```go title="Signature"
func (c fiber.Ctx) SendEarlyHints(hints []string) error
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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 argument

Length of output: 2661


🏁 Script executed:

#!/bin/bash
# Locate the res.go file in the repository
fd . -type f -name res.go

Length 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants