Dive C4.07.3

Branded ids

Three letters tell a service what an id names. A total check tells a key builder whether to trust it.

A branded id is two parts glued together: a three-letter uppercase namespace and the eleven-character Base62 Snowflake — fourteen bytes. The integer stays canonical; the string is transport. EchoMQ's jobs are minted under the JOB namespace, and the keyspace will not build a key from an id until that id passes isValid — a total predicate: fourteen characters, the first three uppercase, the last eleven in the Base62 alphabet. A bare "JOB" has a valid namespace but is not a valid id. This dive quotes echo_fs/EchoMQ/BrandedId.fs and Keyspace.fs verbatim; every value was produced by dotnet fsi.

Run the validity gate Module hub

C4.07.3 · part 1

Mint, namespace, and the integer behind it

mint concatenates the namespace with the Base62 payload; namespaceOf reads the first three characters back; snowflakeOf recovers the canonical integer by decoding the rest. The module is quoted verbatim from echo_fs/EchoMQ/BrandedId.fs.

module BrandedId =
    /// The namespace EchoMQ jobs are minted under.
    [<Literal>]
    let Job = "JOB"

    let private isUpper (c: char) = c >= 'A' && c <= 'Z'
    let private isBase62 (c: char) = Base62.Alphabet.IndexOf(c) >= 0

    /// 3 uppercase letters then 11 Base62 chars. A bare "JOB" is NOT a valid id.
    let isValid (id: string) : bool =
        not (isNull id)
        && id.Length = 14
        && Seq.forall isUpper (id.Substring(0, 3))
        && Seq.forall isBase62 (id.Substring(3))

    /// The 3-letter namespace ("JOB", "USR", ...).
    let namespaceOf (id: string) : string = id.Substring(0, 3)

    /// The canonical integer snowflake behind the transport string.
    let snowflakeOf (id: string) : int64 = Base62.decode (id.Substring(3))

    /// Compose a branded id from a namespace and a snowflake integer.
    let mint (ns: string) (snowflake: int64) : string = ns + Base62.encode snowflake

let branded = BrandedId.mint BrandedId.Job 55264149504028672L
// val branded : string = "JOB0456qLH4via"
BrandedId.namespaceOf branded   // val it : string = "JOB"
BrandedId.snowflakeOf branded   // val it : int64 = 55264149504028672L

Job = "JOB": the namespace EchoMQ mints jobs under. Other kinds would take their own three letters ("USR", …).
mint: namespace + Base62.encode of the integer — a 3-char prefix on an 11-char payload, fourteen characters.
namespaceOf / snowflakeOf: the two readers: the first decodes nothing (route on three characters); the second decodes the payload back to the canonical int64.

C4.07.3 · part 2

isValid — a total predicate

isValid answers a single yes/no for every string: not null, exactly fourteen characters, the first three uppercase, the last eleven in the Base62 alphabet. It is total — it returns a bool for any input, never throwing — which is what makes it safe to call as a precondition. A bare "JOB" fails on length; a lowercase namespace fails the uppercase check.

// isValid is total: a bool for any input (FSI)
BrandedId.isValid "JOB0456qLH4via"   // val it : bool = true
BrandedId.isValid "JOB"             // val it : bool = false  (length 3, not 14)
BrandedId.isValid "job0456qLH4via"   // val it : bool = false  (namespace not uppercase)
BrandedId.isValid "JOB0456"          // val it : bool = false  (length 7)

A namespace check alone is not a validity check. "JOB" begins with the right three letters, yet it is not an id — it has no payload. The length-and-shape predicate is what catches that, which is why the key builder calls isValid and not namespaceOf.

Build a key — or get refused

Pick a candidate string. The readout runs BrandedId.isValid on it and then Keyspace.jobKey "orders" — which builds emq:{orders}:job:<id> for a valid id and raises ArgumentException for anything else. The check runs in this page's JavaScript with the same rule (length 14, first three A–Z, last eleven in the Base62 alphabet). Each outcome below was confirmed in dotnet fsi.

