@vyhoang/gateway-registration-sdk

Gateway Registration SDK

Package dùng chung để các gRPC service đăng ký route runtime với gateway.

Package này gồm 2 phần:

• contracts: kiểu dữ liệu route metadata, policy, pipeline, validation schema
• sdk: helper/service SDK để publish và re-publish routes lên gateway

Mục tiêu là để các gRPC service có thể dùng chung một chuẩn metadata, thay vì mỗi service tự định nghĩa type và subject riêng.

Package này giải quyết bài toán gì?

Khi gateway đi theo hướng runtime route registration:

1. Service boot lên
2. Service publish danh sách route metadata qua message bus
3. Gateway nhận metadata và nạp vào runtime registry
4. Gateway có thể yêu cầu các service re-sync route khi vừa khởi động hoặc khi cần đồng bộ lại

Package này chuẩn hóa đúng flow đó.

Phạm vi

Package này chỉ nên chứa:

• contract dùng chung giữa gateway và service
• constants cho subject/event
• helper để định nghĩa route metadata
• service-side SDK để publish route metadata

Package này không nên chứa:

• RouteRegistry của gateway
• GatewayPipeline
• auth/security step
• transport adapter runtime của gateway
• business logic của từng service

Export chính

Contracts

• RouteDefinition
• RouteRegistrationPayload
• ActionPolicy
• ActionPipelineConfig
• RouteValidationConfig
• JsonSchemaLike
• GrpcTargetDefinition (Định nghĩa target cho gRPC service)
• RouteMetadata
• ApiAction

Constants

• GATEWAY_REGISTER_SUBJECT
• GATEWAY_ROUTE_SYNC_REQUEST_SUBJECT

Helpers

• defineRoute(...)
• defineRoutes(...)

SDK

• GatewayRoutePublisher
• createGatewayRoutePublisher(...)
• isGatewayRouteSyncRequestSubject(...)

Cài đặt

npm install @vyhoang/gateway-registration-sdk

Ví dụ route metadata

import { defineRoutes } from '@vyhoang/gateway-registration-sdk';

export const PRODUCT_ROUTES = defineRoutes([
  {
    method: 'POST',
    path: '/product',
    action: 'product.create',
    target: {
      protocol: 'grpc',
      package: 'product',
      service: 'ProductService',
      method: 'CreateProduct',
    },
    policy: {
      clientPermissions: ['product-write'],
      requiredScopes: ['product.write'],
      rateLimit: 20,
      audit: true,
      requireUser: true,
      authCacheSeconds: 60,
    },
    validation: {
      body: {
        type: 'object',
        required: ['name'],
      },
    },
  },
]);

Lưu ý:

• Trường target trong RouteDefinition hiện tại chỉ hỗ trợ GrpcTargetDefinition (dành cho gRPC service).
• Kiểu JsonSchemaLike hiện tại là phiên bản đơn giản của JSON Schema, chỉ hỗ trợ các trường type và required. Các tính năng mở rộng như properties, minLength chưa được hỗ trợ.

Ví dụ dùng SDK trong service

SDK này không phụ thuộc framework. Chỉ cần truyền vào một object có hàm emit(subject, payload).

import {
  createGatewayRoutePublisher,
  defineRoutes,
} from '@vyhoang/gateway-registration-sdk';

const routes = defineRoutes([
  {
    method: 'POST',
    path: '/product',
    action: 'product.create',
    target: {
      protocol: 'grpc',
      package: 'product',
      service: 'ProductService',
      method: 'CreateProduct',
    },
  },
]);

const publisher = createGatewayRoutePublisher({
  source: 'product-service',
  routes,
  client: {
    emit: (subject, payload) => messageClient.emit(subject, payload),
  },
  logger: console,
});

await publisher.publishRoutes();

Re-sync routes

Khi gateway gửi subject gateway.routes.sync.request, service có thể gọi lại publishRoutes() để đăng ký lại toàn bộ route hiện tại.

Ví dụ:

await publisher.handleSyncRequest();

Hoặc nếu bạn đang tự subscribe event:

