9.0.0 Release Notes

[hueniverse]

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.

[boennemann]

@hueniverse Thanks a lot for this release!

I would like to ask you to not use the issue tracker for release notes.

I first notice that a dependency of mine has a breaking change when my badges turn yellow or red. I then turn over to your repository and can neither find a CHANGELOG.md or any release notes attached to the tag you created on GitHub. From then on it could just be anywhere: an issue, a closed issue, a blogpost, hidden in the commits, no release notes at all, etc. Please make it easier for everyone to upgrade by posting the release notes at common places like a changelog file, or much better, the GitHub release page.

Thank you,

Stephan

[hueniverse]

@boennemann sorry but I am not going to change how we work. You can always find the changelog here: http://hapijs.com/updates

[AdriVanHoudt]

we can go all crazy and try to link issues with release note tag to the correct milestone on the site, will open an issue for it on the website repo

[tanepiper]

Has something been missed for route handlers? Getting Error: Unknown handler: directory on a file handler:

server.route({
    method: 'GET',
    path: '/{file*}',
    config: {
      handler: {
        directory: {
          path: server.settings.app.server.files.relativeTo,
          listing: false
        }
      }
    }
  });

Don't see anything in the 8 or 9 notes about this changing, but now breaking in 8 -> 9 release

[gergoerdosi]

@tanepiper Inert has been removed which was responsible for serving files and directories. You need to manually register it now.

[nelsonic]

If others are seeing the Error: Unknown handler: directory when trying to serve a directory in Hapi.js 9.0.1 the fix is easy: simply follow the instructions on https://www.npmjs.com/package/inert#examples
e.g:

var Hapi = require('hapi');
var Inert = require('inert');
var Path = require('path');
var server = new Hapi.Server();
var port = process.env.PORT || 8000;
server.register(Inert, function () {
  server.connection({ port: port });
  server.route( {
    method: 'GET',
    path: '/{param*}',
    handler: {
      directory: { path: Path.normalize(__dirname + '/') }
    }
  });
  server.start(function() { console.log('Visit: http://127.0.0.1:' +port) });
}); // requires a callback function but can be blank

done.

[AdriVanHoudt]

@nelsonic you should really do the connection, route and start in the callback of register

[gergoerdosi]

Submitted a PR to fix documentation: hapijs/inert#37

[nelsonic]

@AdriVanHoudt I've updated the code block in the comment above. Thanks. 👍

[AdriVanHoudt]

Code in PR looks good

[jrmce]

This may just be a documentation issue on the release notes (or maybe I'm understanding it wrong) so not opening an issue yet, but I'm noticing that setting generateTimeout to false on the cache object of a server method doesn't work, you'll get an error that generateTimeout is required.

server.method('cached', internals.getCached, {
        cache: {
            expiresIn: Moment.duration(1, 'months').asMilliseconds(),
            generateTimeout: false
        }
});

[hueniverse]

@jrmce open an issue