init

Author: jamesbt365

.cargo_vcs_info.json

@@ -0,0 +1,6 @@
+{
+  "git": {
+    "sha1": "842506c917b644aba1aa26f4ca7b48c7c4d6b711"
+  },
+  "path_in_vcs": ""
+}

.gitignore

@@ -0,0 +1,2 @@
+resources/
+target/

Cargo.toml

@@ -0,0 +1,74 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2021"
+name = "perspective_api"
+version = "1.0.0"
+authors = ["honestlysamuk"]
+exclude = ["src/main.rs"]
+description = "An unopinionated client and a somewhat opinionated service for the Perspective API."
+homepage = "https://github.com/honestlysamuk/perspective_api"
+documentation = "https://developers.perspectiveapi.com/s/?language=en_US"
+readme = "README.md"
+license = "BSD-3-Clause"
+repository = "https://github.com/honestlysamuk/perspective_api"
+
+[dependencies.anyhow]
+version = "1.0.86"
+optional = true
+
+[dependencies.reqwest]
+version = "0.12.5"
+features = ["json"]
+
+[dependencies.serde]
+version = "1.0.205"
+features = ["derive"]
+
+[dependencies.serde_json]
+version = "1.0.122"
+
+[dependencies.thiserror]
+version = "1.0.63"
+
+[dependencies.tracing]
+version = "0.1.40"
+
+[dependencies.url]
+version = "2.5.2"
+
+[dev-dependencies.pretty_assertions]
+version = "1"
+
+[dev-dependencies.tokio]
+version = "1"
+features = ["full"]
+
+[features]
+service = ["anyhow"]
+
+[lints.clippy]
+collapsible_match = "warn"
+expect_used = "warn"
+match_bool = "warn"
+match_ref_pats = "warn"
+match_same_arms = "warn"
+match_single_binding = "warn"
+needless_bool = "deny"
+needless_late_init = "warn"
+needless_match = "warn"
+redundant_guards = "warn"
+redundant_pattern = "warn"
+redundant_pattern_matching = "warn"
+single_match = "warn"
+single_match_else = "warn"
+unwrap_used = "warn"

Cargo.toml.orig

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, honestlysam
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE

@@ -0,0 +1,6 @@
+# perspective_api
+An unopinionated client and a somewhat opinionated service for the Perspective API.
+
+Activate the service feature for some extra convenience.
+
+Version 1.0.0 is released now. I have aimed at an MVP to begin. There is another endpoint not yet implemented, and a command line version is also not yet implemented.

README.md

