Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
5155f1c
Fix nested relationship selection filters and pagination
kylebernhardy Oct 18, 2026
e31bbdb
Close nested query validation and cancellation gaps
kylebernhardy Oct 18, 2026
0b6739f
Preserve absent foreign keys under zero relationship limits
kylebernhardy Oct 18, 2026
006c9c8
Keep projection-only bracket syntax compatible
kylebernhardy Oct 18, 2026
a08662b
Close nested selections when their parent query ends
kylebernhardy Oct 18, 2026
711eaab
Resolve asynchronous nested projection arrays
kylebernhardy Oct 18, 2026
f56d77b
Pin permission and nested join review controls
kylebernhardy Oct 18, 2026
96fb3b8
Fix nested selection composition and cancellation
kylebernhardy Oct 19, 2026
a3cbfbe
Exercise exact nested relationship documentation examples in CI
kylebernhardy Oct 19, 2026
4456075
Check documentation contract parity with the companion repository
kylebernhardy Oct 19, 2026
d3db946
Discriminate nested window and sort guidance contracts
kylebernhardy Oct 19, 2026
6d28dda
test: harden documentation fixture checks and cover nested OR pages
kylebernhardy Oct 19, 2026
0bfccec
test: isolate fixtures and preserve HTTP failures during cleanup
kylebernhardy Oct 19, 2026
8b2f0aa
fix: classify malformed nested operators as client errors
kylebernhardy Oct 20, 2026
76fb612
fix: mark table read transaction helper internal
kylebernhardy Oct 26, 2026
115e382
Merge main into nested relationship constraints
kylebernhardy Oct 26, 2026
7b2778f
Stop pending relationship lookups after selection cancellation
kylebernhardy Oct 26, 2026
87847a3
Merge main while preserving nested relationship query behavior
kylebernhardy Oct 27, 2026
9ad33e1
Trim repeated resource guide introduction to fit merged documentation…
kylebernhardy Oct 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 155 additions & 0 deletions .github/scripts/github-fixture-fetch.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
import { test } from 'node:test';
import assert from 'node:assert';
import { createServer } from 'node:http';
import {
discardBody,
githubHeaders,
peerRevision,
readGitHubText,
} from '../../integrationTests/resources/nested-relationship-docs/github-fixture-fetch.mjs';

async function withServer(handler, run) {
const server = createServer(handler);
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
try {
await run('http://127.0.0.1:' + server.address().port + '/fixture');
} finally {
server.closeAllConnections();
await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
}
}

test('credentials are attached only to the exact GitHub API origin', () => {
const token = 'test-token-not-a-credential';
assert.strictEqual(
githubHeaders('https://api.github.com/repos/HarperFast/harper', token).Authorization,
'Bearer ' + token
);
for (const url of [
'https://raw.githubusercontent.com/HarperFast/harper/main/file',
'http://api.github.com/file',
'https://api.github.com.example/file',
'http://127.0.0.1/file',
])
assert.strictEqual(githubHeaders(url, token).Authorization, undefined);
assert.strictEqual(githubHeaders('https://api.github.com/repos/HarperFast/harper').Authorization, undefined);
});

test('discarding an already errored response body preserves HTTP failure handling', async () => {
const response = new Response(
new ReadableStream({
start(controller) {
controller.error(new Error('discarded stream failed'));
},
}),
{ status: 503 }
);
await assert.rejects(response.body.cancel(), /discarded stream failed/);
await assert.doesNotReject(discardBody(response));
});

test('companion revisions fail closed for closed-unmerged or malformed peers', () => {
const sha = 'a'.repeat(40);
assert.strictEqual(peerRevision({ state: 'open', head: { sha } }), sha);
assert.strictEqual(peerRevision({ state: 'closed', merged_at: '2026-10-19T00:00:00Z' }), 'main');
assert.throws(() => peerRevision({ state: 'closed', head: { sha } }), /closed without merging/);
assert.throws(() => peerRevision({ state: 'open', head: { sha: 'invalid' } }), /Invalid companion revision/);
});

test('transient HTTP failures retry and return the successful body without leaking a token', async () => {
for (const status of [408, 429, 500, 503]) {
let attempts = 0;
await withServer(
(request, response) => {
assert.strictEqual(request.headers.authorization, undefined);
response.writeHead(++attempts < 3 ? status : 200, { 'Retry-After': '0' });
response.end(attempts < 3 ? 'temporary' : 'fixture bytes');
},
async (url) => {
assert.strictEqual(await readGitHubText(url, { token: 'not-for-this-origin' }), 'fixture bytes');
assert.strictEqual(attempts, 3);
}
);
}
});

test('network disconnects retry within the same request budget', async () => {
let attempts = 0;
await withServer(
(request, response) => {
if (++attempts < 3) request.socket.destroy();
else response.end('recovered');
},
async (url) => {
assert.strictEqual(await readGitHubText(url), 'recovered');
assert.strictEqual(attempts, 3);
}
);
});

