sailfork / t3code-github / packages/ client-runtime/ src/ projectFaviconCache.ts

import { EnvironmentId } from "@t3tools/contracts";
import { mediaMimeType } from "@t3tools/shared/mediaPreview";
import {
  getProjectFaviconCacheKey,
  getProjectFaviconResourceKey,
  isProjectFaviconFallbackUrl,
} from "@t3tools/shared/projectFavicon";
import * as Base64 from "effect/encoding/Base64";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";

export const PROJECT_FAVICON_THUMBNAIL_SIZE = 96;
export const PROJECT_FAVICON_MAX_DATA_URL_LENGTH = 32 * 1024;
export const PROJECT_FAVICON_MAX_SOURCE_BYTES = 4 * 1024 * 1024;
export const PROJECT_FAVICON_CACHE_MAX_BYTES = 1024 * 1024;
export const PROJECT_FAVICON_CACHE_MAX_ENTRIES = 128;

export interface ProjectFaviconTarget {
  readonly environmentId: EnvironmentId;
  readonly cwd: string;
  readonly faviconPath?: string | null | undefined;
}

const ImageDataUrl = Schema.String.check(
  Schema.isMaxLength(PROJECT_FAVICON_MAX_DATA_URL_LENGTH),
  Schema.isPattern(
    /^data:image\/(?:png|jpeg|gif|webp|avif|svg\+xml|x-icon|vnd\.microsoft\.icon);base64,[A-Za-z0-9+/]+={0,2}$/,
  ),
);
const Entry = Schema.Struct({
  environmentId: EnvironmentId,
  cwd: Schema.String,
  faviconPath: Schema.NullOr(Schema.String),
  revision: Schema.String,
  dataUrl: ImageDataUrl,
});
export type ProjectFaviconEntry = typeof Entry.Type;
const decodeEntry = Schema.decodeUnknownOption(Entry);
const isImageDataUrl = Schema.is(ImageDataUrl);

function keyFor(target: ProjectFaviconTarget) {
  return getProjectFaviconResourceKey(target.environmentId, target.cwd, target.faviconPath);
}

export interface ProjectFaviconStorage {
  readonly list: () => Promise<ReadonlyArray<unknown>>;
  readonly put: (key: string, entry: ProjectFaviconEntry) => Promise<void>;
  readonly remove: (key: string, entry: ProjectFaviconEntry) => Promise<void>;
}

async function readBounded(response: Response, maxBytes: number) {
  const declared = Number(response.headers.get("content-length"));
  if (declared > maxBytes) {
    await response.body?.cancel().catch(() => {});
    throw new Error("Project icon is too large to decode.");
  }
  if (!response.body) {
    const bytes = new Uint8Array<ArrayBuffer>(await response.arrayBuffer());
    if (bytes.byteLength > maxBytes) throw new Error("Project icon is too large to decode.");
    return bytes;
  }
  const reader = response.body.getReader();
  const chunks: Array<Uint8Array> = [];
  let total = 0;
  try {
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      total += value.byteLength;
      if (total > maxBytes) throw new Error("Project icon is too large to decode.");
      chunks.push(value);
    }
  } finally {
    reader.cancel().catch(() => {});
  }
  const bytes = new Uint8Array<ArrayBuffer>(new ArrayBuffer(total));
  let offset = 0;
  for (const chunk of chunks) {
    bytes.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return bytes;
}

/**
 * Larger bitmaps go through the platform downscaler; larger SVGs stay remote because rasterizing
 * them without intrinsic dimensions is unreliable.
 */
export function createProjectFaviconImageLoader(input: {
  readonly fetch?: typeof fetch;
  readonly downscale: (
    image: {
      readonly url: string;
      readonly mimeType: string;
      readonly bytes: Uint8Array<ArrayBuffer>;
    },
    signal: AbortSignal,
  ) => Promise<string>;
}) {
  const fetchImpl = input.fetch ?? globalThis.fetch;
  return async (url: string, signal: AbortSignal): Promise<string> => {
    const response = await fetchImpl(url, { signal });
    if (!response.ok) throw new Error(`Project icon request failed with ${response.status}.`);
    const contentType = response.headers
      .get("content-type")
      ?.split(";", 1)[0]
      ?.trim()
      .toLowerCase();
    const mimeType = contentType?.startsWith("image/") ? contentType : mediaMimeType(url);
    if (!mimeType) throw new Error("Project icon has no image type.");
    const bytes = await readBounded(response, PROJECT_FAVICON_MAX_SOURCE_BYTES);
    signal.throwIfAborted();
    const dataUrl = `data:${mimeType};base64,${Base64.encode(bytes)}`;
    if (isImageDataUrl(dataUrl)) return dataUrl;
    if (mimeType === "image/svg+xml") throw new Error("Project icon exceeds the cache limit.");
    return input.downscale({ url, mimeType, bytes }, signal);
  };
}

