Merge pull request #4 from noctisynth/rocket-and-memo

🚀 Add some documentation notes and optimize some issues

src/api.rs

@@ -1,19 +1,22 @@
-//! # Oblivion API 接口
+//! # Oblivion API Interface
 //!
-//! Oblivion 提供了直接进行 GET、POST、PUT 等请求的方法。
+//! Oblivion provides methods for making direct GET, POST, PUT, etc. requests.
 use serde_json::Value;
 
 use crate::{exceptions::OblivionException, models::client::Response};
 
 use super::sessions::Session;
 
-/// 裸 Oblivion 请求模式
+/// Naked Oblivion Request Mode
 ///
 /// ```rust
 /// use oblivion::api::request;
+/// use oblivion::models::client::Response;
+/// use oblivion::exceptions::OblivionException;
 ///
-/// async fn run() {
-///     request("get", "127.0.0.1:813/get", None, None, true).await.unwrap();
+/// #[tokio::test]
+/// async fn run() -> Result<Response, OblivionException> {
+///     request("get", "127.0.0.1:813/get", None, None, true).await
 /// }
 /// ```
 pub async fn request(

src/exceptions.rs

@@ -1,5 +1,6 @@
 //! # Oblivion 异常
 //! 所有 Oblivion 函数的异常均返回`OblivionException`。
+use ring::error::Unspecified;
 use scrypt::errors::InvalidOutputLen;
 use thiserror::Error;
 
@@ -44,5 +45,12 @@ pub enum OblivionException {
         error: elliptic_curve::Error,
     },
     #[error("共享密钥生成时出现异常: {error:?}")]
-    InvalidOutputLen { error: InvalidOutputLen },
+    InvalidOutputLen {
+        #[from]
+        error: InvalidOutputLen,
+    },
+    #[error("加密时出现异常: {error:?}")]
+    EncryptError { error: Unspecified },
+    #[error("解密时出现异常: {error:?}")]
+    DecryptError { error: Unspecified },
 }

src/lib.rs

@@ -1,18 +1,20 @@
 //! # Oblivion
 //!
-//! Oblivion 是浊莲为确保信息安全而开发的端到端加密协议，这是 Oblivion 的 Rust 实现。
-//! 它在 Python 实现的基础上大大提高了 Oblivion 的安全性、稳定性和并发性。
+//! Oblivion is a Rust implementation of Oblivion,an end-to-end encryption protocol developed by Turbolane to secure information.
+//! It greatly improves the security, stability, and concurrency of Oblivion based on the Python implementation.
 //!
-//! 由于 Oblivion 协议中要求的加密算法为 ECDHE 算法，它以高效安全密钥派生方法，使得它可以应用于信息派发和及时通讯。
+//! Since the encryption algorithm required in the Oblivion protocol is the ECDHE algorithm,
+//! it is based on an efficient and secure key derivation method,
+//! which makes it possible to apply it to message dispatching and just-in-time communication.
 pub extern crate oblivion_codegen;
 pub extern crate proc_macro;
 pub mod api;
 pub mod exceptions;
 pub mod sessions;
 
-/// # Oblivion 工具类
+/// # Oblivion Utilities
 ///
