Build a Smart Bookmarking Tool with Rust and Rocket

One of my favorite tools that exists internally is our smart bookmarking tool commonly referred to as “bunnylol.” Originally named bunny1 and open sourced , it’s what we use to navigate across all tools, wikis, knowledge bases, and everything else one might use working at Facebook.

An example of a bookmark I use often is the cal command. I can type in the browser cal and it will take me to our internal calendar tool. Another example is the `wiki` command, which I can use to search our internal wiki pages. I type in `wiki` followed by the name of something I’m looking for and it will provide search results for wiki pages that match what I’m looking for.

As you can imagine, it’s immensely helpful! It also provides a way for us to not only bookmark things like the calendar, but also do things like search wikis using the provided queries. Talk about smart bookmarks, eh?

Today, I’m going to show you how to build a simple clone of bunny1 usingRust andRocket (a web-framework for Rust). The original implementation is written in Python as a web server. We’re going with Rust because it’s:

• Fast
• Type-safe
• Fun to write
• Well-documented as a language

Let’s get to it!

Building the App

Before building the app, I’ll cover how it will work and the prerequisites for following along. After that, I’ll jump in and go through each step before setting it up for production.

How will it work?

Starting from a high-level, the app will work something like this.

1. Open browser
2. In address bar, type a keyword
3. App will redirect if keyword matches one of the commands

Say for instance I was using Firefox and I had a command gh <page/> which redirected to a page on GitHub like a repository. It would look like this:

1. Open Firefox
2. Type in gh facebook/react
3. Redirects to https://github.com/facebook/react

Here is that flow in action:

I want to dig more into the technical details of this approach. I can achieve this by building a basic web server app that listens for requests and redirects them based on if it matches specific criteria. I am not building a client-side app because the only functionality I need is a redirect so it makes more sense to be built as a web server.

Using the same example, the application logic will flow like this:

I will use acustom search engine which will allow me to connect the address bar to my own search engine. With the basic flow down, I am ready to move on to the next step!

Prerequisites

In order to start writing the Rust application, I will need to do a few things:

• Install Rust
• Switch to Nightly Rust
• Set up VS Code for Rust
• Test Rocket with Hello World

I will walk through each of these.

Install Rust

To install Rust, I will use a tool calledrustup. You can install it by running the command:

shell
          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This will install rustup which is used for installing Rust and staying up to date with different versions of the language. After you run it and follow the instructions, you should have Rust installed.

You can double-check by running:

shell
          cargo --version

shell
          rustup default nightly

You can always change it back to the stable version by running:

shell
          rustup default stable

Set up VS Code for Rust

For this walkthrough, I suggest usingVS Code as an editor.

Make sure to install theRust(rls) extension, which will make it a lot easier to build the app thanks to code completion and other handy features.

If you’re looking to add the extension in another editor, you can take a look at therust-lang website to see if it’s supported.

Test Rocket with Hello World

To make sure you’re ready to develop with Rocket, I’ll walk you throughtheir “Hello world” getting started application.

Create a new project and cd into it by running:

shell
          cargo new rusty-bunny --bin
          cd rusty-bunny

Add Rocket as a dependency to your Cargo.toml like so:

diff
          [dependencies]
          +    rocket = "0.4.4"

Modify the src/main.rs so that it looks like this:

rust
          #![feature(proc_macro_hygiene, decl_macro)]

          #[macro_use] extern crate rocket;

          #[get("/")]
          fn index() -> &'static str {
              "Hello, world!"
          }

          fn main() {
              rocket::ignite().mount("/", routes![index]).launch();
          }

Inside the hello-rocket directory, run the command:

shell
          cargo run

rust
          #[get("/search")]
          fn search() -> &'static str {
              "Hello from the search page!"
          }

I copied this from the root route (“/”). Before I can test, I need to inform Rocket that there is a new route. Near the bottom, make the following adjustments and add “search” to the array after “index”:

diff	
          fn main() {
          +    rocket::ignite().mount("/", routes![index, search]).launch();
          }

diff
          +#[get("/search?<cmd/>")]
          +fn search(cmd: String) -> &'static str {
          +    println!("You typed in: {}", cmd);
               "Hello from the search page!"
          }

Here, I made the following changes:

1. I added a query param to the route as “cmd”
2. I modified the params for our `search` fn so it can receive the query param value

