1use std::{borrow::Borrow, iter::once};
2
3use futures::{FutureExt, StreamExt, TryFutureExt};
4use ruma::{
5 CanonicalJsonObject, CanonicalJsonValue, OwnedEventId, OwnedServerName, RoomId,
6 RoomOrAliasId, RoomVersionId, UserId,
7 api::federation::{
8 self,
9 membership::{
10 RawStrippedState,
11 create_knock_event::v1::{
12 Request as SendKnockRequest, Response as SendKnockResponse,
13 },
14 },
15 },
16 canonical_json::to_canonical_value,
17 events::{
18 AnyStrippedStateEvent, StateEventType,
19 receipt::ReceiptThread,
20 room::member::{MembershipState, RoomMemberEventContent},
21 },
22 room_version_rules::RoomVersionRules,
23 serde::Raw,
24 signatures::Verified,
25};
26use tuwunel_core::{
27 Err, Result, async_noinline, at, debug_info, debug_warn, err, implement, info, trace,
28 utils::{self, IterStream, result::LogErr, stream::WidebandExt},
29 warn,
30};
31use tuwunel_matrix::{
32 Event, PduCount,
33 event::gen_event_id,
34 pdu::{PduBuilder, PduEvent},
35 room_version::rules as room_version_rules,
36};
37
38use super::{
39 Service, StrippedCreateVerdict, dedup_stripped_state, enforce_stripped_create,
40 stripped_state::occupies_cell, v12_room_ids, without_member,
41};
42use crate::{
43 membership::join::get_servers_for_room,
44 rooms::{state::RoomMutexGuard, state_cache::MembershipUpdate},
45};
46
47type Summary = Vec<Raw<AnyStrippedStateEvent>>;
51
52#[implement(Service)]
53#[async_noinline]
55#[tracing::instrument(
56 name = "knock",
57 level = "debug",
58 skip_all,
59 fields(%sender_user, %room_id)
60)]
61pub async fn knock<'a>(
62 &'a self,
63 sender_user: &'a UserId,
64 room_id: &'a RoomId,
65 orig_server_name: Option<&'a RoomOrAliasId>,
66 reason: Option<String>,
67 servers: &'a [OwnedServerName],
68 state_lock: &'a RoomMutexGuard,
69) -> Result {
70 let servers =
71 get_servers_for_room(&self.services, sender_user, room_id, orig_server_name, servers)
72 .await?;
73
74 if self
75 .services
76 .state_cache
77 .is_invited(sender_user, room_id)
78 .await
79 {
80 debug_warn!(%sender_user, %room_id, "Invited user attempted to knock.");
81 return Err!(Request(Forbidden(
82 "You cannot knock on a room you are already invited/accepted to."
83 )));
84 }
85
86 if self
87 .services
88 .state_cache
89 .is_joined(sender_user, room_id)
90 .await
91 {
92 debug_warn!(%sender_user, %room_id, "Joined user attempted to knock.");
93 return Err!(Request(Forbidden("You cannot knock on a room you are already joined in.")));
94 }
95
96 let server_in_room = self
97 .services
98 .state_cache
99 .server_in_room(self.services.globals.server_name(), room_id)
100 .await;
101
102 if server_in_room
104 && self
105 .services
106 .state_cache
107 .is_knocked(sender_user, room_id)
108 .await
109 {
110 debug_warn!(%sender_user, %room_id, "User is already knocking.");
111 return Ok(());
112 }
113
114 if self
115 .banned_from_resident_room(sender_user, room_id)
116 .await
117 {
118 debug_warn!(%sender_user, %room_id, "Banned user attempted to knock.");
119 return Err!(Request(Forbidden("You cannot knock on a room you are banned from.")));
120 }
121
122 let local_knock = server_in_room
123 || servers.is_empty()
124 || (servers.len() == 1 && self.services.globals.server_is_ours(&servers[0]));
125
126 if local_knock {
127 self.knock_room_helper_local(sender_user, room_id, reason, &servers, state_lock)
128 .await
129 } else {
130 self.knock_room_helper_remote(sender_user, room_id, reason, &servers)
131 .boxed() .await
133 }
134}
135
136#[implement(Service)]
137async fn knock_room_helper_local(
138 &self,
139 sender_user: &UserId,
140 room_id: &RoomId,
141 reason: Option<String>,
142 servers: &[OwnedServerName],
143 state_lock: &RoomMutexGuard,
144) -> Result {
145 debug_info!("We can knock locally");
146
147 let room_version_id = self
148 .services
149 .state
150 .get_room_version(room_id)
151 .await?;
152
153 ensure_room_version_supports_knock(&room_version_id)?;
154
155 let content = self
156 .services
157 .profile
158 .fill_content(sender_user, RoomMemberEventContent {
159 reason: reason.clone(),
160 ..RoomMemberEventContent::new(MembershipState::Knock)
161 })
162 .await;
163
164 let Err(error) = self
165 .services
166 .timeline
167 .build_and_append_pdu(
168 PduBuilder::state(sender_user.to_string(), &content),
169 sender_user,
170 room_id,
171 state_lock,
172 )
173 .await
174 else {
175 return Ok(());
176 };
177
178 if servers.is_empty()
179 || (servers.len() == 1 && self.services.globals.server_is_ours(&servers[0]))
180 {
181 return Err(error);
182 }
183
184 warn!("We couldn't do the knock locally, maybe federation can help to satisfy the knock");
185
186 self.knock_room_local_federation_fallback(sender_user, room_id, reason, servers, state_lock)
187 .boxed() .await
189}
190
191fn ensure_room_version_supports_knock(room_version_id: &RoomVersionId) -> Result {
192 if matches!(
193 room_version_id,
194 RoomVersionId::V1
195 | RoomVersionId::V2
196 | RoomVersionId::V3
197 | RoomVersionId::V4
198 | RoomVersionId::V5
199 | RoomVersionId::V6
200 ) {
201 return Err!(Request(Forbidden("This room does not support knocking.")));
202 }
203
204 Ok(())
205}
206
207#[implement(Service)]
208async fn knock_room_local_federation_fallback(
209 &self,
210 sender_user: &UserId,
211 room_id: &RoomId,
212 reason: Option<String>,
213 servers: &[OwnedServerName],
214 state_lock: &RoomMutexGuard,
215) -> Result {
216 let (pdu, event) = self
217 .knock_over_federation(sender_user, room_id, reason, servers)
218 .await?;
219
220 info!("Appending room knock event locally");
221 self.services
222 .timeline
223 .append_pdu(&pdu, event, once(pdu.event_id.borrow()), None, state_lock)
224 .await?;
225
226 Ok(())
227}
228
229#[implement(Service)]
235async fn knock_room_helper_remote(
236 &self,
237 sender_user: &UserId,
238 room_id: &RoomId,
239 reason: Option<String>,
240 servers: &[OwnedServerName],
241) -> Result {
242 info!("Knocking over federation.");
243
244 self.knock_over_federation(sender_user, room_id, reason, servers)
245 .await?;
246
247 Ok(())
248}
249
250#[implement(Service)]
257async fn knock_over_federation(
258 &self,
259 sender_user: &UserId,
260 room_id: &RoomId,
261 reason: Option<String>,
262 servers: &[OwnedServerName],
263) -> Result<(PduEvent, CanonicalJsonObject)> {
264 let (make_knock_response, remote_server) = self
265 .make_knock_request(sender_user, room_id, servers)
266 .await?;
267
268 info!("make_knock finished");
269
270 let room_version_id = make_knock_response.room_version.clone();
271
272 self.services
273 .config
274 .require_supported_room_version(&room_version_id)?;
275
276 let (knock_event, event_id) = self
277 .build_knock_event(sender_user, room_id, reason, &make_knock_response, &room_version_id)
278 .await?;
279
280 let send_knock_response = self
281 .execute_send_knock(&remote_server, room_id, &event_id, &knock_event, &room_version_id)
282 .await?;
283
284 self.services
285 .short
286 .get_or_create_shortroomid(room_id)
287 .await;
288
289 info!("Parsing knock event");
290 let pdu = PduEvent::from_object_and_eventid(&event_id, knock_event.clone())
291 .map_err(|e| err!(BadServerResponse("Invalid knock event PDU: {e:?}")))?;
292
293 let summary = self
294 .knock_summary(room_id, &room_version_id, &pdu, send_knock_response.knock_room_state)
295 .await?;
296
297 self.record_knock(room_id, sender_user, &pdu, summary)
298 .await?;
299
300 Ok((pdu, knock_event))
301}
302
303#[implement(Service)]
304async fn build_knock_event(
305 &self,
306 sender_user: &UserId,
307 room_id: &RoomId,
308 reason: Option<String>,
309 make_knock_response: &federation::membership::prepare_knock_event::v1::Response,
310 room_version_id: &RoomVersionId,
311) -> Result<(CanonicalJsonObject, OwnedEventId)> {
312 let mut knock_event_stub: CanonicalJsonObject =
313 serde_json::from_str(make_knock_response.event.get()).map_err(|e| {
314 err!(BadServerResponse("Invalid make_knock event json received from server: {e:?}"))
315 })?;
316
317 let content = self
318 .services
319 .profile
320 .fill_content(sender_user, RoomMemberEventContent {
321 reason,
322 ..RoomMemberEventContent::new(MembershipState::Knock)
323 })
324 .await;
325
326 knock_event_stub.insert(
327 "origin".into(),
328 CanonicalJsonValue::String(
329 self.services
330 .globals
331 .server_name()
332 .as_str()
333 .to_owned(),
334 ),
335 );
336 knock_event_stub.insert(
337 "origin_server_ts".into(),
338 CanonicalJsonValue::Integer(
339 utils::millis_since_unix_epoch()
340 .try_into()
341 .expect("Timestamp is valid js_int value"),
342 ),
343 );
344 knock_event_stub.insert(
345 "content".into(),
346 to_canonical_value(content).expect("event is valid, we just created it"),
347 );
348
349 knock_event_stub
350 .insert("room_id".into(), CanonicalJsonValue::String(room_id.as_str().into()));
351
352 knock_event_stub
353 .insert("state_key".into(), CanonicalJsonValue::String(sender_user.as_str().into()));
354
355 knock_event_stub
356 .insert("sender".into(), CanonicalJsonValue::String(sender_user.as_str().into()));
357
358 knock_event_stub.insert("type".into(), CanonicalJsonValue::String("m.room.member".into()));
359
360 self.services
363 .server_keys
364 .hash_and_sign_event(&mut knock_event_stub, room_version_id)?;
365
366 let event_id = gen_event_id(&knock_event_stub, room_version_id)?;
367
368 knock_event_stub
369 .insert("event_id".into(), CanonicalJsonValue::String(event_id.clone().into()));
370
371 Ok((knock_event_stub, event_id))
372}
373
374#[implement(Service)]
375async fn execute_send_knock(
376 &self,
377 remote_server: &OwnedServerName,
378 room_id: &RoomId,
379 event_id: &OwnedEventId,
380 knock_event: &CanonicalJsonObject,
381 room_version_id: &RoomVersionId,
382) -> Result<SendKnockResponse> {
383 info!("Asking {remote_server} for send_knock in room {room_id}");
384 let send_knock_request = SendKnockRequest {
385 room_id: room_id.to_owned(),
386 event_id: event_id.clone(),
387 pdu: self
388 .services
389 .federation
390 .format_pdu_into(knock_event.clone(), Some(room_version_id))
391 .await,
392 };
393
394 let response = self
395 .services
396 .federation
397 .execute(remote_server, send_knock_request)
398 .await?;
399
400 info!("send_knock finished");
401
402 Ok(SendKnockResponse::new(dedup_stripped_state(response.knock_room_state)))
404}
405
406#[implement(Service)]
407async fn make_knock_request(
408 &self,
409 sender_user: &UserId,
410 room_id: &RoomId,
411 servers: &[OwnedServerName],
412) -> Result<(federation::membership::prepare_knock_event::v1::Response, OwnedServerName)> {
413 let mut make_knock_response_and_server =
414 Err!(BadServerResponse("No server available to assist in knocking."));
415
416 let mut make_knock_counter: usize = 0;
417
418 for remote_server in servers {
419 if self
420 .services
421 .globals
422 .server_is_ours(remote_server)
423 {
424 continue;
425 }
426
427 info!("Asking {remote_server} for make_knock ({make_knock_counter})");
428
429 let make_knock_response = self
430 .services
431 .federation
432 .execute(remote_server, federation::membership::prepare_knock_event::v1::Request {
433 room_id: room_id.to_owned(),
434 user_id: sender_user.to_owned(),
435 ver: self
436 .services
437 .config
438 .supported_room_versions()
439 .map(at!(0))
440 .collect(),
441 })
442 .await;
443
444 trace!("make_knock response: {make_knock_response:?}");
445 make_knock_counter = make_knock_counter.saturating_add(1);
446
447 make_knock_response_and_server = make_knock_response.map(|r| (r, remote_server.clone()));
448
449 if make_knock_response_and_server.is_ok() {
450 break;
451 }
452
453 if make_knock_counter > 40 {
454 warn!(
455 "50 servers failed to provide valid make_knock response, assuming no server can \
456 assist in knocking."
457 );
458 make_knock_response_and_server =
459 Err!(BadServerResponse("No server available to assist in knocking."));
460
461 return make_knock_response_and_server;
462 }
463 }
464
465 make_knock_response_and_server
466}
467
468#[implement(Service)]
475#[expect(
476 deprecated,
477 reason = "Matrix 1.16 still permits receiving the legacy stripped variant for backwards \
478 compatibility."
479)]
480async fn knock_summary(
481 &self,
482 room_id: &RoomId,
483 room_version_id: &RoomVersionId,
484 knock_pdu: &PduEvent,
485 knock_room_state: Vec<RawStrippedState>,
486) -> Result<Summary> {
487 let pdus = knock_room_state
488 .iter()
489 .filter_map(|state| match state {
490 | RawStrippedState::Pdu(pdu) => Some(pdu),
491 | RawStrippedState::Stripped(_) => None,
492 });
493
494 self.services
495 .server_keys
496 .acquire_events_pubkeys(pdus)
497 .await;
498
499 let verdict = self
500 .validate_stripped_create(&knock_room_state, room_id, room_version_id)
501 .await?;
502
503 let enforce = self
504 .services
505 .config
506 .federation
507 .enforce_stripped_state_pdu_validation;
508
509 let drop_create = enforce_stripped_create(verdict, v12_room_ids(room_version_id), enforce);
510
511 if verdict != StrippedCreateVerdict::Valid {
512 debug_warn!(?verdict, %room_id, drop_create, "MSC4311 knock create-event validation failed");
513 }
514
515 let rules = room_version_rules(room_version_id)?;
516 let summary = without_member(knock_room_state, knock_pdu.sender())
517 .filter(|state| !drop_create || !occupies_cell(state, &StateEventType::RoomCreate, ""))
518 .stream()
519 .wide_filter_map(|state| {
520 self.knock_summary_entry(room_id, room_version_id, &rules, state)
521 })
522 .chain(once(knock_pdu.to_format()).stream())
523 .collect()
524 .await;
525
526 Ok(summary)
527}
528
529#[implement(Service)]
530#[expect(
531 deprecated,
532 reason = "Matrix 1.16 still permits receiving the legacy stripped variant for backwards \
533 compatibility."
534)]
535async fn knock_summary_entry(
536 &self,
537 room_id: &RoomId,
538 room_version_id: &RoomVersionId,
539 rules: &RoomVersionRules,
540 state: RawStrippedState,
541) -> Option<Raw<AnyStrippedStateEvent>> {
542 let pdu = match state {
543 | RawStrippedState::Stripped(raw) => return Some(raw),
544 | RawStrippedState::Pdu(pdu) => pdu,
545 };
546
547 let (event_id, pdu, _, verified) = self
548 .verified_pdu(room_id, room_version_id, rules, &pdu)
549 .inspect_err(
550 |error| debug_warn!(%room_id, %error, "Omitting an invalid knock summary event."),
551 )
552 .map(Result::ok)
553 .await?;
554
555 if verified != Verified::All {
556 debug_warn!(%room_id, %event_id, "Omitting a knock summary event failing its content hash.");
557 return None;
558 }
559
560 Some(pdu.to_format())
561}
562
563#[implement(Service)]
564async fn record_knock(
565 &self,
566 room_id: &RoomId,
567 sender_user: &UserId,
568 pdu: &PduEvent,
569 summary: Summary,
570) -> Result {
571 info!("Updating membership locally to knock state with the room summary");
572 let count = self.services.globals.next_count();
573 let membership_event = pdu.get_content().expect("we just created this");
574
575 self.services
577 .pusher
578 .reset_notification_counts_for_thread(
579 sender_user,
580 room_id,
581 None,
582 &ReceiptThread::Unthreaded,
583 )
584 .await;
585
586 self.services
587 .sending
588 .refresh_push_badge(sender_user)
589 .await
590 .log_err()
591 .ok();
592
593 let knock = MembershipUpdate::self_sent(
594 room_id,
595 sender_user,
596 membership_event,
597 PduCount::Normal(*count),
598 );
599
600 self.services
601 .state_cache
602 .update_membership(MembershipUpdate {
603 last_state: Some(summary),
604 update_joined_count: false,
605 ..knock
606 })
607 .await
608}
609
610#[cfg(test)]
611mod tests;