Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

9.5 KB
Raw Blame
import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { LinkPreviewMetadata } from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
  LinkPreviewCache,
  type LinkPreviewCacheOptions,
  type LinkPreviewOutcome,
  normalizePreviewUrl,
} from './preview-cache.ts';

let dir: string;
beforeEach(() => {
  dir = mkdtempSync(join(tmpdir(), 'ok-linkpreview-cache-'));
});
afterEach(() => {
  rmSync(dir, { recursive: true, force: true });
});

function makeCache(over: Partial<LinkPreviewCacheOptions> = {}): LinkPreviewCache {
  return new LinkPreviewCache({ cacheDir: dir, ...over });
}

function ok(domain: string, extra: Partial<LinkPreviewMetadata> = {}): LinkPreviewOutcome {
  return { ok: true, metadata: { domain, ...extra } };
}

function counter(outcome: LinkPreviewOutcome): [() => Promise<LinkPreviewOutcome>, () => number] {
  let n = 0;
  return [
    async () => {
      n += 1;
      return outcome;
    },
    () => n,
  ];
}

const mustNotFetch = async (): Promise<LinkPreviewOutcome> => {
  throw new Error('expected a cache hit, but compute ran');
};

describe('normalizePreviewUrl', () => {
  test('strips the fragment and userinfo, keeps scheme+host+path+query', () => {
    expect(normalizePreviewUrl('https://ex.com/p?q=1#a')).toBe(
      normalizePreviewUrl('https://ex.com/p?q=1#b'),
    );
    expect(normalizePreviewUrl('https://ex.com/p?q=1#frag')).toBe('https://ex.com/p?q=1');
    expect(normalizePreviewUrl('https://user:[email protected]/p')).toBe('https://ex.com/p');
  });

  test('returns null for an unparseable URL', () => {
    expect(normalizePreviewUrl('not a url')).toBeNull();
  });
});

