How to trigger a shutdown from outside Rocket?

[blackghost1987]

I've checked the documentation for Shutdown, and it looks great, it's really clear on how to get a Shutdown handle after ignition from a rocket instance, or through a request guard. My problem is I can't really find a way to trigger a shutdown from outside Rocket, is this possible currently?

I'm trying to use Rocket as part of a larger app, which handles some stuff before starting the Rocket instance (or not starting it at all), then later stopping it on demand (via an mpsc channel). I've achieved the first part by moving the entry point of the server to a child module (based on a recommendation from a previous discussion), like so:

mod web_server {
    #[launch]
    pub fn run_rocket_server() -> Rocket<Build> {
        rocket::build().attach(...)
    }
}

fn main() {
    // do stuff without Rocket
    
    // launch Rocket
    web_server::main();
}

I've also tried to use #[rocket::main] instead of launch. My first approach was to pass the mpsc::Receiver as a parameter and use it inside Rocket to trigger a shutdown, but neither of the macro functions allow parameters in the function header. Next I've tried to return the Rocket instance after launching it, so I can get the shutdown handler outside, but neither of the functions return until the server is stopped...

I can return the Rocket instance if I do not launch the server from #[rocket::main], but then I've lost the built-in tokio runtime handling of Rocket. In this case I have to spin-up an executor just to launch Rocket (after I got the shutdown handle from Rocket), which would be a hassle because my app doesn't really use anything async outside of Rocket.

Any recommendations on how to tackle this problem?

[jebrosen]

It seems like the main barrier is going to be #[launch] - it's designed to replace Rust's (synchronous!) fn main() entry point, which you need for other things. You should take a look at the launch() function instead; for instance, you could do something like this:

// keeping this split out makes it easy to call 'rocket()' in tests
fn rocket() -> Rocket<Build> {
    rocket::build().attach(...).mount(...)
}

/// Spawns a Rocket server and returns its Shutdown handle
async fn spawn_rocket() -> Shutdown {
    let rocket = rocket().ignite().await;
    let shutdown_handle = rocket.shutdown();
    rocket::tokio::spawn(rocket.launch());
    shutdown_handle
}

The spawn_rocket() function can be called (and awaited) from any async function running on the tokio runtime, whether it be #[rocket::main], #[tokio::main], or something else.

[blackghost1987]

Thanks, I didn't know I can access the Tokio instance of Rocket through rocket::tokio::spawn(). There's just one issue: shutdown() is not available on Rocket<Build>, only on Rocket<Ignite>, and the ignite() function is also async. So while this is a good solution, it still requires a custom runtime, because spawn_rocket will be async and something has to await on it.
As far as I can see, there's no blocking way anymore to ignite and launch Rocket, so it looks like I have to try my hand at Tokio after all.

Thanks for your help!

[jebrosen]

Thanks, I didn't know I can access the Tokio instance of Rocket through rocket::tokio::spawn().

That's not quite what's happening there: rocket::tokio is just a re-export of the tokio crate (so you don't need to put it in Cargo.toml yourself and match the versions up). tokio::spawn always acts upon the currently running runtime, regardless of who/what started it.

There's just one issue: shutdown() is not available on Rocket<Build>, only on Rocket<Ignite>, and the ignite() function is also async. So while this is a good solution, it still requires a custom runtime, because spawn_rocket will be async and something has to await on it.

Whoops! I fixed the code in my previous answer to account for that.

[blackghost1987]

I managed to get this to work, but it's not pretty. I'm just leaving this solution here for others looking for a quick hack, but I presume this is not recommended.
I've expanded on @jebrosen 's example code by creating a custom Tokio runtime (with rocket::tokio::runtime::Builder), then called block_on(spawn_rocket()) on it. This is actually breaking the Shutdown functionality and gives these warnings:

Rocket is executing inside of a custom runtime.
Rocket's runtime is enabled via `#[rocket::main]` or `#[launch]`.
Forced shutdown is disabled. Runtime settings may be suboptimal.

So I hacked around this limitation by renaming my runtime to something starting with rocket-worker, which did the trick, but it still breaks the Shutdown functionality a bit. It emits the following warning: "Server failed to shutdown cooperatively. Terminating.", but at least the application is stopping now.

So the bottom line: it IS possible currently to stop a Rocket instance from outside Rocket BUT it's super ugly and breaks cooperative Shutdown.

[jebrosen]

Hm, I think I understand the issue better now. I was a bit focused the code you posted, which doesn't include as much detail of the parts that actually made this difficult. I think there are really two separate "problems" here to deal with, the non-async vs async and passing the shutdown handle around. One way you could use #[rocket::main] would be along these lines:

#[rocket::main]
async fn main() {
    // for sending the shutdown handle
    let (tx, rx) = channel();
    std::thread::spawn(move || run_non_async_thread(rx));

    let shutdown_handle = spawn_rocket().await;
    tx.send(shutdown_handle.clone());

    // Wait for the server to shut down before exiting.
    //  TODO: Alternatively, set up an async channel to wait for the non-async code - depending on what you need!
    shutdown_handle.await;
}

I think it's worth exploring this and other ideas further; perhaps there are additional or different APIs Rocket could provide. But I'm still not sure I've accurately guessed which part(s) aren't working well together, so knowing if this approach is any better/worse would help a lot!

[blackghost1987]

Yes, I see now I should have been more clear with my requirements, it wasn't really clear in my head either 😃 I gave it some though and I think there are actually 4 "problems" here. You mostly got it right, but here it is a bit more explicitly:

1. I have non-async code which should run parallel with async Rocket
2. The non-async code needs a way to notify Rocket to shut down
3. I would like to use Rocket's own runtime, for two reasons: A) the other parts of the application don't require an async runtime B) Shutdown depends on Rocket's own runtime as it seems
4. the application's main() cannot be async, so #[rocket::main] cannot be on it