export function createProjectFaviconCache(input: {
  readonly storage: ProjectFaviconStorage;
  readonly load: (url: string, signal: AbortSignal) => Promise<string>;
}) {
  const entries = new Map<string, ProjectFaviconEntry>();
  const environmentRevisions = new Map<EnvironmentId, number>();
  let generation = 0;
  let hydration: Promise<void> | undefined;
  let clearing: Promise<void> | undefined;
  const pending = new Set<Promise<void>>();

  const persist = (operation: () => Promise<void>) => {
    const task: Promise<void> = operation()
      .catch(() => {})
      .finally(() => pending.delete(task));
    pending.add(task);
  };

  const remove = (key: string) => {
    const entry = entries.get(key);
    if (!entry) return;
    entries.delete(key);
    persist(() => input.storage.remove(key, entry));
  };

  const trim = () => {
    let bytes = 0;
    for (const entry of entries.values()) bytes += entry.dataUrl.length;
    while (
      entries.size > PROJECT_FAVICON_CACHE_MAX_ENTRIES ||
      bytes > PROJECT_FAVICON_CACHE_MAX_BYTES
    ) {
      const oldest = entries.entries().next().value;
      if (!oldest) break;
      bytes -= oldest[1].dataUrl.length;
      remove(oldest[0]);
    }
  };

  const hydrate = () =>
    (hydration ??= (async () => {
      try {
        for (const record of await input.storage.list()) {
          const entry = decodeEntry(record);
          if (Option.isSome(entry)) entries.set(keyFor(entry.value), entry.value);
        }
        trim();
      } catch {}
    })());

  const peek = (target: ProjectFaviconTarget) => entries.get(keyFor(target))?.dataUrl ?? null;

  const resolve = async (
    target: ProjectFaviconTarget,
    url: string | null,
    signal: AbortSignal,
  ): Promise<string | null> => {
    await clearing;
    const startGeneration = generation;
    const startRevision = environmentRevisions.get(target.environmentId) ?? 0;
    await hydrate();
    if (signal.aborted || url === null) return peek(target);
    const key = keyFor(target);
    if (isProjectFaviconFallbackUrl(url)) {
      remove(key);
      return null;
    }
    const revision = getProjectFaviconCacheKey(target.environmentId, target.cwd, url);
    const cached = entries.get(key);
    if (cached) {
      entries.delete(key);
      entries.set(key, cached);
      if (cached.revision === revision) return cached.dataUrl;
    }
    try {
      const dataUrl = await input.load(url, signal);
      if (
        signal.aborted ||
        startGeneration !== generation ||
        startRevision !== (environmentRevisions.get(target.environmentId) ?? 0)
      ) {
        return peek(target);
      }
      if (isImageDataUrl(dataUrl)) {
        const entry = {
          environmentId: target.environmentId,
          cwd: target.cwd,
          faviconPath: target.faviconPath || null,
          revision,
          dataUrl,
        };
        entries.set(key, entry);
        persist(() => input.storage.put(key, entry));
        trim();
        return dataUrl;
      }
    } catch {}
    return peek(target) ?? url;
  };

  const flush = async () => {
    await Promise.all(pending);
  };

  // A download that started before the clear sees the revision change and is discarded;
  // one that starts during the clear waits for it, so it cannot repopulate storage.
  const clear = async (environmentId?: EnvironmentId) => {
    if (environmentId === undefined) generation += 1;
    else
      environmentRevisions.set(environmentId, (environmentRevisions.get(environmentId) ?? 0) + 1);
    const previous = clearing;
    const task = (async () => {
      await previous;
      await hydrate();
      for (const [key, entry] of entries) {
        if (environmentId === undefined || entry.environmentId === environmentId) remove(key);
      }
      await flush();
    })().finally(() => {
      if (clearing === task) clearing = undefined;
    });
    clearing = task;
    await task;
  };

  return {
    hydrate,
    peek,
    resolve,
    clearEnvironment: (environmentId: EnvironmentId) => clear(environmentId),
    clearAll: () => clear(),
    flush,
  };
}

export type ProjectFaviconCache = ReturnType<typeof createProjectFaviconCache>;