extend command_handler macro

now supports aliases and restricted commands, captures docs

Author: internet-catte

doc/command-handlers.md

@@ -14,17 +14,23 @@ Handlers are identified by the `command_handler` attribute macro.
 
 ## The command_handler macro
 
-The `command_handler` attribute macro has two possible forms, allowing for
-multiple command dispatchers to exist.
+The `command_handler` attribute macro can take several arguments:
 
-The single-argument form - e.g. `#[command_handler("CAP")]` defines a handler
-for the 'default' global dispatcher, which is used to look up client protocol
-commands.
+```rs
+#[command_handler("PRIMARY", "ALIAS", "ALIAS2", in("PARENT"), restricted)]
+```
 
-The two-argument form - e.g. `#[command_handler("CERT", in("NS"))]` puts the
-handler into a named secondary dispatcher, in this case `"NS"`. This form is
+The first argument defines the primary name of the command. Any further strings
+given will be used as aliases for the command.
+
+If an argument is given of the form `in("PARENT")`, the command handler will be
+put into a named secondary dispatcher, in this case `"PARENT"`. This form is
 used to define handlers for services commands, and may have other uses in the
-future.
+future. If this argument is not given, the handler is added to the 'default'
+global dispatcher, which is used to look up client protocol commands.
+
+If the `restricted` keyword is added, the command will be marked as for operators
+and will not be shown in `HELP` output to users.
 
 ## Async handlers
 

sable_ircd/src/command/dispatcher.rs

@@ -1,3 +1,5 @@
+use std::collections::hash_map;
+
 use super::{plumbing::Command, *};
 
 /// Type alias for a boxed command context
@@ -7,17 +9,21 @@ pub type BoxCommand<'cmd> = Box<dyn Command + 'cmd>;
 /// attribute macro
 pub type CommandHandlerWrapper = for<'a> fn(BoxCommand<'a>) -> Option<AsyncHandler<'a>>;
 
+#[derive(Clone)]
 /// A command handler registration. Constructed by the `command_handler` attribute macro.
 pub struct CommandRegistration {
     pub(super) command: &'static str,
+    pub(super) aliases: &'static [&'static str],
     pub(super) dispatcher: Option<&'static str>,
     pub(super) handler: CommandHandlerWrapper,
+    pub(super) restricted: bool,
+    pub(super) docs: &'static [&'static str],
 }
 
 /// A command dispatcher. Collects registered command handlers and allows lookup by
 /// command name.
 pub struct CommandDispatcher {
-    handlers: HashMap<String, CommandHandlerWrapper>,
+    commands: HashMap<String, CommandRegistration>,
 }
 
 inventory::collect!(CommandRegistration);
@@ -42,11 +48,14 @@ impl CommandDispatcher {
 
         for reg in inventory::iter::<CommandRegistration> {
             if reg.dispatcher == category_name {
-                map.insert(reg.command.to_ascii_uppercase(), reg.handler);
+                map.insert(reg.command.to_ascii_uppercase(), reg.clone());
+                for alias in reg.aliases {
+                    map.insert(alias.to_ascii_uppercase(), reg.clone());
+                }
             }
         }
 
-        Self { handlers: map }
+        Self { commands: map }
     }
 
     /// Look up and execute the handler function for to a given command.
@@ -59,12 +68,20 @@ impl CommandDispatcher {
     ) -> Option<AsyncHandler<'cmd>> {
         let command: BoxCommand<'cmd> = Box::new(command);
 
-        match self.handlers.get(&command.command().to_ascii_uppercase()) {
-            Some(handler) => handler(command),
+        match self.commands.get(&command.command().to_ascii_uppercase()) {
+            Some(cmd) => (cmd.handler)(command),
             None => {
                 command.notify_error(CommandError::CommandNotFound(command.command().to_owned()));
                 None
             }
         }
     }
+
+    pub fn get_command(&self, command: &str) -> Option<&CommandRegistration> {
+        self.commands.get(&command.to_ascii_uppercase())
+    }
+
+    pub fn iter_commands(&self) -> hash_map::Iter<'_, String, CommandRegistration> {
+        self.commands.iter()
+    }
 }

sable_ircd/src/server/mod.rs

@@ -21,7 +21,7 @@ use tokio::{
 };
 
 use std::{
-    collections::VecDeque,
+    collections::{hash_map, VecDeque},
     sync::{Arc, Weak},
     time::Duration,
 };
@@ -116,6 +116,16 @@ impl ClientServer {
         self.node.name()
     }
 
