From 4a1ec068fc13393e249853403085be6958a807a4 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Fri, 11 Nov 2022 21:04:18 +0000 Subject: [PATCH] improved docs --- azalea-client/src/client.rs | 13 ++++++++----- azalea-client/src/lib.rs | 2 +- azalea-protocol/src/connect.rs | 5 +++-- azalea-protocol/src/lib.rs | 11 ++--------- azalea-protocol/src/read.rs | 10 ++++++++++ azalea-protocol/src/resolver.rs | 2 ++ azalea-protocol/src/write.rs | 9 ++++++--- 7 files changed, 32 insertions(+), 20 deletions(-) diff --git a/azalea-client/src/client.rs b/azalea-client/src/client.rs index 8393a977..3d6c8e05 100644 --- a/azalea-client/src/client.rs +++ b/azalea-client/src/client.rs @@ -135,7 +135,9 @@ pub enum HandleError { impl Client { /// Connect to a Minecraft server. /// - /// To change the render distance and other settings, use [`Client::set_client_information`]. + /// To change the render distance and other settings, use + /// [`Client::set_client_information`]. To watch for events like packets + /// sent by the server, use the `rx` variable this function returns. /// /// # Examples /// @@ -145,7 +147,7 @@ impl Client { /// #[tokio::main] /// async fn main() -> Box { /// let account = Account::offline("bot"); - /// let client = Client::join(&account, "localhost").await?; + /// let (client, rx) = Client::join(&account, "localhost").await?; /// client.chat("Hello, world!").await?; /// client.shutdown().await?; /// } @@ -583,9 +585,10 @@ impl Client { if let Err(e) = client .dimension .lock() - .replace_with_packet_data(&pos, &mut Cursor::new(&p.chunk_data.data)) { - error!("Couldn't set chunk data: {}", e); - } + .replace_with_packet_data(&pos, &mut Cursor::new(&p.chunk_data.data)) + { + error!("Couldn't set chunk data: {}", e); + } } ClientboundGamePacket::LightUpdate(_p) => { // debug!("Got light update packet {:?}", p); diff --git a/azalea-client/src/lib.rs b/azalea-client/src/lib.rs index c32bd212..7a76e103 100755 --- a/azalea-client/src/lib.rs +++ b/azalea-client/src/lib.rs @@ -1,5 +1,5 @@ //! Significantly abstract [`azalea_protocol`] so it's actually useable for -//! real clients. If you want to make bots, however, you should use the +//! real clients. If you want to make bots, you should use the //! [`azalea`] crate instead. //! //! [`azalea_protocol`]: https://crates.io/crates/azalea-protocol diff --git a/azalea-protocol/src/connect.rs b/azalea-protocol/src/connect.rs index f67d0e4a..d14d3424 100644 --- a/azalea-protocol/src/connect.rs +++ b/azalea-protocol/src/connect.rs @@ -1,4 +1,4 @@ -//! Create connections that communicate with a remote server or client. +//! Connect to remote servers/clients. use crate::packets::game::{ClientboundGamePacket, ServerboundGamePacket}; use crate::packets::handshake::{ClientboundHandshakePacket, ServerboundHandshakePacket}; @@ -11,7 +11,7 @@ use crate::write::write_packet; use azalea_auth::sessionserver::SessionServerError; use azalea_crypto::{Aes128CfbDec, Aes128CfbEnc}; use bytes::BytesMut; -use log::{info, error}; +use log::{error, info}; use std::fmt::Debug; use std::marker::PhantomData; use std::net::SocketAddr; @@ -116,6 +116,7 @@ impl ReadConnection where R: ProtocolPacket + Debug, { + /// Read a packet from the stream. pub async fn read(&mut self) -> Result { read_packet::( &mut self.read_stream, diff --git a/azalea-protocol/src/lib.rs b/azalea-protocol/src/lib.rs index 84306142..0fae75b1 100755 --- a/azalea-protocol/src/lib.rs +++ b/azalea-protocol/src/lib.rs @@ -6,6 +6,8 @@ //! //! [`azalea`]: https://crates.io/crates/azalea //! [`azalea_client`]: https://crates.io/crates/azalea-client +//! +//! See [`crate::connect::Connection`] for an example. // these two are necessary for thiserror backtraces #![feature(error_generic_member_access)] @@ -57,15 +59,6 @@ impl<'a> TryFrom<&'a str> for ServerAddress { } } -#[cfg(feature = "connecting")] -pub async fn connect(address: ServerAddress) -> Result<(), Box> { - use log::debug; - - let resolved_address = resolver::resolve_address(&address).await; - debug!("Resolved address: {:?}", resolved_address); - Ok(()) -} - #[cfg(test)] mod tests { use std::io::Cursor; diff --git a/azalea-protocol/src/read.rs b/azalea-protocol/src/read.rs index 8d8bc731..a459d3bb 100644 --- a/azalea-protocol/src/read.rs +++ b/azalea-protocol/src/read.rs @@ -1,3 +1,5 @@ +//! Read packets from a stream. + use crate::packets::ProtocolPacket; use azalea_buf::BufReadError; use azalea_buf::McBufVarReadable; @@ -157,6 +159,8 @@ pub enum DecompressionError { AboveCompressionThreshold { size: u32, maximum: u32 }, } +/// Get the decompressed bytes from a packet. It must have been decrypted +/// first. fn compression_decoder( stream: &mut Cursor<&[u8]>, compression_threshold: u32, @@ -192,6 +196,12 @@ fn compression_decoder( Ok(decoded_buf) } +/// Read a single packet from a stream. +/// +/// The buffer is required because servers may send multiple packets in the +/// same frame, so we need to store the packet data that's left to read. +/// +/// The current protocol state must be passed as a generic. pub async fn read_packet<'a, P: ProtocolPacket + Debug, R>( stream: &'a mut R, buffer: &mut BytesMut, diff --git a/azalea-protocol/src/resolver.rs b/azalea-protocol/src/resolver.rs index b3455a59..26baf2f9 100755 --- a/azalea-protocol/src/resolver.rs +++ b/azalea-protocol/src/resolver.rs @@ -1,3 +1,5 @@ +//! Resolve IPs from hostnames. + use crate::ServerAddress; use async_recursion::async_recursion; use std::net::{IpAddr, SocketAddr}; diff --git a/azalea-protocol/src/write.rs b/azalea-protocol/src/write.rs index 8e56e5fc..10f09165 100755 --- a/azalea-protocol/src/write.rs +++ b/azalea-protocol/src/write.rs @@ -1,3 +1,5 @@ +//! Write packets to a stream. + use crate::{packets::ProtocolPacket, read::MAXIMUM_UNCOMPRESSED_LENGTH}; use async_compression::tokio::bufread::ZlibEncoder; use azalea_buf::McBufVarWritable; @@ -6,10 +8,11 @@ use std::fmt::Debug; use thiserror::Error; use tokio::io::{AsyncReadExt, AsyncWrite, AsyncWriteExt}; -fn frame_prepender(data: &mut Vec) -> Result, std::io::Error> { +/// Prepend the length of the packet to it. +fn frame_prepender(mut data: Vec) -> Result, std::io::Error> { let mut buf = Vec::new(); (data.len() as u32).var_write_into(&mut buf)?; - buf.append(data); + buf.append(&mut data); Ok(buf) } @@ -82,7 +85,7 @@ where if let Some(threshold) = compression_threshold { buf = compression_encoder(&buf, threshold).await.unwrap(); } - buf = frame_prepender(&mut buf).unwrap(); + buf = frame_prepender(buf).unwrap(); // if we were given a cipher, encrypt the packet if let Some(cipher) = cipher { azalea_crypto::encrypt_packet(cipher, &mut buf);