UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

413 lines (381 loc) • 16.8 kB
import { sniffImageDimensions } from "./anthropic-image-guard"; import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory"; /** One ladder position: dimension cap, JPEG quality attempts, per-image base64 cap. */ export interface TierSpec { maxEdge: number; qualities: number[]; /** Hard per-image base64-length cap at this position; Infinity = terminal (measured size accepted). */ hardCap: number; } const KiB = 1024; const MiB = 1024 * 1024; /** * Ladder positions 0-5. 0-2 are the age-assigned tiers; 3-5 are demotion floor steps. * Terminal (last) accepts its measured output so the aggregate loop always terminates * (audit round 2, blocker 1). */ export const TIER_SPECS: TierSpec[] = [ { maxEdge: 2000, qualities: [80, 60, 40, 30], hardCap: 2 * MiB }, { maxEdge: 1024, qualities: [70, 50], hardCap: 512 * KiB }, { maxEdge: 700, qualities: [60, 40], hardCap: 192 * KiB }, { maxEdge: 500, qualities: [40], hardCap: 100 * KiB }, { maxEdge: 400, qualities: [30], hardCap: 100 * KiB }, { maxEdge: 320, qualities: [25], hardCap: Infinity }, ]; export const TERMINAL_POS = TIER_SPECS.length - 1; /** Newest 6 images ride tier 0, the next 14 tier 1, the rest tier 2 (020 tier table). */ export const TIER0_COUNT = 6; export const TIER1_COUNT = 14; /** Decode-bomb guards: refuse to decode absurd inputs (020 guards; "extreme values excluded"). */ export const MAX_INPUT_BASE64_LENGTH = 64 * MiB; /** * First-pass worker-pool width. Memory-bound, not CPU-bound: each in-flight item can * hold a decoded bitmap, so this bounds peak memory to ~4 decoded images while still * overlapping I/O and native-encode threadpool work. Fixed on purpose — a config knob * would widen the adapter contract with no demonstrated need. */ export const IMAGE_NORMALIZE_CONCURRENCY = 4; // Keep one decoded RGBA surface below 64 MiB. Native codecs may allocate additional // working buffers, so this is paired with process-wide admission in the normalizer. export const MAX_INPUT_PIXELS = 16_000_000; /** Formats Anthropic accepts as-is; anything else must be transcoded or dropped. */ const PASSTHROUGH_MEDIA = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]); export interface NormalizeOptions { /** Shift every image's starting ladder position down (413 retry tightening; 030). */ tierBias?: number; /** Cancels queued native decode work and stops pulling more images. */ abortSignal?: AbortSignal; /** Test seam: replaces the Bun.Image encode path (audit round 1, blocker 6). */ encode?: EncodeFn; /** Test seam: replaces the pass-through decode validation (C-gate round 1, blocker 1). */ validate?: ValidateFn; } export type EncodeFn = ( input: Uint8Array, spec: TierSpec, quality: number, ) => Promise<{ data: string; mediaType: string }>; /** Proves the payload fully decodes; must throw for corrupt/truncated data. */ export type ValidateFn = (input: Uint8Array) => Promise<void>; type ProcessResult = | { kind: "pass"; b64Length: number } | { kind: "encoded"; data: string; mediaType: string } | { kind: "failed" }; /** * Byte-weighted LRU over normalized outputs (audit round 1, blocker 2): aggregate cap, * not entry count. Entries are immutable snapshots — demotions write NEW tier-suffixed * keys, never mutate stored values. */ export const IMAGE_NORMALIZE_CACHE_MAX_BYTES = 64 * MiB; const CACHE_MAX_ENTRIES = 4_096; const CACHE_MAX_ENTRY_BYTES = 20 * MiB; // "pass" = validated pass-through; "miss" = this position's ladder cannot meet its hard // cap for these bytes (skip straight to the next position — C-gate round 2, blocker 1). type CacheValue = { data: string; mediaType: string } | "pass" | "miss"; interface CacheEntry { value: CacheValue; sizeBytes: number; metadataBytes: number; storedAt: number; } interface NormalizeCacheLimits { maxBytes: number; maxEntries: number; maxEntryBytes: number; } const DEFAULT_CACHE_LIMITS: NormalizeCacheLimits = { maxBytes: IMAGE_NORMALIZE_CACHE_MAX_BYTES, maxEntries: CACHE_MAX_ENTRIES, maxEntryBytes: CACHE_MAX_ENTRY_BYTES, }; const cacheEncoder = new TextEncoder(); const cache = new Map<string, CacheEntry>(); let cacheLimits = { ...DEFAULT_CACHE_LIMITS }; let cacheBytes = 0; let cacheMetadataBytes = 0; let cacheSentinelEntries = 0; let encodeCalls = 0; /** * Last-EMITTED ladder position per image identity (#4532). The age-tier pyramid in * anthropic-image-normalize derives an image's start position from its recency rank * within the current request, so appending one newer image shifts every older image's * rank by one and can push it across a tier boundary — re-encoding it to different * bytes and busting Anthropic's prompt prefix cache for the whole history. Pinning the * start position to the image's own identity keeps already-emitted bytes stable across * appends. Keys are fixed-size digests of the bytes and canonical media type, so * caller-controlled metadata cannot make the retained identity arbitrarily large. * The bytes count toward the shared retained-memory budget but are pinned: the * shared evictor clears normalization cache slots first and never drops position * memory, because a request reads this store before it finishes and a mid-request * eviction would make a repeated image lose its pinned position and fall back to * an age-derived tier. Positions shrink only through this store's own entry-count * cap, applied when positions are committed after the request settles. */ const POSITION_STORE_MAX_ENTRIES = 4_096; const MAX_CANONICAL_MEDIA_TYPE_LENGTH = 127; const MEDIA_TYPE_PATTERN = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/; interface PositionEntry { position: number; sizeBytes: number; storedAt: number } const emittedPositions = new Map<string, PositionEntry>(); let positionBytes = 0; function positionKey(b64: string, mediaType: string): string { const normalized = mediaType.trim().toLowerCase(); const canonical = normalized.length <= MAX_CANONICAL_MEDIA_TYPE_LENGTH && MEDIA_TYPE_PATTERN.test(normalized) ? normalized // Keep invalid/overlong types distinct under an "invalid:" namespace: folding // them all onto application/octet-stream let a different invalid type reuse a // prior emitted position and demote the second image to a smaller tier. The // prefix cannot collide with a valid canonical type (':' fails the pattern). : `invalid:${normalized}`; return new Bun.CryptoHasher("sha256").update(b64).update("\0").update(canonical).digest("hex"); } function deletePositionEntry(key: string): number { const entry = emittedPositions.get(key); if (!entry) return 0; emittedPositions.delete(key); positionBytes -= entry.sizeBytes; return entry.sizeBytes; } /** * The position this image was last emitted at, if it has been normalized before. * Reads refresh recency (insertion-order LRU, same discipline as the encode cache). */ export function recordedEmittedPosition(b64: string, mediaType: string): number | undefined { const key = positionKey(b64, mediaType); const entry = emittedPositions.get(key); if (entry !== undefined) { emittedPositions.delete(key); entry.storedAt = Date.now(); emittedPositions.set(key, entry); } return entry?.position; } /** * Record the position an image actually ended at. Positions only ever move DOWN the * ladder (first-pass tier, aggregate demotion, tierBias) — nothing raises an image * back up — so the stored value is monotonically non-decreasing and cannot flap. * That monotonicity is what makes identity-pinning safe: a stale entry can only make * an image smaller than its fresh tier would, never larger. */ export function recordEmittedPosition(b64: string, mediaType: string, pos: number): void { const key = positionKey(b64, mediaType); const existing = emittedPositions.get(key); if (existing !== undefined) { deletePositionEntry(key); pos = Math.max(existing.position, pos); } while (emittedPositions.size + 1 > POSITION_STORE_MAX_ENTRIES) { const oldest = emittedPositions.keys().next().value; if (oldest === undefined) break; deletePositionEntry(oldest); } const sizeBytes = cacheEncoder.encode(key).byteLength + 16; emittedPositions.set(key, { position: pos, sizeBytes, storedAt: Date.now() }); positionBytes += sizeBytes; enforceAppOwnedMemoryBudget(); } function cacheEntry(key: string, value: CacheValue): CacheEntry { const keyBytes = cacheEncoder.encode(key).byteLength; const valueBytes = typeof value === "string" ? cacheEncoder.encode(value).byteLength : cacheEncoder.encode(value.mediaType).byteLength + cacheEncoder.encode(value.data).byteLength; const metadataBytes = keyBytes + (typeof value === "string" ? cacheEncoder.encode(value).byteLength : cacheEncoder.encode(value.mediaType).byteLength); return { value, sizeBytes: keyBytes + valueBytes, metadataBytes, storedAt: Date.now() }; } function deleteCacheEntry(key: string): number { const entry = cache.get(key); if (!entry) return 0; cache.delete(key); cacheBytes -= entry.sizeBytes; cacheMetadataBytes -= entry.metadataBytes; if (typeof entry.value === "string") cacheSentinelEntries--; return entry.sizeBytes; } function cachePut(key: string, value: CacheValue): boolean { const next = cacheEntry(key, value); if ( next.sizeBytes > cacheLimits.maxEntryBytes || next.sizeBytes > cacheLimits.maxBytes || cacheLimits.maxEntries <= 0 ) return false; const existing = cache.get(key); if (existing !== undefined) { deleteCacheEntry(key); // re-insert refreshes recency and prevents double-count on concurrent misses } while (cache.size + 1 > cacheLimits.maxEntries || cacheBytes + next.sizeBytes > cacheLimits.maxBytes) { const oldest = cache.keys().next().value; if (oldest === undefined || deleteCacheEntry(oldest) === 0) return false; } cache.set(key, next); cacheBytes += next.sizeBytes; cacheMetadataBytes += next.metadataBytes; if (typeof value === "string") cacheSentinelEntries++; enforceAppOwnedMemoryBudget(); return true; } /** Read a cache entry, refreshing its recency (true LRU, C-gate round 1 blocker 5). */ function cacheGet(key: string): CacheValue | undefined { const entry = cache.get(key); if (entry !== undefined) { cache.delete(key); entry.storedAt = Date.now(); cache.set(key, entry); } return entry?.value; } /** Test hooks: encoder-invocation counter + cache reset (no production caller). */ export function getNormalizeStatsForTests(): { encodeCalls: number; cacheEntries: number; cacheBytes: number; sentinelEntries: number; metadataBytes: number; positionEntries: number; positionBytes: number; oldestAt: number | null; } { return { encodeCalls, cacheEntries: cache.size, cacheBytes, sentinelEntries: cacheSentinelEntries, metadataBytes: cacheMetadataBytes, positionEntries: emittedPositions.size, positionBytes, oldestAt: cache.values().next().value?.storedAt ?? null, }; } export function resetNormalizeStateForTests(): void { cache.clear(); emittedPositions.clear(); positionBytes = 0; cacheBytes = 0; cacheMetadataBytes = 0; cacheSentinelEntries = 0; encodeCalls = 0; } export function setNormalizeCacheLimitsForTests(limits?: Partial<NormalizeCacheLimits>): void { resetNormalizeStateForTests(); cacheLimits = limits ? { ...DEFAULT_CACHE_LIMITS, ...limits } : { ...DEFAULT_CACHE_LIMITS }; } export function anthropicImageNormalizeRetainedStoreSnapshot(): { count: number; bytes: number; evictableBytes: number; pinnedBytes: number; oldestAt: number | null; } { return { count: cache.size + emittedPositions.size, bytes: cacheBytes + positionBytes, evictableBytes: cacheBytes, pinnedBytes: positionBytes, oldestAt: cache.values().next().value?.storedAt ?? null, }; } export function evictOldestAnthropicImageNormalizeForBudget(): number { // Position memory is pinned for the life of a request (see the store comment): // the shared budget reclaims normalization cache slots first, and a position // entry is only released by recordEmittedPosition's own entry-count cap after // the request settles. A cache miss is cheaper than losing an image's pinned // ladder position mid-request. const cacheOldest = cache.entries().next().value as [string, CacheEntry] | undefined; return cacheOldest ? deleteCacheEntry(cacheOldest[0]) : 0; } /** Default encoder: Bun.Image resize-to-fit + JPEG at the given quality. */ export const bunImageEncode: EncodeFn = async (input, spec, quality) => { const image = new Bun.Image(input); const meta = await image.metadata(); const w = typeof meta.width === "number" ? meta.width : 0; const h = typeof meta.height === "number" ? meta.height : 0; if (w <= 0 || h <= 0 || w * h > MAX_INPUT_PIXELS) { throw new Error("image dimensions exceed the safe decode limit"); } let pipeline = new Bun.Image(input); if (w > spec.maxEdge || h > spec.maxEdge) { const scale = spec.maxEdge / Math.max(w, h); pipeline = pipeline.resize(Math.max(1, Math.round(w * scale)), Math.max(1, Math.round(h * scale))); } const out = await pipeline.jpeg({ quality }).toBuffer(); return { data: Buffer.from(out).toString("base64"), mediaType: "image/jpeg" }; }; /** * Default pass-through validation: force a full decode (resize forces pixel decoding, a * header-only metadata read does not). A sniffable-but-truncated payload must throw here * instead of riding pass-through to an Anthropic 400 (C-gate round 1, blocker 1). */ export const bunImageValidate: ValidateFn = async input => { const image = new Bun.Image(input); const meta = await image.metadata(); const w = typeof meta.width === "number" ? meta.width : 0; const h = typeof meta.height === "number" ? meta.height : 0; if (w <= 0 || h <= 0 || w * h > MAX_INPUT_PIXELS) { throw new Error("image dimensions exceed the safe decode limit"); } await image.resize(1, 1).jpeg({ quality: 1 }).toBuffer(); }; /** * Process one image at a ladder position: pass through when it already fits the * position's caps (Anthropic-native format, dims within maxEdge, size within hardCap — * this also exempts possibly-animated GIF/WebP from a lossy re-encode; pass-through is * additionally VALIDATED with a full decode once, cached), otherwise walk positions * downward encoding until a hard cap is met; terminal accepts measured size. * `mediaType` must be the ORIGINAL source media type (cache keys include it — C-gate * round 1, blocker 4 — and pass-through eligibility depends on it). */ export async function processAt( b64: string, startPos: number, mediaType: string, encode: EncodeFn, validate: ValidateFn, ): Promise<ProcessResult & { pos: number }> { const dims = sniffImageDimensions(b64); const hash = Bun.hash(b64).toString(36); let input: Uint8Array; try { input = Uint8Array.from(Buffer.from(b64, "base64")); } catch { return { kind: "failed", pos: startPos }; } for (let pos = startPos; pos <= TERMINAL_POS; pos++) { const spec = TIER_SPECS[pos]; const key = `${hash}:${mediaType}:${pos}`; const cached = cacheGet(key); if (cached === "pass") return { kind: "pass", b64Length: b64.length, pos }; if (cached === "miss") continue; // known cap miss: skip to the next position if (cached) return { kind: "encoded", data: cached.data, mediaType: cached.mediaType, pos }; const fitsDims = dims !== null && dims.width <= spec.maxEdge && dims.height <= spec.maxEdge; if (PASSTHROUGH_MEDIA.has(mediaType) && fitsDims && b64.length <= spec.hardCap) { try { await validate(input); // sniffable-but-truncated data must not ride pass-through } catch { return { kind: "failed", pos }; } cachePut(key, "pass"); return { kind: "pass", b64Length: b64.length, pos }; } let last: { data: string; mediaType: string } | null = null; try { for (const quality of spec.qualities) { encodeCalls++; last = await encode(input, spec, quality); if (last.data.length <= spec.hardCap) { cachePut(key, last); return { kind: "encoded", data: last.data, mediaType: last.mediaType, pos }; } } } catch { // Decode/encode failure: corrupt or unsupported payload (audit round 2, blocker 2). return { kind: "failed", pos }; } if (pos === TERMINAL_POS && last) { cachePut(key, last); return { kind: "encoded", data: last.data, mediaType: last.mediaType, pos }; } // Hard cap missed at this position — remember the miss, continue down the ladder. cachePut(key, "miss"); } return { kind: "failed", pos: TERMINAL_POS }; }