Document Emitter trait method panics

.changes/document-event-name-requirements.md

@@ -0,0 +1,5 @@
+---
+"tauri": patch:enhance
+---
+
+Document requirements on event names and panics that result if requirements are not met.

crates/tauri/src/app.rs

@@ -18,7 +18,7 @@ use crate::{
   sealed::{ManagerBase, RuntimeOrDispatch},
   utils::{config::Config, Env},
   webview::PageLoadPayload,
-  Context, DeviceEventFilter, Emitter, EventLoopMessage, Listener, Manager, Monitor, Result,
+  Context, DeviceEventFilter, Emitter, EventLoopMessage, EventName, Listener, Manager, Monitor,
   Runtime, Scopes, StateManager, Theme, Webview, WebviewWindowBuilder, Window,
 };
 
@@ -38,7 +38,6 @@ use tauri_runtime::{
 };
 use tauri_utils::{assets::AssetsIter, PackageInfo};
 
-use serde::Serialize;
 use std::{
   borrow::Cow,
   collections::HashMap,
@@ -929,7 +928,8 @@ macro_rules! shared_app_impl {
       where
         F: Fn(Event) + Send + 'static,
       {
-        self.manager.listen(event.into(), EventTarget::App, handler)
+        let event = EventName::new(event.into()).unwrap();
+        self.manager.listen(event, EventTarget::App, handler)
       }
 
       /// Listen to an event on this app only once.
@@ -939,7 +939,8 @@ macro_rules! shared_app_impl {
       where
         F: FnOnce(Event) + Send + 'static,
       {
-        self.manager.once(event.into(), EventTarget::App, handler)
+        let event = EventName::new(event.into()).unwrap();
+        self.manager.once(event, EventTarget::App, handler)
       }
 
       /// Unlisten to an event on this app.
@@ -966,79 +967,7 @@ macro_rules! shared_app_impl {
       }
     }
 
-    impl<R: Runtime> Emitter<R> for $app {
-      /// Emits an event to all [targets](EventTarget).
-      ///
-      /// # Examples
-      /// ```
-      /// use tauri::Emitter;
-      ///
-      /// #[tauri::command]
-      /// fn synchronize(app: tauri::AppHandle) {
-      ///   // emits the synchronized event to all webviews
-      ///   app.emit("synchronized", ());
-      /// }
-      /// ```
-      fn emit<S: Serialize + Clone>(&self, event: &str, payload: S) -> Result<()> {
-        self.manager.emit(event, payload)
-      }
-
-      /// Emits an event to all [targets](EventTarget) matching the given target.
-      ///
-      /// # Examples
-      /// ```
-      /// use tauri::{Emitter, EventTarget};
-      ///
-      /// #[tauri::command]
-      /// fn download(app: tauri::AppHandle) {
-      ///   for i in 1..100 {
-      ///     std::thread::sleep(std::time::Duration::from_millis(150));
-      ///     // emit a download progress event to all listeners
-      ///     app.emit_to(EventTarget::any(), "download-progress", i);
-      ///     // emit an event to listeners that used App::listen or AppHandle::listen
-      ///     app.emit_to(EventTarget::app(), "download-progress", i);
-      ///     // emit an event to any webview/window/webviewWindow matching the given label
-      ///     app.emit_to("updater", "download-progress", i); // similar to using EventTarget::labeled
-      ///     app.emit_to(EventTarget::labeled("updater"), "download-progress", i);
-      ///     // emit an event to listeners that used WebviewWindow::listen
-      ///     app.emit_to(EventTarget::webview_window("updater"), "download-progress", i);
-      ///   }
-      /// }
-      /// ```
-      fn emit_to<I, S>(&self, target: I, event: &str, payload: S) -> Result<()>
-      where
-        I: Into<EventTarget>,
-        S: Serialize + Clone,
-      {
-        self.manager.emit_to(target, event, payload)
-      }
-
-      /// Emits an event to all [targets](EventTarget) based on the given filter.
-      ///
-      /// # Examples
-      /// ```
-      /// use tauri::{Emitter, EventTarget};
-      ///
-      /// #[tauri::command]
-      /// fn download(app: tauri::AppHandle) {
-      ///   for i in 1..100 {
-      ///     std::thread::sleep(std::time::Duration::from_millis(150));
-      ///     // emit a download progress event to the updater window
-      ///     app.emit_filter("download-progress", i, |t| match t {
-      ///       EventTarget::WebviewWindow { label } => label == "main",
-      ///       _ => false,
-      ///     });
-      ///   }
-      /// }
-      /// ```
-      fn emit_filter<S, F>(&self, event: &str, payload: S, filter: F) -> Result<()>
-      where
-        S: Serialize + Clone,
-        F: Fn(&EventTarget) -> bool,
-      {
-        self.manager.emit_filter(event, payload, filter)
-      }
-    }
+    impl<R: Runtime> Emitter<R> for $app {}
   };
 }
 

