@vyhoang/gateway-registration-sdk

Gateway Registration SDK

Package dùng chung để các 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à để nhiều service như NestJS, Moleculer hoặc service dùng NATS thuần 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

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',
    service: 'product',
    transport: 'nats',
    pattern: 'product.create',
    policy: {
      clientPermissions: ['product-write'],
      requiredScopes: ['product.write'],
      rateLimit: 20,
      audit: true,
      requireUser: true,
      authCacheSeconds: 60,
    },
    validation: {
      body: {
        type: 'object',
        required: ['name'],
        properties: {
          name: { type: 'string', minLength: 1 },
        },
      },
    },
  },
]);

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',
    service: 'product',
    transport: 'nats',
    pattern: 'product.create',
  },
]);

const publisher = createGatewayRoutePublisher({
  source: 'product-service',
  routes,
  client: {
    emit: (subject, payload) => natsClient.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 service

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

Với Moleculer service

• giữ metadata ở tầng infrastructure
• khởi tạo publisher trong started()
• đóng publisher trong stopped() nếu cần
• khi nhận sync request thì publish lại route

English

Shared package for runtime route registration between 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 multiple services such as NestJS, Moleculer, or plain NATS-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

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',
    service: 'product',
    transport: 'nats',
    pattern: 'product.create',
    policy: {
      clientPermissions: ['product-write'],
      requiredScopes: ['product.write'],
      rateLimit: 20,
      audit: true,
      requireUser: true,
      authCacheSeconds: 60,
    },
    validation: {
      body: {
        type: 'object',
        required: ['name'],
        properties: {
          name: { type: 'string', minLength: 1 },
        },
      },
    },
  },
]);

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',
    service: 'product',
    transport: 'nats',
    pattern: 'product.create',
  },
]);

const publisher = createGatewayRoutePublisher({
  source: 'product-service',
  routes,
  client: {
    emit: (subject, payload) => natsClient.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 services

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

For Moleculer services

• keep metadata in the infrastructure layer
• initialize the publisher in started()
• close publisher resources in stopped() if needed
• re-publish routes when a sync request arrives