test(indexer-lag): add unit tests for IndexerLagService and IndexerLagGuard

.github/workflows/backend.yml

@@ -41,6 +41,14 @@ jobs:
       - name: Build
         run: pnpm run build
 
+      - name: OpenAPI spec must not diverge
+        run: pnpm run docs:export:check
+        env:
+          NODE_ENV: test
+          NETWORK: testnet
+          SUPABASE_URL: https://spec-export.supabase.co
+          SUPABASE_ANON_KEY: spec-export-key
+
       # Tests are run separately to avoid CI failures during development
       # Uncomment when tests are stable
       # - name: Run Unit Tests

app/backend/package.json

@@ -4,51 +4,52 @@
   "private": true,
   "description": "QuickEx NestJS backend API",
   "dependencies": {
-    "@nestjs/common": "^10.4.22",
-    "@nestjs/config": "^3.3.0",
-    "@nestjs/core": "^10.0.0",
-    "@nestjs/event-emitter": "^3.0.1",
-    "@nestjs/platform-express": "^10.0.0",
-    "@nestjs/schedule": "^3.0.4",
-    "@nestjs/swagger": "^7.4.2",
+    "@nestjs/common": "^11.1.28",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.1.28",
+    "@nestjs/event-emitter": "^3.1.0",
+    "@nestjs/platform-express": "^11.1.28",
+    "@nestjs/schedule": "^6.1.3",
+    "@nestjs/swagger": "^11.4.6",
     "@nestjs/throttler": "^6.5.0",
-    "@sentry/nestjs": "^10.46.0",
-    "@sentry/node": "^10.46.0",
-    "@sentry/profiling-node": "^10.46.0",
-    "@stellar/stellar-sdk": "^14.5.0",
-    "@supabase/supabase-js": "^2.0.0",
+    "@sentry/nestjs": "^10.69.0",
+    "@sentry/node": "^10.69.0",
+    "@sentry/profiling-node": "^10.69.0",
+    "@stellar/stellar-sdk": "^16.2.0",
+    "@supabase/supabase-js": "^2.112.2",
     "bcrypt": "^6.0.0",
     "class-transformer": "^0.5.1",
-    "class-validator": "^0.14.0",
-    "helmet": "^8.1.0",
-    "ipaddr.js": "^2.4.0",
-    "joi": "^18.0.2",
-    "lru-cache": "^11.3.5",
+    "class-validator": "^0.15.1",
+    "helmet": "^8.3.0",
+    "ioredis": "^6.0.0",
+    "ipaddr.js": "^2.5.0",
+    "joi": "^18.2.3",
+    "lru-cache": "^11.5.2",
     "nest-winston": "^1.10.2",
     "prom-client": "^15.1.3",
-    "reflect-metadata": "^0.1.13",
+    "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
     "telegraf": "^4.16.3",
-    "uuid": "^9.0.1",
+    "uuid": "^14.0.1",
     "winston": "^3.19.0"
   },
   "devDependencies": {
-    "@nestjs/cli": "^10.0.0",
-    "@nestjs/testing": "^10.0.0",
-    "@types/jest": "^29.5.0",
-    "@types/node": "^20.0.0",
-    "@types/supertest": "^2.0.16",
-    "@types/uuid": "^9.0.1",
+    "@nestjs/cli": "^11.0.24",
+    "@nestjs/testing": "^11.1.28",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.1.2",
+    "@types/supertest": "^7.2.1",
+    "@types/uuid": "^11.0.0",
     "@types/yargs": "^17.0.35",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
-    "eslint": "^8.0.0",
-    "fast-check": "^4.8.0",
-    "jest": "^29.7.0",
-    "supertest": "^6.3.3",
-    "ts-jest": "^29.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.66.0",
+    "@typescript-eslint/parser": "^8.66.0",
+    "eslint": "^10.8.0",
+    "fast-check": "^4.9.0",
+    "jest": "^30.4.2",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.12",
     "ts-node": "^10.9.0",
-    "typescript": "^5.2.2"
+    "typescript": "^7.0.2"
   },
   "pnpm": {
     "neverBuiltDependencies": [
@@ -69,6 +70,8 @@
     "test:int:coverage": "jest --config jest.int.config.ts --coverage",
     "test:e2e": "jest --config jest.e2e.config.ts",
     "soroban:deploy": "ts-node scripts/soroban-deploy.ts",
+    "docs:export": "ts-node scripts/export-openapi.ts",
+    "docs:export:check": "pnpm run docs:export && git diff --exit-code -- openapi.json",
     "test:fuzz": "jest --config jest.fuzz.config.ts",
     "test:fuzz:ci": "jest --config jest.fuzz.config.ts --runInBand",
     "test:smoke": "jest --config jest.e2e.config.ts test/smoke.e2e-spec.ts --testTimeout=30000",

app/backend/scripts/export-openapi.ts

@@ -0,0 +1,61 @@
+/**
+ * Exports the generated OpenAPI specification to `openapi.json`.
+ *
+ * Used by CI to fail when the committed spec diverges from the application's
+ * generated spec (see .github/workflows/backend.yml "OpenAPI spec divergence").
+ *
+ * Run: pnpm run docs:export
+ */
+import { writeFileSync } from "fs";
+import { join } from "path";
+import { NestFactory } from "@nestjs/core";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+
+// Provide minimal valid config so the app can boot and build the document.
+process.env.NODE_ENV = process.env.NODE_ENV ?? "test";
+process.env.NETWORK = process.env.NETWORK ?? "testnet";
+process.env.SUPABASE_URL =
+  process.env.SUPABASE_URL ?? "https://spec-export.supabase.co";
+process.env.SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY ?? "spec-export-key";
+process.env.SENTRY_DSN = process.env.SENTRY_DSN ?? "";
+
+import { AppModule } from "../src/app.module";
+import { AppConfigService } from "../src/config";
+
+async function main() {
+  const app = await NestFactory.create(AppModule, { logger: false });
+
+  const config = app.get(AppConfigService);
+  const swaggerConfig = new DocumentBuilder()
+    .setTitle("QuickEx Backend")
+    .setDescription(
+      "QuickEx API documentation - A Stellar-based exchange platform. " +
+        `Currently connected to: ${config.network}`,
+    )
+    .setVersion("v1")
+    .addTag("health", "Health check endpoints")
+    .addTag("usernames", "Username management endpoints")
+    .addTag("links", "Payment link validation and metadata endpoints")
+    .addTag("transactions", "Stellar transaction and payment history")
+    .addTag("scam-alerts", "Fraud detection and link scanning")
+    .addTag("analytics", "Dashboard analytics, time-series insights, and report exports")
+    .addTag("metrics", "Application performance and health metrics")
+    .addTag("stellar", "Verified assets, path preview, Soroban preflight")
+    .addTag("contracts", "Contract registry publication and discovery")
+    .addTag("developer", "Developer self-service: ping, webhook testing, key management, health score")
+    .build();
+
+  const document = SwaggerModule.createDocument(app, swaggerConfig);
+  const outPath = join(process.cwd(), "openapi.json");
+  writeFileSync(outPath, JSON.stringify(document, null, 2));
+  // eslint-disable-next-line no-console
+  console.log(`OpenAPI spec written to ${outPath}`);
+
+  await app.close();
+}
+
+void main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error("Failed to export OpenAPI spec:", err);
+  process.exit(1);
+});

