Docs should better explain what this package actually does

[jonchurch]

Cutting this issue to track some docs changes I have queued up, and am open to feedback.

CORS is confusing, infamously so. And we will sometimes get users who are confused about what it is and how it works.

I don't really want the README to try and teach folks everything about CORS, but I do want to try and help people out by improving the documentation to hopefully catch some of the repeat issues we see.

So below is a summary of what I've seen across various issues historically here, and some simple suggestions for improving the readme.

Problem

Users regularly open issues demonstrating misunderstandings about what this package does:

• Incorrect CORS response when origin is set to a String #365 - User thought origin: 'http://example.com' would block other origins server-side
• Why run request handlers "successfully" if the request fails CORS? #109 - "Why run request handlers successfully if the request fails CORS?"
• "origin" is undefined when requests are received from the same server AND when malicious requests are sent from a program #296 - User wanted to prevent "malicious requests from Postman"
• Get request is returning 200 even when origin not allowed #27 - "GET request is returning 200 even when origin not allowed"
• Should CORS deny access from curl requests?  #8 - "Should CORS deny access from curl requests?"

The common thread: users think CORS is server-side access control.

The documentation doesn't clearly state what the library actually does, and uses ambiguous language:

• "Enable CORS" / "allow origins" suggests blocking
• "reflect" is jargon that doesn't explain actual header behavior
• No mention that browsers enforce CORS, not servers

Proposed Improvements

• Add a clear callout explaining that CORS is browser enforced, not server-enforced
  • docs: tweak intro, add note w/ browser enforcement, FAQ  #385
• Add a "Common Misconceptions" section addressing the patterns seen in issues, that way we have something to link people to within the repo.
  • docs: tweak intro, add note w/ browser enforcement, FAQ  #385
• Replace ambiguous language with explicit descriptions of what headers get set
  • docs: tighten prose and clarify configuration options #387
• Add comments to code examples showing the actual response headers
  • docs: simplify code examples with header comments #386

[jonchurch]

cc @UlisesGascon

[jub0bs]

CORS is confusing, infamously so. And we will sometimes get users who are confused about what it is and how it works.

Two more ideas for v3 that would help clear up some of the confusion surrounding CORS:

• mercilessly validate configuration and fail early rather than produce dysfunctional middleware,
• provide a debug mode useful for troubleshooting why CORS preflight fails.