@yolo-croket-dev/core 1.10.1 → 1.10.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.10.3
+
+- 종료 시작 시 등록한 RMQ consumer를 먼저 중단하고 실행 중인 RPC는 완료까지 기다립니다.
+- 종료 중 도착한 미실행 메시지와 재전달 확인 중 종료가 시작된 요청을 즉시 재큐잉합니다.
+- channel setup과 종료가 겹쳐도 새 consumer를 남기지 않습니다.
+
 ## 1.10.0
 
 - 비회원 인증 로그 마스킹·검증 오류 보호·재시도 정보 필드를 정식 발행합니다.

package/functions/rmq-diagnostics.function.d.ts

@@ -67,6 +67,18 @@ export declare function registerRmqObservation(owner: object, observer: RmqConne
  * @process 관찰 대상이 아니면 undefined를 반환한다.
  */
 export declare function getRmqDiagnosticSnapshot(owner: object): Snapshot | undefined;
+/**
+ * @author jun
+ * @description 현재 메시지의 핸들러 오류 상세를 LoggingServiceInterceptor가 기록할 수 있음을 표시한다.
+ * @process 메시지 객체만 약하게 참조하여 동시 요청과 재전달 메시지를 구분한다.
+ */
+export declare function markRmqHandlerLogging(message: unknown): void;
+/**
+ * @author jun
+ * @description 현재 메시지에 핸들러 오류 상세 로거가 있는지 확인한다.
+ * @process RPCInterceptor의 중복 상세 기록 여부를 결정한다.
+ */
+export declare function hasRmqHandlerLogging(message: unknown): boolean;
 /**
  * @author jun
  * @description 이미 기록한 오류 상세를 표시한다.

package/functions/rmq-diagnostics.function.js

@@ -26,13 +26,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDiagnosticRmqClient = exports.getRecordedRmqDiagnosticError = exports.recordRmqDiagnosticError = exports.getRmqDiagnosticSnapshot = exports.registerRmqObservation = exports.withRmqConnectionName = exports.createRmqObserver = exports.RmqConnectionObserver = exports.isRmqDiagnosticsEnabled = void 0;
+exports.createDiagnosticRmqClient = exports.getRecordedRmqDiagnosticError = exports.recordRmqDiagnosticError = exports.hasRmqHandlerLogging = exports.markRmqHandlerLogging = exports.getRmqDiagnosticSnapshot = exports.registerRmqObservation = exports.withRmqConnectionName = exports.createRmqObserver = exports.RmqConnectionObserver = exports.isRmqDiagnosticsEnabled = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_os_1 = __importDefault(require("node:os"));
 const microservices_1 = require("@nestjs/microservices");
 const msa_logger_1 = __importStar(require("@yolo-croket-dev/msa-logger"));
 const observations = new WeakMap();
 const recordedErrors = new WeakMap();
+const handlerLoggingMessages = new WeakSet();
 let logger;
 /**
  * @author jun
@@ -245,6 +246,25 @@ function getRmqDiagnosticSnapshot(owner) {
     return (_a = observations.get(owner)) === null || _a === void 0 ? void 0 : _a.snapshot();
 }
 exports.getRmqDiagnosticSnapshot = getRmqDiagnosticSnapshot;
+/**
+ * @author jun
+ * @description 현재 메시지의 핸들러 오류 상세를 LoggingServiceInterceptor가 기록할 수 있음을 표시한다.
+ * @process 메시지 객체만 약하게 참조하여 동시 요청과 재전달 메시지를 구분한다.
+ */
+function markRmqHandlerLogging(message) {
+    if (message !== null && typeof message === 'object')
+        handlerLoggingMessages.add(message);
+}
+exports.markRmqHandlerLogging = markRmqHandlerLogging;
+/**
+ * @author jun
+ * @description 현재 메시지에 핸들러 오류 상세 로거가 있는지 확인한다.
+ * @process RPCInterceptor의 중복 상세 기록 여부를 결정한다.
+ */
+function hasRmqHandlerLogging(message) {
+    return message !== null && typeof message === 'object' && handlerLoggingMessages.has(message);
+}
+exports.hasRmqHandlerLogging = hasRmqHandlerLogging;
 // Contains error metadata only, never per-request context: one RMQ error can reject concurrent calls.
 /**
  * @author jun

package/interceptors/logging-service.interceptor.js

@@ -161,6 +161,8 @@ let LoggingServiceInterceptor = class LoggingServiceInterceptor {
             loggingSpan.setTag('traceId', traceId);
             loggingSpan.setTag('messagePattern', pattern);
         }
+        if (connection)
+            (0, rmq_diagnostics_function_1.markRmqHandlerLogging)(originalMessage);
         return next.handle()
             .pipe((0, operators_1.tap)(() => {
             const elapsed = Date.now() - now;

package/interceptors/rpc.interceptor.d.ts

@@ -12,5 +12,6 @@ export declare class RPCInterceptor implements NestInterceptor {
     /** 메시지가 재전송되었을때에, 재시도 Count가 명시되어 있지 않을때에 처리 할지 여부를 결정하는 함수 */
     isRedeliveryMessage(replyTo: string, traceId: string): Promise<boolean>;
     private updateMaxLengthArrayShorten;
+    private requeueMessageOnShutdown;
     intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<unknown>>;
 }

