@acarmisc/backstage-plugin-litellm-backend 0.15.0 → 0.16.0

package/dist/errors.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Central error handling and sanitization for the LiteLLM backend.
+ *
+ * Ensures that:
+ * - Upstream auth failures (401/403) don't log out Backstage sessions
+ * - Upstream 5xx errors are generic and don't leak implementation details
+ * - Upstream 4xx errors are sanitized and capped
+ * - Non-JSON error bodies are not embedded in responses
+ * - All error logging happens server-side only
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHttpishError = isHttpishError;
+exports.errorMessage = errorMessage;
+exports.sanitizeUpstreamMessage = sanitizeUpstreamMessage;
+exports.toHttpError = toHttpError;
+exports.sendError = sendError;
+const client_1 = require("./client");
+/** Regex to find HTML-like tags and entities. */
+const HTML_TAG_PATTERN = /<[^>]*>|&[a-z]+;/gi;
+/**
+ * Type guard: narrows unknown to {status: number; body: Record<string, unknown>}.
+ * Used to detect custom errors that have status and body properties.
+ */
+function isHttpishError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'status' in error &&
+        'body' in error &&
+        typeof error.status === 'number' && // any: property access after guard check
+        typeof error.body === 'object' // any: property access after guard check
+    );
+}
+/**
+ * Safely extract a message string from any error type.
+ * Returns empty string if no message can be extracted.
+ */
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object' && 'message' in error) {
+        const msg = error.message; // any: message type varies, guarded below
+        if (typeof msg === 'string')
+            return msg;
+    }
+    return '';
+}
+/**
+ * Sanitizes a message by:
+ * - Stripping HTML tags
+ * - Collapsing consecutive whitespace
+ * - Truncating to 500 characters
+ *
+ * @param msg The raw message (may contain HTML, newlines, etc.)
+ * @returns A safe, printable message
+ */
+function sanitizeUpstreamMessage(msg) {
+    if (!msg || typeof msg !== 'string')
+        return '';
+    return msg
+        .replace(HTML_TAG_PATTERN, '') // Strip HTML tags and entities
+        .replace(/\s+/g, ' ') // Collapse whitespace
+        .trim()
+        .slice(0, 500);
+}
+/**
+ * Maps any error type to an HTTP response shape {status, body}.
+ *
+ * Behaviour:
+ * - LiteLLMUpstreamError 401/403 → 502 generic (prevent session logout)
+ * - LiteLLMUpstreamError 5xx or network → 502 generic
+ * - LiteLLMUpstreamError 4xx (other) → 400 with sanitized message + param if present
+ * - KeyServiceError / ProvisioningError / objects with status+body → pass through
+ * - Backstage-style errors (name: InputError/NotAllowedError/NotFoundError/ConflictError) → map to 400/403/404/409
+ * - Anything else → 500 (message logged server-side, not returned)
+ *
+ * @returns {status, body, logLevel} for HTTP response; undefined _logMessage is only present for 500s
+ */
+function toHttpError(error) {
+    // KeyServiceError and ProvisioningError have status + body fields — pass through.
+    if (isHttpishError(error)) {
+        return {
+            status: error.status,
+            body: error.body,
+            logLevel: 'warn',
+        };
+    }
+    // LiteLLMUpstreamError
+    if (error instanceof client_1.LiteLLMUpstreamError) {
+        // 401/403 from upstream → don't expose; map to 502 so Backstage session isn't logged out
+        if (error.status === 401 || error.status === 403) {
+            return {
+                status: 502,
+                body: { error: 'LiteLLM rejected the request' },
+                logLevel: 'warn',
+            };
+        }
+        // 5xx or other network errors → generic 502
+        if (error.status >= 500 || error.status < 100) {
+            return {
+                status: 502,
+                body: { error: 'LiteLLM is unavailable' },
+                logLevel: 'error',
+            };
+        }
+        // 4xx (other than 401/403) → sanitized message and param. Not-found and
+        // conflict keep their meaning; everything else collapses to 400.
+        return {
+            status: error.status === 404 || error.status === 409 ? error.status : 400,
+            body: {
+                error: sanitizeUpstreamMessage(error.message),
+                ...(error.param ? { param: error.param } : {}),
+            },
+            logLevel: 'warn',
+        };
+    }
+    // Backstage-style errors (name field)
+    if (error &&
+        typeof error === 'object' &&
+        'name' in error &&
+        'message' in error) {
+        const name = error.name; // any: error name type varies, guarded by 'in' checks
+        const message = String(error.message); // any: error message type varies, guarded by 'in' checks
+        if (name === 'InputError') {
+            return {
+                status: 400,
+                body: { error: message },
+                logLevel: 'warn',
+            };
+        }
+        if (name === 'NotAllowedError') {
+            return {
+                status: 403,
+                body: { error: message },
+                logLevel: 'warn',
+            };
+        }
+        if (name === 'NotFoundError') {
+            return {
+                status: 404,
+                body: { error: message },
+                logLevel: 'warn',
+            };
+        }
+        if (name === 'ConflictError') {
+            return {
+                status: 409,
+                body: { error: message },
+                logLevel: 'warn',
+            };
+        }
+    }
+    // Network-level failures reaching LiteLLM (DNS, refused, reset, timeout/abort):
+    // an upstream problem, not an internal one.
+    if (error instanceof Error) {
+        const code = error.code;
+        const cause = error.cause;
+        const networkCodes = ['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT'];
+        if (error.name === 'AbortError' ||
+            error.name === 'TimeoutError' ||
+            (error.name === 'TypeError' && error.message === 'fetch failed') ||
+            (typeof code === 'string' && networkCodes.includes(code)) ||
+            (typeof cause?.code === 'string' && networkCodes.includes(cause.code))) {
+            return {
+                status: 502,
+                body: { error: 'LiteLLM is unavailable' },
+                logLevel: 'error',
+                _logMessage: error.message,
+            };
+        }
+    }
+    // Fallback: 500 with no message in response
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        status: 500,
+        body: { error: 'Internal error' },
+        logLevel: 'error',
+        _logMessage: message,
+    };
+}
+/**
+ * Express error handler helper. Logs the real error server-side and responds
+ * via toHttpError.
+ *
+ * @param res Express Response object
+ * @param error The caught error (any type)
+ * @param logger Logger instance with error/warn/info/debug methods
+ * @param context Contextual label for the log entry (e.g. 'fetch user info')
+ */
+function sendError(res, error, logger, context) {
+    const { status, body, logLevel, _logMessage } = toHttpError(error);
+    const realMessage = _logMessage || (error instanceof Error ? error.message : String(error));
+    if (logLevel === 'error') {
+        logger.error(`Failed to ${context}`, error instanceof Error ? error : new Error(String(error)));
+    }
+    else if (logLevel === 'warn') {
+        logger.warn(`${context}: ${realMessage}`);
+    }
+    else {
+        logger.info(`${context}: ${realMessage}`);
+    }
+    res.status(status).json(body);
+}

