Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
3f322c4
Rework to be a regular class instance
kanongil Dec 1, 2023
84b81e0
Tighten input types and make cause option explicit
kanongil Dec 4, 2023
4609d8c
Remove decorate option
kanongil Dec 4, 2023
0dcd0aa
Allow to boomify non-Error errors
kanongil Dec 4, 2023
bd7ddd7
Make _apply internal
kanongil Dec 4, 2023
d685e22
Make isBoom a prototype property
kanongil Dec 4, 2023
de34590
Make isServer property computed
kanongil Dec 4, 2023
d5fdc6f
Refactor output and payload to classes
kanongil Dec 5, 2023
c8c2d85
Remove unauthorized payload.attributes
kanongil Dec 5, 2023
c2f4a3f
Fix WWW-Authenticate header when empty attributes
kanongil Dec 5, 2023
447ee21
Refactor implementation to use helpers
kanongil Dec 5, 2023
28fc99a
Add and use a Boom "headers" option
kanongil Dec 5, 2023
204d542
Use statusError for all helpers
kanongil Dec 5, 2023
51862fa
Throw TypeError instead of Hoek assertion
kanongil Dec 5, 2023
3f10016
Remove typeof property
kanongil Dec 5, 2023
f4f0161
Fix legacy boom object support
kanongil Dec 6, 2023
ccc53dc
Add tests for "name" property
kanongil Dec 7, 2023
e780c73
Explicit cause in super() call
kanongil Dec 7, 2023
aa1465a
Assign .cause if not handled by super() call
kanongil Dec 7, 2023
283f635
Fix and update typings
kanongil Dec 7, 2023
4a35028
Clone incoming headers
kanongil Dec 7, 2023
f8cb4d3
Cleanup typings
kanongil Dec 7, 2023
e2efda7
Narrow typings
kanongil Dec 11, 2023
6d8f640
Revert "Remove decorate option"
kanongil Dec 7, 2023
c69e872
Use decorate option internally
kanongil Dec 7, 2023
f5e93af
Allow usage on runtimes with no Error.captureStackTrace()
kanongil Oct 24, 2024
96d92c7
Update docs
kanongil Oct 24, 2024
f0e0f6c
Restore decorate option to typings
kanongil Oct 24, 2024
56795ff
Make reformat() apply to initial payload
kanongil Dec 7, 2023
4135963
Update typescript
kanongil Oct 24, 2024
26fc313
Fix tests on windows filesystem
kanongil Oct 24, 2024
6816b3d
Don't set cause when not in the options
kanongil Oct 26, 2024
1e0c464
Allow isServer to be written to
kanongil Oct 26, 2024
9084371
Fix boomify option typings
kanongil Oct 26, 2024
d8637d6
Improve boomify typings
kanongil Oct 26, 2024
ec14f45
Document headers option
kanongil Oct 26, 2024
7899720
Require data option when Data generic is not unknown
kanongil Oct 30, 2024
71ced42
Remove decorate option
kanongil Oct 30, 2024
9109bdb
Improve boomify data type support
kanongil Oct 31, 2024
e4ba24d
Improve docs
kanongil Oct 31, 2024
e114fbd
Fix notImplemented and more setting Error cause
kanongil Oct 31, 2024
b2102b1
Cleanup
kanongil Oct 31, 2024
46c282c
Ignore all non-object headers option
kanongil Nov 1, 2024
0330283
Shallow copy headers and throw when bad
kanongil Nov 4, 2024
90a9361
Directly require escapeHeaderAttribute
kanongil Nov 4, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 49 additions & 56 deletions API.md
Original file line number Diff line number Diff line change
@@ -1,82 +1,81 @@

**boom** provides a set of utilities for returning HTTP errors. Each utility returns a `Boom`
error response object which includes the following properties:
- `isBoom` - if `true`, indicates this is a `Boom` object instance. Note that this boolean should
only be used if the error is an instance of `Error`. If it is not certain, use `Boom.isBoom()`
instead.
- `isServer` - convenience bool indicating status code >= 500.
- `message` - the error message.
- `typeof` - the constructor used to create the error (e.g. `Boom.badRequest`).
- `output` - the formatted response. Can be directly manipulated after object construction to return a custom
error response. Allowed root keys:
- `statusCode` - the HTTP status code (typically 4xx or 5xx).
- `headers` - an object containing any HTTP headers where each key is a header name and value is the header content.
- `payload` - the formatted object used as the response payload (stringified). Can be directly manipulated but any
changes will be lost
if `reformat()` is called. Any content allowed and by default includes the following content:
- `payload` - the formatted object used as the response payload.
Can be directly manipulated but any changes will be lost if `reformat()` is called.
Any content allowed and by default includes the following content:
- `statusCode` - the HTTP status code, derived from `error.output.statusCode`.
- `error` - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from `statusCode`.
- `message` - the error message derived from `error.message`.
- inherited `Error` properties.
- `stack` - string with stack trace from where error was created.
- optional `cause` - the error cause, as set by constructor.

