DEV Community: Jules Smeets

Dynamic machine ID leases in Elixir

Jules Smeets — Wed, 19 Aug 2026 18:55:36 +0000

Distributed ID generators often look simple: combine a timestamp, a counter, and a machine ID. NoNoncense uses that idea for fast counter, sortable, and encrypted nonces. It is a wonderfully fast design, right up until two running nodes receive the same machine ID.

The hard part is not incrementing a counter. It is deciding who may use each machine ID, especially when pods are replaced, nodes autoscale, deployments overlap, and network partitions happen. Two locally correct counters with the same machine ID can produce globally duplicate values.

NoNoncense 1.x left that decision to application startup: derive an ID, initialize the nonce factory, and make the topology safe yourself. That is perfectly reasonable for a fixed fleet. Version 2.0 brings the decision into the supervision tree and gives different deployments a suitable way to establish exclusivity.

Where exclusivity comes from

The strategy is not an afterthought; it expresses what makes an ID unique in a particular deployment:

SQL leases coordinate through PostgreSQL or MySQL. They are a natural fit when the application already has a database and wants a durable, inspectable source of truth.
Valkey or Redis leases use modern per-field hash TTLs for a compact, server-managed lease registry.
Kubernetes StatefulSets can use the pod ordinal through an environment variable when that ordinal is globally unique among nonce-generating pods.
Host identifiers retain the fixed-node model for deployments with a known, stable node list.

The last two are intentionally uncomplicated: when the platform can prove an instance's identity, NoNoncense can use it directly. The interesting work begins when it cannot and the application needs to coordinate competing nodes.

One lifecycle, several coordinators

For dynamic deployments, NoNoncense treats a machine ID as a lease. NoNoncense.MachineId starts a LeaseManager under supervision and waits for it to acquire an initial lease before application startup can complete. Only then are the configured nonce factories initialized. There is no interval in which a node generates values with an unproven ID.

The manager then renews the lease in the background. Its strategy interface distinguishes a confirmed loss from an uncertain result:

{:ok, lease, ttl_ms}
{:error, :lost, reason}
{:error, :retry, reason}

lost means the coordinator has positively rejected ownership, perhaps because the lease expired and somebody else claimed the ID. retry means the result is uncertain: a timeout or a dropped connection might have happened before or after the coordinator applied the renewal. The manager retries uncertainty for a bounded period, but on confirmed loss or local expiry it erases the affected factories and calls the optional :on_lease_lost callback. Continuing after that would trade an availability problem for a uniqueness problem, so the library chooses uniqueness.

For dynamic strategies, it then retries acquisition with backoff and reinitializes the factories only after it holds a new lease. That makes recovery part of the component's normal lifecycle rather than a bespoke application failure path.

The manager also has a small, in-memory lease cache. If the manager itself crashes and supervision restarts it, it first tries to renew the cached lease rather than needlessly claim another one of the 512 available IDs. The cache is deliberately not durable: after a node crash or forced kill, normal lease expiry remains the source of truth.

This lifecycle is not limited to the included backends. A strategy is a small behaviour that implements acquire/2, renew/3, release/2, and declares whether its IDs are deterministic. Applications can therefore bring a coordinator with their own allocation rules while keeping the same startup, recovery, and safety policy.

With that shared lifecycle in place, the interesting question becomes how a coordinator makes ownership atomic without slowing the nonce path down.

SQL: let the database arbitrate the race

The SQL strategy works with PostgreSQL and MySQL using a small, pre-populated lease table. Each possible machine ID has a row containing an expiry time, an ownership token, and a lock version.

Acquisition is a two-stage optimistic operation:

Read a small set of expired candidate rows, ordered by ID.
Attempt to claim one with an UPDATE that matches both its ID and the lock_version just read.

The update sets a new random token, moves expires_at forward, and increments the version. If two nodes read the same expired row, they both try to update it, but only one update still matches the old version. The loser tries another candidate. The database turns a familiar optimistic-locking primitive into lease arbitration: no process-local lock, no table-wide lock, and no opportunity to overwrite a concurrent claim.

The strategy uses CURRENT_TIMESTAMP in the database for both expiry checks and new expirations. That is a small but important choice: eligibility is decided by one clock, rather than by application nodes whose clocks may disagree.

