Skip to main content

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}