Merge pull request #444 from Saboleee/staging

This PR implements comprehensive observability and reliability enhancements for the payments and limits services, adding domain event emission

Author: Jambox11

package.json

@@ -29,27 +29,30 @@
     "@nestjs/common": "^11.0.1",
     "@nestjs/config": "^4.0.2",
     "@nestjs/core": "^11.0.1",
+    "@nestjs/event-emitter": "^3.1.0",
     "@nestjs/mapped-types": "*",
     "@nestjs/platform-express": "^11.0.1",
     "@nestjs/terminus": "^11.1.1",
     "@nestjs/throttler": "^6.5.0",
     "@prisma/adapter-pg": "^7.3.0",
     "@prisma/client": "^7.3.0",
+    "@willsoto/nestjs-prometheus": "^6.1.0",
     "axios": "^1.6.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
     "dotenv": "^17.2.3",
     "pg": "^8.17.2",
+    "prom-client": "^15.1.3",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
     "stellar-sdk": "^10.2.0"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.18.0",
-    "@nestjs/swagger": "^8.0.0",
     "@nestjs/cli": "^11.0.0",
     "@nestjs/schematics": "^11.0.0",
+    "@nestjs/swagger": "^8.0.0",
     "@nestjs/testing": "^11.0.1",
     "@types/express": "^5.0.0",
     "@types/jest": "^30.0.0",

src/app.module.ts

@@ -2,7 +2,9 @@ import { Module } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { AppController } from './app.controller';
 import { ConfigModule } from '@nestjs/config';
+import { EventEmitterModule } from '@nestjs/event-emitter';
 import { PrismaModule } from './prisma/prisma.module';
+import { MetricsModule } from './metrics/metrics.module';
 import { AppService } from './app.service';
 import { UsersModule } from './users/users.module';
 import { IdempotentUserModule } from './users/idempotent-user.module';
@@ -30,6 +32,8 @@ import { HealthModule } from './health/health.module';
       isGlobal: true,
       envFilePath: '.env',
     }),
+    EventEmitterModule.forRoot(),
+    MetricsModule,
     PrismaModule,
     AuthModule,
     RateLimitModule,

src/common/utils/retry.spec.ts

@@ -0,0 +1,93 @@
+import { Logger } from '@nestjs/common';
+import { retryWithBackoff, RetryError } from './retry';
+
+describe('retryWithBackoff', () => {
+  let logger: any;
+
+  beforeEach(() => {
+    logger = { debug: jest.fn() };
+  });
+
+  it('should return value on first attempt success', async () => {
+    const fn = jest.fn().mockResolvedValue('success');
+
+    const result = await retryWithBackoff(fn, 3, 100, logger);
+
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should retry and succeed on second attempt', async () => {
+    const fn = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('Network error'))
+      .mockResolvedValueOnce('success');
+
+    const result = await retryWithBackoff(fn, 3, 100, logger);
+
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(logger.debug).toHaveBeenCalledTimes(1);
+  });
+
+  it('should exhausts all retries and throw last error', async () => {
+    const error = new Error('Persistent error');
+    const fn = jest.fn().mockRejectedValue(error);
+
+    await expect(retryWithBackoff(fn, 3, 100, logger)).rejects.toThrow(
+      'Persistent error',
+    );
+
+    expect(fn).toHaveBeenCalledTimes(3);
+    expect(logger.debug).toHaveBeenCalledTimes(2);
+  });
+
+  it('should not retry on 400 client error', async () => {
+    const error = new Error('Bad request');
+    (error as any).status = 400;
+    const fn = jest.fn().mockRejectedValue(error);
+
+    await expect(retryWithBackoff(fn, 3, 100, logger)).rejects.toThrow(
+      'Bad request',
+    );
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not retry on 403 forbidden error', async () => {
+    const error = new Error('Forbidden');
+    (error as any).status = 403;
+    const fn = jest.fn().mockRejectedValue(error);
+
+    await expect(retryWithBackoff(fn, 3, 100, logger)).rejects.toThrow(
+      'Forbidden',
+    );
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should retry on 500 server error', async () => {
+    const error = new Error('Server error');
+    (error as any).status = 500;
+    const fn = jest
+      .fn()
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce('success');
+
+    const result = await retryWithBackoff(fn, 3, 100, logger);
+
+    expect(result).toBe('success');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('should log retry attempts', async () => {
+    const fn = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('Error 1'))
+      .mockResolvedValueOnce('success');
+
+    await retryWithBackoff(fn, 3, 100, logger);
+
+    expect(logger.debug).toHaveBeenCalled();
+  });
+});

src/common/utils/retry.ts

