grpc-boom

gRPC Boom

A gRPC implementation of the awesome Boom library to help create gRPC-friendly error objects. It supports gRPC Metadata, and can be customised as desired. See Usage examples below for more details.

This library has zero external dependencies.

Installation

npm install grpc-boom --save

Test Coverage

Table of Contents

• Overview
  • Usage
    • gRPC Callback
    • Constructor
    • Boomify
    • Convenience
    • Custom
  • Helper Methods
    • new GrpcBoom(message, [options])
    • boomify(error, [options])
  • Convenience Methods
    • GrpcBoom.cancelled([message], [metadata])
    • GrpcBoom.unknown([message], [metadata])
    • GrpcBoom.invalidArgument([message], [metadata])
    • GrpcBoom.deadlineExceeded([message], [metadata])
    • GrpcBoom.notFound([message], [metadata])
    • GrpcBoom.alreadyExists([message], [metadata])
    • GrpcBoom.permissionDenied([message], [metadata])
    • GrpcBoom.resourceExhausted([message], [metadata])
    • GrpcBoom.failedPrecondition([message], [metadata])
    • GrpcBoom.aborted([message], [metadata])
    • GrpcBoom.outOfRange([message], [metadata])
    • GrpcBoom.unimplemented([message], [metadata])
    • GrpcBoom.internal([message], [metadata])
    • GrpcBoom.unavailable([message], [metadata])
    • GrpcBoom.dataLoss([message], [metadata])
    • GrpcBoom.unauthenticated([message], [metadata])

Overview

gRPC Boom provides a set of utilities for returning gRPC-friendly errors. Each utility returns a GrpcBoom error response object which includes the following properties:

• isBoom - if true, indicates this is a GrpcBoom object instance.
• metadata - an optional gRPC Metadata object.
• code - the gRPC status code.
• error - the gRPC status message (e.g. 'INVALID_ARGUMENTS', 'INTERNAL').
• message - the error message.

Usage

Below are some general usage examples:

gRPC Callback

Can be used as the first argument of a gRPC callback method:

import GrpcBoom from 'grpc-boom';

function sayHelloStrict(call, callback) {
  if (call.request.getName().length > 10) {
    return callback(GrpcBoom.invalidArgument('Length of "Name" cannot be more than 10 characters'), null);
  }
  callback(null, { Result: 'Hey, ' + call.request.getName() + '!' });
}

Generates the following response payload if "Name" is more than 10 characters:

{
  "code": 3,
  "error": "INVALID_ARGUMENT",
  "message": "Length of 'Name' cannot be more than 10 characters"
}

Constructor

See new GrpcBoom(message, [options]) for details.

import { Metadata } from 'grpc';
import GrpcBoom, { Status } from 'grpc-boom';

function example(): GrpcBoom {
  const metadata: Metadata = new Metadata();
  metadata.set('constructed', 'true');
  return new GrpcBoom('Constructor Example!', { 
    code: Status.CANCELLED,
    metadata
  });
}

Returns a gRPC Boom object with the following properties:

isBoom: true
message: Constructor Example!
code: 1
error: CANCELLED
metadata: {"_internal_repr":{"constructed":["true"]}}

Boomify

See boomify(error, [options]) for details.

import { Metadata } from 'grpc';
import GrpcBoom, { Status } from 'grpc-boom';

function example(): GrpcBoom {
  const metadata: Metadata = new Metadata();
  metadata.set('boomified', 'true');
  return GrpcBoom.boomify(new Error('Boomify Example!'), {
    code: Status.UNKNOWN,
    metadata
  });
}

Returns a gRPC Boom object with the following properties:

isBoom: true
message: Boomify Example!
code: 2
error: UNKNOWN
metadata: {"_internal_repr":{"boomified":["true"]}}

Convenience

See Convenience Methods for a list of available methods.

import { Metadata } from 'grpc';
import GrpcBoom from 'grpc-boom';

function example(): GrpcBoom {
  const metadata: Metadata = new Metadata();
  metadata.set('name', 'Cannot be more than 10 characters');
  return GrpcBoom.invalidArgument('Validation failed', metadata);
}

Returns a gRPC Boom object with the following properties:

isBoom: true
message: Validation failed
code: 3
error: INVALID_ARGUMENT
metadata: {"_internal_repr":{"name":["Cannot be more than 10 characters"]}}

Custom

You can also customise the gRPC Boom object:

import { Metadata } from 'grpc';
import GrpcBoom from 'grpc-boom';

function example(): GrpcBoom {
  const metadata: Metadata = new Metadata();
  metadata.set('customised', 'true');
  return GrpcBoom.boomify(new Error('Custom Example!'), {
    code: 200,
    metadata,
    error: 'CUSTOM_EXAMPLE'
  });
}

Returns a gRPC Boom object with the following properties:

isBoom: true
message: Custom Example!
code: 200
error: CUSTOM_EXAMPLE
metadata: {"_internal_repr":{"customised":["true"]}}

Helper Methods

The gRPC Boom object also supports the following helper methods:

new GrpcBoom(message, [options])

Creates a new GrpcBoom object using the provided message and decorates the error with GrpcBoom properties, where:

• message - the error message.
• options - and optional object where:
  • code - the gRPC status code. Defaults to 2 if no status code is set.
  • metadata - an optional gRPC Metadata object.
  • error - the gRPC status message (e.g. 'INVALID_ARGUMENTS', 'INTERNAL').

boomify(error, [options])

Decorates an error with GrpcBoom properties where:

• error - the Error / GrpcBoom object to decorate.
• options - optional object with the following settings:
  • code - the gRPC status code. Defaults to 2 if no status code is already set.
  • message - the error message string
  • metadata - an optional gRPC Metadata object.
  • error - the gRPC status message (e.g. 'INVALID_ARGUMENTS', 'INTERNAL').

