docs: Explain the reason for passing an "empty" session to NewAccessRequest

[ovk]

Looking at the scarce documentation, example and the source code I am still puzzled by an seemingly empty session that is passed to NewAccessRequest function.

Here is an example from the readme:

// Create an empty session object which will be passed to the request handlers
mySessionData := newSession("")

// This will create an access request object and iterate through the registered TokenEndpointHandlers to validate the request.
accessRequest, err := oauth2.NewAccessRequest(ctx, req, mySessionData)

or here is similar code from example and here is same from even Hydra.

It is not clear what this session is for? Why is it empty? Shouldn't the actual session (the one that was passed to NewAuthorizeResponse) be persisted by store and used across endpoints?

I think the purpose of session object needs to be better explained in the docs. Still trying to figure out what is exactly needed for OIDC + Oauth2 with JWT stateless tokens (so far my working hypothesis is this)

[aeneasr]

The idea is similar to how JSON de/encoding works:

var sess Session
json.NewDecoder(...).Decoder(&sess)

This makes sense because the Session is polymorph and because Go doesn't support Generics (yet) we need another way of working with this polymorph object. Assuming the type in the store or somewhere else is quite tricky, so the easiest is to pass a reference to the memory you'd like to hydrate/use.

[ovk]

Thanks for the explanation, that's what I've guessed.

I also found this bug #256 which to me indicates that perhaps you should document this somewhere (maybe in the example code in the readme and the fosite-example?) to avoid possible confusion and similar questions in the future.

[aeneasr]

This is an open source project, and contributions towards documentation are really welcomed. So feel free to document this wherever you see fit!