@@ -0,0 +1,56 @@
+import { Logger } from '@nestjs/common';
+
+export class RetryError extends Error {
+  constructor(
+    public readonly lastError: Error,
+    public readonly attemptsMade: number,
+  ) {
+    super(
+      `Retryable operation failed after ${attemptsMade} attempts: ${lastError.message}`,
+    );
+    this.name = 'RetryError';
+  }
+}
+
+function isRetryable(error: any): boolean {
+  if (!error) return false;
+
+  // Don't retry on client errors (4xx)
+  if (error.status && error.status >= 400 && error.status < 500) {
+    return false;
+  }
+
+  // Retry on network errors, timeouts, server errors (5xx), or other thrown exceptions
+  return true;
+}
+
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxAttempts: number = 3,
+  baseDelayMs: number = 100,
+  logger?: Logger,
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt === maxAttempts || !isRetryable(error)) {
+        throw error;
+      }
+
+      const delay = baseDelayMs * Math.pow(2, attempt - 1);
+      logger?.debug(
+        `Retry attempt ${attempt} failed: ${lastError.message}. Waiting ${delay}ms before retry.`,
+      );
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  // This should never be reached, but for type safety
+  throw lastError || new Error('Unknown retry error');
+}

src/limits/events/limit-exceeded.event.ts

@@ -0,0 +1,9 @@
+export class LimitExceededEvent {
+  constructor(
+    public readonly userId: string,
+    public readonly limitType: string,
+    public readonly limit: number,
+    public readonly attempted: number,
+    public readonly timestamp: Date,
+  ) {}
+}

src/limits/events/limit-updated.event.ts

@@ -0,0 +1,9 @@
+export class LimitUpdatedEvent {
+  constructor(
+    public readonly walletId: string,
+    public readonly limitType: string,
+    public readonly oldValue: number | null,
+    public readonly newValue: number,
+    public readonly timestamp: Date,
+  ) {}
+}

src/limits/limits.controller.spec.ts

@@ -36,7 +36,6 @@ describe('LimitsController', () => {
     }).compile();
 
     controller = module.get<LimitsController>(LimitsController);
-    service = module.get(LimitsService);
   });
 
   it('should be defined', () => {
@@ -74,5 +73,20 @@ describe('LimitsController', () => {
         expect(metadata).toBeDefined();
       });
     });
+
+    it('should have @ApiOperation on all routes', () => {
+      const routes = ['setLimits', 'getLimits', 'removeLimits'];
+
+      routes.forEach((route) => {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          LimitsController.prototype,
+          route,
+        );
+        expect(descriptor).toBeDefined();
+
+        const metadata = Reflect.getMetadata('swagger/apiOperation', descriptor.value);
+        expect(metadata).toBeDefined();
+      });
+    });
   });
 });

src/limits/limits.controller.ts

@@ -23,8 +23,11 @@ import { SetLimitsDto } from './dto/set-limits.dto';
 export class LimitsController {
   constructor(private readonly limitsService: LimitsService) {}
 
-  @ApiOperation({ summary: 'Set wallet transaction and daily limits' })
-  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiOperation({
+    summary: 'Set wallet transaction and daily limits',
+    description: 'Set or update daily and per-transaction limits for a wallet. Requires API key authentication. Emits limit.updated events for each limit changed.',
+  })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID (UUID)' })
   @ApiBody({
     type: SetLimitsDto,
     examples: {
@@ -38,7 +41,7 @@ export class LimitsController {
   })
   @ApiResponse({
     status: 201,
-    description: 'Limits set successfully',
+    description: 'Limits set successfully. Emits limit.updated events.',
     example: {
       walletId: '123e4567-e89b-12d3-a456-426614174000',
       dailyLimit: 5000,
@@ -78,8 +81,11 @@ export class LimitsController {
     );
   }
 
-  @ApiOperation({ summary: 'Get wallet limits' })
-  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiOperation({
+    summary: 'Get wallet limits',
+    description: 'Retrieve current daily and per-transaction limits for a wallet. Requires API key authentication.',
+  })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID (UUID)' })
   @ApiResponse({
     status: 200,
     description: 'Wallet limits retrieved successfully',
@@ -101,13 +107,28 @@ export class LimitsController {
       error: 'Not Found',
     },
   })
+  @ApiResponse({
+    status: 422,
+    description: 'Limit exceeded - transaction blocked',
+    example: {
+      statusCode: 422,
+      timestamp: '2024-06-24T12:34:56.789Z',
+      path: '/payments',
+      message: 'Per-transaction limit exceeded. Limit: 1000',
+      error: 'Unprocessable Entity',
+      errorCode: 'LIMIT_PER_TX_EXCEEDED',
+    },
+  })
   @Get()
   getLimits(@Param('walletId') walletId: string) {
     return this.limitsService.getLimits(walletId);
   }
 
-  @ApiOperation({ summary: 'Remove wallet limits' })
-  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiOperation({
+    summary: 'Remove wallet limits',
+    description: 'Delete all limits for a wallet. Requires API key authentication.',
+  })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID (UUID)' })
   @ApiResponse({
     status: 204,
     description: 'Limits removed successfully',