Vault is a lightweight Elixir library for immutable data storage within a process subtree.

Due to Elixir’s actor model nature, it’s common for a process to have global context that is valid for every function call inside the process and its children.

For example, this context can include:

• A user when processing a request
• A tenant in a multi-tenant application
• Rate limiting buckets/quotas
• Cache namespaces
• API or client versions
• And many more, depending on your application domain

Vault.init/1 provides you a guarantee that the context can only be defined once per existing process subtree, so you won’t override it by accident. This makes it easy to reason about your context origination.

# Initialize vault in parent process
Vault.init(current_user: %{id: 1, first_name: "Alice", role: "admin"})

# Access data from any descendant process, even these not linked!
spawn(fn ->
  Vault.get(:current_user) # => %{id: 1, first_name: "Alice", role: "admin"}

  Vault.init(current_user: :user) # => raises, because the ancestor already has vault initialized
end)

# Access data from the parent process itself
Vault.get(:current_user) # => %{id: 1, first_name: "Alice", role: "admin"}

In my case, repeatedly passing the user from the connection and GraphQL context into lower-level functions became hard to maintain.

A typical flow involved extracting the user from the Absinthe resolution context, performing substantial business logic, and only at the end persisting data or writing to the audit log - both of which also required the user. Maintaining this plumbing was cumbersome.

Because the user is immutable for the lifetime of the request and retrieved only once, storing it in the process dictionary is an elegant way to eliminate redundant parameters and simplify the overall flow.

This approach does introduce an implicit dependency - the need to understand where the value originates - but since it’s initialized exactly once, the trade-off is acceptable. In most cases, callers can simply read the value without needing to think about its source.

Properties

• Immutability guarantees. Initializes only once per process tree - will raise if one of ancestors already has vault initialized.
• Familiar API - API is the same as for Elixir’s Map module, except for Vault.init part.
• Any child process will have access to the parent’s Vault. We’re using ProcessTree library by JB Steadman, which does all the heavy lifting of traversing process trees and propagating data back. You can read more about how ancestors are fetched in this amazing blog post by the library’s author.
• Once the vault is found on one of the parents, it’s cached (set in the child’s process dict), so next fetches are faster.
• We have a set of unsafe_* functions to perform updates on already initialized vault. These updates won’t propagate to the children that already initialized the vault.

I’m really curious what you guys think!