
> Cover image created by me using [Ferris the Crab], [the Rust logo], and [the FastAPI logo].

_This post is part of a series. If you haven't already, you may want to read the [previous post] before continuing._

---

In the [previous post], I decided that Rocket is the best candidate to replace FastAPI with two big caveats:

1. It _requires_ nightly Rust, and therefore [unstable features](https://doc.rust-lang.org/stable/book/appendix-07-nightly-rust.html#unstable-features).
2. It is not async, and therefore not compatible with my favorite option for handling SQL: [SQLx].

Both of these issues are fixed on the `master` branch of the Rocket repository, which will become Rocket 0.5 once released. However, hosting a Rocket application on AWS Lambda requires a crate called `rocket_lamb` which will need to be updated for Rocket 0.5 before it will work.

In this post, I walk through my experience updating `rocket_lamb` to support the latest development version of Rocket in an effort to prepare it for the inevitable 0.5 Rocket release. The highlights are:

1. My general purpose process for refactoring in Rust
2. How to solve async lifetime issues using `Arc` and `Mutex`
3. Some thoughts on testing methodology

## Step 1: Just Try It!

One of the nicest things about Rust's strict compiler is that you can generally refactor by following the errors. If you also have good test coverage in your project, you can be even more confident! So far in my Rust journey, I’ve been able to follow this process in every significant refactor:

1. Just do the thing you’re trying to achieve.
2. Run `cargo check`, fix errors, rinse, and repeat.
3. Run `cargo test`, fix failures, rinse, and repeat.
4. It just works!

So in this case, step 1 is to replace Rocket 0.4 with the current development version using a Git dependency and replace all the `lambda_` crates with the equivalent `lamedh_` crates. This all happened [in this commit](https://github.com/dbanty/rocket-lamb/commit/2d4fe5102dcc23898941f9c8bb2374e831f6d5eb) if you’d like to follow along. Here’s a summary:

### Step 1.0: Replace the Dependencies

In addition to the changes mentioned above, I had to change out the `http` version based on some `cargo check` complaints. I also needed to add `aws_lambda_events`, `tokio`, and `parking_lot` for some code changes that come later. All in all, here are the changes:

#### Before

```toml
rocket = { version = "0.4.0", default-features = false }
lambda_runtime = "0.2.1"
lambda_http = "0.1.1"
http = "0.1"
failure = "0.1.5"
```

#### After

```toml
rocket = { git = "https://github.com/SergioBenitez/Rocket", branch = "master", default-features = false }
lamedh_runtime = "0.3.0"
lamedh_http = "0.3.0"
http = "0.2.3"
failure = "0.1.5"
aws_lambda_events = "0.4.0"
tokio = "1"
parking_lot = "0.11.1"
```

Cargo (or maybe it’s `rustc` under the hood?) can provide pretty helpful error messages in this process, though sometimes you have to know what to look for. I always recommend reading the _entire_ output of Rust compiler errors. In other languages (notably Python) I’m used to looking at stack traces where I’ve gotten good at ignoring most of the content since it’s not relevant to the problem I’m solving. A ton of care is taken in designing Rust compiler messages, so all of the information is likely to be relevant. In the case of `http` being on the wrong version, the error was something like `expected struct http::Method, found struct lamedh_http::http::Method` however there is a note which says “perhaps two different versions of crate `http` are being used?” informing you of exactly the problem!

### Step 1.1: Update the Imports

If you’re replacing one package with another, the next step after updating your `Cargo.toml` is to update all the `use` statements. Going from `lambda_` to `lamedh_` was _mostly_ straight forward, just replace one crate with the equivalent. There were a couple notable exceptions though:

1. Instead of using a `lambda!` macro to start things up, you want to use the `lamedh_runtime::run` function, which takes the result of the `lamedh_http::handler` function. I prefer explicit function invocations anyway over macros when it doesn’t make a huge difference to readability (that’s foreshadowing).
2. `lambda_http` was re-exporting `aws_lambda_events::encodings::Body` but `lamedh_http` does not, so that had to be imported separately.

### Step 1.2: Update the Code

There were some API differences both in the new `rocket` version and in the `lamedh_` conversion that had to be handled here:

1. `rocket::local` was split into `rocket::local::blocking` and `rocket::local::asynchronous` so you can choose how you handle things. I picked `blocking` for now just to minimize the up front changes. I go back and update it to `asynchronous` later.
2. The `Handler` trait from `lamedh` switches the `run` function for one called `call` and requires an associated `Fut` type.
3. The `RequestContext` from `lamedh` has been completely reorganized and supports the newer API Gateway v2 requests. At this point, being new to the code base, I wasn’t entirely sure what the `base_path` method of `RequestExt` was doing, so I just commented out most of the logic.

## Step 2: Check and Check and Check

I’ve now entered the stage where I’m repeatedly running `cargo check` and fixing the errors I’ve found. I quickly came to a similar issue to the one I faced when implementing my own `Handler` for `actix-web`. Passing data to the `Future` doing the actual handling requires some hoop-jumping. The code changes for Step 2 can be found [in this commit](https://github.com/dbanty/rocket-lamb/commit/6a995b1b977675736fa32d96e1094ba3fcc05098).

### Step 2.1: Solving Async References

The `Fut` associated type on `Handler` requires that any lifetimes be `’static`, presumably so the `Future` can live longer than the `Handler` that spawned it (though I’m not sure why you’d want this). In any event, the `Handler` code I inherited from the existing `rocket_lamb` crate was passing `&mut self` to the now-asynchronous code which left me a bunch of errors saying something about needing `’static` lifetimes.

At this point I was thoroughly lost, if I needed to pass data to something, and some trait outside of my control was requiring it to be `'static`, then I couldn’t pass references right? I didn’t want to clone all the data for every request, as doing so would be very inefficient. Even if I wanted to do that, some of the data I needed to pass was not `Clone`. I decided to go out on a limb and ask for help. Asking questions in open source projects is always nerve-wracking, as some of the responders can be quite hostile. However, one of the contributors to the `lamedh_` crates quickly dispelled my fears by coming through with a friendly answer!

I had heard of, though never used, `std::sync::Arc` before. I’m not really qualified to explain how this works, but I’ll do my best to convey _my_ understanding. `std::rc::Rc` effectively lets you have shared, read-only ownership of an object. If you do something like this:

```rust
use std::rc::Rc;

let original = String::from("blah");
let first = Rc::new(original);
let second = Rc::clone(&first);
```

Then you effectively end up with two different owned values `first` and `second` which can be dereferenced to read data as if it were `original` (note that creating `first` took ownership of `original` so you can’t access that one anymore). Because the values are owned, you’re not passing references, and therefore don’t have to worry about lifetimes!

This isn’t magic, `Rc` stands for “reference counting” which is a common way of handling memory in more dynamic languages (e.g. Python). Behind the scenes, Rust is keeping track of how many times `Rc::clone` has been used for a given piece of data and once they’re _all_ dropped, it will free the memory. So even if `Handler` goes out of scope and gets dropped with a `Future` still on the loose, the data it was given is still perfectly valid!

“Wait a second, you said you were using `Arc` though?!” Yep! `Arc` is just the version of `Rc` that is `Send`, meaning it is safe in threaded contexts. Because we’re using Tokio and Tokio can use threads to execute `Future`s, everything has to be `Send` and therefore we use `Arc`! And thus the problem of sharing data in Tokio futures is solved!

### Step 2.1: Being Less Selfish

In order to aid me with `Arc`ing the codebase, I pulled out most of the methods on `RocketHandler` into functions which took just the data they needed rather than the whole `self`. This made it _way_ easier to reason about the code and make faster, more confident modifications. I prefer this style anyway because it makes it clear when you _call_ something exactly what that something is taking. An object-oriented “method” style hides whether something is just reading data, or mutating it, or outright consuming it until you jump to definition. Why not take full advantage of how explicit Rust is? Here's an example to illustrate my point:

```rust
// Method style
handler.ensure_client_ready(&request)

// Function style
ensure_client_ready(&mut handler.client, &handler.config, &request)
```

It's more verbose, but now I can clearly see that I need to `Arc` the handler's config attribute to share it in this manner and that the `handler.client` needs to be mutable, so I need some way to deal with that. Also, I'm not sure how I would go about `Arc`ing the entire `RocketHandler` anyway to pass it through to methods in a thread-safe manner, so I had to pick functional style whether I wanted to or not.

### Step 2.2: Disabling a Feature

That `ensure_client_ready` function from before required mutability and was fairly dense code related to what I disabled in step 1.2.3. So for now, I just removed this feature as well, figuring I’d come back to it once I understood the code better.

And with that, `cargo check` passed! Next it was on to `cargo test` , which of course couldn’t even complete the compilation step to start with.

## Step 3: Testing

Automated tests in your project are primarily important for two reasons:

1. If some hooligan comes along trying to refactor your entire project to work with different libraries, they can have some confidence of knowing they didn’t break anything once they’re done.
2. Tests serve as documentation that is often far more specific than is worth putting in comments. If you properly cover all the behavior of your code and do so with relatively readable tests, then a contributor can read the tests to discover what the code is supposed to be doing.

### Step 3.1: Async Tests

Now that most of the code required async, the tests had to know how to handle async as well! Tokio provides a convenient `#[tokio::test]` macro to replace the normal `#[test]` with in order to allow your test functions to be `async`. This, along with replacing some imports, was done by another contributor who’d been following my progress and wanted to help out! Isn’t the open source community amazing when people work together? You can see their work [here](https://github.com/dbanty/rocket-lamb/commit/6a995b1b977675736fa32d96e1094ba3fcc05098).

Building on top of what they had, I did a bit more work to finish getting the tests to compile which mostly involved switching to the `asynchronous` Rocket client and to stable Rust (!!!). You can see those changes [in this commit](https://github.com/dbanty/rocket-lamb/commit/3f5ece7a610921f834323cc0e1461406eaa18f91). I also had to make the doctests work with async which basically just involved wrapping any async code in the doc comments with `tokio_test::block_on()` [like this](https://github.com/dbanty/rocket-lamb/blob/92d3049fd9fdc9ec66866655b310cf51cac1fe05/src/builder.rs#L46).

### Step 3.2: Making Tests Less DRY

DRY is an acronym for a mantra that is often preached in software development: “Don’t Repeat Yourself”. This advice _can_ be beneficial, but only when not taken at face value. Personally I prefer my code like I prefer my food: MOIST. That is, “Maintain One Indisputable Source (of) Truth” (yes that is a [backcronym](https://en.wikipedia.org/wiki/Backronym), no I’m not sorry). The main reason to not repeat code is that it’s easy for multiple sources to get out of sync and thereby cause bugs. One should not remove duplicated code simply because it’s duplicated, but rather to keep the implementation in sync.

DRY becomes particularly painful when applied to tests. If tests are to serve as documentation for your code, someone must be able to easily understand what a test is doing. Using a macro to effectively [parametrize](https://docs.pytest.org/en/stable/parametrize.html#parametrizing-fixtures-and-test-functions) a test means that:

1. It’s not immediately clear where a test is defined when it fails to run or compile using `cargo test`.
2. You have to read macro code to figure out what the test is doing, which is always more difficult than reading Rust code directly.
3. Failures/panics can be particularly hard to debug when they come from inside generated code.
4. Most tooling just doesn’t work as well. For example, using CLion, I cannot easily click to run a single test which is generated in a macro like I can with normal functions. I also can’t jump to definition of code defined within the macro.

All of that was to say that `rocket_lamb` had a file full of test cases, each of which was defined with a macro (presumably to reduce duplication) which were failing and hard to debug. Rather than continue to guess as to the problem, I rewrote the tests using standard Rust code instead of a macro, keeping some shared setup in a separate function so that if we change the way the `RocketHandler` is built, for instance, there is a single location which defines that.

Refactoring into standard Rust code also made it completely obvious what the features I had removed were trying to do.

### Step 3.3: Mutation and Arcs

As I had mentioned earlier, there were two related pieces of code that I had removed to skip while implementing the basic async conversion. The first piece was pulling information out of the raw lambda request. The second piece was mutating some shared data in order to modify the rocket `Client` before using it. Reading the failing tests gave me the last bit of context I needed to reimplement these features.

API Gateway is the service often used to route requests to Lambda functions, and it allows you to modify the paths of these requests either to add a fixed base path (e.g. /v2/) or a stage (e.g. /QA/). The application will likely not be aware of these changes, since they’re probably specific to the deployment. There are a few approaches I see to solve this problem:

1. Have a feature flag or something and compile the full path into the application at build time. This has the huge downside of not being able to promote a /canary/ instance to prod, for example, without rebuilding.
2. Erase any base path or stage before giving the request to the application. So a request with the path `/canary/v2/hello` might just surface as `/hello` to Rocket. This will work, but it means any response headers from Rocket won’t include the same path that the client attempted to reach, which could cause problems.
3. Update the Rocket application to use the full paths at runtime. Specifically, delay building the `Client` which does request handling until after you receive the first request. From that request you can determine any base path and stage and rewrite the Rocket routes on the fly before generating a client. _This_ is what that feature was doing.

So if we want to maintain this feature (which seems like a good idea because presumably people are using it), we have to be able to mutate some shared state in an asynchronous context. You’ll remember, however, that our shared data is now behind an `Arc` and that `Arc` only provides read access to consumers. So how do we mutate it? Well there are a few solutions provided in the standard library, but I went with `Mutex` from a crate called `parking_lot` which is just a bit easier to use than the one in `std`.

I went back to a similar pattern that `rocket_lamb` had originally. It was using an enum that looked like this:

```rust
enum LazyClient {
    Placeholder,
    Uninitialized(Rocket),
    Ready(Client),
}
```

The `LazyClient` was shared directly with the handler code (safe because it wasn’t async). It was set to `Uninitialized` with the original Rocket instance at startup. Upon receiving the first request, the handling code would use `mem::replace` to get the owned Rocket and leave a `Placeholder` in its place (again, safe because the code was blocking, so nothing will reach this same code once it became `Placeholder`). Finally, it updated all the routes in the `Rocket` instance with any base path or stage before transforming that `Rocket` into a `Client` and setting the state to `Ready`. Future requests would simply see that it’s already `Ready` and use the `Client`.

Because anything which is threaded is naturally harder to deal with safely, I had to make a bunch of changes here. This is my first real foray into dealing with these sorts of problems, so if you have suggestions for improvements let me know! My enum looks like this:

```rust
enum LazyClient {
    Uninitialized(Option<Rocket>),
    Ready(Arc<Client>),
}
```

And I passed it to the handling `Future` as an `Arc<Mutex<LazyClient>>`. This way it’s safe to pass into the future without lifetime issues (because of the `Arc` thing mentioned before) and safe to mutate because of the `Mutex`. The only other difference is that I use an `Option<Rocket>` so I can `.take()` the owned `Rocket` instead of using `mem::replace` with another enum type (mostly because I had a lot of trouble getting this to work with the `Mutex`).

The obvious problem I see with my new code is it will have significantly more overhead than the old version due to all the indirection and the hard lock. Hopefully it’s not slow enough to matter much, and hopefully someone with more experience can tune it up a bit. All of the changes required to get this feature working again (including test refactors) can be found [here](https://github.com/dbanty/rocket-lamb/commit/47671b79b102402ebcf82c715dcd866079a741f4).

## Conclusion

That’s it! [My fork of rocket_lamb](https://github.com/dbanty/rocket-lamb/tree/rocket-0.5) now works with the development version of `rocket` and the latest `tokio`. I was even able to get [my rocket experiment](https://github.com/dbanty/rust-fastapi-experiments/tree/rocket-0.5) working with the latest `rocket` by combining my fork with [a fork of okapi which has been updated](https://github.com/dbanty/okapi/tree/async2). So what’s next? Well now that everything has been updated, in theory my endpoints can be async, which means I should finally be able to use [SQLx] with this project!

---

_Have a question or comment about this post? Leave it in the [discussions] thread on GitHub!_

_Want to be notified when the next part of this series is released? Watch releases in [the GitHub repo]._

_Have an idea or request for a future blog topic? Drop it in the GitHub discussions under [ideas]._

[ferris the crab]: https://www.rustacean.net
[the rust logo]: https://www.rust-lang.org/policies/media-guide
[the fastapi logo]: https://github.com/tiangolo/fastapi
[discussions]: https://github.com/dbanty/dylananthony.com/discussions/26
[ideas]: https://github.com/dbanty/dylananthony.com/discussions/categories/ideas
[the github repo]: https://github.com/dbanty/dylananthony.com
[previous post]: https://dylananthony.com/posts/fastapi-rust-4-a-solution
[sqlx]: https://crates.io/crates/sqlx


Replacing FastAPI with Rust: Part 5 - Rocket 0.5


> Cover image created by me using [Ferris the Crab], [the Rust logo], and [the FastAPI logo].

_This post is part of a series. If you haven't already, you may want to read the [previous post] before continuing._

---

After investigating a few more options, I've finally decided on a framework to use. Here's how I got there, step by step.

## [rweb]

As planned, I started with [rweb]. This framework was ranked second of the three options I considered in [part 2] of this blog series. As a short reminder, this framework is built around [warp] and seems to provide most of the features I'm looking for. My main reservations are about the maintenance and community around this project.

I started out by copying and pasting the example from the docs and trying to run it. I noticed right off the bat that the version included in the example is much older than the latest released version, so I went ahead and updated that. Attempting to run the example produced a series of issues:

1. The example doesn't include the `tokio` "macros" feature or `serde` as a dependency, both of which were required. Easy enough to fix.
2. `rweb` requires `rweb-macros` which requires a different version of `rweb-openapi` than `rweb` itself does, so you get two different copies of that. I assume this was just a failure to update internal versions on release at some point. All three of these crates are in the same GitHub repository.
3. CLion (my editor of choice) highlights a syntax error because of the way endpoints are registered. Basically, it seems like the macros transform the functions into something completely different. You then call the functions to register them, but CLion is expecting you to pass the input params (e.g. json body) to the function which you aren't doing.
4. The code doesn't compile because it was using a module of `syn` which was documented as internal only and do not use. The maintainers of `syn` changed the name of that module which broke `rweb`. There are a couple of sub-issues here:
   1. rweb was using an internal module of `syn` which it should not have been. This seems to be a common issue though or `syn` would not have been changed to make the internal code more internal.
   2. Someone reported this as an issue, but the maintainer closed it without investigation. With additional prodding from both myself and the issue opener the maintainer fixed the problem.

All of this basically confirmed my fears about rweb. The maintenance and stability of the project are not consistent enough for me to be comfortable relying on it. By the time the maintainer fixed the issue, I'd already investigated two other frameworks and chosen one.

## [DropShot]

I received a DM on [Twitter] from @ayper recommending I take a look at this project. It's certainly very interesting, though also very young. It seems like this project's goals may align with my own though it would take some work to get there. Specifically, right now there is no way to make offline direct requests as I need for a serverless environment. It seems like even their test utilities (which is where you usually see offline invocation) use a local webserver. I'll definitely be keeping my eyes on this in the future though to see where it goes.

## [Rocket]

Yes, Rocket. The framework I pretty much immediately discounted in [part 2]. I'm not too proud to admit that I was wrong. Between my frustrations with other frameworks and a glowing review [on Dev.to][rocket comment] I had to at least try it. The results were... fantastic.

Okay so this solution doesn't resolve either of my main misgivings about Rocket because it uses the released 0.4 version. The code still requires nightly rust and still does not support async, but both of these have already been resolved on Rocket's "master" branch and therefore will be present in the 0.5.0 release. Then it's just a matter of updating supporting packages.

Getting this all to work was a breath of fresh air compared to previous attempts. I started by copying the official JSON example and tweaking it to have the same pet echo behavior I used in my actix experiment. The code basically looked like this:

```rust
#![feature(proc_macro_hygiene, decl_macro)]

#[macro_use]
extern crate rocket;
#[macro_use]
extern crate serde_derive;

use rocket_contrib::json::Json;

#[derive(Serialize, Deserialize)]
struct Pet {
    name: String,
    id: Option<i64>,
}

#[post("/echo", format = "json", data = "<pet>")]
fn echo(pet: Json<Pet>) -> Json<Pet> {
    pet
}

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

Pretty simple. That code handles validation, serialization, and deserialization. Now I just needed to add in AWS Lambda support and OpenAPI documentation.

## AWS Lambda Support

[rocket_lamb] uses the last release of the official AWS runtime which is based on an older version of Tokio, so it will take some work to update it for Rocket 0.5 once it's ready. There was one issue I encountered while running this, but the maintainer responded within a day, and it turned out to be an issue with AWS SAM. So all I had to do to make my code work with `sam invoke start-api` was to:

1. Downgrade to aws-sam-cli 1.12.0 to avoid the bug
2. `cargo add rocket_lamb`
3. Add `use rocket_lamb::RocketExt;` with the rest of my imports.
4. Add `.lambda()` before `.launch()` in main.

That's it! So easy! And this crate clearly has a responsive and helpful maintainer, great!

## OpenAPI Documentation

[okapi] was clearly the way to go here and also happens to have the same maintainer as [rocket_lamb]. This process was also super simple:

1. Add `okapi`, `rocket_okapi`, and `schemars` (0.7) as dependencies.
2. Copy a couple of things from the example in the README
3. There is no step three

Now I have a self-documenting API compatible with AWS Lambda with very minimal work on my part. [okapi] even comes with a functional (if a bit outdated) Swagger UI, just like FastAPI does!

## Requirements Check

Let's check in with our list of requirements for a FastAPI solution and see where we're at.

1. _"MUST be written in Rust."_ Yup!
2. _"MUST automatically produce an OpenAPI v3 document from the Rust code and comments."_ Yes!
3. _"MUST be easily deployable on AWS Lambda using some infrastructure as code tool (SAM, Serverless, etc.)."_ Actually yes, the only one so far!
4. _"MUST perform at least as fast as an equivalent FastAPI application for common CRUD tasks."_ Tentatively? TechEmpower has it showing a little better in some cases and worse in others, but switching to Tokio in 0.5 is bound change this one way or another.
5. _"MUST interact with a relational database (MySQL or Postgres)."_ Yes, even though the method will likely change with 0.5.
6. _"MUST have a simple way to test endpoints, comparable to pytest with FastAPI."_ The basic tests were quite simple! Much better than what I was able to achieve with actix-web.
7. _"MUST have great documentation."_ I was able to get my simple experiment working by just reading the docs, so I'm giving this one a yes as well.
8. _"MUST have stable, active maintenance."_ The Rocket community is definitely active in developing 0.5, and the maintainer of [rocket_lamb] was quite responsive, so yes.
9. _"SHOULD have automatically hosted documentation which allows direct interaction with the API."_ Yes! The version of Swagger UI is a bit old but it works!

If you tally it up, this solution meets every single one of my framework requirements, even the optional one! There are a couple items that need more experimentation to be super confident in, but this is the best crate-stack I have tried yet _by far_.

## Conclusion

I'm using Rocket! It was way too easy to get all of this working to pass it up. There will certainly be work to do to get [rocket_lamb] and [okapi] ready for Rocket 0.5, but my experience so far has left me very confident.

I'm not completely sure what the next step for me will be. I could try actually deploying a test function using Rocket to a real cloud provider. I could also dig into those two Rocket companion libraries and see how hard it is to update them to work with Rocket's "master" branch. I do want to wire this thing up to a database and create an equivalent FastAPI function to run benchmarks against, but I'd rather wait until I have async since that will likely make a big impact. If you have a suggestion on what to do next, leave it in the [ideas] section of this blog's GitHub repo.

By the way, if you want to check out the Rocket code I ended up with, it's available in the [experiments repo] alongside the actix code from the [previous post].

---

_Have a question or comment about this post? Leave it in the [discussions] thread on GitHub!_

_This post is part of a series and the [next part] is already available!_

_Have an idea or request for a future blog topic? Drop it in the GitHub discussions under [ideas]._

[ferris the crab]: https://www.rustacean.net
[the rust logo]: https://www.rust-lang.org/policies/media-guide
[the fastapi logo]: https://github.com/tiangolo/fastapi
[discussions]: https://github.com/dbanty/dylananthony.com/discussions/22
[ideas]: https://github.com/dbanty/dylananthony.com/discussions/categories/ideas
[the github repo]: https://github.com/dbanty/dylananthony.com
[previous post]: https://dylananthony.com/posts/fastapi-rust-3-trying-actix
[part 2]: https://dylananthony.com/posts/fastapi-rust-2-research
[rweb]: https://github.com/kdy1/rweb
[netlify_lambda_http]: https://docs.rs/netlify_lambda_http/0.2.0/netlify_lambda_http/
[aws sam]: https://aws.amazon.com/serverless/sam/
[experiments repo]: https://github.com/dbanty/rust-fastapi-experiments
[warp]: https://docs.rs/warp/0.2.5/warp/
[dropshot]: https://docs.rs/dropshot/0.3.0/dropshot/
[rocket]: https://rocket.rs
[rocket comment]: https://dev.to/follpvosten/comment/1ae8c
[rocket_lamb]: https://github.com/GREsau/rocket-lamb
[okapi]: https://github.com/GREsau/okapi
[twitter]: https://twitter.com/TBDylan
[next part]: https://dylananthony.com/posts/fastapi-rust-5-rocket-0.5


Replacing FastAPI with Rust: Part 4 - A Solution


> Cover image created by me using [Ferris the Crab], [the Rust logo], and [the FastAPI logo].

_This post is part of a series. If you haven't already, you may want to read the [previous post] before continuing._

## TL;DR

I got [actix-web] + [Paperclip] working with [AWS SAM]. Development was time consuming, troubleshooting was frustrating, and the end result was fragile and ugly. In future blog posts I will be experimenting with other solutions and hoping for a much nicer result. I'll only return to the actix-web approach if other methods are somehow even worse.

I will say that most of my struggles were related to running actix-web on AWS Lambda. So if that's not a requirement for _you_, it may still be worth looking into this approach.

If you'd like to share in my suffering and (maybe) learn something, read on! If you'd rather wait for future blog posts to point you in a _productive_ direction, I completely understand.

## Setting up [actix-web]

The first bit I tried was following pieces of the [official actix-web tutorial][actix-web docs] in order to get a tiny little web server started locally. This went fine, but was actually a big mistake as that tutorial teaches you to use macros to define endpoints which, at the time of writing, [Paperclip does not support][paperclip macro issue].

## Setting up [Paperclip]

[Paperclip's instructions][paperclip plugin] for using actix were okay, I just wish I hadn't read any actix documentation yet. After a complete rewrite of my existing code, I was able to run the web server locally and produce a v2 OpenAPI document. I used their echo example to validate JSON on the way in and document the output, nice and easy.

## Trying to Test it

I wanted to do my best to keep track of what was working and what I broke as I made changes, and my favorite way to do that is with unit tests! Unfortunately, I couldn't seem to find a good way to unit test endpoints with actix-web. I knew I'd seen testing in ["Zero To Production In Rust"] so I went back and referenced it only to find out the unit testing is (nearly) impossible in actix-web! The author uses integration testing only for their routes which requires spawning a local webserver. That doesn't work at all if I'm not going to be running a web server!

So scratch one requirement for [actix-web], it **does not** have a simple way to test endpoints.

## Processing Requests Without a Webserver

Not to be deterred by the lack of testing (figuring I'd find a way eventually), I moved on to what I thought would be the most difficult task. The [docs for actix-web][actix-web docs] did not provide a way to do this, they only show running an actual web server. So it was time to put my finely honed search-engine skills to work!

In the end I found two methods for achieving this:

1. Run the webserver and forward requests from the lambda handler back to localhost. This felt yucky and like there would be a fair amount of overhead so I dropped that idea quickly.
2. [This GitHub issue][actix-web lambda issue] suggested using some of the testing tools included with [actix-web] to achieve what I was looking for. This is the route I decided to take, though it was probably more effort than it was worth.

I ended up with something that looked roughly like this:

```rust
let service = App::new()
  .wrap_api()
  .service(web::resource("/actix/echo").route(web::post().to(echo_pet)))
  .with_json_spec_at("/actix/openapi.json")
  .build()
  .into_factory()
  .new_service(AppConfig::default())
  .await?;

// Note that I don't actually have a request here,
// for initial testing these params were hard-coded
let req = TestRequest::with_uri(&request.uri().to_string())
    .method(request.method().clone())
    .set_json(request.body())
    .to_request();

let actix_response: ServiceResponse = service.call(req).await?;
```

Not the most elegant of solutions, but it worked. Now seems like a good time, by the way, to take away a point for "MUST have great documentation". While the docs for using [actix-web] as intended were good, I'm far off the beaten path at this point and will only go further. I didn't find any docs at all to help me with this nor later code, and instead spent a lot of time digging through source code and deciphering cryptic compiler errors.

## Using AWS SAM

This _would_ have been the easiest part of the whole experiment if I had found [this blog post][sam blog] right away. I made the mistake of starting with the official docs which, even though they provided a Rust example, really didn't help at all. I then found another blog which got me 99% of the way there, but that last missing 1% meant my code would not compile. Anyway, once I found the good post, adapting it to use [Netlify's Lambda Runtime][netlify_lambda_http] was easy.

Why Netlify's fork and not the official AWS runtime? Basically because it seems like AWS has abandoned their project for now. Netlify has graciously taken up maintenance in the meantime.

## Combining the Lambda Runtime with actix

Getting [actix-web] to run using [netlify_lambda_http] was **very hard** and probably the most frustrating thing I've done in Rust so far. The way to set up a lambda handler is to provide either an async function or a struct that implements the `Handler` trait. Easy enough right? I already had an async function that would take some request data and spit out the `ServiceResponse` so I _should_ just need to convert to and from the proper structures.

As it turns out, the `Future` returned from the async function has to be `Send` (the lambda runtime must do something with threads to manage requests). The outputs of the futures provided by all the test methods I was using were not `Send`. As a result, the compiler spit out hundreds of lines about the nested types that were not `Send`, preventing me from using my async function.

There is probably some standard way to get around this sort of stuff, but I couldn't figure it out, certainly not with messages as cryptic as the ones I was getting. So I turned to a crate I found called [warp_lambda]. That's right, I found a crate that allows you to run [warp] on AWS Lambda. As a reminder, [rweb], the most promising option from a functional standpoint, is based on [warp].

This crate has an implementation for the `Handler` trait which I used to model my own `Handler` trait for an actix-web `Service`. Using my own struct which implemented that trait suddenly made the "this is not `Send`" error messages simple enough to decipher. I was able to get the thing to actually compile, but it required using a few `unwrap()`s on errors which were not `Send`. I could probably go back and figure out how to wrap or map those errors to something simpler to make my implementation less fragile, but I was already annoyed enough at this implementation that I was headed toward [rweb] anyway.

At this point I encountered yet another problem. While I was able to create and run a `Service` in my `Handler`, I had to create it for every single request. Try as I might to decipher the opaque types involved with the _many_ generics used with an actix `App`, I could not satisfy the compiler enough to store this thing in my struct. I didn't run any benchmarks here, but there's no way that re-initializing an entire `App` for each and every request is fast. It would take a ton of testing to make sure it didn't fall over for large applications, which means I couldn't confidently check off the "perform at least as fast as FastAPI" requirement.

## Translating Between Lambda and Actix

On to yet another challenge! As I said, I was already convinced that this actix-web approach was not the best way to go, but I wanted to at least make it work _a little bit_ before giving up.

I'm not going to go into a ton of detail here, but basically I had to spend a lot of time reading actix-web source code in order to figure out how to translate body types, headers, etc. and I only managed to get the bare minimum for my JSON test-endpoints working.

I really have come to appreciate WSGI/ASGI in the Python world. While I've not directly interfaced with it, I know that it sets some standards for how web requests work which means a lot of this manual conversion nonsense is unnecessary. It also means that web frameworks are almost always completely independent of web servers, so most of this hunting around for a way to directly invoke requests would not have been necessary.

## Conclusion

The code works... but barely. If you want to see the end result, I have put it up in a [GitHub Repository][experiments repo] where I also intend to add future experiments in other frameworks. If you haven't gathered as much from all of the text above, this code is fragile, slow, and **in no way recommended for production**. But if you're more experienced (or dedicated) than I am and want to try your hand at making it better, go for it!

Closing the loop on the [previous post], my experience has indicated that none of these requirements are actually met by actix-web + Paperclip for my serverless usecase:

1. _"MUST be easily deployable on AWS Lambda using some infrastructure as code tool (SAM, Serverless, etc.)."_
2. _"MUST perform at least as fast as an equivalent FastAPI application for common CRUD tasks."_
3. _"MUST have a simple way to test endpoints, comparable to pytest with FastAPI."_
4. _"MUST have great documentation."_

Updating the score, this solution only meets 3/8 "MUST" requirements for my FastAPI replacement (potentially 4/8 if the performance hit isn't as bad as I think it will be). This actually puts it below [rweb] which was my runner up in the initial research phase.

## What's Next?

I'm going to dive in and try [rweb]. My biggest near-term concern was the lack of documentation, but no amount of documentation actually helped me with [actix-web] so... why not? Hopefully it will go much better, and I won't have to write my own lambda handler code _or_ OpenAPI 3 structures. Plus now I get to enjoy the (subjectively) nicer syntax of rweb!

---

_Have a question or comment about this post? Leave it in the [discussions] thread on GitHub!_

_This post is part of a series and the [next part] is already available!_

_Have an idea or request for a future blog topic? Drop it in the GitHub discussions under [ideas]._

[ferris the crab]: https://www.rustacean.net
[the rust logo]: https://www.rust-lang.org/policies/media-guide
[the fastapi logo]: https://github.com/tiangolo/fastapi
[discussions]: https://github.com/dbanty/dylananthony.com/discussions/18
[ideas]: https://github.com/dbanty/dylananthony.com/discussions/categories/ideas
[the github repo]: https://github.com/dbanty/dylananthony.com
[previous post]: https://dylananthony.com/posts/fastapi-rust-2-research
[teaser comment]: https://dev.to/patarapolw/comment/19m15
[rweb]: https://github.com/kdy1/rweb
[paperclip plugin]: https://paperclip.waffles.space/actix-plugin.html
[actix-web]: https://github.com/actix/actix-web
[sam blog]: https://dev.to/netguru/commentable-rs-building-a-serverless-comment-system-in-rust-5egb
[netlify_lambda_http]: https://docs.rs/netlify_lambda_http/0.2.0/netlify_lambda_http/
[actix-web lambda issue]: https://github.com/actix/actix-web/issues/768
[aws sam]: https://aws.amazon.com/serverless/sam/
[actix-web docs]: https://actix.rs/docs/
[paperclip macro issue]: https://github.com/wafflespeanut/paperclip/issues/63
[paperclip]: https://github.com/wafflespeanut/paperclip
["zero to production in rust"]: https://www.zero2prod.com
[warp_lambda]: https://github.com/aslamplr/warp_lambda
[warp]: https://github.com/seanmonstar/warp
[experiments repo]: https://github.com/dbanty/rust-fastapi-experiments
[next part]: https://dylananthony.com/posts/fastapi-rust-4-a-solution


Replacing FastAPI with Rust: Part 3 - Trying Actix


> Cover image created by me using [Ferris the Crab], [the Rust logo], and [the FastAPI logo].

_This post is part of a series. If you haven't already, you may want to read the [previous post] before continuing._

## Intro

After the first post (which was very accurately dubbed a "teaser" in [a comment on Dev.to][teaser comment]), I was really itching to keep talking about this project. So without further ado, here is part 2! This time around we're going to explore a few of the existing options in the Rust ecosystem to see how close we can get to our FastAPI replacement.

## [rweb]: The Promising Upstart

The very first project I came across when searching for the FastAPI of Rust was [rweb]. This is a relatively new project (just under a year old at time of writing) which seems to share a lot of similarities with our framework-to-beat. Much like FastAPI adds features to Starlette, rweb builds on top of the framework [warp].

### Where it Shines

Users of FastAPI will feel immediately at home looking at the example code:

```rust
#[get("/search")]
fn search(_product: Query<SearchOption>) -> Json<Vec<Product>> {
    // ...
    // This returns 200 with application/json
}
```

You have a macro (comparable in this context to a Python decorator) which defines the HTTP method and path of the operation. Then you declare the function which does the work, the arguments to which are inputs to the endpoint and the return type is the output. You can declare the location of inputs (`Query`), format of output (`Json`), and structure of the data for both. This method and its associated types will get documented in an OpenAPI v3 format _and_ automatically validated! Your doc comments for your function will even become the description of the path operation. Very FastAPI-esque.

### Where it Falls Short

Aside from a few missing OpenAPI types (e.g. cookies), [rweb] seems like a relatively complete solution. The biggest flaw, in what I can tell from reading documentation, is around project maintenance. Recent releases are not documented in GitHub and indeed there seems to be no changelog at all. There are also out of date milestones and issues which have gone several months with no reply from the maintainer.

To their credit, the maintainer did accept a pull request from me to fix a slight typo in the README within the same day, so they're definitely paying attention. However, if I want to replace a framework like FastAPI for production workloads, I want to have confidence that the community will address any major issues if they come up.

Another concern is the relatively limited documentation. Very few projects will come close to the quality of FastAPI's documentation, but [rweb's][rweb docs] are particularly terse. What is documented typically provides a series of code examples, often with little or no explanation.

Let me be clear, maintaining an open source project is _hard_ and _time consuming_. Putting your code out there for other people to use is something to be celebrated and encouraged. My comments above are in no way meant to be a knock on [rweb] or its collaborators, just a transparent account of why I'm hesitant to use it for company projects.

### Will I Use It?

Let's look back at the requirements from [part 1][previous post]:

1. _"MUST be written in Rust."_ Check! We wouldn't be looking at it if it weren't.
2. _"MUST automatically produce an OpenAPI v3 document from the Rust code and comments."_ Also check!
3. _"MUST be easily deployable on AWS Lambda using some infrastructure as code tool (SAM, Serverless, etc.)."_ I couldn't find any examples or documentation for deploying an [rweb] app this way, so it's not going to be _easy_. I did find one comment on a GitHub issue for [warp] that may be useful, but it'll take some work.
4. _"MUST perform at least as fast as an equivalent FastAPI application for common CRUD tasks."_ Yes? The [tech empower] benchmarks (same ones FastAPI lists on its website) actually show warp performing _worse_ than FastAPI at multiple queries on "physical hardware", but still better on the Cloud. So that feels like a yes from what we can tell.
5. _"MUST interact with a relational database (MySQL or Postgres)."_ Yes, [warp] uses Tokio (so presumably [rweb] does too) which is the most popular Rust async runtime, and one I can use with my preferred SQL library [sqlx].
6. _"MUST have a simple way to test endpoints, comparable to pytest with FastAPI."_ I haven't tried it, but [warp] includes a testing module, so this should be fine.
7. _"MUST have great documentation."_ Nope.
8. _"SHOULD have automatically hosted documentation which allows direct interaction with the API."_ Also no.

That means it meets 5 out of 7 "MUST" requirements, leaving me to figure out running on AWS Lambda and writing a complete user's guide. There is, however, an 8th "MUST" requirement that has surfaced from my research: "MUST have stable, active maintenance." I'm looking to replace some production workloads with whatever my choice is, which means I need to be confident that an update to the library won't break everything unexpectedly and that security vulnerabilities, if found, will be fixed quickly. Based on what I've seen, [rweb] does not meet this requirement.

All of that is to say [rweb] is a possible solution, but not a likely one. The product seems great, and if the code functions as well as the brief examples indicate, this is the best option from a code perspective (oops, spoilers!). Given my concerns about the community, I would have to be comfortable forking and maintaining my own version of this framework in the event that I need changes and can't wait months for a PR to be reviewed. Even if that's not the case, I'll certainly have to write much more complete documentation for my teammates to be able to use this project effectively. I'm not mortally opposed to any of that, but I'd rather avoid it if I can.

## [Rocket]: The Lib I Want to Like

Oh [Rocket], you playful muse. I've watched you ascend from my early Rust days; yet each time I reach for you my heart sinks more. This research project of mine led me to [okapi], an extension for OpenAPI documentation. And yet, I have to pass once again. While most of the Rust ecosystem blazes toward async, you inch toward it too slowly. Perhaps next time I search for a web framework our paths will align, but until then, I must follow a different orbit.

## [Paperclip]: The Sensible Option

[Paperclip] is a project to provide various forms of OpenAPI tooling to the Rust ecosystem. Particularly relevant to our mission is a [plugin][paperclip plugin] for [actix-web].

### Pros

[actix-web] is easily to most well known, well documented, and well used web framework for Rust. What's more, it is a very active project, already making progress toward Tokio 1.0 (while at last check Rocket was still pursuing Tokio 0.2 integration). It also comes with built in support for input validation and output serialization via Rust's go-to library [serde]. That means all [Paperclip] has to do is document those same functions and structures, which it does!

[Paperclip] seems to be quite an active project seeking to build OpenAPI functionality on top of [actix-web] by using the plugin system the latter provides. The project is well documented, and even has its own Discord server for chatting about development.

### Cons

The biggest issue with [Paperclip] is that it only currently supports OpenAPI v2. There is work in progress to add v3 support, but it's just that: in progress. This means that if I really want to supplant FastAPI with this actix-web w/ Paperclip combo, I'm going to have to write my own v3 implementation. There is a [GitHub Issue](https://github.com/wafflespeanut/paperclip/issues/177) which talks about the intended strategy for achieving this being somehow based on converting a v2 spec to v3. I'm not sure how possible this will be considering there are some important features missing from v2. It makes more sense to me for this to be a different feature via cargo flag (or at least a different module).

Subjectively, the code required to use this project is also uglier than [rweb]. Here's an example from their website:

```rust
#[api_v2_operation]
async fn echo_pet(body: Json<Pet>) -> Result<Json<Pet>, ()> {
    Ok(body)
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| App::new()
        .wrap_api()
        .service(
            web::resource("/pets")
                .route(web::post().to(echo_pet))
        )
        .with_json_spec_at("/api/spec")
        .build()
    ).bind("127.0.0.1:8080")?
    .run().await
}
```

The main difference here is that you have to use a macro to get the endpoint documented which is _separate from_ the binding of the endpoint to the application. Then the assigning of a path and method happens elsewhere, not where the function is declared. There can certainly be arguments made for this more explicit, non-macro style... but it's definitely different than what a Python developer would be used to with FastAPI.

### Is This the One?

Let's check the scoreboard again:

1. _"MUST be written in Rust."_ Yup!
2. _"MUST automatically produce an OpenAPI v3 document from the Rust code and comments."_ Sadly, no. We'll get v2 for free but have to write our own v3 variant.
3. _"MUST be easily deployable on AWS Lambda using some infrastructure as code tool (SAM, Serverless, etc.)."_ I _was_ able to find some examples and sample projects deploying actix-web to Lambda. It will still require some tinkering but I have a pretty solid foundation. So tentatively yes.
4. _"MUST perform at least as fast as an equivalent FastAPI application for common CRUD tasks."_ Yes! [actix-web] is usually one of the top few entries [tech empower] benchmarks. Assuming [Paperclip] doesn't add a massive amount of overhead, it should be significantly faster than FastAPI.
5. _"MUST interact with a relational database (MySQL or Postgres)."_ Yes again! There are, in fact, several documented examples of using [sqlx] with [actix-web] which I've seen around the internet.
6. _"MUST have a simple way to test endpoints, comparable to pytest with FastAPI."_ Yup!
7. _"MUST have great documentation."_ Yes! Both [actix-web] and [Paperclip] have quite good documentation. I would even put [actix-web] in the "great" category.
8. _"MUST have stable, active maintenance."_ It sure seems like it!
9. _"SHOULD have automatically hosted documentation which allows direct interaction with the API."_ Not yet, but work is actually in progress on this.

Tallying up the results, we get 7/8 "MUST" requirements met. I think that Paperclip + actix-web seems like the most promising candidate. I'm really not opposed to writing the OpenAPI v3 construction myself as I've worked with the structure a fair bit in my [openapi-python-client] project (shameless plug).

## Conclusion and Next Steps

In the next blog post in this series, I'm going to take [actix-web] and [Paperclip] for a test drive! Hopefully I can have myself an OpenAPI v2 API hosted on Lambda as a proof of concept. The level of difficulty of that task should help inform my decision as a whole... and whether I need to give [rweb] more of a chance.

---

_Have a question or comment about this post? Leave it in the [discussions] thread on GitHub!_

_This post is part of a series and the [next part] is already available!_

[ferris the crab]: https://www.rustacean.net
[the rust logo]: https://www.rust-lang.org/policies/media-guide
[the fastapi logo]: https://github.com/tiangolo/fastapi
[discussions]: https://github.com/dbanty/dylananthony.com/discussions/11
[ideas]: https://github.com/dbanty/dylananthony.com/discussions/categories/ideas
[previous post]: https://dylananthony.com/posts/fastapi-rust-1-intro
[teaser comment]: https://dev.to/patarapolw/comment/19m15
[rweb]: https://github.com/kdy1/rweb
[rweb docs]: https://docs.rs/rweb/0.5.4/rweb/
[warp]: https://github.com/seanmonstar/warp
[rocket]: https://github.com/SergioBenitez/Rocket
[okapi]: https://github.com/GREsau/okapi
[paperclip]: https://github.com/wafflespeanut/paperclip
[paperclip plugin]: https://paperclip.waffles.space/actix-plugin.html
[actix-web]: https://github.com/actix/actix-web
[openapi-python-client]: https://github.com/triaxtec/openapi-python-client
[serde]: https://serde.rs
[tech empower]: https://www.techempower.com/benchmarks/#section=data-r19&hw=cl&test=query&f=zik0zj-zik0zj-zik0zj-zik0zj-zik0zj-zik0zj-yyku7z-ziimf3-zik0zj-zik0zj-71
[sqlx]: https://github.com/launchbadge/sqlx
[next part]: https://dylananthony.com/posts/fastapi-rust-3-trying-actix


Replacing FastAPI with Rust: Part 2 - Research


> Cover image created by me using [Ferris the Crab], [the Rust logo], and [the FastAPI logo].

## What is this Series?

I am going to produce a series of blog posts attempting to create a method for replacing FastAPI applications with Rust for my particular use case. I don't know what this will lead to just yet; it may end up being a tutorial, it may end up being a development log as I create the pieces of the ecosystem that are missing, it may end up being only one more post if I find something that magically solves all my issues.

Check out the requirements section below for _exactly_ what I'm trying to achieve!

## Some Background

I have been using FastAPI as my go-to back end framework for a little over a year now and it's _almost_ perfect. In my opinion, FastAPI is the **best** way to create an API **in any language**. I regularly look around the ecosystem for
competitors worth trying and haven't found anything compelling enough to try... yet.

For those of you not acquainted, [FastAPI] is a Python web framework for creating OpenAPI documented REST APIs. You can do a lot more with it too, but that's my primary use case, and the one that matters to this blog series. The key features (to me) are:

1. Automatic documentation via OpenAPI, which lets you do things like [generate Python code][openapi-python-client] that knows how to talk to your API.
2. [A documentation UI][swagger ui] allowing users to easily understand and interact with the API directly.
3. Input validation via [Pydantic], the same tool used to generate the schemas in documentation. Basically you just annotate your endpoint with inputs/outputs and they are documented _and_ validated.
4. Easy to test using something like pytest due to some fantastic included tools and the flexibility of dependency injection.
5. [Fantastic documentation][fastapi] of FastAPI itself, some of the best I've ever read, without which it might as well not have all of these amazing features.
6. Easy to host on AWS Lambda using [Mangum].

FastAPI does much, _much_ more and has one of the most amazing open source communities I've ever encountered. So why am I looking to replace it? FastAPI has one fundamental drawback that it will never overcome: Python.

Don't get me wrong, I love Python, it's my second favorite language, but it has some serious limitations that I would love to move beyond.

## Why Rust?

I know, I know, Rust users never shut up about how great the language is, so I'll try to keep this brief and on topic. [Let me know in GitHub][ideas] if you want a blog post going in depth on any of these points:

1. Python's static typing story is a sad one. It might get better, but it's not good enough right now, and will never be as good as Rust's.
2. Rust is way faster than Python which matters when you're billed by execution time (like on AWS Lambda).
3. Rust error handling is _undeniably better_ than exception-based errors (like in Python) when stability matters.
4. Algebraic data types in Rust allow you to encode business **and security** logic in a way that your code **will not compile** if you get it wrong. This is far better than forcing internal server errors when when someone forgets to secure an endpoint like I do in FastAPI.

## Requirements

The end result of my investigation should be a method to produce an API which:

1. MUST be written in Rust.
2. MUST automatically produce an OpenAPI v3 document from the Rust code and comments.
   1. The developer may need to know some OpenAPI concepts for properly documenting things, but should not have to write JSON or YAML to achieve it.
   2. The document MUST be hosted on an endpoint of the API so it's accessible from the internet.
3. MUST be _easily_ deployable on AWS Lambda using some infrastructure as code tool (SAM, Serverless, etc.).
4. MUST perform at least as fast as an equivalent FastAPI application for common CRUD tasks.
5. MUST interact with a relational database (MySQL or Postgres).
6. MUST have a _simple_ way to test endpoints, comparable to pytest with FastAPI. If a lot of work has to go into testing, people just won't test things.
7. MUST have great documentation.
8. SHOULD have automatically hosted documentation which allows direct interaction with the API. If not, this could be achieved by hosting the documentation externally.

## Conclusion

So I'm going on an adventure to replace what I believe to be the best API framework that exists with something else. There will be research, documentation, writing of Rust code, and who knows what else! In the end, I'll either come away with the new best way to produce APIs, or even more evidence of how amazing [FastAPI] is. Sound like fun? Follow along with this series! Have some suggestions of where I should start? Please, _please_ let me know.

---

_Have a question or comment about this post? Leave it in the [discussions] thread on GitHub!_

_This post is part of a series and the [next part] is already available!_

_Want to be notified of future blog posts? Watch releases in [the GitHub repo]._

[ferris the crab]: https://www.rustacean.net
[the rust logo]: https://www.rust-lang.org/policies/media-guide
[the fastapi logo]: https://github.com/tiangolo/fastapi
[discussions]: https://github.com/dbanty/dylananthony.com/discussions/9
[openapi-python-client]: https://github.com/triaxtec/openapi-python-client
[swagger ui]: https://swagger.io/tools/swagger-ui/
[pydantic]: https://pydantic-docs.helpmanual.io
[fastapi]: https://fastapi.tiangolo.com
[mangum]: https://mangum.io
[ideas]: https://github.com/dbanty/dylananthony.com/discussions/categories/ideas
[the github repo]: https://github.com/dbanty/dylananthony.com
[next part]: https://dylananthony.com/posts/fastapi-rust-2-research


Replacing FastAPI with Rust: Part 1 - Intro


## Why?

After I decided I wanted to write some blog content again, I had to decide whether to make my own website or just
stick with [Dev.to] as I have done in the past. Clearly I decided to create my own website (thus this post), but why? Here are the reasons:

1. I wanted to store all my blog posts in source control. I write them in Markdown which is an easy enough format to
   control, and I'm very much used to GitHub for storing my data for programming projects, so why not use GitHub to
   store the markdown of my blog posts? If I'm already storing my markdown in GitHub, I'm not too far off from
   having my own hosted blog.
2. I already have my own domain for email (so I'm not permanently reliant on something like gmail, even if I decide
   to use it as a back end), and I've been looking for a reason to use the domain for something else too.
3. Pretty much all the advice I've read from writers that I respect says that even if you do post on another site,
   you should always provide a canonical link back to your own site. If I don't respect the advice of people on the
   internet who know their trade, what exactly am I doing here?

## Requirements

The "Lead Software Engineer" in me has to make sure I have a clear set of goals before embarking on a new project, and my personal blog is no different. So here they are:

1. Content must be written in Markdown. I already know Markdown from all the technical documentation I do in my
   day-to-day most other platforms I would consider writing on (e.g. [Dev.to]) use Markdown, it's an easy format to track in change control (unlike, say, MS Word), and I know there are great tools for converting it to HTML.
2. Hosting must be free because incurring yet another monthly cost for a side project which doesn't yield any clear returns just doesn't sound great.
3. Continuous integration and delivery must be relatively painless to set up.
4. It must use tech I'm already familiar with. I have enough learning topics queued up to not add yet another. Also,
   the reason I'm starting blogging again is that I have a series I want to write, I don't want to delay that too long.
5. It should be very customizable, but also very easy to get started. I will likely want to take the website further
   in the future, tweaking styling, adding more sections beyond the blog, etc. For right now though, I only want to get a nice blog up and running quickly. So there should be an easy-to-use framework to get started with minimal effort, but built on a platform that's easy to expand in the future.

## The Tech I Chose

1. **Markdown**: as indicated by the requirements this choice was made before I even started investigating options.
   See requirement number 1 for some reasons why.
2. **GitHub**: This is the source control host I'm most familiar with and seems to be set up for the longest term success.
3. **GitHub Actions**: Requirement 3 basically drove this. I could set up CircleCI which I'm more familiar with, but it's more steps than GitHub Actions and more complexity to the project.
4. **Next.js**: Front end tech I'm already familiar with (requirement 4) would either be Angular or Next.js. I would
   pick Next.js over Angular for any new project for a whole host of reasons, not the least of which is the excellent documentation which even includes [this Markdown blog example][blog starter] which I got started with. Of course Next.js, being React with more features, also easily solves requirement 5.
5. **Vercel**: I could write an entire blog just about how amazing Vercel is. To put it concisely: they are **by
   far** the single most painless hosting solution I have ever found. If you're using Next.js, they are a no-brainer,
   and they are **free** for small projects. This means they handily meet requirements 2 & 3.
6. **TypeScript**: Maintainability and correctness of code is **always** a requirement of everything I write. TypeScript is so much better than JavaScript in that area that I will pretty much never choose to write vanilla JavaScript. I _was_ going to save TypeScript conversion from the [starter example][blog starter] for a later date... until I spent a half hour debugging a typo in a prop name >.>.
7. **Prettier**: I just love auto formatters. Prettier will take care of my TypeScript and my Markdown, so why not add it in?
8. **Tailwind**: I love Tailwind, and would have ended up using it eventually for customizing the rest of the site... but the only reason I'm including it in the initial blog-only version is because it came with the [example][blog starter].

## A Brief Tutorial

Here are the steps I took to get the site to where it is today:

1. Use Yarn to make me a copy of [the example][blog starter].
2. Create a repo in GitHub and push (the [GitHub CLI](https://cli.github.com) makes this easier).
3. Add my project to Vercel which, being as amazing as it is, took about 5 minutes. Now I have continuous delivery, so I can manually check the results of every change after this.
4. Update all the dependencies.
5. Upgrade to Yarn 2 (unnecessary, but it comes with more dependable builds which I like).
6. Resolve a couple Tailwind warnings.
7. Add explicit alt text to cover images instead of the generic text included. It's nice to actually describe what's going on in the images.
8. Add and run Prettier, along with a GitHub workflow to check on every push.
9. Yank the default blog content / author info and add some of my own in an empty version of this post.
10. Convert to TypeScript while debugging alt text of the image for my new shell of a post.
11. Write this post

## Retrospective

Okay so how did it go? Would I do anything differently? Basically "great" and "no". I might change my mind and
update this in a month, but for now I'm super satisfied with the results. Check out https://dylananthony.com to see what it looks like. It took me a couple of hours all told to get it put together which I think is a worthy investment, granted I was already familiar with all the tech involved so there was minimal DuckDuckGoing required. I probably should have looked around for a TypeScript variant of the example already to reduce that time even further, but I wasn't initially planning on using TypeScript at launch.

## What's Next?

1. More blog posts! As I mentioned, the whole reason I wanted to get this off the ground quickly is because there's a new blog series I'm working on. Now that this initial version of my site is done, I want to get right into that. I expect most of my readers will still be on [Dev.to] so I'm not too concerned with making the site look nicer just yet.
2. I know I did some hokey stuff that [eslint] will complain about whenever I add it, so eventually I'll have to add it and fix those complaints.
3. Continuous delivery to other platforms? I have seen a couple of people talk about automatically cross-posting to
   [Dev.to] or [Medium] and I plan on posting my new series to both of those. So perhaps once it becomes too tedious
   to do so manually I'll look into some form of CD. I imagine I'll want to make some manual tweaks anyway though so... we'll see.
4. Custom styling on my website! Right now it's very basic, using pretty much the exact same thing as the starter template. I'll definitely want to make it more "me" eventually, but again, after this blog post.
5. Some sort of notifications? _If_ I start getting traffic to my personal site, _maybe_ I'll create an RSS feed or mailing list somehow. Like I said I expect 99% of traffic to just be on [Dev.to] or [Medium] so this feature is a long way off.

## Conclusion

If you want to have your own website to host blogs on, Next.js on Vercel seems like a great choice. I am in no way, shape, or form a professional writer, front end engineer, or designer, so take everything I have said with that grain of salt. What I _am_ is a professional DevOps engineer who has tried several tech stacks for hosting websites, so I am pretty confident in my claim that what Vercel offers is truly amazing.

## Meta Conclusion

That's the sort of content you can expect from me in future blog posts! I'm going to try to accomplish some goal
using software then tell you how it went and _hopefully_ provide some useful takeaways. I'll do my best to point out
my confidence in or experience with different tech, so I won't lead you astray. I'm also always open to suggestions,
comments, or corrections which you can leave [in the repo for this website][repo]. I will likely post most blog
posts on [Dev.to] and/or [Medium], but will always post **all** content on my website first.

[dev.to]: https://dev.to/dbanty
[blog starter]: https://github.com/vercel/next.js/tree/canary/examples/blog-starter
[eslint]: https://eslint.org
[medium]: https://medium.com/@dbanty
[repo]: https://github.com/dbanty/dylananthony.com/discussions/6


A Blog

About producing quality software with minimal frustration.

Replacing FastAPI with Rust: Part 5 - Rocket 0.5

More Stories

Replacing FastAPI with Rust: Part 4 - A Solution

Replacing FastAPI with Rust: Part 3 - Trying Actix

Replacing FastAPI with Rust: Part 2 - Research

Replacing FastAPI with Rust: Part 1 - Intro

An intro to this blog using... this blog