fix(api): serve cached stats when Hypixel fails

apps/api/src/guild/guild.controller.ts

@@ -11,6 +11,7 @@ import {
   ApiNotFoundResponse,
   ApiOkResponse,
   ApiOperation,
+  ApiServiceUnavailableResponse,
   ApiTags,
 } from "@nestjs/swagger";
 import { Auth } from "#auth";
@@ -19,6 +20,7 @@ import {
   ErrorResponse,
   GetGuildResponse,
   GuildNotFoundException,
+  HypixelUnavailableException,
   PlayerNotFoundException,
 } from "@statsify/api-client";
 import { GuildDto } from "#dtos";
@@ -34,14 +36,16 @@ export class GuildController {
   @ApiBadRequestResponse({ type: ErrorResponse })
   @ApiNotFoundResponse({ type: PlayerNotFoundException })
   @ApiNotFoundResponse({ type: GuildNotFoundException })
+  @ApiServiceUnavailableResponse({ type: HypixelUnavailableException })
   @Get()
   @Auth({ weight: 120 })
   public async getGuild(@Query() { guild: tag, type, cache }: GuildDto) {
-    const guild = await this.guildService.get(tag, type, cache);
+    const { guild, hypixelUnavailable } = await this.guildService.get(tag, type, cache);
 
     return {
       success: !!guild,
       guild,
+      hypixelUnavailable,
     };
   }
 }

apps/api/src/guild/guild.service.ts

@@ -17,7 +17,7 @@ import { GuildLeaderboardService } from "./leaderboards/guild-leaderboard.servic
 import { HypixelService } from "#hypixel";
 import { InjectModel } from "@m8a/nestjs-typegoose";
 import { InjectRedis } from "#redis";
-import { Injectable, ServiceUnavailableException } from "@nestjs/common";
+import { Injectable } from "@nestjs/common";
 import { Logger } from "@statsify/logger";
 import { PlayerService } from "#player";
 import { Redis } from "ioredis";
@@ -43,18 +43,15 @@ export class GuildService {
     inputtedTag: string,
     type: GuildQuery,
     cache: CacheLevel
-  ): Promise<Guild | null> {
+  ): Promise<{ guild: Guild; hypixelUnavailable: boolean }> {
     let [cachedGuild, tag, displayName] = await this.getCachedGuild(inputtedTag, type);
 
     // A player's saved guild id isn't cleared when they leave
     const listsPlayer =
       type !== GuildQuery.PLAYER || cachedGuild?.members.some((member) => member.uuid === tag);
 
     if (cachedGuild && listsPlayer && this.hypixelService.shouldCache(cachedGuild.expiresAt, cache)) {
-      return {
-        ...deserialize(Guild, flatten(cachedGuild)),
-        cached: true,
-      };
+      return this.fromCache(cachedGuild, false);
     }
 
     if (
@@ -73,15 +70,9 @@ export class GuildService {
         tag,
         type.toLowerCase() as Lowercase<GuildQuery>
       );
-    } catch {
-      if (cachedGuild && listsPlayer) {
-        return {
-          ...deserialize(Guild, flatten(cachedGuild)),
-          cached: true,
-        };
-      }
-
-      throw new ServiceUnavailableException();
+    } catch (error) {
+      if (cachedGuild && listsPlayer) return this.fromCache(cachedGuild, true);
+      throw error;
     }
 
     if (!guild) {
@@ -179,7 +170,14 @@ export class GuildService {
 
     await this.guildLeaderboardService.addLeaderboards(Guild, serializedGuild, "id");
 
-    return deserialize(Guild, flatGuild);
+    return { guild: deserialize(Guild, flatGuild), hypixelUnavailable: false };
+  }
+
+  private fromCache(cachedGuild: Guild, hypixelUnavailable: boolean) {
+    return {
+      guild: { ...deserialize(Guild, flatten(cachedGuild)), cached: true },
+      hypixelUnavailable,
+    };
   }
 
   private async getCachedGuild(

apps/api/src/hypixel/hypixel.service.ts

@@ -7,7 +7,7 @@
  */
 
 import * as Sentry from "@sentry/node";
-import { CacheLevel } from "@statsify/api-client";
+import { CacheLevel, HypixelUnavailableException } from "@statsify/api-client";
 import {
   GameCounts,
   Guild,
@@ -43,33 +43,19 @@ export class HypixelService {
           if (data.player) return new Player(data.player);
           return null;
         }),
-        catchError((err) => {
-          this.logger.error(err);
-          return of(null);
-        })
+        catchError((err) => this.handleFailure(err, null))
       )
     );
   }
 