-/// Oblivion 的工具类提供了密钥创建，数据加密解密与请求解析处理方法。
+/// Oblivion utility classes provide key creation, data encryption and decryption, and request resolution processing methods.
 pub mod utils {
     pub mod decryptor;
     pub mod encryptor;
@@ -21,9 +23,9 @@ pub mod utils {
     pub mod parser;
 }
 
-/// # Oblivion 模型
+/// # Oblivion Models
 ///
-/// Oblivion 提供了所有前后端模型，包括数据包构建以及客户端和服务端的构建。
+/// Oblivion provides all front- and back-end models, including packet building as well as client-side and server-side building.
 pub mod models {
     pub mod client;
     pub mod handler;
@@ -33,9 +35,9 @@ pub mod models {
     pub mod server;
 }
 
-/// 绝对路由宏
+/// Absolute Routing Macros
 ///
-/// 使用路由宏可以简单的实现路由：
+/// Routing can be simply implemented using routing macros:
 ///
 /// ```rust
 /// use futures::future::{BoxFuture, FutureExt};
@@ -57,7 +59,7 @@ pub mod models {
 /// path_route!(&mut router, "/welcome" => welcome);
 /// ```
 ///
-/// 上面的路由将会引导路径为`/welcome`或`/welcome/`的请求。
+/// The above route will direct requests with the path `/welcome` or `/welcome/`.
 #[macro_export]
 macro_rules! path_route {
     ($router:expr, $path:expr => $handler:ident) => {{
@@ -70,9 +72,9 @@ macro_rules! path_route {
     }};
 }
 
-/// 起始路由宏
+/// Startswith Routing Macros
 ///
-/// 使用起始路由宏可以简单的实现起始路由：
+/// Starting routes can be simply implemented using the start route macro:
 ///
 /// ```rust
 /// use futures::future::{BoxFuture, FutureExt};
@@ -94,7 +96,7 @@ macro_rules! path_route {
 /// startswith_route!(&mut router, "/welcome" => welcome);
 /// ```
 ///
-/// 上面的路由将会引导所有以`/welcome`起始的 Oblivion Location Path String。
+/// The above route will direct all Oblivion Location Path String starting with `/welcome`.
 #[macro_export]
 macro_rules! startswith_route {
     ($router:expr, $path:expr => $handler:ident) => {{
@@ -110,9 +112,9 @@ macro_rules! startswith_route {
     }};
 }
 
-/// 正则路由宏
+/// Regular routing macro
 ///
-/// 使用正则路由宏可以简单的实现正则路由：
+/// Regular routing can be simply implemented using regular routing macros:
 ///
 /// ```rust
 /// use futures::future::{BoxFuture, FutureExt};
@@ -134,9 +136,9 @@ macro_rules! startswith_route {
 /// regex_route!(&mut router, r"^/welcome/.*" => welcome);
 /// ```
 ///
-/// 上面的路由将会引导所有以`/welcome/`起始的 Oblivion Location Path String。
+/// The above route will direct all Oblivion Location Path String starting with `/welcome/`.
 ///
-/// 你还可以使用`^/.*`来劫持所有路由。
+/// You can also use `^/. *` to hijack all routes.
 #[macro_export]
 macro_rules! regex_route {
     ($router:expr, $path:expr => $handler:ident) => {{

src/models/client.rs

@@ -79,7 +79,7 @@ impl Request {
         let method = method.to_uppercase();
         let path = OblivionPath::new(&olps)?;
         let olps = path.get_olps();
-        let oblivion = Oblivion::new(&method, &olps)?;
+        let oblivion = Oblivion::new(&method, &olps);
         let plain_text = oblivion.plain_text();
         Ok(Self {
             method,
@@ -113,8 +113,9 @@ impl Request {
             };
         self.tcp = Some(Socket::new(tcp));
 
-        if self.tfo {};
-        // TODO 在这里启用TCP Fast Open
+        if self.tfo {
+            todo!() // 在这里启用TCP Fast Open
+        };
 
         self.send_header().await?;
 
@@ -187,13 +188,13 @@ impl Request {
             let mut oed = OED::new(self.aes_key.clone());
             oed.from_stream(tcp, 5).await?;
 
-            let mut osc = OSC::from_stream(tcp).await?;
+            let osc = OSC::from_stream(tcp).await?;
 
             let response = Response::new(
                 self.plain_text.clone(),
                 oed.get_data(),
                 self.olps.clone(),
-                osc.get_status_code(),
+                osc.status_code,
             );
             Ok(response)
         }

src/models/packet.rs

@@ -3,7 +3,7 @@ use crate::utils::gear::Socket;
 use crate::exceptions::OblivionException;
 
 use super::super::utils::decryptor::decrypt_bytes;
-use super::super::utils::encryptor::{encrypt_bytes, encrypt_message};
+use super::super::utils::encryptor::{encrypt_bytes, encrypt_plaintext};
 use super::super::utils::generator::{generate_random_salt, generate_shared_key};
 use super::super::utils::parser::length;
 
@@ -46,7 +46,7 @@ impl ACK {
 }
 
 pub struct OSC {
-    status_code: i32,
+    pub status_code: i32,
 }
 
 impl OSC {
@@ -72,10 +72,6 @@ impl OSC {
         let status_code = format!("{}", self.status_code);
         status_code.into_bytes()
     }
-
-    pub fn get_status_code(&mut self) -> i32 {
-        self.status_code
-    }
 }
 
 pub struct OKE<'a> {
@@ -230,17 +226,20 @@ impl OED {
         serialized_bytes
     }
 
-    pub fn from_json_or_string(&mut self, json_or_str: String) -> Result<&mut Self, ()> {
+    pub fn from_json_or_string(
+        &mut self,
+        json_or_str: String,
+    ) -> Result<&mut Self, OblivionException> {
         let (encrypted_data, tag, nonce) =
-            encrypt_message(json_or_str, &self.aes_key.as_ref().unwrap());
+            encrypt_plaintext(json_or_str, &self.aes_key.as_ref().unwrap())?;
         (self.encrypted_data, self.tag, self.nonce) =
             (Some(encrypted_data), Some(tag), Some(nonce));
         Ok(self)
     }
 
     pub fn from_dict(&mut self, dict: Value) -> Result<&mut Self, OblivionException> {
         let (encrypted_data, tag, nonce) =
-            encrypt_message(dict.to_string(), &self.aes_key.as_ref().unwrap());
+            encrypt_plaintext(dict.to_string(), &self.aes_key.as_ref().unwrap())?;
         (self.encrypted_data, self.tag, self.nonce) =
             (Some(encrypted_data), Some(tag), Some(nonce));
         Ok(self)
@@ -252,7 +251,7 @@ impl OED {
     }
 
     pub fn from_bytes(&mut self, data: Vec<u8>) -> Result<&mut Self, OblivionException> {
-        let (encrypted_data, tag, nonce) = encrypt_bytes(data, &self.aes_key.as_ref().unwrap());
+        let (encrypted_data, tag, nonce) = encrypt_bytes(data, &self.aes_key.as_ref().unwrap())?;
         (self.encrypted_data, self.tag, self.nonce) =
             (Some(encrypted_data), Some(tag), Some(nonce));
         Ok(self)

src/models/server.rs

@@ -27,8 +27,8 @@ impl ServerConnection {
         let (private_key, public_key) = generate_key_pair()?;
 
         Ok(Self {
-            private_key: private_key,
-            public_key: public_key,
+            private_key,
+            public_key,
             aes_key: None,
         })
     }
@@ -48,12 +48,12 @@ impl ServerConnection {
         oke.from_stream(stream).await?;
         self.aes_key = Some(oke.get_aes_key());
 
-        if request.get_method() == "POST" {
+        if request.method == "POST" {
             let mut oed = OED::new(self.aes_key.clone());
             oed.from_stream(stream, 5).await?;
             request.set_post(from_slice(&oed.get_data()).unwrap());
-        } else if request.get_method() == "GET" {
-        } else if request.get_method() == "PUT" {
+        } else if request.method == "GET" {
+        } else if request.method == "PUT" {
             let mut oed = OED::new(self.aes_key.clone());
             oed.from_stream(stream, 5).await?;
             request.set_post(from_slice(&oed.get_data()).unwrap());
@@ -63,7 +63,7 @@ impl ServerConnection {
             request.set_put(oed.get_data());
         } else {
             return Err(OblivionException::UnsupportedMethod {
-                method: request.get_method(),
+                method: request.method,
             });
         };
         Ok(request)