📒 docs: Enhance CORS middleware documentation with preflight request details and infrastructure considerations#3509
Conversation
…tails and infrastructure considerations
|
""" WalkthroughThe CORS middleware documentation was updated with a new "Infrastructure Considerations" section. This addition provides guidance on handling CORS at the application versus infrastructure level, outlines common infrastructure pitfalls, offers configuration examples for AWS CloudFront, and includes debugging tips and warnings regarding header handling. Changes
Sequence Diagram(s)Not applicable due to documentation-only changes. Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes found. Suggested reviewers
Poem
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 (
|
![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 (2)
docs/middleware/cors.md (2)
212-218: Remove trailing spaces in list items
The line forAccess-Control-Request-Methodhas a trailing space (MD009). Please remove trailing whitespace from all list items to satisfy markdownlint.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 217-217: Trailing spaces
docs/middleware/cors.md:217:34 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md🪛 GitHub Actions: markdownlint
[error] 217-217: markdownlint MD009/no-trailing-spaces: Trailing spaces found (Expected: 0 or 2; Actual: 1). See https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
239-252: Includefmtimport in Go snippet
The debugging middleware snippet referencesfmt.Printfbut doesn’t show thefmtimport. For completeness, add:+import "fmt"above the code block.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/middleware/cors.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/middleware/cors.md
[uncategorized] ~207-~207: Possible missing comma found.
Context: ...nse. ## Infrastructure Considerations First you need to decide whether you want to ...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~208-~208: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ddleware in your Fiber application, you need to ensure that it is configured correctly ...
(REP_NEED_TO_VB)
🪛 GitHub Check: markdownlint
docs/middleware/cors.md
[failure] 217-217: Trailing spaces
docs/middleware/cors.md:217:34 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
🪛 GitHub Actions: markdownlint
docs/middleware/cors.md
[error] 217-217: markdownlint MD009/no-trailing-spaces: Trailing spaces found (Expected: 0 or 2; Actual: 1). See https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
🔇 Additional comments (4)
docs/middleware/cors.md (4)
172-176: Well-defined preflight request note
The added note clearly explains what preflight requests are and when they are sent, improving developer understanding.
206-210: Approve infrastructure considerations introduction
The new section provides essential context for choosing between application-level and infrastructure-level CORS handling.🧰 Tools
🪛 LanguageTool
[uncategorized] ~207-~207: Possible missing comma found.
Context: ...nse. ## Infrastructure Considerations First you need to decide whether you want to ...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~208-~208: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ddleware in your Fiber application, you need to ensure that it is configured correctly ...(REP_NEED_TO_VB)
220-237: Solid common infrastructure issue examples
The CloudFront, API Gateway, and load balancer guidance is practical and well-structured.
254-256: Clear warning on header stripping
The warning block effectively highlights potential failure modes when infrastructure strips CORS preflight headers.
…ng options and best practices
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (10)
docs/middleware/cors.md (10)
210-218: Outline Infrastructure-Level CORS Benefits
The bullets capture key advantages well. To address MD032 errors, ensure there’s a blank line before and after this list block.
219-224: List Common Infrastructure CORS Solutions
Great enumeration of CDN and gateway options. Please add blank lines above and below this list to satisfy markdownlint’s blank‐lines rule.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 220-220: Lists should be surrounded by blank lines
docs/middleware/cors.md:220 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- CDNs: CloudFront, CloudF..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md🪛 GitHub Actions: markdownlint
[error] 220-220: markdownlint MD032: Lists should be surrounded by blank lines [Context: "- CDNs: CloudFront, CloudF..."]
232-238: Clarify Application-Level CORS Use Cases
Good coverage of when to use middleware. Add blank lines around the bullet list to conform with MD032.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 235-235: Lists should be surrounded by blank lines
docs/middleware/cors.md:235 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- *Dynamic origin validation..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
242-249: Detail Required Preflight Headers
This list is essential. Surround it with blank lines to resolve the markdownlint violations.
256-264: Document General CORS Response Headers
Comprehensive coverage. Insert blank lines before and after the list to fix MD032 errors.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 260-260: Lists should be surrounded by blank lines
docs/middleware/cors.md:260 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- `Access-Control-Allow-Origin..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
265-271: Document Preflight Response Headers
Thorough listing of headers. Please add blank lines around this block for proper formatting.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 266-266: Lists should be surrounded by blank lines
docs/middleware/cors.md:266 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- `Access-Control-Allow-Method..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
272-278: Highlight CDN Configuration Pitfalls
Informative CDN guidance. Remove any trailing spaces (e.g., at the end of line 274) and ensure blank lines around the bullets to satisfy MD009/MD032.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 275-275: Lists should be surrounded by blank lines
docs/middleware/cors.md:275 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Configure cache policies to ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 274-274: Trailing spaces
docs/middleware/cors.md:274:41 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
279-283: Clarify API Gateway Recommendations
The points are clear. Please trim trailing spaces on line 279 and wrap the list with blank lines for lint compliance.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 280-280: Lists should be surrounded by blank lines
docs/middleware/cors.md:280 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Choose either gateway-level ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 279-279: Trailing spaces
docs/middleware/cors.md:279:18 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
284-287: Document Load Balancer and Proxy Settings
Solid advice. Add a blank line before the list on line 285 and remove any trailing spaces.🧰 Tools
🪛 GitHub Check: markdownlint
[failure] 285-285: Lists should be surrounded by blank lines
docs/middleware/cors.md:285 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Preserve all HTTP headers, e..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 284-284: Trailing spaces
docs/middleware/cors.md:284:36 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
288-291: Explain WAF Security Service Rules
WAF recommendations are well‐stated. Surround this list with blank lines to adhere to markdownlint’s rules.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/middleware/cors.md(2 hunks)
🧰 Additional context used
🪛 GitHub Check: markdownlint
docs/middleware/cors.md
[failure] 285-285: Lists should be surrounded by blank lines
docs/middleware/cors.md:285 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Preserve all HTTP headers, e..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 284-284: Trailing spaces
docs/middleware/cors.md:284:36 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
[failure] 280-280: Lists should be surrounded by blank lines
docs/middleware/cors.md:280 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Choose either gateway-level ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 279-279: Trailing spaces
docs/middleware/cors.md:279:18 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
[failure] 275-275: Lists should be surrounded by blank lines
docs/middleware/cors.md:275 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Configure cache policies to ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 274-274: Trailing spaces
docs/middleware/cors.md:274:41 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
[failure] 266-266: Lists should be surrounded by blank lines
docs/middleware/cors.md:266 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- `Access-Control-Allow-Method..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 260-260: Lists should be surrounded by blank lines
docs/middleware/cors.md:260 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- `Access-Control-Allow-Origin..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 235-235: Lists should be surrounded by blank lines
docs/middleware/cors.md:235 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- *Dynamic origin validation..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
[failure] 220-220: Lists should be surrounded by blank lines
docs/middleware/cors.md:220 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- CDNs: CloudFront, CloudF..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md
🪛 GitHub Actions: markdownlint
docs/middleware/cors.md
[error] 220-220: markdownlint MD032: Lists should be surrounded by blank lines [Context: "- CDNs: CloudFront, CloudF..."]
🔇 Additional comments (4)
docs/middleware/cors.md (4)
172-176: Add Preflight Requests Note
The new note clearly explains what constitutes a preflight request and its required headers, which enhances clarity for users.
206-209: Introduce Infrastructure Considerations Section
The heading and introductory text effectively set the stage for the new deployment guidance.
225-230: Disable Fiber CORS Middleware Snippet
The example clearly shows how to remove the middleware when using infrastructure‐level CORS.
251-254: Emphasize Critical Preflight Warning
The warning callout effectively highlights the missing-header pitfall.
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Pull Request Overview
Enhance CORS middleware documentation by adding preflight details and infrastructure considerations.
- Added a note explaining what preflight requests contain and when browsers send them
- Introduced an Infrastructure Considerations section with deployment options, required headers, and common pitfalls
- Included debugging tips, curl examples, caching guidance, and a decision table for choosing CORS handling approaches
Comments suppressed due to low confidence (3)
docs/middleware/cors.md:204
- Fix the sentence for clarity and grammar. For example: "The
Varyheader indicates which request headers (e.g.,Access-Control-Request-MethodandAccess-Control-Request-Headers) affect caching for both preflight and actual requests."
The `Vary` header is used in this middleware to inform the client that the server's response to a request. For or both preflight and actual requests, the Vary header is set to `Access-Control-Request-Method` and `Access-Control-Request-Headers`.
docs/middleware/cors.md:309
- The snippet uses
fmt.Printfbut doesn’t include an import forfmt. Addimport "fmt"at the top of the code block to make the example copy-pasta–ready.
fmt.Printf("OPTIONS %s\n", c.Path())
docs/middleware/cors.md:251
- [nitpick] Consider adding a link to the Private Network Access spec or a note about browser support/compatibility for this header, so readers understand where and when it applies.
- `Access-Control-Request-Private-Network` - Optional, for private network access requests
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/middleware/cors.md (1)
360-370: Correct Cloudflare branding
The provider name "CloudFlare" should be "Cloudflare" for accuracy.- - [CloudFlare CORS](https://developers.cloudflare.com/fundamentals/get-started/reference/http-request-headers/#cf-connecting-ip) + - [Cloudflare CORS](https://developers.cloudflare.com/fundamentals/get-started/reference/http-request-headers/#cf-connecting-ip)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/middleware/cors.md(2 hunks)
🔇 Additional comments (18)
docs/middleware/cors.md (18)
172-176: Clarify preflight note addition
The new note clearly explains preflight requests and required headers.
206-210: Introduce Infrastructure Considerations section
Good addition: outlines deployment-level CORS handling choices.
212-225: Detail Option 1: Infrastructure-Level CORS
The recommended approach and its benefits are well summarized.
226-231: Disable Fiber CORS when using infrastructure CORS
The code snippet to removecors.New()is clear and actionable.
233-242: Detail Option 2: Application-Level CORS
The use-cases for Fiber middleware are well outlined.
244-251: List required preflight headers
The mandatory headers are accurately listed for correct preflight handling.
252-256: Highlight critical preflight warning
TheAccess-Control-Request-Methodrequirement warning is essential and stands out.
257-274: Enumerate CORS response headers
Comprehensive breakdown of headers for actual and preflight responses.
276-283: Common CDN pitfalls
Good coverage of CDN caching and header-forwarding concerns.
284-289: API Gateway CORS guidance
Clear advice on choosing gateway vs. app-level CORS.
290-293: Load Balancer/Proxy recommendations
Preserving CORS headers is correctly emphasized.
295-298: WAF/Security service considerations
Whitelist and allow OPTIONS requests to avoid unintended blocks.
300-307: Add debug middleware snippet
Helpful snippet to log OPTIONS request headers before the CORS middleware.
308-315: Debug middleware implementation
Use offmt.Printffor development logging is acceptable here.
316-321: Show middleware registration example
Complements the debug snippet with proper CORS middleware usage.
323-337: Provide curl examples for testing
The preflight and simple request examples are clear and practical.
339-347: Explain caching considerations
The Vary header guidance covers cache correctness and poisoning prevention.
349-359: Add decision matrix table
The scenarios table helps readers choose the right CORS approach.
gaby
changed the title
Improve the documentation for the CORS middleware by adding information about preflight requests and important infrastructure considerations to ensure proper configuration and functionality. Include debugging tips and common issues related to CORS headers in various deployment scenarios.
Closes #3501