Documentation

Namespace: grpc

grpc

Classes

Channel
Client
Metadata
Server
ServerCredentials
Call
ClientDuplexStream
ClientReadableStream
ClientUnaryCall
ClientWritableStream
ServerDuplexStream
ServerReadableStream
ServerUnaryCall
ServerWritableStream

Namespaces

credentials

Members

<static, constant> callError :number

Call error constants. Call errors almost always indicate bugs in the gRPC library, and these error codes are mainly useful for finding those bugs.

Type:
  • number
Properties:
Name Type Default Description
OK number 0
ERROR number 1
NOT_ON_SERVER number 2
NOT_ON_CLIENT number 3
ALREADY_INVOKED number 5
NOT_INVOKED number 6
ALREADY_FINISHED number 7
TOO_MANY_OPERATIONS number 8
INVALID_FLAGS number 9
INVALID_METADATA number 10
INVALID_MESSAGE number 11
NOT_SERVER_COMPLETION_QUEUE number 12
BATCH_TOO_BIG number 13
PAYLOAD_TYPE_MISMATCH number 14

<static, readonly> connectivityState :number

Connectivity state values

Type:
  • number
Properties:
Name Type Default Description
IDLE number 0
CONNECTING number 1
READY number 2
TRANSIENT_FAILURE number 3
SHUTDOWN number 4

<static> load

Load a gRPC object from a .proto file.

Deprecated:

<static, readonly> logVerbosity :number

Type:
  • number
Properties:
Name Type Default Description
DEBUG number 0
INFO number 1
ERROR number 2

<static, readonly> methodTypes :number

Method types: the supported RPC types

Type:
  • number
Properties:
Name Type Default Description
UNARY number 0
CLIENT_STREAMING number 1
SERVER_STREAMING number 2
BIDI_STREAMING number 3

<static> propagate :number

Propagation flags: these can be bitwise or-ed to form the propagation option for calls.

Users are encouraged to write propagation masks as deltas from the default. i.e. write grpc.propagate.DEFAULTS & ~grpc.propagate.DEADLINE to disable deadline propagation.

Type:
  • number
Properties:
Name Type Default Description
DEADLINE number 1
CENSUS_STATS_CONTEXT number 2
CENSUS_TRACING_CONTEXT number 4
CANCELLATION number 8
DEFAULTS number 65535

<static, readonly> status :number

Enum of status codes that gRPC can return

Type:
  • number
Properties:
Name Type Default Description
OK number 0

Not an error; returned on success
CANCELLED number 1

The operation was cancelled (typically by the caller).
UNKNOWN number 2

Unknown error. An example of where this error may be returned is if a status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT number 3

Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED number 4

Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.
NOT_FOUND number 5

Some requested entity (e.g., file or directory) was not found.
ALREADY_EXISTS number 6

Some entity that we attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED number 7

The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors).
RESOURCE_EXHAUSTED number 8

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION number 9

Operation was rejected because the system is not in a state required for the operation's execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.

A litmus test that may help a service implementor in deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:

  • Use UNAVAILABLE if the client can retry just the failing call.
  • Use ABORTED if the client should retry at a higher-level (e.g., restarting a read-modify-write sequence).
  • Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless they have first fixed up the directory by deleting files from it.
  • Use FAILED_PRECONDITION if the client performs conditional REST Get/Update/Delete on a resource and the resource on the server does not match the condition. E.g., conflicting read-modify-write on the same resource.
ABORTED number 10

The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.

See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE number 11

Operation was attempted past the valid range. E.g., seeking or reading past end of file.

Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size.

There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED number 12

Operation is not implemented or not supported/enabled in this service.
INTERNAL number 13

Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.
UNAVAILABLE number 14

The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.

See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
DATA_LOSS number 15

Unrecoverable data loss or corruption.
UNAUTHENTICATED number 16

The request does not have valid authentication credentials for the operation.

<static, readonly> writeFlags :number

Write flags: these can be bitwise or-ed to form write options that modify how data is written.

Type:
  • number
Properties:
Name Type Default Description
BUFFER_HINT number 1

Hint that the write may be buffered and need not go out on the wire immediately. GRPC is free to buffer the message until the next non-buffered write, or until writes_done, but it need not buffer completely or at all.
NO_COMPRESS number 2

Force compression to be disabled for a particular write

<inner> defaultLoadOptions

Default options for loading proto files into gRPC

Methods

<static> closeClient(client_obj)

Parameters:
Name Type Description
client_obj grpc.Client

The client to close

<static> loadObject(value [, options])

Load a ProtoBuf.js object as a gRPC object.

Parameters:
Name Type Argument Description
value Object

The ProtoBuf.js reflection object to load
options Object <optional>

Options to apply to the loaded file

Properties
Name Type Argument Default Description
binaryAsBase64 bool <optional>
 false

deserialize bytes values as base64 strings instead of Buffers
longsAsStrings bool <optional>
 true

deserialize long values as strings instead of objects
enumsAsStrings bool <optional>
 true

deserialize enum values as strings instead of numbers. Only works with Protobuf.js 6 values.
deprecatedArgumentOrder bool <optional>
 false

