|
2 years ago | |
---|---|---|
.. | ||
lib | 2 years ago | |
CHANGELOG.md | 2 years ago | |
LICENSE | 2 years ago | |
README.md | 2 years ago | |
package.json | 2 years ago |
Netflix services uses VError to make operation of Node.js applications easier through meaningful error chains. VError is an amazing library by Joyent and we are glad for all the hard work for the contributors made during the years. In early 2019 Netflix error handling requirements started to broaden enough that we had to find a way to make quick iterations on VError with minimizing the churn on existing VError customers. As a result of this we decided to fork VError as NError. We hope in the future after the initial development period we can seek convergence between the two projects.
This module provides several classes in support of Joyent’s Best Practices for Error Handling in Node.js. If you find any of the behavior here confusing or surprising, check out that document first.
See API
The error classes here support:
The classes here are:
For the full list of features see API.
First, install the package:
npm install @netflix/nerror
If nothing else, you can use VError as a drop-in replacement for the built-in JavaScript Error class, with the addition of printf-style messages:
const { VError } = require('@netflix/nerror');
const err = new VError('missing file: "%s"', '/etc/passwd');
console.log(err.message);
This prints:
missing file: "/etc/passwd"
You can also pass a cause
argument, which is any other Error object:
const fs = require('fs');
const filename = '/nonexistent';
fs.stat(filename, function (err1) {
const err2 = new VError(err1, 'stat "%s"', filename);
console.error(err2.message);
});
This prints out:
stat "/nonexistent": ENOENT, stat '/nonexistent'
which resembles how Unix programs typically report errors:
$ sort /nonexistent
sort: open failed: /nonexistent: No such file or directory
To match the Unixy feel, when you print out the error, just prepend the
program’s name to the VError’s message
. Or just call
node-cmdutil.fail(your_verror), which
does this for you.
You can get the next-level Error using err.cause()
:
console.error(err2.cause().message);
prints:
ENOENT, stat '/nonexistent'
Of course, you can chain these as many times as you want, and it works with any kind of Error:
const err1 = new Error('No such file or directory');
const err2 = new VError(err1, 'failed to stat "%s"', '/junk');
const err3 = new VError(err2, 'request failed');
console.error(err3.message);
This prints:
request failed: failed to stat "/junk": No such file or directory
The idea is that each layer in the stack annotates the error with a description of what it was doing. The end result is a message that explains what happened at each level.
You can also decorate Error objects with additional information so that callers can not only handle each kind of error differently, but also construct their own error messages (e.g., to localize them, format them, group them by type, and so on). See the example below.
The two main goals for VError are:
"ip": "192.168.1.2"
and "tcpPort": 80
. This can be used
for feeding into monitoring systems, analyzing large numbers of Errors (as
from a log file), or localizing error messages.To really make this useful, it also needs to be easy to compose Errors:
higher-level code should be able to augment the Errors reported by lower-level
code to provide a more complete description of what happened. Instead of saying
“connection refused”, you can say “operation X failed: connection refused”.
That’s why VError supports causes
.
In order for all this to work, programmers need to know that it’s generally safe to wrap lower-level Errors with higher-level ones. If you have existing code that handles Errors produced by a library, you should be able to wrap those Errors with a VError to add information without breaking the error handling code. There are two obvious ways that this could break such consumers:
name
to determine what
kind of Error they’ve got. To ensure compatibility, you can create VErrors
with custom names, but this approach isn’t great because it prevents you from
representing complex failures. For this reason, VError provides
findCauseByName
, which essentially asks: does this Error or any of its
causes have this specific type? If error handling code uses
findCauseByName
, then subsystems can construct very specific causal chains
for debuggability and still let people handle simple cases easily. There’s an
example below.name
, message
, and stack
, but also fileName
,
lineNumber
, and a few others. Plus, it’s useful for some Error subclasses
to have their own private properties -- and there’d be no way to know whether
these should be copied. For these reasons, VError first-classes these
information properties. You have to provide them in the constructor, you can
only fetch them with the info()
function, and VError takes care of making
sure properties from causes wind up in the info()
output.Let’s put this all together with an example from the node-fast RPC library. node-fast implements a simple RPC protocol for Node programs. There’s a server and client interface, and clients make RPC requests to servers. Let’s say the server fails with an UnauthorizedError with message “user ‘bob’ is not authorized”. The client wraps all server errors with a FastServerError. The client also wraps all request errors with a FastRequestError that includes the name of the RPC call being made. The result of this failed RPC might look like this:
name: FastRequestError
message: "request failed: server error: user 'bob' is not authorized"
rpcMsgid: <unique identifier for this request>
rpcMethod: GetObject
cause:
name: FastServerError
message: "server error: user 'bob' is not authorized"
cause:
name: UnauthorizedError
message: "user 'bob' is not authorized"
rpcUser: "bob"
When the caller uses VError.info()
, the information properties are collapsed
so that it looks like this:
message: "request failed: server error: user 'bob' is not authorized"
rpcMsgid: <unique identifier for this request>
rpcMethod: GetObject
rpcUser: "bob"
Taking this apart:
findCauseByName('FastServerError')
rather than checking the name
field directly.It’s not expected that you’d use these complex forms all the time. Despite supporting the complex case above, you can still just do:
new VError(“my service isn’t working”);
for the simple cases.
The “Demo” section above covers several basic cases. Here’s a more advanced case:
const err1 = new VError('something bad happened');
/* ... */
const err2 = new VError({
'name': 'ConnectionError',
'cause': err1,
'info': {
'errno': 'ECONNREFUSED',
'remote_ip': '127.0.0.1',
'port': 215
}
}, 'failed to connect to "%s:%d"', '127.0.0.1', 215);
console.log(err2.message);
console.log(err2.name);
console.log(VError.info(err2));
console.log(err2.stack);
This outputs:
failed to connect to "127.0.0.1:215": something bad happened
ConnectionError
{ errno: 'ECONNREFUSED', remote_ip: '127.0.0.1', port: 215 }
ConnectionError: failed to connect to "127.0.0.1:215": something bad happened
at Object.<anonymous> (/home/dap/node-verror/examples/info.js:5:12)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:935:3
Information properties are inherited up the cause chain, with values at the top of the chain overriding same-named values lower in the chain. To continue that example:
const err3 = new VError({
'name': 'RequestError',
'cause': err2,
'info': {
'errno': 'EBADREQUEST'
}
}, 'request failed');
console.log(err3.message);
console.log(err3.name);
console.log(VError.info(err3));
console.log(err3.stack);
This outputs:
request failed: failed to connect to "127.0.0.1:215": something bad happened
RequestError
{ errno: 'EBADREQUEST', remote_ip: '127.0.0.1', port: 215 }
RequestError: request failed: failed to connect to "127.0.0.1:215": something bad happened
at Object.<anonymous> (/home/dap/node-verror/examples/info.js:20:12)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:935:3
You can also print the complete stack trace of combined Error
s by using
VError.fullStack(err).
const err1 = new VError('something bad happened');
/* ... */
const err2 = new VError(err1, 'something really bad happened here');
console.log(VError.fullStack(err2));
This outputs:
VError: something really bad happened here: something bad happened
at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:5:12)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)
at Function.Module.runMain (module.js:441:10)
at startup (node.js:139:18)
at node.js:968:3
caused by: VError: something bad happened
at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:3:12)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)
at Function.Module.runMain (module.js:441:10)
at startup (node.js:139:18)
at node.js:968:3
VError.fullStack
is also safe to use on regular Error
s, so feel free to use
it whenever you need to extract the stack trace from an Error
, regardless if
it’s a VError
or not.