9.0.0 Release Notes
hueniverse opened this issue · comments
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
andfiles.etagsCacheMaxSize
configuration option (moved to an inert plugin optionetagsCacheMaxSize
in version 3.0.0). server.method()
withcache
enabled requires thecache.generateTimeout
option.- Throws when
server.start()
is called beforeserver.register()
is completed. - Require callback for
server.start()
andserver.stop()
. - Changes empty payload handling:
- empty application/json to
null
from{}
- empty text/* to
''
from{}
- empty application/octet-stream to
null
fromBuffer
- empty application/json to
- The qs module now parses dot notation names into sub objects by default (see: #2718)
New Features
server.inject()
can setremoteAddress
.server.method()
reports invalid arguments.server.cache()
cache object supports newcache.stats
information.- Caches can be configured with new
generateOnReadError
to abort calling the generate function when the upstream cache read operation fails and thegenerateIgnoreWriteError
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 serverlog
event.
Bug fixes
- Set
vary
response header wheneveraccept-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 emptyBuffer
)
Miscellaneous
- Make sure you are waiting for the
server.register()
callback to return before callingserver.start()
. - Pass a callback to
server.start()
andserver.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.
@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
@boennemann sorry but I am not going to change how we work. You can always find the changelog here: http://hapijs.com/updates
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
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
@tanepiper Inert has been removed which was responsible for serving files and directories. You need to manually register it now.
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.
@nelsonic you should really do the connection, route and start in the callback of register
Submitted a PR to fix documentation: hapijs/inert#37
@AdriVanHoudt I've updated the code block in the comment above. Thanks. 👍
Code in PR looks good
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
}
});
@jrmce open an issue