Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
/**
* What a GSA request carries when the reader leaves a field blank.
*
* It used to carry the word "undefined". `submitQuery` mapped every parameter
* through `param.value + ''`, and a parameter seeded from an absent `default`
* has `value: undefined` — so an unfilled email was submitted as the string
* `"undefined"`, and the analysis service was asked to deliver a report to an
* address that cannot exist. Reports arrived; mail did not; nothing said why
* (#168).
*
* The rule is tested rather than the service, because the service needs a store,
* an HttpClient and a config provider to construct, and none of them have
* anything to do with the decision being made here.
*/
import { describe, expect, it } from 'vitest';
import { submittedParameters } from './analysis.service';

describe('what a GSA request carries', () => {
it('leaves out a field the reader never filled in', () => {
expect(submittedParameters([{ name: 'email', value: undefined } as never])).toEqual([]);
});

it('leaves out an empty string, which is a blank box rather than an answer', () => {
expect(submittedParameters([{ name: 'email', value: '' } as never])).toEqual([]);
});

it('keeps false and zero, which are answers', () => {
expect(
submittedParameters([
{ name: 'create_reports', value: false } as never,
{ name: 'max_missing_values', value: 0 } as never,
])
).toEqual([
{ name: 'create_reports', value: 'false' },
{ name: 'max_missing_values', value: '0' },
]);
});

it('sends what the reader typed', () => {
expect(submittedParameters([{ name: 'email', value: 'curator@example.org' } as never])).toEqual(
[{ name: 'email', value: 'curator@example.org' }]
);
});
});
31 changes: 20 additions & 11 deletions projects/reactome-gsa-form/src/lib/services/analysis.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,22 @@ import { Parameter } from '../model/parameter.model';
import { extractErrorMessage } from '../utilities/utils';
import { ConfigProvider, REACTOME_GSA_CONFIG } from '../config/gsa-config';

/**
* A parameter the reader never filled in has no value, and `value + ''` turns
* that into the **string** `"undefined"`. For the email parameter that means
* asking the analysis service to deliver a report to an address that cannot
* exist, rather than telling it there is no address -- reports arrive, no mail
* does, and nothing anywhere says why (#168).
*
* So unset parameters are left out. `false` and `0` are values and are kept;
* only `undefined`, `null` and the empty string are absent.
*/
export function submittedParameters(parameters: Parameter[] | undefined) {
return (parameters ?? [])
.filter((param) => param.value !== undefined && param.value !== null && param.value !== '')
.map((param) => ({ name: param.name, value: String(param.value) }));
}

