Merge pull request #612 from autostack-art/feature/stellar-wave-536-539

Add Horizon circuit breaker, login metadata, API versioning, and login smoke test

Author: Jambox11

README.md

@@ -33,6 +33,8 @@ It handles wallet creation, transaction orchestration, fee sponsorship, and on-c
 
 ## API Endpoints
 
+All routes below are served under the `/v1` prefix (e.g. `GET /v1/health`). See [docs/API-VERSIONING.md](docs/API-VERSIONING.md) for the versioning strategy.
+
 ### Health & Monitoring
 
 #### `GET /health`

docs/API-VERSIONING.md

@@ -0,0 +1,50 @@
+# API Versioning Strategy
+
+This document describes how the Mux backend versions its public HTTP API.
+
+## Current approach: URI path versioning
+
+All routes are served under a global `/v1` prefix, applied once in `src/main.ts`:
+
+```ts
+app.setGlobalPrefix('v1');
+```
+
+Individual controllers (e.g. `@Controller('auth')`, `@Controller('wallets')`)
+declare their resource path only; the version prefix is applied globally so
+every route is automatically namespaced (`/v1/auth/authenticate`,
+`/v1/wallets`, etc.). Requests made without the `/v1` prefix return `404 Not
+Found` — there is no unversioned fallback.
+
+## Why URI versioning
+
+- **Explicit and cache-friendly**: the version is visible in the URL, in logs,
+  and in reverse-proxy/CDN routing rules, without relying on a header that
+  intermediaries may strip.
+- **Simple for consumers**: partners and the frontend hard-code a base URL
+  (e.g. `https://api.mux.dev/v1`) rather than needing to set a custom header
+  on every request.
+- **Matches existing NestJS conventions** in this repo — a single
+  `setGlobalPrefix` call versions every controller without per-route
+  decorators.
+
+## Introducing a breaking change (`/v2`)
+
+When a change is not backwards compatible:
+
+1. Add the new/changed controllers under a `v2` path (NestJS's built-in
+   [URI versioning](https://docs.nestjs.com/techniques/versioning) via
+   `app.enableVersioning({ type: VersioningType.URI })` can be adopted at that
+   point to run `v1` and `v2` controllers side by side).
+2. Keep `/v1` serving the previous behavior until consumers have migrated.
+3. Announce the deprecation window for `/v1` in release notes before removal.
+
+## Non-breaking changes
+
+Additive changes (new endpoints, new optional request/response fields) ship
+directly under the current `/v1` prefix — no new version is required.
+
+## Health and monitoring endpoints
+
+`/v1/health` and `/v1/ready` follow the same prefix as every other route, so
+uptime checks and readiness probes must be configured with the `/v1` path.

prisma/migrations/20260724000000_add_user_last_login_metadata/migration.sql

@@ -0,0 +1,8 @@
+-- Migration: add lastLoginIp and lastLoginUserAgent to User
+--
+-- Captures the IP address and User-Agent seen on the user's most recent
+-- successful authentication, alongside the existing lastLoginAt timestamp.
+-- Both columns are nullable so existing rows require no backfill.
+
+ALTER TABLE "User" ADD COLUMN "lastLoginIp" TEXT;
+ALTER TABLE "User" ADD COLUMN "lastLoginUserAgent" TEXT;

prisma/schema.prisma

@@ -102,6 +102,12 @@ model User {
   /// Last login timestamp
   lastLoginAt DateTime?
 
+  /// IP address captured on the most recent successful login
+  lastLoginIp String?
+
+  /// User-Agent header captured on the most recent successful login
+  lastLoginUserAgent String?
+
   /// Operational metadata
   createdAt DateTime  @default(now())
   updatedAt DateTime  @updatedAt

src/auth/auth-orchestrator.controller.ts

@@ -7,6 +7,7 @@ import {
   Get,
   Param,
   Headers,
+  Req,
   Res,
   UseGuards,
   Query,
@@ -20,7 +21,7 @@ import {
   ApiQuery,
   ApiHeader,
 } from '@nestjs/swagger';
-import type { Response } from 'express';
+import type { Request, Response } from 'express';
 import {
   AuthOrchestrator,
   type AuthenticationRequest,
@@ -174,11 +175,14 @@ export class AuthOrchestratorController {
   async authenticate(
     @Body() request: AuthenticationRequest,
     @Headers('idempotency-key') idempotencyKey: string | undefined,
+    @Req() httpRequest: Request,
     @Res() response: Response,
   ): Promise<void> {
     const requestWithIdempotency: AuthenticationRequestWithIdempotency = {
       ...request,
       idempotencyKey,
+      ipAddress: httpRequest.ip,
+      userAgent: httpRequest.headers['user-agent'],
     };
 
     const result = await this.authOrchestrator.handleAuthentication(

src/auth/auth-orchestrator.service.ts

@@ -28,6 +28,8 @@ export interface AuthenticationRequest {
   displayName?: string;
   authProvider?: string;
   network?: WalletNetwork;
+  ipAddress?: string;
+  userAgent?: string;
 }
 
 export class AuthPayloadValidator {
@@ -365,6 +367,8 @@ export class AuthOrchestrator {
       email: request.email,
       displayName: request.displayName,
       authProvider: request.authProvider || 'UNKNOWN',
+      lastLoginIp: request.ipAddress,
+      lastLoginUserAgent: request.userAgent,
     };
 
     return retryWithBackoff(() =>

src/balance-indexer/stellar-horizon.service.ts

@@ -1,8 +1,16 @@
-import { Injectable, Logger } from '@nestjs/common';
+import {
+  Injectable,
+  Logger,
+  ServiceUnavailableException,
+} from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Server } from 'stellar-sdk';
 import { Asset, AssetType, BalanceUpdate } from './domain/balance.model';
 import { RequestContextService } from '../common/request-context/request-context.service';
+import {
+  CircuitBreaker,
+  CircuitOpenError,
+} from '../common/utils/circuit-breaker';
 
 export interface HorizonBalance {
   asset_type: string;
@@ -19,6 +27,7 @@ export class StellarHorizonService {
   private readonly retryBackoffMs: number;
   private readonly retryJitterMs: number;
   private readonly server: Server;
+  private readonly circuitBreaker: CircuitBreaker;
 
   constructor(
     private readonly configService: ConfigService,
@@ -44,29 +53,62 @@ export class StellarHorizonService {
 
     this.logger.log(`Initialized Stellar Horizon client: ${this.horizonUrl}`);
     this.server = new Server(horizonUrl, { allowHttp: false });
+    this.circuitBreaker = new CircuitBreaker('stellar-horizon', {
+      failureThreshold: this.configService.get<number>(
+        'HORIZON_CIRCUIT_FAILURE_THRESHOLD',
+        5,
+      ),
+      resetTimeoutMs: this.configService.get<number>(
+        'HORIZON_CIRCUIT_RESET_TIMEOUT_MS',
+        30000,
+      ),
+    });
     this.logger.log(`Initialized Stellar Horizon client: ${horizonUrl}`);
   }
 
   /**
-   * Helper to execute server actions with retry & backoff
+   * Helper to execute server actions with retry & backoff, guarded by a
+   * circuit breaker so a degraded Horizon backend fails fast instead of
+   * queuing up retries (and their backoff delays) on every caller.
    */
   private async executeWithRetry<T>(
     operation: () => Promise<T>,
     opName: string,
   ): Promise<T> {
+    const requestId = this.requestContext.getRequestId();
+    const logPrefix = requestId ? `[${requestId}] ` : '';
+
+    try {
+      this.circuitBreaker.assertClosed();
+    } catch (error) {
+      if (error instanceof CircuitOpenError) {
+        this.logger.warn(
+          `${logPrefix}Horizon API ${opName} short-circuited: ${error.message}`,
+        );
+        throw new ServiceUnavailableException(
+          'Stellar Horizon is currently unavailable. Please try again shortly.',
+        );
+      }
+      throw error;
+    }
+
     const maxRetries = this.configService.get<number>('HORIZON_MAX_RETRIES', 3);
     let attempt = 0;
     while (true) {
       try {
-        return await operation();
+        const result = await operation();
+        this.circuitBreaker.recordSuccess();
+        return result;
       } catch (error) {
         attempt++;
         if (attempt > maxRetries) {
+          this.circuitBreaker.recordFailure();
           throw error;
         }
-        const delay = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 15000);
-        const requestId = this.requestContext.getRequestId();
-        const logPrefix = requestId ? `[${requestId}] ` : '';
+        const delay = Math.min(
+          1000 * Math.pow(2, attempt) + Math.random() * 1000,
+          15000,
+        );
         this.logger.warn(
           `${logPrefix}Horizon API ${opName} failed (attempt ${attempt}/${maxRetries}). Retrying in ${Math.round(delay)}ms. Error: ${error.message}`,
         );

src/common/utils/circuit-breaker.ts

@@ -0,0 +1,76 @@
+export enum CircuitState {
+  CLOSED = 'CLOSED',
+  OPEN = 'OPEN',
+  HALF_OPEN = 'HALF_OPEN',
+}
+
+export class CircuitOpenError extends Error {
+  constructor(name: string) {
+    super(`Circuit breaker "${name}" is open — failing fast`);
+    this.name = 'CircuitOpenError';
+  }
+}
+
+export interface CircuitBreakerOptions {
+  /** Consecutive failures required to trip the circuit from CLOSED to OPEN. */
+  failureThreshold?: number;
+  /** How long the circuit stays OPEN before allowing a single HALF_OPEN trial call. */
+  resetTimeoutMs?: number;
+}
+
+/**
+ * Minimal in-memory circuit breaker (no external dependency).
+ *
+ * CLOSED: calls pass through; failures are counted, threshold trips to OPEN.
+ * OPEN: calls fail fast with CircuitOpenError until resetTimeoutMs elapses.
+ * HALF_OPEN: a single trial call is allowed through; success closes the
+ * circuit, failure reopens it and resets the cooldown timer.
+ */
+export class CircuitBreaker {
+  private state: CircuitState = CircuitState.CLOSED;
+  private consecutiveFailures = 0;
+  private openedAt = 0;
+  private readonly failureThreshold: number;
+  private readonly resetTimeoutMs: number;
+
+  constructor(
+    private readonly name: string,
+    options: CircuitBreakerOptions = {},
+  ) {
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeoutMs = options.resetTimeoutMs ?? 30000;
+  }
+
+  getState(): CircuitState {
+    if (
+      this.state === CircuitState.OPEN &&
+      Date.now() - this.openedAt >= this.resetTimeoutMs
+    ) {
+      this.state = CircuitState.HALF_OPEN;
+    }
+    return this.state;
+  }
+
+  /** Throws CircuitOpenError if the call should be short-circuited. */
+  assertClosed(): void {
+    if (this.getState() === CircuitState.OPEN) {
+      throw new CircuitOpenError(this.name);
+    }
+  }
+
+  recordSuccess(): void {
+    this.consecutiveFailures = 0;
+    this.state = CircuitState.CLOSED;
+  }
+
+  recordFailure(): void {
+    this.consecutiveFailures++;
+    if (
+      this.state === CircuitState.HALF_OPEN ||
+      this.consecutiveFailures >= this.failureThreshold
+    ) {
+      this.state = CircuitState.OPEN;
+      this.openedAt = Date.now();
+    }
+  }
+}

src/main.ts

@@ -14,6 +14,10 @@ async function bootstrap() {
   // Attach request logging middleware early in the pipeline
   app.use(requestLogger as any);
 
+  // All routes are served under /v1. See docs/API-VERSIONING.md for the
+  // versioning strategy and how future breaking changes will be introduced.
+  app.setGlobalPrefix('v1');
+
   // Validate incoming requests for DTOs globally
   app.useGlobalPipes(
     new ValidationPipe({

src/users/idempotent-user.service.ts

@@ -13,6 +13,8 @@ export interface FindOrCreateUserRequest {
   email?: string;
   displayName?: string;
   authProvider?: string;
+  lastLoginIp?: string;
+  lastLoginUserAgent?: string;
 }
 
 export interface User {
@@ -23,6 +25,8 @@ export interface User {
   status?: UserStatus;
   authProvider: string;
   lastLoginAt?: Date;
+  lastLoginIp?: string;
+  lastLoginUserAgent?: string;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -66,7 +70,14 @@ export class IdempotentUserService {
   async findOrCreateUser(
     request: FindOrCreateUserRequest,
   ): Promise<FindOrCreateUserResult> {
-    const { authId, email, displayName, authProvider = 'UNKNOWN' } = request;
+    const {
+      authId,
+      email,
+      displayName,
+      authProvider = 'UNKNOWN',
+      lastLoginIp,
+      lastLoginUserAgent,
+    } = request;
 
     this.logger.log(`Looking up user with authId: ${authId}`);
 
@@ -80,7 +91,11 @@ export class IdempotentUserService {
 
         const updatedUser = await this.prisma.user.update({
           where: { id: existingUser.id },
-          data: { lastLoginAt: new Date() },
+          data: {
+            lastLoginAt: new Date(),
+            lastLoginIp,
+            lastLoginUserAgent,
+          },
         });
 
         this.logger.log(
@@ -100,6 +115,8 @@ export class IdempotentUserService {
           displayName,
           authProvider,
           lastLoginAt: new Date(),
+          lastLoginIp,
+          lastLoginUserAgent,
           status: 'ACTIVE',
         },
       });
@@ -132,7 +149,11 @@ export class IdempotentUserService {
         if (retryUser) {
           const updatedRetryUser = await this.prisma.user.update({
             where: { id: retryUser.id },
-            data: { lastLoginAt: new Date() },
+            data: {
+              lastLoginAt: new Date(),
+              lastLoginIp,
+              lastLoginUserAgent,
+            },
           });
 
           return {
@@ -247,6 +268,8 @@ export class IdempotentUserService {
       status: prismaUser.status,
       authProvider: prismaUser.authProvider,
       lastLoginAt: prismaUser.lastLoginAt,
+      lastLoginIp: prismaUser.lastLoginIp,
+      lastLoginUserAgent: prismaUser.lastLoginUserAgent,
       createdAt: prismaUser.createdAt,
       updatedAt: prismaUser.updatedAt,
     };