feat: introduce experimental unstable_getServerSession API

[ThangHuuVu]

Reasoning 💡

Improve the getServerSession API to match the NextAuth API.

• Rename getServerSession to unstable_getServerSession
• Update part of docs (rest is in chore(docs): update securing pages tutorial #3982)

Checklist 🧢

• Documentation
• Tests
• Ready to be merged

Affected issues 🎟

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/nextauthjs/next-auth/4Sn474Kx6ArjZ923F4sxXM1Me7j4
✅ Preview: https://next-auth-git-fork-thanghuuvu-refactor-improv-abf15d-nextauthjs.vercel.app

[balazsorban44]

should we rather have a different response when there is or there isn't a session? Eg. return 401 if un authenticated

[balazsorban44]

Should we return a redirect if unauthenticated? https://nextjs.org/docs/api-reference/data-fetching/get-server-side-props#redirect

[ThangHuuVu]

Totally!

[ubbe-xyz]

Looking good for me ✅ ; I leave some small grammar suggestions 👍🏽

[balazsorban44]

Let's land this!

[Dragate]

Occurrences of getServerSession need to be replaced with unstable_getServerSession.

[ThangHuuVu]

@balazsorban44 please merge it when you're back! 🙌

[magicspon]

Is this documented anywhere?

[Dragate]

Is this documented anywhere?

https://next-auth.js.org/configuration/nextjs#unstable_getserversession

[ndom91]

It will require 24hrs for Algolia to scrape the latest docs page deployment and update the search index.

[larsqa]

The docs mention that this is an experimental feature, but nowhere to be found is why this is unstable. This makes it difficult for me as a user to figure out if I even should consider it before it becomes stable and look for alternatives.

Anyone mind to explain the "unstable" situation here?

[DavidJFelix]

I'm not super keen about how an API was removed (renamed) without a semver bump.

[ndom91]

@larsqa Theres a small note in the docs:

The unstable_getServerSession only has the prefix unstable_ at the moment, because the API may change in the future. There are no known bugs at the moment and it is safe to use. If you discover any issues, please do report them as a GitHub Issue and we will patch them as soon as possible.

The API was released with the unstable prefix, because we're still not 100% sure about a few things, in particular, we wanted to ensure we could still:

• Make it take in the same parameters with the middleware method
• Address that this API could be changed in the future releases when we finalize how to do authOptions properly 🤔

---

@DavidJFelix unstable_getServerSession was introduced in the 4.5.0...4.6.0 update

[DavidJFelix]

I think the issue really is a breaking change to getServerSession was introduced in the 4.5.0...4.6.0 update and it was documented as an addition of a new function, not the replacement/removal/renaming of an existing function. Semantics, I know, but that's SemVer.