crates/tauri/src/error.rs

@@ -160,6 +160,9 @@ pub enum Error {
   /// Bad `__TAURI_INVOKE_KEY__` value received in ipc message.
   #[error("bad __TAURI_INVOKE_KEY__ value received in ipc message")]
   InvokeKey,
+  /// Illegal event name.
+  #[error("only alphanumeric, '-', '/', ':', '_' permitted for event names: {0:?}")]
+  IllegalEventName(String),
 }
 
 impl From<getrandom::Error> for Error {

crates/tauri/src/event/listener.rs

@@ -21,10 +21,10 @@ enum Pending {
   Unlisten(EventId),
   Listen {
     id: EventId,
-    event: String,
+    event: crate::EventName,
     handler: Handler,
   },
-  Emit(EmitArgs),
+  Emit(crate::EventName, EmitArgs),
 }
 
 /// Stored in [`Listeners`] to be called upon, when the event that stored it, is triggered.
@@ -128,28 +128,31 @@ impl Listeners {
       match action {
         Pending::Unlisten(id) => self.unlisten(id),
         Pending::Listen { id, event, handler } => self.listen_with_id(id, event, handler),
-        Pending::Emit(args) => {
-          self.emit(args)?;
+        Pending::Emit(event, args) => {
+          self.emit(event, args)?;
         }
       }
     }
 
     Ok(())
   }
 
-  fn listen_with_id(&self, id: EventId, event: String, handler: Handler) {
+  fn listen_with_id(&self, id: EventId, event: crate::EventName, handler: Handler) {
     match self.inner.handlers.try_lock() {
       Err(_) => self.insert_pending(Pending::Listen { id, event, handler }),
       Ok(mut lock) => {
-        lock.entry(event).or_default().insert(id, handler);
+        lock
+          .entry(event.into_inner())
+          .or_default()
+          .insert(id, handler);
       }
     }
   }
 
   /// Adds an event listener.
   pub(crate) fn listen<F: Fn(Event) + Send + 'static>(
     &self,
-    event: String,
+    event: crate::EventName,
     target: EventTarget,
     handler: F,
   ) -> EventId {
@@ -162,7 +165,7 @@ impl Listeners {
   /// Listen to an event and immediately unlisten.
   pub(crate) fn once<F: FnOnce(Event) + Send + 'static>(
     &self,
-    event: String,
+    event: crate::EventName,
     target: EventTarget,
     handler: F,
   ) -> EventId {
@@ -190,16 +193,21 @@ impl Listeners {
   }
 
   /// Emits the given event with its payload based on a filter.
-  pub(crate) fn emit_filter<F>(&self, emit_args: EmitArgs, filter: Option<F>) -> crate::Result<()>
+  pub(crate) fn emit_filter<F>(
+    &self,
+    event: crate::EventName,
+    emit_args: EmitArgs,
+    filter: Option<F>,
+  ) -> crate::Result<()>
   where
     F: Fn(&EventTarget) -> bool,
   {
     let mut maybe_pending = false;
 
     match self.inner.handlers.try_lock() {
-      Err(_) => self.insert_pending(Pending::Emit(emit_args)),
+      Err(_) => self.insert_pending(Pending::Emit(event, emit_args)),
       Ok(lock) => {
-        if let Some(handlers) = lock.get(&emit_args.event_name) {
+        if let Some(handlers) = lock.get(event.as_str()) {
           let handlers = handlers.iter();
           let handlers = handlers.filter(|(_, h)| match_any_or_filter(&h.target, &filter));
           for (&id, Handler { callback, .. }) in handlers {
@@ -218,13 +226,13 @@ impl Listeners {
   }
 
   /// Emits the given event with its payload.
-  pub(crate) fn emit(&self, emit_args: EmitArgs) -> crate::Result<()> {
-    self.emit_filter(emit_args, None::<&dyn Fn(&EventTarget) -> bool>)
+  pub(crate) fn emit(&self, event: crate::EventName, emit_args: EmitArgs) -> crate::Result<()> {
+    self.emit_filter(event, emit_args, None::<&dyn Fn(&EventTarget) -> bool>)
   }
 
   pub(crate) fn listen_js(
     &self,
-    event: &str,
+    event: crate::EventName<&str>,
     source_webview_label: &str,
     target: EventTarget,
     id: EventId,
@@ -238,29 +246,29 @@ impl Listeners {
       .insert(JsHandler::new(target, id));
   }
 
-  pub(crate) fn unlisten_js(&self, event: &str, id: EventId) {
+  pub(crate) fn unlisten_js(&self, event: crate::EventName<&str>, id: EventId) {
     let mut js_listeners = self.inner.js_event_listeners.lock().unwrap();
     let js_listeners = js_listeners.values_mut();
     for js_listeners in js_listeners {
-      if let Some(handlers) = js_listeners.get_mut(event) {
+      if let Some(handlers) = js_listeners.get_mut(event.as_str()) {
         handlers.retain(|h| h.id != id);
 
         if handlers.is_empty() {
-          js_listeners.remove(event);
+          js_listeners.remove(event.as_str());
         }
       }
     }
   }
 
   pub(crate) fn has_js_listener<F: Fn(&EventTarget) -> bool>(
     &self,
-    event: &str,
+    event: crate::EventName<&str>,
     filter: F,
   ) -> bool {
     let js_listeners = self.inner.js_event_listeners.lock().unwrap();
     js_listeners.values().any(|events| {
       events
-        .get(event)
+        .get(event.as_str())
         .map(|handlers| handlers.iter().any(|handler| filter(&handler.target)))
         .unwrap_or(false)
     })
@@ -269,7 +277,6 @@ impl Listeners {
   pub(crate) fn emit_js_filter<'a, R, I, F>(
     &self,
     mut webviews: I,
-    event: &str,
     emit_args: &EmitArgs,
     filter: Option<F>,
   ) -> crate::Result<()>
@@ -280,6 +287,7 @@ impl Listeners {
   {
     let js_listeners = self.inner.js_event_listeners.lock().unwrap();
     webviews.try_for_each(|webview| {
+      let event = &emit_args.event;
       if let Some(handlers) = js_listeners.get(webview.label()).and_then(|s| s.get(event)) {
         let ids = handlers
           .iter()
@@ -293,22 +301,12 @@ impl Listeners {
     })
   }
 
-  pub(crate) fn emit_js<'a, R, I>(
-    &self,
-    webviews: I,
-    event: &str,
-    emit_args: &EmitArgs,
-  ) -> crate::Result<()>
+  pub(crate) fn emit_js<'a, R, I>(&self, webviews: I, emit_args: &EmitArgs) -> crate::Result<()>
   where
     R: Runtime,
     I: Iterator<Item = &'a Webview<R>>,
   {
-    self.emit_js_filter(
-      webviews,
-      event,
-      emit_args,
-      None::<&dyn Fn(&EventTarget) -> bool>,
-    )
+    self.emit_js_filter(webviews, emit_args, None::<&dyn Fn(&EventTarget) -> bool>)
   }
 }
 
@@ -339,33 +337,32 @@ mod test {
     fn listeners_check_key(e in "[a-z]+") {
       let listeners: Listeners = Default::default();
       // clone e as the key
-      let key = e.clone();
+      let key = crate::EventName::new(e.clone()).unwrap();
       // pass e and an dummy func into listen
-      listeners.listen(e, EventTarget::Any, event_fn);
+      listeners.listen(key, EventTarget::Any, event_fn);
 
       // lock mutex
       let l = listeners.inner.handlers.lock().unwrap();
 
       // check if the generated key is in the map
-      assert!(l.contains_key(&key));
+      assert!(l.contains_key(&e));
     }
 
     // check to see if listen inputs a handler function properly into the LISTENERS map.
     #[test]
     fn listeners_check_fn(e in "[a-z]+") {
-       let listeners: Listeners = Default::default();
-       // clone e as the key
-       let key = e.clone();
+      let listeners: Listeners = Default::default();
+      let key = crate::EventName::new(e.clone()).unwrap();
        // pass e and an dummy func into listen
-       listeners.listen(e, EventTarget::Any, event_fn);
+       listeners.listen(key, EventTarget::Any, event_fn);
 
        // lock mutex
        let mut l = listeners.inner.handlers.lock().unwrap();
 
        // check if l contains key
-       if l.contains_key(&key) {
+       if l.contains_key(&e) {
         // grab key if it exists
-        let handler = l.get_mut(&key);
+        let handler = l.get_mut(&e);
         // check to see if we get back a handler or not
         match handler {
           // pass on Some(handler)
@@ -378,22 +375,22 @@ mod test {
 
     // check to see if on_event properly grabs the stored function from listen.
     #[test]
-    fn check_on_event(key in "[a-z]+", d in "[a-z]+") {
+    fn check_on_event(e in "[a-z]+", d in "[a-z]+") {
       let listeners: Listeners = Default::default();
+      let key = crate::EventName::new(e.clone()).unwrap();
       // call listen with key and the event_fn dummy func
       listeners.listen(key.clone(), EventTarget::Any, event_fn);
       // call on event with key and d.
-      listeners.emit(EmitArgs {
-        event_name: key.clone(),
-        event: serde_json::to_string(&key).unwrap(),
+      listeners.emit(key.clone(), EmitArgs {
+        event: serde_json::to_string(&e).unwrap(),
         payload: serde_json::to_string(&d).unwrap()
       })?;
 
       // lock the mutex
       let l = listeners.inner.handlers.lock().unwrap();
 
       // assert that the key is contained in the listeners map
-      assert!(l.contains_key(&key));
+      assert!(l.contains_key(&e));
     }
   }
 }