spray-can webservice graceful shutdown

Question

I have spray.io based webservice, it runs as standalone jar (I use `sbt assembly` and then just `java -jar myws.jar`). It has pretty the same bootsrap as in spray examples, like this: ``` /** Bootstrap */ object Boot extends App { // we need an ActorSystem to host our application in implicit val system = ActorSystem("my-system") // create and start our service actor val service = system.actorOf(Props[MyServiceActor], "my-ws-service") implicit val timeout = Timeout(10.seconds) CLIOptionsParser.parse(args, CLIOptionsConfig()) map { config => // start a new HTTP server IO(Http) ? Http.Bind(service, interface = config.interface, port = config.port) } } ``` Now I just run the process in the backgroud with `java -jar my-service "$@" &` and stop with `kill -9 pid`. I'd like to stop my webservice gracefully, meaning that it finishes open connections and refuses new ones. Spray-can page on github recommends `to send it an Akka PoisonPill message`. Ideally I'd like to initiate it from command l…

Accepted Answer

While I tried to use SIGTERM and JVM hook, I was in need to block the hook thread from exiting until my shutdown sequence finishes, and I simply don't know how to do it (I'm a bit inexperienced in akka, so maybe I missed some obvious solution).

What I finally did is attaching one more HTTP listener to localhost only, which has method to initiate shutdown (also it happened to be convenient for other tasks, like getting server status, triggering events in the application and such).

This can look like this (I suspect this may contain unnecessary actions, so refinements are welcome):

In bootstrap:

```
implicit val system = ActorSystem(...)

// create and start external service actor
val service = system.actorOf(Props[MyWebServiceActor], "my-web-service")

// create internal service to manage application
val controlService = system.actorOf(Props[ControlServiceActor], "control-service")

implicit val timeout = Timeout(10.seconds)

// start a new HTTP server for external service (notifying control of HTTP listener)
IO(Http).tell(Http.Bind(service, interface = config.interface, port = config.port), controlService)

// start internal server looking at localhost
IO(Http) ? Http.Bind(controlService, interface = "127.0.0.1", port = config.controlPort)
```

And the control service itself:

```
class ControlServiceActor extends Actor with HttpService with ActorLogging {
  def actorRefFactory = context
  implicit val system = context.system

/* Listener of main service */
  var listener: ActorRef = _

def receive = {
    // this is reply from IO.Http when HTTP listener is bound
    case Http.Bound(_) =>
      listener = sender()
      context.become(mainContext)
  }

// http api for graceful stop
  val mainContext = runRoute {
    path("stop") {
      get {
        parameter('timeout.as[Int] ? 60) { timeout =>
          complete {
            // unbind makes listener to reject new connections
            context.become(shuttingDownContext)
            log.warning(s"Stopping application within $timeout seconds...")
            context.watch(listener)
            listener ! Http.Unbind(timeout.seconds)

"Stopping..."
          }
        }
      }
    }
  }

// Shutdown sequence
  val shuttingDownContext = ({
    // when unbound HTTP listener not accepting connections
    case Http.Unbound =>
      log.info("Webservice unbound, waiting for active connections to complete")

// when HTTP listener terminated after unbound it has been processed all requests
    case Terminated(ref) if ref == listener =>
      log.info("Webservice finished, exiting")
      system.shutdown()
  }: Actor.Receive) orElse runRoute(complete("Shutdown in progress"))
}
```

spray-can webservice graceful shutdown

Solution

Problem