package/dist/http/respondTeam.d.ts

@@ -0,0 +1,15 @@
+import { Response } from 'express';
+import { TeamInfo } from '../types';
+import type { RouterContext } from '../routes/context';
+/**
+ * Helper to respond with a team record, conditionally redacting its budget.
+ *
+ * `caller` indicates the role of the requester:
+ * - 'member': person viewing from GET /teams (hides if hideTeamBudgetForMembers)
+ * - 'manager': team admin viewing from GET /teams/managed or a write response (hides if hideTeamBudgetForManagers)
+ */
+export declare function respondTeam(res: Response, team: TeamInfo, ctx: RouterContext, caller: 'member' | 'manager'): void;
+/**
+ * Helper to respond with a list of teams, conditionally redacting budgets.
+ */
+export declare function respondTeamList(res: Response, teams: TeamInfo[], ctx: RouterContext, caller: 'member' | 'manager'): void;

package/dist/http/respondTeam.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.respondTeam = respondTeam;
+exports.respondTeamList = respondTeamList;
+const teamBudgetVisibility_1 = require("../teamBudgetVisibility");
+/**
+ * Helper to respond with a team record, conditionally redacting its budget.
+ *
+ * `caller` indicates the role of the requester:
+ * - 'member': person viewing from GET /teams (hides if hideTeamBudgetForMembers)
+ * - 'manager': team admin viewing from GET /teams/managed or a write response (hides if hideTeamBudgetForManagers)
+ */
+function respondTeam(res, team, ctx, caller) {
+    const shouldHide = caller === 'member'
+        ? ctx.teamBudgetVisibility.hideTeamBudgetForMembers
+        : ctx.teamBudgetVisibility.hideTeamBudgetForManagers;
+    res.json(shouldHide ? (0, teamBudgetVisibility_1.redactTeamBudget)(team) : team);
+}
+/**
+ * Helper to respond with a list of teams, conditionally redacting budgets.
+ */
+function respondTeamList(res, teams, ctx, caller) {
+    const shouldHide = caller === 'member'
+        ? ctx.teamBudgetVisibility.hideTeamBudgetForMembers
+        : ctx.teamBudgetVisibility.hideTeamBudgetForManagers;
+    res.json(shouldHide ? teams.map(teamBudgetVisibility_1.redactTeamBudget) : teams);
+}

