<img src="https://s3.us-east-1.amazonaws.com/resource.mixa.site/valhallaresearch/Media/DALL%C2%B7E%202023-11-02%2006.52.48%20-%20red%20crab%20poet,%20multi-colored%20paint%20splotch%20background.png" priority="1"> 
I <a href="https://valhallaresearch.net/01_RESEARCH/SECURITY/GrabbrApp/Goodbye%20Golang%20Microservices,%20and%20Hello%20Rust%20Monoservice">wrote recently</a> about converting my startup's backend in Rust. I did fairly little looking before settling on a library called poem, so it honestly may not even be the very best choice, but I have thus far really enjoyed using Poem and figured I'd write up a blog covering some of the basics as well as some of the gotcha's I've run into.
<h2 id="poem-introduction"><a aria-hidden="true" tabindex="-1" href="#poem-introduction"></a>Poem introduction</h2>
Poem, or more specifically <code>poem-openapi</code>, is a <a href="https://crates.io/crates/poem-openapi">backend framework</a> that creates an OpenAPI v3 compliant API with fairly little user-made boilerplate code. What the OpenAPI v3 compliance means practically is that you basically get swagger API documentation for free, just by using the framework. Judging by how ugly my app's current API documentation is, this is super nice.
Poem uses Tokio under the hood and from what I've seen it's pretty fast. The compile times thus far haven't been too bad either, even with custom Request/Response structs across multiple files. The AWS SDK (blogs coming soon) integrates pretty easily with Poem as well.
The introduction we'll go through in this article is a fair bit simpler than what I'm working on with <a href="https://grabbrapp.io">GrabbrApp</a> but there were a couple of weird issues I went through that weren't very well documented. There is actually a fairly significant lack of articles on Poem so I'm hoping to help fill that gap a bit over time.
<h2 id="the-hello-world-example"><a aria-hidden="true" tabindex="-1" href="#the-hello-world-example"></a>The Hello World Example</h2>
To start things off, here is my <code>Cargo.toml</code> for this example:
<pre><code>[package]
name = "poem_example"
version = "0.1.0"
edition = "2021"

[dependencies]
poem = "1"
tokio = { version = "1", features = ["full"] }
poem-openapi = {version ="3.0.5", features=["swagger-ui"]}
</code></pre>
In our <code>main.rs</code> file, we start with creating a struct and an <code>impl</code> block with our API paths in it. These use the <code>#[oai(...)</code> attribute which takes in the path of the route (in this case, <code>/hello</code>) and its method (<code>get</code>) followed by the handler function.
<pre><code>use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService};

struct Api;

#[OpenApi]
impl Api {
 #[oai(path = "/hello", method = "get")]
 async fn index(&#x26;self, name: Query&#x3C;Option&#x3C;String>>) -> PlainText&#x3C;String> {
 match name.0 {
 Some(name) => PlainText(format!("hello, {}!", name)),
 None => PlainText("hello!".to_string()),
 }
 }
}
</code></pre>
We then implement this endpoint by passing the <code>Api</code> struct into the initializing function <code>OpenApiService::new()</code> and pass it a base URL and port. We can then create the swagger API docs with literally one line and create an app to run within the server using the <code>poem::Server::new().run()</code>, which takes in a TCP Listener and our newly created app.
<pre><code>#[tokio::main]
async fn main() -> Result&#x3C;(), std::io::Error> {
 let api_service =
 OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3001/api");
 let ui = api_service.swagger_ui();
 let app = Route::new().nest("/api", api_service).nest("/", ui);

 poem::Server::new(TcpListener::bind("127.0.0.1:3001"))
 .run(app)
 .await
}
</code></pre>
Running this, if we go to <code>localhost:3001/</code> we will see the swagger API documentation. If we navigate to <code>localhost:3001/api/hello?name=mitch</code> we will see the expected output:
<img src="https://s3.us-east-1.amazonaws.com/resource.mixa.site/valhallaresearch/Media/Screen%20Shot%202023-11-02%20at%206.20.02%20AM.png">
<h2 id="extending-our-api---post-requests-with-custom-structs"><a aria-hidden="true" tabindex="-1" href="#extending-our-api---post-requests-with-custom-structs"></a>Extending our API - POST requests with custom structs</h2>
One of the first things I needed to do was define custom data structures that the API could parse via POST request JSON bodies. This was a surprisingly opaque process and took me a bit to figure out.
Here is our new <code>/user</code> POST route as well as a custom struct we're going to use in it.
<pre><code>use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService, payload::Json, Object};