Once claimed, the random token becomes the lease identity. Renewals and releases match both the machine ID and that token, so a node that has lost its lease cannot extend or release the next owner's row.

Valkey and Redis: turn field existence into ownership

Redis 8 and Valkey 9 add HSETEX: conditional hash updates with a per-field TTL. That makes it possible to store all leases in one hash without a polling cleanup job.

At first, an ID field appears sufficient:

"17" => "random-token"

But HSETEX conditions check field existence, not whether a field still holds a particular value. A renewal conditioned only on field "17" could refresh an ID after another owner had taken it. That is exactly the operation a lease protocol must reject.

NoNoncense writes two fields in one HSETEX command, with the same TTL:

"17"                    => "random-token"
"token.17.random-token" => "17"

The first field makes occupied IDs easy to discover. The second is an ownership marker: its key contains both the ID and the token. On acquisition, HSETEX ... FNX creates both fields only if neither already exists. On renewal or release, HSETEX ... FXX succeeds only if both fields still exist.

When a lease expires, both fields disappear together. A later owner will create a new token marker, not the old one. Therefore an old owner cannot refresh or delete the new owner's lease: its marker is absent, so the conditional command returns zero updated fields and the manager treats the lease as lost.

This is the useful pattern here: when a datastore can conditionally test only existence, give each ownership generation its own expiring marker and update the resource and marker atomically. The marker converts an existence check into proof that this exact owner still has the right to act.

Fast generation, deliberate ownership

The new strategies make the same promise in different environments: nonce factories run only while the deployment can establish that their machine ID belongs to them. SQL gets there with a database clock, tokens, and optimistic compare-and-swap. Valkey and Redis get there with an atomic, expiring ownership marker. StatefulSets and fixed fleets can use the identity their platform already provides.

The optional conflict guard adds another signal for connected Erlang nodes, and optional Telemetry reports acquisition, renewal, retries, loss, release, and conflicts. Neither feature touches the nonce generation hot path.

The result is a deliberately asymmetric design: the path that generates a nonce stays tiny and fast, while the rare coordination path does the careful work needed to answer one question with confidence: who is allowed to generate values with this machine ID right now?

NoNoncense 2.0 is available on Hex. The machine ID documentation and migration guide cover configuration and upgrading from 1.x.

JWTs in Elixir: fast parsing by plain pattern matching

Jules Smeets — Thu, 26 Mar 2026 21:35:01 +0000

JSON Web Tokens (JWTs) are the backbone of modern authentication. If you are building an API, chances are you are verifying a JWT on almost every single incoming request.

Because it happens so frequently, JWT verification is a prime candidate for optimization. But if you look at how standard JWT verification works, there is a lot of hidden overhead.

The Standard "Slow Path"

A JWT consists of three parts separated by dots: header.payload.signature. To verify a standard token, your application typically has to do the following:

Split the string by the . character using String.split/2 and/or regex.
Base64-decode the header.
Parse the resulting JSON string into a map.
Extract the kid (Key ID) and alg (Algorithm) claims.
Look up the correct public or symmetric key.
Verify the signature against the payload.

Steps 1 through 4 require allocating memory for new binaries, running a Base64 decoder, and firing up a JSON parser—all just to figure out which key to use.

If your application is minting its own tokens, 99% of the incoming requests are going to use your current, active signing key. Doing all that decoding and parsing on every request is wasted effort.

Our own header is always the same

The realization that speeds this up is simple: if you control the active signing key, the JWT header is entirely predictable.

Instead of extracting the token's header to find the key, we can flip the process upside down. We can pre-calculate exactly what the Base64-encoded header will look like for our active key, and use it to fast-track both signing and verifying tokens.

Setup: Caching the Header

The first step is to calculate the expected header at startup (or upon key rotation) and cache it. We use Erlang's :persistent_term for blazing fast, concurrent read access.

defmodule MyApp.Jwt do
  @doc "Run this at application startup or when rotating keys"
  def setup_fast_path(kid, alg \\ "HS256") do
    expected_header =
      # we need deterministic JSON with predictable key ordering
      ~s({"alg":"#{alg}","typ":"JWT","kid":"#{kid}"})
      |> Base.url_encode64(padding: false)

    :persistent_term.put(:jwt_header, expected_header)
  end