This means when you visit http://localhost:8000/search?cmd=tw , you will see “You typed in: tw” logged to your terminal console (where you ran `cargo run`). Go ahead and try it out!

Now that I have the search route ready that accepts query params, I can move on to the next step.

Parsing Commands and Redirecting

The next piece of logic that I’m going to add to the application is parsing the command from the query string and then redirecting based on that string.

Parsing Query String

I will set up our logic so that it grabs all the characters up to the first whitespace in the query string and uses that as the command.

To start this off, go ahead and write a unit test using Rust’s built-in testing features. At the bottom of src/main.rs , add the following code:

rust
          fn get_command_from_query_string(query_string: &str) -> &str {
              let test = "hello";
              return &test;
          }

          #[cfg(test)]
          mod tests {
              use super::*;

              #[test]
              fn test_get_command_from_query_string_no_whitespace() {
                  // Test with command only
                  let actual = get_command_from_query_string("tw");
                  let expected = "tw";
                  assert_eq!(actual, expected);
              }
              #[test]
              fn test_get_command_from_query_string_with_whitespace() {
                  let actual = get_command_from_query_string
                  ("tw @fbOpenSource");
                  let expected = "tw";
                  assert_eq!(actual, expected);
              }
          }

I first add a function called get_command_from_query_string which I will use to parse the query string. For now, it always returns the word “hello” along with two unit tests for the function. You can read more about unit testing in the Rust By Example BookUnit testing chapter.

The tests will ensure I can get the command when I have a query string with whitespace and without. This will ensure I can use commands that take arguments such as navigating to a user’s Twitter profile page.

To run this and watch it fail, run cargo test in your terminal.

Now, I’m going to modify the function so the tests pass.

diff
          fn get_command_from_query_string(query_string: &str) -> &str {
          -    let test = "hello";
          -    return &test;
          +    if query_string.contains(' ') {
          +        // We need to this to know where to slice the string
          +        let index_of_space = query_string.find(' ').unwrap_or(0);
          +        return &query_string[..index_of_space];
          +    }
          +    // Otherwise, return the query string as is
          +    query_string
          }

diff
        #![feature(proc_macro_hygiene, decl_macro)]

        #[macro_use] extern crate rocket;

        + use rocket::response::Redirect;

        #[get("/")]
        // ...

Then modify the search route return type and return a basic Redirect to https://www.google.com/ .

diff
        #[get("/search?<cmd/>")]
        +    fn search(cmd: String) -> Redirect {
                 println!("You typed in: {}", cmd);
        -        "Hello from the search page!"
        +        let redirect_url = "https://google.com";
        +        Redirect::to(redirect_url)
             }

Test it in your browser by restarting the server and running cargo run and navigate to http://localhost:8000/search?cmd=hello . If it redirects you, then it worked!

The last step is to add the function I created to parse the command, and then redirect based on what it gets. I’ll add that in.

diff 
          #[get("/search?<cmd/>")]
          fn search(cmd: String) -> Redirect {
               println!("You typed in: {}", cmd);
          +    let command = get_command_from_query_string(&cmd);

          +	let redirect_url = match command {
          +    	"tw" => String::from("https://twitter.com"),
          +  	_ => String::from("https://google.com")
          +	};

          	Redirect::to(redirect_url)
          }