+    /// Get a command from the server's dispatcher
+    pub fn get_command(&self, cmd: &str) -> Option<&CommandRegistration> {
+        self.command_dispatcher.get_command(cmd)
+    }
+
+    /// Get a command from the server's dispatcher
+    pub fn iter_commands(&self) -> hash_map::Iter<'_, String, CommandRegistration> {
+        self.command_dispatcher.iter_commands()
+    }
+
     /// Submit a command action to process in the next loop iteration.
     #[tracing::instrument(skip(self))]
     pub fn add_action(&self, act: CommandAction) {

sable_macros/src/command_handler.rs

@@ -2,32 +2,67 @@ use super::*;
 
 use quote::{quote, quote_spanned};
 use syn::{
-    parenthesized, parse::Parse, parse_macro_input, token::In, Ident, ItemFn, LitStr, Token,
+    parenthesized, parse::Parse, parse_macro_input, token::In, Attribute, Ident, ItemFn, LitStr,
+    Meta, MetaNameValue, Token,
 };
 
 struct CommandHandlerAttr {
     command_name: LitStr,
+    aliases: Vec<LitStr>,
     dispatcher: Option<LitStr>,
+    restricted: bool,
 }
 
 impl Parse for CommandHandlerAttr {
     fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
         let command_name = input.parse()?;
-        let dispatcher = if input.parse::<Token![,]>().is_ok() {
-            let content;
-            input.parse::<In>()?;
-            let _paren = parenthesized!(content in input);
-            Some(content.parse()?)
-        } else {
-            None
-        };
+        let mut aliases = vec![];
+        let mut dispatcher = None;
+        let mut restricted = false;
+        while input.peek(Token![,]) {
+            if !input.peek2(LitStr) {
+                break;
+            }
+            let _ = input.parse::<Token![,]>();
+            aliases.push(input.parse()?);
+        }
+        while input.peek(Token![,]) {
+            let _ = input.parse::<Token![,]>()?;
+            if input.peek(In) {
+                let content;
+                input.parse::<In>()?;
+                let _paren = parenthesized!(content in input);
+                dispatcher = Some(content.parse()?);
+            } else if input.peek(Ident) {
+                if input.parse::<Ident>()? == "restricted" {
+                    restricted = true;
+                }
+            }
+        }
         Ok(Self {
             command_name,
+            aliases,
             dispatcher,
+            restricted,
         })
     }
 }
 
+pub fn command_docs(attrs: &[Attribute]) -> Vec<String> {
+    attrs
+        .iter()
+        .filter(|a| a.path.is_ident("doc"))
+        .filter_map(|a| match a.parse_meta() {
+            Ok(Meta::NameValue(MetaNameValue {
+                lit: syn::Lit::Str(s),
+                ..
+            })) => Some(s.value()),
+            _ => None,
+        })
+        .map(|s| s.strip_prefix(' ').unwrap_or(&s).trim_end().to_owned())
+        .collect()
+}
+
 pub fn command_handler(attr: TokenStream, item: TokenStream) -> TokenStream {
     let input = parse_macro_input!(attr as CommandHandlerAttr);
     let item = parse_macro_input!(item as ItemFn);
@@ -43,11 +78,24 @@ pub fn command_handler(attr: TokenStream, item: TokenStream) -> TokenStream {
         }
     }
 
+    let aliases = input.aliases;
+    for alias in &aliases {
+        for c in alias.value().chars() {
+            if !c.is_ascii_uppercase() {
+                return quote_spanned!(command_name.span()=> compile_error!("Command aliases should be uppercase")).into();
+            }
+        }
+    }
+
     let dispatcher = match input.dispatcher {
         Some(name) => quote!( Some( #name ) ),
         None => quote!(None),
     };
 
+    let restricted = input.restricted;
+
+    let docs = command_docs(&item.attrs);
+
     let body = if asyncness.is_none() {
         quote!(
             if let Err(e) = crate::command::plumbing::call_handler(ctx.as_ref(), &super::#name, ctx.args())
@@ -90,8 +138,11 @@ pub fn command_handler(attr: TokenStream, item: TokenStream) -> TokenStream {
 
             inventory::submit!(crate::command::CommandRegistration {
                 command: #command_name,
+                aliases: &[ #(#aliases),* ],
                 dispatcher: #dispatcher,
-                handler: call_proxy
+                handler: call_proxy,
+                restricted: #restricted,
+                docs: &[ #(#docs),* ],
             });
         }
     ).into()