Routing
Content-based routing lets the sender describe a message without naming every program that should receive it. Each listener registers a path describing the fields it is interested in, and mesgd compares incoming messages with those paths. Several listeners can match the same message, which allows a new consumer to participate without changing the sender.
A path consists of segments separated by /. For an object, key=value selects a particular field value, while key=* requires the field to be present with any value. A segment containing only a key is shorthand for key=*. A segment containing only * matches the remaining path.
Build a pattern from a message
The message-access form can compile a pattern from a sample JSON object or array. Choose exact for a field whose value identifies the messages you want, any when the field must exist but its value may vary, or omit when the field should have no effect on selection. Object keys are sorted lexicographically, so the compiled path is consistent regardless of their order in the sample.
Array positions support exact or omit. A compiled pattern must contain at least one segment and can name at most 16 fields. Segment values cannot contain /, =, or *; nested values can be omitted or required to exist. Numeric object keys are reserved for positional patterns.
For {"kind":"chat","room":"lobby","text":"hello"} with kind and room exact and text omitted, the pattern is /kind=chat/room=lobby. Room as any value is /kind=chat/room=*.
When you ask mesgd to suggest a pattern, a field mode of *, wildcard, or all means any. A field key of * or wildcard, or a suggestion that marks every known field omit, matches any value on each field that allows it. omit on one field drops that field.
A granted pattern covers a narrower path. /room=lobby allows /room=lobby/from=ann. It does not allow /room=*.
Choose a credential
| You are trying to | Use |
|---|---|
Call /auth or /account, or open a WebSocket that mesgd will scan against every listener | A login session from POST /auth/login, confirm, or OAuth complete. It is a compact HS256 JWT. It lasts 24 hours unless session_ttl sets another lifetime, and it carries no path list and no administrator role |
| Connect a program that should only reach paths you have assigned | A grant token from POST /auth/admin/issue. It lasts one hour. mesgd keeps a pattern only when it is in the token and still assigned. It cannot call /auth |
| Try a specific set of claims against a path | mesgd forge, then mesgd check PATH TOKEN, which prints ok or fail. Forging a token does not save a permission |
mesgd forge sub alice room lobby is a claim token for those pairs. Message access is how you store several patterns on one user and issue a grant token. See Grants.
A grant token and a forged claim token share a wire format: encrypted claims, a dot, and a PKI signature. A login session is the only compact HS256 JWT. SDK message signatures are a third format, JSON {"r","s"} with base64url fields. mesgd's PKI signatures are not that encoding. Message encryption already matches across mesgd and the SDK (RSA-OAEP, SHA-256, MGF1-SHA-256). Do not verify a forged claim token with an SDK verify that expects {"r","s"}.
From the node shell, mesgd_auth:anonymous/1 can mint a one-hour token for at most eight path prefixes. There is no HTTP route for that call. It is not a login and it is not a grant. / and a pattern that is only stars are refused.
Connection and delivery checks
mesgd admits the upgrade with the credential you sent. A missing credential is 401 unless {disable_auth, true} is set or the path is in public_paths. A login session is accepted. A grant token is accepted when that path is still covered by an assigned pattern. A claim token is accepted when its pairs match that path. The frame format is in WebSocket.
After the upgrade, a connection that is not a grant is registered on its URL path. Each JSON message is scanned against every listener registered with mesgd.
A grant connection is filtered before that scan. mesgd considers every listener path, then keeps a listener only when one of the token's patterns covers that path and the pattern is still assigned to the user. Removing a permission, role, or assignment takes effect on the next check. Adding one requires a new token. A disabled or deleted account, or an expired token, matches nothing. /auth is never permitted for a grant token.