@quenty/nevermore-cli 4.30.0 → 4.31.0

package/src/utils/open-cloud/open-cloud-client.ts

@@ -392,7 +392,8 @@ export class OpenCloudClient {
    */
   async downloadPlaceAsync(
     universeId: number,
-    placeId: number
+    placeId: number,
+    onProgress?: (transferredBytes: number, totalBytes: number) => void
   ): Promise<Buffer> {
     const apiKey = await this._resolveApiKeyAsync();
     const url = `https://apis.roblox.com/asset-delivery-api/v1/assetId/${placeId}`;
@@ -436,14 +437,78 @@ export class OpenCloudClient {
     }
 
     OutputHelper.verbose('Fetching place binary from CDN...');
-    const cdnResponse = await fetch(data.location);
-    if (!cdnResponse.ok) {
-      throw new Error(
-        `Download place CDN fetch failed: ${cdnResponse.status} ${cdnResponse.statusText}`
+    return _fetchCdnBinaryAsync(data.location, onProgress);
+  }
+}
+
+const CDN_MAX_ATTEMPTS = 4;
+
+async function _fetchCdnBinaryAsync(
+  url: string,
+  onProgress?: (transferredBytes: number, totalBytes: number) => void
+): Promise<Buffer> {
+  let lastError: unknown = null;
+  for (let attempt = 1; attempt <= CDN_MAX_ATTEMPTS; attempt++) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return await _readBodyWithProgressAsync(response, onProgress);
+      }
+      lastError = new Error(
+        `Download place CDN fetch failed: ${response.status} ${response.statusText}`
       );
+      // 4xx (other than 408/429) won't fix itself — stop retrying.
+      if (
+        response.status >= 400 &&
+        response.status < 500 &&
+        response.status !== 408 &&
+        response.status !== 429
+      ) {
+        throw lastError;
+      }
+    } catch (err) {
+      lastError = err;
     }
 
-    const arrayBuffer = await cdnResponse.arrayBuffer();
-    return Buffer.from(arrayBuffer);
+    if (attempt === CDN_MAX_ATTEMPTS) {
+      break;
+    }
+    const waitMs = Math.min(8000, 500 * Math.pow(2, attempt - 1));
+    OutputHelper.warn(
+      `CDN download attempt ${attempt}/${CDN_MAX_ATTEMPTS} failed (${
+        lastError instanceof Error ? lastError.message : String(lastError)
+      }). Retrying in ${(waitMs / 1000).toFixed(1)}s...`
+    );
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+  }
+  throw lastError ?? new Error('Download place CDN fetch failed');
+}
+
+async function _readBodyWithProgressAsync(
+  response: Response,
+  onProgress?: (transferredBytes: number, totalBytes: number) => void
+): Promise<Buffer> {
+  if (!onProgress || !response.body) {
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  // Content-Length may be absent (chunked transfer); report 0 in that case
+  // and let the formatter render "transferred so far" without a denominator.
+  const contentLength = response.headers.get('content-length');
+  const totalBytes = contentLength ? parseInt(contentLength, 10) : 0;
+
+  const chunks: Uint8Array[] = [];
+  let transferred = 0;
+  const reader = response.body.getReader();
+  onProgress(0, totalBytes);
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    transferred += value.byteLength;
+    onProgress(transferred, totalBytes);
   }
+
+  return Buffer.concat(chunks);
 }

package/src/utils/open-cloud/rate-limiter.test.ts

@@ -132,16 +132,16 @@ describe('RateLimiter', () => {
     expect(fetchMock).toHaveBeenCalledTimes(2);
   });
 