use the beta method argument order for client methods, with optional arguments after the callback. This option is only a temporary stopgap measure to smooth an API breakage. It is deprecated, and new code should not use it.
protobufjsVersion number | string <optional>
 'detect'

5 and 6 respectively indicate that an object from the corresponding version of Protobuf.js is provided in the value argument. If the option is 'detect', gRPC will guess what the version is based on the structure of the value.
Returns:

The resulting gRPC object.

Type
Object.<string, *>

<static> setLogger(logger)

Sets the logger function for the gRPC module. For debugging purposes, the C core will log synchronously directly to stdout unless this function is called. Note: the output format here is intended to be informational, and is not guaranteed to stay the same in the future. Logs will be directed to logger.error.

Parameters:
Name Type Description
logger Console

A Console-like object.

<static> setLogVerbosity(verbosity)

Sets the logger verbosity for gRPC module logging. The options are members of the grpc.logVerbosity map.

Parameters:
Name Type Description
verbosity Number

The minimum severity to log

<inner> getClientChannel(client)

Return the underlying channel object for the specified client

Parameters:
Name Type Description
client grpc.Client

The client
See:
Returns:

The channel

Type
Channel

<inner> makeGenericClientConstructor(methods, serviceName, class_options)

Creates a constructor for a client with the given methods, as specified in the methods argument. The resulting class will have an instance method for each method in the service, which is a partial application of one of the Client request methods, depending on requestSerialize and responseSerialize, with the method, serialize, and deserialize arguments predefined.

Parameters:
Name Type Description
methods grpc~ServiceDefinition

An object mapping method names to method attributes
serviceName string

The fully qualified name of the service
class_options Object

An options object.

Properties
Name Type Argument Default Description
deprecatedArgumentOrder boolean <optional>
 false

Indicates that the old argument order should be used for methods, with optional arguments at the end instead of the callback at the end. This option is only a temporary stopgap measure to smooth an API breakage. It is deprecated, and new code should not use it.
Returns:

New client constructor, which is a subclass of grpc.Client, and has the same arguments as that constructor.

Type
function

<inner> waitForClientReady(client, deadline, callback)

Wait for the client to be ready. The callback will be called when the client has successfully connected to the server, and it will be called with an error if the attempt to connect to the server has unrecoverablly failed or if the deadline expires. This function will make the channel start connecting if it has not already done so.

Parameters:
Name Type Description
client grpc.Client

The client to wait on
deadline grpc~Deadline

When to stop waiting for a connection. Pass Infinity to wait forever.
callback function

The callback to call when done attempting to connect.
See:

Type Definitions

ChannelOptions

Type:
  • Object.<string, (string|number)>

CoreMetadata

Metadata representation as passed to and the native addon

Type:
  • object

Deadline

The deadline of an operation. If it is a date, the deadline is reached at the date and time specified. If it is a finite number, it is treated as a number of milliseconds since the Unix Epoch. If it is Infinity, the deadline will never be reached. If it is -Infinity, the deadline has already passed.

Type:
  • number | Date

deserialize(data)

A deserialization function

Parameters:
Name Type Description
data Buffer

The byte sequence to deserialize
Returns:

The data deserialized as a value

Type
*

Listener

A set of interceptor functions triggered by responses

Type:
  • object
Properties:
Name Type Argument Description
onReceiveMetadata MetadataListener <optional>

A function triggered by response metadata.
onReceiveMessage MessageListener <optional>

A function triggered by a response message.
onReceiveStatus StatusListener <optional>

A function triggered by a response status.

MethodDefinition

An object that completely defines a service method signature.

Type:
  • Object
Properties:
Name Type Description
path string

The method's URL path
requestStream boolean

Indicates whether the method accepts a stream of requests
responseStream boolean

Indicates whether the method returns a stream of responses
requestSerialize grpc~serialize

Serialization function for request values
responseSerialize grpc~serialize

Serialization function for response values
requestDeserialize grpc~deserialize

Deserialization function for request data
responseDeserialize grpc~deserialize

Deserialization function for repsonse data

PackageDefinition

An object that defines a package hierarchy with multiple services

Type:

ProtobufTypeDefinition

An object that defines a protobuf type

Type:
  • object

Requester

Type:
  • object

serialize(value)

A serialization function

Parameters:
Name Type Description
value *

The value to serialize
Returns:

The value serialized as a byte sequence

Type
Buffer

ServiceDefinition

An object that completely defines a service.

Type:

ServiceError

Describes how a request has failed. The member message will be the same as details in grpc~StatusObject, and code and metadata are the same as in that object.

Type:
  • Error
Properties:
Name Type Description
code number

The error code, a key of grpc.status that is not grpc.status.OK
metadata grpc.Metadata

Trailing metadata sent with the status, if applicable

StatusObject

Represents the status of a completed request. If code is grpc.status.OK, then the request has completed successfully. Otherwise, the request has failed, details will contain a description of the error. Either way, metadata contains the trailing response metadata sent by the server when it finishes processing the call.

Type:
  • object
Properties:
Name Type Description
code number

The error code, a key of grpc.status
details string

Human-readable description of the status
metadata grpc.Metadata

Trailing metadata sent with the status, if applicable