Struct Service 

pub struct Service {
    services: Arc<OnceServices>,
    channel: RwLock<Option<Sender<CommandInput>>>,
    pub command: RwLock<Option<Arc<dyn Command>>>,
    pub admin_alias: OwnedRoomAliasId,
    register_nonces: Mutex<BTreeMap<String, Instant>>,
    pub console: Arc<Console>,
}

Fields

services: Arc<OnceServices>

channel: RwLock<Option<Sender<CommandInput>>>

command: RwLock<Option<Arc<dyn Command>>>

admin_alias: OwnedRoomAliasId

register_nonces: Mutex<BTreeMap<String, Instant>>

console: Arc<Console>

Implementations

impl Service

pub(super) async fn attach( &self, output: &CommandOutput, ) -> Result<RoomMessageEventContent>

Uploads a command’s output to the media repository and builds an m.file message referencing it. The caller attaches the relation.

impl Service

pub(super) async fn console_auto_start(&self)

Possibly spawn the terminal console at startup if configured and standard input is a terminal.

impl Service

pub(super) async fn console_auto_stop(&self)

Shutdown the console when the admin worker terminates.

impl Service

pub async fn startup_execute(&self) -> Result

Execute admin commands after startup

impl Service

pub(super) async fn signal_execute(&self) -> Result

Execute admin commands after signal

impl Service

async fn execute_command(&self, i: usize, command: String) -> Result

Execute one admin command after startup or signal

impl Service

fn execute_command_output(i: usize, content: &CommandOutput) -> Result

impl Service

fn execute_command_error(i: usize, content: &CommandOutput) -> Result

impl Service

pub async fn make_user_admin(&self, user_id: &UserId) -> Result

Invite the user to the tuwunel admin room.

This is equivalent to granting server admin privileges. A local user must already hold an account, or the grant would wait for whoever registers the name.

impl Service

pub async fn make_room_admin(&self, room_id: &RoomId, target: &UserId) -> Result

Grant room admin powers to a target by impersonating the highest-powered local member.

The target is granted the impersonated member’s power level (100 when that member is a room-version 12 creator with infinite power), sent as a new m.room.power_levels from that member. When the room is non-public and the target is neither joined nor invited, the target is invited first.

impl Service

async fn invite_new_admin( &self, user_id: &UserId, room_id: &RoomId, state_lock: &RoomMutexGuard, ) -> Result

impl Service

pub async fn revoke_admin(&self, user_id: &UserId) -> Result

Demote an admin, removing its rights.

The server user is refused, since the admin room exists only while the server user stays joined.

impl Service

pub async fn notify(&self, body: &str)

Sends a notice gated on the admin_room_notices config; admin command responses use the unconditional notice().

impl Service

pub async fn notify_loud(&self, body: &str)

Sends a message gated on the admin_room_notices config; admin command responses use the unconditional send_text().

impl Service

pub async fn notice(&self, body: &str)

Sends markdown notice to the admin room as the admin user.

impl Service

pub async fn send_text(&self, body: &str)

Sends markdown message (not an m.notice for notification reasons) to the admin room as the admin user.

impl Service

pub async fn send_report(&self, body: &str)

Sends a markdown report to the configured report room, falling back to the admin room, as the server user.

impl Service

pub async fn send_message( &self, message_content: RoomMessageEventContent, ) -> Result

Sends a message to the admin room as the admin user (see send_text() for convenience).

impl Service

async fn send_to_room( &self, content: RoomMessageEventContent, room_id: &RoomId, ) -> Result

impl Service

pub fn issue_register_nonce(&self) -> String

impl Service

pub fn consume_register_nonce(&self, nonce: &str) -> bool

Consume nonce if it exists and has not expired. The entry is removed either way; true means the caller may proceed.

impl Service

pub fn register_is_enabled(&self) -> bool

Answered without opening the secret file, since the nonce endpoint this gates takes no authentication and is not rate limited.

impl Service

pub fn register_shared_secret(&self) -> Option<Secret>

Reads registration_shared_secret_file on every call, so a rotated secret takes effect without a restart.

impl Service

pub(super) async fn handle_response( &self, output: CommandOutput, reply_id: Option<&EventId>, ) -> Result

impl Service

async fn respond( &self, output: &CommandOutput, room_id: &RoomId, sender: &UserId, mode: &Mode, ) -> Result