-  /**
-   * Resolves to null when Hypixel says there is no guild or rejects the input.
-   * Other failures reject, so callers don't mistake an outage for a missing guild.
-   */
   public getGuild(tag: string, type: "name" | "id" | "player") {
     return lastValueFrom(
       this.request<APIData>("/guild", { [type]: tag }).pipe(
         map((data) => {
           if (data.guild) return new Guild(data.guild);
           return null;
         }),
-        catchError((err) => {
-          this.logger.error(err);
-
-          const status = err.cause?.response?.status;
-          if (status === 400 || status === 422) return of(null);
-
-          return throwError(() => err);
-        })
+        catchError((err) => this.handleFailure(err, null))
       )
     );
   }
@@ -81,10 +67,7 @@ export class HypixelService {
           if (data.games) return data.games.map((game: APIData) => new RecentGame(game));
           return [];
         }),
-        catchError((err) => {
-          this.logger.error(err);
-          return of([]);
-        })
+        catchError((err) => this.handleFailure(err, []))
       )
     );
   }
@@ -96,10 +79,7 @@ export class HypixelService {
           if (data.session) return new Status(data.session);
           return null;
         }),
-        catchError((err) => {
-          this.logger.error(err);
-          return of(null);
-        })
+        catchError((err) => this.handleFailure(err, null))
       )
     );
   }
@@ -149,6 +129,16 @@ export class HypixelService {
     return this.resources.get(resource);
   }
 
