Skip to content
Closed
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
1 change: 0 additions & 1 deletion specs/001-pathway-pdfs/contracts/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,5 +128,4 @@ The single-event service (contracts/service.md).
| `--figures` | | as for `book`: the release's figures' folder, read for a PDF without an analysis while it passes `book`'s folder checks, ignored otherwise (contracts/service.md) |
| `--render` | `RENDER_SERVICE` | as for `figures`: draws the figures of a PDF with an analysis, and any the folder lacks |
| `--analysis` | `ANALYSIS_SERVICE` | the analysis service's base URL |
| `--retention` | `TOKEN_RETENTION` | how long an analysis token is kept, in days; must match the analysis service's own setting (research R6) |
| `--concurrency` | | PDFs made at once; default 2 |
11 changes: 6 additions & 5 deletions specs/001-pathway-pdfs/contracts/service.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,16 @@ and its error envelope are WebsiteAngular's (FR-014). This is the interface behi
| 200 | the PDF is made | `application/pdf`, with the stable identifier in the `Content-Disposition` file name |
| 400 | `depth` is not 0 or 1, or the identifier names something that is not a pathway or reaction | JSON `{ "reason": "not-an-event" \| "bad-depth" }` |
| 404 | the identifier names nothing in the graph | JSON `{ "reason": "no-event" }` |
| 404 | the token is unknown, malformed, or older than the retention period | JSON `{ "reason": "unknown-token" }` |
| 410 | the token's result is gone within the retention period | JSON `{ "reason": "gone-token" }` |
| 404 | the token is malformed, or the analysis service answers 404 for it | JSON `{ "reason": "unknown-token" }` |
| 410 | the analysis service answers 410 for it: no result, though dated within its 7 days | JSON `{ "reason": "gone-token" }` |
| 503 | the graph, the render service or the analysis service cannot answer, or the service is at its limit | JSON `{ "reason": "unavailable" }` |

- **The order of checks:** the depth, then the identifier, then the token. An unknown or
non-event identifier is answered as such whatever the token.
- **The token** is checked here before the analysis service is asked (research R6): its
form, and its date against the retention period. A malformed or expired token is
`unknown-token`; the service's 404 is `unknown-token` and its 410 `gone-token`.
- **The token's form** is checked here before the analysis service is asked (research
R6): a malformed token is `unknown-token`. Whether it has expired is the service's to
say: its 404 is `unknown-token`, its 410 `gone-token`, and any other failure
`unavailable`.
- **The reasons** are for the content service, which writes WebsiteAngular's envelope.
They never carry a path, a host or a name.
- **Where a figure comes from:** without a token, from the release's figures' folder
Expand Down
12 changes: 7 additions & 5 deletions specs/001-pathway-pdfs/data-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,13 +139,15 @@ From the analysis service's API (research R6).
- `token`, `type`, `species`, `resource` (`TOTAL`), `projection`, `interactors`.
- **Requested with FR-006's defaults:** all resources together, no expression column, all
identifiers rather than only importable ones.
- `identifiersFound`, `identifiersTotal`, `pathwaysHit`. Found from the summary if it
carries it, otherwise from the result file (research R6).
- `identifiersFound`, `identifiersTotal`, `pathwaysHit`. Found is the count of distinct
submitted identifiers in the found identifiers' CSV, as the summary carries none; the
total adds the summary's `identifiersNotFound`; the pathways hit are its
`pathwaysFound` (research R6).
- `found(pathwayStId)`: the entities and interactors found. A reaction uses its first
parent pathway's, filtered to the reaction's own identifiers.
- **Errors:** checked here before the service is asked (research R6): a malformed token
or one past the retention period is unknown; the service's 404 is unknown, its 410
gone. The identifier is checked first.
- **Errors:** the token's form is checked here before the service is asked (research
R6): a malformed token is unknown; the service's 404 is unknown, its 410 gone, and
whether a token has expired is the service's to say. The identifier is checked first.

## Run report

