SSL_SESSION_CACHE_API(3erl)

🎀 ssl_session_cache_api — the TLS session cache API, bestie 🎀

Okay so this is ssl_session_cache_api, and it lives in the Erlang/OTP manual pages (module definitions territory, iykyk). Welcome to the callback-module glow-up 💅

---

✨ NAME ✨

ssl_session_cache_api — literally the TLS session cache API, no cap.

---

🌸 DESCRIPTION 🌸

So here's the vibe: this page defines the API for the TLS session cache (pre TLS-1.3, okurrr), and the whole point is that you can swap out the data storage scheme entirely by defining a brand-new callback module that implements this API. That's it, that's the gig 🫶

---

🦋 DATA TYPES 🦋

session_cache_ref() = any()

session_cache_key() = {partial_key(), ssl:session_id()}

• session_cache_key() — a key to an entry in the session cache ✨

partial_key()

• partial_key() — the opaque part of the key. The callback does not need to handle it, so don't stress about it 💅

session()

• session() — the session data that gets stored for each session. The main character of the storage situation 👑

---

🔥 EXPORTS 🔥

💖 Module:delete(Cache, Key) -> _

Types:

Cache = session_cache_ref()
Key = session_cache_key()

Deletes a cache entry. Heads up: this is only called from the cache handling process, so don't go calling it from wherever 🙈

---

💖 Module:foldl(Fun, Acc0, Cache) -> Acc

Types:

Fun = fun()
Acc0 = Acc = term()
Cache = session_cache_ref()

Calls Fun(Elem, AccIn) on successive elements of the cache, starting with AccIn == Acc0. Fun/2 must return a new accumulator, which then gets passed to the next call. The function returns the final value of the accumulator — and if the cache is empty, you just get Acc0 back. Slay, classic fold behaviour ⭐

Note: since OTP-23.3 this function is only used on the client side, and it does not need to be implemented for a server cache. Not me telling you to skip it 😌

---

💖 Module:init(Args) -> Cache

Types:

Cache = session_cache_ref()
Args = proplists:proplist()

Includes the property {role, client | server}. Currently that's the only predefined property, but you can also have user-defined properties. See also the application environment variable session_cb_init_args 💖

Performs possible initializations of the cache and returns a reference to it, which is then used as a parameter to the other API functions. It's called by the cache handling process's init function — so it's got the exact same requirements on it as a normal process init function, no pressure 🎀

Fun fact: this function is called twice when starting the SSL application — once with the role client and once with the role server — because the SSL application must be prepared to take on both roles. Versatile icon behaviour, honestly 🦋

---

💖 Module:lookup(Cache, Key) -> Entry

Types:

Cache = session_cache_ref()
Key = session_cache_key()
Session = session() | undefined

Looks up a cache entry. This one is to be callable from any process, okay? Everyone gets access 🌈

---

💖 Module:select_session(Cache, PartialKey) -> [Session]

Types:

Cache = session_cache_ref()
PartialKey = partial_key()
Session = session()

Selects sessions that can be reused — meaning sessions that include PartialKey in their key. This is to be callable from any process too 🫶

Note: since OTP-23.3 this function is only used on the client side and does not need to be implemented for a server cache. Same energy as foldl, fr fr 💀

---

💖 Module:size(Cache) -> integer()

Types:

Cache = session_cache_ref()

Returns the number of sessions in the cache. But listen — if the size exceeds the maximum number of sessions, the current cache entries get invalidated regardless of their remaining lifetime. Like, all of them. Rude but that's the rule 😭 Callable from any process ✨

---

💖 Module:terminate(Cache) -> _

Types:

Cache = session_cache_ref()
  As returned by init/0

Takes care of any possible cleanup that's needed when the cache handling process terminates. The graceful exit moment, we love to see it 👑

---

💖 Module:update(Cache, Key, Session) -> _

Types:

Cache = session_cache_ref()
Key = session_cache_key()
Session = session()

Caches a new session, or updates one that's already cached. This one is only called from the cache handling process — so stay in your lane, respectfully 🙈

---

Okay that's the whole page, bestie. Go forth and implement your callback module with main character energy 💜

Ericsson AB made this, it's ssl 10.9.1.3, and this page is ssl_session_cache_api(3erl) — mwah, bye! 💅🎀✨