<

Rewriting LibrExam’s indexer (and most of the app)

on 28 October, 2026

A few days ago, I pushed the first substantial set of changes to LibrExam in over a year. The bulk of it went into a single commit touching 56 files, which reworked the storage layer, the results page and most of the interface; a complete rewrite of the indexer in librexamtests followed shortly after.

I have previously written about how LibrExam uses GitHub to distribute tests, along with a list of everything wrong with that approach. Most of that list has now been dealt with, and the fixes - along with a few problems I only discovered while making them - are documented here.

I have omitted the interface changes; they are better seen than described.

The indexer

The basic idea remains the same: authors tag their repos with the librexam-test topic, and a GitHub Actions workflow in my repo periodically searches for them. Everything around that search, however, has been rewritten.

The workflow now runs every 30 minutes, inside a concurrency group, so that two runs can never overlap. It also authenticates with the GITHUB_TOKEN that every workflow is given, which raises the search limit from 10 requests a minute to 30. Results are paged through 100 at a time, for at most 10 pages; GitHub does not return more than 1,000 results for a single search anyway, and LibrExam is (comfortably) nowhere near that number.

For every repo it finds, the indexer then:

  1. Skips it if it is a fork, archived, or listed in my blocklist.json.
  2. Fetches its index.json from the repo’s actual default branch.
  3. Rejects any entry whose url is not an https:// link.
  4. Downloads every test in that index and validates it (more on that below).
  5. Writes everything that survived into a single, flat tests.json.

Each entry in tests.json carries everything the browser needs to display a test, so the browser never has to look at the repo itself. A (trimmed) entry looks like this:

{
  "name": "LibrExam Sample Test",
  "filename": "test1.json",
  "author": "Sayak",
  "duration": 5400,
  "tags": ["sample", "physics", "chemistry", "mathematics", "jee"],
  "url": "https://raw.githubusercontent.com/librexam/testRepo/main/tests/test1.json",
  "repo": "librexam/testRepo",
  "updated_at": "2026-10-26T11:34:57Z",
  "stargazers_count": 2
}

Writes are atomic: each file is first written to a .tmp file, which is then renamed over the real one. A run that fails halfway through, therefore, can never leave a half-written index behind.

function writeJson(file, data) {
  fs.writeFileSync(`${file}.tmp`, JSON.stringify(data, null, 2) + "\n");
  fs.renameSync(`${file}.tmp`, file);
}

The indexer also refuses to overwrite a non-empty index with an empty one. If a search suddenly returns zero repos when the previous run found some, it is far more likely that GitHub is having a bad day than that every test repo vanished at once; the run simply fails, and the old index stays.

Committing only when something changes

Previously, the index was rewritten with a fresh timestamp on every run, whether or not anything had changed. Now, a commit is only made if the index actually differs from the last one:

if ! git diff --cached --quiet; then
  git commit -m "Update test index"
else
  last=$(git log -1 --format=%ct)
  if [ $(( $(date +%s) - last )) -gt $(( 50 * 86400 )) ]; then
    git commit --allow-empty -m "Keepalive (index unchanged)"
  else
    exit 0
  fi
fi

The second branch exists for a slightly odd reason: GitHub disables scheduled workflows in public repos after 60 days without any activity. If nothing has changed for 50 days, the workflow therefore makes an empty commit, purely to keep itself scheduled.

One request per visit

Previously, every visitor’s browser fetched the central list of repos, and then the index.json of each repo in it. This is a textbook N+1 problem; with five hundred repos, it would have meant five hundred and one requests for every single visit. Since the indexer now does the crawling, the browser only needs to fetch tests.json.

The old per-repo approach has been kept, but only as a fallback:

const list = (await loadFromTestsIndex()) || (await loadFromRepos());

It now also uses each repo’s default_branch, instead of assuming that every repo’s branch is called main.

Falling back to jsDelivr

Every file LibrExam loads still comes from raw.githubusercontent.com. However, any such URL can be mechanically rewritten into a jsDelivr URL for the exact same file:

function sourcesFor(url) {
  const m = url.match(
    /^https:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/,
  );
  if (!m) return [url];
  const [, user, repo, ref, path] = m;
  const mirror = `https://cdn.jsdelivr.net/gh/${user}/${repo}@${ref}/${path}`;
  return preferMirror ? [mirror, url] : [url, mirror];
}

Each source is given 10 seconds (through an AbortController) before the next one is tried. If the mirror ends up answering, preferMirror is set, and the mirror is asked first for the remainder of the session; there is little point in waiting ten seconds for an unresponsive GitHub on every single request. jsDelivr does have caching of its own, so the mirror may occasionally be slightly behind - which is still preferable to it not being there at all.