Expand Down
3 changes: 2 additions & 1 deletion specs/001-pathway-pdfs/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,8 @@ Dockerfile
- a single-event PDF's stages, with the render service's cache off (R7, SC-005);
- the diagrams' widths against FR-016's floor (R4; measured by T008, which replaced the floor);
- what the analysis service answers for an expired and a malformed token, and its
retention period, on a private instance (R6);
retention period (R6; measured by T009 on a non-production instance: the period is
the service's to judge, so none is set here);
- the join's memory, and stamping page numbers after it (R4).
2. **Foundations:**
- the package, TypeScript, lint, Prettier and CI;
Expand Down
2 changes: 1 addition & 1 deletion specs/001-pathway-pdfs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Each opens, has the parts of the spec's Background in order and has bookmarks.
pdf.js at the same scale (research R8): no more than 1% of pixels differ.

- **The errors:** an unknown identifier, a non-event, a bad depth, an unknown token, a
malformed token, an expired token and a token gone within the period each give
malformed token, an expired token and a token gone within the service's 7 days each give
contracts/service.md's answer, and a bad identifier with a bad token gives the
identifier's.

Expand Down
78 changes: 64 additions & 14 deletions specs/001-pathway-pdfs/research.md
Original file line number Diff line number Diff line change
Expand Up @@ -376,26 +376,76 @@ synthetic documents, on this host under load.
content service answers it with an empty response, as it does the other token errors.
- **The render page** reads the same API for its overlays.

**Measured (T009, 3 Nov 2026)**, against a non-production instance of the analysis
service on release 98, never production. Nothing was deleted from its storage: each case
was made from a token the service reads by its own rules, and one small analysis was
submitted (three accessions that map and one that does not; projection to human, without
and then with interactors). The rules were read from analysis-core 3.6.0's `TokenUtils`
and `Tokenizer`, and the answers agree with them.

- **A token** is Base64 of `{yyyyMMddHHmmss}_{counter}`, URL-encoded (`=` as `%3D`). The
service URL-decodes it until it no longer changes (Java's `URLDecoder`, which reads `+`
as a space), then Base64-decodes it with Java's basic decoder (padding optional).
- **The service reads the stored result first.** Only when there is none does it judge
the token's date: within 7 days, 410; otherwise, or with no date in it, 404. The 7 is
`DAYS_TO_LIVE`, a constant in analysis-core, not a setting, and counted in whole days
(Joda's `daysBetween`): a token dated 7 days 23 hours ago is still 410, one dated 8
days ago 404, and one dated in the future 410.
- **So a result outlives its 7 days while its file is kept:** a token older than 7 days
whose result is still stored is answered in full. Read from the code; not seen here, as
no stored result older than 7 days was at hand (five recorded tokens from September and
October were all 404).
- **The answers,** each `application/json;charset=UTF-8`:

| Case | Status | Body |
| --------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| a good token, `/token/{token}` | 200 | the summary (below) |
| dated within 7 days (or in the future), no result stored | 410 | `{"code":410,"reason":"Gone","messages":[]}` |
| dated 8 days ago or more, no result stored | 404 | `{"code":404,"reason":"Not Found","messages":[]}` |
| Base64 of text with no date (no `_`) | 404 | as above |
| not Base64 (`not-base64!`), or a URL-decoding error (`%25`) | 500 | `{"code":500,"reason":"Internal Server Error","messages":["Please get in touch with our help desk (help@reactome.org) for more details about this problem"]}` |
| `found/interactors/{pathway}`, none found (with or without interactors in the analysis) | 404 | the 404 body above |

A malformed token is the service's catch-all 500, the same answer as any failure of its
own, so it cannot be told apart from one by its answer.

- **The summary** (`summary` in `/token/{token}`) holds `token`, `projection`,
`interactors`, `type`, `sampleName`, `text` and `includeDisease`. Beside it,
`/token/{token}` gives `identifiersNotFound` (a count), `pathwaysFound`,
`resourceSummary`, `speciesSummary`, `expression` and `warnings`. **It carries no count
of identifiers found,** nor of identifiers submitted.
- **`/download/{token}/result.json`** has no such count either: its keys are `summary`,
`pathways`, `notFound`, `expressionSummary` and `warnings`, and it was 468 KB for this
four-identifier analysis.
- **`/download/{token}/entities/found/TOTAL/{name}.csv`** lists them: a row per
submitted identifier and what it maps to (three columns: submitted identifier, found identifier, resource), 113 bytes here. It is built from the same map as today's book's
count (`getAnalysisIdentifiers()`, the found entities map's keys, which are equal when
their ids are), so the count of distinct submitted identifiers in it is that count.

**Decision.**

- **The token is checked here first,** before the service is asked: its form (the
Base64 the service issues), and the date it carries against the retention period.
- **Only the token's form is checked here,** before the service is asked; whether it has
expired is the service's to say. Judging the date here would refuse a result the
service still answers, and the website still shows, whenever its file outlives 7 days.
- The identifier is checked first: an unknown or non-event identifier is answered as
such whatever the token.
- A malformed token, or one older than the retention period: `unknown-token` (404).
- The service's 404: `unknown-token`. Its 410, for a result gone within the period:
`gone-token` (410).
- What the service itself answers for an expired and a malformed token is confirmed
against a private instance in the first tasks. CI's stub has a case for each.
- **The retention period is a setting** of `serve` (contracts/cli.md), and must match
the analysis service's own: if they drift, a token one calls expired the other may
still answer. The first tasks read the service's period from its configuration and
set the default to it.
- A malformed token: `unknown-token` (404), as the service's own catch-all 500 would
read as `unavailable`. Malformed is what the service fails on: URL-decoding, repeated
until the token no longer changes (`+` read as a space), that fails, or Base64 that
Java's basic decoder refuses (a character outside its alphabet, misplaced padding, a
length of 1 modulo 4).
- The service's 404: `unknown-token`. Its 410, for a result not stored though its date
is within 7 days: `gone-token` (410). Its other answers, a 500 among them, are
`unavailable`.
- **No retention setting:** the period is the service's constant, and it alone applies
it. CI's stub has a case for each row of the table.
- **The requests carry FR-006's defaults:** all resources together (`TOTAL`), no
expression column, all identifiers rather than only importable ones.
- **The found count:** if `/token/{token}`'s summary carries the identifiers found, it
is read there. Otherwise from `/download/{token}/result.json`, which can be large for
a big analysis. Which one is confirmed in the first tasks.
- **The found count** is the count of distinct submitted identifiers in
`/download/{token}/entities/found/TOTAL/{name}.csv`, which grows with what was found,
not with the pathways hit as `result.json` does. The total is that count plus the
summary's `identifiersNotFound`, and the pathways hit are its `pathwaysFound`, as
today's book counts them.
- pdf-export reads the analysis through the analysis service's API, at an address that
is a setting. It is the same service, reading the same files by the same rules, and
the render page reads it too, so a PDF's figures and its text agree.
Expand Down
11 changes: 6 additions & 5 deletions specs/001-pathway-pdfs/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ Compare each with `event-pdf`'s by FR-012.
the analysis's properties, the entities and interactors found per event, and figures
overlaid with the analysis.
4. **Given** an identifier that names no event, an unknown token, or a token whose
result is gone though its date is still within the retention period, **When** a PDF
result is gone though its date is still within the analysis service's 7 days, **When** a PDF
is asked for, **Then** the answer says which of the three, by the analysis service's
token rules, and no PDF is made. Today's endpoint answers an empty response for
either token case; telling them apart is new.
Expand Down Expand Up @@ -298,10 +298,11 @@ of pages with today's book.
the summary names for a pathway the graph holds, but the files lack. (An entry for an
event the graph does not hold is ignored: plan, research R7.) The step fails and names
it (Story 5, scenario 3).
- **An analysis token unknown, malformed, older than the retention period, or gone
within it:** a malformed token, or one older than the retention period, is answered
as unknown; one whose result is gone within the period is answered as gone (Story 2,
scenario 4).
- **An analysis token unknown, malformed, or gone:** a malformed token is answered as
unknown, as is one the analysis service answers 404 (no result, and dated more than 7
days ago or not at all); one it answers 410 (no result, though dated within its 7 days)
is answered as gone. Whether a token has expired is the analysis service's to say, as
it answers a result still stored whatever its date (Story 2, scenario 4; research R6).
- **A release file missing for a single-event PDF:** the PDF is made without that figure,
as today, and the absence is logged; only the book's step fails on it.

Expand Down
Loading
Loading