const error = new Error('Unexpected input');
GrpcBoom.boomify(error, { code: 3 });

Generates the following response payload:

{
  "code": 3,
  "error": "INVALID_ARGUMENT",
  "message": "Unexpected input"
}

Convenience Methods

Below is a list of convenience methods that can be used to easily generate gRPC errors:

GrpcBoom.cancelled([message], [metadata])

Returns a 1 Cancelled error where:

• message - optional message.
• metadata - optional gRPC Metadata object.

GrpcBoom.cancelled('Operation was cancelled');

Generates the following response payload:

{
  "code": 1,
  "error": "CANCELLED",
  "message": "Operation was cancelled"
}

GrpcBoom.unknown([message], [metadata])

Returns a 2 Unknown error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.unknown('Unknown error');

Generates the following response payload:

{
  "code": 2,
  "error": "UNKNOWN",
  "message": "Unknown error"
}

GrpcBoom.invalidArgument([message], [metadata])

Returns a 3 Invalid Argument error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.invalidArgument('Invalid query');

Generates the following response payload:

{
  "code": 3,
  "error": "INVALID_ARGUMENT",
  "message": "Invalid query"
}

GrpcBoom.deadlineExceeded([message], [metadata])

Returns a 4 Deadline Exceeded error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.deadlineExceeded('Deadline expired before operation could complete');

Generates the following response payload:

{
  "code": 4,
  "error": "DEADLINE_EXCEEDED",
  "message": "Deadline expired before operation could complete"
}

GrpcBoom.notFound([message], [metadata])

Returns a 5 Not Found error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.notFound('Requested entity was not found');

Generates the following response payload:

{
  "code": 5,
  "error": "NOT_FOUND",
  "message": "Requested entity was not found"
}

GrpcBoom.alreadyExists([message], [metadata])

Returns a 6 Already Exists error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.alreadyExists('Requested entity already exists');

Generates the following response payload:

{
  "code": 6,
  "error": "ALREADY_EXISTS",
  "message": "Requested entity already exists"
}

GrpcBoom.permissionDenied([message], [metadata])

Returns a 7 Permission Denied error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.permissionDenied('The caller does not have permission to execute the specified operation');

Generates the following response payload:

{
  "code": 7,
  "error": "PERMISSION_DENIED",
  "message": "The caller does not have permission to execute the specified operation"
}

GrpcBoom.resourceExhausted([message], [metadata])

Returns a 8 Resource Exhausted error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.resourceExhausted('Resource has been exhausted');

Generates the following response payload:

{
  "code": 8,
  "error": "RESOURCE_EXHAUSTED",
  "message": "Resource has been exhausted"
}

GrpcBoom.failedPrecondition([message], [metadata])

Returns a 9 Failed Precondition error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.failedPrecondition(
  'Operation was rejected because the system is not in a state required for the operations execution'
);

Generates the following response payload:

{
  "code": 9,
  "error": "FAILED_PRECONDITION",
  "message": "Operation was rejected because the system is not in a state required for the operations execution"
}

GrpcBoom.aborted([message], [metadata])

Returns a 10 Aborted error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.aborted('The operation was aborted');

Generates the following response payload:

{
  "code": 10,
  "error": "ABORTED",
  "message": "The operation was aborted"
}

GrpcBoom.outOfRange([message], [metadata])

Returns a 11 Out of Range error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.outOfRange('Operation was attempted past the valid range');

Generates the following response payload:

{
  "code": 11,
  "error": "OUT_OF_RANGE",
  "message": "Operation was attempted past the valid range"
}

GrpcBoom.unimplemented([message], [metadata])

Returns a 12 Unimplemented error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.unimplemented('Operation is not implemented or not supported/enabled');

Generates the following response payload:

{
  "code": 12,
  "error": "UNIMPLEMENTED",
  "message": "Operation is not implemented or not supported/enabled"
}

GrpcBoom.internal([message], [metadata])

Returns a 13 Internal error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.internal('Internal errors');

Generates the following response payload:

{
  "code": 13,
  "error": "INTERNAL",
  "message": "Internal errors"
}

GrpcBoom.unavailable([message], [metadata])

Returns a 14 Unavailable error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.unavailable('The service is currently unavailable');

Generates the following response payload:

{
  "code": 14,
  "error": "UNAVAILABLE",
  "message": "The service is currently unavailable"
}

GrpcBoom.dataLoss([message], [metadata])

Returns a 15 Data Loss error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.dataLoss('Unrecoverable data loss or corruption');

Generates the following response payload:

{
  "code": 15,
  "error": "DATA_LOSS",
  "message": "Unrecoverable data loss or corruption"
}

GrpcBoom.unauthenticated([message], [metadata])

Returns a 16 Unauthenticated error where:

• message - optional message.
• metadata - optional gRPC Metadata object

GrpcBoom.unauthenticated(
  'The request does not have valid authentication credentials for the operation'
);

Generates the following response payload:

{
  "code": 16,
  "error": "UNAUTHENTICATED",
  "message": "The request does not have valid authentication credentials for the operation"
}

Contributing

Contributions are encouraged, please see further details below:

Pull Requests

Here are some basic rules to follow to ensure timely addition of your request:

1. Match coding style (braces, spacing, etc.).
2. If it is a feature, bugfix, or anything please only change the minimum amount of code required to satisfy the change.
3. Please keep PR titles easy to read and descriptive of changes, this will make them easier to merge :)
4. Pull requests must be made against develop branch. Any other branch (unless specified by the maintainers) will get rejected.
5. Check for existing issues first, before filing a new issue.

License

BSD-3 License