rustdoc

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "thumbor"
 description = "A Rust client for the Thumbor image service"
-version = "0.1.2"
+version = "0.1.3"
 repository = "https://github.com/SteelAlloy/thumbor-rs"
 documentation = "https://docs.rs/thumbor"
 readme = "README.md"

README.md

@@ -29,20 +29,6 @@
 
 ## Usage
 
-In short :
-
-```rust
-use thumbor::Server;
-
-let url = Server::new("http://localhost:8888", "my-security-key")
-    .unwrap()
-    .settings_builder()
-    .resize((300, 200))
-    .smart(true)
-    .build()
-    .to_url("path/to/my/image.jpg");
-```
-
 ```rust
 use thumbor::Server;
 

src/endpoint.rs

@@ -0,0 +1,84 @@
+use crate::{
+    geometry::{Coords, Rect},
+    server::Server,
+};
+use filter::Filter;
+
+mod builder;
+pub mod filter;
+
+#[derive(strum::AsRefStr)]
+#[strum(serialize_all = "lowercase")]
+pub enum HAlignment {
+    Left,
+    Center,
+    Right,
+}
+
+#[derive(strum::AsRefStr)]
+#[strum(serialize_all = "lowercase")]
+pub enum VAlignment {
+    Top,
+    Middle,
+    Bottom,
+}
+
+/// Removing surrounding space in images can be done using the trim option.
+///
+/// Unless specified trim assumes the top-left pixel color and no tolerance
+/// (more on tolerance below).
+///
+/// Trim also supports color tolerance. The euclidean distance between the colors
+/// of the reference pixel and the surrounding pixels is used. If the distance is
+/// within the tolerance they’ll get trimmed. For a RGB image the tolerance would
+/// be within the range 0-442.
+#[derive(Default)]
+pub enum Trim {
+    #[default]
+    TopLeft,
+    BottomRight,
+}
+
+#[derive(Default)]
+pub enum FitIn {
+    #[default]
+    Default,
+    Adaptive,
+    Full,
+}
+
+pub enum ResponseMode {
+    Metadata,
+    Debug,
+}
+
+#[derive(Default, bon::Builder)]
+#[builder(start_fn = with_server)]
+pub struct Endpoint {
+    #[builder(start_fn)]
+    server: Server,
+    response: Option<ResponseMode>,
+    trim: Option<Trim>,
+
+    /// The manual crop is entirely optional. This is very useful for applications
+    /// that provide custom real-time cropping capabilities to their users.
+    ///
+    /// The manual crop part of the url takes two points as arguments, separated by a colon.
+    /// The first point is the left-top point of the cropping rectangle.
+    /// The second point is the right-bottom point.
+    ///
+    /// This crop is performed before the rest of the operations, so it can be used as
+    /// a prepare step before resizing and smart-cropping. It is very useful when you
+    /// just need to get that celebrity face on a big picture full of people, as an example.
+    #[builder(into)]
+    crop: Option<Rect>,
+    fit_in: Option<FitIn>,
+    #[builder(into)]
+    resize: Option<Coords>,
+    h_align: Option<HAlignment>,
+    v_align: Option<VAlignment>,
+    #[builder(default, into)]
+    filters: Vec<Filter>,
+    #[builder(default)]
+    smart: bool,
+}

src/settings/builder.rs → src/endpoint/builder.rs

@@ -1,9 +1,9 @@
-use super::{FitIn, ResponseMode, Settings, Trim};
+use super::{Endpoint, FitIn, ResponseMode, Trim};
 use crate::server::Security;
 use base64ct::{Base64Url, Encoding};
 use hmac::Mac;
 
-impl Settings {
+impl Endpoint {
     fn build_path(&self, image_uri: &str) -> String {
         let mut path = vec![];
 
@@ -74,6 +74,15 @@ impl Settings {
         path.join("/")
     }
 
+    /// ```
+    /// use thumbor::Server;
+    ///
+    /// let server = Server::new_unsafe("http://localhost:8888");
+    /// let endpoint = server.endpoint_builder().build();
+    /// let path = endpoint.to_path("path/to/my/image.jpg");
+    ///
+    /// assert_eq!(path, "/unsafe/path/to/my/image.jpg");
+    /// ```
     pub fn to_path(&self, image_uri: &str) -> String {
         let path = self.build_path(image_uri);
 
@@ -91,6 +100,15 @@ impl Settings {
         format!("/{security}/{path}")
     }
 
+    /// ```
+    /// use thumbor::Server;
+    ///
+    /// let server = Server::new_unsafe("http://localhost:8888");
+    /// let endpoint = server.endpoint_builder().build();
+    /// let path = endpoint.to_url("path/to/my/image.jpg");
+    ///
+    /// assert_eq!(path, "http://localhost:8888/unsafe/path/to/my/image.jpg");
+    /// ```
     pub fn to_url(&self, image_uri: &str) -> String {
         format!("{}{}", self.server.origin, self.to_path(image_uri))
     }

src/lib.rs

@@ -3,13 +3,13 @@
     html_logo_url = "https://raw.githubusercontent.com/SteelAlloy/thumbor-rs/main/assets/doc/logo.svg"
 )]
 
