feat: queue depth monitoring, auth docs, request logging, migration CI

.github/workflows/ci.yml

@@ -30,3 +30,35 @@ jobs:
 
       - name: Unit tests
         run: npx jest --ci
+
+  migrate:
+    name: Migration test
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: parashield_test
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Run database migrations
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/parashield_test
+        run: npx prisma migrate deploy

src/app.module.ts

@@ -13,6 +13,7 @@ import { AuthModule }    from './auth/auth.module';
 import { HealthModule }  from './health/health.module';
 import { RedisModule }   from './redis/redis.module';
 import { VersioningInterceptor } from './common/interceptors/versioning.interceptor';
+import { LoggingInterceptor } from './common/interceptors/logging.interceptor';
 import { WebhooksModule } from './common/webhooks/webhooks.module';
 
 /**
@@ -100,6 +101,10 @@ function validateConfig(config: Record<string, unknown>) {
       provide: APP_GUARD,
       useClass: ThrottlerGuard,
     },
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: LoggingInterceptor,
+    },
     {
       provide: APP_INTERCEPTOR,
       useClass: VersioningInterceptor,

src/auth/auth.controller.ts

@@ -34,9 +34,16 @@ export class AuthController {
    */
   @Get('challenge')
   @Throttle(AUTH_THROTTLE)
-  @ApiOperation({ summary: 'Obtain a server-issued nonce before login' })
+  @ApiOperation({
+    summary: 'Obtain a server-issued nonce before login',
+    description:
+      'Step 1 of 2 in the wallet-based auth flow. Returns a cryptographically random ' +
+      'nonce tied to the given wallet address. The nonce expires in 5 minutes and must ' +
+      'be signed by the wallet private key, then submitted to POST /auth/login.',
+  })
   @ApiResponse({ status: 200, description: 'Returns the challenge nonce' })
   @ApiResponse({ status: 400, description: 'Invalid wallet address' })
+  @ApiResponse({ status: 429, description: 'Too many requests — rate limit exceeded (10 req / 60 s)' })
   async getChallenge(@Query('wallet') wallet: string) {
     if (!wallet || !/^G[A-Z2-7]{55}$/.test(wallet)) {
       throw new UnauthorizedException('Invalid or missing Stellar wallet address');
@@ -73,10 +80,18 @@ export class AuthController {
   @Post('login')
   @HttpCode(HttpStatus.OK)
   @Throttle(AUTH_THROTTLE)
-  @ApiOperation({ summary: 'Authenticate with a Stellar wallet signature and receive a JWT' })
+  @ApiOperation({
+    summary: 'Authenticate with a Stellar wallet signature and receive a JWT',
+    description:
+      'Step 2 of 2 in the wallet-based auth flow. Sign the nonce obtained from ' +
+      'GET /auth/challenge with your Stellar private key (Ed25519), base64-encode the ' +
+      'signature, and submit it here. On success, returns a signed JWT to use as ' +
+      'Bearer token in subsequent authenticated requests.',
+  })
   @ApiBody({ type: WalletLoginDto })
   @ApiResponse({ status: 200, description: 'Returns a JWT token for the authenticated wallet' })
   @ApiResponse({ status: 401, description: 'Invalid or missing wallet signature' })
+  @ApiResponse({ status: 429, description: 'Too many requests — rate limit exceeded (10 req / 60 s)' })
   async login(@Body() dto: WalletLoginDto) {
     const { walletAddress, signature, message } = dto;
 

src/health/health.controller.ts

@@ -85,12 +85,24 @@ export class HealthController {
     // stop processing without any observable API-layer error. A PING here
     // surfaces the failure in the health endpoint so load balancers and
     // on-call alerts can react before users notice stuck claims or policies.
+    let queueDepths: Record<string, number> | undefined;
     try {
       const pong = await this.redis.ping();
       if (pong !== 'PONG') {
         queueStatus = 'error';
         queueError  = `Redis PING returned unexpected response: ${pong}`;
         this.logger.error(`Health check: ${queueError}`);
+      } else {
+        // #421 — Report waiting job counts for known Bull queues so ops can
+        // detect build-up before processing latency becomes user-visible.
+        const queueNames = (this.config.get<string>('HEALTH_QUEUE_NAMES') ?? 'claims,oracle')
+          .split(',')
+          .map(n => n.trim())
+          .filter(Boolean);
+        const depths = await Promise.all(
+          queueNames.map(async (name) => [name, await this.redis.llen(`bull:${name}:wait`)] as [string, number]),
+        );
+        queueDepths = Object.fromEntries(depths);
       }
     } catch (err) {
       queueStatus = 'error';
@@ -116,6 +128,7 @@ export class HealthController {
         },
         queue: {
           status: queueStatus,
+          ...(queueDepths !== undefined ? { depth: queueDepths } : {}),
           ...(queueError ? { error: queueError } : {}),
         },
       },