nice-grpc

Server middleware intercepts calls to execute logic before/after methods, inspect/modify metadata, or augment the CallContext. Middleware is defined as an AsyncGenerator.

Basic Middleware Structure:

import {ServerMiddlewareCall, CallContext} from 'nice-grpc';

async function* middleware<Request, Response>(call: ServerMiddlewareCall<Request, Response>, context: CallContext) {
  return yield* call.next(call.request, context);
}

Attaching Middleware:

• Globally: createServer().use(middleware)
• Per-service: server.with(middleware).add(Service, implementation)

Note: Middleware attached first is invoked first.

import {ServerMiddlewareCall, CallContext} from 'nice-grpc';

async function* middleware<Request, Response>(call: ServerMiddlewareCall<Request, Response>, context: CallContext) {
  if (!call.responseStream) {
    const response = yield* call.next(call.request, context);
    return response;
  } else {
    for await (const response of call.next(call.request, context)) {
      yield response;
    }
    return;
  }
}

const server = createServer().use(middleware);

Client middleware intercepts outgoing calls, allowing you to execute logic before/after the call, modify metadata, inspect requests/responses, or implement retries.

Middleware is defined as an Async Generator.

Basic Middleware Structure

For unary and client streaming methods, call.next yields no items and returns a single response. For server streaming and bidirectional streaming, it yields each response.

import {ClientMiddlewareCall, CallOptions} from 'nice-grpc-web';

async function* middleware<Request, Response>(
  call: ClientMiddlewareCall<Request, Response>,
  options: CallOptions,
) {
  if (!call.responseStream) {
    // Unary or Client Streaming
    const response = yield* call.next(call.request, options);
    return response;
  } else {
    // Server Streaming or Bidirectional
    for await (const response of call.next(call.request, options)) {
      yield response;
    }
    return;
  }
}

Using a Client Factory

To attach middleware, use createClientFactory. Middleware attached first is invoked last (it wraps the subsequent ones).

import {createClientFactory} from 'nice-grpc-web';

const clientFactory = createClientFactory().use(middleware1).use(middleware2);

// Create multiple clients from one factory
const client1 = clientFactory.create(Service1, channel1);
const client2 = clientFactory.create(Service2, channel2);

Client middleware intercepts outgoing calls. Unlike server middleware, the invocation order is reversed (the first middleware attached is the last one invoked). Client middleware uses CallOptions instead of CallContext.

Creating a Client with Middleware: Use createClientFactory() to chain middleware before creating the client.

import {createClientFactory} from 'nice-grpc';

const client = createClientFactory()
  .use(middleware1)
  .use(middleware2)
  .create(ExampleService, channel);

Type Augmentation: If your middleware adds properties to CallOptions, you can annotate the client type:

let client: ExampleServiceClient<{myCustomOption?: number}>;
client = createClientFactory().use(middleware).create(ExampleService, channel);

import {ClientMiddlewareCall, CallOptions} from 'nice-grpc';

async function* middleware<Request, Response>(call: ClientMiddlewareCall<Request, Response>, options: CallOptions) {
  return yield* call.next(call.request, options);
}

const clientFactory = createClientFactory().use(middleware);
const client = clientFactory.create(ExampleService, channel);

You can provide your own metric instances to the middleware. This is useful if you want to use custom histogram buckets or a custom registry. When using custom metrics, ensure you use the correct labelNames (either labelNames or labelNamesWithCode) to avoid errors.

import {createClientFactory} from 'nice-grpc';
import {
  labelNamesWithCode,
  prometheusClientMiddleware,
} from 'nice-grpc-prometheus';
import {Histogram, Registry} from 'prom-client';

const registry = new Registry();

const clientHandlingSecondsMetric = new Histogram({
  registers: [registry],
  name: 'custom_grpc_client_handling_seconds',
  help: 'Custom histogram of response latency (seconds) of the gRPC until it is finished by the application.',
  labelNames: labelNamesWithCode,
  buckets: [0.1, 0.5, 1, 2, 3, 5, 10],
});

const clientFactory = createClientFactory()
  .use(prometheusClientMiddleware({clientHandlingSecondsMetric}))
  .use(/* ... other middleware */);

// Remember to merge this registry with your global registry