Skip to content

Commit 26c192d

Browse files
dev-seth-vapidvsth
andauthored
docs: speed up publishing with a Fern example cache (#1225)
* docs: cache Fern API property examples across builds * docs: include external reference base in example cache keys * docs: cache request examples with stable typed input keys * docs: preserve warm caches across generated build outputs --------- Co-authored-by: dev-seth-vapi <dev@devseth.com>
1 parent 29ee1f9 commit 26c192d

10 files changed

Lines changed: 389 additions & 12 deletions

File tree

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Set up Fern with an example cache
2+
description: Install the pinned CLI and restore generated API examples without skipping validation.
3+
runs:
4+
using: composite
5+
steps:
6+
- uses: actions/setup-node@v4
7+
with:
8+
node-version: 22.22.2
9+
- name: Install pinned Fern
10+
shell: bash
11+
run: |
12+
npm install --prefix "$RUNNER_TEMP/vapi-fern" --no-save --no-audit --no-fund fern-api@5.112.0
13+
echo "FERN_CLI_PATH=$RUNNER_TEMP/vapi-fern/node_modules/fern-api/cli.cjs" >> "$GITHUB_ENV"
14+
- name: Test cache safeguards
15+
shell: bash
16+
run: node --test scripts/fern/example-cache.test.cjs
17+
- uses: actions/cache@v4
18+
with:
19+
path: .cache/fern-examples
20+
key: fern-examples-v1-${{ runner.os }}-${{ runner.arch }}-node22.22.2-${{ hashFiles('fern/apis/**', 'fern/fern.config.json', 'scripts/fern/run.cjs', 'scripts/fern/example-cache.cjs', 'scripts/fern/register.cjs') }}-${{ github.run_id }}-${{ github.run_attempt }}
21+
restore-keys: |
22+
fern-examples-v1-${{ runner.os }}-${{ runner.arch }}-node22.22.2-${{ hashFiles('fern/apis/**', 'fern/fern.config.json', 'scripts/fern/run.cjs', 'scripts/fern/example-cache.cjs', 'scripts/fern/register.cjs') }}-

‎.github/workflows/check.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@ jobs:
1313
- name: Checkout repository
1414
uses: actions/checkout@v4
1515

16-
- name: Install Fern
17-
run: npm install -g fern-api
16+
- uses: ./.github/actions/setup-fern
1817

1918
- name: Check API is valid
20-
run: fern check
19+
run: node scripts/fern/run.cjs check

‎.github/workflows/preview-docs.yml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,21 @@ jobs:
1010
- name: Checkout repository
1111
uses: actions/checkout@v4
1212

13-
- name: Install Fern
14-
run: npm install -g fern-api
13+
- uses: ./.github/actions/setup-fern
1514

1615
- name: Generate preview URL
1716
id: generate-docs
1817
env:
1918
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
2019
POSTHOG_PROJECT_API_KEY: ${{ secrets.POSTHOG_PROJECT_API_KEY }}
2120
run: |
22-
OUTPUT=$(fern generate --docs --preview --log-level debug 2>&1) || true
23-
echo "$OUTPUT"
24-
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
21+
set -euo pipefail
22+
node scripts/fern/run.cjs generate --docs --preview --log-level debug 2>&1 | tee "$RUNNER_TEMP/fern-preview.log"
23+
URL=$(grep -oP 'Published docs to \K.*(?= \()' "$RUNNER_TEMP/fern-preview.log")
2524
echo "Preview URL: $URL"
2625
echo "🌿 Preview your docs: $URL" > preview_url.txt
2726
2827
- name: Comment URL in PR
2928
uses: thollander/actions-comment-pull-request@v2.4.3
3029
with:
31-
filePath: preview_url.txt
30+
filePath: preview_url.txt

‎.github/workflows/publish-docs.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,10 @@ jobs:
1313
- name: Checkout repository
1414
uses: actions/checkout@v4
1515

16-
- name: Install Fern
17-
run: npm install -g fern-api
16+
- uses: ./.github/actions/setup-fern
1817

1918
- name: Publish Docs
2019
env:
2120
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
2221
POSTHOG_PROJECT_API_KEY: ${{ secrets.POSTHOG_PROJECT_API_KEY }}
23-
run: fern generate --docs --log-level debug
22+
run: node scripts/fern/run.cjs generate --docs --log-level debug

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ dist/
55
.env
66
.DS_Store
77
.tool-versions
8+
.cache/
89

910
# Fern AI-generated examples (regenerated on each build; not committed)
1011
fern/apis/api/ai_examples_override.yml

‎scripts/fern/README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Fern example cache
2+
3+
Fern 5.112.0 repeatedly generates examples for nested API properties during
4+
validation and publication. The GPT-Live docs publish spent about 24 minutes
5+
preparing validation and another 25 minutes building the API navigation. Its
6+
final deployment took six seconds.
7+
8+
This adapter caches the exact return values of Fern's property and request/response
9+
example generators.
10+
It does not remove fields, shorten examples, skip schema checks, disable SDK
11+
snippets, or change the API playground. Changes are confined to this docs repo.
12+
13+
## How it works
14+
15+
- A cold miss invokes the unmodified property-example generator.
16+
- Successful values are stored with V8 serialization, preserving `undefined`
17+
values that JSON would discard. Each entry has a checksum and is written
18+
atomically. Every read returns an independent object.
19+
- Any call that reports a diagnostic through Fern's error collector is not
20+
cached. Exceptions still fail the build. Unreadable or corrupt entries are
21+
regenerated normally.
22+
- The cache namespace includes API source files under `fern/apis`, the Fern config,
23+
adapter implementation, exact CLI checksum, Node/V8 versions, OS, and CPU
24+
architecture. Each entry also includes the resolved API spec, parser settings,
25+
example settings, schema, property ID, and breadcrumbs. Markdown changes do
26+
not invalidate API examples. Fern's generated `.definition` directories and
27+
`ai_examples_override.yml` files do not invalidate the source fingerprint.
28+
Actual resolved examples and overrides remain part of each entry key.
29+
- GitHub Actions restores only caches with the same API/tooling fingerprint.
30+
Each successful run saves a new snapshot, so additional examples generated
31+
during publishing can extend the validation cache. It never falls back to
32+
different API inputs. The first build for new inputs fills the cache.
33+
34+
## Maintenance and escape hatch
35+
36+
This is a small, version-specific adapter to Fern's bundled CLI, not a public
37+
Fern extension API. `run.cjs` verifies the complete official CLI SHA-256 and the
38+
two expected function signatures before adding the wrappers. An unexpected
39+
version or bundle fails before publishing. Upgrading Fern requires reviewing the
40+
adapter and repeating the output and timing checks.
41+
42+
To bypass the cache, invoke the installed Fern CLI directly. No source schema or
43+
published content needs to change. Removing the setup action and restoring the
44+
original Fern commands also removes this optimization.
45+
46+
## Local verification
47+
48+
```sh
49+
npm install --prefix /tmp/vapi-fern --no-save fern-api@5.112.0
50+
export FERN_CLI_PATH=/tmp/vapi-fern/node_modules/fern-api/cli.cjs
51+
node --test scripts/fern/example-cache.test.cjs
52+
node scripts/fern/run.cjs check --local --log-level debug
53+
node scripts/fern/run.cjs generate --docs --preview --log-level debug
54+
```
55+
56+
Only use `--preview` for verification. Production publishing remains in the
57+
existing main-branch workflow. Logs print cache hits, misses, and uncached
58+
diagnostic-producing calls at exit.
59+
60+
## Measured validation results
61+
62+
On the same machine and API inputs, the original generators took 697 seconds
63+
in docs validation setup. A fresh process using the cache took 6.9 seconds,
64+
with 2,266 hits and zero misses. Both complete local checks reported zero errors
65+
and 11 warnings, with identical warning text. The cached full check took about
66+
15 seconds. This measures validation, not end-to-end publication.
67+
68+
Two complete preview publications took approximately 47 and 49 seconds, with
69+
4,532 cache hits and zero misses each. Both used the normal publishing flags,
70+
including dynamic SDK snippets. Browser checks covered the guide, API reference,
71+
request examples, and API Explorer form. These are local timings, not CI timings.
72+
A first build after API or tooling changes still pays the original generation
73+
cost before populating the cache.

‎scripts/fern/example-cache.cjs‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
const crypto = require('node:crypto');
2+
const fs = require('node:fs');
3+
const path = require('node:path');
4+
const v8 = require('node:v8');
5+
6+
const digest = (value) => crypto.createHash('sha256').update(value).digest('hex');
7+
8+
// V8 serialization preserves values but is not a canonical encoding for keys.
9+
// Tag every value so undefined, null, NaN, and user-authored objects cannot collide.
10+
function fingerprint(value) {
11+
const ancestors = new Set();
12+
function encode(value) {
13+
if (value === null) return ['null'];
14+
if (value === undefined) return ['undefined'];
15+
if (typeof value === 'string' || typeof value === 'boolean') return [typeof value, value];
16+
if (typeof value === 'number') return ['number', Object.is(value, -0) ? '-0' : String(value)];
17+
if (typeof value !== 'object') throw new Error('Unsupported cache input');
18+
if (value instanceof Date) return ['date', value.toISOString()];
19+
if (ancestors.has(value)) throw new Error('Cyclic cache input');
20+
ancestors.add(value);
21+
try {
22+
if (Array.isArray(value)) return ['array', Array.from({ length: value.length }, (_, i) => Object.hasOwn(value, i) ? encode(value[i]) : ['hole'])];
23+
if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error('Unsupported cache input prototype');
24+
return ['object', Object.keys(value).sort().map((key) => [key, encode(value[key])])];
25+
} finally {
26+
ancestors.delete(value);
27+
}
28+
}
29+
return digest(JSON.stringify(encode(value)));
30+
}
31+
32+
// Cache only return values of Fern's property and request/response example generators. API parsing,
33+
// schema validation, markdown validation, and deployment still run normally.
34+
function createExampleCache({ directory, namespace }) {
35+
const contexts = new WeakMap();
36+
const stats = { hits: 0, misses: 0, skipped: 0 };
37+
38+
function contextKey(context) {
39+
let key = contexts.get(context);
40+
if (key !== undefined) return key;
41+
const {
42+
spec, settings, generationLanguage, smartCasing, namespace: apiNamespace,
43+
exampleGenerationArgs, authOverrides, environmentOverrides,
44+
globalHeaderOverrides, enableUniqueErrorsPerEndpoint, generateV1Examples,
45+
documentBaseDir,
46+
} = context;
47+
key = fingerprint({
48+
spec, settings, generationLanguage, smartCasing, namespace: apiNamespace,
49+
exampleGenerationArgs, authOverrides, environmentOverrides,
50+
globalHeaderOverrides, enableUniqueErrorsPerEndpoint, generateV1Examples,
51+
documentBaseDir,
52+
});
53+
contexts.set(context, key);
54+
return key;
55+
}
56+
57+
function run(args, generate) {
58+
const { context, ...inputs } = args;
59+
let file;
60+
try {
61+
file = path.join(directory, namespace, contextKey(context), `${fingerprint(inputs)}.bin`);
62+
} catch {
63+
stats.skipped++;
64+
return generate();
65+
}
66+
try {
67+
const entry = fs.readFileSync(file);
68+
const payload = entry.subarray(65);
69+
if (entry[64] !== 10 || entry.subarray(0, 64).toString() !== digest(payload)) throw new Error('Invalid cache checksum');
70+
const result = v8.deserialize(payload);
71+
stats.hits++;
72+
return result;
73+
} catch {
74+
// A missing, stale, or corrupt cache is a normal cold build.
75+
}
76+
stats.misses++;
77+
const collector = context.errorCollector;
78+
const owned = Object.hasOwn(collector, 'collect');
79+
const collect = collector.collect;
80+
let clean = true;
81+
collector.collect = function (...values) {
82+
clean = false;
83+
return collect.apply(this, values);
84+
};
85+
let result;
86+
try {
87+
result = generate();
88+
} finally {
89+
if (owned) collector.collect = collect;
90+
else delete collector.collect;
91+
}
92+
// Never suppress diagnostics on subsequent builds.
93+
if (!clean) {
94+
stats.skipped++;
95+
return result;
96+
}
97+
const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
98+
try {
99+
const payload = v8.serialize(result);
100+
fs.mkdirSync(path.dirname(file), { recursive: true });
101+
fs.writeFileSync(temporary, Buffer.concat([Buffer.from(`${digest(payload)}\n`), payload]));
102+
fs.renameSync(temporary, file);
103+
} catch {
104+
// Cache storage must not make an otherwise valid build fail.
105+
try { fs.unlinkSync(temporary); } catch {}
106+
}
107+
return result;
108+
}
109+
110+
return { run, stats };
111+
}
112+
113+
module.exports = { createExampleCache, digest, fingerprint };
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
const test = require('node:test');
2+
const assert = require('node:assert/strict');
3+
const fs = require('node:fs');
4+
const os = require('node:os');
5+
const path = require('node:path');
6+
const { createExampleCache, fingerprint } = require('./example-cache.cjs');
7+
const { inputDigest } = require('./run.cjs');
8+
9+
function fixture(t) {
10+
const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'fern-cache-test-'));
11+
t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
12+
const errors = [];
13+
const context = {
14+
spec: { components: { schemas: { Voice: { type: 'string', enum: ['marin'] } } } },
15+
settings: {},
16+
errorCollector: { collect(value) { errors.push(value); } },
17+
};
18+
const args = { context, propertySchema: { $ref: '#/components/schemas/Voice' }, breadcrumbs: ['voice'], propertyId: 'voice' };
19+
return { directory, context, args, errors, cache: createExampleCache({ directory, namespace: 'test' }) };
20+
}
21+
22+
test('a new process can reuse an exact result without sharing mutable objects', (t) => {
23+
const { directory, args, cache } = fixture(t);
24+
const expected = { userSpecifiedExamples: {}, autogeneratedExamples: { voice: { value: 'marin', missing: undefined } } };
25+
assert.deepEqual(cache.run(args, () => expected), expected);
26+
expected.autogeneratedExamples.voice.value = 'changed after conversion';
27+
const next = createExampleCache({ directory, namespace: 'test' });
28+
const hit = next.run(args, () => { throw new Error('must be a cache hit'); });
29+
assert.equal(hit.autogeneratedExamples.voice.value, 'marin');
30+
assert.ok(Object.hasOwn(hit.autogeneratedExamples.voice, 'missing'));
31+
hit.autogeneratedExamples.voice.value = 'changed after cache read';
32+
assert.equal(next.run(args, () => assert.fail()).autogeneratedExamples.voice.value, 'marin');
33+
});
34+
35+
test('schemas, parser settings, property inputs, and namespaces invalidate entries', (t) => {
36+
const { directory, args, cache } = fixture(t);
37+
cache.run(args, () => 'old');
38+
for (const context of [
39+
{ ...args.context, spec: { changed: true } },
40+
{ ...args.context, settings: { changed: true } },
41+
{ ...args.context, generationLanguage: 'python' },
42+
{ ...args.context, smartCasing: true },
43+
{ ...args.context, documentBaseDir: '/different-reference-base' },
44+
]) assert.equal(cache.run({ ...args, context }, () => 'new'), 'new');
45+
assert.equal(cache.run({ ...args, propertySchema: { type: 'number' } }, () => 'new'), 'new');
46+
assert.equal(createExampleCache({ directory, namespace: 'new-version' }).run(args, () => 'new'), 'new');
47+
});
48+
49+
test('diagnostics are emitted on every run and the collector is restored', (t) => {
50+
const { args, context, errors, cache } = fixture(t);
51+
const original = context.errorCollector.collect;
52+
for (let i = 0; i < 2; i++) {
53+
cache.run(args, () => { context.errorCollector.collect('invalid example'); return {}; });
54+
assert.equal(context.errorCollector.collect, original);
55+
}
56+
assert.deepEqual(errors, ['invalid example', 'invalid example']);
57+
assert.equal(cache.stats.hits, 0);
58+
});
59+
60+
test('generation errors propagate and do not poison the cache', (t) => {
61+
const { args, context, cache } = fixture(t);
62+
const original = context.errorCollector.collect;
63+
assert.throws(() => cache.run(args, () => { throw new Error('invalid schema'); }), /invalid schema/);
64+
assert.equal(context.errorCollector.collect, original);
65+
assert.equal(cache.run(args, () => 'recovered'), 'recovered');
66+
});
67+
68+
test('cache keys preserve null, undefined, and non-JSON numeric values', (t) => {
69+
const { args, cache } = fixture(t);
70+
for (const example of [null, undefined, NaN, Infinity]) {
71+
const inputs = { ...args, mediaExampleArgs: { example } };
72+
assert.deepEqual(cache.run(inputs, () => ({ example })), { example });
73+
assert.deepEqual(cache.run(inputs, () => assert.fail()), { example });
74+
}
75+
assert.equal(cache.stats.misses, 4);
76+
assert.equal(cache.stats.hits, 4);
77+
});
78+
79+
test('fingerprints are stable across key order and shared object identities', () => {
80+
const shared = { text: 'hello', number: 3 };
81+
assert.equal(fingerprint({ a: shared, b: shared }), fingerprint({ b: { number: 3, text: 'hello' }, a: { text: 'hello', number: 3 } }));
82+
assert.notEqual(fingerprint([undefined]), fingerprint(Array(1)));
83+
assert.notEqual(fingerprint(NaN), fingerprint(['number', 'NaN']));
84+
});
85+
86+
test('corrupt entries fall back to original generation', (t) => {
87+
const { directory, args, cache } = fixture(t);
88+
cache.run(args, () => 'old');
89+
const contextDirectory = path.join(directory, 'test', fs.readdirSync(path.join(directory, 'test'))[0]);
90+
fs.writeFileSync(path.join(contextDirectory, fs.readdirSync(contextDirectory)[0]), 'corrupt');
91+
assert.equal(cache.run(args, () => 'regenerated'), 'regenerated');
92+
});
93+
94+
test('all local API inputs invalidate the cache but prose does not', (t) => {
95+
const { directory } = fixture(t);
96+
fs.mkdirSync(path.join(directory, 'fern/apis/api'), { recursive: true });
97+
fs.writeFileSync(path.join(directory, 'fern/fern.config.json'), '{"version":"5.112.0"}');
98+
fs.writeFileSync(path.join(directory, 'fern/apis/api/openapi.json'), '{}');
99+
const before = inputDigest(directory);
100+
fs.writeFileSync(path.join(directory, 'fern/overview.mdx'), 'new prose');
101+
assert.equal(inputDigest(directory), before);
102+
fs.writeFileSync(path.join(directory, 'fern/apis/api/ai_examples_override.yml'), 'generated output');
103+
assert.equal(inputDigest(directory), before);
104+
fs.writeFileSync(path.join(directory, 'fern/apis/api/overrides.yml'), 'new schema override');
105+
assert.notEqual(inputDigest(directory), before);
106+
});

‎scripts/fern/register.cjs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
const { createExampleCache } = require('./example-cache.cjs');
2+
const cache = createExampleCache({ directory: process.env.VAPI_FERN_CACHE_DIR, namespace: process.env.VAPI_FERN_CACHE_NAMESPACE });
3+
globalThis.__vapiFernExamples = cache.run;
4+
process.on('exit', () => console.error('[fern-example-cache]', JSON.stringify(cache.stats)));

0 commit comments

Comments
 (0)