end

Fast-track verification

The real magic happens when checking incoming requests. We use Elixir's binary pattern matching to instantly route the token based on whether it starts with our cached header:

def verify(token) do
  expected_header = :persistent_term.get(:jwt_header, nil)

  case token do
    # Does the token start with our exact pre-calculated header?
    <<^expected_header::binary, ?., payload_and_sig::binary>> -> 
      fast_verify(payload_and_sig)

    # ... slow path fallback ...
    _ ->
      slow_verify(token)
  end
end

The binary pattern matching is Elixir at its finest. The VM doesn't need to split strings or allocate new memory to do so. It simply looks at the bytes of the incoming token, checks if they match the pinned expected_header variable followed by a . character, and assigns the rest of the binary to payload_and_sig. We now know the signing key and algorithm without parsing the header!

We are not done, however, and can take pattern matching one step further to split the payload and signature. This relies on two things: we know the signature's length in advance and can use byte_size/1 to determine the length of the whole (in constant time!):

# For HS256, the encoded signature is always exactly 43 characters
@hs256_sig_len 43

def fast_verify(payload_and_sig) do
  payload_len = byte_size(payload_and_sig) - @hs256_sig_len - 1

  case payload_and_sig do
    <<enc_payload::binary-size(payload_len), ?., enc_sig::binary-size(@hs256_sig_len)>> ->
      # We skipped String.split/2 entirely!
      # Now we just decode the payload and verify the signature...
      do_crypto_verify(enc_payload, enc_sig)

    _ ->
      {:error, :malformed_token}
  end
end

Signing

Of course, we can also use our precomputed header to speed up token signing (also leveraging iolists to prevent creating unnecessary intermediate binaries):

def sign(payload, key) do
  header = :persistent_term.get(:jwt_header, nil)
  enc_payload = payload |> JSON.encode!() |> Base.url_encode64(padding: false)
  mac_base = [header, ?., enc_payload]
  sig = :crypto.mac(:hmac, :sha256, key, mac_base) |> Base.url_encode64(padding: false)
  IO.iodata_to_binary([mac_base, ?., sig])
end

What if the header is not fully deterministic? Poly1305 and Base64 Magic

The optimization above works flawlessly for algorithms like HS256 or EdDSA. But what if you are using a MAC generated via Poly1305?

Poly1305 requires a unique nonce for every single invocation to remain secure. This means our JWT header suddenly needs to look like this:
{"alg":"Poly1305","typ":"JWT","nonce":"<random_string>","kid":"my_key"}

Because the nonce changes every time, we can no longer pre-calculate the entire Base64 encoded header. Does this mean we have to fall back to the slow path? Not if we use a little Base64 math.

Base64 works by encoding 3 bytes of raw data into 4 characters. If a string's byte length is exactly a multiple of 3, it encodes cleanly without padding (=) and without carrying over bits into the next character block. Such encoded strings can then be safely concatenated without invalidating the encoding!

We can exploit this by carefully crafting our JSON header so the static parts are multiples of 3 bytes:

Part 1: {"alg":"Poly1305","typ":"JWT","nonce":" (Length is 39, and 39 / 3 = 13. Perfect!)
Part 2: <dynamic_nonce>", (The nonce is 12 bytes, which encodes to 16 bytes. We add ", and part 2 is now 18 bytes - dividable by 3!)
Part 3: "kid": (Length is 6!)
Part 4: "my_key"} (The last part has no length requirement because nothing will be concatenated to its tail)

Because Parts 1, 2 and 3 are multiples of 3, we can safely pre-calculate their Base64 equivalents and concatenate them with the encoded dynamic bits later:

