docs: Improve the docs
Signed-off-by: Awiteb <a@4rs.nl>
This commit is contained in:
parent
a294ebfe96
commit
0f83f29c85
7 changed files with 28 additions and 8 deletions
|
@ -26,6 +26,10 @@ either = { version = "1.13.0", default-features = false }
|
||||||
cacache-storage = ["dep:cacache"]
|
cacache-storage = ["dep:cacache"]
|
||||||
simple_generator = ["dep:captcha"]
|
simple_generator = ["dep:captcha"]
|
||||||
|
|
||||||
|
[package.metadata.docs.rs]
|
||||||
|
all-features = true
|
||||||
|
rustdoc-args = ["--cfg", "docsrs"]
|
||||||
|
|
||||||
[dev-dependencies]
|
[dev-dependencies]
|
||||||
tempfile = "3.9"
|
tempfile = "3.9"
|
||||||
tokio = { version = "1.35", features = ["macros", "rt-multi-thread"] }
|
tokio = { version = "1.35", features = ["macros", "rt-multi-thread"] }
|
||||||
|
|
|
@ -12,7 +12,8 @@
|
||||||
#[cfg(feature = "simple_generator")]
|
#[cfg(feature = "simple_generator")]
|
||||||
mod simple_generator;
|
mod simple_generator;
|
||||||
|
|
||||||
#[cfg(feature = "simple_generator")]
|
#[cfg_attr(docsrs, doc(cfg(feature = "simple-generator")))]
|
||||||
|
#[cfg(feature = "simple-generator")]
|
||||||
pub use simple_generator::*;
|
pub use simple_generator::*;
|
||||||
|
|
||||||
/// Captcha generator, used to generate a new captcha image and answer.
|
/// Captcha generator, used to generate a new captcha image and answer.
|
||||||
|
|
|
@ -76,7 +76,7 @@ impl Display for SimpleGeneratorError {
|
||||||
|
|
||||||
impl std::error::Error for SimpleGeneratorError {}
|
impl std::error::Error for SimpleGeneratorError {}
|
||||||
|
|
||||||
/// The simple captcha generator
|
/// A simple captcha generator, using the [`captcha`](https://crates.io/crates/captcha) crate.
|
||||||
pub struct SimpleGenerator {
|
pub struct SimpleGenerator {
|
||||||
name: CaptchaName,
|
name: CaptchaName,
|
||||||
difficulty: CaptchaDifficulty,
|
difficulty: CaptchaDifficulty,
|
||||||
|
@ -93,8 +93,6 @@ impl CaptchaGenerator for SimpleGenerator {
|
||||||
type Error = SimpleGeneratorError;
|
type Error = SimpleGeneratorError;
|
||||||
|
|
||||||
/// The returned captcha image is 220x110 pixels in png format.
|
/// The returned captcha image is 220x110 pixels in png format.
|
||||||
///
|
|
||||||
/// For more information about the captcha name and difficulty, see the [`README.md`](https://git.4rs.nl/awiteb/salvo-captcha/#captcha-name-and-difficulty).
|
|
||||||
async fn new_captcha(&self) -> Result<(String, Vec<u8>), Self::Error> {
|
async fn new_captcha(&self) -> Result<(String, Vec<u8>), Self::Error> {
|
||||||
let Some((captcha_answer, captcha_image)) =
|
let Some((captcha_answer, captcha_image)) =
|
||||||
captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple()
|
captcha::by_name(self.difficulty.into(), self.name.into()).as_tuple()
|
||||||
|
|
17
src/lib.rs
17
src/lib.rs
|
@ -13,6 +13,7 @@
|
||||||
#![deny(warnings)]
|
#![deny(warnings)]
|
||||||
#![deny(missing_docs)]
|
#![deny(missing_docs)]
|
||||||
#![deny(clippy::print_stdout)]
|
#![deny(clippy::print_stdout)]
|
||||||
|
#![cfg_attr(docsrs, feature(doc_cfg))]
|
||||||
|
|
||||||
mod captcha_gen;
|
mod captcha_gen;
|
||||||
mod finder;
|
mod finder;
|
||||||
|
@ -29,7 +30,21 @@ pub use {captcha_gen::*, finder::*, storage::*};
|
||||||
/// Key used to insert the captcha state into the depot
|
/// Key used to insert the captcha state into the depot
|
||||||
pub const CAPTCHA_STATE_KEY: &str = "::salvo_captcha::captcha_state";
|
pub const CAPTCHA_STATE_KEY: &str = "::salvo_captcha::captcha_state";
|
||||||
|
|
||||||
/// Captcha struct, contains the token and answer.
|
/// The captcha middleware
|
||||||
|
///
|
||||||
|
/// The captcha middleware is used to check the captcha token and answer from
|
||||||
|
/// the request. You can use the [`CaptchaBuilder`] to create a new captcha
|
||||||
|
/// middleware.
|
||||||
|
///
|
||||||
|
/// ## Note
|
||||||
|
/// You need to generate the captcha token and answer before, then the captcha
|
||||||
|
/// middleware will check the token and answer from the request using the finder
|
||||||
|
/// and storage you provided. The captcha middleware will insert the
|
||||||
|
/// [`CaptchaState`] into the depot, you can get the captcha state from the
|
||||||
|
/// depot using the [`CaptchaDepotExt::get_captcha_state`] trait, which is
|
||||||
|
/// implemented for the [`Depot`].
|
||||||
|
///
|
||||||
|
/// Check the [`examples`](https://git.4rs.nl/awiteb/salvo-captcha/src/branch/master/examples) for more information.
|
||||||
#[non_exhaustive]
|
#[non_exhaustive]
|
||||||
pub struct Captcha<S, F>
|
pub struct Captcha<S, F>
|
||||||
where
|
where
|
||||||
|
|
|
@ -16,7 +16,7 @@ use std::{
|
||||||
|
|
||||||
use crate::CaptchaStorage;
|
use crate::CaptchaStorage;
|
||||||
|
|
||||||
/// The [`cacache`] storage.
|
/// The [`cacache`] storage. Store the token and answer in the disk.
|
||||||
///
|
///
|
||||||
/// [`cacache`]: https://github.com/zkat/cacache-rs
|
/// [`cacache`]: https://github.com/zkat/cacache-rs
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
|
@ -26,7 +26,7 @@ pub struct CacacheStorage {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl CacacheStorage {
|
impl CacacheStorage {
|
||||||
/// Create a new CacacheStorage
|
/// Create a new [`CacacheStorage`] instance with the cache directory.
|
||||||
pub fn new(cache_dir: impl Into<PathBuf>) -> Self {
|
pub fn new(cache_dir: impl Into<PathBuf>) -> Self {
|
||||||
Self {
|
Self {
|
||||||
cache_dir: cache_dir.into(),
|
cache_dir: cache_dir.into(),
|
||||||
|
|
|
@ -20,7 +20,7 @@ use tokio::sync::RwLock;
|
||||||
|
|
||||||
use crate::CaptchaStorage;
|
use crate::CaptchaStorage;
|
||||||
|
|
||||||
/// Captcha storage implementation using an in-memory HashMap.
|
/// Captcha storage implementation using an in-memory [HashMap].
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub struct MemoryStorage(RwLock<HashMap<String, (u64, String)>>);
|
pub struct MemoryStorage(RwLock<HashMap<String, (u64, String)>>);
|
||||||
|
|
||||||
|
@ -32,6 +32,7 @@ impl MemoryStorage {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl CaptchaStorage for MemoryStorage {
|
impl CaptchaStorage for MemoryStorage {
|
||||||
|
/// This storage does not return any error.
|
||||||
type Error = Infallible;
|
type Error = Infallible;
|
||||||
|
|
||||||
async fn store_answer(&self, answer: String) -> Result<String, Self::Error> {
|
async fn store_answer(&self, answer: String) -> Result<String, Self::Error> {
|
||||||
|
|
|
@ -15,6 +15,7 @@ use std::{sync::Arc, time::Duration};
|
||||||
mod cacache_storage;
|
mod cacache_storage;
|
||||||
mod memory_storage;
|
mod memory_storage;
|
||||||
|
|
||||||
|
#[cfg_attr(docsrs, doc(cfg(feature = "cacache-storage")))]
|
||||||
#[cfg(feature = "cacache-storage")]
|
#[cfg(feature = "cacache-storage")]
|
||||||
pub use cacache_storage::*;
|
pub use cacache_storage::*;
|
||||||
pub use memory_storage::*;
|
pub use memory_storage::*;
|
||||||
|
|
Loading…
Reference in a new issue