+pub mod endpoint;
 pub mod error;
 pub mod geometry;
 mod server;
-pub mod settings;
 
 #[cfg(test)]
 mod tests;
 
+pub use endpoint::{filter::Filter, Endpoint, EndpointBuilder};
 pub use server::Server;
-pub use settings::{filter::Filter, SettingsBuilder};

src/server.rs

@@ -1,4 +1,4 @@
-use crate::settings::{Settings, SettingsBuilder};
+use super::{Endpoint, EndpointBuilder};
 use hmac::{digest::InvalidLength, Hmac, Mac};
 use sha1::Sha1;
 
@@ -59,7 +59,7 @@ impl Server {
     /// let server = Server::new("http://localhost:8888", "my-security-key").unwrap();
     /// let builder = server.settings_builder();
     /// ```
-    pub fn settings_builder(&self) -> SettingsBuilder {
-        Settings::with_server(self.clone())
+    pub fn endpoint_builder(&self) -> EndpointBuilder {
+        Endpoint::with_server(self.clone())
     }
 }

src/tests.rs

@@ -1,26 +1,26 @@
 use crate::{
-    settings::{FitIn, ResponseMode},
-    Filter, Server, SettingsBuilder,
+    endpoint::{FitIn, ResponseMode},
+    EndpointBuilder, Filter, Server,
 };
 
 const TEST_BASE: &str = "http://my.server.com";
 const SECURITY_KEY: &str = "my-security-key";
 const IMAGE_PATH: &str = "my.server.com/some/path/to/image.jpg";
 
-fn new_builder() -> SettingsBuilder {
+fn new_builder() -> EndpointBuilder {
     Server::new(TEST_BASE, SECURITY_KEY)
         .expect("Server creation failed")
-        .settings_builder()
+        .endpoint_builder()
 }
 
 #[test]
 fn signing_of_a_known_url_results() {
     let width = 300;
     let height = 200;
 
-    let settings = new_builder().resize((width, height)).build();
+    let endpoint = new_builder().resize((width, height)).build();
 
-    let path = settings.to_path(IMAGE_PATH);
+    let path = endpoint.to_path(IMAGE_PATH);
 
     assert_eq!(
         path,
@@ -30,9 +30,9 @@ fn signing_of_a_known_url_results() {
 
 #[test]
 fn signature_with_meta() {
-    let settings = new_builder().response(ResponseMode::Metadata).build();
+    let endpoint = new_builder().response(ResponseMode::Metadata).build();
 
-    let path = settings.to_path(IMAGE_PATH);
+    let path = endpoint.to_path(IMAGE_PATH);
 
     assert_eq!(
         path,
@@ -42,9 +42,9 @@ fn signature_with_meta() {
 
 #[test]
 fn signature_with_smart() {
-    let settings = new_builder().smart(true).build();
+    let endpoint = new_builder().smart(true).build();
 
-    let path = settings.to_path(IMAGE_PATH);
+    let path = endpoint.to_path(IMAGE_PATH);
 
     assert_eq!(
         path,
@@ -54,9 +54,9 @@ fn signature_with_smart() {
 
 #[test]
 fn signature_with_fit_in() {
-    let settings = new_builder().fit_in(FitIn::Default).build();
+    let endpoint = new_builder().fit_in(FitIn::Default).build();
 
-    let path = settings.to_path(IMAGE_PATH);
+    let path = endpoint.to_path(IMAGE_PATH);
 
     assert_eq!(
         path,
@@ -66,11 +66,11 @@ fn signature_with_fit_in() {
 
 #[test]
 fn signature_with_filters() {
-    let settings = new_builder()
+    let endpoint = new_builder()
         .filters([Filter::Brightness(10), Filter::Contrast(20)])
         .build();
 
-    let path = settings.to_path(IMAGE_PATH);
+    let path = endpoint.to_path(IMAGE_PATH);
 
     assert_eq!(
         path,