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, but it is assumed that you are using the @grpc/grpc-js library.

Installation

yarn add grpc-boom

Install the @grpc/grpc-js library:

yarn add @grpc/grpc-js

Table of Contents

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

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.
• details - optional error details.

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/grpc-js';
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/grpc-js';
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"]}}

From Http Exception

This method attempts to convert an http exception to a grpc boom error, it will fail-over to an unknown grpc error if the error code cannot be inferred. This method supports Boom errors.

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

function example(): GrpcBoom {
  const metadata: Metadata = new Metadata();
  metadata.set('boomified', 'true');
  const httpException = {
    code: 400,
    message: 'Invalid input provided.',
    details: 'Password must be more than 6 characters.',
  };
  return GrpcBoom.fromHttpException(httpException, metadata);
}

Returns a gRPC Boom object with the following properties:

isBoom: true,
code: 3,
error: 'INVALID_ARGUMENT',
message: 'Invalid input provided.',
details: 'Password must be more than 6 characters.',
metadata: {"_internal_repr":{"boomified":["true"]}}

Convenience

See Convenience Methods for a list of available methods.

import { Metadata } from '@grpc/grpc-js';
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/grpc-js';
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.
  • details - optional error details.
  • 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.
  • details - optional error details.
  • 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], [details])

Returns a 1 Cancelled error where:

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

GrpcBoom.cancelled('Operation was cancelled');

Generates the following response payload:

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

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

Returns a 2 Unknown error where:

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

GrpcBoom.unknown('Unknown error');

Generates the following response payload:

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

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

Returns a 3 Invalid Argument error where:

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

GrpcBoom.invalidArgument('Invalid query');

Generates the following response payload:

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

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

Returns a 4 Deadline Exceeded error where:

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

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], [details])

Returns a 5 Not Found error where:

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

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], [details])

Returns a 6 Already Exists error where:

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

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], [details])

Returns a 7 Permission Denied error where:

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

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], [details])

Returns a 8 Resource Exhausted error where:

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

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], [details])

Returns a 9 Failed Precondition error where:

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

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], [details])

Returns a 10 Aborted error where:

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

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

Generates the following response payload:

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

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

Returns a 11 Out of Range error where:

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

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], [details])

Returns a 12 Unimplemented error where:

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

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], [details])

Returns a 13 Internal error where:

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

GrpcBoom.internal('Internal errors');

Generates the following response payload:

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

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

Returns a 14 Unavailable error where:

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

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], [details])

Returns a 15 Data Loss error where:

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

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], [details])

Returns a 16 Unauthenticated error where:

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

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"
}

License

BSD-3 License

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 the main branch. Any other branch (unless specified by the maintainers) will get rejected.
5. Check for existing issues first, before filing a new issue.