isValid → jobKey · select a candidate

isValid "JOB0456qLH4via" = true · jobKey "orders" builds emq:{orders}:job:JOB0456qLH4via

The id is checked once, at the door. After that, every key built from it is well-formed by construction — an ill-formed id never reaches the keyspace.

C4.07.3 · part 3

The keyspace gate

jobKey composes the queue's job: family with a branded id — but only after isValid passes. On a bad id it raises rather than returning a malformed key. The function is quoted verbatim from echo_fs/EchoMQ/Keyspace.fs.

/// A per-queue key: emq:{q}:<type>.
let queueKey (queue: string) (keyType: string) : string =
    "emq:{" + queue + "}:" + keyType

/// A job key: the queue's job: family plus a valid branded id. Raises on an
/// ill-formed id — the INV5 gate the Elixir builder enforces.
let jobKey (queue: string) (branded: string) : string =
    if BrandedId.isValid branded then
        queueKey queue "job:" + branded
    else
        invalidArg (nameof branded) "jobKey requires a valid branded id"

// the gate in action (FSI)
Keyspace.jobKey "orders" "JOB0456qLH4via"
// val it : string = "emq:{orders}:job:JOB0456qLH4via"

Keyspace.jobKey "orders" "JOB"
// System.ArgumentException: jobKey requires a valid branded id

The brand gives

A 14-byte, self-describing id and a total isValid the key builder leans on.

What it unlocks

Every job key (emq:{q}:job:<id>) is well-formed by construction — the next module, persistence, builds on exactly this.

EchoMQ in F#

EchoMQ mints a job with BrandedId.mint BrandedId.Job and refuses to build a key from anything that fails isValid — so a malformed id is rejected at the door rather than poisoning a key. A service routes on the JOB prefix; the keyspace trusts the integer behind it.

The F# EchoMQ mints and validates these ids today — BrandedId is built and tested (BrandedIdTests covers mint, isValid, namespaceOf, and snowflakeOf). The Valkey transport EchoMQ.Connector lands next.

The same brand, in two languages

The Elixir course brands a Snowflake the same way — a namespace prefix on a base62 payload. F#'s shift is the total isValid the compiler can reason about, and the int64 the integer stays. isValid is O(14): two Substring allocations and two bounded Seq.forall scans. The branded string is one System.String; the canonical integer is recovered by snowflakeOf only when it is actually needed.

Elixir — brand a Snowflake (the E4.07 idiom)

# Elixir — namespace tag on a base62 payload
branded = "JOB" <> EchoData.Base62.encode(snowflake)
# the namespace is read back by slicing the first three bytes
ns = String.slice(branded, 0, 3)   # "JOB"

F# — brand and validate (verified in FSI)

// F# — echo_fs/EchoMQ/BrandedId.fs
let branded = BrandedId.mint BrandedId.Job 55264149504028672L
// val branded : string = "JOB0456qLH4via"
BrandedId.isValid branded   // val it : bool = true

↑ C4.07 · Identifiers C4.07.1 · The Snowflake ← C4.07.2 · Base62

Status — echo_fs is an in-memory model. The EchoMQ protocol — the Lua transitions executing on a Valkey wire — is not implemented (there is no Lua and no Valkey client in the code); that is the coming-soon transport (EchoMQ.Connector). This block shows how the model uses the structure, not a running bus.

References

Sources

Microsoft — F# documentation — strings, Substring, and the Seq module.
FSharp.Core API reference — Seq.forall and isNull.
Microsoft — .NET documentation — String.IndexOf and ArgumentException.
The F# Software Foundation — F# on the .NET runtime.

Related in this course

Elixir — Branded ids — the namespace + base62 brand on the BEAM.
C4.07.1 — The Snowflake — the integer behind the brand.
C4.07.2 — Base62 — the payload encoding.
C4.07 — Identifiers — the module hub.