Collect, document, and answer FAQ

[SergioBenitez]

There are questions that are frequently asked that are not directly related to Rocket but impact Rocketeers nevertheless. In pursuit of making Rocket as friendly and easy to use, we should collect these questions in an official capacity and answer them once and for all. This issue tracks such questions.

• How do I listen on IPv4 and IPv6?
• How do I upload a file / what is this multipart metadata in my stream?
• Can I, and if so how, do I handle websockets?
• How do I respond with different kinds of responses, with different status codes?
• Should I use global state with something like lazy_static!?
• How do I access managed state outside of a Rocket-related context?
• How do I mount a generic route?
• How do I make Rocket restart automatically when I change source code?
• How do I get an &Request in a handler?
• How do I get a specific header in a handler?
• When will version x + 1 be released? Why does it take so long?
• Is example foo broken? It doesn't work for me.
• Why so many macros? I heard they lead to bad errors and make my code harder to understand.
• Is Rocket slow? Is Rocket fast?
• Can I use Rocket in production? Should I? It's only 0.x!

Please feel free to make suggestions!

[SergioBenitez]

Hiding comments as "resolved" as I bring them into the top-level post or they get addressed elsewhere in docs.

[SergioBenitez]

Indeed, this is a question I'd love to answer but one that requires more than a few paragraphs. I (or someone else) will eventually write such a book, I imagine.

[the10thWiz]

@jhwgh1968 I would recommend using a more regular approach to starting the server: namely, by using #[launch] or #[rocket::main], just from another module, and calling the generated main function in a new thread to start the server. You can then use the existing shutdown mechanisms to shutdown the server when it's done.

Using the codegen (launch or rocket::main), is highly recommended, because it makes maintaining the code simpler; the internal functions to start the server are considered somewhat unsafe, and subject to change. Relying on the codegen prevents changes to these internal APIs affecting your codebase, since the codegen will simply output the correct code to start the server.

[MikailBag]

Here is a way to run Rocket server on an already existing Tokio runtime

async fn run_rocket_server() -> Result<(), Box<dyn std::error::Error>> {
    let rocket = rocket::build();
    // configure routes, fairing, etc
    rocket.launch().await?;
    Ok(())
}

This code does not use any internal APIs.

[SergioBenitez]

Here is a way to run Rocket server on an already existing Tokio runtime

async fn run_rocket_server() -> Result<(), Box<dyn std::error::Error>> {

    let rocket = rocket::build();

    // configure routes, fairing, etc

    rocket.launch().await?;

    Ok(())

}

This code does not use any internal APIs.

This is fine, but it isn't recommended. The Rocket-created runtime is tuned for Rocket applications. It's also Rocket-aware with regards to shutdown. If you do this, graceful shutdown may not work, as indicated in the documentation.

[the10thWiz]

I believe running Rocket on an existing runtime is explicitly not recommended.

From my understanding, Rocket hopes to eventually be able to switch to a different runtime than Tokio, and code like this would make that a breaking change.

[SergioBenitez]

See also https://api.rocket.rs/v0.5-rc/rocket/fn.execute.html.

[SergioBenitez]

Context is only designed to be used as the error type of a failed form parse. This is why, for instance, it doesn't implement FromForm. Instead, Rocket enforces strictly typed form parsing as indicated throughout the docs.

Thus, pre-population of a form should be done by populating a strongly typed value with whatever field values you'd like and rendering those fields in the template.