-  it('returns the last 429 response after exhausting all retries', async () => {
+  it('returns the last 429 response after exhausting all retries without sleeping past the final attempt', async () => {
     vi.useFakeTimers();
-    const limiter = new RateLimiter();
+    const limiter = new RateLimiter({ maxRetries: 3 });
 
     fetchMock.mockResolvedValue(makeResponse(429, { 'retry-after': '1' }));
 
     const promise = limiter.fetchAsync('https://apis.roblox.com/cloud/v2/a');
 
-    // Three attempts, each waiting 1s before the next (or before giving up).
-    await vi.advanceTimersByTimeAsync(1000);
+    // Two backoffs between three attempts. After the third failure the
+    // limiter must return immediately rather than sleeping pointlessly.
     await vi.advanceTimersByTimeAsync(1000);
     await vi.advanceTimersByTimeAsync(1000);
 
@@ -149,4 +149,52 @@ describe('RateLimiter', () => {
     expect(response.status).toBe(429);
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
+
+  it('retries on 503 with backoff before returning success', async () => {
+    vi.useFakeTimers();
+    const limiter = new RateLimiter();
+
+    fetchMock
+      .mockResolvedValueOnce(makeResponse(503))
+      .mockResolvedValueOnce(makeResponse(200));
+
+    const promise = limiter.fetchAsync('https://apis.roblox.com/cloud/v2/a');
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Exponential fallback for attempt 0 is 2^0 = 1s.
+    await vi.advanceTimersByTimeAsync(1000);
+    const response = await promise;
+    expect(response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries on transport errors and surfaces the last error if all attempts reject', async () => {
+    vi.useFakeTimers();
+    const limiter = new RateLimiter({ maxRetries: 2 });
+
+    fetchMock.mockRejectedValue(new TypeError('ECONNRESET'));
+
+    const promise = limiter.fetchAsync('https://apis.roblox.com/cloud/v2/a');
+    const settled = promise.catch((err) => err);
+
+    await vi.advanceTimersByTimeAsync(1000);
+
+    const err = await settled;
+    expect(err).toBeInstanceOf(TypeError);
+    expect((err as Error).message).toBe('ECONNRESET');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry on non-retryable 4xx responses', async () => {
+    const limiter = new RateLimiter();
+    fetchMock.mockResolvedValueOnce(makeResponse(404));
+
+    const response = await limiter.fetchAsync(
+      'https://apis.roblox.com/cloud/v2/a'
+    );
+    expect(response.status).toBe(404);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
 });

package/src/utils/open-cloud/rate-limiter.ts

@@ -19,7 +19,9 @@ function _extractRoute(url: string | URL | Request): string {
 }
 
 const DEFAULT_MAX_CONCURRENCY = 4;
+const DEFAULT_MAX_RETRIES = 6;
 const RETRY_JITTER_FRACTION = 0.3;
+const RETRYABLE_SERVER_ERROR_STATUSES = new Set([502, 503, 504]);
 
 export interface RateLimiterOptions {
   /**
@@ -28,6 +30,12 @@ export interface RateLimiterOptions {
    * keeping a tight feedback loop on `x-ratelimit-remaining`.
    */
   maxConcurrency?: number;
+  /**
+   * Total attempts per request before giving up (including the initial try).
+   * Defaults to 6, sized to ride out the Luau-execution endpoint's burst
+   * windows during a multi-place deploy.
+   */
+  maxRetries?: number;
 }
 
 /**
@@ -48,12 +56,14 @@ export class RateLimiter {
   private _queue: Array<() => void> = [];
   private _inflight = 0;
   private _maxConcurrency: number;
+  private _maxRetries: number;
 
   constructor(options: RateLimiterOptions = {}) {
     this._maxConcurrency = Math.max(
       1,
       options.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY
     );
+    this._maxRetries = Math.max(1, options.maxRetries ?? DEFAULT_MAX_RETRIES);
   }
 
   private _updateFromHeaders(headers: Headers): void {
@@ -122,7 +132,8 @@ export class RateLimiter {
    * - Caps concurrency at `_maxConcurrency` (default 4) so we keep getting
    *   header feedback before each new wave fans out
    * - Delays if we know we're out of quota
-   * - Retries on 429 with jittered back-off (up to 3 attempts)
+   * - Retries on 429, retryable 5xx (502/503/504), and transport errors
+   *   with jittered back-off
    * - Tracks rate-limit headers from every response
    */
   async fetchAsync(
@@ -134,44 +145,95 @@ export class RateLimiter {
     const route = _extractRoute(url);
 
     try {
-      await this._waitIfNeededAsync(route);
-
       let lastResponse: Response | null = null;
-      const maxRetries = 3;
+      let lastError: unknown = null;
+
+      for (let attempt = 0; attempt < this._maxRetries; attempt++) {
+        await this._waitIfNeededAsync(route);
+
+        let response: Response | null = null;
+        let transportError: unknown = null;
 
-      for (let attempt = 0; attempt < maxRetries; attempt++) {
-        const response = await fetch(url, init);
-        this._updateFromHeaders(response.headers);
+        try {
+          response = await fetch(url, init);
+          this._updateFromHeaders(response.headers);
+        } catch (err) {
+          transportError = err;
+        }
 
-        if (response.status !== 429) {
+        if (response && !_isRetryableStatus(response.status)) {
           return response;
         }
 
-        lastResponse = response;
+        if (response) {
+          lastResponse = response;
+        } else {
+          lastError = transportError;
+        }
 
-        const retryAfter = response.headers.get('retry-after');
-        const baseSec = retryAfter
-          ? parseFloat(retryAfter)
-          : 10 * (attempt + 1);
-        // Additive jitter only — never wait less than retry-after asked for,
-        // but desynchronize concurrent callers so they don't all retry on the
-        // exact same millisecond and re-collide on the next attempt.
-        const waitSec = baseSec * (1 + Math.random() * RETRY_JITTER_FRACTION);
+        const isFinalAttempt = attempt === this._maxRetries - 1;
+        if (isFinalAttempt) {
+          break;
+        }
 
+        const waitSec = _computeWaitSeconds(response, attempt);
+        const reason = response
+          ? `${response.status} on ${route}`
+          : `transport error on ${route} (${_describeError(transportError)})`;
         OutputHelper.warn(
-          `429 on ${route} (attempt ${
-            attempt + 1
-          }/${maxRetries}). Retrying in ${waitSec.toFixed(
-            1
-          )}s (Roblox requested)...`
+          `${reason} (attempt ${attempt + 1}/${
+            this._maxRetries
+          }). Retrying in ${waitSec.toFixed(1)}s...`
         );
         await new Promise((resolve) => setTimeout(resolve, waitSec * 1000));
       }
 
-      // All retries exhausted — return the last 429 response
-      return lastResponse!;
+      if (lastResponse) {
+        return lastResponse;
+      }
+      throw lastError ?? new Error(`Request to ${route} failed`);
     } finally {
       this._release();
     }
   }
 }
+
+function _isRetryableStatus(status: number): boolean {
+  return status === 429 || RETRYABLE_SERVER_ERROR_STATUSES.has(status);
+}
+
+function _computeWaitSeconds(
+  response: Response | null,
+  attempt: number
+): number {
+  const retryAfter = response?.headers.get('retry-after');
+  const parsed = retryAfter != null ? _parseRetryAfter(retryAfter) : null;
+  // Exponential fallback capped at 30s — keeps multi-place deploys from
+  // ballooning to minutes of compounded backoff while still spacing out
+  // collisions when the server doesn't pin a retry-after.
+  const baseSec = parsed ?? Math.min(30, Math.pow(2, attempt));
+  // Additive jitter only — never wait less than retry-after asked for, but
+  // desynchronize concurrent callers so they don't all retry on the exact
+  // same millisecond and re-collide on the next attempt.
+  return baseSec * (1 + Math.random() * RETRY_JITTER_FRACTION);
+}
+
+function _parseRetryAfter(value: string): number | null {
+  const trimmed = value.trim();
+  const asSeconds = Number(trimmed);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return asSeconds;
+  }
+  const asDateMs = Date.parse(trimmed);
+  if (Number.isFinite(asDateMs)) {
+    return Math.max(0, (asDateMs - Date.now()) / 1000);
+  }
+  return null;
+}
+
+function _describeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}

package/src/utils/testing/reporting/test-github-columns.ts

@@ -47,7 +47,7 @@ function createTryItColumn(): GithubCommentColumn {
         return '';
       }
       const openUrl = `https://www.roblox.com/games/${placeId}`;
-      const playUrl = `roblox://experiences/start?placeId=${placeId}`;
+      const playUrl = `https://www.roblox.com/games/start?placeId=${placeId}`;
       return `[Open](${openUrl}) \\| [Play](${playUrl})`;
     },
   };