From c8ddd4e15785de1a98945e7cb367edd4fe8759c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Florkiewicz?= Date: Tue, 12 Mar 2024 23:24:37 +0100 Subject: [PATCH] chore: Add doc requirement to CI, add missing docs (#28) --- .github/workflows/ci.yml | 10 +++++++++- examples/{client.rs => node.rs} | 23 +++++++++++++++++++++++ src/lib.rs | 24 ++++++++++++++++++++++-- src/message.rs | 3 --- src/multihasher.rs | 13 +++++++++++++ src/utils.rs | 2 ++ 6 files changed, 69 insertions(+), 6 deletions(-) rename examples/{client.rs => node.rs} (81%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5c67eba..0240744 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,8 +12,16 @@ jobs: steps: - uses: actions/checkout@v1 - name: Run clippy - run: cargo clippy --all --all-targets -- -D warnings + run: cargo clippy --all --all-targets -- -D warnings -D missing-docs + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Run rustdoc check + env: + RUSTDOCFLAGS: -D warnings + run: cargo doc fmt: runs-on: ubuntu-latest diff --git a/examples/client.rs b/examples/node.rs similarity index 81% rename from examples/client.rs rename to examples/node.rs index 94ac03e..997f868 100644 --- a/examples/client.rs +++ b/examples/node.rs @@ -1,3 +1,26 @@ +//! Example bitswap node implementation allowing with basic interaction over cli +//! +//! It shows off example way to setup beetswap behaviour with a libp2p swarm and then either +//! connecting to another node and/or listening for incoming connections. In both cases both +//! the server and the client parts of the bitswap are running. +//! +//! Example invocations: +//! +//! Listen on port `9898` and serve single block with contents "12345" +//! ```sh +//! cargo run --example=node -- -l 9898 --preload-blockstore-string 12345 +//! ``` +//! +//! Connect to `10.0.0.101` on port `9898` and ask for CID `bafkreic...` (it's a CID of "12345" string above). You can specify multiple CIDs at once. +//! ```sh +//! cargo run --example=node -- -p /ip4/10.0.0.101/tcp/9898 bafkreiczsrdrvoybcevpzqmblh3my5fu6ui3tgag3jm3hsxvvhaxhswpyu +//! ``` +//! +//! Listen on port `9898` and requests provided CID from them until it gets correct response with +//! data +//! ```sh +//! cargo run --example=node -- -l 9898 bafkreiczsrdrvoybcevpzqmblh3my5fu6ui3tgag3jm3hsxvvhaxhswpyu +//! ``` use std::collections::HashMap; use std::time::Duration; diff --git a/src/lib.rs b/src/lib.rs index ca3087f..4bdcafb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,6 @@ +#![cfg_attr(docs_rs, feature(doc_cfg))] +#![doc = include_str!("../README.md")] + use std::sync::{Arc, Mutex}; use std::task::{Context, Poll}; @@ -52,19 +55,35 @@ where /// Event produced by [`Behaviour`]. #[derive(Debug)] pub enum Event { - GetQueryResponse { query_id: QueryId, data: Vec }, - GetQueryError { query_id: QueryId, error: Error }, + /// Requested block has been successfuly retrieved + GetQueryResponse { + /// Id of the query, returned by [`Behaviour::get`] + query_id: QueryId, + /// Data of the requested block + data: Vec, + }, + /// Error occurred while fetching block + GetQueryError { + /// Id of the query, returned by [`Behaviour::get`] + query_id: QueryId, + /// Error that occurred when getting the data + error: Error, + }, } /// Representation of all the errors that can occur when interacting with this crate. #[derive(Debug, thiserror::Error)] pub enum Error { + /// Encountered CID with multihash longer than max set when creating the [`Behaviour`] #[error("Invalid multihash size")] InvalidMultihashSize, + /// Invalid protocol prefix provided when building `Behaviour`, see + /// [`BehaviourBuilder::protocol_prefix`] #[error("Invalid protocol prefix: {0}")] InvalidProtocolPrefix(String), + /// Error received when interacting with blockstore #[error("Blockstore error: {0}")] Blockstore(#[from] BlockstoreError), } @@ -212,6 +231,7 @@ pub enum ToHandlerEvent { QueueOutgoingMessages(Vec<(Vec, Vec)>), } +#[doc(hidden)] pub enum StreamRequester { Client, Server, diff --git a/src/message.rs b/src/message.rs index 97774f5..deb40f9 100644 --- a/src/message.rs +++ b/src/message.rs @@ -13,9 +13,6 @@ pub(crate) const MAX_MESSAGE_SIZE: usize = 4 * 1024 * 1024; pub(crate) struct Codec; -#[derive(Debug, thiserror::Error)] -pub(crate) enum CodecError {} - impl Encoder for Codec { type Item<'a> = &'a Message; type Error = io::Error; diff --git a/src/multihasher.rs b/src/multihasher.rs index d6499e6..78d3ae3 100644 --- a/src/multihasher.rs +++ b/src/multihasher.rs @@ -1,3 +1,13 @@ +//! Module responsible for calculating hashes for data received +//! +//! For interoperability `StandardMultihasher` is registered by default, which uses hashes +//! provided by [`multihash_codetable::Code`]. If you need to register your own multihashes, +//! you can implement [`Multihasher`] trait and then register the struct with +//! [`BehaviourBuilder::register_multihasher`] when creating the behaviour. +//! +//! [`BehaviourBuilder::register_multihasher`]: +//! crate::builder::BehaviourBuilder::register_multihasher + use std::collections::VecDeque; use std::fmt::{self, Display}; @@ -40,10 +50,13 @@ pub enum MultihasherError { } impl MultihasherError { + /// Custom error, causes block to be ignored pub fn custom(e: impl Display) -> MultihasherError { MultihasherError::Custom(e.to_string()) } + /// Custom fatal error, causes block to be ignored and stream from which it was received to + /// close pub fn custom_fatal(e: impl Display) -> MultihasherError { MultihasherError::CustomFatal(e.to_string()) } diff --git a/src/utils.rs b/src/utils.rs index 95f1cba..569bab9 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -1,3 +1,5 @@ +//! Helpers used in and provided by the crate + use cid::CidGeneric; use libp2p_core::multihash::Multihash; use libp2p_swarm::StreamProtocol;