Repository navigation
Releases
v0.3.7
Go apps can mint relay tokens with massrelay's own signer.
Added
middleware.RelaySigner(issue 78). A Go app mints relay tokens with
Mint(subject, rooms), which writes the claimsRelayAuthenticatorreads,
and gets the matching authenticator fromAuthenticatoror the key store
fromKeyStore. It signs HS256, with a key generated per process unless
one is passed. Nothing changes on the wire.
v0.3.6
Keycloak user tokens now report their client. Nothing changes on the wire, and the Go floor stays at 1.26.9.
Changed
- oneauth v0.3.2 (PR 77). A token without
client_idreports itsazpas the client, which is how Keycloak user tokens name theirs. SoPeerIdentity.client_idis set for those users, and ReAuth's same-client check compares a real value. Before, both were empty for those tokens. Tokens that carryclient_idsee no change.
Upgrading
- mcpkit's Go side pins massrelay exactly. Bumping it to v0.3.6 also brings oneauth v0.3.2 through massrelay's
go.mod.
v0.3.5
v0.3.5
An operator can now revoke a user. Until this release RelayAuthenticator.DenySub
existed but nothing called it, and even if something had, a denied user stayed
in their rooms until their token's exp. Now one admin call ends every
connection the user has open, and a new connection gets a 403 until the
operator allows them again.
Mission 72 closed with this release. Its exercise, make exercise-revoke,
runs in CI against the relay binary and through the make prod-up stack.
Nothing changes on the wire. A v0.3.3 or v0.3.4 client keeps working, and a
denied client sees SessionEnded{denied}, which those clients already treat
as the end of the session.
Added
- Admin deny endpoints (issues 73 and 63, PR 74). Behind
RELAY_ADMIN_TOKEN:POST /admin/subjects/{sub}/denyrevokes a token subject. Each of its
open connections leaves its rooms (peers seePeerLeftwith reason
denied) and getsSessionEnded{denied}. A new upgrade gets 403, and a
ReAuthActionis refused.CollabClientreports
onSessionEnded("denied")and doesn't reconnect. Answers 204.DELETE /admin/subjects/{sub}/denyallows the subject again (204).GET /admin/subjects/deniedlists the deny list.- The deny routes answer 409 when the relay runs without auth. The list is
in memory, so a restarted relay forgets it. Pair revocation with
short-lived tokens.
RelayAuthenticator.OnDeny(fn)andDeniedSubs()(PR 74).DenySub
calls eachOnDenylistener, and the relay registers one that ends the
subject's connections. So an embedder that callsDenySubdirectly gets
the same effect as the admin route.make exercise-revoke(PR 74). A subject with two connections is
denied, then allowed again.make exercise-prodruns it too.
Changed
- oneauth v0.3.1 (issue 37, PR 76).
RelayAuthenticator.ValidateToken
now uses oneauth'sValidateBearer, andRelayClaimscomes from its
TokenInfo,expandiatincluded. That replaces a synthetic request
and a second parse of every token. The Go floor stays at 1.26.9.- A DPoP-bound token sent in a
ReAuthActionis now refused, since a bare
token has no proof to check. massrelay only takes plain bearer tokens,
so no working setup changes.
- A DPoP-bound token sent in a
Upgrading
- mcpkit's Go side pins massrelay exactly. Bumping it to v0.3.5 also bumps
oneauth to v0.3.1 through massrelay'sgo.mod.
v0.3.4
v0.3.4
A client can now stay in its room past its token's expiry. Until this release
the relay ended a connection at the token's exp, and a CollabClient with
getToken rejoined under a new clientId. Every other peer saw it leave and
join again, once per token lifetime. Now the client hands the relay a fresh
token over the open socket before exp, and nobody sees anything.
Two missions closed with this release, each with an exercise in CI:
make exercise-token-refresh (issue 66) and make exercise-prod (issue 68),
which runs all three mission exercises through the make prod-up stack.
Nothing changes for a client that doesn't set getToken, and a v0.3.3 client
keeps working against this relay (see Compatibility).
Changed (behavior)
- A
CollabClientwithgetTokenrefreshes its token in-session (issue
13, PR 67). Against a v0.3.4 relay it no longer drops and rejoins at each
exp. It keeps itsclientId, andonConnect/onDisconnectdon't fire.
Against an older relay it behaves as before. - A failed refresh falls back to a bounded reconnect (PR 67). The client
retries the refresh at half the time left while 2s or more remain. If none
succeeds, the relay ends the connection at the oldexpand the client
reconnects throughgetToken. If the refresh fails again in the next
lifetime, the session ends withonSessionEnded("token_expired"). That
stops a client from dropping and rejoining once per lifetime indefinitely.
Added
ReAuthActionandReAuthResult(issue 13, PR 67). A client sends a
fresh JWT over the open connection. The relay checks it like the upgrade's
token (signature, issuer,exp, the deny list). The token must have the
samesubandclient_id, and itsroomsclaim must allow the
connection's room. On success the connection ends at the newexp. A
refusal leaves the oldexpin place, andReAuthResult.errorsays why.
ReAuth isn't rate limited.RoomJoined.token_expires_atgives the client the firstexp. The
relay sets it only when the connection has a token and the join's
protocol_versionis 3 or higher (PR 71).CollabClientOptions.onTokenRefreshreports each refresh: the new
expiresAt, or why it failed.- Go:
RelayAuthenticator.ValidateToken(ctx, raw)andErrAuthDisabled,
Guard.Authenticator(), andStreamConfig.Auth.api.gowires the Guard's
authenticator into every stream, so an embedder with a hand-builtGuard
(as mcpkit has) gets ReAuth without changes. make exercise-prod(issue 69, PR 70) brings up theprod-upstack
(Caddy with TLS, the relay container, auth from env, the stack's own rate
limits) and runs the auth, reconnect and token-refresh exercises against
wss://localhost. A required CI job runs it. The exercises take an
external relay fromMASSRELAY_RELAY_URL.
Fixed
- A rejoin refused with
ROOM_FORBIDDENstopped silently (PR 67). It
closed the connection without callingonSessionEnded. It now ends with
onSessionEnded("token_refused").
Compatibility
- A v0.3.3 client against this relay keeps working (PR 71). v0.3.3
rejects JSON fields it doesn't know, so the relay sends
token_expires_atonly to a join withprotocol_version3 or higher.
CollabClient0.3.4 sends 3.ts/interop/compat.interop.tsruns the
published v0.3.3 client against the binary in CI. - A v0.3.4 client against an older relay gets no
token_expires_at, so
it never sends aReAuthActionand reconnects atexpas before. An older
relay acceptsprotocol_version3. CollabClientnow ignores event fields it doesn't know, so a later
relay's additions can't stop it handling an event.
Tests
identity.interop.tsflaked about 1 run in 10 on an ordering assertion
across two senders, which the relay never promised. It now waits for the
first message before sending the second (PR 67).
v0.3.3
v0.3.3
Auth works in the relay binary now, and CollabClient reconnects on its own.
Until this release NewRelayApp never built a key store, so a relay started
with RELAY_AUTH_REQUIRED=true quietly accepted every connection, and a client
whose socket dropped just stayed dropped. Connections also end when their
token expires, where before they outlived it indefinitely. Two defaults change
behavior, so read the first section before upgrading: RelayApp.Init now
refuses to start open, and a slow-consumer eviction reconnects instead of
ending the session.
Two missions closed with this release, each with an exercise that runs against
the relay binary in CI: make exercise-auth (issue 53) and
make exercise-reconnect (issue 54).
Changed (behavior)
- The relay refuses to start open (issue 56, PR 58).
RelayApp.Init
returnsErrAuthRequiredNoKeyswhenRELAY_AUTH_REQUIRED=trueand no key
source is set, and an error for an unreadable or malformed keys file or a
JWKS URL it can't fetch at startup. The binary exits on any of these.- Migration: set
RELAY_AUTH_KEYS_FILEorRELAY_AUTH_JWKS_URLalongside
RELAY_AUTH_REQUIRED=true. An embedder that builds its ownGuardand
also setsRELAY_AUTH_REQUIRED=trueneeds a key source too.
- Migration: set
- A slow-consumer eviction reconnects (issue 38, PR 59). Reconnect is on by
default, soonSessionEnded("slow_consumer")no longer fires; the client
rejoins the same session instead.- Migration: pass
reconnect: falseto get the old behavior.
- Migration: pass
Added
- Signing keys from config (issue 56, PR 58).
RELAY_AUTH_KEYS_FILEis a
JSON array of{client_id, alg, key}, andRELAY_AUTH_JWKS_URLfetches
public keys matched bykid. Indeploy/production, keys go in
./secrets, mounted read-only at/etc/massrelay(a directory, since docker
turns a missing single-file mount into an empty directory). CollabClientreconnects (issues 38 and 57, PR 59). After the socket
closes withoutdisconnect(), or an eviction, it backs off, checks
GET /api/v1/rooms/{sessionId}, and rejoins on a 200. A 404 ends with
onSessionEnded("session_gone"), so a relay restart no longer leaves a
phantom room, and running out ofmaxRetriesends with
"reconnect_failed". New options arereconnect(default true),
retryDelayMs,onReconnecting, andgetTokenfor a fresh JWT on every
connection.- Connections end at the token's
exp(issue 60, PR 62). The peer leaves
its room and getsSessionEnded{token_expired}. WithgetTokenset,
CollabClientreconnects on a fresh token; without it, it reports
onSessionEnded("token_expired"). JoinRoom.must_exist(issue 61, PR 62). Joins only a room the relay
already has, answeringErrorEvent{ROOM_NOT_FOUND}otherwise.CollabClient
sets it on every rejoin, which closes the window where a room lost between
the room check and the join came back empty.RelayApp.Close()(PR 62) stops the JWKS background refresh, andmain
calls it on shutdown.- Exercises and interop tests against the binary.
make exercise-auth
(issue 55, PR 58) andmake exercise-reconnect(issue 57, PR 59) run in CI.
New interop tests cover slow-consumer eviction as the TS client sees it
(issue 50, PR 52) and peer identity with keys fromRELAY_AUTH_KEYS_FILE,
including an addressed call and reply the way the mcpkit room bridge makes
them (issue 27, PR 65).
Changed
CollabEnginereportssession_goneandreconnect_failedwith their own
messages instead of "The owner ended the sharing session".- servicekit v0.2.2 (was v0.2.0), and
@panyam/servicekit-client^0.2.2 in
development. Neither release changed an API massrelay uses.
Fixed
RelayClaims.ExpiresAtandIssuedAtwere always zero, because oneauth's
custom claims leave outexpandiat. The middleware now reads them from
the verified token (PR 62). Issue 63 tracks a oneauth accessor for this.deploy/production/docker-compose.ymlpassesRELAY_AUTH_REQUIREDand
RELAY_AUTH_ISSUERto the relay container. Before, both were set in.env
and never reached it.
Known limits
- A token can't be refreshed inside a live session; the client reconnects with
a new one instead (issue 13). DenySubdoesn't end streams already open for that subject (issue 63).
v0.3.2
Moves to servicekit v0.2.0 and accepts servicekit-client 0.2.x as a peer. No
API changes in the Go module or the TS package.
Changed
- servicekit v0.2.0 (was v0.1.12), and
@panyam/servicekit-client^0.2.0 in
development. The peer range widens to^0.0.7 || ^0.1.9 || ^0.2.0, so an
app on servicekit-client 0.2.x no longer gets a peer warning. massrelay used
none of the APIs v0.2.0 renamed or moved, so nothing else changes, and the
v0.3.1
A browser page can see which peers the relay validated a token for, and the
relay now closes an evicted slow consumer's socket instead of leaving it to
the pong timeout. No breaking changes.
Added
CollabClientpassesPeerInfo.identitytoonPeerJoined, for peers
already in the room and for ones that join later (issue 42, PR 48). Before, it
copied every other field and dropped this one, so a browser page couldn't
tell which peers the relay had validated a token for.CollabClient.getPeer(clientId)returns a peer in the room, identity
included, so anonAppMessagehandler can check
getPeer(fromClientId)?.identity?.subjectbefore acting. It is cleared on
peerLeftand when the connection closes.
Changed
- servicekit v0.1.12 (was v0.1.11), and
@panyam/servicekit-client^0.1.12
in development; the peer range is unchanged. Besides the options below,
v0.1.12 ends a server connection as soon as the client closes cleanly
(before, it lingered until the pong timeout) and fixes a browser bundle of
servicekit-client that imported nothing (PR 49).
Fixed
- An evicted slow consumer's socket is closed by the relay (issue 46, PR 49). Its
stream ends afterSessionEnded{slow_consumer}, and the WebSocket handler
now sets servicekit'sCloseOnStreamEnd, so the client gets a 1000 close
within the 2s grace period. Before, a client that wasn't reading held its
socket, and one of theRELAY_MAX_CONNECTIONSslots, for up to the 5 min
pong timeout. - Writes to a client time out after 10s (
StreamConfig.WriteTimeout), which
closes the connection. A client that stopped reading entirely used to block
its writer, and with it the eviction that should have removed it. - An evicted client gets the events it already had queued before
SessionEnded. Depending on goroutine scheduling, the relay could evict it
with none of them sent, which also madeTestStreamEvictsSlowConsumerfail
about half the time on a single CPU (and on CI).
v0.3.0
v0.3.0
This release lets one AppMessage go to several peers, and stops the relay
from dropping messages without telling anyone. It's a minor bump because the
AppMessage wire format changes: to_client_id becomes to_client_ids on
the same field number, and nothing out there was sending the old field yet.
It also raises how many connections one IP can open at once, which was
quietly refusing the fourth tab of a browser restoring a session.
Breaking
AppMessage.to_client_ids(issue 43, PR 44). The string
to_client_id = 3is nowrepeated string to_client_ids = 3. Each listed
peer gets the message once, withto_client_idsrewritten to hold only its
own id, so a receiver still tells addressed from room-wide and doesn't learn
who else was addressed. Ids not in the room come back to the sender as one
ErrorEvent{PEER_NOT_FOUND}naming them all, and the rest are still
delivered. Before, one absent target meant nothing was delivered.
Empty still fans out to the whole room.- Migration (TS):
sendAppMessage(kind, payload, { to })takes a string or
an array, so existing calls keep working.onAppMessage'stoClientId
argument is unchanged (this client's id, or empty). - Migration (Go):
DeliverAppMessagetakes the new message shape, and its
error wrapsErrPeerNotFoundwith the missing ids.CollabRoom.SendTois
gone; useSendEach.
- Migration (TS):
- Slow consumers are evicted (PR 44). A peer whose 64-event queue fills is
removed from the room and sentSessionEnded{reason: "slow_consumer"}, and
the others seePeerLeftwith that reason. Before, the relay dropped events
to it and kept delivering later ones, so it saw gaps. Now every receiver gets
an unbroken, in-order prefix of each sender's messages, which is what lets a
batch A1..A5 reliably land before B1..B5 at every peer.
Added
RELAY_PER_IP_BURST(issue 45, PR 47). How many connections one IP may
open at once. It defaults to max(3,RELAY_PER_IP_RATE), so production goes
from 3 to 5 and raising the rate raises the burst with it.CollabClient
doesn't retry a refused upgrade, so a fourth concurrent tab used to just fail
with a 429.
Changed
- Over-rate messages get
ErrorEvent{RATE_LIMITED}(PR 44), naming the
droppedactionId, instead of vanishing. - README's Rate Limiting section now lists the real env vars instead of a
RateLimitConfigsnippet that didn't match any API.
Known limits
- An evicted slow consumer's WebSocket stays open until the client closes it,
since servicekit has no way for a stream to close its own socket yet
(issue 46).
v0.2.5
Moves to servicekit v0.1.11. No API changes in the Go module or the TS package.
Changed
- servicekit v0.1.11 (was v0.1.9), and
@panyam/servicekit-client^0.1.11 in
development; the peer range is unchanged. v0.1.10 fixes a data race on
every grpcws WebSocket close by makingStreamMetrics.MsgsSent/MsgsReceived
andBaseConn.PingIdatomic.Int64. massrelay doesn't read them, so nothing
here changes. v0.1.11 raises servicekit's grpc, gorilla/websocket and x/net
minimums for Dependabot alerts; massrelay already required newer versions
(PR 40, PR 41).
v0.2.4
CollabClient stays in the room after a refused message, and the package is
the first massrelay release published from CI.
Fixed
CollabClientno longer closes the connection on a relay error that follows
the join.PEER_NOT_FOUND(replying to a peer that already left) and
ALREADY_JOINEDrefuse one action and the relay keeps the stream open, so the
client now reports them throughonErrorEventand stays in the room. Errors
that refuse the join (ROOM_FULL,ROOM_FORBIDDEN,
PROTOCOL_VERSION_TOO_OLD) still close it.CollabEnginefollows the same
split and staysconnected(issue 33).onDisconnectfires once for every connection that reachedonConnect,
including when the owner ends the session (it runs beforeonSessionEnded).
Before, a close the relay caused skipped it.
Changed
- servicekit v0.1.9 (was v0.1.7), and
@panyam/servicekit-client^0.1.9 in
development. servicekit-client now shares servicekit's version, so it jumped
from 0.0.7 to 0.1.x; the peer range is^0.0.7 || ^0.1.9, since^0.0.7
alone allows only 0.0.7 and npm refuses the install next to 0.1.9. check:packreads npm 12'snpm pack --jsonoutput (an object keyed by
package name) as well as npm 10/11's array.- npm publishing goes through servicekit's shared
npm-publish.ymlwith npm
trusted publishing, so release tags publish@panyam/massrelaywithout an
NPM_TOKENsecret. scripts/check-versions.shfails CI whents/package.jsondrifts from
CAPABILITIES.md's version, and a publish when the tag does.ts/package.jsongainsdescriptionandrepository, which npm provenance
checks against the publishing repo.