Files
OwnCord/Server/ws/voice_moderation.go
T
J3vbandClaude Opus 5 39551de4a6 refactor(server): work off the complexity backlog — 62 findings to 0 (#1389)
* refactor(ws): split handleVoiceJoin into cohesive join-stage helpers

handleVoiceJoin was 130 statements / cyclomatic 59 / nestif 11, breaking all
three complexity budgets at once. Split along the stage boundaries the doc
comment already described: precheck, leave-current, persist, restore
moderator flags, grant token, complete. The publish-permission derivation
becomes its own helper because it is the one branch-heavy block inside the
token grant.

Pure move: every statement is preserved verbatim. The only edits are bare
`return`s becoming the typed returns of their new helper, `c.userID` becoming
the `userID` parameter inside voiceJoinPublishPerms, and voiceJoinComplete
re-reading `ch.VoiceMaxUsers` instead of receiving it — `ch` is never mutated,
so the value is identical.

Verified by normalising both revisions of the region to sorted, comment- and
whitespace-stripped statements and diffing: the only deltas are the ones
listed above.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor: collapse the three duplicated sibling pairs

dupl flagged three pairs of adjacent near-identical functions. Each pair is
now one parameterised implementation plus two thin, still-greppable wrappers.

- ws/voice_controls.go: handleVoiceMuteV2 / handleVoiceDeafenV2 share
  voiceSelfToggleV2; handleVoiceCameraV2 / handleVoiceScreenshareV2 share
  voiceStreamToggleV2. Camera and screenshare drawing from one
  voice_max_video budget (OC-0023) was a bug caused by exactly this
  duplication drifting, so one body is the point, not a side effect.
- db/mention_queries.go: ListMentionTargetsByRoles / ListMentionTargetsByUserIDs
  share listMentionTargets. The matched column is a closed named type
  (mentionTargetColumn) rather than a bare string, so the value interpolated
  into the SELECT cannot become caller-supplied.

Behaviour is unchanged: every rate-limit key, error code, error string, slog
message and slog key is preserved verbatim, including the two "failed to
update <kind> state" messages, which are now assembled the same way
enableVideoSlot already assembled them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(api): extract readEmojiUpload from handleCreateEmoji

handleCreateEmoji was 101 lines against a 100-line budget. The upload-bytes
stage — pull the file out of the parsed form, cap its size, sniff its MIME
type and sniff its dimensions — is the one self-contained block in it, and it
already wrote its own refusals, so it moves out whole as readEmojiUpload.

The permission-before-parse ordering the doc comment calls out is unchanged;
so is every error string. file.Close() now runs when the helper returns
rather than when the handler does, which is strictly earlier and unobservable:
the bytes are already copied into raw and nothing else touches the handle.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor: extract one cohesive block from three single-budget offenders

Each of these was over exactly one budget, so each gets exactly one extraction
rather than a restructure:

- api/totp_handler.go handleVerifyTOTP (102 lines / 100): the block that
  resolves the user behind the partial-auth challenge and decrypts their TOTP
  secret becomes totpChallengeSecret. The ban-inside-the-partial-window check
  moves with it.
- service/message_reactions.go handleReaction (cyclop 21 / 20): the whole
  authorisation chain — channel lookup, archived gate, DM participant and
  block checks, non-DM permission check — becomes reactionAudience, which
  also returns the DM fan-out audience it already resolved. Check order is
  unchanged and load-bearing.
- db/admin_queries.go BackupToSafe (cyclop 21 / 20): the character allowlist
  loop and the SQL-comment rejection become validateBackupPathChars. That
  loop alone was most of the branch count.

No error string, no check and no ordering changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(plugin): split InstallFromZip into staged install helpers

104 statements / cyclomatic 44 / nestif 12. Split along the stages the code
already had: installZipExtract (the per-entry write loop, with
installZipEntryDest holding the mode/symlink/zip-slip guard chain and
installZipWriteEntry the size-capped copy), installZipStagedManifest,
installZipPromote, and installZipReactivate for the :399 nested block.

Every zip-slip, symlink, entry-mode and uncompressed-size check is preserved
in the same order relative to the writes it guards. The 19 inline
`cleanup(); return` sites collapse to 4 in the orchestrator, one per stage,
because each helper now returns an error instead of unwinding itself — the
staging directory is still removed on exactly the same set of failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(api): split newWAFMiddleware into engine build and per-phase helpers

184 lines / cyclomatic 38, and the request-body block at :382 was the worst
nested site in the tree at nestif 17.

Engine construction moves out of the closure (wafInlineEngine, wafCRSEngine —
the Coraza directive string is lifted verbatim), and each request phase
becomes its own helper: wafInlineRequestHeaders, wafCRSRequestHeaders
(including the Host/Transfer-Encoding re-add for CRS 920280), wafFeedCRSBody
and wafInspectRequestBody, which is the old :382 block.

The three `handleWAFInterruption(w, it); return` sites inside the body block
become one: the helper now returns the interruption and the orchestrator
handles it. No statement runs between the two points on either side, so the
verdict is honoured identically — in particular a CRS body interruption still
returns without replacing r.Body.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(service): split SendMessage and lift EditMessage's access check

SendMessage was 79 statements / cyclomatic 35 with an 11-deep nested
attachment block at :101; EditMessage was one point over cyclop.

SendMessage becomes sendMessagePrecheck (permission and DM-block gates,
content sanitisation), sendMessageLinkAttachments (the :101 block: attachment
ownership, claim and link) and sendMessageDMSideEffects. EditMessage gets
editMessageCheckAccess and nothing else — one budget over earns one
extraction.

The sanitizeContent fixpoint and the attachment ownership check are unchanged,
as is the order of every gate. The DM side effects run behind
`isDM && !s.sendMessageDMSideEffects(...)`, so a non-DM never enters them;
inside, only the GetDMParticipantIDs failure returns false, matching the one
error the original early-returned on.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(admin): split handlePatchUser into per-field apply helpers

106 lines / cyclomatic 29, with the ban block at :154 nested 9 deep.

Each optional field of the partial edit becomes its own helper —
patchUserPrecheck, patchUserAuthorizeRole, patchUserApplyBan (the :154 block,
including the session disconnect and the broadcast) and patchUserApplyRole.
Each returns a bool meaning "keep going"; none of them writes a success
response, so the single response site in the orchestrator is unchanged.

Field application order, the permission-cache invalidation on a role change
and the disconnect-and-broadcast on a ban are all preserved, as are the three
fail-closed `mod == nil` guards, which now sit at the top of their own helper
and still fire on exactly the same conditions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(admin): split handleSetup into first-run setup stages

143 lines / cyclomatic 30, with the optional-wizard block at :219 sitting
exactly on the nestif threshold.

Split into the stages the endpoint already had: request gating (rate limit and
origin check, which run before any auth exists on a fresh server), owner
account creation, and the wizard application that was the :219 block.

Every gate in front of the handler is a security control on an unauthenticated
endpoint; none moved relative to the work it protects. setup_wizard.go is
untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor: split run() into named bootstrap and shutdown steps

131 statements / cyclomatic 57, with the executable-path fallback at :126
nested 9 deep.

The five anonymous `defer func(){...}()` blocks become named functions —
telemetryStop, runClosePlugins, runStopEventPersistence, runStopAuditWriter,
maintenanceStop — and the bootstrap stages move out likewise.

Every defer is still registered in run() itself, at the same point in the
sequence, so the LIFO teardown order is unchanged; that order is documented
in the surrounding comments and is load-bearing (the audit-writer stop must
follow database.Close's registration, the event-persistence stop must precede
it). runStopEventPersistence is now registered unconditionally with a nil
persister meaning "disabled", where the old code registered its defer inside
the enabled branch — a no-op occupying that slot cannot change the relative
order of the others.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(ws): split handleReconnect into resume stages

77 statements / cyclomatic 41, plus the replay block at :199 and, in
handleFreshConnect, the voice-state restore at :622.

handleReconnect becomes reconnectPrecheck, reconnectSelectReplay (with
reconnectVetColdTail for the cold-tier gap check), reconnectRegister and
reconnectWriteReplay. handleFreshConnect's stale-voice cleanup moves to its
own helper, where the `if h.livekit != nil` wrapper becomes a guard clause —
that block was the tail of its scope, so returning early and falling off the
end are the same.

The parts that carry the invariants are moved verbatim: reconnectRegister
still takes h.seqMu, still calls registerNow inside that same critical
section (BUG-123 / OC-0206), still unlocks on every exit, and still emits the
"full" tier counter and telemetry on each of its three re-check failures.
handleReconnect's two-boolean contract is unchanged — the collapsed
`return false, false` sites are all fall-through-to-full-ready, and the
single `return true, false` is still the handshake-write-failure path whose
teardown already ran (OC-0051).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(server): fold in the adversarial review of the complexity refactors

Eleven skeptic passes over the refactor commits on this branch found no
blocker and no major — behaviour is preserved throughout. They did find
comment and accuracy defects worth correcting:

- db/mention_queries.go: the mentionTargetColumn rationale claimed the named
  type made the interpolated column "only ever one of the two constants". A
  Go named type is not closed, so that is a convention the type makes visible,
  not one it enforces. Reworded, gosec justification included.
- ws/voice_controls.go: the dupl collapse generalised away three specifics —
  that a server deafen is the moderator's to lift (now on the serverDeafen
  field), the concrete voice_states.camera / voice_states.screenshare column
  names, and the half of the OC-0023 rationale about neither stream kind
  hiding from the other's count. All three restored.
