📒docs: Fix Cache middleware docs #3644
Conversation
WalkthroughThis update revises documentation and code comments for the Fiber cache middleware. The changes clarify cache key construction, cache expiration behavior, and configuration options in the documentation, and correct and expand comments in the middleware's configuration struct. No code logic or exported entity signatures were altered. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Suggested labels
Suggested reviewers
Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ 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. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
This PR improves the cache middleware documentation to better align with the actual implementation behavior. The changes clarify how cache keys are constructed and how expiration times are determined.
Key changes:
- Updated documentation to clarify that cache keys include both HTTP method and path
- Added explanation of Cache-Control max-age directive usage for expiration
- Cleaned up configuration comments for better clarity
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| middleware/cache/config.go | Improved comment clarity and fixed terminology inconsistencies |
| docs/middleware/cache.md | Updated documentation to accurately describe cache key generation and expiration behavior |
Comments suppressed due to low confidence (1)
middleware/cache/config.go:12
- The comment says 'Storage' but the field name in the struct should also be updated from 'Store' to 'Storage' to match the comment, or the comment should refer to 'Store' to match the existing field name.
// Storage is used to store the state of the middleware
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @gaby, 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 accuracy and clarity of the documentation for the cache middleware. The primary goal is to ensure that the documentation precisely reflects the current implementation details, particularly concerning how cache keys are generated and how cache expiration is managed. Additionally, it includes minor cleanups and improvements to comments within the middleware's configuration file.
Highlights
- Cache Key Generation: Updated documentation to explicitly state that cache keys are built using both the request path and the HTTP method, aligning with the middleware's actual behavior.
- Cache Expiration: Added documentation detailing that the
Cache-Control: max-agedirective in server responses is utilized to determine the expiration time for cached entries. - Configuration Comment Refinements: Improved the clarity and accuracy of comments within the
config.gofile for various cache middleware options, such asStorage,ExpirationGenerator, andStoreResponseHeaders.
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 or fill out our survey to provide feedback.
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. ↩
gaby
changed the title
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3644 +/- ##
=======================================
Coverage 91.82% 91.82%
=======================================
Files 113 113
Lines 11426 11426
=======================================
Hits 10492 10492
Misses 671 671
Partials 263 263
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Code Review
This pull request does a great job of improving the documentation for the cache middleware and cleaning up comments in the configuration. The changes make the behavior around cache keys and expiration much clearer. I've found one minor point of inconsistency between the code comments and the documentation that could be addressed.
| // StoreResponseHeaders allows you to store additional headers generated by | ||
| // next middlewares and handlers. |
There was a problem hiding this comment.
This comment cleanup is great! I noticed that the corresponding documentation for StoreResponseHeaders in docs/middleware/cache.md was not updated to reflect this change (& handler is still used there). Could you please update it as well for consistency?
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
middleware/cache/config.go (2)
12-15: Clarify what gets persisted inStorageThe comment reads “Storage is used to store the state of the middleware”, but what is actually persisted are the cached responses. Re-phrasing avoids confusing “state” (internal flags) with the cache entries themselves.
- // Storage is used to store the state of the middleware + // Storage backend where cached responses are persisted // - // Default: an in-memory store for this process only + // Default: an in-memory store local to the current process
34-38: Minor wording polish forExpirationGenerator“allows you to generate a custom expiration per request” is great, but the second sentence (“If nil, the Expiration value is used.”) can be folded into the first for brevity:
- // ExpirationGenerator allows you to generate a custom expiration per request. - // If nil, the Expiration value is used. + // ExpirationGenerator lets you compute a per-request TTL; falls back to + // Expiration when nil.docs/middleware/cache.md (2)
72-83: Example could mention custom key prefixingSince the HTTP method is auto-appended, many users add a prefix (e.g. tenant ID). A short hint here would drive that point home, but it’s optional.
112-115: Table wording & typoTiny polish:
- “Key allows you to generate custom keys.” → “KeyGenerator allows you to generate custom keys.”
- Row description still says “expiration keys”.
-| KeyGenerator | `func(fiber.Ctx) string` | Key allows you to generate custom keys. The HTTP method is appended automatically. | `func(c fiber.Ctx) string { return utils.CopyString(c.Path()) }` +| KeyGenerator | `func(fiber.Ctx) string` | KeyGenerator lets you build custom cache keys (the HTTP method is appended automatically). | `func(c fiber.Ctx) string { return utils.CopyString(c.Path()) }` @@ -| ExpirationGenerator | `func(fiber.Ctx, *cache.Config) time.Duration` | ExpirationGenerator allows you to generate custom expiration keys based on the request. | `nil` +| ExpirationGenerator | `func(fiber.Ctx, *cache.Config) time.Duration` | ExpirationGenerator lets you compute a per-request TTL when the default `Expiration` is insufficient. | `nil`
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/middleware/cache.md(3 hunks)middleware/cache/config.go(3 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/middleware/cache.md
🧠 Learnings (9)
📓 Common learnings
Learnt from: hcancelik
PR: gofiber/fiber#3036
File: docs/middleware/cache.md:103-103
Timestamp: 2024-10-08T19:06:06.583Z
Learning: There are no hard tabs in the lines 100 to 105 of the `docs/middleware/cache.md` file. Future comments about formatting should accurately reflect the actual content.
Learnt from: hcancelik
PR: gofiber/fiber#3036
File: docs/middleware/cache.md:103-103
Timestamp: 2024-06-15T19:26:06.401Z
Learning: There are no hard tabs in the lines 100 to 105 of the `docs/middleware/cache.md` file. Future comments about formatting should accurately reflect the actual content.
Learnt from: ReneWerner87
PR: gofiber/fiber#3161
File: app.go:923-932
Timestamp: 2024-11-15T07:56:21.623Z
Learning: In the Fiber framework, breaking changes are acceptable when moving from version 2 to version 3, including modifications to method signatures such as in the `Test` method in `app.go`.
Learnt from: sixcolors
PR: gofiber/fiber#3446
File: docs/middleware/logger.md:44-44
Timestamp: 2025-05-13T00:19:16.407Z
Learning: In documentation files for the Fiber framework, code examples are often partial and don't repeat import statements that were shown in earlier examples, focusing instead on demonstrating specific usage patterns.
Learnt from: sixcolors
PR: gofiber/fiber#3016
File: middleware/session/config.go:16-26
Timestamp: 2024-09-25T16:17:00.969Z
Learning: In the session middleware `Config` struct, `Store` is backed by `fiber.Storage`; they are different entities serving distinct purposes in session management.
Learnt from: sixcolors
PR: gofiber/fiber#3016
File: middleware/session/config.go:16-26
Timestamp: 2024-10-08T19:06:06.583Z
Learning: In the session middleware `Config` struct, `Store` is backed by `fiber.Storage`; they are different entities serving distinct purposes in session management.
📚 Learning: there are no hard tabs in the lines 100 to 105 of the `docs/middleware/cache.md` file. future commen...
Learnt from: hcancelik
PR: gofiber/fiber#3036
File: docs/middleware/cache.md:103-103
Timestamp: 2024-06-15T19:26:06.401Z
Learning: There are no hard tabs in the lines 100 to 105 of the `docs/middleware/cache.md` file. Future comments about formatting should accurately reflect the actual content.
Applied to files:
docs/middleware/cache.mdmiddleware/cache/config.go
📚 Learning: in documentation files for the fiber framework, code examples are often partial and don't repeat imp...
Learnt from: sixcolors
PR: gofiber/fiber#3446
File: docs/middleware/logger.md:44-44
Timestamp: 2025-05-13T00:19:16.407Z
Learning: In documentation files for the Fiber framework, code examples are often partial and don't repeat import statements that were shown in earlier examples, focusing instead on demonstrating specific usage patterns.
Applied to files:
docs/middleware/cache.md
📚 Learning: detailed usage examples and explanations for new methods like `removeroute` and `removeroutebyname` ...
Learnt from: ckoch786
PR: gofiber/fiber#3230
File: docs/whats_new.md:944-951
Timestamp: 2024-12-15T19:56:45.935Z
Learning: Detailed usage examples and explanations for new methods like `RemoveRoute` and `RemoveRouteByName` are documented in `docs/api/app.md`, so it's unnecessary to duplicate them in `docs/whats_new.md`.
Applied to files:
docs/middleware/cache.md
📚 Learning: in the session middleware `config` struct, `store` is backed by `fiber.storage`; they are different ...
Learnt from: sixcolors
PR: gofiber/fiber#3016
File: middleware/session/config.go:16-26
Timestamp: 2024-10-08T19:06:06.583Z
Learning: In the session middleware `Config` struct, `Store` is backed by `fiber.Storage`; they are different entities serving distinct purposes in session management.
Applied to files:
docs/middleware/cache.mdmiddleware/cache/config.go
📚 Learning: in the `middleware/adaptor/adaptor.go` file of the fiber framework, when updating context handling, ...
Learnt from: gaby
PR: gofiber/fiber#3193
File: middleware/adaptor/adaptor.go:111-111
Timestamp: 2024-11-10T23:44:13.704Z
Learning: In the `middleware/adaptor/adaptor.go` file of the Fiber framework, when updating context handling, replacing `c.Context()` with `c.RequestCtx()` is appropriate to access the `fasthttp.RequestCtx`.
Applied to files:
docs/middleware/cache.md
📚 Learning: in the session middleware `config` struct, the `extractor` field uses function closures (like `fromc...
Learnt from: sixcolors
PR: gofiber/fiber#3625
File: middleware/session/config.go:57-58
Timestamp: 2025-07-27T17:28:53.403Z
Learning: In the session middleware `Config` struct, the `Extractor` field uses function closures (like `FromCookie(key)`), making it impossible to introspect extractor parameters at runtime for validation purposes without complex reflection techniques.
Applied to files:
middleware/cache/config.go
📚 Learning: in the session middleware, the `newstore`, `new`, and `newwithstore` functions ensure that a `store`...
Learnt from: sixcolors
PR: gofiber/fiber#3016
File: middleware/session/config.go:26-26
Timestamp: 2024-09-25T16:18:46.641Z
Learning: In the session middleware, the `newStore`, `New`, and `NewWithStore` functions ensure that a `Store` is present even if it is not initialized in `ConfigDefault`.
Applied to files:
middleware/cache/config.go
📚 Learning: in the fiber framework tests, using `ctx.response.header.cookie` may not be suitable for parsing coo...
Learnt from: sixcolors
PR: gofiber/fiber#3016
File: middleware/csrf/csrf_test.go:188-193
Timestamp: 2024-10-08T19:06:06.583Z
Learning: In the Fiber framework tests, using `ctx.Response.Header.Cookie` may not be suitable for parsing cookies from the response header, as it requires a `*Cookie` and fills it rather than returning a string value; thus, manual parsing of the `Set-Cookie` header may be necessary.
Applied to files:
middleware/cache/config.go
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: lint
- GitHub Check: unit (1.24.x, macos-13)
- GitHub Check: unit (1.24.x, windows-latest)
- GitHub Check: repeated
- GitHub Check: Compare
- GitHub Check: Analyse
🔇 Additional comments (3)
middleware/cache/config.go (1)
70-74: 👍 Comment now matches runtime behaviourThe revised description of
StoreResponseHeadersaccurately communicates that headers added by downstream middlewares/handlers are stored. No further action needed.docs/middleware/cache.md (2)
7-8: Good call-out that key includes path + methodExplicitly stating this saves users from subtle cache-key collisions between
GETandPOSTroutes.
13-14: Nice addition aboutCache-Control: max-agesupportDocumenting the max-age override closes a long-standing ambiguity in issue discussions.
Summary