client, server: let callers opt out of the claim on queue RPCs

[erikhortsch]

A queue subscription selects exactly one server before any claim exists, so on a queue RPC the claim handshake only ratifies a decision the bus already made. The server bids a hardcoded affinity = 1, and the caller sets AcceptFirstAvailable for every non-affinity method, so nothing can change the outcome. It costs two extra fire-and-forget publishes per call, and the claim response goes to SRV.<service>.<topic> — no .Q — so every server registered for the topic receives and discards one per request.

This is bus-independent: SubscribeQueue is exclusive on NATS (queue group), Redis (SetNX on the payload hash), and local (round-robin), so the redundancy is not specific to any broker.

1. skip_claim

Request gains skip_claim (field 9), set by the caller whenever the RPC is queue-routed. The server honors it only when its own RequestInfo also says queue:

if h.i.RequireClaim {
    if ir.SkipClaim && h.i.Queue {
        ...
    } else if claimed, err := h.claimRequest(s, ctx, ir, req); ...
}

That re-check matters on the redis path specifically. Channel.Server embeds .Q iff Queue, so on NATS a client/server disagreement over queue-ness puts them on different subjects and the request simply never arrives — fail-closed. Channel.Legacy, which redis uses, has no queue component, so both land on the same channel and a skew would otherwise let several plain subscribers each honor skip_claim and run the handler.

2. Affinity is rejected on a queue RPC, not worked around

Trying to set affinity on a queue is a broken config. Only 1 server will ever get the request. Trying to configure affinity on a queue now results in an error.

Registration (newRPCHandler, the single choke point for RPC handlers): an affinity function on a queue method is rejected with InvalidArgument. The generator emits one only for Routing_AFFINITY, so generated code cannot produce the pair, but RegisterHandler is exported and nothing checked. Its decline path (affinity < 0) would drop the request with no response. Stream handlers never use queue subscriptions and are unaffected.

Per request (newRPC): SelectionFunc, MinimumAffinity and MaximumAffinity on a queue method are rejected the same way. AcceptFirstAvailable and AffinityTimeout are excluded, since getRequestOpts defaults both in for every non-affinity method.

Note this also surfaces an existing silent failure: MinimumAffinity > 1 on a queue method makes the claim unacceptable forever, so the RPC always fails with no explanation. That is now an error at the call.

No call site in the livekit tree is affected: handlers are registered only from generated code, and of the five WithSelectionOpts call sites, two are on StartEgress (affinity, queue=false) and three set only AcceptFirstAvailable/AffinityTimeout.

3. A skipped claim is still observable

Skipping emitted no lifecycle event, so a migrated queue RPC looked identical to no traffic at all. ClaimOutcome gains ClaimSkipped, reported with a zero wait since nothing was negotiated, and only where RequireClaim is set so methods that never claimed do not inflate the count.

It rides the existing claim_wait_time_ms{service,method,outcome} series from livekit/protocol#1687 — granted decaying to zero against skipped rising is the migration, per method. protocol needs no change: PSRPCMetricsObserver.OnClaim already labels by outcome.String().

Mixed fleets need no deploy ordering

The caller still registers its claim channel and still answers a claim if one arrives, so:

	behavior
old caller + new server	skip_claim defaults false, server claims — unchanged
new caller + old server	field ignored, server claims, caller answers it — unchanged
new caller + new server	claim skipped, 4 hops become 2

The permissiveness is what makes this safe. Not registering the claim channel when skip_claim is set would reintroduce a break where the server times out at request expiry and silently returns nil.

Incidental fix, and one behavior change

selectServer previously discarded a successful response that arrived during selection — the arm was commented will only happen with malformed requests and only extracted an error. A response reaching it was consumed and the call ended in ErrNoResponse. It now returns that response to the caller.

Related behavior change, scoped to skip_claim: an error response now returns immediately rather than being held until the selection timeout. The only response that can precede a claim is MalformedRequest; the old accumulate-and-wait exists so that on a broadcast RPC one server failing to deserialize does not lose a good response from another. A queue RPC has one recipient, so the first response is the final answer. Broadcast behavior is unchanged.

Tests

TestSkipClaim asserts via the observer that a queue RPC records ClaimSkipped and runs its handler once, while a broadcast RPC on the same client still records ClaimGranted. It runs on all three buses, since the property comes from SubscribeQueue rather than any one broker.

TestQueueRejectsAffinityFunc and TestQueueRejectsAffinitySelection cover the two validations, including that the broadcast case still accepts an affinity function and that the defaulted-in selection options are not rejected.

Two selectServer unit tests cover both mixed-fleet directions: skip_claim set with a claim arriving must honor the claim; skip_claim set with a response arriving must hand it back.

Worth noting the existing suite never registered a queue=true method — every RegisterMethod call passes false for the queue argument — so the queue request path had no end-to-end coverage before this.

Reviewer notes

• internal/internal.pb.go carries a protoc header change (v4.23.4 → v5.28.2). Regenerated with the repo's pinned protoc and protoc-gen-go v1.36.4 to match the existing file; the pinned protoc has moved since the file was last generated. Worth regenerating with whatever CI pins.
• No generator change — getRequireClaim is untouched, so generated services need no regeneration. Making the skip a codegen decision instead would break both mixed-fleet directions, one of them silently.

🤖 Generated with Claude Code