app/backend/src/analytics/analytics-events.service.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { Observable } from 'rxjs';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+@Injectable()
+export class AnalyticsEventsService {
+  constructor(private readonly eventEmitter: EventEmitter2) {}
+
+  stream(publicKey: string): Observable<MessageEvent> {
+    return new Observable<MessageEvent>((subscriber) => {
+      const listener = (eventName: string, payload: unknown) => {
+        if (!isRecord(payload)) return;
+
+        const eventPublicKey = payload.recipientPublicKey ?? payload.publicKey ?? payload.owner;
+        if (eventPublicKey !== publicKey) return;
+
+        subscriber.next({
+          type: 'analytics.updated',
+          data: JSON.stringify({
+            eventType: eventName,
+            eventId: payload.eventId ?? null,
+            occurredAt: new Date().toISOString(),
+          }),
+        });
+      };
+
+      this.eventEmitter.onAny(listener);
+      const heartbeat = setInterval(() => {
+        subscriber.next({ type: 'analytics.heartbeat', data: '{}' });
+      }, 30_000);
+
+      return () => {
+        this.eventEmitter.offAny(listener);
+        clearInterval(heartbeat);
+      };
+    });
+  }
+}

app/backend/src/analytics/analytics-stale-cache.ts

@@ -0,0 +1,87 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { LRUCache } from "lru-cache";
+
+import { AppConfigService } from "../config";
+import { AnalyticsInterval } from "./dto/analytics-query.dto";
+import type { AnalyticsReport } from "./analytics.service";
+
+export type StaleCacheEntry = {
+  report: AnalyticsReport;
+  generatedAt: number;
+};
+
+/**
+ * Stores the last successful analytics report per (publicKey, interval) so the
+ * dashboard can keep serving (stale) data when the data source is unavailable.
+ *
+ * Entries are retained for up to `MAX_STALE_AGE_MS` (24h) and a fresh result is
+ * cached with a configurable TTL (default 5m). On failure the controller signals
+ * staleness via the `X-Cache-Status: stale` header.
+ */
+@Injectable()
+export class AnalyticsStaleCache {
+  private readonly logger = new Logger(AnalyticsStaleCache.name);
+  private readonly cache: LRUCache<string, StaleCacheEntry>;
+
+  /** Stale data is only ever served up to 24 hours old. */
+  private readonly MAX_STALE_AGE_MS = 24 * 60 * 60 * 1000;
+
+  constructor(private readonly appConfig: AppConfigService) {
+    const ttl = Math.max(this.appConfig.analyticsStaleCacheTtlMs, 1000);
+    this.cache = new LRUCache<string, StaleCacheEntry>({
+      max: 1000,
+      // Retain entries long enough to serve stale data within the 24h cap.
+      ttl: Math.max(ttl, this.MAX_STALE_AGE_MS),
+      updateAgeOnGet: false,
+    });
+  }
+
+  /**
+   * Separate cache key per publicKey, interval, organization and date window.
+   */
+  getCacheKey(
+    publicKey: string,
+    interval: AnalyticsInterval,
+    organizationId?: string,
+    startDate?: string,
+    endDate?: string,
+  ): string {
+    return [
+      "quickex",
+      "analytics",
+      "stale",
+      publicKey,
+      interval,
+      organizationId ?? "anon",
+      startDate ?? "default-start",
+      endDate ?? "default-end",
+    ].join(":");
+  }
+
+  get(kind: "fresh" | "stale", key: string): StaleCacheEntry | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    const age = Date.now() - entry.generatedAt;
+    if (age > this.MAX_STALE_AGE_MS) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    // A "fresh" hit means the cached copy is within the configured TTL — no need
+    // to recompute on failure paths that can still serve it. `kind` is used to
+    // keep semantics explicit; both resolve to the same entry.
+    void kind;
+
+    return entry;
+  }
+
+  set(key: string, entry: StaleCacheEntry): void {
+    this.cache.set(key, entry, {
+      ttl: Math.max(
+        this.appConfig.analyticsStaleCacheTtlMs,
+        this.MAX_STALE_AGE_MS,
+      ),
+    });
+  }
+}