describe('LinkPreviewCache', () => {
  test('success → persist → re-init serves the metadata from disk (round-trip)', async () => {
    const cache = makeCache();
    await cache.init();
    const metadata: LinkPreviewMetadata = {
      domain: 'example.com',
      title: 'Example',
      description: 'A description',
      siteName: 'Example Site',
      faviconDataUri: 'data:image/png;base64,iVBORw0KGgo=',
    };
    await cache.load('https://example.com/page', counter({ ok: true, metadata })[0]);
    await cache.persist();
    expect(existsSync(join(dir, 'manifest.json'))).toBe(true);
    expect(readdirSync(join(dir, 'meta')).length).toBe(1);

    const reopened = makeCache();
    await reopened.init();
    expect(await reopened.load('https://example.com/page#section', mustNotFetch)).toEqual({
      ok: true,
      metadata,
    });
  });

  test('caches a negative outcome and serves it without recomputing', async () => {
    const cache = makeCache();
    await cache.init();
    const first = await cache.load(
      'https://n.com/',
      counter({ ok: false, reason: 'private-ip' })[0],
    );
    expect(first).toEqual({ ok: false, reason: 'private-ip' });

    const [compute, calls] = counter(ok('n.com'));
    expect(await cache.load('https://n.com/', compute)).toEqual({
      ok: false,
      reason: 'private-ip',
    });
    expect(calls()).toBe(0);
  });

  test('a success past its TTL is a miss and recomputes', async () => {
    let clock = 1_000_000;
    const cache = makeCache({ successTtlMs: 5000, now: () => clock });
    await cache.init();
    const [first, firstCalls] = counter(ok('s.com'));
    await cache.load('https://s.com/', first);
    expect(firstCalls()).toBe(1);

    const [withinTtl, withinCalls] = counter(ok('s.com'));
    await cache.load('https://s.com/', withinTtl);
    expect(withinCalls()).toBe(0);

    clock += 6000;
    const [afterTtl, afterCalls] = counter(ok('s.com'));
    await cache.load('https://s.com/', afterTtl);
    expect(afterCalls()).toBe(1);
  });

  test('a negative past its short TTL recomputes so a dead link recovers', async () => {
    let clock = 1_000_000;
    const cache = makeCache({ negativeTtlMs: 1000, now: () => clock });
    await cache.init();
    await cache.load('https://nt.com/', counter({ ok: false, reason: 'timeout' })[0]);

    clock += 2000;
    const [compute, calls] = counter(ok('nt.com'));
    expect(await cache.load('https://nt.com/', compute)).toEqual(ok('nt.com'));
    expect(calls()).toBe(1);
  });

  test('coalesces concurrent identical lookups into a single compute (single-flight)', async () => {
    const cache = makeCache();
    await cache.init();
    const { promise: gate, resolve: resolveGate } = Promise.withResolvers<LinkPreviewOutcome>();
    let calls = 0;
    const compute = () => {
      calls += 1;
      return gate;
    };

    const p1 = cache.load('https://x.com/', compute);
    const p2 = cache.load('https://x.com/', compute);
    resolveGate(ok('x.com'));
    const [r1, r2] = await Promise.all([p1, p2]);

    expect(calls).toBe(1);
    expect(r1).toEqual(ok('x.com'));
    expect(r2).toEqual(ok('x.com'));
  });

  test('clears the in-flight slot when compute throws (no stuck key, no caching)', async () => {
    const cache = makeCache();
    await cache.init();
    await expect(
      cache.load('https://y.com/', async () => {
        throw new Error('boom');
      }),
    ).rejects.toThrow('boom');

    const [compute, calls] = counter(ok('y.com'));
    expect(await cache.load('https://y.com/', compute)).toEqual(ok('y.com'));
    expect(calls()).toBe(1);
  });

  test('evicts the least-recently-used entry past the size cap', async () => {
    const cache = makeCache({ maxEntries: 2 });
    await cache.init();
    await cache.load('https://a.com/', counter(ok('a.com'))[0]);
    await cache.load('https://b.com/', counter(ok('b.com'))[0]);
    await cache.load('https://c.com/', counter(ok('c.com'))[0]);
    expect(cache.size).toBe(2);

    const [reA, reACalls] = counter(ok('a.com'));
    await cache.load('https://a.com/', reA);
    expect(reACalls()).toBe(1);

    await cache.load('https://c.com/', mustNotFetch);

    await cache.persist();
    expect(readdirSync(join(dir, 'meta')).length).toBe(2);
  });

  test('a hit bumps recency so the next eviction drops the older un-accessed key', async () => {
    const cache = makeCache({ maxEntries: 2 });
    await cache.init();
    await cache.load('https://a.com/', counter(ok('a.com'))[0]);
    await cache.load('https://b.com/', counter(ok('b.com'))[0]);
    await cache.load('https://a.com/', mustNotFetch);
    await cache.load('https://c.com/', counter(ok('c.com'))[0]);

    await cache.load('https://a.com/', mustNotFetch);
    const [reB, reBCalls] = counter(ok('b.com'));
    await cache.load('https://b.com/', reB);
    expect(reBCalls()).toBe(1);
  });

  test('a corrupt manifest is treated as empty and never throws', async () => {
    writeFileSync(join(dir, 'manifest.json'), 'not-json{{{');
    const cache = makeCache();
    await cache.init();
    expect(cache.size).toBe(0);

    const [compute, calls] = counter(ok('c.com'));
    await cache.load('https://c.com/', compute);
    expect(calls()).toBe(1);
  });

  test('a success blob that no longer matches the schema drops the entry', async () => {
    const cache = makeCache();
    await cache.init();
    await cache.load('https://b.com/page', counter(ok('b.com'))[0]);
    await cache.persist();
    const [blob] = readdirSync(join(dir, 'meta'));
    writeFileSync(join(dir, 'meta', blob as string), '{"unexpected":true}');

    const reopened = makeCache();
    await reopened.init();
    const [compute, calls] = counter(ok('b.com'));
    await reopened.load('https://b.com/page', compute);
    expect(calls()).toBe(1);
  });

  test('drops an already-expired entry on init (no resurrection)', async () => {
    let clock = 1_000_000;
    const cache = makeCache({ negativeTtlMs: 1000, now: () => clock });
    await cache.init();
    await cache.load('https://g.com/', counter({ ok: false, reason: 'timeout' })[0]);
    await cache.persist();

    clock += 2000;
    const reopened = makeCache({ negativeTtlMs: 1000, now: () => clock });
    await reopened.init();
    expect(reopened.size).toBe(0);
    const [compute, calls] = counter(ok('g.com'));
    await reopened.load('https://g.com/', compute);
    expect(calls()).toBe(1);
  });

  test('memory-only mode (cacheDir null) caches in memory and never touches disk', async () => {
    const cache = new LinkPreviewCache({ cacheDir: null });
    await cache.init();
    const [compute, calls] = counter(ok('m.com'));
    await cache.load('https://m.com/', compute);
    await cache.load('https://m.com/', compute);
    expect(calls()).toBe(1);
    await expect(cache.persist()).resolves.toBeUndefined();
    expect(readdirSync(dir).length).toBe(0);
  });

  test('wipe clears memory and the on-disk cache directory', async () => {
    const cache = makeCache();
    await cache.init();
    await cache.load('https://w.com/', counter(ok('w.com'))[0]);
    await cache.persist();
    expect(existsSync(join(dir, 'manifest.json'))).toBe(true);

    await cache.wipe();
    expect(existsSync(dir)).toBe(false);

    const [compute, calls] = counter(ok('w.com'));
    await cache.load('https://w.com/', compute);
    expect(calls()).toBe(1);
  });

  test('persist is best-effort when the cache directory is unwritable', async () => {
    const blocker = join(dir, 'blocker');
    writeFileSync(blocker, 'x');
    const cache = new LinkPreviewCache({ cacheDir: join(blocker, 'nested') });
    await cache.init();

    await cache.load('https://e.com/', counter(ok('e.com'))[0]);
    await expect(cache.persist()).resolves.toBeUndefined();

    const [compute, calls] = counter(ok('e.com'));
    expect(await cache.load('https://e.com/', compute)).toEqual(ok('e.com'));
    expect(calls()).toBe(0);
  });
});