Upgrade guide

View Source

3.x to 4.x

RedisStore changes

If you use Charon.SessionStore.RedisStore you must do the following before upgrading to 4.x:

  1. Prepare a maintenance window during which no session write operations take place (or risk an in-place data migration, with the possibility of some sessions being lost).
  2. Upgrade Charon to 4.x.
  3. Upgrade your Redis instance to 8.x.x or Valkey to 9.x.x.
  4. Run Charon.SessionStore.RedisStore.Migrate.migrate_v3_to_v4!/1.

JWT changes

JWT's signed with Blake3 keyed hashing are no longer supported because the Elixir Blake3 library is unmaintained. If you use this algorithm to sign your JWTs, you must migrate away from it. This can be done by replacing the key in the keyset, but that means you log out all existing sessions, which may or may not be a problem. However, Charon support cycling your keys gracefully: take a look at Charon.TokenFactory.Jwt.

Browser clients using :bearer token transport

Config option :enforce_browser_cookies has been flipped to true, as a secure default. This can cause problems if you have browser clients that use :bearer token transport (which they shouldn't). Make sure your browser clients request :cookie or :cookie_only tokens, and protect them against CSRF, or opt-out of the new, more secure default.

Charon.Utils.KeyGenerator no longer caches keys

A simple cache helper has been added as Charon.Utils.PersistentTermCache. If you use KeyGenerator, be sure to cache the resulting keys using an appropriate mechanism. Caching using :persistent_term should only be used for create-once-use-often keys, not dynamically generated keys.

Deprecated functions

All marked-as-deprecated functions from v3 have been dropped, so make sure your code does not use these functions anymore. The compiler emits warnings if you do.

2.x to 3.x

RedisStore changes

If you use Charon.SessionStore.RedisStore you must do the following before upgrading to 3.x:

  1. Update Charon to >= 2.8.0
  2. Upgrade your Redis instance to 7.x.x (this can be an in-place upgrade)
  3. Run Charon.SessionStore.RedisStore.migrate_sessions/1
  4. If you explicitly set config options :allow_unsigned? and :redix_module, you must remove your overrides. Support for these config options has been dropped.
  5. Initialize the Redix connection pool in your supervision tree. See readme section setting up a sessionstore.
  6. Remove your Redix module (if you don't use it for anything else).

Deprecated functions

All marked-as-deprecated functions have been dropped, so make sure your code does not use these functions anymore. The compiler emits warnings if you do.