Config

gRPCity exposes two configuration objects that match the two layers it talks to:

loadOptions — how the .proto files are parsed and decoded. Passed to loader.init().
channelOptions — how the underlying gRPC channel behaves on the wire. Passed to initClients() and initServer().

Both are passthroughs: gRPCity ships sensible defaults and merges your overrides on top.

Default Options


import { defaultLoadOptions, defaultChannelOptions } from 'grpcity'

loadOptions

Fields supported by loadOptions:

Field Name	Valid Values	Description
`keepCase`	`true` or `false`	Preserve field names. By default, they are changed to camel case.
`longs`	`String` or `Number`	Type used to represent `long` values. Default is the `Long` object type.
`enums`	`String`	Type used to represent `enum` values. Default is a numeric type.
`bytes`	`Array` or `String`	Type used to represent `bytes` values. Default is `Buffer`.
`defaults`	`true` or `false`	Set default values on the output object. Default is `false`.
`arrays`	`true` or `false`	Set empty arrays for missing array values, even if `defaults` is `false`. Default is `false`.
`objects`	`true` or `false`	Set empty objects for missing object values, even if `defaults` is `false`. Default is `false`.
`oneofs`	`true` or `false`	Set virtual oneof properties as field names. Default is `false`.
`json`	`true` or `false`	Represent `Infinity` and `NaN` as strings in `float` fields and automatically decode `google.protobuf.Any` values. Default is `false`.
`includeDirs`	Array of strings	List of search paths for imported `.proto` files.

gRPCity’s defaults:


{
  keepCase: true,
  longs: String,
  enums: String,
  defaults: false,
  oneofs: true
}

channelOptions

channelOptions are passed straight through to @grpc/grpc-js. The full list of channel arguments is documented here ; the subset that grpc-js currently honours is documented here .

gRPCity’s defaults are tuned for typical microservice deployments — short reconnect backoff, conservative keepalives, and a basic retry policy on UNAVAILABLE:


{
  // grpc library options accept only numeric and string types
  // Configure grpc reconnect time (1s to 10s random number)
  'grpc.min_reconnect_backoff_ms': 1000,
  'grpc.max_reconnect_backoff_ms': 10000,
  // Communication timeout
  'grpc.grpclb_call_timeout_ms': 5000,
  // The following 3 parameters address the issue of long-idle gRPC clients not promptly detecting TCP connection breaks
  // After waiting for a duration of this time, if the keepalive ping sender does not receive the ping ack, it will close the transport.
  'grpc.keepalive_timeout_ms': (20 * 1000),
  // duration of this time the client/server pings its peer to see if the transport is still alive
  'grpc.keepalive_time_ms': (120 * 1000),
  'grpc.keepalive_permit_without_calls': 1,
  // Communication failure allows grpc library retry
  'grpc.enable_retries': 1,
  // Configure retry parameters
  // Reference: https://github.com/grpc/proposal/blob/master/A6-client-retries.md#integration-with-service-config
  'grpc.service_config': JSON.stringify({
    retryPolicy: {
      // 1 normal send + 3 failed retries, each retry has the opportunity to be sent on a different subchannel than the original failure
      maxAttempts: 4,
      // Initial retry time interval: random(0, initialBackoff) seconds
      // The nth retry time; random(0, min(initialBackoff*backoffMultiplier^(n-1), maxBackoff)) seconds
      initialBackoff: '0.1s',
      maxBackoff: '1s',
      backoffMultiplier: 2,
      // Retry only in the case of network unavailability
      retryableStatusCodes: ['UNAVAILABLE']
    }
  })
}