Release v0.2.0 (#6)

Reviewed-on: #6

.drone.yml

@@ -0,0 +1,14 @@
+---
+kind: pipeline
+type: docker
+name: default
+
+steps:
+- name: cargo_check
+  image: rust
+  commands:
+  - rustup component add clippy
+  - cargo clippy -- -D warnings
+  - cargo test --all-features
+
+

Cargo.toml

@@ -1,19 +1,31 @@
 [package]
 name = "grammalecte_client"
-version = "0.1.0"
+version = "0.1.5"
 edition = "2021"
 authors = ["Pierre Hubert <pierre.git@communiquons.org>"]
 description = "Grammalecte HTTP client"
 license = "MIT"
+repository = "https://gitea.communiquons.org/pierre/GrammalecteClient"
+keywords = ["grammalecte", "spell-check", "spellcheck"]
+readme = "README.md"
+categories = ["text-processing"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-serde_json = "1.0.89"
+serde_json = "1.0.96"
-reqwest = { version = "0.11.13", features = ["json"] }
+reqwest = { version = "0.12.4", features = ["json"] }
-serde = { version = "1.0.151", features = ["derive"] }
+serde = { version = "1.0.163", features = ["derive"] }
 log = "0.4.17"
+zip = { version = "2.1.3", optional = true }
+mktemp = { version = "0.5.0", optional = true }
+rand = { version = "0.8.5", optional = true }
+port_scanner = { version = "0.1.5", optional = true }
+thiserror = "1.0.61"
+
+[features]
+embedded-server = ["zip", "mktemp", "rand", "port_scanner"]
 
 [dev-dependencies]
-env_logger = "0.10.0"
+env_logger = "0.11.3"
-tokio = { version = "1.23.0", features = ["full"] }
+tokio = { version = "1.28.1", features = ["full"] }

README.md

@@ -0,0 +1,7 @@
+# Grammalecte client
+[![Crate](https://img.shields.io/crates/v/grammalecte_client.svg)](https://crates.io/crates/grammalecte_client)
+[![Documentation](https://docs.rs/grammalecte_client/badge.svg)](https://docs.rs/grammalecte_client/)
+
+This crate is an Open Source [Grammalecte](https://grammalecte.net/) client, written in Rust.
+
+Please have a look at this [crate documentation](https://docs.rs/grammalecte_client/latest/grammalecte_client/) to learn more.

renovate.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["major", "minor", "patch"],
+      "automerge": true
+    }
+  ]
+}

src/lib.rs

@@ -1,5 +1,49 @@
+//! # Grammalecte Rust Client
+//!
+//! This crate is a Rust client to the Grammalecte server API.
+//!
+//! Grammalecte is an Open Source software that allows to do
+//! french spell-checking.
+//!
+//! ## Integrated server
+//! The optional feature `embedded-server` allows you to spin up an
+//! temporary web server that will act as Grammalecte backend, instead
+//! of targetting an existing instance:
+//!
+//! ```rust,ignore
+//! use grammalecte_client::GrammalecteClient;
+//!
+//! let msg = "Les ange sont inssuportables!";
+//! let res = GrammalecteClient::start_server()
+//!             .unwrap()
+//!             .spell_check(msg)
+//!             .await
+//!             .unwrap();
+//! println!("RESULT = {:#?}", res);
+//! ```
+//!
+//! ## Suggestion
+//! You can also ask Grammalecte to give you valid alternatives words:
+//! ```rust,ignore
+//! use grammalecte_client::GrammalecteClient;
+//!
+//! let res = GrammalecteClient::start_server()
+//!             .unwrap()
+//!             .suggest("bonjou")
+//!             .await
+//!             .unwrap();
+//! assert!(res.suggestions.contains(&"bonjour".to_string()));
+//! println!("RESULT = {:#?}", res);
+//! ```
+
+use thiserror::Error;
+
+#[cfg(feature = "embedded-server")]
+use crate::server::EmbeddedServer;
 use std::collections::HashMap;
-use std::error::Error;
+
+#[cfg(feature = "embedded-server")]
+pub mod server;
 
 /// Spell check options
 #[derive(Hash, Debug, Eq, PartialEq)]
@@ -145,6 +189,7 @@ pub enum GramOpt {
 }
 
 impl GramOpt {
+    /// Get the technical ID of the Grammalecte option
     pub fn id(&self) -> &'static str {
         match self {
             GramOpt::SignesTypographiques => "typo",
@@ -203,6 +248,7 @@ pub struct CheckResult {
     pub paragraphs: Vec<Paragraph>,
 }
 
+/// Check spell result of a given paragraph
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct Paragraph {
     #[serde(rename = "iParagraph")]
@@ -213,6 +259,7 @@ pub struct Paragraph {
     pub spelling: Vec<SpellingError>,
 }
 
+/// Single grammar error
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct GrammarError {
     #[serde(rename = "nStart")]
@@ -226,7 +273,7 @@ pub struct GrammarError {
     #[serde(rename = "sType")]
     pub rule_type: String,
     #[serde(rename = "aColor")]
-    pub rule_underline_color: Vec<u8>,
+    pub rule_underline_color: Option<Vec<u8>>,
     #[serde(rename = "sMessage")]
     pub message: String,
     #[serde(rename = "aSuggestions")]
@@ -235,6 +282,7 @@ pub struct GrammarError {
     pub url: String,
 }
 
+/// Spelling error information
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct SpellingError {
     pub i: usize,
@@ -248,19 +296,49 @@ pub struct SpellingError {
     pub error_type: String,
 }
 
+/// Response to a suggestion request
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct SuggestResult {
-    suggestions: Vec<String>,
+    /// Suggestions returned by Grammalecte
+    pub suggestions: Vec<String>,
 }
 
+#[derive(Debug, Error)]
+pub enum Error {
+    #[cfg(feature = "embedded-server")]
+    #[error("Grammalecte-server failed to start")]
+    ServerStartFailed(#[from] server::Error),
+
+    #[error("Failed to Serialize Option in Json")]
+    OptionJsonSerialization(#[source] serde_json::Error),
+
+    #[error("Failed to send request `check with option`")]
+    RequestSendCheckWithOptions(#[source] reqwest::Error),
+
+    #[error("Failed to send request `suggest`")]
+    RequestSendSuggest(#[source] reqwest::Error),
+
+    #[error("Failed to Deserialize Check result")]
+    CheckResultDeserialize(#[source] reqwest::Error),
+
+    #[error("Failed to Deserialize Suggest result")]
+    SuggestDeserialize(#[source] reqwest::Error),
+}
+
+/// The Grammalecte client itself
 pub struct GrammalecteClient {
     base_url: String,
+
+    #[cfg(feature = "embedded-server")]
+    _server: Option<EmbeddedServer>,
 }
 
 impl Default for GrammalecteClient {
     fn default() -> Self {
         Self {
             base_url: "http://localhost:8080".to_string(),
+            #[cfg(feature = "embedded-server")]
+            _server: None,
         }
     }
 }
@@ -270,28 +348,43 @@ impl GrammalecteClient {
     pub fn new(base_url: &str) -> Self {
         Self {
             base_url: base_url.to_string(),
+            #[cfg(feature = "embedded-server")]
+            _server: None,
         }
     }
 
+    /// Construct a new Grammalecte client, spinning up an associated
+    /// temporary web server.
+    ///
+    /// Python 3.7 or higher must is required at runtime
+    #[cfg(feature = "embedded-server")]
+    pub fn start_server() -> Result<Self, Error> {
+        let server = EmbeddedServer::start()?;
+        Ok(Self {
+            base_url: server.base_url(),
+            _server: Some(server),
+        })
+    }
+
     /// Run spell check on text
-    pub async fn spell_check(&self, text: &str) -> Result<CheckResult, Box<dyn Error>> {
+    pub async fn spell_check(&self, text: &str) -> Result<CheckResult, Error> {
-        self.spell_check_with_options(text, HashMap::new()).await
+        self.spell_check_with_options(text, &HashMap::new()).await
     }
 
     /// Run spell check with custom options
     pub async fn spell_check_with_options(
         &self,
         text: &str,
-        options: HashMap<GramOpt, bool>,
+        options: &HashMap<GramOpt, bool>,
-    ) -> Result<CheckResult, Box<dyn Error>> {
+    ) -> Result<CheckResult, Error> {
         let url = format!("{}/gc_text/fr", self.base_url);
         log::debug!("Will use URL {} for spell check", url);
 
         let options = options
-            .into_iter()
+            .iter()
             .map(|t| (t.0.id(), t.1))
             .collect::<HashMap<_, _>>();
-        let options = serde_json::to_string(&options)?;
+        let options = serde_json::to_string(&options).map_err(Error::OptionJsonSerialization)?;
 
         let mut params = HashMap::new();
         params.insert("text", text);
@@ -301,32 +394,37 @@ impl GrammalecteClient {
             .post(url)
             .form(&params)
             .send()
-            .await?
+            .await
+            .map_err(Error::RequestSendCheckWithOptions)?
             .json::<CheckResult>()
-            .await?;
+            .await
+            .map_err(Error::CheckResultDeserialize)?;
 
         Ok(result)
     }
 
     /// Ask for word suggestion
-    pub async fn suggest(&self, token: &str) -> Result<SuggestResult, Box<dyn Error>> {
+    pub async fn suggest(&self, token: &str) -> Result<SuggestResult, Error> {
         let url = format!("{}/suggest/fr", self.base_url);
         log::debug!("Will use URL {} for word suggestion", url);
 
         let mut params = HashMap::new();
         params.insert("token", token);
 
-        Ok(reqwest::Client::new()
+        reqwest::Client::new()
             .post(&url)
             .form(&params)
             .send()
-            .await?
+            .await
+            .map_err(Error::RequestSendSuggest)?
             .json()
-            .await?)
+            .await
+            .map_err(Error::SuggestDeserialize)
     }
 }
 
 #[cfg(test)]
+#[cfg(feature = "embedded-server")]
 mod test {
     use crate::{GramOpt, GrammalecteClient};
     use std::collections::HashMap;
@@ -336,7 +434,11 @@ mod test {
         let _ = env_logger::builder().is_test(true).try_init();
 
         let msg = "Les ange sont inssuportables!";
-        let res = GrammalecteClient::default().spell_check(msg).await.unwrap();
+        let res = GrammalecteClient::start_server()
+            .unwrap()
+            .spell_check(msg)
+            .await
+            .unwrap();
         println!("RESULT = {:#?}", res);
     }
 
@@ -347,8 +449,9 @@ mod test {
         let msg = "Bonjour !";
         let mut opts = HashMap::new();
         opts.insert(GramOpt::EspacesInsecables, false);
-        let res = GrammalecteClient::default()
+        let res = GrammalecteClient::start_server()
-            .spell_check_with_options(msg, opts)
+            .unwrap()
+            .spell_check_with_options(msg, &opts)
             .await
             .unwrap();
         println!("RESULT = {:#?}", res);
@@ -359,7 +462,8 @@ mod test {
     async fn simple_suggestion() {
         let _ = env_logger::builder().is_test(true).try_init();
 
-        let res = GrammalecteClient::default()
+        let res = GrammalecteClient::start_server()
+            .unwrap()
             .suggest("bonjou")
             .await
             .unwrap();

src/server.rs

@@ -0,0 +1,179 @@
+use crate::server::utils::{get_free_port, wait_for_server};
+use mktemp::Temp;
+use std::io::{self, Cursor, Read};
+use std::process::{Child, ExitStatus, Stdio};
+use thiserror::Error;
+use zip::{result::ZipError, ZipArchive};
+
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("Grammalecte-server failed to launch process")]
+    StartServerProcess(#[source] io::Error),
+
+    #[error("Get an available port failed")]
+    GetFreePort(#[source] io::Error),
+
+    #[error("Server exit with `{status}`")]
+    ServerExitWithStatus { status: ExitStatus },
+
+    #[error("Server exit with `{status}` :\n{msg}")]
+    ServerExitWithError { status: ExitStatus, msg: String },
+
+    #[error("Error append during check grammalecte-server status")]
+    ServerCheckStatus(#[source] io::Error),
+
+    #[error("Port {port} did not open in time!")]
+    WaitPortOpen { port: u16 },
+
+    #[error("Create temporary directory failed")]
+    CreateTempDir(#[source] io::Error),
+
+    #[error("Zip archive loading failed")]
+    ZipArchiveLoading(#[source] ZipError),
+
+    #[error("Access file by index failed")]
+    ZipFileIndex(#[source] ZipError),
+
+    #[error("Create directory for files from zip")]
+    CreateDirectoryForZipFile(#[source] io::Error),
+
+    #[error("Read file from zip archive")]
+    ZipFileReadToEnd(#[source] io::Error),
+
+    #[error("Write file from archive on disk")]
+    WriteFile(#[source] io::Error),
+}
+
+pub struct EmbeddedServer {
+    _srv_dir: Temp,
+    port: u16,
+    child: Child,
+}
+
+impl EmbeddedServer {
+    /// Start embedded Grammalecte server on a random free port
+    pub fn start() -> Result<Self, Error> {
+        Self::start_listen_on_port(get_free_port())
+    }
+
+    /// Start embedded Grammalecte server on a given port
+    pub fn start_listen_on_port(port: u16) -> Result<Self, Error> {
+        log::info!("Will start server");
+        // First, unpack server
+        let dest = mktemp::Temp::new_dir().map_err(Error::CreateTempDir)?;
+        let cursor = Cursor::new(include_bytes!("GrammalecteDist.zip"));
+        let mut zip = ZipArchive::new(cursor).map_err(Error::ZipArchiveLoading)?;
+        for i in 0..zip.len() {
+            let mut file = zip.by_index(i).map_err(Error::ZipFileIndex)?;
+            if file.is_dir() {
+                log::debug!("Create directory: {}", file.name());
+                std::fs::create_dir_all(dest.join(file.name()))
+                    .map_err(Error::CreateDirectoryForZipFile)?;
+            } else {
+                log::debug!("Decompress file: {}", file.name());
+
+                let mut buff = Vec::with_capacity(file.size() as usize);
+                file.read_to_end(&mut buff)
+                    .map_err(Error::ZipFileReadToEnd)?;
+
+                std::fs::write(dest.join(file.name()), buff).map_err(Error::WriteFile)?;
+            }
+        }
+
+        log::info!("Will start to listen on port {}", port);
+
+        let server_file = dest
+            .join("grammalecte/grammalecte-server.py")
+            .to_string_lossy()
+            .to_string();
+        log::info!("Will execute file {}", server_file);
+
+        // Start server
+        let mut child = std::process::Command::new("/usr/bin/python3")
+            .arg(server_file)
+            .arg("-p")
+            .arg(port.to_string())
+            .stdout(Stdio::null())
+            .stderr(Stdio::piped())
+            .spawn()
+            .map_err(Error::StartServerProcess)?;
+
+        wait_for_server(&mut child, port)?;
+
+        Ok(Self {
+            _srv_dir: dest,
+            port,
+            child,
+        })
+    }
+
+    /// Get embedde instance base URL
+    pub fn base_url(&self) -> String {
+        format!("http://localhost:{}", self.port)
+    }
+}
+
+impl Drop for EmbeddedServer {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+    }
+}
+
+mod utils {
+    use super::Error;
+    use std::fmt::Write;
+    use std::io::{BufRead, BufReader};
+    use std::process::Child;
+    use std::time::Duration;
+
+    /// Get a free port
+    pub fn get_free_port() -> u16 {
+        let mut port = 0;
+
+        while !(2000..=64000).contains(&port) {
+            port = rand::random::<u16>() % 64000;
+        }
+
+        while port_scanner::scan_port(port) {
+            port += 1;
+        }
+
+        port
+    }
+
+    pub fn wait_for_server(child: &mut Child, port: u16) -> Result<(), Error> {
+        for _ in 0..50 {
+            check_server(child)?;
+            if port_scanner::scan_port(port) {
+                return Ok(());
+            }
+            std::thread::sleep(Duration::from_millis(100));
+        }
+
+        Err(Error::WaitPortOpen { port })
+    }
+
+    fn check_server(child: &mut Child) -> Result<(), Error> {
+        match child.try_wait().map_err(Error::ServerCheckStatus)? {
+            None => Ok(()), // Continue
+            Some(status) => {
+                if let Some(err) = child.stderr.take() {
+                    let mut msg = format!("grammalecte-server exit with `{status}`");
+                    writeln!(&mut msg, " :").unwrap();
+                    let err = BufReader::new(err);
+                    err.lines().for_each(|line| match line {
+                        Ok(line) => {
+                            writeln!(&mut msg, "\t{}", line).unwrap();
+                        }
+                        Err(err) => {
+                            writeln!(&mut msg, "__{err:?}").unwrap();
+                        }
+                    });
+                    Err(Error::ServerExitWithError { status, msg })
+                } else {
+                    Err(Error::ServerExitWithStatus { status })
+                }
+            }
+        }
+    }
+}