adjust_xxx docs

[hyperknot]

First of all thanks for implementing the different cookie adjust methods, it's great! I've read the updated readme and the PRs, however some small things are still not clear:

• adjust_cookie_expires - clear what it does, might not be supported in WebOb 1.9+?

• adjust_cookie_max_age - clear what it does, this will be supported in WebOb in the future right?
  I guess the same is true for the .ini settings.

• cookie_expires= support on creating - hasn't this always been the case when using .ini settings?

• adjust_session_timeout this is clear, changes the TTL value in Redis

• adjust_session_expires this is the confusing one for me. Readme says that expires is only used in cookie context, nothing to do with Redis, except for If Redis stores our Timeout info, it stores it in an "expiry" value via SETEX or similar calls.

I'm only using the "basic" scenario with only timeout specified.

[jvanasco]

Sorry, I somehow missed the notification on this. I put a response on my todo list.

[jvanasco]

Hope this helps, @hyperknot

• adjust_cookie_expires. this invokes a cookie's expires via webob. web marked expires for deprecation because it can be confused with max-age. I don't believe it should be deprecated, as the browsers still support it. I filed a ticket on webob (should expires be removed from set_cookie? Pylons/webob#429) and urge everyone to lobby them to keep it in. expires and max-age are conflicting arguments that can be used to accomplish the same thing, they just have different input formats and a chain of precedence.

• adjust_cookie_max_age. this invokes the max-age on a cookie. webob has plans to deprecate expires in favor of only supporting max-age.

• cookie_expires support was introduced last year. this package was originally a fork from another redis package, which never supported that. I thought it did myself!

• adjust_session_timeout yes that is right.

• adjust_session_expires this gets confusing for me to. i wish i had time to sit down and think of better names for a 1.0 release!

There are three potential expiry mechanisms across two concepts and two hooks:

• Concept 1 - The Session

  • the Python payload has an internal expires attribute. This is used to timeout the session, and for triggering the timeout renewals. adjust_session_expires can be used to change this.
  • the Redis server can optionally track expiry itself (via SETEX, etc). Depending on server usage patterns, this may or may not want to be used. If the Python payload is adjusted, the updates should automatically cascade and affect this behind the scenes.

• Concept 2 - The Cookie

  • a cookie can be directly affected by an expires or max-age mechanism.
  • adjust_cookie_expires will queue an update to use the value in the cookie's expire argument. Because expire is being deprecated by webob, it is better to use adjust_cookie_max_age instead.

I added the adjust_cookie_expires functionality because some developers/situations might want to use it. I think you were the person who was trying to affect the underlying cookie a while back; adjust_cookie_expires and adjust_cookie_max_age were intended to support that.

[hyperknot]

Thanks a lot for the detailed response! Yes I was the one who wanted to support that. For me adjust_cookie_max_age is perfect! I personally don't use cookie expires, so that's not affecting me.

adjust_session_expires one thing still not clear to me: in the default case, with just redis.sessions.timeout specified, I believe Timeout is handled by Redis. In this case adjust_session_expires is the same as adjust_session_timeout? Or in this case adjust_session_expires doesn't do anything?

[jvanasco]

adjust_session_expires only affects a Python based expiration. If you're not configuring a session with Python expiry tracking, and all expiry is happening in Redis, then I believe it should enroll/upgrade the session into supporting Python expiry tracking.

The only thing those 2 functions do is to adjust the internal payloads, as seen here

They're both really just there to provide an interface for developers to adjust these values, which has been necessary a few times over the years, and not to support a specific use-case.