package/dist/http/teamFetch.d.ts

@@ -0,0 +1,14 @@
+export declare const teamCreateInFlight: Map<string, Promise<unknown>>;
+/**
+ * Retries a LiteLLM team-info fetch with the given backoff schedule.
+ *
+ * LiteLLM proxies are commonly run behind multiple replicas; a request can
+ * land on a replica that hasn't yet caught up with a very recent write
+ * (team create/update, membership change), or on one that is transiently
+ * unhealthy. Both surface as a failed `getTeamInfo` call that would
+ * otherwise be swallowed (e.g. GET /teams silently drops the team from the
+ * response) or bubble up as a spurious 500/404 right after a write this
+ * same request just made. A short retry smooths over that window without
+ * masking a genuine, persistent failure.
+ */
+export declare function withTeamFetchRetry<T>(fn: () => Promise<T>, delaysMs?: number[]): Promise<T>;

package/dist/http/teamFetch.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.teamCreateInFlight = void 0;
+exports.withTeamFetchRetry = withTeamFetchRetry;
+const client_1 = require("../client");
+exports.teamCreateInFlight = new Map();
+/** Backoff schedule for `withTeamFetchRetry` — 3 retries over ~1.3s total. */
+const TEAM_FETCH_RETRY_DELAYS_MS = [100, 300, 900];
+/**
+ * Only 5xx (and network/timeout) failures are treated as transient — a 4xx
+ * like "team not found" or "forbidden" is a deterministic answer from the
+ * upstream and retrying it would just add latency for the same result.
+ */
+function isRetryableTeamFetchError(err) {
+    if (err instanceof client_1.LiteLLMUpstreamError) {
+        return err.status >= 500;
+    }
+    return true;
+}
+/**
+ * Retries a LiteLLM team-info fetch with the given backoff schedule.
+ *
+ * LiteLLM proxies are commonly run behind multiple replicas; a request can
+ * land on a replica that hasn't yet caught up with a very recent write
+ * (team create/update, membership change), or on one that is transiently
+ * unhealthy. Both surface as a failed `getTeamInfo` call that would
+ * otherwise be swallowed (e.g. GET /teams silently drops the team from the
+ * response) or bubble up as a spurious 500/404 right after a write this
+ * same request just made. A short retry smooths over that window without
+ * masking a genuine, persistent failure.
+ */
+async function withTeamFetchRetry(fn, delaysMs = TEAM_FETCH_RETRY_DELAYS_MS) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (attempt >= delaysMs.length || !isRetryableTeamFetchError(err)) {
+                throw err;
+            }
+            await new Promise(resolve => setTimeout(resolve, delaysMs[attempt]));
+        }
+    }
+}