Skip to content
Merged
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 or in the future | 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 (header skipped), as
`/token/{token}` carries none; the total adds its `identifiersNotFound`; the pathways
hit are its `pathwaysFound`, asked for with `includeDisease=true` (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: expiry is the
service's to judge, so no period 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
4 changes: 2 additions & 2 deletions specs/001-pathway-pdfs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ research R7.
- **Then, first of the new work** (research R7): the render service's throughput at the
book's scale against the 44-minute figures budget, go or no-go (T005: a no-go, and the
figures moved to a step of their own, T006); the analysis service's
answers for an expired and a malformed token on a private instance (R6); the join's
answers for an expired and a malformed token on a non-production instance (R6); the join's
memory and stamping after it (R4).

## 2. CI's own runs
Expand Down 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, a token the service answers 404 and one it answers 410 each give
contracts/service.md's answer, and a bad identifier with a bad token gives the
identifier's.

Expand Down
Loading
Loading