test('permanent HTTP failures do not retry or expose response bodies', async () => {
for (const status of [401, 403, 404]) {
let attempts = 0;
await withServer(
(_request, response) => {
attempts++;
response.writeHead(status, { 'Retry-After': '0' });
response.end('sensitive-response');
},
async (url) => {
await assert.rejects(readGitHubText(url, { token: 'sensitive-token' }), (error) => {
assert(error.message.includes('HTTP ' + status));
assert(error.message.includes(url));
assert(!/sensitive|Bearer|Authorization/.test(error.message));
return true;
});
assert.strictEqual(attempts, 1);
}
);
}
});

test('transient failures stop after three attempts', async () => {
let attempts = 0;
await withServer(
(_request, response) => {
attempts++;
response.writeHead(503, { 'Retry-After': '0' });
response.end('unavailable');
},
async (url) => {
await assert.rejects(readGitHubText(url), /HTTP 503 after 3 attempt/);
assert.strictEqual(attempts, 3);
}
);
});

test('Retry-After beyond the comparison wait budget fails rather than retrying early', async () => {
let attempts = 0;
await withServer(
(_request, response) => {
attempts++;
response.writeHead(429, { 'Retry-After': '60' });
response.end();
},
async (url) => {
await assert.rejects(readGitHubText(url), /longer Retry-After/);
assert.strictEqual(attempts, 1);
}
);
});

test('the shared comparison signal terminates a stalled request without retries', async () => {
let attempts = 0;
const controller = new AbortController();
await withServer(
() => {
attempts++;
controller.abort();
},
async (url) => {
await assert.rejects(readGitHubText(url, { signal: controller.signal }), /network error or timeout/);
assert.strictEqual(attempts, 1);
}
);
});
13 changes: 13 additions & 0 deletions .github/scripts/nested-relationship-fixture-parity.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { verifyPeerFixtures } from '../../integrationTests/resources/nested-relationship-docs/github-fixture-fetch.mjs';

test('paired documentation fixtures stay synchronized across repositories', { timeout: 35_000 }, async () => {
await verifyPeerFixtures({
localRoot: fileURLToPath(new URL('../../integrationTests/resources/nested-relationship-docs/', import.meta.url)),
peerRoot: process.env.HARPER_DOCS_FIXTURE_ROOT,
repository: 'HarperFast/documentation',
pull: 736,
peerPath: 'scripts/fixtures/nested-relationship-docs',
});
});
17 changes: 17 additions & 0 deletions .github/workflows/integration-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,23 @@ env:
# the `if: failure()` Harper-log upload still runs, while a job timeout CANCELS it and skips the
# upload.
jobs:
documentation-fixture-parity:
name: Documentation fixture parity
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '24'
package-manager-cache: false
- name: Test fixture fetch reliability
run: node --test .github/scripts/github-fixture-fetch.test.mjs
- name: Compare companion fixtures
env:
GH_TOKEN: ${{ github.token }}
run: node --test .github/scripts/nested-relationship-fixture-parity.test.mjs

generate-node-version-matrix:
name: Generate Node Version Matrix
runs-on: ubuntu-latest
Expand Down
132 changes: 132 additions & 0 deletions integrationTests/resources/nested-relationship-docs.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
/**
* Executes the request/response examples in the nested-relationship documentation companion:
* https://github.com/HarperFast/documentation/pull/736.
* The offline fixtures in that repo are checked against the published Markdown by docs CI.
*/
import { suite, test, before, after } from 'node:test';
import assert from 'node:assert';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import {
setupHarperWithFixture,
teardownHarper,
sendOperation,
DEFAULT_ADMIN_USERNAME,
DEFAULT_ADMIN_PASSWORD,
type ContextWithHarper,
} from '@harperfast/integration-testing';

