DEV Community

Zero Heartbeat
Zero Heartbeat

Posted on Originally published at delta1labs.com

Migrating per-machine keys to floating licensing

A floating license pool looks like a server setting: "allow 25 concurrent users instead of 25 named machines." It is not. The machine-count model and the concurrent-seat model are two different conversations between the client and the service, and the clients that are already installed only know how to have one of them. Flip the server before the field is ready and you get the worst licensing bug there is — one where paying customers are locked out and the dashboard still says everything is fine.

Key takeaway: Treat the move from node-locked to floating as a rolling protocol migration. Put a per-key seat.model claim in the license, ship a dual-mode SDK that reads it, let that SDK reach the field first, and only then start minting floating keys. The server reconciles each machine's old activation into the new pool atomically, so the shared ceiling holds throughout.

The real question: who decides the model, and when?

Under node-locking, a client binds a lease to a stable machine fingerprint and validates it locally; the service tracks one activation per machine and caps the count. Under floating, the client owns nothing permanent — it calls ClaimSeatAsync on start, renews a short lease on a heartbeat, and the seat returns to the pool when the client exits or stops renewing.

Those are incompatible defaults. A node-locked client never asks for a seat; a floating client never expects a permanent binding. So the decision cannot be a global server flag read at validation time — it has to travel inside each license, where both the server and the client can read it before choosing a path.

{
  "lic": "KR-7F3A-...",
  "product": "acme-suite",
  "seat": { "model": "floating", "max": 25, "leaseTtl": "00:05:00" },
  "exp": "2027-03-01T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

The seat claim is signed as part of the license payload, so a client cannot forge its way from node-locked to floating, and the model is a fact about the key rather than about the server's current mood. Old keys keep "model": "node-locked"; renewed and new keys get "model": "floating".

Step 1 — ship an SDK that speaks both

The first deliverable is a client that reads the claim and dispatches. This is the piece that must reach the field before any key changes, because it is the only version that will not break when it meets a floating key.

public async Task<SeatResult> AcquireAsync(CancellationToken ct = default)
{
    LicenseClaims claims = _verifier.Verify(_storedKey);   // Ed25519 check, fully local
    if (!claims.IsValid)
        return SeatResult.Invalid;

    return claims.Seat.Model switch
    {
        SeatModel.NodeLocked => BindToMachine(claims),              // legacy path, untouched
        SeatModel.Floating   => await ClaimFloatingSeatAsync(claims, ct),
        _                    => SeatResult.Invalid,                 // unknown model: fail closed
    };
}
Enter fullscreen mode Exit fullscreen mode

The node-locked branch is the code you already ship, unchanged. The floating branch claims a seat and then holds it by renewing at half the lease TTL, so a dropped heartbeat still has one more attempt before the seat is reaped.

async Task<SeatResult> ClaimFloatingSeatAsync(LicenseClaims claims, CancellationToken ct)
{
    SeatGrant seat = await _service.ClaimSeatAsync(claims.LicenseId, _fingerprint, ct);
    if (seat.Status == SeatStatus.PoolExhausted)
        return SeatResult.Denied("all seats in use");

    var half = claims.Seat.LeaseTtl / 2;
    _heartbeat = new Timer(_ => _ = _service.RenewSeatAsync(seat.Token, ct), null, half, half);
    return SeatResult.Granted(seat.Token, seat.ExpiresAtUtc);
}
Enter fullscreen mode Exit fullscreen mode

Crucially, this SDK is correct against both key types. A customer who upgrades today keeps working on their node-locked key with zero behaviour change. That is what makes the rollout safe: the SDK migration and the key migration are decoupled.

Step 2 — reconcile each machine as it crosses over

Here is where a naive cutover double-counts. A machine that already holds a node-locked activation and then claims its first floating seat would occupy two units of capacity — one legacy activation the pool cannot see, plus one live seat. Across a fleet, that silently oversells the ceiling and starts denying legitimate seats.

The fix lives on the server and must be atomic. On the first floating claim from a fingerprint that still has a node-locked activation on the same license, Keyright retires the activation and issues the seat in one transaction.

One ceiling across the whole migration. Each machine moves from a node-locked unit to a floating seat atomically, so node-locked + floating never exceeds the cap.

The admin-side operation is a single idempotent call, so a retried claim after a network blip does not convert twice:

# Server reconciles on first floating claim; the SDK triggers it transparently.
# To audit a license mid-migration, read its occupancy:
keyright seats show --license KR-7F3A-... --breakdown-by-model
#   model=node-locked  held=10
#   model=floating     active=15
#   ceiling=25  overcommit=0
Enter fullscreen mode Exit fullscreen mode

As long as overcommit stays at zero, the ceiling is intact and you can keep converting at whatever pace the field upgrades.

Step 3 — flip keys on renewal, not all at once

You do not have to migrate everyone on a date. Because the model is per key, the cleanest cutover rides the renewal cycle: when a node-locked key renews, mint the replacement as floating. Fleets that have fully adopted the dual-mode SDK can be flipped in bulk; everyone else converts naturally as their term rolls over.

keyright license reissue --license KR-7F3A-... \
    --seat-model floating --seat-max 25 --lease-ttl 00:05:00
Enter fullscreen mode Exit fullscreen mode

The client picks up the new model on its next license refresh and calls AcquireAsync down the floating branch — no reinstall, no re-entry of a key, no support ticket.

Caveats: where this bites

Order is non-negotiable. If a floating key reaches a machine still running the old single-model SDK, that client hits an unknown model and — if it was not written to fail closed on the node-locked path — can misbehave. Ship and confirm SDK adoption telemetry before you reissue a single key. The seat claim lets both models coexist precisely so you can wait.

A crash holds a seat until the lease lapses. Floating capacity is only reclaimed when the lease TTL expires without a heartbeat; see license heartbeat and lease reaping for sizing the TTL against your real exit behaviour. Set it too long and a laptop that sleeps mid-session ties up a seat; too short and a slow network drops a live user.

Offline installs do not belong in a pool. Floating needs the heartbeat round-trip. Keep genuinely air-gapped machines node-locked with a bounded offline grace, and let the seat.model claim carry that distinction per customer rather than forcing one model on the whole base.

Reconciliation must be atomic or you oversell. The retire-and-grant has to be one transaction keyed by an idempotency token. Do it in two steps and a retried claim converts the same machine twice, quietly eating a seat from the ceiling.

Takeaway

Moving from node-locked to floating is a migration, not a flag. Put the model in a signed per-key seat claim, ship a dual-mode SDK that dispatches on it and reaches the field first, reconcile each machine's old activation into the pool atomically, and flip keys on renewal. Done in that order, the shared ceiling holds every step of the way and no customer ever notices the model changed underneath them. Keyright's Community Edition runs the node-locked path for free; floating pools and model reconciliation are part of the paid tiers. The full migration recipe lives in the Keyright docs.

Top comments (0)