#[derive(Object)]
struct User {
 id: Option&#x3C;i32>,
 name: String,
 color: String

}
...
	#[oai(path = "/user", method = "post")]
 async fn userdisplay(&#x26;self, mut user: Json&#x3C;User>) -> Json&#x3C;User> {

 user.0.id = Some(420);
 Json(user.0)
 }
</code></pre>
The important bits to note here:
<ul>
<li>You're going to need the <code>#[derive(Object)]</code> attribute which pulls from the <code>Object</code> macro imported from <code>poem_openapi</code>. This allows the later <code>Json</code> function to parse it.</li>
<li>When you're using the object as a request value (in the function header) you will need to wrap it in the <code>Json&#x3C;></code> type. This will allow poem to actually parse it without having to write any custom parsing code. For reference, I found this out after writing a bunch of custom parsing code...</li>
<li>Accessing the underlying variable within the Json struct is as easy as calling <code>user.0</code></li>
</ul>
Hopping over to Postman, we can easily call this endpoint. I made the <code>id</code> field optional to display how you can mutate user input in the endpoint.
<img src="https://s3.us-east-1.amazonaws.com/resource.mixa.site/valhallaresearch/Media/Screen%20Shot%202023-11-02%20at%206.35.23%20AM.png">
<h2 id="putting-your-routes-in-separate-files"><a aria-hidden="true" tabindex="-1" href="#putting-your-routes-in-separate-files"></a>Putting your routes in separate files</h2>
This one is super useful, and also not very well documented. You can put your routes in separate files and import them all in one place. We're going to create a <code>user</code> module and move our <code>/api/user</code> POST route over there to show how this works.
We first create a user module by creating a <code>user</code> directory with a single <code>mod.rs</code> file. We can import this into our <code>main.rs</code> file using <code>mod user;</code> toward the top of the file. We will then copy/paste most of the code from the top of our <code>main.rs</code> file, to include the imports, the creation of our <code>Api</code> and <code>User</code> structs, and the implementation with our endpoints. In <code>/user/mod.rs</code> we will delete the endpoints that don't have anything to do with our fictional user. In practice, you should probably organize your files such that <code>/user/mod.rs</code> only deals with <code>/api/user/</code> endpoints, <code>/database/mod.rs</code> only deals with <code>/api/database</code> endpoints, etc. but I'm not going to tell you how to write your code.
After moving everything over and getting rid of copied endpoints in <code>main.rs</code> and <code>user/mod.rs</code>, rename your <code>Api</code> struct in <code>user/mod.rs</code> to something else and make it public. This is how you will eventually import it in <code>main.rs</code>. At the end, your <code>user/mod.rs</code> will look like this:
<pre><code>// /user/mod.rs
use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService, payload::Json, Object};

pub struct UserApi;

#[derive(Object)]
struct User {
 id: Option&#x3C;i32>,
 name: String,
 color: String

}

#[OpenApi]
impl UserApi {
 

 #[oai(path = "/user", method = "post")]
 async fn userdisplay(&#x26;self, mut user: Json&#x3C;User>) -> Json&#x3C;User> {

 user.0.id = Some(420);
 Json(user.0)
 }
}
</code></pre>
Now that we have created our <code>/user/mod.rs</code> endpoints, let's import them. Within your <code>main.rs</code> file, all you really have to do is link the module (<code>mod user</code>) and create a tuple that will hold both the <code>Api</code> struct in your <code>main.rs</code> file and the <code>UserApi</code> struct in your <code>user/mod.rs</code> file. This tuple will be passed to the <code>OpenApiService::new()</code> function, like so:
<pre><code>// main.rs
use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService, payload::Json, Object};

struct Api;
mod user;
#[derive(Object)]
struct User {
 id: Option&#x3C;i32>,
 name: String,
 color: String

}