const fixture = resolve(import.meta.dirname, 'nested-relationship-docs');
const examples = JSON.parse(readFileSync(resolve(fixture, 'examples.json'), 'utf8'));
suite('documented nested relationship requests and responses', { timeout: 120_000 }, (ctx: ContextWithHarper) => {
const auth = 'Basic ' + Buffer.from(DEFAULT_ADMIN_USERNAME + ':' + DEFAULT_ADMIN_PASSWORD).toString('base64');
async function get(path: string) {
const response = await fetch(ctx.harper.httpURL + path, {
headers: { Authorization: auth },
signal: AbortSignal.timeout(10_000),
});
const body = await response.json();
assert.strictEqual(response.status, 200, JSON.stringify(body));
return body;
}
async function insert(table: string, records: unknown[]) {
await sendOperation(ctx.harper, { operation: 'insert', schema: 'data', table, records });
}
before(async () => {
await setupHarperWithFixture(ctx, fixture, {
config: { threads: { count: 1 } },
env: { HARPER_STORAGE_ENGINE: process.env.HARPER_STORAGE_ENGINE || 'rocksdb' },
});
const deadline = Date.now() + 30_000;
let ready = false;
while (Date.now() < deadline) {
try {
await get('/Brand/');
ready = true;
break;
} catch {
await delay(50);
}
}
assert(ready, 'Brand route did not become ready');
await insert('Brand', examples.brands);
await insert('Product', examples.products);
});
after(async () => {
await teardownHarper(ctx);
});
for (const example of examples.cases)
test(example.key, async () => {
assert.deepStrictEqual(await get(example.url), example.response);
});
test('the outer limit uses an exclusive end with three eligible parents', async () => {
assert.deepStrictEqual(await get('/Brand/?sort(id)&limit(1,2)&select(id,)'), [{ id: 43 }]);
});
test('grouped OR preserves both branches before sorting and pagination', async () => {
const example = examples.cases.find((example: { key: string }) => example.key === 'grouped_or_page');
assert(example, 'grouped OR documentation example is missing');
const unskipped = await get(example.url.replace('limit(1,2)', 'limit(0,3)'));
assert.deepStrictEqual(
unskipped.map((brand: { products: { id: string }[] }) => brand.products.map((product) => product.id)),
[['p3', 'p1'], ['p4'], ['p6']]
);
const intersection = await get(example.url.replace('|', '&').replace('limit(1,2)', 'limit(0,3)'));
assert.deepStrictEqual(
intersection.map((brand: { products: unknown[] }) => brand.products),
[[], [], []]
);
});
test('both exact programmatic snippets produce their documented responses', async () => {
assert.deepStrictEqual(await get('/DocumentedQueries/'), {
single: examples.single,
programmatic: examples.programmatic,
});
});
test('repeating the inherited predicate does not change the response', async () => {
const inherited = examples.cases.find((example: { key: string }) => example.key === 'outer_inherited');
assert.deepStrictEqual(
await get(inherited.url.replace('products[', 'products[price=ge=number:30&')),
inherited.response
);
});
test('the outer page bounds parents independently of child limits', async () => {
const bounded = examples.cases.find((example: { key: string }) => example.key === 'bounded_parent_page');
assert.deepStrictEqual(await get(bounded.url.replace('limit(0,20)', 'limit(0,1)')), [bounded.response[0]]);
});
test('nested sorting permits an unindexed child field', async () => {
const rows = await get('/Brand/?select(id,products[sort(name)&limit(1)&select(id,)])');
assert.deepStrictEqual(
rows.map((row: { products: { id: string }[] }) => row.products),
[[{ id: 'p1' }], [{ id: 'p4' }], [{ id: 'p6' }]]
);
});

test('the unique child sort key breaks equal-price ties', async () => {
try {
await insert('Product', [{ id: 'p0', brandId: 42, name: 'Adapter', price: 35 }]);
const bounded = examples.cases.find((example: { key: string }) => example.key === 'bounded_parent_page');
const rows = await get(bounded.url);
assert.deepStrictEqual(rows[0].products, [{ id: 'p0', name: 'Adapter', price: 35 }]);
const descending = await get(bounded.url.replace('sort(price,id)', 'sort(price,-id)'));
assert.deepStrictEqual(descending[0].products, [{ id: 'p2', name: 'Keyboard', price: 35 }]);
const window = await get(bounded.url.replace('limit(1)', 'limit(1,2)'));
assert.deepStrictEqual(window[0].products, [{ id: 'p2', name: 'Keyboard', price: 35 }]);
} finally {
await sendOperation(ctx.harper, { operation: 'delete', schema: 'data', table: 'Product', ids: ['p0'] });
}
});
test('the unique parent sort key breaks equal-name ties', async () => {
try {
await insert('Brand', [{ id: 45, name: 'Acme' }]);
await insert('Product', [{ id: 'p7', brandId: 45, name: 'Hub', price: 50 }]);
const bounded = examples.cases.find((example: { key: string }) => example.key === 'bounded_parent_page');
const page = bounded.url.replace('limit(0,20)', 'limit(0,1)');
assert.strictEqual((await get(page))[0].id, 42);
assert.strictEqual((await get(page.replace('sort(name,id)', 'sort(name,-id)')))[0].id, 45);
} finally {
await sendOperation(ctx.harper, { operation: 'delete', schema: 'data', table: 'Product', ids: ['p7'] });
Comment thread
kylebernhardy marked this conversation as resolved.
Resolved
await sendOperation(ctx.harper, { operation: 'delete', schema: 'data', table: 'Brand', ids: [45] });
}
});
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
graphqlSchema:
files: '*.graphql'
jsResource:
files: resources.js
rest: true
Loading
Loading