Learn how to put your digital team to work with MuleSoft for Agentforce.
Register now
Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.3)
  3. Develop Mule Applications

  4. Understand HTTP Connection Handling During Mule Runtime Shutdown

Understanding HTTP Connection Handling During Mule Runtime Shutdown

Mule runtime engine (Mule) manages HTTP connections during shutdown through a two-stage graceful shutdown process followed by a forceful termination.

The process first refuses new connections while allowing existing ones to complete with a Connection: close signal, then rejects new requests entirely while finishing in-flight processing, before finally forcefully terminating all remaining connections upon timeout.

This supports seamless scale-down scenarios, enabling the reduction of Mule replicas while maintaining the stability and reliability of the application by progressively draining traffic.

HTTP Connection Handling Diagram

This diagram shows how HTTP connection behaves during Mule shutdown:

runtime http connections diagram

Phase 1: Mule Started

  • Mule State: Mule has started and is running normally.

  • HTTP Behavior: All incoming HTTP traffic routes to Mule and gets processed without any special handling.

Transition: Send Stop Signal to Mule

  • The shutdown sequence starts by sending a stop signal to the Mule instance.

Phase 2: HTTP Graceful Shutdown - Mule Stopping

  • Trigger: Reception of the stop signal.

  • Duration: Up to the configured HTTP Graceful Timeout (default: 5 seconds). However, if all existing HTTP connections close before this timeout period elapses, the HTTP Graceful Shutdown phase ends early, and Mule doesn’t wait for the full timeout duration.

  • Mule State: Mule is initiating a shutdown or transitioning to stopped.

  • HTTP Behavior:

    • No new connections: The HTTP server stops accepting new incoming TCP connections (the acceptor socket is closed).

    • Existing and In-Flight requests: Ongoing HTTP requests (both those already being processed in-flight and those on existing, established connections) continue to be handled normally. However, all responses include the Connection: close header, signaling to the HTTP client to close the connection after the current request-response cycle.

    • Early termination: If there are no active HTTP connections when the stop signal is received, the HTTP Graceful Shutdown phase ends immediately, even before the timeout period expires.

    • Late-Arriving requests: If an HTTP request arrives just before the HTTP Graceful Timeout is reached, it’ll still be processed normally, even if the processing extends beyond the HTTP Graceful Shutdown timeout.

Transition: HTTP Graceful Shutdown Timeout Elapsed

  • The configured duration for the HTTP Graceful Shutdown has ended.

Phase 3: Mule Graceful Shutdown - Mule Stopping

  • Trigger: Expiration of the HTTP Graceful Shutdown Timeout.

  • Duration: Up to the configured Mule Graceful Shutdown Timeout (default: 5 seconds).

  • Mule State: Mule is shutting down gracefully.

  • HTTP Behavior:

    • Reject new requests (503): Any new HTTP requests arriving at the runtime is immediately rejected with a 503 Service Unavailable error.

    • Reject new Requests (404): Once the Mule app unregisters the HTTP endpoint from the underlying HTTP server, subsequent new HTTP requests receive a 404 Not Found error.

    • Complete In-Flight messages: HTTP requests that were already fully read and are being processed (in-flight messages) complete their execution normally.

Transition: Mule Graceful Shutdown Timeout Elapsed

  • The configured duration for the overall Mule Graceful Shutdown has ended.

Phase 4: Mule Stopped

  • Trigger: Expiration of the Mule Graceful Shutdown Timeout.

  • Mule State: Mule has stopped.

  • Behavior: The Mule process proceeds to a forceful shutdown and eventually exits. As a result:

    • All remaining open HTTP connections close abruptly.

    • Clients connected to these forcibly closed connections will likely receive a connection reset error or a broken pipe error, depending on the TCP status of their socket at the time of closure.

Configure Shutdown Timeout

While the HTTP Graceful Shutdown Timeout and the overall Mule Graceful Shutdown Timeout serve distinct purposes in the shutdown sequence, you configure them using the same shutdownTimeout parameter within the <configuration> element of your Mule app’s XML file.

Specify the value in milliseconds (default 5000 milliseconds), which controls the maximum duration for both graceful shutdown periods. For example:

<mule ...>
  <configuration shutdownTimeout="10000" /> </mule>

For details, refer to Global Configurations Reference.