@everystack/api 0.4.2 → 0.4.4

package/src/handler/service-unavailable.ts

@@ -0,0 +1,48 @@
+import { safeRead } from './thrown';
+
+/**
+ * Classify an error as an infrastructure outage: the database (or another
+ * backing service) could not be reached or dropped the connection. Duck-typed
+ * on `err.code` so the api package stays free of any driver dependency.
+ *
+ * Besides transport errors this covers SQLSTATE class 28 (a bad login): end
+ * users never log in to PostgreSQL (the handler only SET LOCAL ROLEs), so a
+ * class 28 error is the service's own credential failing, e.g. after a
+ * rotation. It also covers jose's JWKS fetch timeout (the key server is down,
+ * the token may be fine).
+ *
+ * An outage must answer 503, never 401 (a client reads 401 as "bad
+ * credentials" and logs the user out) and never echo the driver's message
+ * (it carries host and port).
+ */
+const UNAVAILABLE_CODES = new Set([
+  // postgres.js transport errors. CONNECTION_ENDED/CONNECTION_DESTROYED are
+  // also raised after the APP calls sql.end(), so a pool-ending bug shows as
+  // 503 rather than 500 (accepted).
+  'CONNECTION_CLOSED', 'CONNECTION_ENDED', 'CONNECTION_DESTROYED', 'CONNECT_TIMEOUT',
+  // Node socket errors
+  'ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'EPIPE', 'ENOTFOUND', 'EAI_AGAIN',
+  'EHOSTUNREACH', 'EHOSTDOWN', 'ENETUNREACH', 'ENETDOWN',
+  // jose: the remote JWKS fetch timed out. A third-party code, duck-typed like
+  // postgres.js. The bad-token codes (ERR_JWKS_NO_MATCHING_KEY, ERR_JWT_*)
+  // are NOT here: those stay 401.
+  'ERR_JWKS_TIMEOUT',
+  // PostgreSQL: admin_shutdown, crash_shutdown, cannot_connect_now,
+  // idle_session_timeout, too_many_connections
+  '57P01', '57P02', '57P03', '57P05', '53300',
+]);
+
+export function isServiceUnavailable(err: unknown): boolean {
+  // The error's own code wins; `cause` (one level, as fetch wraps a socket
+  // error) is read only when the error declares no code at all.
+  // A code getter that throws is a declared but unusable code: no outage, no cause.
+  const code = safeRead(err, 'code') ?? safeRead(safeRead(err, 'cause'), 'code');
+  if (typeof code !== 'string') return false;
+  // SQLSTATE class 08: connection_exception.
+  if (code.length === 5 && code.startsWith('08')) return true;
+  // SQLSTATE class 28: invalid_authorization_specification (28000, 28P01).
+  if (code.length === 5 && code.startsWith('28')) return true;
+  return UNAVAILABLE_CODES.has(code);
+}
+
+export const SERVICE_UNAVAILABLE_MESSAGE = 'Service temporarily unavailable';

package/src/handler/thrown.ts

@@ -0,0 +1,32 @@
+/**
+ * Reads of a thrown value. Anything can be thrown, and an Error can carry a
+ * getter that throws, so every read the handler makes of one goes through
+ * safeRead: a classifier or the fault reporter must never throw in place of
+ * the error it was handed.
+ */
+
+/** What safeRead returns when the property access itself threw. */
+export const UNREADABLE: unique symbol = Symbol('unreadable');
+
+/** `value[key]`, or UNREADABLE when the access throws. Never throws. */
+export function safeRead(value: unknown, key: string): unknown {
+  if (value === null || value === undefined) return undefined;
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return UNREADABLE;
+  }
+}
+
+/**
+ * Detect PostgreSQL permission denied errors (code 42501).
+ * Used to convert Postgres GRANT/RLS denials into clean 403 responses.
+ */
+export function isPermissionDenied(error: unknown): boolean {
+  if (error && typeof error === 'object') {
+    if (safeRead(error, 'code') === '42501') return true;
+    const message = safeRead(error, 'message');
+    if (typeof message === 'string' && message.includes('permission denied')) return true;
+  }
+  return false;
+}