- ws/voice_join.go: `maxUsers := ch.VoiceMaxUsers` had been hoisted to the top
  of voiceJoinComplete, moving a read across the tail supersession guard. The
  read is inert, but it was the one statement in that commit whose position
  relative to a security guard changed; it now sits at its use, as before.
- ws/*_test.go: three test comments cited voice_join.go line numbers that the
  split invalidated. They now cite the helper by name instead.
- service/message_reactions.go: reactionAudience's doc claimed to enforce
  "every gate on reacting"; it enforces the channel-scoped ones, and the doc
  now says which gates stay with the caller.
- api/emoji_handler.go: the readEmojiUpload call reused the outer `ok` from
  the auth check by assignment; it gets its own readOK.
- admin/setup_handler.go: a moved comment kept a "the response above" deictic
  that no longer had a response above it.

No behaviour change. Build, vet, full tests and -race on five packages green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(ws): clear the remaining complexity budgets across the hub

Eight files, thirteen findings. Each function is split at the stages it
already had; no branch is reordered, merged or inverted.

- handlers.go handleMessage (cyclop 28, 88 stmts): session re-check, frame
  decode and result application become handleMessageSessionRecheck,
  handleMessageDecode and handleMessageApply. The V2 constructor lookup ->
  DispatchV2 -> Result resolution order is untouched.
- serve_ready.go buildReady (cyclop 26, 61 stmts): the per-section fetches
  split out, readyChannelPayloads among them. Every visibility predicate is
  preserved verbatim — this is the payload that decides what a client may see.
- serve_pumps.go writePump (cyclop 31): writePumpWrite, writePumpDeliver,
  writePumpDrainChannel and writePumpDrainAndClose. Every channel receive
  stays in the same select statement, so scheduling is unchanged.
- hub_sweep.go sweepStaleVoiceStates (cyclop 22, 56 stmts): the staleness
  predicate, the hub-lock ordering and the position of the race hook are all
  as they were — handleVoiceJoin's BUG-088 ordering depends on them.
- hub_broadcast.go channelReadAudienceImpl and RefreshChannelVisibility
  (cyclop 22 each, 57 stmts): channelReadAudienceDM and
  refreshChannelVisibilityCanSend. The audience predicate is the OC-0090
  group-DM leak surface, so it is extracted, never simplified.
- livekit_webhook.go (nestif 13 and 14): webhookJoinedEnforceVoiceState,
  webhookLeftCleanupClient and webhookLeftFinishLeave. DB delete still
  precedes broadcast on every path.
- livekit_download.go EnsureLiveKitBinary (52 stmts): one extraction,
  ensureLiveKitStageBinary, keeping every archive path check intact.
- voice_moderation.go (nestif 8): voiceModDeafenRollback. The persisted
  server_muted flag remains the authority.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor(api): clear the remaining complexity budgets across the HTTP layer

- router.go NewRouter (cyclop 28, 84 stmts): split by wiring concern into
  routerTOTPKey, routerHealthDeps, routerMiddleware, routerUploadRoutes,
  routerPluginWiring, routerVoiceRoutes and routerMetricsRoutes. Middleware
  ORDER is a security property (auth before handler, WAF before body parse,
  rate limit before work) and is unchanged; the returned cleanup func still
  closes over and releases everything it did before.
- auth_handler.go handleRegister (133 lines) and handleLogin (cyclop 21,
  152 lines): registerPolicyGate, registerReadRequest, loginReadRequest and
  loginAuthenticate. The always-compare posture, every rate-limit key, every
  counter reset and the ban-check-versus-password-compare order are all
  preserved — including loginUserFailureThreshold staying unscaled by
  scaledAuthLimit, which is deliberate and commented.
- upload_handler.go handleServeFile (cyclop 31, 128 lines): serveFileResolve
  and serveFileAuthorize. Every header this sets — Content-Disposition
  included, which is what stops a stored file being served as active content —
  is still set with the same value in the same circumstances.
- profile_handler.go handleUploadAvatar (120 lines): avatarUploadReadImage,
  mirroring readEmojiUpload in shape but with the avatar caps and MIME set.
  The two deliberately do not share a helper.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor: clear the last complexity budgets in db and admin

- db/account.go DeleteAccount (cyclop 28, 55 stmts): grouped by subsystem into
  deleteAccountAdminGuard, deleteAccountDMChannels and
  deleteAccountCloseDMChannels, each taking the same transaction. The
  transaction boundary, the delete ORDER (which foreign keys depend on) and
  the rollback path are unchanged.
- admin/logstream.go handleLogStream (cyclop 24): logStreamAuthorize. Flush
  cadence, heartbeat and disconnect detection untouched.
- admin/setup_wizard.go validateWizard (cyclop 23): grouped by section into
  wizardValidateIdentity, wizardValidateNetwork and wizardValidateMedia. Every
  message and bound is unchanged — this is the first input-validation boundary
  on a fresh server, before any auth exists.

With this the tree is at zero: golangci-lint run reports 0 issues against the
budgets set in #1384 (funlen 100/50, cyclop 20, nestif 8, dupl 150), with no
//nolint and no exclusion added anywhere.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-18 20:39:45 +02:00

522 lines
24 KiB
Go

package ws
import (
"context"
"fmt"
"log/slog"
"github.com/owncord/server/auth"
"github.com/owncord/server/db"
"github.com/owncord/server/permissions"
)
// Voice moderation handlers: server mute, server deafen, move, disconnect.
//
// All four share one authorization contract, enforced by voiceModTarget:
// MUTE_MEMBERS on the actor's role (Administrator bypasses), the actor must
// strictly outrank the target by role position (mirroring
// ModerationService.requireOutranks), and the target must currently be in a
// voice channel. Effects that reach past the acting connection — the SFU and
// the target's own socket — go through VoiceDeps.Mod.
// registerVoiceModerationV2 registers the four moderator voice commands.
// Called from registerVoiceControlsV2 so the deps struct is built once.
func registerVoiceModerationV2(r *HandlerRegistry, deps VoiceDeps) {
r.RegisterV2(MsgTypeVoiceModMute, handleVoiceModMuteV2, deps)
r.RegisterV2(MsgTypeVoiceModDeafen, handleVoiceModDeafenV2, deps)
r.RegisterV2(MsgTypeVoiceModMove, handleVoiceModMoveV2, deps)
r.RegisterV2(MsgTypeVoiceModKick, handleVoiceModKickV2, deps)
}
// voiceModRole loads a role through the permission cache when one is wired and
// falls back to the live DB otherwise. Every failure is a denial: an
// unresolvable role must never authorize a moderation action.
func voiceModRole(ctx context.Context, d VoiceDeps, userID int64) (*db.Role, bool) {
if d.PermSvc != nil {
role, err := d.PermSvc.GetRoleForUser(ctx, userID)
if err == nil && role != nil {
return role, true
}
return nil, false
}
if d.DB == nil {
return nil, false
}
role, err := d.DB.GetRoleForUser(ctx, userID)
if err != nil || role == nil {
return nil, false
}
return role, true
}
// voiceModTarget runs the shared gate and returns the target's live voice
// state. Authorization is checked before the voice-state lookup so an actor
// without authority always sees FORBIDDEN and never learns who is in voice.
func voiceModTarget(ctx context.Context, d VoiceDeps, actorID, targetID int64) (*db.VoiceState, *Result) {
if actorID == targetID {
return nil, &Result{Error: ClientError{Code: ErrCodeBadRequest, Message: "cannot moderate yourself"}}
}
actorRole, ok := voiceModRole(ctx, d, actorID)
if !ok {
return nil, &Result{Error: ClientError{Code: ErrCodeForbidden, Message: "failed to load actor role"}}
}
if !permissions.HasServerPerm(actorRole.Permissions, permissions.MuteMembers) {
return nil, &Result{Error: ClientError{Code: ErrCodeForbidden, Message: "missing MUTE_MEMBERS permission"}}
}
targetRole, ok := voiceModRole(ctx, d, targetID)
if !ok {
return nil, &Result{Error: ClientError{Code: ErrCodeForbidden, Message: "failed to load target role"}}
}
// Administrator bypasses permission bits, never the hierarchy.
if actorRole.Position <= targetRole.Position {
return nil, &Result{Error: ClientError{
Code: ErrCodeForbidden,
Message: "cannot moderate a user of equal or higher rank",
}}
}
state, err := d.DB.GetVoiceState(ctx, targetID)
if err != nil {
slog.Error("ws voiceModTarget GetVoiceState", "err", err, "target_id", targetID)
return nil, &Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to read voice state"}}
}
if state == nil {
return nil, &Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in a voice channel"}}
}
// MUTE_MEMBERS authorizes moderating server voice channels, not a private
// DM call the actor happens not to be part of — voice_mod_kick and friends
// carry no channel id from the client, so without this a moderator could
// reach into any two users' DM call by targeting a user id alone. Refused
// with the exact same shape as "target not in voice" so the actor learns
// nothing about a DM call they are not in.
ch, err := d.DB.GetChannel(ctx, state.ChannelID)
if err != nil {
slog.Error("ws voiceModTarget GetChannel", "err", err, "channel_id", state.ChannelID)
return nil, &Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to read channel"}}
}
if ch != nil && ch.Type == "dm" {
participant, err := d.DB.IsDMParticipant(ctx, actorID, state.ChannelID)
if err != nil {
slog.Error("ws voiceModTarget IsDMParticipant", "err", err, "channel_id", state.ChannelID)
return nil, &Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to verify DM membership"}}
}
if !participant {
return nil, &Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in a voice channel"}}
}
}
return state, nil
}
// voiceModRateLimited applies the shared per-action rate limit. Each of these
// commands fans a voice_state broadcast out to every client that can see the
// channel, so a moderator must not be able to drive them in a tight loop.
func voiceModRateLimited(d VoiceDeps, action string, userID int64) *Result {
if d.Limiter == nil {
return nil
}
if d.Limiter.Allow(auth.Key(action, userID), voiceModRateLimit, voiceModWindow) {
return nil
}
return &Result{Error: ClientError{Code: ErrCodeRateLimited, Message: "too many voice moderation actions"}}
}
// requireTargetInChannel refuses when the target has moved on since the
// moderator's client rendered the row that produced this command.
func requireTargetInChannel(state *db.VoiceState, channelID int64) *Result {
if state.ChannelID == channelID {
return nil
}
return &Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in that voice channel"}}
}
// voiceChannelDisconnector is the channel-scoped form of
// VoiceModerator.DisconnectFromVoice. The bare interface method takes no
// channel, so it evicts the target from whatever channel their live connection
// is in at that instant — not the channel voiceModTarget authorized against.
// A channel switch on the target's own read-pump goroutine, concurrent with
// the moderator's DB round trips, therefore redirects a kick or a move onto a
// channel that was never checked, up to and including a DM call the actor is
// not a participant of (the case voiceModTarget's IsDMParticipant guard
// exists to refuse).
//
// Widening VoiceModerator itself lives in deps.go; until then *Hub also
// satisfies this optional extension and disconnectFromVoiceIn prefers it,
// falling back to the unscoped method for any other implementation.
type voiceChannelDisconnector interface {
DisconnectFromVoiceInChannel(ctx context.Context, userID, channelID int64) bool
}
// disconnectFromVoiceIn evicts targetID from channelID, reporting false when
// the target has no connection on this node or has already left that channel.
func disconnectFromVoiceIn(ctx context.Context, mod VoiceModerator, targetID, channelID int64) bool {
if scoped, ok := mod.(voiceChannelDisconnector); ok {
return scoped.DisconnectFromVoiceInChannel(ctx, targetID, channelID)
}
return mod.DisconnectFromVoice(ctx, targetID)
}
// handleVoiceModMuteV2 processes a voice_mod_mute command. The DB row is the
// authority for the UI; the SFU mute is what makes it more than cosmetic, so a
// LiveKit failure is logged but does not fail the action — the persisted
// server_muted still blocks the target's own unmute and is re-applied whenever
// the moderator retries.
func handleVoiceModMuteV2(ctx context.Context, cmd Command, info ClientInfo, deps any) Result {
d := deps.(VoiceDeps)
c := cmd.(VoiceModMuteCmd)
if r := voiceModRateLimited(d, "voice_mod_mute", info.UserID); r != nil {
return *r
}
state, r := voiceModTarget(ctx, d, info.UserID, c.TargetID())
if r != nil {
return *r
}
if r := requireTargetInChannel(state, c.ChannelID()); r != nil {
return *r
}
matched, err := d.DB.SetVoiceServerMute(ctx, c.TargetID(), state.ChannelID, c.Muted())
if err != nil {
slog.Error("ws handleVoiceModMuteV2 SetVoiceServerMute", "err", err, "target_id", c.TargetID())
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to update server mute"}}
}
if !matched {
// The target's row moved off state.ChannelID between requireTargetInChannel's
// snapshot and this write (OC-0005) -- same refusal requireTargetInChannel
// itself gives for the non-racing case, so the write never follows the
// target onto a channel (including a DM call) nobody authorized it against.
return Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in that voice channel"}}
}
if d.Mod != nil {
if err := d.Mod.MuteParticipant(ctx, state.ChannelID, c.TargetID(), state.JoinedAt, c.Muted()); err != nil {
slog.Warn("ws handleVoiceModMuteV2 MuteParticipant failed",
"err", err, "target_id", c.TargetID(), "channel_id", state.ChannelID)
}
}
writeVoiceModAudit(ctx, d, info.UserID, "voice_mod_mute", c.TargetID(),
fmt.Sprintf("server mute %s in channel %d", onOff(c.Muted()), state.ChannelID))
slog.Info("voice server mute", "actor_id", info.UserID, "target_id", c.TargetID(),
"channel_id", state.ChannelID, "muted", c.Muted())
return voiceStateBroadcast(ctx, d, c.TargetID())
}
// voiceModDeafenPreMuteRaceHook, when non-nil, runs immediately after the
// deafen write matches and before the implied-mute write that follows it —
// the one-statement-wide window a concurrent channel switch would need to
// land in for OC-0034. Test-only (nil in production), mirroring the
// voiceJoinPostTokenRaceHook / cleanupVoiceRaceClearHook pattern used to pin
// the analogous races elsewhere.
var voiceModDeafenPreMuteRaceHook func(ctx context.Context, d VoiceDeps, targetID int64)
// handleVoiceModDeafenV2 processes a voice_mod_deafen command. Deafen has no
// SFU equivalent (it is about what the target plays back), so it is enforced by
// the target's client honoring server_deafened plus the server refusing their
// own undeafen while it is set.
func handleVoiceModDeafenV2(ctx context.Context, cmd Command, info ClientInfo, deps any) Result {
d := deps.(VoiceDeps)
c := cmd.(VoiceModDeafenCmd)
if r := voiceModRateLimited(d, "voice_mod_deafen", info.UserID); r != nil {
return *r
}
state, r := voiceModTarget(ctx, d, info.UserID, c.TargetID())
if r != nil {
return *r
}
if r := requireTargetInChannel(state, c.ChannelID()); r != nil {
return *r
}
deafenMatched, err := d.DB.SetVoiceServerDeafen(ctx, c.TargetID(), state.ChannelID, c.Deafened())
if err != nil {
slog.Error("ws handleVoiceModDeafenV2 SetVoiceServerDeafen", "err", err, "target_id", c.TargetID())
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to update server deafen"}}
}
if !deafenMatched {
// The target's row moved off state.ChannelID between requireTargetInChannel's
// snapshot and this write (OC-0005) -- refuse exactly as requireTargetInChannel
// itself does for the non-racing case, before the implied mute below can
// touch a channel nobody authorized it against.
return Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in that voice channel"}}
}
if voiceModDeafenPreMuteRaceHook != nil {
voiceModDeafenPreMuteRaceHook(ctx, d, c.TargetID())
}
// A server deafen implies a server mute at the SFU: a deafened user must
// not keep talking into a room they cannot hear. Lifting the deafen must
// lift that implied mute too, or the target stays SFU-muted and refused
// their own unmute even after the deafen is gone. server_muted is a
// single bool with no way to tell "explicit" from "deafen-implied" apart,
// so an explicit-mute-then-deafen sequence has both lifted together by an
// undeafen — accepted as the simplest correct behavior given the schema.
muteMatched, err := d.DB.SetVoiceServerMute(ctx, c.TargetID(), state.ChannelID, c.Deafened())
if err != nil || !muteMatched {
if err != nil {
slog.Error("ws handleVoiceModDeafenV2 SetVoiceServerMute", "err", err, "target_id", c.TargetID())
}
voiceModDeafenRollback(ctx, d, c, state)
if err != nil {
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to update server deafen"}}
}
return Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not in that voice channel"}}
}
if d.Mod != nil {
if err := d.Mod.MuteParticipant(ctx, state.ChannelID, c.TargetID(), state.JoinedAt, c.Deafened()); err != nil {
slog.Warn("ws handleVoiceModDeafenV2 MuteParticipant failed",
"err", err, "target_id", c.TargetID(), "channel_id", state.ChannelID)
}
}
writeVoiceModAudit(ctx, d, info.UserID, "voice_mod_deafen", c.TargetID(),
fmt.Sprintf("server deafen %s in channel %d", onOff(c.Deafened()), state.ChannelID))
slog.Info("voice server deafen", "actor_id", info.UserID, "target_id", c.TargetID(),
"channel_id", state.ChannelID, "deafened", c.Deafened())
return voiceStateBroadcast(ctx, d, c.TargetID())
}
// voiceModDeafenRollback best-effort undoes the server_deafened write
// handleVoiceModDeafenV2 committed just before the implied server_muted write
// failed to land.
//
// The deafen write above already committed as its own statement (no
// transaction spans the two — a single UPDATE covering both columns
// needs a db-change; see cross_batch). Best-effort undo it rather
// than leave server_deafened=1 with server_muted=0: that combination
// is not SFU-muted yet still refuses the target's own undeafen
// (refuseIfServerSilenced), for a deafen nobody was ever told about.
// Detached from ctx — the cancellation that most likely caused the
// failure above (the moderator's socket dropping mid-request, or the
// target moving off state.ChannelID between the two writes) must not
// also abort the rollback.
//
// Re-read the row's CURRENT channel rather than reusing the stale
// state.ChannelID snapshot: when the mismatch above was caused by
// the target switching channels (not leaving voice), the row is no
// longer on state.ChannelID, so a rollback scoped to that stale
// channel matches zero rows and silently no-ops -- exactly the case
// this rollback exists to handle (OC-0034). Clearing a restriction
// is safe on whatever channel the row is actually on now; if the
// row is gone entirely (target left voice), there is nothing left
// to roll back.
//
// The rollback value is the OPPOSITE of the request (!c.Deafened()),
// so which channel it is safe to scope to depends on which
// direction it runs:
// - request was a DEAFEN (c.Deafened()==true): rollback CLEARS.
// Clearing a restriction can never authorize anything the
// target wasn't already free of, so following the row to
// cur.ChannelID is safe -- this is the OC-0034 case above.
// - request was an UNDEAFEN (c.Deafened()==false): rollback
// APPLIES a restriction. Scoping an apply to cur.ChannelID
// would stamp it onto whatever channel the row now points at,
// including one voiceModTarget never authorized the actor
// against (OC-0036) -- the exact hazard channel-scoping exists
// to prevent for the ordinary write path. Scope to
// state.ChannelID (the channel that WAS authorized) instead,
// so a moved/rejoined target simply matches zero rows.
func voiceModDeafenRollback(ctx context.Context, d VoiceDeps, c VoiceModDeafenCmd, state *db.VoiceState) {
compCtx := context.WithoutCancel(ctx)
if cur, gErr := d.DB.GetVoiceState(compCtx, c.TargetID()); gErr != nil {
slog.Error("ws handleVoiceModDeafenV2 GetVoiceState for rollback",
"err", gErr, "target_id", c.TargetID())
} else if cur != nil {
rollbackChannelID := cur.ChannelID
if !c.Deafened() {
rollbackChannelID = state.ChannelID
}
if _, compErr := d.DB.SetVoiceServerDeafen(compCtx, c.TargetID(), rollbackChannelID, !c.Deafened()); compErr != nil {
slog.Error("ws handleVoiceModDeafenV2 SetVoiceServerDeafen rollback failed",
"err", compErr, "target_id", c.TargetID())
}
}
}
// handleVoiceModMoveV2 processes a voice_mod_move command.
//
// The move is a server-driven leave followed by a client-driven re-join: the
// hub runs its voice-leave routine for the target (DB row, LiveKit participant,
// voice_leave broadcast) and then sends voice_moved, which the target's client
// answers with an ordinary voice_join for the destination. That keeps one
// implementation of the join sequence — capacity, token minting, key-holder
// election, existing-state fan-out — instead of a second, divergent copy here.
// The checks below are the pre-flight: they refuse a move the re-join would
// only bounce, so the target is never dropped from voice for nothing.
func handleVoiceModMoveV2(ctx context.Context, cmd Command, info ClientInfo, deps any) Result {
d := deps.(VoiceDeps)
c := cmd.(VoiceModMoveCmd)
if r := voiceModRateLimited(d, "voice_mod_move", info.UserID); r != nil {
return *r
}
state, r := voiceModTarget(ctx, d, info.UserID, c.TargetID())
if r != nil {
return *r
}
if state.ChannelID == c.ToChannelID() {
return Result{Error: ClientError{Code: ErrCodeBadRequest, Message: "user is already in that voice channel"}}
}
dest, err := d.DB.GetChannel(ctx, c.ToChannelID())
if err != nil {
slog.Error("ws handleVoiceModMoveV2 GetChannel", "err", err, "channel_id", c.ToChannelID())
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to read destination channel"}}
}
if dest == nil {
return Result{Error: ClientError{Code: ErrCodeNotFound, Message: "channel not found"}}
}
if dest.Type != "voice" {
return Result{Error: ClientError{Code: ErrCodeBadRequest, Message: "destination is not a voice channel"}}
}
// The re-join this move hands off to (handleVoiceJoin) refuses an
// archived channel outright; check it here too, or the pre-flight commits
// the destructive half of the move for a re-join guaranteed to bounce.
if dest.Archived {
return Result{Error: ClientError{Code: ErrCodeBadRequest, Message: "channel is archived"}}
}
// The destination is gated on the TARGET's access, not the moderator's:
// a move must not become a way to place someone in a channel they could
// not join themselves.
if !hasChannelAccess(ctx, d.DB, d.Permissions, d.PermSvc, c.TargetID(), c.ToChannelID(), permissions.ConnectVoice) {
return Result{Error: ClientError{
Code: ErrCodeForbidden,
Message: "user cannot connect to that voice channel",
}}
}
// Advisory capacity check with JoinVoiceChannelIfCapacity's semantics. The
// atomic one still runs on the re-join; this one keeps the common case from
// dropping the target into a channel that is already full.
if dest.VoiceMaxUsers > 0 {
count, cErr := d.DB.CountChannelVoiceUsers(ctx, c.ToChannelID())
if cErr != nil {
slog.Error("ws handleVoiceModMoveV2 CountChannelVoiceUsers", "err", cErr, "channel_id", c.ToChannelID())
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "failed to check channel capacity"}}
}
if count >= dest.VoiceMaxUsers {
return Result{Error: ClientError{Code: ErrCodeChannelFull, Message: "voice channel is full"}}
}
}
if d.Mod == nil {
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "voice moderation unavailable"}}
}
if !disconnectFromVoiceIn(ctx, d.Mod, c.TargetID(), state.ChannelID) {
// No live connection on this node — the voice_states row is a ghost the
// sweeper owns, and there is nobody to send voice_moved to — or the
// target left the checked channel while this handler was deciding, in
// which case the move must not follow them.
return Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not connected"}}
}
d.Mod.SendToUser(c.TargetID(), buildVoiceMoved(c.ToChannelID()))
writeVoiceModAudit(ctx, d, info.UserID, "voice_mod_move", c.TargetID(),
fmt.Sprintf("moved from channel %d to channel %d", state.ChannelID, c.ToChannelID()))
slog.Info("voice moderator move", "actor_id", info.UserID, "target_id", c.TargetID(),
"from_channel_id", state.ChannelID, "to_channel_id", c.ToChannelID())
// handleVoiceLeave already broadcast voice_leave for the old channel; the
// re-join broadcasts voice_state for the new one.
return Result{}
}
// handleVoiceModKickV2 processes a voice_mod_kick command: the target is
// removed from the LiveKit room, their voice_states row is deleted and
// voice_leave is broadcast (all by the hub's voice-leave routine), then they
// are told why.
func handleVoiceModKickV2(ctx context.Context, cmd Command, info ClientInfo, deps any) Result {
d := deps.(VoiceDeps)
c := cmd.(VoiceModKickCmd)
if r := voiceModRateLimited(d, "voice_mod_kick", info.UserID); r != nil {
return *r
}
state, r := voiceModTarget(ctx, d, info.UserID, c.TargetID())
if r != nil {
return *r
}
if d.Mod == nil {
return Result{Error: ClientError{Code: ErrCodeInternal, Message: "voice moderation unavailable"}}
}
// Scoped to the channel the gate above authorized: a target who switched
// channels mid-decision must not be kicked out of the new one.
if !disconnectFromVoiceIn(ctx, d.Mod, c.TargetID(), state.ChannelID) {
return Result{Error: ClientError{Code: ErrCodeVoiceError, Message: "user is not connected"}}
}
d.Mod.SendToUser(c.TargetID(),
buildVoiceDisconnected(state.ChannelID, "You were disconnected from voice by a moderator"))
writeVoiceModAudit(ctx, d, info.UserID, "voice_mod_kick", c.TargetID(),
fmt.Sprintf("disconnected from channel %d", state.ChannelID))
slog.Info("voice moderator disconnect", "actor_id", info.UserID, "target_id", c.TargetID(),
"channel_id", state.ChannelID)
return Result{}
}
// writeVoiceModAudit records a moderation action. The row must survive a
// connection that dies right after the effect landed, so the write is detached
// from the dispatching context.
func writeVoiceModAudit(ctx context.Context, d VoiceDeps, actorID int64, action string, targetID int64, detail string) {
if d.DB == nil {
return
}
db.WriteAudit(context.WithoutCancel(ctx), d.DB, actorID, action, "user", targetID, detail)
}
// onOff renders a boolean for an audit detail string.
func onOff(v bool) string {
if v {
return "on"
}
return "off"
}
// ── Hub-side effects ────────────────────────────────────────────────────────
// MuteParticipant mutes or unmutes the target's published audio at the SFU.
// Satisfies VoiceModerator; reads h.livekit at call time so SetLiveKit's late
// wiring is picked up (same reason as GenerateToken).
func (h *Hub) MuteParticipant(ctx context.Context, channelID, userID int64, voiceJoinToken string, muted bool) error {
if h.livekit == nil {
return fmt.Errorf("voice not configured")
}
return h.livekit.MuteParticipantAudio(ctx, channelID, userID, voiceJoinToken, muted)
}
// DisconnectFromVoice runs the hub's voice-leave routine for another user's
// connection, which is what a moderator move or disconnect needs: DB row,
// LiveKit participant, topic unsubscribe, key-holder re-election and the
// voice_leave broadcast, in the one implementation that also serves the
// disconnect and channel-switch paths. Reports false when the user has no
// connection on this node.
func (h *Hub) DisconnectFromVoice(ctx context.Context, userID int64) bool {
c := h.GetClient(userID)
if c == nil {
return false
}
h.handleVoiceLeave(ctx, c)
return true
}
// DisconnectFromVoiceInChannel is DisconnectFromVoice conditioned on the
// channel the caller authorized against, satisfying voiceChannelDisconnector.
// The comparison and the clear happen together under the client's voiceMu
// (handleVoiceLeaveIfStillIn -> clearVoiceStateIfMatch), so a channel switch
// committed on the target's own goroutine after the moderator's checks either
// loses the race outright or is left untouched — never evicted in place of the
// channel that was checked. Reports false in both of those cases, which the
// callers already treat as "user is not connected".
func (h *Hub) DisconnectFromVoiceInChannel(ctx context.Context, userID, channelID int64) bool {
c := h.GetClient(userID)
if c == nil {
return false
}
return h.handleVoiceLeaveIfStillIn(ctx, c, channelID)
}