#[OpenApi]
impl Api {
 #[oai(path = "/hello", method = "get")]
 async fn index(&#x26;self, name: Query&#x3C;Option&#x3C;String>>) -> PlainText&#x3C;String> {
 match name.0 {
 Some(name) => PlainText(format!("hello, {}!", name)),
 None => PlainText("hello!".to_string()),
 }
 }

 
}

#[tokio::main]
async fn main() -> Result&#x3C;(), std::io::Error> {
	// Create a tuple with both the Api struct and the imported user::UserApi struct
 let endpoints = (Api, user::UserApi);
 let api_service =
 OpenApiService::new(endpoints, "Hello World", "1.0").server("http://localhost:3001/api");
 let ui = api_service.swagger_ui();
 let app = Route::new().nest("/api", api_service).nest("/", ui);

 poem::Server::new(TcpListener::bind("127.0.0.1:3001"))
 .run(app)
 .await
}

</code></pre>
Hit run and you're good to go!
This one took a bit to figure out, in no small part because I'm pretty new to Rust and didn't even think about just making the struct public. That said, it's not super well documented (I think it was a StackOverflow question that revealed it to me) so I figured I would include it in this article.
<h2 id="conclusion-and-next-up"><a aria-hidden="true" tabindex="-1" href="#conclusion-and-next-up"></a>Conclusion and next up</h2>
That wraps up at least the beginner topics for Poem. Next up I'm going to cover error handling, more advanced typing and more!
Enjoy this article? Find me on <a href="https://twitter.com/valhalla_dev">Twitter</a> while it's still around or check out my <a href="https://www.youtube.com/channel/UCSXxklOmlUOJfjzOkKM07gg">YouTube Channel</a>

Vectors in Rust are fairly similar to arrays in just about every other language.

Rust Vectors

Making My Way Through the Rust Book

Rust's poem_api makes REST API development easy and swagger documentation even easier

Backend API's with Rust's poem_openapi

Creating a DigitalOcean Droplet with Golang

Delaying GrabbrApp's Launch

Full-Stackism and Being a Well-Rounded Developer

Golang Microservices - How to Make a Golang Lambda Function

Pushing the Pico - D3d_Dr0p and Hyperlocal E-Graffiti

There are a lot of languages to pick from. Here is why I think you should pick a couple, and be open to experiment with more

Should you learn multiple programming languages?

Terraform - The Basics

The Gin Framework - REST API's with Golang

Writing is Dead and Meetings are Killing It

CODE MOC

Go Routines - Wicked Fast Concurrency in Golang

Atomic Habits

01_BOOK NOTES MOC

WIP Antifragile - Nassim Taleb

WIP Revolt - Nadav Eyal

Digital Gardens

Junior Developer's Resume

We'd love to believe that we're logical thinkers, but I think there's danger in it

Logical vs. Critical Thinking

Disruption Isn't Just Moving Money Around

Personal Knowledge Management (PKM)

On making a move away from research blogging and toward just research

The Obsidian Switch

The Tightening Belt

Zettelkasten Method

01_NONTECH MOC

WIP - The Qakbot Takedown

Detection engineering isn't just stopping badness. Unfortunately, false positives and false negatives, as well as mis-detections, make it much more complex

Detection Engineering: False Positives, False Negatives and Mis-Detections

1 November 2023 GrabbrApp Update

Rewrite-It-In-Rust seems like it's become a meme, but I started to see the light pretty quickly

Goodbye Golang Microservices, and Hello Rust Monoservice

26 September - Poking around with the Go compiler

22 September - Initial Irritation

16 October - Awesome SANS talk on Golang RE

WIP - Reverse Engineering GoLang Binaries

01_SECURITY_MOC

01_Research MOC

02_DATA_MOC

29 August 2023 - Check Point Shares Analysis of Qakbot Malware Group - Check Point

13 July 2023 - Avast - Go Malware on the Rise

30 August 2023 - Qakbot Malware Takedown and Defending Forward - John Hammond via Huntress

29 September 2021 - Reversing in action - Golang malware used in the SolarWinds attack

29 August 2023 - Qakbot Malware Disrupted in International Cyber Takedown - US FBI