Validation

Every test now passes through a single validateTest() function, which is the exact same code in both the indexer and the app. Problems are sorted into two kinds:

None of this happens silently, either. Every error and warning is recorded in a problems array alongside the tests in tests.json, so an author can see exactly why their test did not appear. At the time of writing, one of the two indexed tests has an answer pointing to a fifth option that does not exist.

Together with the blocklist and the fork/archive filter, this goes some way towards addressing the concern of unmoderated content. It does not solve it; it does, however, make it manageable.

Is the marking any closer to JEE Advanced?

Somewhat. The old version did award partial marks for multiple-correct questions - one mark per correct option picked - but this was the only scheme available, it was buried inside the results page’s view code, and it counted a partially correct answer as simply “correct” in the statistics.

Scoring now lives in its own module, partially correct answers have their own partial status, and each section (or question, which overrides its section) can choose a partial mode: perOption, proportional or none.

For an MMCQ, picking even one wrong option results in -negM, and picking every correct option results in posM. If only some of the correct options are picked, the mode decides:

const mode = q.partial ?? section.partial ?? "perOption";
if (mode === "none") return { status: "incorrect", marks: 0 };
if (mode === "proportional") {
  const marks = Math.round((posM * hits * 100) / correct.size) / 100;
  return { status: "partial", marks };
}
return { status: "partial", marks: hits };

perOption remains the default, since it is roughly what JEE Advanced does; proportional awards that fraction of the full marks instead, and none awards a flat zero.

Numerical questions can also have a tolerance now. Previously, an answer had to match exactly, so 1.414 against an answer of 1.4142 was simply marked wrong. The tolerance is padded internally by 1e-9, since 0.1 + 0.2 === 0.3 evaluates to false in JavaScript, and a student should not lose marks to floating-point arithmetic.

Storage

This is where most of those 56 files went.

Previously, every attempt - paused or submitted - was kept in a single localStorage key, librexam_test_history, as a snapshot that included the entire test. Attempting the same test five times meant storing five copies of it (six, counting the current attempt, which was saved separately as well). The whole array was also serialised and written out again every time progress was saved. Browsers usually give a site around 5 MB of localStorage, and the old code did not handle running out of it at all.

Now, every test is hashed with cyrb53 - a small, fast, non-cryptographic 53-bit string hash - and stored exactly once, under librexam_test_<hash>. An attempt, stored under librexam_attempt_<id>, only keeps its answers, timings and a testHash pointing back to its test. Collisions are not a realistic concern at this scale, and there is nobody to defend against here.

Tests that are no longer referenced by any attempt are then garbage collected, in a mark-and-sweep fashion:

export function removeUnusedTests() {
  const used = new Set();
  for (const key of keysWithPrefix(ATTEMPT_PREFIX))
    used.add(readJson(key)?.testHash);
  used.add(readJson(CURRENT_KEY)?.testHash);

  for (const key of keysWithPrefix(TEST_PREFIX)) {
    const hash = key.slice(TEST_PREFIX.length);
    if (!used.has(hash)) {
      localStorage.removeItem(key);
      testCache.delete(hash);
    }
  }
}

Old saves are migrated automatically the first time the new version is opened: each snapshot has its test hashed and split out, after which librexam_test_history is deleted. If storage does still fill up, every progress save now goes through safeSet(), which catches the failure and asks the user (once) to export a backup from Your Data and delete some old attempts.

While working on this, I also found that downloaded tests were being cached under their file name alone - json-${filename}. Two different repos with a test1.json each would, therefore, quietly overwrite each other; the sample repo’s test is, of course, named test1.json. The cache key now includes the repo as well.

Working offline

LibrExam now registers a service worker. On install, it fetches the app’s index.html, extracts every src and href from it with a regular expression, and caches all of them. (Parsing HTML with a regular expression is generally a bad idea; for a single file whose structure I control, it is an acceptable one.)

After that:

The service worker only handles LibrExam’s own files, though, and question images are hosted elsewhere. To cover those, LibrExam creates an Image() for every image and simage URL in a test the moment it is loaded, so the browser has downloaded (and cached) all of them before the test even begins. Losing one’s connection halfway through a test, then, no longer means losing the diagrams as well.

What is still missing

If you would like to host tests of your own, an index.json at the root of a repo (and a valid test or two) along with the librexam-test topic are all it takes for them to show up.

Happy testing.