Summary

hapi v9.0.0 is a small collection of changes meant to streamline the development process of plugins within the hapi.js community. The main change removes the three built-in plugins from the core distribution: inert (files and directories), vision (view templates), and h2o2 (proxy). By removing this functionality, the community can more rapidly innovate on these features as well as open the door for competing implementations based on new use cases.

• Upgrade time: low - a couple of hours to a day for most users
• Complexity: low - mostly adding a few boilerplate lines to existing code
• Risk: low - low risk of side effects (mostly just empty payload changes) and few changes to keep track of overall
• Dependencies: low - no changes to the plugin API

Sponsor

The v9.0.0 major release is sponsored by Sideway.

Breaking Changes

• Removed inert, vision, and h2o2 dependencies and built-in integration.
• Removed the server minimal option.
• Removed the server files and files.etagsCacheMaxSize configuration option (moved to an inert plugin option etagsCacheMaxSize in version 3.0.0).
• server.method() with cache enabled requires the cache.generateTimeout option.
• Throws when server.start() is called before server.register() is completed.
• Require callback for server.start() and server.stop().
• Changes empty payload handling:
  • empty application/json to null from {}
  • empty text/* to '' from {}
  • empty application/octet-stream to null from Buffer
• The qs module now parses dot notation names into sub objects by default (see: Breaking change with query string validation from 8.6.0 to 9.0.2 #2718)

New Features

• server.inject() can set remoteAddress.
• server.method() reports invalid arguments.
• server.cache() cache object supports new cache.stats information.
• Caches can be configured with new generateOnReadError to abort calling the generate function when the upstream cache read operation fails and the generateIgnoreWriteError to pass write errors back (defaults to ignore cache errors).
• Added new server extension points: onPreStart, onPostStart, onPreStop, onPostStop.
• server.initialize() starts the cache and finalizes plugin registration without listening on the ports.
• New defaultContentType payload option.
• New connection compression configuration option.
• Node HTTP clientError events are emitted via the server log event.

Bug fixes

• Set vary response header whenever accept-encoding is received.
• Various etag fixes.
• Preserve response validation information when sample is zero.
• Include caching instructions on 304 (if 200 is enabled).
• Fixes issue of errors returned to the wrong request when caching is used.

Updated dependencies

• shot from v1.5.3 to v1.6.0
• catbox from v4.3.0 to v6.0.0
• content from v1.0.1 to v1.0.2
• moment from v2.10.3 to v2.10.6
• joi from v6.4.1 to v6.6.1
• iron from v2.1.2 to v2.1.3
• call from v2.0.1 to v2.0.2
• boom from v2.7.2 to v2.8.0
• ammo from v1.0.0 to v1.0.1
• accept from v1.0.0 to v1.1.0

Migration Checklist

Removal of built-in plugins

Check your code for view, render, views, file, directory, and proxy. If you used any of these features you will need to manually load the required plugins to access these features.

• inert - plugin for serving static files
• vision - plugin for rendering templates
• h2o2 - plugin for proxy support

If you are already loading plugins, simply add the ones from the list that you want to your plugin list. If you are not, use the server.register() method to load these. Remember to add the plugins you need to your package.json file.

If you have plugins that depend on these features, make sure to specify it using the server.dependency() method. Note that this will break compatibility with hapi 8.x.x because the three plugins are loaded before connections are set up and will show us as missing.

The server minimal option is now the default and no longer supported.

If you used the static file features, the server files and files.etagsCacheMaxSize configuration option have been moved to the inert plugin under option etagsCacheMaxSize in v3.0.0.

Caching

Previous versions had a potential critical problem if a server method or cache using the generateFunc option got stuck. This makes every request to get() to get stuck and it will never release. To solve this, catbox included the generateTimeout option.

The generateTimeout option is now required. If you are using server.cache() or server.method() with the cache option, you will need to add the cache.generateTimeout option. Set to false to keep the previous v8.x.x behavior.

Empty payload

Check your code for payload assumptions when the client sends an empty payload (zero bytes). The following changed when handling an incoming empty payload request:

• empty application/json is now null (previously {})
• empty text/* is now '' (previously {})
• empty application/octet-stream is now null (previously an empty Buffer)

Miscellaneous

• Make sure you are waiting for the server.register() callback to return before calling server.start().
• Pass a callback to server.start() and server.stop().
• If you accept query parameters with dots and don't want them parsed into object with keys, pass the { allowDots: false } query qs option.