Version 0.2.3!

.envrc

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+use flake

.gitignore

@@ -1,14 +1,5 @@
-# Generated by Cargo
-# will have compiled files and executables
+.direnv/
+coverage/
 debug/
 target/
-
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 Cargo.lock
-
-# These are backup files generated by rustfmt
-**/*.rs.bk
-
-# MSVC Windows builds of rustc generate these, which store debugging information
-*.pdb

Cargo.toml

@@ -3,10 +3,10 @@
 [package]
 name = "gravatar-rs"
 description = "Gravatar image URL library"
-authors = ["Holllo <helllo@holllo.cc>"]
-version = "0.1.0"
+repository = "https://git.bauke.xyz/Holllo/gravatar-rs"
 license = "MIT OR Apache-2.0"
-repository = "https://github.com/Holllo/gravatar-rs"
+version = "0.2.3"
+authors = ["Holllo <helllo@holllo.org>"]
 edition = "2021"
 keywords = ["gravatar", "ivatar", "libravatar"]
 
@@ -15,3 +15,7 @@ path = "source/lib.rs"
 
 [dependencies]
 md5 = "0.7.0"
+urlencoding = "2.1.3"
+
+[dev-dependencies]
+insta = "1.34.0"

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Holllo <helllo@holllo.cc>
+Copyright (c) 2022 Holllo <helllo@holllo.org>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile.toml

@@ -0,0 +1,27 @@
+# Do a full check of everything.
+[tasks.complete-check]
+dependencies = [
+  "clean",
+  "format",
+  "check",
+  "clippy",
+  "test",
+  "code-coverage",
+  "docs",
+  "build",
+  "audit-flow",
+  "outdated-flow"
+]
+
+# Run cargo-tarpaulin and output the test coverage.
+[tasks.code-coverage]
+workspace = false
+command = "cargo"
+args = [
+  "tarpaulin",
+  "--exclude-files=target/*",
+  "--out=html",
+  "--output-dir=coverage",
+  "--skip-clean",
+  "--target-dir=target/tarpaulin",
+]

README.md

@@ -1,28 +1,34 @@
-# gravatar-rs
+# Gravatar 📇 Rust
 
-> Gravatar image URL library
+> **Gravatar image URL library for Rust.**
 
 ## API
 
-For full documentation see [docs.rs].
+For full documentation see [docs.rs](https://docs.rs/gravatar-rs).
 
-[docs.rs]: https://docs.rs/gravatar-rs
+## Example
 
 ```rust
 use gravatar_rs::Generator;
 
 let generator = Generator::default();
 
-let gravatar_url = generator.generate("helllo@holllo.cc");
+let gravatar_url = generator.generate("helllo@holllo.org");
 
 assert_eq!(
   gravatar_url,
-  "https://www.gravatar.com/avatar/ebff9105dce4954b1bdb57fdab079ff3"
+  "https://www.gravatar.com/avatar/e9a2c03d607ec80a5b725ad42c19ee36"
 );
 ```
 
+## Development
+
+With [Nix flakes](https://nixos.wiki/wiki/Flakes) and [direnv](https://direnv.net/) installed and enabled, all the required dependencies are automatically loaded from [`shell.nix`](./shell.nix). Then [cargo-make](https://sagiegurari.github.io/cargo-make/) can be used to build, deploy and lint the code. The available tasks are all described in the [`Makefile.toml`](Makefile.toml) configuration.
+
+## Feedback
+
+Found a problem or want to request a new feature? Email [helllo@holllo.org](mailto:helllo@holllo.org) and I'll see what I can do for you.
+
 ## License
 
-This project is licensed under either of [Apache License, Version 2.0](https://github.com/Holllo/gravatar-rs/blob/main/LICENSE-Apache) or [MIT license](https://github.com/Holllo/gravatar-rs/blob/main/LICENSE-MIT) at your option.
-
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in either crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Distributed under the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0.html) and [MIT](https://spdx.org/licenses/MIT.html) licenses, see [LICENSE-Apache](https://git.bauke.xyz/Holllo/gravatar-rs/src/branch/main/LICENSE-Apache) and [LICENSE-MIT](https://git.bauke.xyz/Holllo/gravatar-rs/src/branch/main/LICENSE-MIT) for more information.

flake.lock

@@ -0,0 +1,128 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1705309234,
+        "narHash": "sha256-uNRRNRKmJyCRC/8y1RqBkqWBLM034y4qN7EprSdmgyA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "1ef2e671c3b0c19053962c07dbda38332dcebf26",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1681202837,
+        "narHash": "sha256-H+Rh19JDwRtpVPAWp64F+rlEtxUWBAQW28eAi3SRSzg=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "cfacdce06f30d2b68473a46042957675eebb3401",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1705697961,
+        "narHash": "sha256-XepT3WS516evSFYkme3GrcI3+7uwXHqtHbip+t24J7E=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "e5d1c87f5813afde2dda384ac807c57a105721cc",
+        "type": "github"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "type": "indirect"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1681358109,
+        "narHash": "sha256-eKyxW4OohHQx9Urxi7TQlFBTDWII+F+x2hklDOQPB50=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "96ba1c52e54e74c3197f4d43026b3f3d92e83ff9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1705803528,
+        "narHash": "sha256-nChqKQPRXxmGBEkHse39LjNpkNKk4U1xPQ4a4oYlUdw=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "bd7e8f4e122e11c934a576abc04327764f9bf19b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,17 @@
+{
+  inputs = {
+    flake-utils.url = "github:numtide/flake-utils";
+    rust-overlay.url = "github:oxalica/rust-overlay";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, rust-overlay }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        overlays = [ (import rust-overlay) ];
+        pkgs = import nixpkgs { inherit system overlays; };
+      in
+      {
+        devShells.default = import ./shell.nix { inherit pkgs; };
+      }
+    );
+}

rustup-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "stable"
+components = ["cargo", "clippy", "rustfmt", "rust-src"]

shell.nix

@@ -0,0 +1,18 @@
+{ pkgs ? import <nixpkgs> { } }:
+
+with pkgs;
+
+let
+  rustup-toolchain = rust-bin.fromRustupToolchainFile ./rustup-toolchain.toml;
+in
+mkShell rec {
+  packages = [
+    cargo-audit
+    cargo-edit
+    cargo-insta
+    cargo-make
+    cargo-outdated
+    cargo-tarpaulin
+    rustup-toolchain
+  ];
+}

source/lib.rs

@@ -1,3 +1,6 @@
+#![forbid(unsafe_code)]
+#![warn(missing_docs, clippy::missing_docs_in_private_items)]
+
 //! # gravatar-rs
 //!
 //! This crate provides an API for creating [Gravatar image URLs], and by
@@ -14,24 +17,58 @@
 //!
 //! let generator = Generator::default();
 //!
-//! let gravatar_url = generator.generate("helllo@holllo.cc");
+//! let gravatar_url = generator.generate("helllo@holllo.org");
 //!
 //! assert_eq!(
 //!   gravatar_url,
-//!   "https://www.gravatar.com/avatar/ebff9105dce4954b1bdb57fdab079ff3"
+//!   "https://www.gravatar.com/avatar/e9a2c03d607ec80a5b725ad42c19ee36"
 //! );
 //! ```
+//!
+//! For all possible options see [`Generator`].
 
 /// A generator for Gravatar image URLs.
 #[derive(Debug)]
+#[non_exhaustive]
 pub struct Generator {
+  /// The base URL for images, defaults to `www.gravatar.com`.
   pub base_url: String,
+
+  /// Which default image to use when there is no matching Gravatar, defaults
+  /// to `None`.
+  ///
+  /// See the [Gravatar documentation] for all the possible ways to use it.
+  ///
+  /// [Gravatar documentation]: https://gravatar.com/site/implement/images/#default-image
+  pub default_image: Option<String>,
+
+  /// Whether you always want the default image to be returned, defaults to
+  /// `false`.
+  pub force_default: bool,
+
+  /// A custom size for images, defaults to `None`.
+  pub image_size: Option<i32>,
+
+  /// Whether to include `.jpg` in the image URL, defaults to false.
+  pub include_file_extension: bool,
+
+  /// Which rating should be allowed, defaults to `None`.
+  ///
+  /// See the [Gravatar documentation] for all the possible ratings.
+  ///
+  /// [Gravatar documentation]: https://gravatar.com/site/implement/images/#rating
+  pub rating: Option<String>,
 }
 
 impl Default for Generator {
   fn default() -> Self {
     Self {
       base_url: "www.gravatar.com".to_string(),
+      default_image: None,
+      force_default: false,
+      image_size: None,
+      include_file_extension: false,
+      rating: None,
     }
   }
 }
@@ -42,11 +79,11 @@ impl Generator {
   /// ```rust
   /// use gravatar_rs::Generator;
   ///
-  /// let hash = Generator::hash_email("helllo@holllo.cc");
+  /// let hash = Generator::hash_email("helllo@holllo.org");
   ///
   /// assert_eq!(
   ///   hash,
-  ///   "ebff9105dce4954b1bdb57fdab079ff3"
+  ///   "e9a2c03d607ec80a5b725ad42c19ee36"
   /// );
   /// ```
   ///
@@ -62,8 +99,49 @@ impl Generator {
   pub fn generate(&self, email: &str) -> String {
     let base_url = &self.base_url;
     let hash = Self::hash_email(email);
+    let query_parameters = self.query_parameters();
 
-    format!("https://{base_url}/avatar/{hash}")
+    let file_extension = if self.include_file_extension {
+      ".jpg"
+    } else {
+      ""
+    };
+
+    format!(
+      "https://{base_url}/avatar/{hash}{file_extension}{query_parameters}"
+    )
+  }
+
+  /// Returns all configurable options as a query parameter string.
+  pub fn query_parameters(&self) -> String {
+    /// Shorthand for [`urlencoding::encode`].
+    fn encode<D: std::fmt::Display>(data: D) -> String {
+      urlencoding::encode(&data.to_string()).into_owned()
+    }
+
+    let mut query_parameters = vec![];
+
+    if let Some(default_image) = &self.default_image {
+      query_parameters.push(format!("d={}", encode(default_image)));
+    }
+
+    if self.force_default {
+      query_parameters.push("f=y".to_string());
+    }
+
+    if let Some(image_size) = self.image_size {
+      query_parameters.push(format!("s={}", encode(image_size)));
+    }
+
+    if let Some(rating) = &self.rating {
+      query_parameters.push(format!("r={}", encode(rating)));
+    }
+
+    if query_parameters.is_empty() {
+      String::new()
+    } else {
+      format!("?{}", query_parameters.join("&"))
+    }
   }
 
   /// Configures the Generator to use a custom base URL for generated URLs.
@@ -80,4 +158,90 @@ impl Generator {
       ..self
     }
   }
+
+  /// Configures the Generator to include `d=<default image>` in the URL.
+  ///
+  /// See the [Gravatar documentation] for all the possible ways to use it.
+  ///
+  /// [Gravatar documentation]: https://gravatar.com/site/implement/images/#default-image
+  ///
+  /// ```rust
+  /// use gravatar_rs::Generator;
+  ///
+  /// // Use the "identicon" default image, a geometric pattern based on the
+  /// // email hash.
+  /// Generator::default().set_default_image("identicon");
+  /// ```
+  pub fn set_default_image(self, default_image: &str) -> Self {
+    Self {
+      default_image: Some(default_image.to_string()),
+      ..self
+    }
+  }
+
+  /// When set to true, the Generator will always add `f=y` to the URL. Making
+  /// Gravatar always return the default image.
+  ///
+  /// ```rust
+  /// use gravatar_rs::Generator;
+  ///
+  /// Generator::default().set_force_default(true);
+  /// ```
+  pub fn set_force_default(self, force_default: bool) -> Self {
+    Self {
+      force_default,
+      ..self
+    }
+  }
+
+  /// Configures the Generator to include a `s=<image size>` in the URL.
+  ///
+  /// ```rust
+  /// use gravatar_rs::Generator;
+  ///
+  /// // Get 128px images instead of the default 80px.
+  /// Generator::default().set_image_size(128);
+  /// ```
+  pub fn set_image_size(self, image_size: i32) -> Self {
+    Self {
+      image_size: Some(image_size),
+      ..self
+    }
+  }
+
+  /// Configures the Generator to add `.jpg` to the end of the hash.
+  ///
+  /// ```rust
+  /// use gravatar_rs::Generator;
+  ///
+  /// Generator::default().set_include_file_extension(true);
+  /// ```
+  pub fn set_include_file_extension(
+    self,
+    include_file_extension: bool,
+  ) -> Self {
+    Self {
+      include_file_extension,
+      ..self
+    }
+  }
+
+  /// Configures the Generator to include `r=<rating>` in the URL.
+  ///
+  /// See the [Gravatar documentation] for all the possible ratings.
+  ///
+  /// [Gravatar documentation]: https://gravatar.com/site/implement/images/#rating
+  ///
+  /// ```rust
+  /// use gravatar_rs::Generator;
+  ///
+  /// // Allow G and PG rated images.
+  /// Generator::default().set_rating("pg");
+  /// ```
+  pub fn set_rating(self, rating: &str) -> Self {
+    Self {
+      rating: Some(rating.to_string()),
+      ..self
+    }
+  }
 }

tests/lib.rs

@@ -1,29 +1,58 @@
 use gravatar_rs::Generator;
 
 const BAUKE_EMAIL: &str = "me@bauke.xyz";
-const BAUKE_HASH: &str = "ecd836ee843ff0ab75d4720bd40c2baf";
-
-const HOLLLO_EMAIL: &str = "helllo@holllo.cc";
-const HOLLLO_HASH: &str = "ebff9105dce4954b1bdb57fdab079ff3";
+const HOLLLO_EMAIL: &str = "helllo@holllo.org";
 
 #[test]
 fn test_hash_email() {
-  assert_eq!(Generator::hash_email(BAUKE_EMAIL), BAUKE_HASH);
-  assert_eq!(Generator::hash_email(HOLLLO_EMAIL), HOLLLO_HASH);
+  let samples = [("bauke", BAUKE_EMAIL), ("holllo", HOLLLO_EMAIL)];
+  let mut snapshot = vec![];
+
+  for (name, email) in samples {
+    snapshot.push((format!("hash-{name}"), Generator::hash_email(email)));
+
+    snapshot.push((
+      format!("hash-{name}-whitespace"),
+      Generator::hash_email(&format!("  {email}  ")),
+    ));
+
+    snapshot.push((
+      format!("hash-{name}-casing"),
+      Generator::hash_email(&email.to_uppercase()),
+    ));
+  }
+
+  insta::assert_debug_snapshot!("hash-email", snapshot);
 }
 
 #[test]
 fn test_generator() {
-  let base_urls = [&Generator::default().base_url, "cdn.libravatar.org"];
-  let samples = [(BAUKE_EMAIL, BAUKE_HASH), (HOLLLO_EMAIL, HOLLLO_HASH)];
+  let emails = [BAUKE_EMAIL, HOLLLO_EMAIL];
+  let samples = [
+    ("gravatar", Generator::default().base_url),
+    ("libravatar", "cdn.libravatar.org".to_string()),
+  ];
+  let mut snapshot = vec![];
 
-  for base_url in base_urls {
-    let generator = Generator::default().set_base_url(base_url);
-
-    for (email, hash) in samples {
-      let actual = generator.generate(email);
-      let expected = format!("https://{base_url}/avatar/{hash}");
-      assert_eq!(actual, expected);
-    }
+  for (name, base_url) in samples {
+    let generator = Generator::default().set_base_url(&base_url);
+    let urls = emails.map(|email| generator.generate(email));
+    snapshot.push((format!("generate-{name}"), urls));
   }
+
+  insta::assert_debug_snapshot!("generator", snapshot);
+}
+
+#[test]
+fn test_all_options() {
+  let generator = Generator::default()
+    .set_base_url("cdn.libravatar.org")
+    .set_default_image("identicon")
+    .set_force_default(true)
+    .set_image_size(128)
+    .set_include_file_extension(true)
+    .set_rating("pg");
+
+  let urls = [BAUKE_EMAIL, HOLLLO_EMAIL].map(|email| generator.generate(email));
+  insta::assert_debug_snapshot!("generate-options", urls);
 }

tests/snapshots/lib__generate-options.snap

@@ -0,0 +1,8 @@
+---
+source: tests/lib.rs
+expression: urls
+---
+[
+    "https://cdn.libravatar.org/avatar/ecd836ee843ff0ab75d4720bd40c2baf.jpg?d=identicon&f=y&s=128&r=pg",
+    "https://cdn.libravatar.org/avatar/e9a2c03d607ec80a5b725ad42c19ee36.jpg?d=identicon&f=y&s=128&r=pg",
+]

tests/snapshots/lib__generator.snap

@@ -0,0 +1,20 @@
+---
+source: tests/lib.rs
+expression: snapshot
+---
+[
+    (
+        "generate-gravatar",
+        [
+            "https://www.gravatar.com/avatar/ecd836ee843ff0ab75d4720bd40c2baf",
+            "https://www.gravatar.com/avatar/e9a2c03d607ec80a5b725ad42c19ee36",
+        ],
+    ),
+    (
+        "generate-libravatar",
+        [
+            "https://cdn.libravatar.org/avatar/ecd836ee843ff0ab75d4720bd40c2baf",
+            "https://cdn.libravatar.org/avatar/e9a2c03d607ec80a5b725ad42c19ee36",
+        ],
+    ),
+]

tests/snapshots/lib__hash-email.snap

@@ -0,0 +1,30 @@
+---
+source: tests/lib.rs
+expression: snapshot
+---
+[
+    (
+        "hash-bauke",
+        "ecd836ee843ff0ab75d4720bd40c2baf",
+    ),
+    (
+        "hash-bauke-whitespace",
+        "ecd836ee843ff0ab75d4720bd40c2baf",
+    ),
+    (
+        "hash-bauke-casing",
+        "ecd836ee843ff0ab75d4720bd40c2baf",
+    ),
+    (
+        "hash-holllo",
+        "e9a2c03d607ec80a5b725ad42c19ee36",
+    ),
+    (
+        "hash-holllo-whitespace",
+        "e9a2c03d607ec80a5b725ad42c19ee36",
+    ),
+    (
+        "hash-holllo-casing",
+        "e9a2c03d607ec80a5b725ad42c19ee36",
+    ),
+]