if (isGatewayRouteSyncRequestSubject(subject)) {
  await publisher.publishRoutes();
}

Gợi ý tích hợp

Với NestJS gRPC service

• tạo file *.route.metadata.ts
• tạo publisher trong onModuleInit()
• khi nhận sync request thì gọi lại publishRoutes()

English

Shared package for runtime route registration between gRPC services and the gateway.

This package includes two main parts:

• contracts: route metadata, policy, pipeline, and validation schema types
• sdk: helper/service SDK to publish and re-publish routes to the gateway

The goal is to let gRPC-based services share one metadata contract instead of redefining types and subjects in each service.

What problem does this package solve?

When the gateway follows a runtime route registration model:

1. A service starts
2. The service publishes its route metadata through a message bus
3. The gateway receives that metadata and loads it into the runtime registry
4. The gateway can request services to re-sync routes after startup or when reloading state

This package standardizes that flow.

Scope

This package should contain only:

• shared contracts between gateway and services
• constants for subjects/events
• helpers to define route metadata
• a service-side SDK to publish route metadata

This package should not contain:

• gateway RouteRegistry
• GatewayPipeline
• auth/security steps
• gateway runtime transport adapters
• business logic from individual services

Main exports

Contracts

• RouteDefinition
• RouteRegistrationPayload
• ActionPolicy
• ActionPipelineConfig
• RouteValidationConfig
• JsonSchemaLike
• GrpcTargetDefinition (Target definition for gRPC services)
• RouteMetadata
• ApiAction

Constants

• GATEWAY_REGISTER_SUBJECT
• GATEWAY_ROUTE_SYNC_REQUEST_SUBJECT

Helpers

• defineRoute(...)
• defineRoutes(...)

SDK

• GatewayRoutePublisher
• createGatewayRoutePublisher(...)
• isGatewayRouteSyncRequestSubject(...)

Installation

npm install @vyhoang/gateway-registration-sdk

Example route metadata

import { defineRoutes } from '@vyhoang/gateway-registration-sdk';

export const PRODUCT_ROUTES = defineRoutes([
  {
    method: 'POST',
    path: '/product',
    action: 'product.create',
    target: {
      protocol: 'grpc',
      package: 'product',
      service: 'ProductService',
      method: 'CreateProduct',
    },
    policy: {
      clientPermissions: ['product-write'],
      requiredScopes: ['product.write'],
      rateLimit: 20,
      audit: true,
      requireUser: true,
      authCacheSeconds: 60,
    },
    validation: {
      body: {
        type: 'object',
        required: ['name'],
      },
    },
  },
]);

Note:

• The target field in RouteDefinition currently only supports GrpcTargetDefinition (for gRPC services).
• The JsonSchemaLike type is a simplified version of JSON Schema, only supporting type and required fields. Extended JSON Schema features like properties, minLength are not yet supported.

Example SDK usage in a service

The SDK is framework agnostic. You only need to provide an object with an emit(subject, payload) function.

import {
  createGatewayRoutePublisher,
  defineRoutes,
} from '@vyhoang/gateway-registration-sdk';

const routes = defineRoutes([
  {
    method: 'POST',
    path: '/product',
    action: 'product.create',
    target: {
      protocol: 'grpc',
      package: 'product',
      service: 'ProductService',
      method: 'CreateProduct',
    },
  },
]);

const publisher = createGatewayRoutePublisher({
  source: 'product-service',
  routes,
  client: {
    emit: (subject, payload) => messageClient.emit(subject, payload),
  },
  logger: console,
});

await publisher.publishRoutes();

Route re-sync

When the gateway emits the gateway.routes.sync.request subject, a service can call publishRoutes() again to re-register its full route set.

Example:

await publisher.handleSyncRequest();

Or when you already subscribe to events yourself:

if (isGatewayRouteSyncRequestSubject(subject)) {
  await publisher.publishRoutes();
}

Integration notes

For NestJS gRPC services

• create a *.route.metadata.ts file
• create the publisher in onModuleInit()
• call publishRoutes() again when a sync request arrives