Add docs and conveniences like Client::requeue_by_ids

src/proto/client/mutation.rs

@@ -1,13 +1,16 @@
 use crate::{
     proto::single::{MutationAction, MutationType},
-    Client, Error, MutationFilter, MutationTarget,
+    Client, Error, JobId, MutationFilter, MutationTarget,
 };
 use std::borrow::Borrow;
 
 impl Client {
     /// Re-enqueue the jobs.
     ///
-    /// This will immediately move the jobs from the targeted set (see [`MutationTarget`])
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    ///
+    /// This method will immediately move the jobs from the targeted set (see [`MutationTarget`])
     /// to their queues. This will apply to the jobs satisfying the [`filter`](crate::MutationFilter).
     ///
     /// ```no_run
@@ -29,8 +32,28 @@ impl Client {
             .await
     }
 
+    /// Re-enqueue the jobs with the given ids.
+    /// 
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    /// 
+    /// Similar to [`Client::requeue`], but will create a filter (see [`MutationFilter`])
+    /// with the gived `jids` for you.
+    pub async fn requeue_by_ids<'a>(
+        &mut self,
+        target: MutationTarget,
+        jids: &'_ [&'_ JobId],
+    ) -> Result<(), Error> {
+        let filter = MutationFilter::builder().jids(jids).build();
+        self.mutate(MutationType::Requeue, target, Some(&filter))
+            .await
+    }
+
     /// Discard the jobs.
     ///
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    ///
     /// Will throw the jobs away without any chance for re-scheduling
     /// on the server side. If you want to still be able to process the jobs,
     /// use [`Client::kill`] instead.
@@ -54,8 +77,28 @@ impl Client {
             .await
     }
 
+    /// Discard the jobs with the given ids.
+    /// 
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    /// 
+    /// Similar to [`Client::discard`], but will create a filter (see [`MutationFilter`])
+    /// with the gived `jids` for you.
+    pub async fn discard_by_ids<'a>(
+        &mut self,
+        target: MutationTarget,
+        jids: &'_ [&'_ JobId],
+    ) -> Result<(), Error> {
+        let filter = MutationFilter::builder().jids(jids).build();
+        self.mutate(MutationType::Discard, target, Some(&filter))
+            .await
+    }
+
     /// Kil the jobs.
     ///
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    ///
     /// Moves the jobs from the target structure to the `dead` set, meaning Faktory
     /// will not touch it further unless you ask it to do so. You then can, for example,
     /// manually process those jobs via the Web UI or send another mutation command
@@ -80,8 +123,27 @@ impl Client {
             .await
     }
 
+    /// Kill the jobs with the given ids.
+    /// 
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    /// 
+    /// Similar to [`Client::kill`], but will create a filter (see [`MutationFilter`])
+    /// with the gived `jids` for you.
+    pub async fn kill_by_ids<'a>(
+        &mut self,
+        target: MutationTarget,
+        jids: &'_ [&'_ JobId],
+    ) -> Result<(), Error> {
+        let filter = MutationFilter::builder().jids(jids).build();
+        self.mutate(MutationType::Kill, target, Some(&filter)).await
+    }
+
     /// Purge the targeted structure.
     ///
+    /// ***Warning!*** The `MUTATE` API is not supposed to be used as part of application logic,
+    /// you will want to use it for administration purposes only.
+    ///
     /// Will have the same effect as [`Client::discard`] with an empty [`MutationFilter`],
     /// but is special cased by Faktory and so is performed faster. Can be though of as
     /// `TRUNCATE tablename` operation in the SQL world versus `DELETE FROM tablename`.

src/proto/single/mutation.rs

@@ -2,7 +2,7 @@ use crate::JobId;
 use derive_builder::Builder;
 
 #[cfg(doc)]
-use crate::Job;
+use crate::{Client, Job};
 
 /// Mutation target set.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
@@ -20,7 +20,17 @@ pub enum MutationTarget {
     Dead,
 }
 
-/// Filter to help narrow down the mutation target.
+// As of Faktory v1.9.2, not all the fields on the filter
+// will be taken into account, rather EITHER `jids` OR optional `kind`
+// plus optional `pattern`.
+// See: https://github.com/contribsys/faktory/issues/489
+//
+/// A filter to help narrow down the mutation target.
+///
+/// As of Faktory version 1.9.2, if [`MutationFilter::pattern`] and/or [`MutationFilter::kind`]
+/// is specified, the values in [`MutationFilter::jids`] will not be taken into account by the
+/// server. If you want to filter by `jids`, make sure to leave other fields of the filter empty
+/// or use dedicated methods like [`Client::requeue_by_ids`].
 ///
 /// Example usage:
 /// ```no_run