@gravity-ui/gateway 4.6.0 → 4.7.1-alpha.0

package/README.md

@@ -7,7 +7,6 @@ A flexible and powerful Express controller for working with REST and gRPC APIs i
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Configuration](#configuration)
-  - [Config Structure](#config-structure)
   - [Validation Schema](#validation-schema)
   - [Using the API in Node.js](#using-the-api-in-nodejs)
   - [Schema Scopes](#schema-scopes)
@@ -17,6 +16,8 @@ A flexible and powerful Express controller for working with REST and gRPC APIs i
   - [Error Handling](#error-handling)
   - [gRPC Reflection](#grpc-reflection-for-grpc-actions)
   - [Retryable Errors](#retryable-errors)
+  - [Request Cancellation](#request-cancellation)
+  - [Response Content Type Validation](#response-content-type-validation)
 - [Development](#development)
   - [Running Tests](#running-tests)
   - [Contributing](#contributing)
@@ -73,11 +74,14 @@ interface Stats {
   action: string;
   restStatus: number;
   grpcStatus?: number;
+  responseSize: number;
   requestId: string;
   requestTime: number;
   requestMethod: string;
   requestUrl: string;
   timestamp: number;
+  userId?: string;
+  traceId: string;
 }
 
 type SendStats = (
@@ -92,9 +96,18 @@ type AxiosRetryCondition = IAxiosRetryConfig['retryCondition'];
 
 type ControllerType = 'rest' | 'grpc';
 
+type ProxyHeadersFunctionExtra = {
+  service: string;
+  action: string;
+
+  protopath?: string;
+  protokey?: string;
+};
+
 type ProxyHeadersFunction = (
   headers: IncomingHttpHeaders,
   type: ControllerType,
+  extra: ProxyHeadersFunctionExtra,
 ) => IncomingHttpHeaders;
 type ProxyHeaders = string[] | ProxyHeadersFunction;
 type ResponseContentType = AxiosResponse['headers']['Content-Type'];
@@ -172,7 +185,7 @@ interface GatewayConfig {
 
   // When passing a boolean value, it enables/disables debug headers in the response to the request.
   // For unary requests to gRPC backends, debug headers will include information from the trailing metadata returned by the backend.
-  withDebugHeaders?: boolean;
+  withDebugHeaders?: boolean | ((req: Request, res: Response) => boolean);
 
   // Validation schema for parameters used when no schema is present in the action.
   // You can use DEFAULT_VALIDATION_SCHEMA from lib/constants.ts.
@@ -202,9 +215,63 @@ interface GatewayConfig {
 
   // Error constructor for handling errors
   ErrorConstructor: AppErrorConstructor;
+
+  // Axios interceptors configuration
+  axiosInterceptors?: AxiosInterceptorsConfig;
 }
 ```
 
+### `proxyHeaders`
+
+`GatewayConfig.proxyHeaders` is an optional method that allows setting headers for requests at the entire `gateway` level:
+
+```javascript
+const proxyHeaders = (headers, actionType, extra) => {
+  const normalizedHeaders = {...headers};
+  const {service, action, protopath, protokey} = extra;
+
+  if (actionType === 'rest' && service === 'mail') {
+    normalizedHeaders['x-mail-service-action'] = action;
+  }
+
+  return normalizedHeaders;
+};
+
+const {controller: gatewayController} = getGatewayControllers(
+  {root: Schema},
+  {...config, proxyHeaders},
+);
+```
+
+The `extra` parameter contains additional information about the request:
+
+- `service`: The service name
+- `action`: The action name
+- `protopath`: The proto path (for gRPC actions)
+- `protokey`: The proto key (for gRPC actions)
+
+You can set headers for a specific action using `ApiServiceBaseActionConfig.proxyHeaders`:
+
+```javascript
+const schema = {
+  userService: {
+    serviceName: 'users',
+    endpoints: {...},
+    actions: {
+      getProfile: {
+        path: () => '/profile',
+        method: 'GET',
+        proxyHeaders: (headers) => ({...headers, ['x-users-service-action']: 'get-profile'}),
+      },
+    },
+  },
+};
+```
+
+The `GatewayConfig.proxyHeaders` and `ApiServiceBaseActionConfig.proxyHeaders` are merged when the action is called. The strategy for merging headers is not guaranteed.
+
+It is recommended to use `GatewayConfig.proxyHeaders` for assigning headers that are common to the entire application or a large number of actions. Otherwise, it is preferable to use `ApiServiceBaseActionConfig.proxyHeaders`.
+
 ### Validation Schema
 
 By default, for path params in REST actions, the following regexp is used: `/^((?!(\.\.|\?|#|\\|\/)).)*$/i`.
@@ -270,6 +337,8 @@ interface ApiActionConfig<Context, TRequestData> {
   timeout?: number;
   callback?: (response: TResponseData) => void;
   authArgs?: Record<string, unknown>;
+  userId?: string;
+  abortSignal?: AbortSignal;
 }
 ```
 
@@ -461,7 +530,7 @@ The **default** retry condition for REST-actions includes the following conditio
 - Network errors (detected by `axiosRetry.isNetworkError`)
 - Other retryable errors (detected by `axiosRetry.isRetryableError`)
 
-You can customize retry behavior for using the `axiosRetryCondition` config option:
+You can customize retry behavior using the `axiosRetryCondition` config option:
 
 ```javascript
 const config = {
@@ -473,6 +542,27 @@ const config = {
 };
 ```
 
+You can also set retry conditions at the action level:
+
+```javascript
+const schema = {
+  userService: {
+    serviceName: 'users',
+    endpoints: {...},
+    actions: {
+      getProfile: {
+        path: () => '/profile',
+        method: 'GET',
+        axiosRetryCondition: (error) => {
+          // Custom logic for this specific action
+          return error.code === 'ECONNRESET';
+        },
+      },
+    },
+  },
+};
+```
+
 #### gRPC-actions
 
 The **default** retry condition for gRPC-actions includes the certain gRPC status codes:
@@ -494,8 +584,94 @@ const config = {
 };
 ```
 
+The library exports the `isRetryableGrpcError` function that you can use to check if a gRPC error is retryable according to the default conditions:
+
+```javascript
+import {isRetryableGrpcError} from '@gravity-ui/gateway';
+
+// Use in your custom retry condition
+const customGrpcRetryCondition = (error) => {
+  return isRetryableGrpcError(error) || error.code === 'RESOURCE_EXHAUSTED';
+};
+```
+
 For gRPC-requests that fail with `DEADLINE_EXCEEDED`, the service connection is recreated before retrying if config option `grpcRecreateService` is not set to `false`.
 
+### Request Cancellation
+
+The gateway supports cancelling requests when the client disconnects. This is useful for long-running operations where you want to avoid unnecessary processing if the client is no longer waiting for the response.
+
+This feature is enabled by default for exported controller. For API requests, you can pass an `AbortSignal` to cancel the request:
+
+```javascript
+const abortController = new AbortController();
+
+const result = await gatewayApi.serviceName.actionName({
+  authArgs: {token: 'auth-token'},
+  requestId: '123',
+  headers: {},
+  args: {param1: 'value1'},
+  ctx: context,
+  abortSignal: abortController.signal,
+});
+```
+
+You can also control this behavior at the action level using the `abortOnClientDisconnect` option:
+
+```javascript
+const schema = {
+  userService: {
+    serviceName: 'users',
+    endpoints: {...},
+    actions: {
+      longRunningOperation: {
+        path: () => '/process',
+        method: 'POST',
+        abortOnClientDisconnect: true, // Enable cancellation for this action
+      },
+    },
+  },
+};
+```
+
+### Response Content Type Validation
+
+For REST actions, you can validate the content type of the response to ensure it matches your expectations. This is useful for ensuring that the API returns the expected format.
+
+You can set the expected content type at the gateway level:
+
+```javascript
+const config = {
+  // ...other config options
+  expectedResponseContentType: 'application/json',
+};
+```
+
+Or at the action level:
+
+```javascript
+const schema = {
+  userService: {
+    serviceName: 'users',
+    endpoints: {...},
+    actions: {
+      getProfile: {
+        path: () => '/profile',
+        method: 'GET',
+        expectedResponseContentType: 'application/json',
+      },
+      getDocument: {
+        path: () => '/document',
+        method: 'GET',
+        expectedResponseContentType: ['application/pdf', 'application/octet-stream'],
+      },
+    },
+  },
+};
+```
+
+You can specify either a single content type or an array of acceptable content types. If the response content type doesn't match any of the expected types, an error will be thrown.
+
 ### gRPC Reflection for gRPC Actions
 
 Instead of using gRPC proto files, you can use gRPC reflection to determine the structure of services and methods.

package/{build → dist/commonjs}/components/grpc.d.ts

@@ -1,9 +1,9 @@
 import * as grpc from '@grpc/grpc-js';
-import * as protobufjs from 'protobufjs';
+import protobufjs from 'protobufjs';
 import type * as descriptor from 'protobufjs/ext/descriptor';
-import { ApiActionConfig, ApiServiceGrpcActionConfig, EndpointsConfig, GatewayApiOptions } from '../models/common';
-import { GatewayContext } from '../models/context';
-import { AppErrorConstructor } from '../models/error';
+import { ApiActionConfig, ApiServiceGrpcActionConfig, EndpointsConfig, GatewayApiOptions } from '../models/common.js';
+import { GatewayContext } from '../models/context.js';
+import { AppErrorConstructor } from '../models/error.js';
 declare module 'protobufjs' {
     interface Root {
         toDescriptor(protoVersion: string): protobufjs.Message<descriptor.IFileDescriptorSet> & descriptor.IFileDescriptorSet;
@@ -20,5 +20,5 @@ export interface GrpcContext {
 }
 export declare function createRoot(includeGrpcPaths?: string[]): protobufjs.Root;
 export declare function getCredentialsMap(caCertificatePath?: string | null): CredentialsMap;
-export default function createGrpcAction<Context extends GatewayContext>({ root, credentials }: GrpcContext, endpoints: EndpointsConfig | undefined, config: ApiServiceGrpcActionConfig<Context, any, any>, serviceKey: string, actionName: string, options: GatewayApiOptions<Context>, ErrorConstructor: AppErrorConstructor): (actionConfig: ApiActionConfig<Context, any, any>) => Promise<import("../models/common").GatewayActionClientStreamResponse<any> | import("../models/common").GatewayActionServerStreamResponse<any> | import("../models/common").GatewayActionDuplexStreamResponse<any> | import("../models/common").GatewayActionUnaryResponse<any>>;
+export declare function createGrpcAction<Context extends GatewayContext>({ root, credentials }: GrpcContext, endpoints: EndpointsConfig | undefined, config: ApiServiceGrpcActionConfig<Context, any, any>, serviceKey: string, actionName: string, options: GatewayApiOptions<Context>, ErrorConstructor: AppErrorConstructor): (actionConfig: ApiActionConfig<Context, any, any>) => Promise<import("../models/common.js").GatewayActionClientStreamResponse<any> | import("../models/common.js").GatewayActionServerStreamResponse<any> | import("../models/common.js").GatewayActionDuplexStreamResponse<any> | import("../models/common.js").GatewayActionUnaryResponse<any>>;
 export {};