docs: Deprecate the old middlewares

WithSessionV2/RequireSessionV2 are for quite some time the de-facto way
to use Clerk. Therefore, deprecate WithSession and update examples to
use WithSessionV2 instead.

Resolves #154

README.md

@@ -66,34 +66,24 @@ For more examples on how to use the client, refer to the [examples](https://gith
 
 ## Middleware
 
-In addition to the API operations, the SDK also provides a middleware that can be used to inject the active session into the request's context.
-The Clerk middleware expects a `clerk.Client` and resolves the active session using the incoming session cookie.
+The SDK provides a middleware, [`WithSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#WithSessionV2), that injects the active session into the request's context.
 
-The active session object will be added in the request's context using the key `clerk.ActiveSession`.
+The active session's claims can then be fetched using [`SessionFromContext`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#SessionFromContext).
 
 ```go
 mux := http.NewServeMux()
-injectActiveSession := clerk.WithSession(client)
+injectActiveSession := clerk.WithSessionV2(client)
 mux.Handle("/your-endpoint", injectActiveSession(yourEndpointHandler))
 ```
 
-For a full example of how to use the middleware, refer to
-[this](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware).
+Additionally, there's [`RequireSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#RequireSessionV2) that will halt the request and respond with 403 if the user is not authenticated. This can be used to restrict access to certain routes unless the user is authenticated.
 
-### Auth v2
-
-If you're using the newly-introduced [Auth v2](https://clerk.com/docs/upgrade-guides/auth-v2) scheme, you'll have to use the
-`clerk.WithSessionV2()` middleware, instead of `clerk.WithSession()`.
-
-Additionally, there's also `clerk.RequireSessionV2()` that will halt the request
-and respond with 403 if the user is not authenticated.
-
-Finally, to retrieve the authenticated session's claims you can use
-`clerk.SessionFromContext()`.
+For more info on how to use the middleware, refer to the
+[example](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware).
 
 ### Additional options
 
-The new middlewares (`clerk.WithSessionV2()` & `clerk.RequireSessionV2()`) also support the ability to pass some additional options.
+The middleware supports the following options:
 
 - clerk.WithAuthorizedParty() to set the authorized parties to check against the azp claim of the token
 - clerk.WithLeeway() to set a custom leeway that gives some extra time to the token to accommodate for clock skew

clerk/middleware.go

@@ -14,6 +14,8 @@ const (
 // with other packages
 )
 
+// Deprecated: this middleware handles the old authentication scheme. Use
+// WithSessionV2 instead.
 func WithSession(client Client) func(handler http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

clerk/middleware_v2.go

@@ -40,9 +40,9 @@ func SessionFromContext(ctx context.Context) (*SessionClaims, bool) {
 	return c, ok
 }
 
-// WithSessionV2 is the new middleware that supports Auth v2. If the session is
-// authenticated, it adds the corresponding session claims found in the JWT to
-// request's context.
+// WithSessionV2 is the de-facto authentication middleware and should be used
+// over WithSession. If the session is authenticated, it adds the corresponding
+// session claims found in the JWT to request's context.
 func WithSessionV2(client Client, verifyTokenOptions ...VerifyTokenOption) func(handler http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

examples/middleware/main.go

@@ -10,14 +10,18 @@ import (
 )
 
 func returnActiveSession(w http.ResponseWriter, req *http.Request) {
-	session := req.Context().Value(clerk.ActiveSession)
-	jsonResp, _ := json.Marshal(session)
+	sessionClaims, ok := clerk.SessionFromContext(req.Context())
+	if ok {
+		jsonResp, _ := json.Marshal(sessionClaims)
+		fmt.Fprintf(w, string(jsonResp))
+	} else {
+		// handle non-authenticated user
+	}
 
-	fmt.Fprintf(w, string(jsonResp))
 }
 
 func main() {
-	fmt.Print("Clerk API Key: ")
+	fmt.Print("Clerk secret key: ")
 	var apiKey string
 	fmt.Scanf("%s", &apiKey)
 
@@ -27,7 +31,7 @@ func main() {
 	}
 
 	mux := http.NewServeMux()
-	injectActiveSession := clerk.WithSession(client)
+	injectActiveSession := clerk.WithSessionV2(client)
 	mux.Handle("/session", injectActiveSession(http.HandlerFunc(returnActiveSession)))
 
 	err = http.ListenAndServe(":3000", mux)