graceful shutdown handler docs?

[Brad Wood]

I'm trying to find out how to implement the GracefulShutdownHandler in an undertow server.  For the life of me, I can't find a shred of documentation other than the acknowledgement that it exists on this page

https://undertow.io/undertow-docs/undertow-docs-2.1.0/index.html#built-in-handlers

Looking at the code, there are a great deal of public methods which are never called from within the handler, which seem to indicate additional setup or configuration is required other than simply placing the handler in the handler chain.  

I have also reviewed the GracefulShutdownTestCase, but without any comments, it's really not clear what parts of the code are required to use the handler, and how much of the test code is simply mocking and setup for the sake of the test.

Can we get a proper example of what it looks like to configure a GracefulShutdownHandler?

And secondly, can someone confirm if there is the ability to set a timeout on shutdown so the server doesn't hang forever if there are hung requests.  i.e. wait up to 10 seconds for running requests to complete, before continuing with shutdown anyway.  I see the awaitShutdown method which accepts a "millis" argument, but where is that method called?  How?  When?  What does it take to configure the millis that will be passed?  There's just too much missing information to piece this together.

Thanks!

~Brad

[Brad Wood]

Any input here?

[Flavia Rainone]

Hi Brad!

The GracefulShutdownHandler is a handler that acts when your server is shutting down. It acts in two ways when shutdown starts: it prevents new requests from being served , and it also allows the requests being served to complete without errors. This happens in two steps:

1. It receives a notification from your code when the server is shutting down. After it receives this notification from your code, it will prevent new requests from being handled by returning a SERVICE UNAVAILABLE 503 response code to any request that the server receives during shutdown. Notifying the handler that your server is shutting down is mandatory, or else it is of no use.

2. It notifies you when the server is ready to conclude shutdown, which is when you should clear your resources, stop any services you use, and you're finally ready to stop the server jdk instance. This guarantees that you wait for the completion of requests being handled when shutdown starts as I pointed out above. There are three ways to do that, and we will see each one of them in the quick tutorial below.

So, here is how you use GracefulShutdownHandler:

1. You set the root handler to be a GracefulShutdownHandler when creating the server. Notice that you want it to be the outermost handler in your chain, simply because you don't want requests reaching other handlers before denying a request that was received after the server started shutting down.

```

GracefulShutdownHandler shutdownHandler = Handlers.gracefulShutdown(nextHandler);

```

2. You invoke start() before starting the server, that way, you know the handler is ready to accept requests, with everything set up, before the server actually starts receiving requests. Notice you don't add any special configuration to the handler.

```

shutdownHandler.start();

```

3. Simply leave the server running as it normally would, until you decide you need to shutdown.

4. When ready to start shutting down your server, you need to flag to the shutdown handler that the server is going to shutdown. For that, invoke the shutdown method(). At this step, you are executing the step (1) above:

```

shutdownHandler.shutdown();

```

5.Now we are going to move to the step (2) above. You don't actually shutdown the server at the previous step. After invoking shutdown() you wait until all requests that were being handled when you invoked shutdown have been fully responded to. Only after that you are free to clear your resources, stop services, stop the jdk, and anything else that you need to do. You know for a certain that no new requests are going to come in because the GracefulShutdownHandler is blocking all new requests. To know when all requests have been fully served, after invoking shutdown(), you can:

   a. Invoke awaitShutdown(): ```shutdownHandler.awaitShutdown();```

       This method will simply block your thread until no requests are being served. When it returns, you know it is safe to stop the server.

   b. Invoke awaitShutdown (milis): ```shutdownHandler.awaitShutdown(60000);```

       This method is similar to the previous one. It will block your thread until either no requests are being served, or the milis timeout expires. This one is useful if you notice that the server waits for a long time because it takes too long to serve some requests. So, you can say something like: "60 s is the maximum time I will wait for the server shutdown; after that I'm done you can continue shutdown even if there are requests still being served"

   c. Invoke addShutdownListener: ```shutdownHandler.addShutdownListener((shutdownSuccessful) -> { if (shutdownSuccessful) { cleanResourcesAndExit();}}); ```

      This method will receive a listener that is notified when all requests have completed. Notice that this method, differently from the previous two, will not block the invoking thread. So, you need to make sure the listener is responsible for triggering the "clear the resouces, stop services, finally stop the jdk instance, etc" step.

I have created a task for improving the documentation on the handler:
https://issues.redhat.com/browse/UNDERTOW-2551

For the time being, I hope, though, that my explanation above sorts out your questions. Please let me know if you have further questions on this topic.

Best regards,

Flavia

[Brad Wood]

Thanks for the walk through.  I see it's much more manual than I had originally thought.  I first assumed that the handler would register itself with the Undertow server and automatically do its job when undertow's stop() method was called.  Is it safe to say I need to wait to call the stop() and undeploy() methods on each of my servlet deployments and the stop() method on my undertow server until AFTER the shutdown handler is finished?

Another question I have is I don't have just one root handler.  Depending on the server my user's have configured, there may be multiple HTTP listeners, each with their own separate handler chains.  This would require a separate shutdown handler instance for each root listener, as well as logic to track, them all, and manage them all.  That's fine-- my question is whether the shutdown handler expects to be a singleton since there are static members tracked at the class level which seems like that may be problematic if I have multiple versions of this handler, each wrapping separate handler chains tied to different HTTP listeners.  Is the graceful shutdown handler safe to have multiple instances of it?

Thanks!

~Brad

Developer Advocate

Ortus Solutions, Corp 

E-mail: br...@coldbox.org

ColdBox Platform: http://www.coldbox.org 

Blog: http://www.codersrevolution.com

--
You received this message because you are subscribed to the Google Groups "Undertow Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to undertow-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/undertow-dev/44e903ef-bd4b-4968-a4cd-3c662da93df0n%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Flavia Rainone]

Yes, it is safe to say you need to wait for the graceful handler at the step 5 and after that, you need to invoke stop and undeploy in your deployments. And then you can stop the server. The order does not matter much, the Undertow.stop will close the http connections (hence, it will close your server ports), the stop();undeploy(); in the deployment will clean up the servlet resources.

Regarding having multiple graceful shutdown handlers, yes, it is safe. The class has multiple static fields but none of them keep any state info.