tuwunel_admin/debug/mod.rs
1// Fires in clap's Subcommand derive output, which an item-level allow does not reach.
2#![expect(clippy::large_unopt_stack_frames)]
3
4mod backoff_metrics;
5mod change_log_level;
6#[cfg(feature = "jwt_login")]
7mod create_jwt;
8mod database_files;
9mod database_stats;
10mod delete_forward_extremities;
11mod dump_pdus;
12mod echo;
13mod first_pdu_in_room;
14mod force_device_list_updates;
15mod force_set_room_state_from_server;
16mod get_auth_chain;
17mod get_pdu;
18mod get_remote_pdu;
19mod get_remote_pdu_list;
20mod get_retained_pdu;
21mod get_room_state;
22mod get_short_pdu;
23mod get_signing_keys;
24mod get_verify_keys;
25mod latest_pdu_in_room;
26mod list_dependencies;
27mod memory_stats;
28mod parse_pdu;
29mod ping;
30mod prev_walk_metrics;
31mod prev_walk_rooms;
32mod rebuild_relation_index;
33mod rebuild_thread_index;
34mod resolve_true_destination;
35mod resync_database;
36mod runtime_interval;
37mod runtime_metrics;
38mod show_remote_pdu;
39mod sign_json;
40mod state_at_incoming;
41mod state_local_metrics;
42mod task_interval;
43mod task_metrics;
44pub(crate) mod tester;
45mod time;
46mod trim_memory;
47mod verify_json;
48mod verify_pdu;
49
50use clap::Subcommand;
51use ruma::{OwnedEventId, OwnedRoomId, OwnedRoomOrAliasId, OwnedServerName};
52use tuwunel_core::Result;
53use tuwunel_service::rooms::short::ShortRoomId;
54
55use self::tester::TesterCommand;
56use crate::{
57 admin_command_dispatch,
58 event_fetcher::{self, EventFetcherCommand},
59};
60
61#[admin_command_dispatch]
62#[derive(Debug, Subcommand)]
63pub(super) enum DebugCommand {
64 /// - Echo input of admin command
65 Echo {
66 message: Vec<String>,
67 },
68
69 /// - Get the auth_chain of a PDU
70 GetAuthChain {
71 /// An event ID (the $ character followed by the base64 reference hash)
72 event_id: OwnedEventId,
73 },
74
75 /// - Parse and print a PDU from a JSON
76 ///
77 /// The PDU event is only checked for validity and is not added to the
78 /// database.
79 ///
80 /// This command needs a JSON blob provided in a Markdown code block below
81 /// the command.
82 ParsePdu,
83
84 /// - Retrieve and print a PDU by EventID from the tuwunel database
85 GetPdu {
86 /// An event ID (a $ followed by the base64 reference hash)
87 event_id: OwnedEventId,
88 },
89
90 /// - Retrieve and print a PDU by PduId from the tuwunel database
91 GetShortPdu {
92 /// Shortroomid integer
93 shortroomid: ShortRoomId,
94
95 /// PduCount integer
96 count: i64,
97 },
98
99 /// - Requests a PDU from a remote server and prints the result. The PDU is
100 /// not inserted into the database.
101 ShowRemotePdu {
102 /// An event ID (a $ followed by the base64 reference hash)
103 event_id: OwnedEventId,
104
105 /// Server to fetch the PDU from
106 server: OwnedServerName,
107 },
108
109 /// - Attempts to retrieve a PDU from a remote server. Inserts it into our
110 /// database/timeline if found and we do not have this PDU already
111 /// (following normal event auth rules, handles it as an incoming PDU).
112 GetRemotePdu {
113 /// An event ID (a $ followed by the base64 reference hash)
114 event_id: OwnedEventId,
115
116 /// Argument for us to attempt to fetch the event from the
117 /// specified remote server.
118 server: OwnedServerName,
119 },
120
121 /// - Same as `get-remote-pdu` but accepts a codeblock newline delimited
122 /// list of PDUs and a single server to fetch from
123 GetRemotePduList {
124 /// Argument for us to attempt to fetch all the events from the
125 /// specified remote server.
126 server: OwnedServerName,
127
128 /// If set, ignores errors, else stops at the first error/failure.
129 #[arg(short, long)]
130 force: bool,
131 },
132
133 /// - Gets all the room state events for the specified room.
134 GetRoomState {
135 /// Room ID
136 room_id: OwnedRoomOrAliasId,
137
138 /// Event Type
139 kind: Option<String>,
140
141 /// State Key
142 state_key: Option<String>,
143 },
144
145 /// - Get and display signing keys from local cache or remote server.
146 GetSigningKeys {
147 server_name: Option<OwnedServerName>,
148
149 #[arg(long)]
150 notary: Option<OwnedServerName>,
151
152 #[arg(short, long)]
153 query: bool,
154 },
155
156 /// - Get and display signing keys from local cache or remote server.
157 GetVerifyKeys {
158 server_name: Option<OwnedServerName>,
159 },
160
161 /// - Sends a federation request to the remote server's
162 /// `/_matrix/federation/v1/version` endpoint and measures the latency it
163 /// took for the server to respond
164 Ping {
165 server: OwnedServerName,
166 },
167
168 /// - Forces device lists for all local and remote users to be updated (as
169 /// having new keys available)
170 ForceDeviceListUpdates,
171
172 /// - Change tracing log level/filter on the fly
173 ///
174 /// This accepts the same format as the `log` config option.
175 ChangeLogLevel {
176 /// Log level/filter
177 filter: Option<String>,
178
179 /// Resets the log level/filter to the one in your config
180 #[arg(short, long)]
181 reset: bool,
182 },
183
184 /// - Sign JSON blob
185 ///
186 /// This command needs a JSON blob provided in a Markdown code block below
187 /// the command.
188 SignJson,
189
190 /// - Verify JSON signatures
191 ///
192 /// This command needs a JSON blob provided in a Markdown code block below
193 /// the command.
194 VerifyJson,
195
196 /// - Verify PDU
197 ///
198 /// This re-verifies a PDU existing in the database found by ID.
199 VerifyPdu {
200 event_id: OwnedEventId,
201 },
202
203 /// - Prints the very first PDU in the specified room (typically
204 /// m.room.create)
205 FirstPduInRoom {
206 /// The room ID
207 room_id: OwnedRoomId,
208 },
209
210 /// - Prints the latest ("last") PDU in the specified room (typically a
211 /// message)
212 LatestPduInRoom {
213 /// The room ID
214 room_id: OwnedRoomId,
215 },
216
217 /// - Forcefully replaces the room state of our local copy of the specified
218 /// room, with the copy (auth chain and room state events) the specified
219 /// remote server says.
220 ///
221 /// A common desire for room deletion is to simply "reset" our copy of the
222 /// room. While this admin command is not a replacement for that, if you
223 /// know you have split/broken room state and you know another server in the
224 /// room that has the best/working room state, this command can let you use
225 /// their room state. Such example is your server saying users are in a
226 /// room, but other servers are saying they're not in the room in question.
227 ///
228 /// This command will get the latest PDU in the room we know about, and
229 /// request the room state at that point in time via
230 /// `/_matrix/federation/v1/state/{roomId}`.
231 ForceSetRoomStateFromServer {
232 /// The impacted room ID
233 room_id: OwnedRoomId,
234 /// The server we will use to query the room state for
235 server_name: OwnedServerName,
236 },
237
238 /// - Prunes the room's forward extremities down to a single one, keeping
239 /// the extremity furthest along in stream order.
240 ///
241 /// A room accumulates extra forward extremities when it takes on events
242 /// across a gap or fork it cannot fully resolve; collapsing them repairs a
243 /// room wedged with a large or growing extremity set. This is the
244 /// admin-command counterpart to the Synapse
245 /// `DELETE /_synapse/admin/v1/rooms/{roomId}/forward_extremities` endpoint.
246 DeleteForwardExtremities {
247 /// The room ID or alias
248 room_id: OwnedRoomOrAliasId,
249 },
250
251 /// - Runs a server name through tuwunel's true destination resolution
252 /// process
253 ///
254 /// Useful for debugging well-known issues
255 ResolveTrueDestination {
256 server_name: OwnedServerName,
257
258 #[arg(short, long)]
259 no_cache: bool,
260 },
261
262 /// - Print extended memory usage
263 ///
264 /// Optional argument is a character mask (a sequence of characters in any
265 /// order) which enable additional extended statistics. Known characters are
266 /// "abdeglmx". For convenience, a '*' will enable everything.
267 MemoryStats {
268 opts: Option<String>,
269 },
270
271 /// - Print general tokio runtime metric totals.
272 RuntimeMetrics,
273
274 /// - Print detailed tokio runtime metrics accumulated since last command
275 /// invocation.
276 RuntimeInterval,
277
278 /// - Print detailed tokio task metrics accumulated in total.
279 TaskMetrics,
280
281 /// - Print process-lifetime state-local build metrics.
282 ///
283 /// Difference two snapshots to observe an interval.
284 StateLocalMetrics,
285
286 /// - Print process-lifetime incoming prev-walk metrics.
287 ///
288 /// Difference two snapshots to observe an interval.
289 PrevWalkMetrics,
290
291 /// - Print process-lifetime backoff verdict metrics.
292 ///
293 /// Difference two snapshots to observe an interval.
294 BackoffMetrics,
295
296 /// - Print the prev walk passes recorded per room, kept for up to three days.
297 ///
298 /// Without a room, lists the rooms with the most recorded passes and their
299 /// totals. With a room, lists its latest passes. A pass is recorded when it
300 /// ends, unless a backoff hold withheld it or its fetch left nothing to walk.
301 PrevWalkRooms {
302 /// The room to list the latest passes of
303 room_id: Option<OwnedRoomId>,
304
305 /// How many rooms or passes to list
306 #[arg(short, long, default_value_t = 20)]
307 limit: usize,
308 },
309
310 /// - Print detailed tokio task metrics accumulated since last command
311 /// invocation.
312 TaskInterval,
313
314 /// - Print the current time
315 Time,
316
317 /// - List dependencies
318 ListDependencies {
319 #[arg(short, long)]
320 names: bool,
321 },
322
323 /// - Get database statistics
324 DatabaseStats {
325 property: Option<String>,
326
327 #[arg(short, long, alias("column"))]
328 map: Option<String>,
329 },
330
331 /// - Trim memory usage
332 TrimMemory,
333
334 /// - List database files
335 DatabaseFiles {
336 map: Option<String>,
337
338 #[arg(long)]
339 level: Option<i32>,
340 },
341
342 /// - Create a JWT token for login
343 #[cfg(feature = "jwt_login")]
344 CreateJwt {
345 /// Localpart of the user's MXID
346 user: String,
347
348 /// Set expiration time in seconds from now.
349 #[arg(long)]
350 exp_from_now: Option<u64>,
351
352 /// Set not-before time in seconds from now.
353 #[arg(long)]
354 nbf_from_now: Option<u64>,
355
356 /// Claim an issuer.
357 #[arg(long)]
358 issuer: Option<String>,
359
360 /// Claim an audience.
361 #[arg(long)]
362 audience: Option<String>,
363 },
364
365 /// - Synchronize database with primary (secondary only)
366 ResyncDatabase,
367
368 /// - Rebuild the typed relation index (relatesto_typed) from all PDUs
369 RebuildRelationIndex,
370
371 /// - Rebuild the thread activity index (threadactivityid_rootid) from all
372 /// thread roots
373 RebuildThreadIndex,
374
375 /// - Retrieves the saved original PDU before it has been redacted
376 GetRetainedPdu {
377 event_id: OwnedEventId,
378 },
379
380 /// - Dump all stored PDUs
381 DumpPdus {
382 dir: String,
383 },
384
385 /// - Run a diagnostic local state derivation for one stored event and report
386 /// the outcome without writing room state, resolved-state memos, or
387 /// production counters
388 StateAtIncoming {
389 /// An event ID (a $ followed by the base64 reference hash)
390 event_id: OwnedEventId,
391 },
392
393 /// - Drive the federation event-fetcher service directly (diagnostic)
394 #[command(subcommand)]
395 #[clap(hide = true)]
396 EventFetcher(EventFetcherCommand),
397
398 /// - Developer test stubs
399 #[command(subcommand)]
400 #[clap(hide(true))]
401 Tester(TesterCommand),
402}