+  private handleFailure<T>(err: any, notFound: T): Observable<T> {
+    this.logger.error(err);
+
+    // Hypixel rejecting the input means there is nothing to find
+    const status = err.cause?.response?.status;
+    if (status === 400 || status === 422) return of(notFound);
+
+    return throwError(() => new HypixelUnavailableException());
+  }
+
   private request<T>(url: string, params?: Record<string, unknown>): Observable<T> {
     const transaction = Sentry.getCurrentHub().getScope()?.getTransaction();
 

apps/api/src/player/player.controller.ts

@@ -11,6 +11,7 @@ import {
   ApiNotFoundResponse,
   ApiOkResponse,
   ApiOperation,
+  ApiServiceUnavailableResponse,
   ApiTags,
 } from "@nestjs/swagger";
 import { Auth, AuthRole } from "#auth";
@@ -26,6 +27,7 @@ import {
   ErrorResponse,
   GetPlayerResponse,
   GetStatusResponse,
+  HypixelUnavailableException,
   PlayerNotFoundException,
   StatusNotFoundException,
 } from "@statsify/api-client";
@@ -41,16 +43,18 @@ export class PlayerController {
   @ApiOkResponse({ type: GetPlayerResponse })
   @ApiBadRequestResponse({ type: ErrorResponse })
   @ApiNotFoundResponse({ type: PlayerNotFoundException })
+  @ApiServiceUnavailableResponse({ type: HypixelUnavailableException })
   @Auth()
   @Get()
   public async getPlayer(@Query() { player: tag, cache }: CachedPlayerDto) {
-    const player = await this.playerService.get(tag, cache);
+    const { player, hypixelError } = await this.playerService.getWithFallback(tag, cache);
 
     if (!player) throw new PlayerNotFoundException();
 
     return {
       success: !!player,
       player,
+      hypixelUnavailable: Boolean(hypixelError),
     };
   }
 
@@ -86,6 +90,7 @@ export class PlayerController {
   @ApiBadRequestResponse({ type: ErrorResponse })
   @ApiNotFoundResponse({ type: StatusNotFoundException })
   @ApiNotFoundResponse({ type: PlayerNotFoundException })
+  @ApiServiceUnavailableResponse({ type: HypixelUnavailableException })
   @Auth({ weight: 2 })
   @Get("/status")
   public async getStatus(@Query() { player: tag }: PlayerDto) {

apps/api/src/player/player.service.ts

@@ -12,7 +12,11 @@ import {
   type Flatten,
   flatten,
 } from "@statsify/util";
-import { CacheLevel, StatusNotFoundException } from "@statsify/api-client";
+import {
+  CacheLevel,
+  HypixelUnavailableException,
+  StatusNotFoundException,
+} from "@statsify/api-client";
 import { HypixelService } from "#hypixel";
 import {
   Inject,
@@ -31,6 +35,12 @@ import type { ReturnModelType } from "@typegoose/typegoose";
 
 type PlayerModel = ReturnModelType<typeof Player>;
 
+export interface PlayerLookup {
+  player: Player | null;
+  /** Set when Hypixel failed and `player` is the cached copy */
+  hypixelError?: HypixelUnavailableException;
+}
+
 @Injectable()
 export class PlayerService {
   public constructor(
@@ -52,6 +62,18 @@ export class PlayerService {
     cacheLevel: CacheLevel,
     selector?: Record<string, boolean>
   ): Promise<Player | null> {
+    const { player } = await this.getWithFallback(tag, cacheLevel, selector);
+    return player;
+  }
+
+  /**
+   * Throws a HypixelUnavailableException when Hypixel failed and there is no cached player.
+   */
+  public async getWithFallback(
+    tag: string,
+    cacheLevel: CacheLevel,
+    selector?: Record<string, boolean>
+  ): Promise<PlayerLookup> {
     // ensure we have all the necessary data to replace the player document if we don't do a cache only request
     if (selector && Object.keys(selector).length > 0) {
       selector.uuid = true;
@@ -67,12 +89,21 @@ export class PlayerService {
       mongoPlayer &&
       this.hypixelService.shouldCache(mongoPlayer.expiresAt, cacheLevel)
     ) {
-      return deserialize(Player, mongoPlayer);
+      return { player: deserialize(Player, mongoPlayer) };
     }
 
-    const player = await this.hypixelService.getPlayer(
-      mongoPlayer?.uuid ?? tag
-    );
+    let player: Player | null;
+
+    try {
+      player = await this.hypixelService.getPlayer(mongoPlayer?.uuid ?? tag);
+    } catch (error) {
+      if (!mongoPlayer) throw error;
+
+      return {
+        player: deserialize(Player, mongoPlayer),
+        hypixelError: error as HypixelUnavailableException,
+      };
+    }
 
     if (player) {
       player.expiresAt = Date.now() + 120_000;
@@ -86,12 +117,12 @@ export class PlayerService {
 
       flatPlayer.isNew = !mongoPlayer;
 
-      return deserialize(Player, flatPlayer);
+      return { player: deserialize(Player, flatPlayer) };
     } else if (mongoPlayer) {
-      return deserialize(Player, mongoPlayer);
+      return { player: deserialize(Player, mongoPlayer) };
     }
 
-    return null;
+    return { player: null };
   }
 
   public async update(data: APIData) {
@@ -132,7 +163,7 @@ export class PlayerService {
 
     const [status, games] = await Promise.all([
       this.hypixelService.getStatus(player.uuid),
-      this.hypixelService.getRecentGames(player.uuid),
+      this.hypixelService.getRecentGames(player.uuid).catch(() => []),
     ]);
 
     if (!status) throw new StatusNotFoundException(player);

apps/api/src/session/session.controller.ts

@@ -10,6 +10,7 @@ import {
   ApiBadRequestResponse,
   ApiOkResponse,
   ApiOperation,
+  ApiServiceUnavailableResponse,
   ApiTags,
 } from "@nestjs/swagger";
 import { Auth, AuthRole } from "#auth";
@@ -18,6 +19,7 @@ import {
   ErrorResponse,
   GetPlayerResponse,
   GetSessionResponse,
+  HypixelUnavailableException,
   SuccessResponse,
 } from "@statsify/api-client";
 import { PlayerDto, SessionDto, UserIdDto } from "#dtos";
@@ -31,20 +33,23 @@ export class SessionController {
   @ApiOperation({ summary: "Get the Session stats of a Player" })
   @ApiOkResponse({ type: GetSessionResponse })
   @ApiBadRequestResponse({ type: ErrorResponse })
+  @ApiServiceUnavailableResponse({ type: HypixelUnavailableException })
   @Get()
   @Auth({ weight: 2 })
   public async getSession(@Query() { player: tag, userUuid }: SessionDto) {
-    const player = await this.sessionService.get(tag, userUuid);
+    const { player, hypixelUnavailable } = await this.sessionService.get(tag, userUuid);
 
     return {
       success: !!player,
       player,
+      hypixelUnavailable,
     };
   }
 
   @ApiOperation({ summary: "Reset the Session stats of a Player" })
   @ApiOkResponse({ type: GetPlayerResponse })
   @ApiBadRequestResponse({ type: ErrorResponse })
+  @ApiServiceUnavailableResponse({ type: HypixelUnavailableException })
   @Patch()
   @Auth({ role: AuthRole.MEMBER })
   public async resetSession(