7.0.0 Release Notes

[hueniverse]

Summary

hapi v7.0 includes a list of breaking changes collected over the last few months. There is no theme to this release other than housekeeping - changing defaults and interfaces required for moving the framework forward. The most significant changes are removing views support from the main server configuration (leaving only server.views() and plugin.views()), and changes to the cache API via new version of catbox.

• Upgrade time: low - a few hours to a day for most users
• Complexity: low - small list of well understood, easy to locate, and trivial to modify
• Risk: low - no side effects
• Dependencies: low - requires validation that plugin used are unaffected.

Breaking Changes

• Proxy handler (reply.proxy() or handler: { proxy: {} }) will no longer include local state (cookies) when configure with passThrough. This changes the default from including local state by default to excluding it. This is a security change as in most cases, local state should not be passed on upstream when proxied.
• pack.handler() and server.handler() registration function first argument changed from the entire route object to just the route configuration (route.settings).
• server.cache() and plugin.cache() now require passing the generateFunc configuration setting to use staleIn.
• Remove cache.getOrGenerate() support.
• cache.get() callback signature when used without generateFunc changed from function(err, cached) to function(err, value, cached, report).
• pack.compose() no longer supports passing a '$env.' value for host or port (still supported when using the CLI).
• Authentication tos no longer supported.
• Server configuration no longer accepts views.

New Features

• server.cache() and plugin.cache() accept a new dropOnError settings which allows retaining stale value if generation of new value fails.
• CLI manifest can now include '$env.' values anywhere, not just for server host and port.
• Override individual route file path with new config.files.relativeTo option.

Migration Checklist

Server Views Configuration

hapi 6.x supports two ways to configure views: via the server configuration object views key, and programmatically via server.views() and plugin.views(). This change removes the first option.

• Look for any explicit creation of Hapi.Server objects using new or Hapi.createServer().
• If you are passing the views key, move that part of the config into a direct call to server.views() after constructing the server object.
• If you are using the CLI with a manifest file to construct the server and configure it with a views manager, this is no longer supported directly. Instead, consider moving the views configuration into one of your application plugins, or use the utility visionary plugin to move that part of the configuration to the plugins section.

Proxy

• Look for proxy handlers or replies (reply.proxy() or handler: { proxy: {} }) with the passThrough option set to true.
• Check if you are configuring any state keys (cookies) using server.state() or plugin.state().
• If you still want those state keys passed upstream when proxied, set the proxy option localStatePassThrough to true or set the state option passThrough to true.

Handler Registration

• Look for any custom handler using pack.handler() and server.handler().
• Change the method argument function signature to take the route configuration object instead of the internal route object.

Caching

• Look for server.cache() and plugin.cache() calls.
• If you are calling cache.getOrGenerate() on the returned object, change it to call cache.get() instead. Pass the generation function to the cache provisioning method (e.g. server.cache()) using the generateFunc setting.
• If you are calling cache.get(), change the callback signature from function(err, cached) to function(err, value, cached, report).

Miscellaneous

• If you are calling pack.compose() and passing a manifest object which includes server host or port using the '$env.'prefix, change it to the actual value by reading the environment variable yourself first and then setting it in the manifest object. This does not apply when using the CLI.
• Look for routes with the config.auth.tos setting and remove it. Authentication tos no longer supported and must be implemented in your application.

[dminkovsky]

\o

[mwawrusch]

Hi Eran,

just want to let you know how much I appreciate you taking the time to write those release notes. Very helpful and great for the hapi community.

[dminkovsky]

Likewise, actually. These are really unique to FOSS.

[hueniverse]

@mwawrusch It's how I get away with breaking changes multiple times a year.