feat(core): Add beforeApplicationShutdown hook

[BrunnerLivio]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Other... Please describe:

What is the current behavior?

At the moment only OnApplicationShutdown exists, which gets called once the server stops taking any requests.

What is the new behavior?

BeforeApplicationShutdown gets called once an e.g. system signal got sent to the process, but the app still accepts any requests, as long as all BeforeApplicationShutdown-Promises have been resolved.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

The shutdown order

- OnModuleDestroy: Use to clean up an injectable (unsubscribe Observables, etc.)
- BeforeApplicationShutdown: Gracefully shutdown all the services, but still send unavailable response codes
- OnApplicationShutdown: Shutdown all pending services

Being able to still process requests, even if a system signal has been sent, is crucial in Kubernetes.
@nestjs/terminus can be further improved once this PR gets merged. As soon as beforeApplicationShutdown gets called, Terminus will send unhealthy responses, notifying Kubernetes to switch out the Pod.

I will update the docs once this PR has been merged :)

[BrunnerLivio]

onModuleDestroy hook gets now called before the server stops taking any requests. Before this PR it was called afterward. Is that a problem? I thought the following order makes more sense, that is why I call onModuleDestroy before now.

1. onModuleDestroy
2. beforeApplicationShutdown
3. onApplicationShutdown

[coveralls]

Pull Request Test Coverage Report for Build 4157

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 95.236%

---

Totals
Change from base Build 4098:	0.0%
Covered Lines:	3638
Relevant Lines:	3820

---

💛 - Coveralls

[marcus-sa]

Does the shutdown lifecycle hooks react to SIGTERM automatically, or do we have to call close ourselves to gracefully shutdown the Nest app? This should probably be added to the documentation.

[BrunnerLivio]

@marcus-sa the onApplicationShutdown (and beforeApplicationShutdown in the future) will not listen to system signals by default. As far as I remember we decided to make it disabled by default because the application could run into memory leak issues in case multiple Nest instances are running (e.g. testing).

This is why we have added NestApplicationContext.enableShutdownHooks(signals: (ShutdownSignal | string)[] = []), which starts listening on system signals.

nest/packages/core/nest-application-context.ts

Lines 102 to 125 in fc99ccd

	public enableShutdownHooks(signals: (ShutdownSignal | string)[] = []): this {
	if (isEmpty(signals)) {
	signals = Object.keys(ShutdownSignal).map(
	(key: string) => ShutdownSignal[key],
	);
	} else {
	// given signals array should be unique because
	// process shouldn't listen to the same signal more than once.
	signals = Array.from(new Set(signals));
	}
	signals = signals
	.map((signal: string) =>
	signal
	.toString()
	.toUpperCase()
	.trim(),
	)
	// filter out the signals which is already listening to
	.filter(signal => !this.activeShutdownSignals.includes(signal));
	this.listenToShutdownSignals(signals);
	return this;
	}

More about this

I can extend the docs further, once this PR gets merged

[kamilmysliwiec]

Why close() is removed?

[BrunnerLivio]

It still exists on NestApplicationContext and behaves the same way as before.

NestApplicationContext.close() will just call NestApplicationContext.stopServer(), which in the case of NestApplicationContext will be a noop Promise. Because of inheritance NestApplication will override NestApplicationContext.stopServer and stop the actual server.

[kamilmysliwiec]

Ahh I see await this.stopServer(); in NestApplicationContext now, thanks! I missed that one.

Nonetheless, NestApplicationContext was intended to be platform-agnostic = term "server" will not always exist in case of just "context-based" applications. Maybe we should adjust the naming here?

[BrunnerLivio]

adjust the naming here

Agree. .stopApplication() or just .stop() maybe? I don't particularly like it because stop is just like a synonym for close, but I can't come up with a more descriptive name

[kamilmysliwiec]

Maybe disposeResources() or just dispose()? In the case of HTTP app, resource = server

[BrunnerLivio]

dispose() sounds alright. It is an internal method so we can still change it if we come up with something better :)

[BrunnerLivio]

@kamilmysliwiec changed stopServer to dispose.

[ninja-]

🤔

[BrunnerLivio]

Rebased with changes from #2790: Checks isNil instead of isUndefined with beforeApplicationShutdown.

---

@kamilmysliwiec any reason why this PR has not been merged yet?

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.