Session Extension

Client Session Management Extension

This extension provides a modular approach to managing sessions, with the concept of a "default" engine handling most attribute requests, and optional additional engines accessible by their name. It populates (lazily) a context.session object whose attributes are (lazily) loaded on access.

An extensive API of callbacks are provided to session engines, while also passing through the WebCore extension level callbacks directly. Certain objects conform to protocols, please see the read-me and individual callbacks below for details.

Session Extension Constructor

When instantiating a SessionExtension configuration is pulled from explicitly passed arguments, environment variables, then defaults, in that order of precedence.

Configuration

• secret — string — 📖 WEBCORE_SESSION_SECRET
  An application-secret value used as the cryptographic basis for cookie validation. Must be set to a reasonably large random, but consistent value in production environments. Can be changed to invalidate all active sessions simultaneously.

  In development, if unset, a suitable random value will be generated on each application startup. In production environments, omitting a secret is a fatal error.

• default — session implementation
  An object implementing the session interface to be used as the "root level" of the context.session. This becomes the target of otherwise unknown attribute access to the context.session object, e.g. ones that are not other named session back-ends.

  If no default is provided, a MemorySession instance will be automatically constructed and utilized, and a warning emitted as sessions will not persist beyond an application process restart.

• expires — timedelta or integer — 📖 WEBCORE_SESSION_EXPIRES
  The maximum lifetime of an abandoned session; one that has not been accessed after this duration will be automatically culled. Also used as the default cookie max_age, if set. Integers represent the number of hours.

• cookie — dictionary/mapping — 📖 Multiple
  Cookie settings, to be passed through as arguments to the context.response.set_cookie WebOb helper. For documentation on these valid members, please reference that WebOb documentation. These include:

  • path — string — 📖 WEBCORE_SESSION_PATH
  • domain — string — 📖 WEBCORE_SESSION_DOMAIN
  • comment — string — 📖 WEBCORE_SESSION_COMMENT
  • expires — complex — 📖 WEBCORE_SESSION_EXPIRES
  • max_age — complex — 📖 WEBCORE_SESSION_MAX_AGE
  • httponly — boolean — 📖 WEBCORE_SESSION_HTTPONLY
  • secure — boolean — 📖 WEBCORE_SESSION_SECURE
  • samesite — string enum — 📖 WEBCORE_SESSION_SAMESITE

• refresh — boolean — 📖 WEBCORE_SESSION_REFRESH If a valid session is detected, automatically "refresh" the cookie to ensure it has an updated expiry time, and extend the lifetime of the underlying session to match. Set this to a falsy value if you wish your sessions to have a fixed lifespan from the point of initial creation, otherwise sessions will only "expire" after being abandoned for this duration.

• Named Session Implementations Additional keyword arguments to the constructor are interpreted as named session implementation instances, to be bound as attributes to the context.session object for use during the request.