Splits the output across up to admin_output_max_events reply or thread events; output needing more events, or any output when the limit is zero, is uploaded and posted as a single file attachment instead.

impl Service

async fn send_segments( &self, segments: &[String], room_id: &RoomId, sender: &UserId, mode: &Mode, markdown: bool, ) -> Result

Appends every segment under one room lock, chaining each reply to the event id returned by the previous append.

impl Service

pub(super) async fn respond_to_room( &self, content: RoomMessageEventContent, room_id: &RoomId, user_id: &UserId, ) -> Result

impl Service

async fn handle_response_error( &self, e: Error, room_id: &RoomId, user_id: &UserId, state_lock: &RoomMutexGuard, ) -> Result

impl Service

pub async fn command(&self, input: CommandInput) -> Result

Queues a command for the service worker and returns once it is queued.

The worker processes it later and replies to the reply_id event in its room, posting nothing without one. Queueing waits while the queue is full, and errors when the queue is unavailable or closed.

pub async fn command_in_place(&self, input: CommandInput) -> ProcessorResult

Dispatches a command to the processor on the current task and waits for completion.

The queue is bypassed, so the outcome returns to the caller rather than being posted as a reply.

pub fn complete_command(&self, command: &str) -> Option<String>

Invokes the tab-completer to complete the command. When unavailable, None is returned.

async fn handle_signal(&self, sig: &'static str)

async fn handle_command(&self, command: CommandInput)

async fn process_command(&self, command: &CommandInput) -> ProcessorResult

pub async fn user_is_admin(&self, user_id: &UserId) -> bool

Checks whether a given user is an admin of this server

pub async fn user_is_last_admin(&self, user_id: &UserId) -> bool

Checks whether a given user is the only active admin left on this server.

The server user is never counted: it can sign in only while an emergency password is configured. Deactivated accounts still joined to the admin room are not counted either, since none of them can sign in to act. Nor is a passwordless account, such as an appservice’s user, since it stores the same empty password as a deactivated one.

pub async fn get_admin_room(&self) -> Result<OwnedRoomId>

Gets the room ID of the admin room

Errors are propagated from the database, and will have None if there is no admin room

pub async fn get_report_room(&self) -> Result<OwnedRoomId>

Gets the room reports are posted to: the configured report room when set and usable, otherwise the admin room.

async fn resolve_report_room( &self, report_room: &RoomOrAliasId, ) -> Result<OwnedRoomId>

pub async fn is_admin_command<Pdu>(&self, event: &Pdu, body: &str) -> bool

where Pdu: Event,

Returns whether a message event is an admin command to run.

Only an m.text from an admin qualifies: prefixed with !admin or the server user’s ID in the admin room, or escaped as \!admin by a local admin anywhere when escape commands are enabled. The server user’s own messages in the admin room are refused unless the emergency password is set.

pub async fn is_admin_room(&self, room_id_: &RoomId) -> bool

impl Service

pub async fn lock_admin_room(&self) -> Option<RoomMutexGuard>

Locks the admins room’s state, when there is an admins room.

Hold the guard from the Service::user_is_last_admin check until the change it permits is made. The admins room’s leave and ban guard runs under the same lock, so two concurrent removals cannot each see the other as the admin who remains.

Trait Implementations

impl Service for Service

fn build(args: &Args<'_>) -> Result<Arc<Self>>

Implement the construction of the service instance. Services are generally singletons so expect this to only be called once for a service type. Note that it may be called again after a server reload, but the prior instance will have been dropped first. Failure will shutdown the server with an error.

fn worker<'async_trait>( self: Arc<Self>, ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait,

Implement the service’s worker loop. The service manager spawns a task and calls this function after all services have been built.

fn interrupt<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Interrupt the service. This is sent to initiate a graceful shutdown. The service worker should return from its work loop.

fn name(&self) -> &str

Return the name of the service. i.e. crate::service::make_name(std::module_path!())

fn clear_cache<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Clear any caches or similar runtime state.

fn memory_usage<'life0, 'life1, 'async_trait>( &'life0 self, _out: &'life1 mut (dyn Write + Send), ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Memory usage report in a markdown string.

fn unconstrained(&self) -> bool

Return true if the service worker opts out of the tokio cooperative budgeting. This can reduce tail latency at the risk of event loop starvation.