@Injectable({
providedIn: 'root',
})
Expand All @@ -27,21 +43,14 @@ export class AnalysisService {
submitQuery(method: Method, parameters: Parameter[], datasets: Dataset[]): Observable<string> {
const query: Request.Query = {
methodName: method.name || 'Method name',
parameters:
parameters.map((param) => ({
name: param.name,
value: param.value + '',
})) || [],
parameters: submittedParameters(parameters),
datasets: datasets.map((dataset: Dataset) => ({
data: dataset.summary!.id,
name: dataset.summary!.title,
type: dataset.summary!.type,
parameters: dataset
.summary!.parameters?.filter((para) => para.scope !== 'common')
.map((param) => ({
name: param.name,
value: param.value + '',
})),
parameters: submittedParameters(
dataset.summary!.parameters?.filter((para) => para.scope !== 'common')
),
design: {
analysisGroup: dataset.annotationColumns.get(dataset.statisticalDesign.analysisGroup!)!,
samples: dataset.annotationColumns.get('sample_ids')!,
Expand Down
134 changes: 134 additions & 0 deletions specs/003-recorded-backend-for-tests/research.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# Decisions behind the recorded backend for e2e tests

Each entry: what was decided, why, what was rejected, and the measurement that
settled it. Dates are when the figure was read off this host or CI.

The change these describe is #233. The problem it solves is that CI ran 172 tests
against **https://reactome.org** on every push and every pull request — about
1,400 requests a run, from August 2026 until 2026-09-17. That was introduced in
461bc8f to stop the e2e job hanging on a runner with no local backend: it fixed
the symptom by pointing the test suite at the public site.

---

## D1. Backend responses are recorded and replayed, not fetched

**Decision**: Everything under `/ContentService/`, `/AnalysisService/`,
`/ExperimentDigester/` and `idg.reactome.org` is served from recordings in
`e2e/har/`. CI talks to no server; `REACTOME_BACKEND` names a closed port on
purpose.

**Why**: Two separate harms. The load — 1,400 requests a run against the public
site. And the false failures: a Cloudflare 521 during one run surfaced as
`TimeoutError: page.waitForSelector: Timeout 90000ms exceeded`, which says nothing
about a backend and teaches people to press re-run.

**Measured** (2026-09-17): the trace from a failed run showed **eight** consecutive
`521` responses from production, with the page snapshot still showing a loading
spinner after 90s. The tests were not flaky; production was down.

**Rejected**: pointing CI at this box instead. Simpler, one line, and it keeps the
real backend in the loop — but it moves ~1,400 requests a run onto the machine
curators use for QA. Rejected on that, not on principle.

**Cost, stated plainly**: these tests no longer prove the backend works. They prove
the app renders recorded data. If ContentService changes shape they stay green.

---

## D2. One recording per test, not per spec file

**Decision**: `e2e/har/<spec>--<test>-<digest>.har`.

**Why**: Playwright writes the HAR when a browser **context** closes, and every
test has its own context. Per-spec files meant tests overwrote each other and the
last one won.

**Measured** (2026-09-17), per-spec recordings:

content-pages 18 tests -> 5 recorded entries
custom-interactor-dialog 9 tests -> 0 recorded entries

`custom-interactor-dialog` was empty because its final test skips, closing a
context that had requested nothing over the top of eight that had. The same fault
left **78 orphaned response bodies, 6.17 MB** — every test wrote its bodies, only
the last wrote an index.

**Rejected**: recording serially to avoid the overwrite. Tried it — 38 minutes
instead of 13, and it did not help, because the overwrite is per context and not a
race between workers. That was a misdiagnosis that cost two recording passes.

---

## D3. Entries match on method, path and query — never the origin

**Decision**: Replay does not use Playwright's `routeFromHAR` reader. Requests are
matched on `METHOD /path?query`.

**Why**: `routeFromHAR` matches the whole URL including the origin. Recordings are
taken wherever is convenient; CI serves on `localhost:4200`.

**Measured** (2026-09-17): recording and replaying against **the same server**
through two spellings of the same host — `127.0.0.1:4253` and `localhost:4253` —
was enough to fail every test in the spec.

---

## D4. Probe requests are recorded separately

**Decision**: Backend calls made through Playwright's `request` fixture are
recorded to `<test>.api.json` and replayed from there.

**Why**: `context.route()` does not intercept the `request` fixture — it is a
separate API context. Several specs use it to decide whether to skip:

const up = await serves(request, '/ContentService/data/query/…');
test.skip(!up, 'the content service is not reachable from here');

Under replay those reached the closed port, failed, and the tests skipped
themselves while the suite reported green.

**Measured** (2026-09-17): skips went from **6** to **20** — fourteen tests
silently not running — and back to 6 once probes were recorded.

---

## D5. The shared fallback serves GET and HEAD only

**Decision**: If a test's own recording lacks an entry, a pool built from every
recording is consulted — but only for idempotent reads.

**Why**: A request still in flight when its test ends is recorded with status
`-1`, no response ever received. That is common for reference data a page fetches
without waiting on, and on replay the abort left the page unable to initialise:
the DOI page failed for want of `/data/species/main`.

**Rejected**: pooling every method. **Eleven** tests POST to
`/ContentService/interactors/static/molecules/details` with a different list of
accessions each, and the key carries no body — so borrowing another test's reply
would hand one pathway's interactors to another. Plausible, wrong, and green.

---

## D6. `e2e/release/**` is never recorded

**Decision**: The release checklist keeps hitting a real host, via `E2E_BASE_URL`.

**Why**: Its job is to answer "is _this release_ right, on a real deployment",
once per cycle before the new database moves to production. Fixtures would make it
prove nothing. The code suite is a spot check on every push; the release suite is
allowed to be comprehensive because it runs rarely.

---

## D7. Recordings are trimmed to what replay reads

**Decision**: `scripts/trim-har.mjs` keeps `request.method`, `request.url`,
`response.status`, `response.headers` and `response.content`. Nothing else.

**Why**: Size, and disclosure. This repository is public, and Playwright records
request headers, cookies and timings that replay never reads.

**Measured** (2026-09-17): indexes **3.5 MB → 1.0 MB**, and across 2,032 entries
the committed recordings carry **0** request headers, **0** request bodies, **0**
cookies and **0** credential patterns.
135 changes: 135 additions & 0 deletions specs/004-build-and-serving-decisions/research.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Decisions behind how the site is built and served

Each entry: what was decided, why, what was rejected, and the measurement that
settled it. Dates are when the figure was read off this host or CI.

These are the choices that do not belong to any one feature — the toolchain, the
web server in front of beta, and two behaviours a curator reported.

---

## D1. nginx serves beta; Apache is stopped and disabled

**Decision**: nginx runs as the `reactome-nginx` container on ports 80 and 443,
from `deploy/nginx/dev.conf`. Apache is `systemctl disable`d. Cut over 2026-09-17.

**Why**: The operational reason is connection handling. The security reason is
that the retired site's vhost was the default server and held the class of
problem open; nginx has no `mod_include`, so the class disappears rather than
being held shut by one `503`.

**Measured** (2026-09-17), connections to Tomcat after 40 concurrent requests:

Apache: 76 CLOSE-WAIT vs 19 ESTABLISHED
nginx: 48 ESTABLISHED, 0 CLOSE-WAIT, 2 TIME-WAIT

**Rejected**: leaving Apache and tuning it. The CLOSE-WAIT pile was the symptom
that prompted the work, but the configuration cruft was the reason to move.

---

## D2. Each upstream gets the keepalive its own backend allows

**Decision**: `keepalive_timeout` is set per upstream, from a measurement of that
backend, not copied.

**Why**: `proxy_http_version 1.1` with `Connection ""` only cures a CLOSE-WAIT
pile while the pool's idle timeout is **shorter** than the backend's. One comment
explaining Tomcat's 20s was pasted into all five upstreams, of which two are
Tomcat.

**Measured** (2026-09-17), by opening a keep-alive socket and timing the close:

site (node/express) 6.0s -> 4s
chatbot (uvicorn) 5.0s -> 4s
deltasignal (julia) >25s -> 10s
content, analysis 20.0s -> 10s

The chatbot case was reported by the session working on `reactome_chatbot`;
checking the rest of the file found `site` had the same inversion, and that one
serves every page.

---

## D3. nginx reads its config from outside the git working tree

**Decision**: The running config lives in `/etc/nginx-reactome/`, root-owned, put
there by `~/nginx-deploy-config.sh`. Deploying is an explicit act.

**Why**: The cutover originally bind-mounted `deploy/nginx/dev.conf` straight from
the repository, so `git checkout` changed what the public-facing server would load
on its next reload or reboot. Nothing warned about it.

**Rejected**: discipline about which branch is checked out. That is not a control.

---

## D4. Node 24 and npm 11

**Decision**: `engines` requires `node >=24.0.0` and `npm >=11`; `.nvmrc`, all
workflows and both Dockerfiles agree.

**Why**: `engines` previously pinned `node: 22.x` and `npm: >=10 <11`, and that
pin was the reason a lockfile generated locally and one generated in CI could
never agree — npm 11 records optional platform packages npm 10 omits. Angular 21
declares `>=24.0.0` and 24 is Latest LTS.

**Measured** (2026-09-17): moving to 24 changed **no** dependency's version — 91
packages added, all optional platform binaries; 0 removed; 0 that lost a version.

---

## D5. `--legacy-peer-deps` is gone, because vitest moved

**Decision**: vitest is pinned at `4.1.11` and nothing installs with the flag.

**Why**: The flag was covering exactly one conflict, and it was ours: this repo
pinned `vitest` at `3.2.7` while `@angular/build` asks for `^4.0.8`.

**Measured** (2026-09-17): bumping vitest changed **13** packages, all inside
vitest's own tree. The unit suite needed no changes — 244 tests before, 244 after.

**Rejected, and worth recording because it was believed for a day**: that
`@analogjs/vitest-angular` was the blocker and removing the flag would drag 207
top-level version changes including React 18 → 19. Analog accepts
`^1 || ^2 || ^3 || ^4` and was never the constraint. The 207 figure came from
deleting the lockfile and letting npm re-resolve everything, which measures a full
re-resolve rather than this change.

---

## D6. Navigating into a pathway keeps the reader's selection

**Decision**: Double-clicking a pathway box preserves `select` rather than
replacing it with the pathway being left.

**Why**: Reported by a curator — "a searched entity is inselected if you try to
navigate to a new pathway within the diagram". The handler set `select` to the
origin pathway deliberately, to orient the reader; the sibling handler for
`.SUB.Pathway` did not, so the two ways out of a diagram disagreed.

**Measured** (2026-09-17): the flag survives and redraws (`flag=PKM`, 6 elements
then 2). Only `select` changed, from `R-HSA-70171` to `R-HSA-70326`.

**Rejected**: keeping the selection only when the new diagram contains it, falling
back to the origin otherwise. Better behaviour, but it needs a rule for an entity
appearing in several complexes, and the asymmetry settles it without one: where
you came from is one **Back** away, what you were looking at was not recoverable.

**Cost**: nothing is highlighted on arrival where the origin pathway would
previously have been.

---

## D7. A GSA parameter with no value is left out

**Decision**: `submittedParameters` omits `undefined`, `null` and `''`. `false`
and `0` are answers and are kept.

**Why**: Every parameter went through `param.value + ''`, so a field the reader
never filled in was submitted as the **string** `"undefined"` — the analysis
service being asked to email a report to an address that cannot exist.

**Not claimed**: that this is why a curator's reports were not emailed. Delivery
is GSA's, our submission path is otherwise correct, and their logs know what
arrived. Asking is cheaper than submitting analyses to reproduce it.
Loading