# Pre-encoded static chunks (safe to concatenate)
@p1305_h ~s({"alg":"Poly1305","typ":"JWT","nonce":") |> Base.url_encode64(padding: false)
@p1305_kid_seg ~s("kid":) |> Base.url_encode64(padding: false)

def setup_poly1305_fast_path(kid) do
  exp_htail = ~s("#{kid}"}) |> Base.url_encode64(padding: false)
  :persistent_term.put(:jwt_p1305_header, exp_htail)
end

Now, we can add a new pattern match to our verify/1 function to catch Poly1305 tokens. We just extract the encoded nonce_seg right out of the middle of the binary string:

def verify(token) do
  exp_header = :persistent_term.get(:jwt_header, nil)
  exp_htail  = :persistent_term.get(:jwt_p1305_header, nil)

  case token do
    # 1. The Simple Fast Path (HS256, etc)
    <<^exp_header::binary, ?., payload_and_sig::binary>> -> 
      fast_verify(payload_and_sig)

    # 2. The Base64 Magic Fast Path (Poly1305)
    <<@p1305_h, nonce_seg::binary-24, @p1305_kid_seg, ^exp_htail::binary, ?., payload_and_sig::binary>> ->
      fast_p1305_verify(nonce_seg, payload_and_sig)

    # 3. THE SLOW PATH
    _ -> 
      slow_verify(token)
  end
end

By ensuring our JSON keys and values add up to multiples of 3, we can continue to use Elixir's blazing fast binary pattern matching to route tokens, skipping the JSON parser entirely even when parts of the header are highly dynamic.

The Fallback

Of course, the slow path cannot be completely removed. If you rotate your signing keys, users with valid tokens signed by the old key will still need to access your API.

Because their tokens will have a different kid in the header, the fast path pattern match will naturally fail. The case statement falls back to slow_verify, which does the traditional Base64 decoding, JSON parsing, and dynamic key lookup.

The beauty of this architecture is that the fast path handles 99% of your traffic with near-zero overhead, while the slow path gracefully catches edge cases, legacy tokens, and key rotations without the caller ever needing to know the difference. And although we don't parse the headers, we don't assume anything here; because of the binary pattern matching, there's not a single header byte that is not exactly what we expect it to be. JWT-verification speed is improved by about 30% for normal-sized JWTs.

A real-world example (using only OTP!) that supports key rotation and multiple signing algorithms including HMAC-SHA256, EdDSA and Poly1305 can be found in Charon's JWT token factory.

Why We Stopped Using UUIDv4 in Elixir (And What We Built Instead)

Jules Smeets — Fri, 27 Feb 2026 18:14:21 +0000

If you’re building a new Phoenix application today, deciding on a primary key strategy usually takes about three seconds. You don't want to use standard auto-incrementing integers because they leak your business volume (e.g., "Oh, I'm only user #104? This app is a ghost town").

So, you do what everyone does: you reach for Ecto.UUID. It's built-in, it's unpredictable, and it solves the problem.

But as your application scales, UUIDv4 becomes a silent performance killer. After wrestling with database bloat and terrible API developer experience, we decided to build a better way. Enter Once.

Here is why we ditched UUIDs, and how you can get Stripe-style, high-performance IDs in your Elixir app in about two minutes.

The Problem with UUIDv4: Database Fragmentation

PostgreSQL (like most relational databases) uses B-trees for its indexes. B-trees are incredibly fast, but they have a distinct preference: they absolutely love sequential data.

When you insert a sequential ID (like a standard integer or a time-sorted Snowflake ID), Postgres cleanly appends it to the right edge of the index.

UUIDv4, however, is purely random. When you insert a million random UUIDs, Postgres has to constantly search for the correct leaf node to insert the new value. This causes massive "page splits," fragments the index, and destroys your cache locality.

Over time, your index size balloons, your write I/O skyrockets, and your database spends precious memory caching index pages that are mostly empty.

The API UX Problem: "Type Confusion"

Beyond database performance, UUIDs are completely hostile to human developers.

If you are looking at a log file or an API payload and see 9f1c0d3a-2b7e-49a1-8d5c-9123456789ab, what is it? Is it a User ID? A Payment ID? A Subscription ID? If a frontend developer accidentally passes an Organization ID into a User endpoint, the system will just return a generic 404 Not Found, leading to hours of frustrating debugging.

Stripe solved this years ago by prefixing their IDs: cus_... for customers, ch_... for charges. It is self-documenting, type-safe, and universally loved by developers. We wanted that exact experience in Ecto.

Enter `Once`: The Best of Both Worlds

We built Once as a custom Ecto type to solve both the database performance problem and the API usability problem, without compromising on security.

Under the hood, Once is powered by NoNoncense, a distributed, lock-free ID generator that uses Erlang's :atomics to generate tens of millions of 64-bit IDs per second. Because it's 64-bit (instead of UUID's 128-bit), it immediately cuts your ID storage footprint in half.

The "Masking" Magic

You usually have to make a painful choice:

Use sequential integers (Fast database, but leaks business metrics).
Use random strings (Protects metrics, but slow database).

With Once masking, you don't have to choose. You configure your Ecto schema to generate a sequential, counter-based ID. When Ecto saves the record to your database, it stores a raw, 64-bit integer. Your database is perfectly happy, and your B-tree indexes stay perfectly compact.

But when Ecto loads that record back into your Elixir application, Once uses blazing-fast encryption to transparently mask the integer, and prepends your chosen prefix.

As a standard bigint in your database: 98770186085072901
In your Elixir App / JSON API: "usr_4Tnk9-GqJ-s"

Your database gets perfectly optimized sequential writes. Your API consumers get unpredictable, Stripe-style, self-documenting strings.

Fully Composable: Pick What You Need

The best part about Once is that these features are fully composable and optional. You can tailor the ID generation to your exact needs:

Just want unique IDs? Use the defaults. You get 64-bit integers that are incredibly fast to generate and index in your database, and url64-encoded strings like "AV7m9gAAAAU" in Elixir.
Need chronological sorting? Change to nonce_type: :sortable. You get a Snowflake-like ID where the first 42 bits are a timestamp, meaning ORDER BY id works perfectly.
Want masked IDs? Just add mask: true.
Need true unpredictability at rest? If you don't want to use masking and genuinely need UUIDv4-style randomness stored in your database, switch to nonce_type: :encrypted.
Want Prefixes? Just add prefix: "req_" to any of the above.
Want to persist the prefix? Use a binary database format like db_format: :hex and add persist_prefix: true.
Want a different API format like integers? Use ex_format: :unsigned to render IDs like "usr_98770186085072901"

You can combine all of these as you see fit, and automagically generate distributed IDs with just the features that you need and nothing more.

Why not UUIDv7?

While UUIDv7 solves the index fragmentation problem, it's not as flexible as Once:

Storage: UUIDv7 is still a bloated 128-bit identifier. Once cuts that in half (64-bit).
API UX: UUIDv7 still looks like a massive, unreadable string (018e4b...). Once gives you Stripe-style usr_... prefixes.
Business Leakage/Security: UUIDv7 visibly leaks the exact millisecond a record was created. Once uses masking to hide the underlying counter/timestamp entirely.

The 2-Minute Phoenix Quickstart

Here is how easy it is to drop into a Phoenix project.

1. Add the dependencies to mix.exs:

def deps do
  [
    {:once, "~> 1.2"}
  ]
end

2. Initialize the generator in your application.ex:

# Create a unique Machine ID for this node (supports up to 512 nodes in a cluster)
machine_id = NoNoncense.MachineId.id!(node_list: [Node.self()])

# Initialize a NoNoncense instance for Once with a secret key for masking
# (Pull this from your environment in production!)
secret_key = System.get_env("ONCE_SECRET_KEY", "my supersecret dev key")
NoNoncense.init(name: Once, machine_id: machine_id, base_key: secret_key)

Note that NoNoncense is not a GenServer; it keeps its write-once-read-often state in :persistent_term.

3. Define your Ecto Schema:
Just set Once as your primary key, give it a prefix, and turn on masking.

defmodule MyApp.Accounts.User do
  use Ecto.Schema

  @primary_key {:id, Once, autogenerate: true, prefix: "usr_", mask: true}
  schema "users" do
    field :email, :string
    timestamps()
  end
end

That’s it. You now have locally unique (within your app or domain), Stripe-prefixed, cryptographically masked 64-bit IDs that won't destroy your database indexes.

If you’re tired of the UUID performance tax or just want a better developer experience for your API consumers, give Once a try on your next project.

Check out the full documentation and advanced configuration options on HexDocs for Once and NoNoncense.