feat(bridge): optional-sharp image normalization util (long-edge 2048)

open-sse/utils/imageNormalize.ts

@@ -0,0 +1,62 @@
+/**
+ * Optional-sharp image normalization.
+ *
+ * Rationale (migrated from freellmapi `server/src/lib/image-normalize.ts:40-58`):
+ * OpenAI resizes images to a long-edge cap of 2048px server-side, Anthropic applies
+ * a similar cap. Downscaling client-side before upload reduces tokens/latency without
+ * changing model behavior. `sharp` is loaded via dynamic import so that a platform
+ * where its native binary fails to load never crashes the request path — it just
+ * falls back to a passthrough (original buffer, unresized).
+ */
+
+const DEFAULT_MAX_LONG_EDGE = 2048;
+
+type SharpModule = typeof import("sharp");
+let sharpPromise: Promise<SharpModule | null> | null = null;
+
+async function loadSharp(): Promise<SharpModule | null> {
+  if (!sharpPromise) {
+    sharpPromise = import("sharp").then((m) => (m.default ?? m) as SharpModule).catch(() => null);
+  }
+  return sharpPromise;
+}
+
+export async function normalizeImageBuffer(
+  input: Buffer,
+  opts?: { maxLongEdge?: number }
+): Promise<{ buffer: Buffer; mime: string | null; resized: boolean }> {
+  const maxLongEdge = opts?.maxLongEdge ?? DEFAULT_MAX_LONG_EDGE;
+  const sharp = await loadSharp();
+  if (!sharp) return { buffer: input, mime: null, resized: false };
+  try {
+    const img = sharp(input, { failOn: "error" });
+    const meta = await img.metadata();
+    const long = Math.max(meta.width ?? 0, meta.height ?? 0);
+    if (!long || long <= maxLongEdge) {
+      return { buffer: input, mime: meta.format ? `image/${meta.format}` : null, resized: false };
+    }
+    const buffer = await img
+      .resize({ width: maxLongEdge, height: maxLongEdge, fit: "inside", withoutEnlargement: true })
+      .toBuffer();
+    return { buffer, mime: meta.format ? `image/${meta.format}` : null, resized: true };
+  } catch {
+    return { buffer: input, mime: null, resized: false };
+  }
+}
+
+export async function normalizeDataUri(
+  dataUri: string,
+  opts?: { maxLongEdge?: number }
+): Promise<string> {
+  try {
+    const match = /^data:([^;,]+);base64,(.*)$/s.exec(dataUri);
+    if (!match) return dataUri;
+    const input = Buffer.from(match[2], "base64");
+    if (!input.length) return dataUri;
+    const out = await normalizeImageBuffer(input, opts);
+    if (!out.resized) return dataUri;
+    return `data:${match[1]};base64,${out.buffer.toString("base64")}`;
+  } catch {
+    return dataUri;
+  }
+}

tests/unit/image-normalize.test.ts

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { normalizeImageBuffer, normalizeDataUri } from "../../open-sse/utils/imageNormalize.ts";
+
+test("passthrough when input is not a decodable image (sharp absent or garbage bytes)", async () => {
+  const junk = Buffer.from("not-an-image");
+  const out = await normalizeImageBuffer(junk);
+  assert.equal(out.resized, false);
+  assert.ok(out.buffer.equals(junk));
+});
+
+test("normalizeDataUri never throws and preserves the uri on failure", async () => {
+  const uri = "data:image/png;base64,%%%broken%%%";
+  assert.equal(await normalizeDataUri(uri), uri);
+});
+
+// Só roda quando sharp estiver instalado (optionalDependency presente no devbox):
+test("downscales a large PNG to the long-edge cap when sharp is available", async (t) => {
+  let sharp: typeof import("sharp");
+  try {
+    sharp = (await import("sharp")).default as never;
+  } catch {
+    t.skip("sharp not installed");
+    return;
+  }
+  const big = await sharp({ create: { width: 4096, height: 100, channels: 3, background: "#fff" } })
+    .png()
+    .toBuffer();
+  const out = await normalizeImageBuffer(big, { maxLongEdge: 2048 });
+  assert.equal(out.resized, true);
+  const meta = await sharp(out.buffer).metadata();
+  assert.equal(meta.width, 2048);
+});