Start versioning from v4 to track Echo versions

Author: aldas

README.md

@@ -1,18 +1,27 @@
 # Echo JWT middleware
 
-JWT middleware for [Echo](https://github.com/labstack/echo) framework. By default uses [golang-jwt/jwt/v4](https://github.com/golang-jwt/jwt) 
+JWT middleware for [Echo](https://github.com/labstack/echo) framework. This middleware uses by default [golang-jwt/jwt/v4](https://github.com/golang-jwt/jwt) 
 as JWT implementation.
 
+## Versioning
+
+This repository does not use semantic versioning. MAJOR version tracks which Echo version should be used. MINOR version
+tracks API changes (possibly backwards incompatible) and PATCH version is incremented for fixes.
+
+For Echo `v4` use `v4.x.y` releases.
+
+`main` branch is compatible with the latest Echo version.
+
 ## Usage
 
 Add JWT middleware dependency with go modules
 ```bash
-go get github.com/labstack/echo-jwt
+go get github.com/labstack/echo-jwt/v4
 ```
 
 Use as import statement
 ```go
-import "github.com/labstack/echo-jwt"
+import "github.com/labstack/echo-jwt/v4"
 ```
 
 Add middleware in simplified form, by providing only the secret key
@@ -31,6 +40,10 @@ e.Use(echojwt.WithConfig(echojwt.Config{
 
 Extract token in handler
 ```go
+import "github.com/golang-jwt/jwt/v4"
+
+// ...
+
 e.GET("/", func(c echo.Context) error {
   token, ok := c.Get("user").(*jwt.Token) // by default token is stored under `user` key
   if !ok {
@@ -52,7 +65,7 @@ package main
 import (
 	"errors"
 	"github.com/golang-jwt/jwt/v4"
-	"github.com/labstack/echo-jwt"
+	"github.com/labstack/echo-jwt/v4"
 	"github.com/labstack/echo/v4"
 	"github.com/labstack/echo/v4/middleware"
 	"log"

go.mod

@@ -1,4 +1,4 @@
-module github.com/labstack/echo-jwt
+module github.com/labstack/echo-jwt/v4
 
 go 1.17
 

jwt_extranal_test.go

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: © 2016 LabStack and Echo contributors
+
+package echojwt_test
+
+import (
+	"errors"
+	"fmt"
+	"github.com/golang-jwt/jwt/v4"
+	echojwt "github.com/labstack/echo-jwt/v4"
+	"github.com/labstack/echo/v4"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"time"
+)
+
+func ExampleJWTWithConfig_usage() {
+	e := echo.New()
+
+	e.Use(echojwt.WithConfig(echojwt.Config{
+		SigningKey: []byte("secret"),
+	}))
+
+	e.GET("/", func(c echo.Context) error {
+		// make sure that your imports are correct versions. for example if you use `"github.com/golang-jwt/jwt"` as
+		// import this cast will fail and `"github.com/golang-jwt/jwt/v4"` will succeed.
+		// Although `.(*jwt.Token)` looks exactly the same for both packages but this struct is still different
+		token, ok := c.Get("user").(*jwt.Token) // by default token is stored under `user` key
+		if !ok {
+			return errors.New("JWT token missing or invalid")
+		}
+		claims, ok := token.Claims.(jwt.MapClaims) // by default claims is of type `jwt.MapClaims`
+		if !ok {
+			return errors.New("failed to cast claims as jwt.MapClaims")
+		}
+		return c.JSON(http.StatusOK, claims)
+	})
+
+	// ----------------------- start server on random port -----------------------
+	l, err := net.Listen("tcp", ":0")
+	if err != nil {
+		log.Fatal(err)
+	}
+	go func(e *echo.Echo, l net.Listener) {
+		s := http.Server{Handler: e}
+		if err := s.Serve(l); err != http.ErrServerClosed {
+			log.Fatal(err)
+		}
+	}(e, l)
+	time.Sleep(100 * time.Millisecond)
+
+	// ----------------------- execute HTTP request with valid token and check the response -----------------------
+	requestURL := fmt.Sprintf("http://%v", l.Addr().String())
+	req, err := http.NewRequest(http.MethodGet, requestURL, nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+	req.Header.Set(echo.HeaderAuthorization, "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ")
+
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	body, err := io.ReadAll(res.Body)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Response: status code: %d, body: %s\n", res.StatusCode, body)
+
+	// Output: Response: status code: 200, body: {"admin":true,"name":"John Doe","sub":"1234567890"}
+}