support arbitrary crate

Author: rhysd

Cargo.lock

@@ -25,6 +25,10 @@ name = "minimal"
 name = "serde"
 required-features = ["serde"]
 
+[[example]]
+name = "arbitrary"
+required-features = ["arbitrary"]
+
 [[example]]
 name = "crossterm"
 required-features = ["crossterm"]
@@ -43,8 +47,10 @@ serde = ["dep:serde"]
 crossterm = ["dep:crossterm"]
 winit = ["dep:winit"]
 termwiz = ["dep:termwiz"]
+arbitrary = ["dep:arbitrary"]
 
 [dependencies]
+arbitrary = { version = "1.4.1", features = ["derive"], optional = true }
 bitflags = "2.8.0"
 crossterm = { version = "0.28.1", optional = true }
 serde = { version = "1.0.217", optional = true }
@@ -60,5 +66,5 @@ members = [".", "bench"]
 
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-pc-windows-msvc"]
-features = ["serde", "crossterm", "winit", "termwiz"]
+features = ["serde", "crossterm", "winit", "termwiz", "arbitrary"]
 rustdoc-args = ["--cfg", "docsrs"]

Cargo.toml

@@ -16,6 +16,7 @@ library can be buggy and have arbitrary breaking changes.**
   - [crossterm][] ([example](./examples/crossterm.rs))
   - [termwiz][] ([example](./examples/termwiz.rs))
   - [winit][] ([example](./examples/winit.rs))
+- Support structral fuzzing using [arbitrary][] optionally. ([example](./examples/arbitrary.rs))
 
 [API Documentation][api-doc]
 
@@ -91,5 +92,6 @@ This crate is licensed under [the MIT license](./LICENSE.txt).
 [crossterm]: https://crates.io/crates/crossterm
 [winit]: https://crates.io/crates/winit
 [termwiz]: https://crates.io/crates/termwiz
+[arbitrary]: https://crates.io/crates/arbitrary
 [api-doc]: https://docs.rs/keybinds/latest/keybinds/
 [toml]: https://crates.io/crates/toml

README.md

@@ -0,0 +1,27 @@
+use arbitrary::{Arbitrary, Result, Unstructured};
+use keybinds::{Key, KeyInput, KeySeq, Keybind, Keybinds, Mods};
+
+// Actions dispatched by key bindings.
+#[derive(Arbitrary, Debug)]
+enum Action {
+    Hello,
+    Goodbye,
+}
+
+fn main() -> Result<()> {
+    let raw_data = b"
+        Hello, an example for arbitrary crate support!
+        This is the random data input from fuzzer.
+    ";
+    let mut unstructured = Unstructured::new(raw_data);
+
+    // Generate arbitrary instances of types in keybinds crate
+    println!("{:?}", Key::arbitrary(&mut unstructured)?);
+    println!("{:?}", Mods::arbitrary(&mut unstructured)?);
+    println!("{:?}", KeyInput::arbitrary(&mut unstructured)?);
+    println!("{:?}", KeySeq::arbitrary(&mut unstructured)?);
+    println!("{:?}", Keybind::<Action>::arbitrary(&mut unstructured)?);
+    println!("{:?}", Keybinds::<Action>::arbitrary(&mut unstructured)?);
+
+    Ok(())
+}

examples/arbitrary.rs

