refactor(router): correct HTTP verb for session refresh endpoint

Since this changes the state for a user's session, a POST is more
appropriate than just a GET - even though the POST body is empty.

We keep the GET route temporarily to allow any consumers to migrate.

README.md

@@ -166,13 +166,28 @@ For production use, we strongly recommend setting up and connecting to Redis.
 Sessions can be configured with a maximum lifetime with the `session.max-lifetime` flag, which accepts Go duration strings
 (e.g. `10h`, `5m`, `30s`, etc.).
 
-There's also an endpoint that returns metadata about the user's session as a JSON object at `/oauth2/session`. This
+There's also an endpoint that returns metadata about the user's session as a JSON object at `GET /oauth2/session`. This
 endpoint will respond with HTTP status codes on errors:
 
 - `401 Unauthorized` - no session cookie or matching session found (e.g. user is not authenticated, or has logged out)
 - `500 Internal Server Error` - the session store is unavailable, or Wonderwall wasn't able to process the request
 
-Otherwise, an `HTTP 200 OK` is returned with the metadata with the `application/json` as the `Content-Type`, e.g:
+Otherwise, an `HTTP 200 OK` is returned with the metadata with the `application/json` as the `Content-Type`.
+
+#### Example
+
+Request:
+
+```
+GET /oauth2/session
+```
+
+Response:
+
+```
+HTTP/2 200 OK
+Content-Type: application/json
+```
 
 ```json
 {
@@ -217,9 +232,24 @@ happens whenever the end-user visits any path that is proxied to the upstream ap
 
 The `session.refresh` flag also enables a new endpoint:
 
-- `/oauth2/session/refresh` - manually refreshes the tokens for the user's session, and returns the metadata like in 
+- `POST /oauth2/session/refresh` - manually refreshes the tokens for the user's session, and returns the metadata like in 
 `/oauth2/session` described previously
 
+#### Example
+
+Request:
+
+```
+POST /oauth2/session/refresh
+```
+
+Response:
+
+```
+HTTP/2 200 OK
+Content-Type: application/json
+```
+
 ```json
 {
   "session": {

pkg/handler/handler_test.go

@@ -766,7 +766,7 @@ func sessionRefresh(t *testing.T, idp *mock.IdentityProvider, rpClient *http.Cli
 	sessionRefreshURL, err := url.Parse(idp.RelyingPartyServer.URL + "/oauth2/session/refresh")
 	assert.NoError(t, err)
 
-	return get(t, rpClient, sessionRefreshURL.String())
+	return post(t, rpClient, sessionRefreshURL.String())
 }
 
 func waitForRefreshCooldownTimer(t *testing.T, idp *mock.IdentityProvider, rpClient *http.Client) {
@@ -817,6 +817,29 @@ func get(t *testing.T, client *http.Client, url string) response {
 	}
 }
 
+func post(t *testing.T, client *http.Client, url string) response {
+	req, err := http.NewRequest(http.MethodPost, url, nil)
+	assert.NoError(t, err)
+
+	resp, err := client.Do(req)
+	assert.NoError(t, err)
+	defer resp.Body.Close()
+
+	location, err := resp.Location()
+	if !errors.Is(http.ErrNoLocation, err) {
+		assert.NoError(t, err)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	assert.NoError(t, err)
+
+	return response{
+		Body:       string(body),
+		Location:   location,
+		StatusCode: resp.StatusCode,
+	}
+}
+
 type upstream struct {
 	Server          *httptest.Server
 	URL             *url.URL

pkg/router/router.go

@@ -65,7 +65,8 @@ func New(src Source) chi.Router {
 				r.Get(paths.LogoutFrontChannel, src.LogoutFrontChannel)
 				r.Get(paths.LogoutCallback, src.LogoutCallback)
 				r.Get(paths.Session, src.Session)
-				r.Get(paths.SessionRefresh, src.SessionRefresh)
+				r.Get(paths.SessionRefresh, src.SessionRefresh) // TODO: for legacy purposes, remove after grace period
+				r.Post(paths.SessionRefresh, src.SessionRefresh)
 			})
 		}
 	})