www.aleph1.co.uk Git - yaffs-website/blob - node_modules/boom/README.md

   1 ![boom Logo](https://raw.github.com/hapijs/boom/master/images/boom.png)
   2
   3 HTTP-friendly error objects
   4
   5 [![Build Status](https://secure.travis-ci.org/hapijs/boom.png)](http://travis-ci.org/hapijs/boom)
   6 [![Current Version](https://img.shields.io/npm/v/boom.svg)](https://www.npmjs.com/package/boom)
   7
   8 Lead Maintainer: [Adam Bretz](https://github.com/arb)
   9
  10 **boom** provides a set of utilities for returning HTTP errors. Each utility returns a `Boom` error response
  11 object (instance of `Error`) which includes the following properties:
  12 - `isBoom` - if `true`, indicates this is a `Boom` object instance.
  13 - `isServer` - convenience bool indicating status code >= 500.
  14 - `message` - the error message.
  15 - `output` - the formatted response. Can be directly manipulated after object construction to return a custom
  16   error response. Allowed root keys:
  17     - `statusCode` - the HTTP status code (typically 4xx or 5xx).
  18     - `headers` - an object containing any HTTP headers where each key is a header name and value is the header content.
  19     - `payload` - the formatted object used as the response payload (stringified). Can be directly manipulated but any
  20       changes will be lost
  21       if `reformat()` is called. Any content allowed and by default includes the following content:
  22         - `statusCode` - the HTTP status code, derived from `error.output.statusCode`.
  23         - `error` - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from `statusCode`.
  24         - `message` - the error message derived from `error.message`.
  25 - inherited `Error` properties.
  26
  27 The `Boom` object also supports the following method:
  28 - `reformat()` - rebuilds `error.output` using the other object properties.
  29
  30 ## Overview
  31
  32 - Helper methods
  33   - [`wrap(error, [statusCode], [message])`](#wraperror-statuscode-message)
  34   - [`create(statusCode, [message], [data])`](#createstatuscode-message-data)
  35 - HTTP 4xx Errors
  36   - 400: [`Boom.badRequest([message], [data])`](#boombadrequestmessage-data)
  37   - 401: [`Boom.unauthorized([message], [scheme], [attributes])`](#boomunauthorizedmessage-scheme-attributes)
  38   - 403: [`Boom.forbidden([message], [data])`](#boomforbiddenmessage-data)
  39   - 404: [`Boom.notFound([message], [data])`](#boomnotfoundmessage-data)
  40   - 405: [`Boom.methodNotAllowed([message], [data])`](#boommethodnotallowedmessage-data)
  41   - 406: [`Boom.notAcceptable([message], [data])`](#boomnotacceptablemessage-data)
  42   - 407: [`Boom.proxyAuthRequired([message], [data])`](#boomproxyauthrequiredmessage-data)
  43   - 408: [`Boom.clientTimeout([message], [data])`](#boomclienttimeoutmessage-data)
  44   - 409: [`Boom.conflict([message], [data])`](#boomconflictmessage-data)
  45   - 410: [`Boom.resourceGone([message], [data])`](#boomresourcegonemessage-data)
  46   - 411: [`Boom.lengthRequired([message], [data])`](#boomlengthrequiredmessage-data)
  47   - 412: [`Boom.preconditionFailed([message], [data])`](#boompreconditionfailedmessage-data)
  48   - 413: [`Boom.entityTooLarge([message], [data])`](#boomentitytoolargemessage-data)
  49   - 414: [`Boom.uriTooLong([message], [data])`](#boomuritoolongmessage-data)
  50   - 415: [`Boom.unsupportedMediaType([message], [data])`](#boomunsupportedmediatypemessage-data)
  51   - 416: [`Boom.rangeNotSatisfiable([message], [data])`](#boomrangenotsatisfiablemessage-data)
  52   - 417: [`Boom.expectationFailed([message], [data])`](#boomexpectationfailedmessage-data)
  53   - 422: [`Boom.badData([message], [data])`](#boombaddatamessage-data)
  54   - 428: [`Boom.preconditionRequired([message], [data])`](#boompreconditionrequiredmessage-data)
  55   - 429: [`Boom.tooManyRequests([message], [data])`](#boomtoomanyrequestsmessage-data)
  56 - HTTP 5xx Errors
  57   - 500: [`Boom.badImplementation([message], [data])`](#boombadimplementationmessage-data)
  58   - 501: [`Boom.notImplemented([message], [data])`](#boomnotimplementedmessage-data)
  59   - 502: [`Boom.badGateway([message], [data])`](#boombadgatewaymessage-data)
  60   - 503: [`Boom.serverTimeout([message], [data])`](#boomservertimeoutmessage-data)
  61   - 504: [`Boom.gatewayTimeout([message], [data])`](#boomgatewaytimeoutmessage-data)
  62 - [FAQ](#faq)
  63
  64
  65 ## Helper Methods
  66
  67 ### `wrap(error, [statusCode], [message])`
  68
  69 Decorates an error with the **boom** properties where:
  70 - `error` - the error object to wrap. If `error` is already a **boom** object, returns back the same object.
  71 - `statusCode` - optional HTTP status code. Defaults to `500`.
  72 - `message` - optional message string. If the error already has a message, it adds the message as a prefix.
  73   Defaults to no message.
  74
  75 ```js
  76 var error = new Error('Unexpected input');
  77 Boom.wrap(error, 400);
  78 ```
  79
  80 ### `create(statusCode, [message], [data])`
  81
  82 Generates an `Error` object with the **boom** decorations where:
  83 - `statusCode` - an HTTP error code number. Must be greater or equal 400.
  84 - `message` - optional message string.
  85 - `data` - additional error data set to `error.data` property.
  86
  87 ```js
  88 var error = Boom.create(400, 'Bad request', { timestamp: Date.now() });
  89 ```
  90
  91 ## HTTP 4xx Errors
  92
  93 ### `Boom.badRequest([message], [data])`
  94
  95 Returns a 400 Bad Request error where:
  96 - `message` - optional message.
  97 - `data` - optional additional error data.
  98
  99 ```js
 100 Boom.badRequest('invalid query');
 101 ```
 102
 103 Generates the following response payload:
 104
 105 ```json
 106 {
 107     "statusCode": 400,
 108     "error": "Bad Request",
 109     "message": "invalid query"
 110 }
 111 ```
 112
 113 ### `Boom.unauthorized([message], [scheme], [attributes])`
 114
 115 Returns a 401 Unauthorized error where:
 116 - `message` - optional message.
 117 - `scheme` can be one of the following:
 118   - an authentication scheme name
 119   - an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
 120 - `attributes` - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used
 121   when `schema` is a string, otherwise it is ignored. Every key/value pair will be included in the
 122   'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the `attributes` key.
 123   `null` and `undefined` will be replaced with an empty string. If `attributes` is set, `message` will be used as
 124   the 'error' segment of the 'WWW-Authenticate' header. If `message` is unset, the 'error' segment of the header
 125   will not be present and `isMissing` will be true on the error object.
 126
 127 If either `scheme` or `attributes` are set, the resultant `Boom` object will have the 'WWW-Authenticate' header set for the response.
 128
 129 ```js
 130 Boom.unauthorized('invalid password');
 131 ```
 132
 133 Generates the following response:
 134
 135 ```json
 136 "payload": {
 137     "statusCode": 401,
 138     "error": "Unauthorized",
 139     "message": "invalid password"
 140 },
 141 "headers" {}
 142 ```
 143
 144 ```js
 145 Boom.unauthorized('invalid password', 'sample');
 146 ```
 147
 148 Generates the following response:
 149
 150 ```json
 151 "payload": {
 152     "statusCode": 401,
 153     "error": "Unauthorized",
 154     "message": "invalid password",
 155     "attributes": {
 156         "error": "invalid password"
 157     }
 158 },
 159 "headers" {
 160   "WWW-Authenticate": "sample error=\"invalid password\""
 161 }
 162 ```
 163
 164 ```js
 165 Boom.unauthorized('invalid password', 'sample', { ttl: 0, cache: null, foo: 'bar' });
 166 ```
 167
 168 Generates the following response:
 169
 170 ```json
 171 "payload": {
 172     "statusCode": 401,
 173     "error": "Unauthorized",
 174     "message": "invalid password",
 175     "attributes": {
 176         "error": "invalid password",
 177         "ttl": 0,
 178         "cache": "",
 179         "foo": "bar"
 180     }
 181 },
 182 "headers" {
 183   "WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""
 184 }
 185 ```
 186
 187 ### `Boom.forbidden([message], [data])`
 188
 189 Returns a 403 Forbidden error where:
 190 - `message` - optional message.
 191 - `data` - optional additional error data.
 192
 193 ```js
 194 Boom.forbidden('try again some time');
 195 ```
 196
 197 Generates the following response payload:
 198
 199 ```json
 200 {
 201     "statusCode": 403,
 202     "error": "Forbidden",
 203     "message": "try again some time"
 204 }
 205 ```
 206
 207 ### `Boom.notFound([message], [data])`
 208
 209 Returns a 404 Not Found error where:
 210 - `message` - optional message.
 211 - `data` - optional additional error data.
 212
 213 ```js
 214 Boom.notFound('missing');
 215 ```
 216
 217 Generates the following response payload:
 218
 219 ```json
 220 {
 221     "statusCode": 404,
 222     "error": "Not Found",
 223     "message": "missing"
 224 }
 225 ```
 226
 227 ### `Boom.methodNotAllowed([message], [data])`
 228
 229 Returns a 405 Method Not Allowed error where:
 230 - `message` - optional message.
 231 - `data` - optional additional error data.
 232
 233 ```js
 234 Boom.methodNotAllowed('that method is not allowed');
 235 ```
 236
 237 Generates the following response payload:
 238
 239 ```json
 240 {
 241     "statusCode": 405,
 242     "error": "Method Not Allowed",
 243     "message": "that method is not allowed"
 244 }
 245 ```
 246
 247 ### `Boom.notAcceptable([message], [data])`
 248
 249 Returns a 406 Not Acceptable error where:
 250 - `message` - optional message.
 251 - `data` - optional additional error data.
 252
 253 ```js
 254 Boom.notAcceptable('unacceptable');
 255 ```
 256
 257 Generates the following response payload:
 258
 259 ```json
 260 {
 261     "statusCode": 406,
 262     "error": "Not Acceptable",
 263     "message": "unacceptable"
 264 }
 265 ```
 266
 267 ### `Boom.proxyAuthRequired([message], [data])`
 268
 269 Returns a 407 Proxy Authentication Required error where:
 270 - `message` - optional message.
 271 - `data` - optional additional error data.
 272
 273 ```js
 274 Boom.proxyAuthRequired('auth missing');
 275 ```
 276
 277 Generates the following response payload:
 278
 279 ```json
 280 {
 281     "statusCode": 407,
 282     "error": "Proxy Authentication Required",
 283     "message": "auth missing"
 284 }
 285 ```
 286
 287 ### `Boom.clientTimeout([message], [data])`
 288
 289 Returns a 408 Request Time-out error where:
 290 - `message` - optional message.
 291 - `data` - optional additional error data.
 292
 293 ```js
 294 Boom.clientTimeout('timed out');
 295 ```
 296
 297 Generates the following response payload:
 298
 299 ```json
 300 {
 301     "statusCode": 408,
 302     "error": "Request Time-out",
 303     "message": "timed out"
 304 }
 305 ```
 306
 307 ### `Boom.conflict([message], [data])`
 308
 309 Returns a 409 Conflict error where:
 310 - `message` - optional message.
 311 - `data` - optional additional error data.
 312
 313 ```js
 314 Boom.conflict('there was a conflict');
 315 ```
 316
 317 Generates the following response payload:
 318
 319 ```json
 320 {
 321     "statusCode": 409,
 322     "error": "Conflict",
 323     "message": "there was a conflict"
 324 }
 325 ```
 326
 327 ### `Boom.resourceGone([message], [data])`
 328
 329 Returns a 410 Gone error where:
 330 - `message` - optional message.
 331 - `data` - optional additional error data.
 332
 333 ```js
 334 Boom.resourceGone('it is gone');
 335 ```
 336
 337 Generates the following response payload:
 338
 339 ```json
 340 {
 341     "statusCode": 410,
 342     "error": "Gone",
 343     "message": "it is gone"
 344 }
 345 ```
 346
 347 ### `Boom.lengthRequired([message], [data])`
 348
 349 Returns a 411 Length Required error where:
 350 - `message` - optional message.
 351 - `data` - optional additional error data.
 352
 353 ```js
 354 Boom.lengthRequired('length needed');
 355 ```
 356
 357 Generates the following response payload:
 358
 359 ```json
 360 {
 361     "statusCode": 411,
 362     "error": "Length Required",
 363     "message": "length needed"
 364 }
 365 ```
 366
 367 ### `Boom.preconditionFailed([message], [data])`
 368
 369 Returns a 412 Precondition Failed error where:
 370 - `message` - optional message.
 371 - `data` - optional additional error data.
 372
 373 ```js
 374 Boom.preconditionFailed();
 375 ```
 376
 377 Generates the following response payload:
 378
 379 ```json
 380 {
 381     "statusCode": 412,
 382     "error": "Precondition Failed"
 383 }
 384 ```
 385
 386 ### `Boom.entityTooLarge([message], [data])`
 387
 388 Returns a 413 Request Entity Too Large error where:
 389 - `message` - optional message.
 390 - `data` - optional additional error data.
 391
 392 ```js
 393 Boom.entityTooLarge('too big');
 394 ```
 395
 396 Generates the following response payload:
 397
 398 ```json
 399 {
 400     "statusCode": 413,
 401     "error": "Request Entity Too Large",
 402     "message": "too big"
 403 }
 404 ```
 405
 406 ### `Boom.uriTooLong([message], [data])`
 407
 408 Returns a 414 Request-URI Too Large error where:
 409 - `message` - optional message.
 410 - `data` - optional additional error data.
 411
 412 ```js
 413 Boom.uriTooLong('uri is too long');
 414 ```
 415
 416 Generates the following response payload:
 417
 418 ```json
 419 {
 420     "statusCode": 414,
 421     "error": "Request-URI Too Large",
 422     "message": "uri is too long"
 423 }
 424 ```
 425
 426 ### `Boom.unsupportedMediaType([message], [data])`
 427
 428 Returns a 415 Unsupported Media Type error where:
 429 - `message` - optional message.
 430 - `data` - optional additional error data.
 431
 432 ```js
 433 Boom.unsupportedMediaType('that media is not supported');
 434 ```
 435
 436 Generates the following response payload:
 437
 438 ```json
 439 {
 440     "statusCode": 415,
 441     "error": "Unsupported Media Type",
 442     "message": "that media is not supported"
 443 }
 444 ```
 445
 446 ### `Boom.rangeNotSatisfiable([message], [data])`
 447
 448 Returns a 416 Requested Range Not Satisfiable error where:
 449 - `message` - optional message.
 450 - `data` - optional additional error data.
 451
 452 ```js
 453 Boom.rangeNotSatisfiable();
 454 ```
 455
 456 Generates the following response payload:
 457
 458 ```json
 459 {
 460     "statusCode": 416,
 461     "error": "Requested Range Not Satisfiable"
 462 }
 463 ```
 464
 465 ### `Boom.expectationFailed([message], [data])`
 466
 467 Returns a 417 Expectation Failed error where:
 468 - `message` - optional message.
 469 - `data` - optional additional error data.
 470
 471 ```js
 472 Boom.expectationFailed('expected this to work');
 473 ```
 474
 475 Generates the following response payload:
 476
 477 ```json
 478 {
 479     "statusCode": 417,
 480     "error": "Expectation Failed",
 481     "message": "expected this to work"
 482 }
 483 ```
 484
 485 ### `Boom.badData([message], [data])`
 486
 487 Returns a 422 Unprocessable Entity error where:
 488 - `message` - optional message.
 489 - `data` - optional additional error data.
 490
 491 ```js
 492 Boom.badData('your data is bad and you should feel bad');
 493 ```
 494
 495 Generates the following response payload:
 496
 497 ```json
 498 {
 499     "statusCode": 422,
 500     "error": "Unprocessable Entity",
 501     "message": "your data is bad and you should feel bad"
 502 }
 503 ```
 504
 505 ### `Boom.preconditionRequired([message], [data])`
 506
 507 Returns a 428 Precondition Required error where:
 508 - `message` - optional message.
 509 - `data` - optional additional error data.
 510
 511 ```js
 512 Boom.preconditionRequired('you must supply an If-Match header');
 513 ```
 514
 515 Generates the following response payload:
 516
 517 ```json
 518 {
 519     "statusCode": 428,
 520     "error": "Precondition Required",
 521     "message": "you must supply an If-Match header"
 522 }
 523 ```
 524
 525 ### `Boom.tooManyRequests([message], [data])`
 526
 527 Returns a 429 Too Many Requests error where:
 528 - `message` - optional message.
 529 - `data` - optional additional error data.
 530
 531 ```js
 532 Boom.tooManyRequests('you have exceeded your request limit');
 533 ```
 534
 535 Generates the following response payload:
 536
 537 ```json
 538 {
 539     "statusCode": 429,
 540     "error": "Too Many Requests",
 541     "message": "you have exceeded your request limit"
 542 }
 543 ```
 544
 545 ## HTTP 5xx Errors
 546
 547 All 500 errors hide your message from the end user. Your message is recorded in the server log.
 548
 549 ### `Boom.badImplementation([message], [data])`
 550
 551 Returns a 500 Internal Server Error error where:
 552 - `message` - optional message.
 553 - `data` - optional additional error data.
 554
 555 ```js
 556 Boom.badImplementation('terrible implementation');
 557 ```
 558
 559 Generates the following response payload:
 560
 561 ```json
 562 {
 563     "statusCode": 500,
 564     "error": "Internal Server Error",
 565     "message": "An internal server error occurred"
 566 }
 567 ```
 568
 569 ### `Boom.notImplemented([message], [data])`
 570
 571 Returns a 501 Not Implemented error where:
 572 - `message` - optional message.
 573 - `data` - optional additional error data.
 574
 575 ```js
 576 Boom.notImplemented('method not implemented');
 577 ```
 578
 579 Generates the following response payload:
 580
 581 ```json
 582 {
 583     "statusCode": 501,
 584     "error": "Not Implemented",
 585     "message": "method not implemented"
 586 }
 587 ```
 588
 589 ### `Boom.badGateway([message], [data])`
 590
 591 Returns a 502 Bad Gateway error where:
 592 - `message` - optional message.
 593 - `data` - optional additional error data.
 594
 595 ```js
 596 Boom.badGateway('that is a bad gateway');
 597 ```
 598
 599 Generates the following response payload:
 600
 601 ```json
 602 {
 603     "statusCode": 502,
 604     "error": "Bad Gateway",
 605     "message": "that is a bad gateway"
 606 }
 607 ```
 608
 609 ### `Boom.serverTimeout([message], [data])`
 610
 611 Returns a 503 Service Unavailable error where:
 612 - `message` - optional message.
 613 - `data` - optional additional error data.
 614
 615 ```js
 616 Boom.serverTimeout('unavailable');
 617 ```
 618
 619 Generates the following response payload:
 620
 621 ```json
 622 {
 623     "statusCode": 503,
 624     "error": "Service Unavailable",
 625     "message": "unavailable"
 626 }
 627 ```
 628
 629 ### `Boom.gatewayTimeout([message], [data])`
 630
 631 Returns a 504 Gateway Time-out error where:
 632 - `message` - optional message.
 633 - `data` - optional additional error data.
 634
 635 ```js
 636 Boom.gatewayTimeout();
 637 ```
 638
 639 Generates the following response payload:
 640
 641 ```json
 642 {
 643     "statusCode": 504,
 644     "error": "Gateway Time-out"
 645 }
 646 ```
 647
 648 ## F.A.Q.
 649
 650 ###### How do I include extra information in my responses? `output.payload` is missing `data`, what gives?
 651
 652 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.