@@ -0,0 +1,66 @@
+# 0800
+
+Read through all code, familiarise myself with the task.
+Summary:
+There is an integration with the Perspective API built in Typescript which still needs migrating to Rust. There is a sample implementation for the TikTok API for reference, so I can copy the style. The MVP is to port one endpoint from Typescript into Rust in a new client.
+
+Strategy:
+1. I start low-level by creating some requests in [Bruno](https://www.usebruno.com/). I can't implement a client without exploring the API outside the clutter of a programming language.
+2. Capture request and response JSON and use it to generate structs and for serde tests.
+3. Write `reqwest`-level modules for calling the endpoint.
+4. Integrate this module with a service.
+
+(Copied from the readme)
+
+My usual first step with a port is to have an example of the old client functional so I can compare implementations.
+
+To begin with, I will take point one and explore Perspective with Bruno.
+
+# 0841
+
+The perspective API already has Python and Node.js implementations provided by Google. There is also a [sample Typescript implementation](https://github.com/conversationai/perspectiveapi-simple-server/tree/main).
+It requires a Google Cloud account and a verification process to use properly, which takes up to one business day. This
+could be step 4.
+
+# 0941
+
+The "old client" just calls the actual JS API client and adds an API key etc to make the internal interface more pleasant.
+Is the challenge therefore to rewrite the typescript wrapper for this API in Rust, leveraging the FFI to call that
+JS package through WASM, or is it to rewrite that JS client itself?
+
+# 1038
+
+My first coding task will be to model the typescript functionality in Rust, without considering IO for now.
+Bruno is a great tool, but I am struggling to get the response back. Testing with cURL works, but what looks
+like the same configuration does not work in Bruno. I will revisit this after some modelling.
+
+I have fleshed out the project with some copy/pasting from the other two projects. I have modelled the structure
+on the TikTok project, and I am working through the typescript project in parallel to form a first case.
+
+# 1200
+
+Lunch
+
+# 1300
+
+Got Bruno to work. Silly auth config issue. Now I can flesh out some examples and decide on the API contract.
+
+TODO
+
+Build a generic Rust library of one function called analyze which mimics the functionality of the original JS API.
+    Flesh out a collection of Bruno examples demonstrating the use of the single end point.
+    Write tests which call the endpoint and demonstrate its use.
+    Write a Stub implementation.
+
+Build a specific Arwen library of one or more functions which mimics the old typescript implementation and uses the generic library.
+Build a service using the Arwen library using Axum
+
+
+# 1430
+
+Almost got a reqwest client to work with the sample data I used in Bruno.
+
+# 1500
+
+Conversation with James to focus the scope of the work. In the same crate, I am to build a mirror of the Perspective API
+in one module, and a service for Arwen using that API in another.

Ticket/20240808.md

@@ -0,0 +1,19 @@
+# 1808
+
+Successfully called the endpoint from Rust.
+Observations:
+- You can input the body with something which serializes into json.
+- You can input the params with the .form() method, instead of formatting
+the URL directly.
+- The .form method appears not to work well with other helper methods.
+
+# 1928
+
+Successfully leveraged serde's attributes to de and re serialise our models.
+Shuffled around the structure and changed some privacy settings on the code.
+Called our endpoint from main successfully.
+TODO
+Test standard HTTP error cases
+Port the peripheral error handling from the original client
+
+# 1950

Ticket/20240809.md

@@ -0,0 +1,4 @@
+# 0900
+
+Discovered Url::parse_with_params to avoid the format macro. Reread the TikTok client for the plan for my errors.
+No need to explicitly state the headers. Using the .json method sets it anyway.

Ticket/20240810.md

@@ -0,0 +1,12 @@
+# 2100
+
+Made a lot of progress on error handling and testing. I am putting more effort into the modelling of the API in
+Rust than I probably need to, but it is useful to separate the concerns of the API representation and what Arwen
+wants to do with it, which will come in the service.
+
+There are four tests which now pass.
+
+There are still lots of warnings, but the Perspective-facing contract is functional.
+The next step is to build the Arwen-facing API, emulating the typescript function and its specifics.
+
+# 2350

Ticket/20240811.md

@@ -0,0 +1,11 @@
+# 1000
+
+Began on the service function implementation. There are two options for making the options more
+ergonomic to use for a developer. The first is the way I would default to if I were in another
+language. The second is to use the builder pattern for the request, which would have in its
+methods ways to control all the features of the API in a compact way. I can also introduce a default
+implementation which can facilitate the convenience function.
+
+# 1400
+
+Committed my first works on the service function. Close to completion.

Ticket/20240813.md

@@ -0,0 +1,3 @@
+In the absence of a work tracking system, I will add comments and attachments in this directory that I would otherwise put elsewhere.
+
+Additionally, since this is a coding challenge for just me, I will be pushing changes directly to main.

Ticket/README.md

@@ -0,0 +1,3 @@
+max_width = 150
+use_small_heuristics = "Default"
+wrap_comments = true

rustfmt.toml

@@ -0,0 +1,10 @@
+/// The Perspective client for version v1alpha1 of their API.
+pub(crate) mod v1alpha1;
+pub use v1alpha1::models::error::AnalyzeCommentError;
+pub use v1alpha1::models::error::AnalyzeCommentErrorResponse;
+pub use v1alpha1::models::error::MAX_LENGTH;
+pub use v1alpha1::models::request::AnalyzeCommentRequest;
+pub use v1alpha1::models::response::AnalyzeCommentResponse;
+pub use v1alpha1::PerspectiveClient;
+
+// This client is versioned by API. When a new version of the Perspective API is released, a new module should be created here.

src/client/mod.rs

@@ -0,0 +1,35 @@
+use reqwest::StatusCode;
+use tracing::debug;
+use url::Url;
+
+use crate::client::AnalyzeCommentError;
+use crate::client::AnalyzeCommentErrorResponse;
+use crate::client::AnalyzeCommentRequest;
+use crate::client::AnalyzeCommentResponse;
+use crate::client::PerspectiveClient;
+
+use super::BASE_URL;
+// Tests for the interaction with the API are in the `tests` directory.
+impl PerspectiveClient {
+    /// This function encapsulates the interaction with the Perspective API, taking a request object and returning a success response or a custom error.
+    pub async fn analyze(&self, request: AnalyzeCommentRequest) -> Result<AnalyzeCommentResponse, AnalyzeCommentError> {
+        let url = Url::parse_with_params(BASE_URL, [("key", &self.api_key)]).expect("no api_keys can fail this function and the base url is const");
+        debug!("URL: {}", &url);
+
+        let response = self.client.post(url).json(&request).send().await?;
+
+        match response.status() {
+            StatusCode::OK => {
+                let body = &response.text().await?;
+                debug!("Response: {}", &body);
+                Ok(serde_json::from_str(body)?)
+            }
+            StatusCode::FORBIDDEN => Err(AnalyzeCommentError::NoApiKey),
+            _ => {
+                let body = &response.text().await?;
+                debug!("Response: {}", &body);
+                Err(serde_json::from_str::<AnalyzeCommentErrorResponse>(body)?)?
+            }
+        }
+    }
+}

src/client/v1alpha1/analyze.rs

@@ -0,0 +1,19 @@
+pub(crate) mod analyze;
+pub(crate) mod models;
+
+// client constants
+pub(crate) const BASE_URL: &str = "https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze";
+
+use reqwest::Client;
+
+/// A wrapper for a `reqwest` client and your API key, and has the API entry points.
+pub struct PerspectiveClient {
+    pub client: Client,
+    pub api_key: String,
+}
+
+impl PerspectiveClient {
+    pub fn new(api_key: &str) -> Self {
+        Self { client: Client::new(), api_key: api_key.to_owned() }
+    }
+}