add a migration guide

README.md

@@ -102,6 +102,84 @@ should give you a response like
 ...
 ```
 
+## Migration Guide
+If you are moving from v1 to v2 this is the place for you.
+
+### `jwtmiddleware.Options`
+Now handled by individual [jwtmiddleware.Option](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#Option) items. They can be passed to [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New) after the [jwtmiddleware.ValidateToken](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ValidateToken) input:
+```golang
+jwtmiddleware.New(validator, WithCredentialsOptional(true), ...)
+```
+
+#### `ValidationKeyGetter`
+Token validation is now handled via a token provider which can be learned about in the section on [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New).
+
+#### `UserProperty`
+This is now handled in the validation provider.
+
+#### `ErrorHandler`
+We now provide a public [jwtmiddleware.ErrorHandler](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ErrorHandler) type:
+```golang
+type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error)
+```
+
+A [default](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#DefaultErrorHandler) is provided which translates errors into HTTP status codes.
+
+You might want to wrap the default so you can hook things into logging:
+```golang
+myErrHandler := func(w http.ResponseWriter, r *http.Request, err error) {
+	fmt.Printf("error in token validation: %+v\n", err)
+
+	jwtmiddleware.DefaultErrorHandler(w, r, err)
+}
+
+jwtMiddleware := jwtmiddleware.New(validator.ValidateToken, jwtmiddleware.WithErrorHandler(myErrHandler))
+```
+
+#### `CredentialsOptional`
+Use the option function [jwtmiddleware.WithCredentialsOptional(true|false)](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithCredentialsOptional). Default is false.
+
+#### `Extractor`
+Use the option function [jwtmiddleware.WithTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithTokenExtractor). Default is to extract tokens from the auth header.
+
+We provide 3 different token extractors:
+- [jwtmiddleware.AuthHeaderTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#AuthHeaderTokenExtractor) a rename of `jwtmiddleware.FromAuthHeader`.
+- [jwtmiddleware.CookieTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#CookieTokenExtractor) a new extractor.
+- [jwtmiddleware.ParameterTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ParameterTokenExtractor) a rename of `jwtmiddleware.FromParameter`.
+
+And also an extractor which can combine multiple different extractors together: [jwtmiddleware.MultiTokenExtractor](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#MultiTokenExtractor) a rename of `jwtmiddleware.FromFirst`.
+
+#### `Debug`
+Dropped. We don't believe that libraries should be logging so we have removed this option.
+If you need more details of when things go wrong the errors should give the details you need.
+
+#### `EnableAuthOnOptions`
+Use the option function [jwtmiddleware.WithValidateOnOptions(true|false)](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithValidateOnOptions). Default is true.
+
+#### `SigningMethod`
+This is now handled in the validation provider.
+
+### `jwtmiddleware.New`
+A token provider is setup in the middleware by passing a [jwtmiddleware.ValidateToken](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#ValidateToken) function:
+```golang
+func(context.Context, string) (interface{}, error)
+```
+to [jwtmiddleware.New](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#New).
+
+In the example above you can see [github.com/auth0/go-jwt-middleware/validate/josev2](https://pkg.go.dev/github.com/auth0/[email protected]/validate/josev2) being used.
+
+This change was made in order to allow JWT validation provider to be easily switched out.
+
+Options are passed into `jwtmiddleware.New` after validation provider and use the `jwtmiddleware.With...` functions to set options.
+
+### `jwtmiddleware.Handler*`
+Both `jwtmiddleware.HandlerWithNext` and `jwtmiddleware.Handler` have been dropped.
+You can use [jwtmiddleware.CheckJWT](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#JWTMiddleware.CheckJWT) instead which takes in an `http.Handler` and returns an `http.Handler`.
+
+### `jwtmiddleware.CheckJWT`
+This function has been reworked to be the main middleware handler piece and so we've dropped the functionality of it returning and error.
+If you need to handle any errors please use the [jwtmiddleware.WithErrorHandler](https://pkg.go.dev/github.com/auth0/go-jwt-middleware#WithErrorHandler) function.
+
 ## Issue Reporting
 
 If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.

jwtmiddleware.go

@@ -76,15 +76,6 @@ type JWTMiddleware struct {
 // Option is how options for the middleware are setup.
 type Option func(*JWTMiddleware)
 
-// WithValidateToken sets up the function to be used to validate all tokens.
-// See the ValidateToken type for more information.
-// Default: TODO: after merge into `v2`
-func WithValidateToken(vt ValidateToken) Option {
-	return func(m *JWTMiddleware) {
-		m.validateToken = vt
-	}
-}
-
 // WithErrorHandler sets the handler which is called when there are errors in
 // the middleware. See the ErrorHandler type for more information.
 // Default value: DefaultErrorHandler