Your latest code handles the first three perfectly, but the catch is at the 4th problem... That was the reason why I was trying to put Rocket in a sub-module originally. I'll investigate it though, maybe I can get away with an async main().
Thanks to your previous comment about "acting upon the currently running runtime", I realized I can get the runtime anywhere with rocket::tokio::runtime::Handle::current(). It may be possible to have #[rocket::main] on the application's main(), with only non-async code inside it calling simple non-async functions, right up to the point where I need to start Rocket. Then I could get the current runtime handle and use on_block(spawn_rocket()). I'll play around with this idea a bit more, maybe it will work. (But it still seems a bit superfluous to create a runtime at application startup, even in cases when Rocket won't be launched at all).

If we are talking about theoretical future Rocket improvements, I think I'd need either of the following to make my life easy:

• a way to build Rocket outside of #[rocket::main], before even having a runtime (after all building is non-async), but still start it with Rocket's runtime. This seems impossible right now because the macros only handle functions without parameters and Rocket<Build> have to be constructed inside #[rocket::main], otherwise I cannot launch it with Rocket's runtime
• get stuff from Rocket after ignition but before launching it, without using a custom runtime. This seems impossible because ignite() is async and the runtime is blocked right away after it's created in async_main. So if I want to run ignite(); <custom code>; launch();, then I have to do it inside #[rocket::main], which won't return (and I can't give it a channel to send stuff out either, because of the previous bullet point)

The first one seems the easiest to tackle. Maybe we could add a function which could accept a pre-built Rocket<Build> instance (building doesn't require a runtime), then Rocket could start the runtime and ignite and launch it. So it would be like #[launch], but a regular function expecting a Rocket<Build> instead of a macro. If it has to be a macro for some codegen reasons, then it could be a macro working on functions like fn(Rocket<Build>) -> Rocket<Build>. Maybe this is even better, because this way the function could get a "semi-built" Rocket and complete it before launching it. What do you think? Should I create a Feature Request for this, or am I on the wrong track?

[blackghost1987]

As a follow up: My approach with rocket::tokio::runtime::Handle::current() doesn't work. I've changed it to try_current() and got a TryCurrentError, which means according to the doc that no Runtime has been started. This is obviously not the case, because try_current() works just fine if I'm doing it directly in the application's async main() (annotated with #[rocket::main]). It fails when I'm trying to use it in some "deeper" code. My assumption is this issue is caused by calling try_current() from another thread 😞.

I think I have to change my 4th requirement: it's not really about annotating the application's main, the real problem is Rocket's runtime should be started from another thread, not the main thread of the application... AFAIK this can only be done by using one of the macros in a sub-module, then calling the generated main() in my thread. But the macros make it impossible to give data to / retrieve data from the Rocket instance, so we are back to square one.

I realize this requirement set might be a niche, but I'm pretty sure the issue with the macros is a more generic problem and solving it could help others as well. I'll create a feature request for it.

[blackghost1987]

Here it is: #1881