The `Boom` object also supports the following method:
The object has additional properties from the `Boom` prototype:
- `name` - string with error name. Set to `'Boom'`.
- `isBoom` - set to `true`, indicating this is a `Boom` object instance. Note that this boolean should
only be tested if the error is an instance of `Error`. If it is not certain, use [`Boom.isBoom()`](#isboomerr-statuscode) instead.
- `isServer` - convenience boolean indicating status code >= 500.

The object also supports the following method:

#### `reformat(debug)`

Rebuilds `error.output` using the other object properties where:

- `debug` - a Boolean that, when `true`, causes Internal Server Error messages to be left in tact. Defaults to `false`, meaning that Internal Server Error messages are redacted.

Note that `Boom` object will return `true` when used with `instanceof Boom`, but do not use the
`Boom` prototype (they are either plain `Error` or the error prototype passed in). This means
`Boom` objects should only be tested using `instanceof Boom` or `Boom.isBoom()` but not by looking
at the prototype or contructor information. This limitation is to avoid manipulating the prototype
chain which is very slow.
- `debug` - a Boolean that, when `true`, causes Internal Server Error messages to be left intact.
Defaults to `false`, meaning that Internal Server Error messages are redacted.

#### Helper Methods
#### Base Constructor

##### `new Boom.Boom(message, [options])`
##### `new Boom([message], [options])`

Creates a new `Boom` object using the provided `message` and then calling
[`boomify()`](#boomifyerr-options) to decorate the error with the `Boom` properties, where:
- `message` - the error message. If `message` is an error, it is the same as calling
[`boomify()`](#boomifyerr-options) directly.
Creates a new `Boom` sub-classed `Error` object, where:
- `message` - the error message.
- `options` - and optional object where:
- `statusCode` - the HTTP status code. Defaults to `500` if no status code is already set.
- `data` - additional error information (assigned to `error.data`).
- `decorate` - an option with extra properties to set on the error object.
- `statusCode` - the HTTP status code. Defaults to `500`.
- `cause` - the error that caused the boom error.
- `data` - additional error information, assigned to `this.data`.
- `headers` - an object containing any HTTP headers where each key is a header name and value is the header content.
- `ctor` - constructor reference used to crop the exception call stack output.
- if `message` is an error object, also supports the other [`boomify()`](#boomifyerr-options)
options.

#### Helper Methods

##### `boomify(err, [options])`

Decorates an error with the `Boom` properties where:
- `err` - the `Error` object to decorate.
Creates a `Boom` object similar to [`new Boom()`](#new-boommessage-options), except it
applies the `options` to the existing error when it is a `Boom` object, where:
- `err` - the object to boomify, set as `cause` when `err` is not a `Boom` object.
- `options` - optional object with the following optional settings:
- `statusCode` - the HTTP status code. Defaults to `500` if no status code is already set and `err` is not a `Boom` object.
- `message` - error message string. If the error already has a message, the provided `message` is added as a prefix.
Defaults to no message.
- `decorate` - an option with extra properties to set on the error object.
- `override` - if `false`, the `err` provided is a `Boom` object, and a `statusCode` or `message` are provided,
the values are ignored. Defaults to `true` (apply the provided `statusCode` and `message` options to the error
regardless of its type, `Error` or `Boom` object).
regardless of its type).
- it returns a `Boom` object with the boomified error

Note that [`new Boom()`](#new-boommessage-options) should generally be preferred in cases where the error can come from awaited logic, or has been passed around.

```js
var error = new Error('Unexpected input');
Boom.boomify(error, { statusCode: 400 });
const error = new Error('Unexpected input');
const boomified = Boom.boomify(error, { statusCode: 400 });
```

##### `isBoom(err, [statusCode])`

Identifies whether an error is a `Boom` object. Same as calling `instanceof Boom.Boom`.
Identifies whether an error is a `Boom` object. Same as calling `err instanceof Boom.Boom`.
- `err` - Error object.
- `statusCode` - optional status code.

```js
Boom.isBoom(Boom.badRequest()); // true
Boom.isBoom(Boom.badRequest(), 400); // true
```

#### HTTP 4xx Errors

##### `Boom.badRequest([message], [data])`
Expand Down Expand Up @@ -108,7 +107,8 @@ Returns a 401 Unauthorized error where:
- an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
- `attributes` - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used
when `scheme` is a string, otherwise it is ignored. Every key/value pair will be included in the
'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the `attributes` key. Alternatively value can be a string which is use to set the value of the scheme, for example setting the token value for negotiate header. If string is used message parameter must be null.
'WWW-Authenticate' in the format of 'key="value"'. Alternatively value can be a string which is used to set the
value of the scheme, for example setting the token value for negotiate header. If string is used message parameter must be null.
`null` and `undefined` will be replaced with an empty string. If `attributes` is set, `message` will be used as
the 'error' segment of the 'WWW-Authenticate' header. If `message` is unset, the 'error' segment of the header
will not be present and `isMissing` will be true on the error object.
Expand Down Expand Up @@ -141,10 +141,7 @@ Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"message": "invalid password",
"attributes": {
"error": "invalid password"
}
"message": "invalid password"
},
"headers": {
"WWW-Authenticate": "sample error=\"invalid password\""
Expand All @@ -160,8 +157,7 @@ Generates the following response:
```json
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"attributes": "VGhpcyBpcyBhIHRlc3QgdG9rZW4="
"error": "Unauthorized"
},
"headers": {
"WWW-Authenticate": "Negotiate VGhpcyBpcyBhIHRlc3QgdG9rZW4="
Expand All @@ -178,13 +174,7 @@ Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"message": "invalid password",
"attributes": {
"error": "invalid password",
"ttl": 0,
"cache": "",
"foo": "bar"
}
"message": "invalid password"
},
"headers": {
"WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""
Expand Down Expand Up @@ -678,7 +668,7 @@ All 500 errors hide your message from the end user.

Returns a 500 Internal Server Error error where:
- `message` - optional message.
- `data` - optional additional error data.
- `data` - optional additional error data. Used as `cause` when when an `Error`.

```js
Boom.badImplementation('terrible implementation');
Expand All @@ -698,7 +688,7 @@ Generates the following response payload:

Returns a 501 Not Implemented error where:
- `message` - optional message.
- `data` - optional additional error data.
- `data` - optional additional error data. Used as `cause` when when an `Error`.

```js
Boom.notImplemented('method not implemented');
Expand All @@ -718,7 +708,7 @@ Generates the following response payload:

Returns a 502 Bad Gateway error where:
- `message` - optional message.
- `data` - optional additional error data.
- `data` - optional additional error data. Used as `cause` when when an `Error`.

```js
Boom.badGateway('that is a bad gateway');
Expand All @@ -738,7 +728,7 @@ Generates the following response payload:

Returns a 503 Service Unavailable error where:
- `message` - optional message.
- `data` - optional additional error data.
- `data` - optional additional error data. Used as `cause` when when an `Error`.

```js
Boom.serverUnavailable('unavailable');
Expand All @@ -758,7 +748,7 @@ Generates the following response payload:

Returns a 504 Gateway Time-out error where:
- `message` - optional message.
- `data` - optional additional error data.
- `data` - optional additional error data. Used as `cause` when when an `Error`.

```js
Boom.gatewayTimeout();
Expand All @@ -777,4 +767,7 @@ Generates the following response payload:

**Q** How do I include extra information in my responses? `output.payload` is missing `data`, what gives?

**A** There is a reason the values passed back in the response payloads are pretty locked down. It's mostly for security and to not leak any important information back to the client. This means you will need to put in a little more effort to include extra information about your custom error. Check out the ["Error transformation"](https://github.com/hapijs/hapi/blob/master/API.md#error-transformation) section in the hapi documentation.
**A** There is a reason the values passed back in the response payloads are pretty locked down.
It's mostly for security and to not leak any important information back to the client.
This means you will need to put in a little more effort to include extra information about your custom error.
Check out the ["Error transformation"](https://github.com/hapijs/hapi/blob/master/API.md#error-transformation) section in the hapi documentation.
Loading