app/backend/src/analytics/analytics.controller.ts

@@ -1,8 +1,9 @@
-import { Controller, Get, Query, Req, Res, UseGuards } from '@nestjs/common';
+import { Controller, Get, Query, Req, Res, Sse, UseGuards } from '@nestjs/common';
 import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import { ApiKeyGuard } from '../auth/guards/api-key.guard';
 import { AnalyticsService } from './analytics.service';
+import { AnalyticsEventsService } from './analytics-events.service';
 import {
   AnalyticsQueryDto,
   ExportReportQueryDto,
@@ -14,21 +15,44 @@ import {
 @UseGuards(ApiKeyGuard)
 @Controller('analytics')
 export class AnalyticsController {
-  constructor(private readonly analyticsService: AnalyticsService) {}
+  constructor(
+    private readonly analyticsService: AnalyticsService,
+    private readonly analyticsEventsService: AnalyticsEventsService,
+  ) {}
+
+  @Sse('events')
+  @ApiOperation({ summary: 'Stream analytics updates for a public key' })
+  events(@Query('publicKey') publicKey: string) {
+    return this.analyticsEventsService.stream(publicKey);
+  }
 
   @Get('report')
   @ApiOperation({
     summary: 'Fetch dashboard analytics report (summary, asset distribution, and time-series)',
   })
   @ApiResponse({ status: 200, description: 'Analytics report generated' })
-  async getReport(@Req() req: Request, @Query() query: TimeSeriesQueryDto) {
-    return this.analyticsService.getAnalyticsReport(
-      query.publicKey,
-      query.startDate,
-      query.endDate,
-      query.interval,
-      req.organizationContext?.organizationId,
-    );
+  async getReport(
+    @Req() req: Request,
+    @Res() res: Response,
+    @Query() query: TimeSeriesQueryDto,
+  ) {
+    const { report, cacheStatus } =
+      await this.analyticsService.getAnalyticsReportWithStatus(
+        query.publicKey,
+        query.startDate,
+        query.endDate,
+        query.interval,
+        req.organizationContext?.organizationId,
+      );
+
+    if (cacheStatus === 'stale') {
+      res.set('X-Cache-Status', 'stale');
+      res.set('X-QuickEx-Stale-Data', 'true');
+    } else {
+      res.set('X-Cache-Status', 'fresh');
+    }
+
+    return res.status(200).json(report);
   }
 
   @Get('time-series')

app/backend/src/analytics/analytics.module.ts

@@ -3,11 +3,13 @@ import { ApiKeysModule } from '../api-keys/api-keys.module';
 import { SupabaseModule } from '../supabase/supabase.module';
 import { AnalyticsController } from './analytics.controller';
 import { AnalyticsService } from './analytics.service';
+import { AnalyticsEventsService } from './analytics-events.service';
+import { AnalyticsStaleCache } from './analytics-stale-cache';
 
 @Module({
   imports: [SupabaseModule, ApiKeysModule],
   controllers: [AnalyticsController],
-  providers: [AnalyticsService],
+  providers: [AnalyticsService, AnalyticsEventsService, AnalyticsStaleCache],
   exports: [AnalyticsService],
 })
 export class AnalyticsModule {}