@@ -0,0 +1,46 @@
+//! Support for [`arbitrary`] crate.
+//!
+//! This module provides [`Arbitrary`] trait support for several types in keybinds crate.
+//!
+//! ```
+//! use arbitrary::{Arbitrary, Result, Unstructured};
+//! use keybinds::{Key, KeyInput, KeySeq, Keybind, Keybinds, Mods};
+//!
+//! // Actions dispatched by key bindings.
+//! #[derive(Arbitrary, Debug)]
+//! enum Action {
+//!     Hello,
+//!     Goodbye,
+//! }
+//!
+//! let raw_data = b"
+//!     Hello, the document for arbitrary crate support!
+//!     This is the random data input from fuzzer.
+//! ";
+//! let mut unstructured = Unstructured::new(raw_data);
+//!
+//! // Generate arbitrary instances of types in keybinds crate
+//! let _ = Key::arbitrary(&mut unstructured).unwrap();
+//! let _ = Mods::arbitrary(&mut unstructured).unwrap();
+//! let _ = KeyInput::arbitrary(&mut unstructured).unwrap();
+//! let _ = KeySeq::arbitrary(&mut unstructured).unwrap();
+//! let _ = Keybind::<Action>::arbitrary(&mut unstructured).unwrap();
+//! let _ = Keybinds::<Action>::arbitrary(&mut unstructured).unwrap();
+//! ```
+use crate::Mods;
+use arbitrary::{Arbitrary, Result, Unstructured};
+
+// Note: We don't use bitflags crate's `arbitrary` feature because it is quite inefficient.
+// Almost all bit patterns are generated by `Unstructured` are incorrect and they cause
+// 'Incorrect format' error which means generating an arbitrary instance failed.
+impl Arbitrary<'_> for Mods {
+    fn arbitrary(u: &mut Unstructured<'_>) -> Result<Self> {
+        let mut mods = Self::NONE;
+        mods.set(Mods::CTRL, u.arbitrary()?);
+        mods.set(Mods::CMD, u.arbitrary()?);
+        mods.set(Mods::ALT, u.arbitrary()?);
+        mods.set(Mods::WIN, u.arbitrary()?);
+        mods.set(Mods::SHIFT, u.arbitrary()?);
+        Ok(mods)
+    }
+}

src/arbitrary.rs

@@ -4,8 +4,12 @@ use std::fmt;
 use std::slice;
 use std::str::FromStr;
 
+#[cfg(feature = "arbitrary")]
+use arbitrary::Arbitrary;
+
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
+#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
 pub enum Key {
     Char(char),
     Up,
@@ -248,6 +252,7 @@ impl fmt::Display for Mods {
 }
 
 #[derive(Clone, PartialEq, Eq, Hash, Debug)]
+#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
 pub struct KeyInput {
     key: Key,
     mods: Mods,
@@ -316,6 +321,7 @@ pub enum Match {
 }
 
 #[derive(Clone, Eq, Debug)]
+#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
 pub enum KeySeq {
     Multiple(Vec<KeyInput>),
     Single(KeyInput),

src/key.rs

@@ -2,7 +2,11 @@ use crate::{Key, KeyInput, KeySeq, Match, Result};
 use std::ops::Deref;
 use std::time::{Duration, Instant};
 
+#[cfg(feature = "arbitrary")]
+use arbitrary::Arbitrary;
+
 #[derive(Clone, PartialEq, Eq, Debug)]
+#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
 pub struct Keybind<A> {
     pub seq: KeySeq,
     pub action: A,
@@ -25,6 +29,7 @@ pub enum Found<'a, A> {
 }
 
 #[derive(Clone, PartialEq, Eq, Debug)]
+#[cfg_attr(feature = "arbitrary", derive(Arbitrary))]
 pub struct Keybinds<A>(Vec<Keybind<A>>);
 
 impl<A> Default for Keybinds<A> {

src/keybind.rs

@@ -10,6 +10,7 @@
 //!   - [crossterm][]
 //!   - [termwiz][]
 //!   - [winit][]
+//! - Support structral fuzzing using [arbitrary][] optionally.
 //!
 //! # Minimal example
 //!
@@ -66,6 +67,7 @@
 //! [crossterm]: https://crates.io/crates/crossterm
 //! [winit]: https://crates.io/crates/winit
 //! [termwiz]: https://crates.io/crates/termwiz
+//! [arbitrary]: https://crates.io/crates/arbitrary
 //! [examples]: https://github.com/rhysd/keybinds-rs/tree/main/examples
 //!
 #![doc = include_str!("../doc/binding_syntax.md")]
@@ -90,6 +92,9 @@ pub mod termwiz;
 #[cfg(feature = "winit")]
 pub mod winit;
 
+#[cfg(feature = "arbitrary")]
+pub mod arbitrary;
+
 pub use error::{Error, Result};
 pub use key::{Key, KeyInput, KeySeq, Match, Mods};
 pub use keybind::{Found, Keybind, KeybindDispatcher, Keybinds, DEFAULT_TIMEOUT};

src/lib.rs

@@ -1,7 +1,7 @@
 //! Support for [`serde`] crate.
 //!
-//! This module provides a `Deserialize` support for [`Keybinds`] to easily parse key bindings from
-//! a configuration file.
+//! This module provides a [`Deserialize`] trait support for [`Keybinds`] to easily parse key bindings
+//! from a configuration file.
 //!
 //! ```
 //! use serde::Deserialize;