package/interceptors/rpc.interceptor.js

@@ -148,6 +148,13 @@ let RPCInterceptor = class RPCInterceptor {
         }
         return obj;
     }
+    async requeueMessageOnShutdown(channel, message) {
+        msaLogger.debug('RPCInterceptor isApplicationExit called', { traceId: 'IS_APPLICATION_EXIT' });
+        await channel.cancel(message.fields.consumerTag);
+        channel.nack(message, false, true);
+        // 기존 서버에서 응답을 완료하면 재전달된 요청의 실제 응답을 클라이언트가 기다릴 수 없다.
+        return new rxjs_1.Observable();
+    }
     async intercept(context, next) {
         var _a, _b, _c, _d, _e;
         const options = this.reflector.get('rpcInterceptorScope', context.getHandler());
@@ -175,9 +182,7 @@ let RPCInterceptor = class RPCInterceptor {
         let abortController = new AbortController();
         /** consume 메시지 전부 cancel */
         if (this.gracefulShutdownService.isApplicationExit) {
-            msaLogger.debug('RPCInterceptor isApplicationExit called', { traceId: 'IS_APPLICATION_EXIT' });
-            channel.cancel(message.fields.consumerTag);
-            return new rxjs_1.Observable();
+            return this.requeueMessageOnShutdown(channel, message);
         }
         if (!staticRetryCount && reDeliveryCount > 0) {
             msaLogger.debug('RETRY_COUNT_ZERO_OR_NO_RETRY 발생 전, redelivery 발생', { traceId: ((_b = content.data.param) === null || _b === void 0 ? void 0 : _b.traceId) || 'RETRY_COUNT_ZERO_OR_NO_RETRY' }, {
@@ -189,6 +194,9 @@ let RPCInterceptor = class RPCInterceptor {
                 staticRetryCount,
             });
             const isRedeliveryMessage = await this.isRedeliveryMessage(message.properties.replyTo, execInterceptor.traceId);
+            if (this.gracefulShutdownService.isApplicationExit) {
+                return this.requeueMessageOnShutdown(channel, message);
+            }
             if (!isRedeliveryMessage || reDeliveryCount > 5) {
                 msaLogger.debug('isRedeliveryMessage RETRY_COUNT_ZERO_OR_NO_RETRY false', { traceId: ((_c = content.data.param) === null || _c === void 0 ? void 0 : _c.traceId) || 'RETRY_COUNT_ZERO_OR_NO_RETRY' });
                 channel.sendToQueue(message.properties.replyTo, Buffer.from(JSON.stringify({
@@ -207,7 +215,7 @@ let RPCInterceptor = class RPCInterceptor {
             msaLogger.debug('isRedeliveryMessage RETRY_COUNT_ZERO_OR_NO_RETRY true, 재처리하여 전달토록 하기', { traceId: ((_d = content.data.param) === null || _d === void 0 ? void 0 : _d.traceId) || 'RETRY_COUNT_ZERO_OR_NO_RETRY' });
         }
         const noAck = message.fields.routingKey.includes('ASYNC');
-        let localErrorProcessor = async (err) => {
+        let localErrorProcessor = async (err, preHandlerError = false) => {
             var _a, _b;
             const errMsg = err.response ? err.response : err.message;
             const status = err.status ? err.status : 500;
@@ -280,7 +288,8 @@ let RPCInterceptor = class RPCInterceptor {
                 }
             }
             const sendMessage = Buffer.from(JSON.stringify(abstractAmqpHandlerData));
-            const diagnostic = startConnection
+            const delegatedDiagnostic = Boolean(startConnection && !preHandlerError && (0, rmq_diagnostics_function_1.hasRmqHandlerLogging)(message));
+            const diagnostic = startConnection && !delegatedDiagnostic
                 ? (0, msa_logger_1.normalizeDiagnosticError)(err, isTimeoutError ? 'response_timeout' : 'service_error') : undefined;
             const diagnosticInfo = diagnostic ? {
                 ...diagnostic.diagnosticInfo,
@@ -293,26 +302,35 @@ let RPCInterceptor = class RPCInterceptor {
             } : undefined;
             if (!isAck || diagnostic) {
                 const currentContext = functions_1.AbortContext.getCurrentContext();
-                msaLogger.warn(isAck ? 'RPCInterceptor 오류 처리' : '에러 응답 전송 처리', {
-                    traceId: execInterceptor.traceId,
-                    diagnosticInfo,
-                }, diagnostic ? {
-                    error: diagnostic.details,
+                let logDetails = {
                     reDeliveryCount,
                     staticRetryCount,
                     currentContext: (_a = currentContext === null || currentContext === void 0 ? void 0 : currentContext.requestId) !== null && _a !== void 0 ? _a : null,
-                } : {
-                    error: {
-                        message: err.message,
-                        stack: err.stack,
-                        name: err.name,
-                        response: err.response,
-                        reDeliveryCount,
-                        staticRetryCount,
-                    },
-                    messagePattern: method,
-                    currentContext: currentContext && currentContext.requestId ? currentContext.requestId : null,
-                });
+                };
+                if (diagnostic) {
+                    logDetails = {
+                        ...logDetails,
+                        error: diagnostic.details,
+                    };
+                }
+                else if (!delegatedDiagnostic) {
+                    logDetails = {
+                        error: {
+                            message: err.message,
+                            stack: err.stack,
+                            name: err.name,
+                            response: err.response,
+                            reDeliveryCount,
+                            staticRetryCount,
+                        },
+                        messagePattern: method,
+                        currentContext: currentContext && currentContext.requestId ? currentContext.requestId : null,
+                    };
+                }
+                msaLogger.warn(isAck ? 'RPCInterceptor 오류 처리' : '에러 응답 전송 처리', {
+                    traceId: execInterceptor.traceId,
+                    diagnosticInfo,
+                }, logDetails);
             }
             if (!isAck) {
                 channel.sendToQueue(message.properties.replyTo, sendMessage, { correlationId: message.properties.correlationId });
@@ -344,10 +362,14 @@ let RPCInterceptor = class RPCInterceptor {
                 }
             }
             catch (err) {
-                await localErrorProcessor(err);
+                await localErrorProcessor(err, true);
                 return new rxjs_1.Observable();
             }
         }
+        // 재전달 여부를 비동기로 확인하는 동안 종료가 시작될 수 있으므로 실행 직전에 다시 확인한다.
+        if (this.gracefulShutdownService.isApplicationExit) {
+            return this.requeueMessageOnShutdown(channel, message);
+        }
         this.gracefulShutdownService.pushActiveInterceptors(execInterceptor);
         // eslint-disable-next-line consistent-return
         return functions_1.AbortContext.run(abortController.signal, execInterceptor.traceId, () => next

package/modules/graceful-shutdown/graceful-shutdown.module.js

@@ -42,8 +42,7 @@ let GracefulShutdownModule = class GracefulShutdownModule {
         this.gracefulShutdownService = gracefulShutdownService;
     }
     async onModuleDestroy() {
-        // onApplicationShutdown에서 모든 activeInterceptors 완료를 기다림
-        // 이렇게 하면 onModuleDestroy가 호출되기 전에 모든 이벤트가 처리됨
+        // provider의 onModuleDestroy에서 신규 수신을 중단한 뒤 기존 요청만 완료까지 기다린다.
         await this.gracefulShutdownService.waitForActiveInterceptors();
         msaLogger.info('GracefulShutdownService.onModuleDestroy: all interceptors finished, shutting down', { traceId: 'ON_MODULE_DESTROY' });
     }

package/modules/graceful-shutdown/graceful-shutdown.rmq.d.ts

@@ -1,7 +1,6 @@
 import { ServerRMQ } from '@nestjs/microservices';
 import type { RmqOptions } from '@nestjs/microservices';
 import type { Channel } from 'amqp-connection-manager';
-import type { ConsumeMessage } from 'amqplib';
 export type GracefulRmqOptions = RmqOptions['options'] & {
     waitingEndingHandlersTimeoutMs?: number;
     waitingEndingHandlersIntervalMs?: number;
@@ -17,12 +16,20 @@ export declare class GracefulServerRMQ extends ServerRMQ {
     protected runningMessages: number;
     protected closing: boolean;
     protected consumerTag: string | null;
+    private stopConsumingPromise?;
     protected readonly waitingEndingHandlersTimeoutMs: number;
     protected readonly waitingEndingHandlersIntervalMs: number;
     constructor(options: GracefulRmqOptions);
     createClient(): any;
     setupChannel(channel: Channel, callback: () => void): Promise<void>;
     protected waitingHandlers(): Promise<void>;
-    handleMessage(message: ConsumeMessage, channel: Channel): Promise<void>;
+    handleMessage(message: Parameters<ServerRMQ['handleMessage']>[0] | null, channel: Channel): Promise<void>;
+    /**
+     * @author jun
+     * @description 실행 중인 요청의 채널을 유지하면서 신규 메시지 수신을 중단한다.
+     * @process 종료 플래그 설정 → consumer 취소 → 이후 도착한 미실행 메시지는 재전달한다.
+     */
+    stopConsuming(): Promise<void>;
+    private cancelConsumer;
     close(): Promise<void>;
 }

package/modules/graceful-shutdown/graceful-shutdown.rmq.js

@@ -87,8 +87,15 @@ class GracefulServerRMQ extends microservices_1.ServerRMQ {
             await channel.assertQueue(this.queue, this.queueOptions);
         }
         await channel.prefetch(this.options.prefetchCount || 0, this.options.isGlobalPrefetchCount);
+        if (this.closing)
+            return;
         const { consumerTag } = await channel.consume(this.queue, (msg) => this.handleMessage(msg, channel), { noAck: false });
         this.consumerTag = consumerTag;
+        if (this.closing) {
+            await channel.cancel(consumerTag);
+            this.consumerTag = null;
+            return;
+        }
         callback();
     }
     async waitingHandlers() {
@@ -97,19 +104,42 @@ class GracefulServerRMQ extends microservices_1.ServerRMQ {
         }
     }
     async handleMessage(message, channel) {
+        if (!message)
+            return;
+        if (this.closing) {
+            channel.nack(message, false, true);
+            return;
+        }
         this.runningMessages += 1;
-        return super.handleMessage(message, channel).finally(() => {
+        await super.handleMessage(message, channel).finally(() => {
             this.runningMessages -= 1;
         });
     }
+    /**
+     * @author jun
+     * @description 실행 중인 요청의 채널을 유지하면서 신규 메시지 수신을 중단한다.
+     * @process 종료 플래그 설정 → consumer 취소 → 이후 도착한 미실행 메시지는 재전달한다.
+     */
+    stopConsuming() {
+        this.closing = true;
+        if (!this.stopConsumingPromise)
+            this.stopConsumingPromise = this.cancelConsumer();
+        return this.stopConsumingPromise;
+    }
+    async cancelConsumer() {
+        const consumerTag = this.consumerTag;
+        if (this.channel) {
+            await this.channel.removeSetup(undefined, async (channel) => {
+                if (consumerTag)
+                    await channel.cancel(consumerTag);
+            });
+        }
+        this.consumerTag = null;
+    }
     async close() {
         var _a;
-        this.closing = true;
         try {
-            if (this.channel) {
-                await this.channel.removeSetup(undefined, (channel) => channel.cancel(this.consumerTag));
-            }
-            this.consumerTag = null;
+            await this.stopConsuming();
             await Promise.race([
                 this.waitingHandlers(),
                 this.waitingEndingHandlersTimeoutMs > 0

package/modules/graceful-shutdown/graceful-shutdown.service.d.ts

@@ -1,4 +1,5 @@
 import { OnApplicationShutdown, OnModuleDestroy, OnApplicationBootstrap } from '@nestjs/common';
+import type { GracefulServerRMQ } from './graceful-shutdown.rmq';
 interface GracefulExecInterceptor {
     method: string;
     traceId?: string;
@@ -8,10 +9,17 @@ export declare class GracefulShutdownService implements OnApplicationShutdown, O
     private isExecLocal?;
     private activeInterceptors;
     isApplicationExit: boolean;
+    private readonly rmqServers;
     private readonly HEALTHY_FILE_PATH;
     private shutdownSignal?;
     private isShutdownInProgress;
     onApplicationBootstrap(): void;
+    /**
+     * @author jun
+     * @description 종료 시 신규 수신을 중단할 RMQ 서버를 등록한다.
+     * @process bootstrap에서 등록한 서버를 요청 drain보다 먼저 중단한다.
+     */
+    registerRmqServer(server: GracefulServerRMQ): void;
     pushActiveInterceptors(execInterceptor: GracefulExecInterceptor): void;
     popActiveInterceptors(execInterceptor: GracefulExecInterceptor): void;
     getActiveInterceptorsCount(): number;

package/modules/graceful-shutdown/graceful-shutdown.service.js

@@ -38,6 +38,7 @@ let GracefulShutdownService = class GracefulShutdownService {
     constructor() {
         this.activeInterceptors = [];
         this.isApplicationExit = false;
+        this.rmqServers = new Set();
         this.HEALTHY_FILE_PATH = '/tmp/healthy';
         this.isShutdownInProgress = false;
     }
@@ -58,6 +59,14 @@ let GracefulShutdownService = class GracefulShutdownService {
         // eslint-disable-next-line max-len
         msaLogger.debug(`GracefulShutdownService.onApplicationBootstrap isExecLocal=${this.isExecLocal}`, { traceId: 'ON_APPLICATION_BOOTSTRAP' }, { isHealthyFileExist });
     }
+    /**
+     * @author jun
+     * @description 종료 시 신규 수신을 중단할 RMQ 서버를 등록한다.
+     * @process bootstrap에서 등록한 서버를 요청 drain보다 먼저 중단한다.
+     */
+    registerRmqServer(server) {
+        this.rmqServers.add(server);
+    }
     pushActiveInterceptors(execInterceptor) {
         this.activeInterceptors.push(execInterceptor);
     }
@@ -85,9 +94,9 @@ let GracefulShutdownService = class GracefulShutdownService {
     }
     async onModuleDestroy() {
         msaLogger.debug('GracefulShutdownService.onModuleDestroy', { traceId: 'ON_MODULE_DESTROY' });
-        // onModuleDestroy에서는 단순히 플래그만 설정
-        // 실제 대기는 onApplicationShutdown에서 처리됨
+        // 신규 수신을 먼저 중단하고, module의 onModuleDestroy에서 기존 요청 완료를 기다린다.
         this.isApplicationExit = true;
+        await Promise.all([...this.rmqServers].map(server => server.stopConsuming()));
     }
     async waitForActiveInterceptors() {
         if (this.isExecLocal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-croket-dev/core",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "author": "Yolo Co., Ltd.",
   "description": "Yolo commonization module",
   "main": "index.js",

package/tests/rmq-consumer-diagnostics.test.cjs

@@ -2,7 +2,8 @@ const assert = require('node:assert/strict');
 const { EventEmitter } = require('node:events');
 const test = require('node:test');
 const { ServerRMQ, RmqContext } = require('@nestjs/microservices');
-const { lastValueFrom, throwError } = require('rxjs');
+const { from, lastValueFrom, throwError } = require('rxjs');
+const { mergeAll } = require('rxjs/operators');
 const { MsaLogger } = require('@yolo-croket-dev/msa-logger');
 const { GracefulServerRMQ } = require('../modules/graceful-shutdown/graceful-shutdown.rmq');
 const { LoggingServiceInterceptor } = require('../interceptors/logging-service.interceptor');
@@ -148,3 +149,90 @@ test('RPC-only handler failure records its trace and channel on the existing war
   assert.equal(warnings[0].info.diagnosticInfo.event, 'handler_failed');
   assert.equal(acknowledgements.length, 1);
 });
+
+test('combined consumer interceptors record one detailed failure in either order', async t => {
+  const warnings = [];
+  const errors = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info, details) => warnings.push({ message, info, details }));
+  t.mock.method(MsaLogger.prototype, 'printExceptionFliterService', (info, details) => errors.push({ info, details }));
+  for (const method of ['printInputInterceptorService', 'printOutService']) t.mock.method(MsaLogger.prototype, method, () => {});
+
+  for (const order of ['logging-first', 'rpc-first']) {
+    warnings.length = 0;
+    errors.length = 0;
+    const acknowledgements = [];
+    const replies = [];
+    const channel = {
+      sendToQueue: (...args) => replies.push(args),
+      ack: message => acknowledgements.push(message),
+    };
+    const observer = new RmqConnectionObserver('USER_SERVICE', 'consumer', undefined, () => {});
+    registerRmqObservation(channel, observer);
+    const data = { payload: {}, param: { traceId: `combined-${order}` } };
+    const message = {
+      content: Buffer.from(JSON.stringify({ pattern: 'user.fail', data })),
+      properties: { headers: {}, correlationId: 'correlation', replyTo: 'reply.queue' },
+      fields: { routingKey: 'USER_SERVICE', consumerTag: 'consumer' },
+    };
+    const rmqContext = new RmqContext([message, channel, 'user.fail']);
+    const execution = {
+      getArgs: () => [data, rmqContext],
+      getHandler: () => function handler() {},
+      switchToRpc: () => ({ getContext: () => rmqContext, getData: () => data }),
+      switchToHttp: () => ({ getRequest: () => data }),
+    };
+    const shutdown = { isApplicationExit: false, pushActiveInterceptors: () => {}, popActiveInterceptors: () => {} };
+    const rpc = new RPCInterceptor({ get: () => undefined }, shutdown);
+    const logging = new LoggingServiceInterceptor();
+    const failure = Error(`handler failed ${order}`);
+    const handler = { handle: () => throwError(() => failure) };
+    const stream = order === 'logging-first'
+      ? logging.intercept(execution, { handle: () => from(rpc.intercept(execution, handler)).pipe(mergeAll()) })
+      : await rpc.intercept(execution, { handle: () => logging.intercept(execution, handler) });
+
+    await assert.rejects(lastValueFrom(stream), actual => actual === failure);
+    assert.equal(errors.length, 1, `${order}: detailed error must be logged once`);
+    assert.equal(errors[0].info.traceId, data.param.traceId);
+    assert.equal(errors[0].info.diagnosticInfo.connectionId, observer.connectionId);
+    assert.equal(errors[0].details.errors[0].message, failure.message);
+    assert.equal(warnings.filter(record => record.info.diagnosticInfo).length, 0, `${order}: RPC must not duplicate diagnostics`);
+    assert.equal(replies.length, 1);
+    assert.equal(acknowledgements.length, 1);
+  }
+});
+
+test('RPC guard failure retains diagnostics when a logging interceptor surrounds it', async t => {
+  const warnings = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info, details) => warnings.push({ message, info, details }));
+  for (const method of ['printInputInterceptorService', 'printOutService']) t.mock.method(MsaLogger.prototype, method, () => {});
+  const replies = [];
+  const channel = { sendToQueue: (...args) => replies.push(args), ack: () => {} };
+  registerRmqObservation(channel, new RmqConnectionObserver('USER_SERVICE', 'consumer', undefined, () => {}));
+  const data = { payload: {}, param: { traceId: 'combined-guard' } };
+  const message = {
+    content: Buffer.from(JSON.stringify({ pattern: 'user.guard', data })),
+    properties: { headers: {}, correlationId: 'correlation', replyTo: 'reply.queue' },
+    fields: { routingKey: 'USER_SERVICE', consumerTag: 'consumer' },
+  };
+  const rmqContext = new RmqContext([message, channel, 'user.guard']);
+  const execution = {
+    getArgs: () => [data, rmqContext],
+    getHandler: () => function handler() {},
+    switchToRpc: () => ({ getContext: () => rmqContext, getData: () => data }),
+    switchToHttp: () => ({ getRequest: () => data }),
+  };
+  const rpc = new RPCInterceptor({ get: () => ({ isAdminGuard: true }) }, { isApplicationExit: false });
+  let guardProcess;
+  new LoggingServiceInterceptor().intercept(execution, {
+    handle: () => {
+      guardProcess = rpc.intercept(execution, { handle: () => { throw Error('guard should reject first'); } });
+      return from(guardProcess).pipe(mergeAll());
+    },
+  });
+  await guardProcess;
+  assert.equal(warnings.length, 1);
+  assert.equal(warnings[0].info.traceId, 'combined-guard');
+  assert.equal(warnings[0].info.diagnosticInfo.event, 'handler_failed');
+  assert.equal(warnings[0].details.error.errors[0].message, 'ADMIN_ONLY_ACCESS');
+  assert.equal(replies.length, 1);
+});

package/tests/rmq-shutdown-requeue.test.cjs

@@ -0,0 +1,191 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { RmqContext, ServerRMQ } = require('@nestjs/microservices');
+const { Subject } = require('rxjs');
+const { MsaLogger } = require('@yolo-croket-dev/msa-logger');
+const { RPCInterceptor } = require('../interceptors/rpc.interceptor');
+const { GracefulShutdownService } = require('../modules/graceful-shutdown/graceful-shutdown.service');
+const { GracefulServerRMQ } = require('../modules/graceful-shutdown/graceful-shutdown.rmq');
+
+function createRequest(channel, headers = {}) {
+  const data = { payload: {}, param: { traceId: 'shutdown-test' } };
+  const message = {
+    content: Buffer.from(JSON.stringify({ pattern: 'test.read', data })),
+    properties: { headers, correlationId: 'request-1', replyTo: 'reply-queue' },
+    fields: { consumerTag: 'consumer-1', routingKey: 'test.read' },
+  };
+  const rmq = new RmqContext([message, channel, 'test.read']);
+  return {
+    message,
+    context: { getHandler: () => 'test.read', getArgs: () => [data, rmq] },
+  };
+}
+
+test('종료 중 받은 미실행 RPC는 즉시 재전달하고 기존 요청의 ACK에는 손대지 않는다', async t => {
+  t.mock.method(MsaLogger.prototype, 'debug', () => {});
+  const shutdown = new GracefulShutdownService();
+  shutdown.isApplicationExit = true;
+  const calls = [];
+  const channel = {
+    cancel: async tag => { calls.push(['cancel', tag]); },
+    nack: (...args) => { calls.push(['nack', ...args]); },
+    ack: (...args) => { calls.push(['ack', ...args]); },
+    sendToQueue: (...args) => { calls.push(['reply', ...args]); },
+  };
+  const { message, context } = createRequest(channel);
+  const next = { handle: t.mock.fn(() => { throw Error('실행하면 안 되는 신규 요청'); }) };
+  const interceptor = new RPCInterceptor({ get: () => undefined }, shutdown);
+  await interceptor.intercept(context, next);
+  assert.deepEqual(calls, [
+    ['cancel', 'consumer-1'],
+    ['nack', message, false, true],
+  ]);
+  assert.equal(next.handle.mock.callCount(), 0);
+  assert.equal(shutdown.getActiveInterceptorsCount(), 0);
+});
+
+test('종료 전에 실행한 RPC는 계속 처리하고 종료 이후 도착한 메시지만 반환한다', async t => {
+  t.mock.method(MsaLogger.prototype, 'debug', () => {});
+  const shutdown = new GracefulShutdownService();
+  const calls = [];
+  let consume;
+  const channel = {
+    assertQueue: async () => {},
+    prefetch: async () => {},
+    consume: async (_queue, callback) => { consume = callback; return { consumerTag: 'consumer-1' }; },
+    cancel: async tag => { calls.push(['cancel', tag]); },
+    nack: (...args) => { calls.push(['nack', ...args]); },
+    ack: (...args) => { calls.push(['ack', ...args]); },
+  };
+  const server = new GracefulServerRMQ({ queue: 'TEST', noAck: false });
+  server.channel = { removeSetup: async (_setup, teardown) => teardown(channel) };
+  await server.setupChannel(channel, () => {});
+  const { message: runningMessage, context } = createRequest(channel);
+  const result = new Subject();
+  t.after(() => result.complete());
+  const interceptor = new RPCInterceptor({ get: () => undefined }, shutdown);
+  const response = await interceptor.intercept(context, { handle: () => result });
+  const values = [];
+  response.subscribe(value => values.push(value));
+  assert.equal(shutdown.getActiveInterceptorsCount(), 1);
+
+  shutdown.registerRmqServer(server);
+  await shutdown.onModuleDestroy();
+  assert.equal(shutdown.isApplicationExit, true);
+  assert.equal(shutdown.getActiveInterceptorsCount(), 1);
+  assert.deepEqual(calls, [['cancel', 'consumer-1']]);
+  const { message: newMessage } = createRequest(channel);
+  await consume(newMessage);
+  await consume(null);
+  assert.deepEqual(calls, [['cancel', 'consumer-1'], ['nack', newMessage, false, true]]);
+
+  result.next({ data: { ok: true } });
+  result.complete();
+  assert.deepEqual(values, [{ data: { ok: true }, isError: false }]);
+  assert.deepEqual(calls.at(-1), ['ack', runningMessage]);
+  assert.equal(shutdown.getActiveInterceptorsCount(), 0);
+});
+
+test('재전달 확인 중 종료가 시작되면 실행 직전에 요청을 반환한다', async t => {
+  t.mock.method(MsaLogger.prototype, 'debug', () => {});
+  const shutdown = new GracefulShutdownService();
+  const calls = [];
+  const channel = {
+    cancel: async tag => { calls.push(['cancel', tag]); },
+    nack: (...args) => { calls.push(['nack', ...args]); },
+  };
+  const { message, context } = createRequest(channel, { 'x-delivery-count': 1 });
+  const next = { handle: t.mock.fn(() => { throw Error('실행하면 안 되는 신규 요청'); }) };
+  const interceptor = new RPCInterceptor({ get: () => undefined }, shutdown);
+  t.mock.method(interceptor, 'isRedeliveryMessage', async () => {
+    shutdown.isApplicationExit = true;
+    return true;
+  });
+  await interceptor.intercept(context, next);
+  assert.deepEqual(calls, [['cancel', 'consumer-1'], ['nack', message, false, true]]);
+  assert.equal(next.handle.mock.callCount(), 0);
+  assert.equal(shutdown.getActiveInterceptorsCount(), 0);
+});
+
+for (const scenario of [
+  { result: false, deliveryCount: 1, name: '재전달 확인 실패' },
+  { result: true, deliveryCount: 6, name: '재전달 횟수 초과' },
+]) {
+  test(`종료가 시작되면 ${scenario.name} 요청도 DLQ 대신 재큐잉한다`, async t => {
+    t.mock.method(MsaLogger.prototype, 'debug', () => {});
+    const shutdown = new GracefulShutdownService();
+    const calls = [];
+    const channel = {
+      cancel: async tag => { calls.push(['cancel', tag]); },
+      nack: (...args) => { calls.push(['nack', ...args]); },
+      sendToQueue: () => { calls.push(['reply']); },
+    };
+    const { message, context } = createRequest(channel, { 'x-delivery-count': scenario.deliveryCount });
+    const next = { handle: t.mock.fn(() => { throw Error('실행하면 안 되는 신규 요청'); }) };
+    const interceptor = new RPCInterceptor({ get: () => undefined }, shutdown);
+    t.mock.method(interceptor, 'isRedeliveryMessage', async () => {
+      shutdown.isApplicationExit = true;
+      return scenario.result;
+    });
+    await interceptor.intercept(context, next);
+    assert.deepEqual(calls, [['cancel', 'consumer-1'], ['nack', message, false, true]]);
+    assert.equal(next.handle.mock.callCount(), 0);
+    assert.equal(shutdown.getActiveInterceptorsCount(), 0);
+  });
+}
+
+test('수신 중단과 서버 close가 겹쳐도 consumer는 한 번만 취소한다', async t => {
+  const calls = [];
+  let finishCancel;
+  const pendingCancel = new Promise(resolve => { finishCancel = resolve; });
+  t.after(() => finishCancel());
+  const channel = { cancel: async tag => { calls.push(['cancel', tag]); await pendingCancel; } };
+  const server = new GracefulServerRMQ({ queue: 'TEST', waitingEndingHandlersTimeoutMs: 1 });
+  server.consumerTag = 'consumer-1';
+  server.channel = { removeSetup: async (_setup, teardown) => teardown(channel) };
+  t.mock.method(ServerRMQ.prototype, 'close', async () => { calls.push(['close']); });
+  const stopping = server.stopConsuming();
+  const closing = server.close();
+  assert.deepEqual(calls, [['cancel', 'consumer-1']]);
+  finishCancel();
+  await Promise.all([stopping, closing]);
+  assert.deepEqual(calls, [['cancel', 'consumer-1'], ['close']]);
+});
+
+test('채널 설정 중 종료가 시작되면 새 consumer를 만들지 않는다', async () => {
+  let finishPrefetch;
+  const prefetch = new Promise(resolve => { finishPrefetch = resolve; });
+  const calls = [];
+  const channel = {
+    assertQueue: async () => {},
+    prefetch: async () => prefetch,
+    consume: async () => { calls.push('consume'); return { consumerTag: 'new-consumer' }; },
+  };
+  const server = new GracefulServerRMQ({ queue: 'TEST' });
+  const setup = server.setupChannel(channel, () => calls.push('ready'));
+  await server.stopConsuming();
+  finishPrefetch();
+  await setup;
+  assert.deepEqual(calls, []);
+});
+
+test('consumer 등록이 끝나기 전에 종료가 시작되면 해당 consumer도 취소한다', async () => {
+  let finishConsume;
+  let enteredConsume;
+  const started = new Promise(resolve => { enteredConsume = resolve; });
+  const consumer = new Promise(resolve => { finishConsume = resolve; });
+  const calls = [];
+  const channel = {
+    assertQueue: async () => {},
+    prefetch: async () => {},
+    consume: async () => { enteredConsume(); return consumer; },
+    cancel: async tag => { calls.push(['cancel', tag]); },
+  };
+  const server = new GracefulServerRMQ({ queue: 'TEST' });
+  const setup = server.setupChannel(channel, () => calls.push(['ready']));
+  await started;
+  await server.stopConsuming();
+  finishConsume({ consumerTag: 'new-consumer' });
+  await setup;
+  assert.deepEqual(calls, [['cancel', 'new-consumer']]);
+});