Merge pull request #1 from chksum-rs/feature/async-traits

Support for async chksum calculation

.cargo/README.md

@@ -3,7 +3,7 @@
 [![GitHub](https://img.shields.io/badge/github-chksum--rs%2Fmd5-24292e?style=flat-square&logo=github "GitHub")](https://github.com/chksum-rs/md5)
 [![Build](https://img.shields.io/github/actions/workflow/status/chksum-rs/md5/rust.yml?branch=master&style=flat-square&logo=github "Build")](https://github.com/chksum-rs/md5/actions/workflows/rust.yml)
 [![docs.rs](https://img.shields.io/docsrs/chksum-md5?style=flat-square&logo=docsdotrs "docs.rs")](https://docs.rs/chksum-md5/)
-[![MSRV](https://img.shields.io/badge/MSRV-1.70.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/md5/blob/master/Cargo.toml)
+[![MSRV](https://img.shields.io/badge/MSRV-1.74.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/md5/blob/master/Cargo.toml)
 [![deps.rs](https://deps.rs/crate/chksum-md5/0.0.0/status.svg?style=flat-square "deps.rs")](https://deps.rs/crate/chksum-md5/0.0.0)
 [![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg?style=flat-square "unsafe forbidden")](https://github.com/rust-secure-code/safety-dance)
 [![LICENSE](https://img.shields.io/github/license/chksum-rs/md5?style=flat-square "LICENSE")](https://github.com/chksum-rs/md5/blob/master/LICENSE)
@@ -27,7 +27,7 @@ cargo add chksum-md5
 
 ## Usage
 
-Use the `chksum` function to calcualate digest of file, directory and so on.
+Use the `chksum` function to calculate digest of file, directory and so on.
 
 ```rust
 use chksum_md5 as md5;

.github/workflows/rust.yml

@@ -58,7 +58,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        toolchain: [1.70.0, stable, nightly]
+        toolchain: [1.74.0, stable, nightly]
     name: "Build and test (OS: Linux, Toolchain: ${{ matrix.toolchain }})"
     steps:
       - name: Repository checkout
@@ -87,7 +87,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        toolchain: [1.70.0, stable, nightly]
+        toolchain: [1.74.0, stable, nightly]
     name: "Build and test (OS: MacOS, Toolchain: ${{ matrix.toolchain }})"
     steps:
       - name: Repository checkout
@@ -116,7 +116,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        toolchain: [1.70.0, stable, nightly]
+        toolchain: [1.74.0, stable, nightly]
     name: "Build and test (OS: Windows, Toolchain: ${{ matrix.toolchain }})"
     steps:
       - name: Repository checkout

CHANGELOG.md

@@ -5,10 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Added async support for Tokio runtime.
+
+### Changed
+
+- Updated MSRV to `1.74.0`.
+
 ## [0.0.0] - 2023-12-21
 
 ### Added
 
 - Initial release.
 
+[Unreleased]: https://github.com/chksum-rs/md5/compare/v0.0.0...HEAD
 [0.0.0]: https://github.com/chksum-rs/md5/releases/tag/v0.0.0

Cargo.toml

@@ -3,7 +3,7 @@ name = "chksum-md5"
 version = "0.0.0"
 authors = ["Konrad Goławski <konrad@golawski.it>"]
 edition = "2021"
-rust-version = "1.70.0"
+rust-version = "1.74.0"
 description = "An implementation of the MD5 hash function with a straightforward interface for computing digests of bytes, files, directories, and more."
 readme = ".cargo/README.md"
 repository = "https://github.com/chksum-rs/md5"
@@ -16,16 +16,21 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
-chksum-core = "0.0.0"
+chksum-core = "0.1.0"
 chksum-hash-md5 = "0.0.0"
-chksum-reader = { version = "0.0.0", optional = true }
-chksum-writer = { version = "0.0.0", optional = true }
+chksum-reader = { version = "0.1.0", optional = true }
+chksum-writer = { version = "0.1.0", optional = true }
+tokio = { version = "1.37.0", features = ["io-util"], optional = true }
 
 [dev-dependencies]
 assert_fs = { version = "1.0.13", features = ["color-auto"] }
 thiserror = "1.0.51"
+tokio = { version = "1.37.0", features = ["macros", "rt", "rt-multi-thread"] }
 
 [features]
 default = []
 reader = ["chksum-reader"]
 writer = ["chksum-writer"]
+
+# async runtimes
+async-runtime-tokio = ["chksum-core/async-runtime-tokio", "chksum-reader?/async-runtime-tokio", "chksum-writer?/async-runtime-tokio", "tokio"]

README.md

@@ -3,7 +3,7 @@
 [![crates.io](https://img.shields.io/crates/v/chksum-md5?style=flat-square&logo=rust "crates.io")](https://crates.io/crates/chksum-md5)
 [![Build](https://img.shields.io/github/actions/workflow/status/chksum-rs/md5/rust.yml?branch=master&style=flat-square&logo=github "Build")](https://github.com/chksum-rs/md5/actions/workflows/rust.yml)
 [![docs.rs](https://img.shields.io/docsrs/chksum-md5?style=flat-square&logo=docsdotrs "docs.rs")](https://docs.rs/chksum-md5/)
-[![MSRV](https://img.shields.io/badge/MSRV-1.70.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/md5/blob/master/Cargo.toml)
+[![MSRV](https://img.shields.io/badge/MSRV-1.74.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/md5/blob/master/Cargo.toml)
 [![deps.rs](https://deps.rs/crate/chksum-md5/0.0.0/status.svg?style=flat-square "deps.rs")](https://deps.rs/crate/chksum-md5/0.0.0)
 [![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg?style=flat-square "unsafe forbidden")](https://github.com/rust-secure-code/safety-dance)
 [![LICENSE](https://img.shields.io/github/license/chksum-rs/md5?style=flat-square "LICENSE")](https://github.com/chksum-rs/md5/blob/master/LICENSE)
@@ -27,7 +27,7 @@ cargo add chksum-md5
 
 ## Usage
 
-Use the `chksum` function to calcualate digest of file, directory and so on.
+Use the `chksum` function to calculate digest of file, directory and so on.
 
 ```rust
 use chksum_md5 as md5;

src/lib.rs

@@ -19,7 +19,7 @@
 //!
 //! # Usage
 //!
-//! Use the [`chksum`] function to calcualate digest of file, directory and so on.
+//! Use the [`chksum`] function to calculate digest of file, directory and so on.
 //!
 //! ```rust
 //! # use std::path::Path;
@@ -39,6 +39,30 @@
 //! # }
 //! ```
 //!
+//! ## Asynchronous Runtime
+//!
+//! Use the [`async_chksum`] function to calculate digest of file, directory and so on.
+//!
+//! ```rust
+//! # #[cfg(feature = "async-runtime-tokio")]
+//! # {
+//! # use std::path::Path;
+//! # use chksum_md5::Result;
+//! use chksum_md5 as md5;
+//! use tokio::fs::File;
+//!
+//! # async fn wrapper(path: &Path) -> Result<()> {
+//! let file = File::open(path).await?;
+//! let digest = md5::async_chksum(file).await?;
+//! assert_eq!(
+//!     digest.to_hex_lowercase(),
+//!     "5c71dbb287630d65ca93764c34d9aa0d"
+//! );
+//! # Ok(())
+//! # }
+//! # }
+//! ```
+//!
 //! # Input Types
 //!
 //! ## Bytes
@@ -231,6 +255,12 @@
 //! cargo add chksum-md5 --features reader,writer
 //! ```
 //!
+//! ## Asynchronous Runtime
+//!
+//! * `async-runtime-tokio`: Enables async interface for Tokio runtime.
+//!
+//! By default, neither of these features is enabled.
+//!
 //! # Disclaimer
 //!
 //! The MD5 hash function should be used only for backward compatibility due to security issues.
@@ -252,14 +282,23 @@ pub mod writer;
 use std::fmt::{self, Display, Formatter, LowerHex, UpperHex};
 
 use chksum_core as core;
+#[cfg(feature = "async-runtime-tokio")]
+#[doc(no_inline)]
+pub use chksum_core::AsyncChksumable;
 #[doc(no_inline)]
 pub use chksum_core::{Chksumable, Error, Hash, Hashable, Result};
 #[doc(no_inline)]
 pub use chksum_hash_md5 as hash;
 
+#[cfg(all(feature = "reader", feature = "async-runtime-tokio"))]
+#[doc(inline)]
+pub use crate::reader::AsyncReader;
 #[cfg(feature = "reader")]
 #[doc(inline)]
 pub use crate::reader::Reader;
+#[cfg(all(feature = "writer", feature = "async-runtime-tokio"))]
+#[doc(inline)]
+pub use crate::writer::AsyncWriter;
 #[cfg(feature = "writer")]
 #[doc(inline)]
 pub use crate::writer::Writer;
@@ -341,6 +380,28 @@ pub fn chksum(data: impl core::Chksumable) -> Result<Digest> {
     core::chksum::<MD5>(data)
 }
 
+/// Computes the hash of the given input.
+///
+/// # Example
+///
+/// ```rust
+/// use chksum_md5 as md5;
+///
+/// # async fn wrapper() {
+/// let data = b"example data";
+/// if let Ok(digest) = md5::async_chksum(data).await {
+///     assert_eq!(
+///         digest.to_hex_lowercase(),
+///         "5c71dbb287630d65ca93764c34d9aa0d"
+///     );
+/// }
+/// # }
+/// ```
+#[cfg(feature = "async-runtime-tokio")]
+pub async fn async_chksum(data: impl core::AsyncChksumable) -> Result<Digest> {
+    core::async_chksum::<MD5>(data).await
+}
+
 /// The MD5 hash instance.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct MD5 {

src/reader.rs

@@ -47,24 +47,36 @@
 use std::io::Read;
 
 use chksum_reader as reader;
+#[cfg(feature = "async-runtime-tokio")]
+use tokio::io::AsyncRead;
 
 use crate::MD5;
 
 /// A specialized [`Reader`](reader::Reader) type with the [`MD5`] hash algorithm.
 pub type Reader<R> = reader::Reader<R, MD5>;
 
+#[cfg(feature = "async-runtime-tokio")]
+/// A specialized [`AsyncReader`](reader::AsyncReader) type with the [`MD5`] hash algorithm.
+pub type AsyncReader<R> = reader::AsyncReader<R, MD5>;
+
 /// Creates new [`Reader`].
-pub fn new<R>(inner: R) -> Reader<R>
-where
-    R: Read,
-{
+pub fn new(inner: impl Read) -> Reader<impl Read> {
     reader::new(inner)
 }
 
 /// Creates new [`Reader`] with provided hash.
-pub fn with_hash<R>(inner: R, hash: MD5) -> Reader<R>
-where
-    R: Read,
-{
+pub fn with_hash(inner: impl Read, hash: MD5) -> Reader<impl Read> {
     reader::with_hash(inner, hash)
 }
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncReader`].
+pub fn async_new(inner: impl AsyncRead) -> AsyncReader<impl AsyncRead> {
+    reader::async_new(inner)
+}
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncReader`] with provided hash.
+pub fn async_with_hash(inner: impl AsyncRead, hash: MD5) -> AsyncReader<impl AsyncRead> {
+    reader::async_with_hash(inner, hash)
+}

src/writer.rs

@@ -45,12 +45,18 @@
 use std::io::Write;
 
 use chksum_writer as writer;
+#[cfg(feature = "async-runtime-tokio")]
+use tokio::io::AsyncWrite;
 
 use crate::MD5;
 
 /// A specialized [`Writer`](writer::Writer) type with the [`MD5`] hash algorithm.
 pub type Writer<W> = writer::Writer<W, MD5>;
 
+#[cfg(feature = "async-runtime-tokio")]
+/// A specialized [`AsyncWriter`](writer::AsyncWriter) type with the [`MD5`] hash algorithm.
+pub type AsyncWriter<R> = writer::AsyncWriter<R, MD5>;
+
 /// Creates new [`Writer`].
 pub fn new(inner: impl Write) -> Writer<impl Write> {
     writer::new(inner)
@@ -60,3 +66,15 @@ pub fn new(inner: impl Write) -> Writer<impl Write> {
 pub fn with_hash(inner: impl Write, hash: MD5) -> Writer<impl Write> {
     writer::with_hash(inner, hash)
 }
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncWriter`].
+pub fn async_new(inner: impl AsyncWrite) -> AsyncWriter<impl AsyncWrite> {
+    writer::async_new(inner)
+}
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncWriter`] with provided hash.
+pub fn async_with_hash(inner: impl AsyncWrite, hash: MD5) -> AsyncWriter<impl AsyncWrite> {
+    writer::async_with_hash(inner, hash)
+}