diff
           + pub fn get_command_from_query_string(query_string: &str) -> &str {
           //...

rust
          pub fn construct_google_search_url(query: &str) -> String {
              // TODO add logic 
              String::from("https://google.com/search?q=test")
          }
          #[cfg(test)]
          mod tests {
              use super::*;

              #[test]
              fn test_construct_google_search_url() {
                  let fake_query = "hello";
                  assert_eq!(
                  construct_google_search_url(fake_query),
                  "https://google.com/search?q=hello"
              );
          }
          #[test]
          fn test_construct_google_search_url_with_encoding() {
              let fake_query = "hello world";
              assert_eq!(
                  construct_google_search_url(fake_query),
                  "https://google.com/search?q=hello%20world"
          		);
          	}
          }

Before I can run our test, Cargo needs to find it, which means it needs to be referenced in a main.rs or from a sub-module used in main.rs . Inside src/utils/mod.rs , add the line pub mod google; to the top. This includes the google modules with our utils module so that Rust knows it’s used in the program and will include the tests.

Running cargo test , you should see it fail. Next, I’ll make it pass!

The first thing I need to do is add a dependency which will encode the query string and pass the second test. Inside your Cargo.toml , add the following:

diff
           [dependencies]
           rocket = "0.4.4"
           +percent-encoding = "2.1.0"

Thepercent-encoding crate will do the heavy lifting of the encoding for you. Now, make the following changes to src/utils/google.rs :

diff
          +    extern crate percent_encoding;

          +    use percent_encoding::{utf8_percent_encode, AsciiSet, CONTROLS};

          // Used as part of the percent_encoding library
          +    const FRAGMENT: &AsciiSet = &CONTROLS.add(b' ').add(b'"')
               .add(b'<').add(b'>').add(b'`');

          pub fn construct_google_search_url(query: &str) -> String {
          -    String::from("https://google.com/search?q=test"
          +    let encoded_query = utf8_percent_encode(query, FRAGMENT)
               .to_string();
          +    let google_search_url = format!(
               "https://google.com/search?q={}", encoded_query);

          +    google_search_url
          }

I made some significant changes. First, I used the extern keyword at the top to let Rust know that I’m using an external dependency in this module. Then, I imported a few utilities from the crate.

Next, I used the const to declare a new variable. I did that so that Rust can work its magic now that it knows the value will never change (hence “const” for “constant”). As you can see from the type, it’s an AsciiSet . I won’t dive down the rabbit hole here. Know that it’s extending the provided CONTROLS AsciiSet and adding the following characters: whitespace, double-quote, angled brackets and the back-tick.

Inside the functions, I have two new let`s: one for the encoded_query and one for the google_search_url . It takes in the query as a parameter, encodes it, and then returns it to the function caller.

Now I want to see if the tests pass by running cargo test . And they do! Woohoo!

I’ll head back over to src/main.rs where I’ll add in the new utility function:

diff
          #[get("/search?<cmd>")]
          fn search(cmd: String) -> Redirect {
              println!("You typed in: {}", cmd);
              let command = utils::get_command_from_query_string(&cmd);

              let redirect_url = match command {
                  "tw" => String::from("https://twitter.com"),
          +       _ => utils::google::construct_google_search_url(&cmd)

              };

              Redirect::to(redirect_url)
          }

rust
           pub fn construct_twitter_url(query: &str) -> String {
               // fill in logic
               String::from("Hello world")
           }

           pub fn construct_twitter_profile_url(profile: &str) -> String {
               // fill in logic
               String::from("Hello world")
           }

           pub fn construct_twitter_search_url(query: &str) -> String {
               // fill in logic
               String::from("Hello world")
           }

           #[cfg(test)]
           mod tests {
               use super::*;

               #[test]
               fn test_construct_twitter_url() {
                   let fake_query = "tw";
                   assert_eq!(construct_twitter_url(fake_query), 
                   "https://twitter.com");
               }

               #[test]
               fn test_construct_twitter_url_query() {
                   let fake_query = "tw hello world";
                   assert_eq!(construct_twitter_url(fake_query),     
                   "https://twitter.com/search?q=hello%20world");
               }

               #[test]
               fn test_construct_twitter_url_profile() {
                   let fake_query = "tw @fbOpenSource";
                   assert_eq!(construct_twitter_url(fake_query), 
                   "https://twitter.com/fbOpenSource");
               }

               #[test]
               fn test_construct_twitter_profile_url() {
                   let fake_profile = "jsjoeio";
                   assert_eq!(
                       construct_twitter_profile_url(fake_profile),
                       "https://twitter.com/jsjoeio"
                   );
               }

               #[test]
               fn test_construct_twitter_search_url() {
                   let fake_query = "hello world";
                   assert_eq!(
                       construct_twitter_search_url(fake_query),
                       "https://twitter.com/search?q=hello%20world"
                   );
                }
           }

diff
         pub mod google;
         +    pub mod twitter;

Run cargo test and see the tests all fail. Great. I’m ready to make them pass!

Working backwards, I’ll start with the construct_twitter_search_url since it is most similar to the smart Google redirect. Inside src/utils.twitter.rs , make the following changes:

diff
          +extern crate percent_encoding;

          +use percent_encoding::{utf8_percent_encode, AsciiSet, CONTROLS};

          // Used as part of the percent_encoding library
          +    const FRAGMENT: &AsciiSet = &CONTROLS.add(b' ').add(b'"')
               .add(b'<').add(b'>').add(b'`');

          //…

          pub fn construct_twitter_search_url(query: <str) -> String {
          -    String::from("Hello world"
          +    let encoded_query = utf8_percent_encode(query, FRAGMENT).to_string();
          +    let twitter_search_url = format!("https://twitter.com/search?q={}", 
    	         encoded_query);

          +    twitter_search_url
          }

And now I can run our test for this function by running:

shell
          cargo test -- test_construct_twitter_search_url

The -- tells cargo to look for exactly this test and this test only. Great, that passes. Next up, I want to tackle the construct_twitter_profile_url . This one is straightforward. It takes in the profile and then appends it to https://twitter.com/ to visit the profile page.

diff
          pub fn construct_twitter_profile_url(profile: &str) -> String {
          -    String::from("Hello world")
          +    format!("https://twitter.com/{}", profile)
          }

The logic related to parsing the username from tw @username will come in the next function. Here it only needs to replace the {} with profile and then return the string. I use theformat! macro provided by Rust. Now, I’m going to run this exact test by running:

shell
          cargo test -- test_construct_twitter_profile_url

Finally, I’m going to add the logic for the main construct_twitter_url function. Modify the function to match this and then I’ll go over what’s happening:

diff
          pub fn construct_twitter_url(query: &str) -> String {
          -     String::from("Hello world")
          +    if query == "tw" {
          +        let twitter_dotcom = "https://twitter.com";
          +
          +        twitter_dotcom.to_string()
          +
          +     // Check if it looks like a Twitter profile
          +	    } else if &query[..4] == "tw @" {
          +         construct_twitter_profile_url(&query[4..])
          +	    } else {
          +         // Assume the other match is "tw sometext"
          +         // and search on Twitter
          +         construct_twitter_search_url(&query[3..])
                }
          }

First, it checks if the query string matches “tw” meaning the user entered “tw” with no other text. If so it sends them to the Twitter homepage. Otherwise, it checks if the first 4 characters match “tw @”. If it does, then it constructs a twitter profile url. The final alternative is taking the text and using it in a search query.

I’m going to run the tests to make sure things are working as expected using cargo test . And they do! Great. The last step is to add this to the main function.

diff
          let redirect_url = match command {
          +    "tw" => utils::twitter::construct_twitter_url(&cmd),
               _ => utils::google::construct_google_search_url(&cmd)

          };

rust
          extern crate percent_encoding;

          use percent_encoding::{utf8_percent_encode, AsciiSet, CONTROLS};

          // Used as part of the percent_encoding library
          const FRAGMENT: &AsciiSet = &CONTROLS.add(b' ').add(b'"').add(b'<')
          .add(b'>').add(b'`');

          pub fn construct_github_url(query: &str) -> String {
              if query == "gh" {
                  let github_dotcom = "https://github.com";

                  github_dotcom.to_string()
              } else {
                  // Assume the other match is "gh page"
                  let encoded_query = utf8_percent_encode(&query[3..], FRAGMENT)
                  .to_string();
                  let github_url = format!("https://github.com/{}", encoded_query);

                  github_url
              }
          }

          #[cfg(test)]
          mod tests {
              use super::*;

              #[test]
              fn test_construct_github_profile_url_with_gh() {
                  let fake_query = "gh";
                  assert_eq!(construct_github_url(fake_query), "https://github.com");
              }

              #[test]
              fn test_construct_github_profile_url_with_repo_url() {
                  let fake_query = "facebook";
                  assert_eq!(
                     construct_github_url(fake_query),
                     "https://github.com/facebook"
                  );
              }

              #[test]
              fn test_construct_github_search_url_with_repo_url() {
                  let fake_query = "gh facebook/docusaurus";
                  assert_eq!(
                      construct_github_url(fake_query),
                      "https://github.com/facebook/docusaurus"
                  );
              }
          }

diff
          let redirect_url = match command {
          +    "gh" => utils::github::construct_github_url(&cmd),
               "tw" => utils::twitter::construct_twitter_url(&cmd),
               _ => utils::google::construct_google_search_url(&cmd)
          };

text
              /target/*
              !/target/release