diff --git a/deploy/nginx/common/routes-core.conf b/deploy/nginx/common/routes-core.conf index 09c885321..14789b3d2 100644 --- a/deploy/nginx/common/routes-core.conf +++ b/deploy/nginx/common/routes-core.conf @@ -201,6 +201,14 @@ location ~ ^/ContentService/search/query(/paginated)?/?$ { include /etc/nginx/common/content-node-proxy.conf; } +# The Pathway Browser's "cite this": a pathway's citation (its authors, +# release and DOI, as content-service's EventCitation writes them), a paper's +# by PubMed id from Europe PMC, and either as a BibTeX, RIS or text download. +# Byte-identical to Java over eleven cases. +location ~ ^/ContentService/citation/(pathway/[^/]+|static/[^/]+|export)$ { + include /etc/nginx/common/content-node-proxy.conf; +} + # What points at an object (the website's detail pages): graph-core's # getReferralsTo -- everything referring to it but edit history, and for a # species, compartment, database, evidence type or review status not all diff --git a/projects/website-angular/src/scripts/proxy-order.spec.ts b/projects/website-angular/src/scripts/proxy-order.spec.ts index 4d68810ad..1ec4ae164 100644 --- a/projects/website-angular/src/scripts/proxy-order.spec.ts +++ b/projects/website-angular/src/scripts/proxy-order.spec.ts @@ -223,6 +223,9 @@ describe('the dev server proxy', () => { '/ContentService/search/fireworks/?query=MAD2&species=Homo%20sapiens', '/ContentService/search/query?query=TP53&cluster=true&Start%20row=0&rows=30', '/ContentService/search/query/paginated?query=TP53&page=1&rowCount=20', + '/ContentService/citation/pathway/R-HSA-109581?dateAccessed=x', + '/ContentService/citation/static/25348405', + '/ContentService/citation/export?id=R-HSA-109581&ext=bib&isPathway=true&dateAccessed=x', '/ContentService/data/instance/R-HSA-141433/referrers', // Spring matches a trailing slash, and so must the route once Java is gone. '/ContentService/data/instance/R-HSA-141433/referrers/', @@ -257,6 +260,8 @@ describe('the dev server proxy', () => { '/ContentService/search/fireworks/flag/x?query=KNTC1', '/ContentService/search/fireworks/x?query=KNTC1', '/ContentService/search/pathways/of/227785/x', + '/ContentService/citation/export/R-HSA-109581?ext=bib', + '/ContentService/citation/download', '/ContentService/data/instance/R-HSA-141433', '/ContentService/data/instance/R-HSA-141433/referrers/x', '/ContentService/search/diagram/R-HSA-68886/occurrences', diff --git a/proxy.conf.js b/proxy.conf.js index b579bc642..bef8d0222 100644 --- a/proxy.conf.js +++ b/proxy.conf.js @@ -128,6 +128,10 @@ module.exports = { // website's search (/query). '^/ContentService/search/(diagram/[^/?]+(/occurrences/[^/?]+|/flag)?|fireworks(/flag|/)?|pathways/of/[^/?]+|query(/paginated)?/?)(\\?|$)': contentNode, + // The Pathway Browser's "cite this": a pathway's citation, a paper's by + // PubMed id, and either to download. /citation/export/{id} and /download + // stay with Java. + '^/ContentService/citation/(pathway/[^/?]+|static/[^/?]+|export)(\\?|$)': contentNode, // What points at an object, for the website's detail pages. '^/ContentService/data/instance/[^/?]+/referrers/?(\\?|$)': contentNode, // A person, and the publications they authored. Not the other attributes diff --git a/tools/content-node/citation.mjs b/tools/content-node/citation.mjs new file mode 100644 index 000000000..69596cc01 --- /dev/null +++ b/tools/content-node/citation.mjs @@ -0,0 +1,332 @@ +/** + * Citations, as content-service's EventCitation and StaticCitation write + * them: a pathway's from its own data, a paper's from Europe PMC. The text + * here is Java's, quirks included -- three authors joined " ," then " & ", + * the default author line, the placeholders a paper without a journal or a + * volume gets. + */ +const DEFAULT_AUTHOR = 'The Reactome Consortium'; +const NOTE = (date) => `Provided by Reactome. Citation Accessed on ${date}`; + +/** Java's DateFormatSymbols short months, for Citation.setMonth. */ +const SHORT_MONTHS = [ + 'Jan', + 'Feb', + 'Mar', + 'Apr', + 'May', + 'Jun', + 'Jul', + 'Aug', + 'Sep', + 'Oct', + 'Nov', + 'Dec', +]; + +/** + * Citation.setMonth: Integer.parseInt of the text, a month only for 1 to 12; + * text that is no int is Java's NumberFormatException. + */ +function citationMonth(text) { + const month = /^[+-]?\d+$/.test(String(text)) ? Number(text) : NaN; + if (!(month >= -2147483648 && month <= 2147483647)) + throw javaFailure(`For input string: "${text}"`); + return month > 0 && month <= 12 ? SHORT_MONTHS[month - 1] : null; +} + +/** + * What Java throws for its GlobalExceptionHandler to answer with a 500: a + * NullPointerException as "Something unexpected happened", anything else + * with its own message (javaFailure). + */ +function unexpected(message) { + return Object.assign(new Error(message), { unexpected: true }); +} +function javaFailure(message) { + return Object.assign(new Error(message), { javaMessage: message }); +} + +/** String.substring's StringIndexOutOfBoundsException, as JDK 11 words it. */ +function substring(text, begin, end) { + if (end > text.length) throw javaFailure(`begin ${begin}, end ${end}, length ${text.length}`); + return text.slice(begin, end); +} + +/** The class Jackson reads a JSON value as, into a Map. */ +function javaClass(value) { + if (typeof value === 'string') return 'java.lang.String'; + if (typeof value === 'boolean') return 'java.lang.Boolean'; + if (Array.isArray(value)) return 'java.util.ArrayList'; + if (typeof value === 'object') return 'java.util.LinkedHashMap'; + if (!Number.isInteger(value)) return 'java.lang.Double'; + if (value >= -2147483648 && value <= 2147483647) return 'java.lang.Integer'; + return Number.isSafeInteger(value) ? 'java.lang.Long' : 'java.math.BigInteger'; +} + +/** A cast of a JSON value as Java's checkcast does it: null passes, a misfit is JDK 11's ClassCastException. */ +function javaCast(value, target, fits) { + if (value === null || value === undefined || fits(value)) return; + const from = javaClass(value); + throw javaFailure( + `class ${from} cannot be cast to class ${target} (${from} and ${target} are in module java.base of loader 'bootstrap')` + ); +} +const isString = (value) => typeof value === 'string'; +const isMap = (value) => typeof value === 'object' && !Array.isArray(value); + +/** + * The casts StaticCitation's toBibtex/toRIS (by name) and toText (by full + * name) make of Europe PMC's authors -- outside Java's try, so a misfit is + * GlobalExceptionHandler's 500 rather than "unable to fetch": each author to + * a Map and its names to String -- by name for BibTeX and RIS, the full + * name for text -- one author at a time; a null author is the + * NullPointerException of author.get. + */ +function checkStaticAuthors(authors, ext) { + if (!authors?.length) return; + for (const author of authors) { + javaCast(author, 'java.util.Map', isMap); + if (author === null) throw unexpected('a null author'); + if (ext === 'bib' || ext === 'ris') { + javaCast(author.lastName, 'java.lang.String', isString); + javaCast( + 'firstName' in author ? author.firstName : author.initials, + 'java.lang.String', + isString + ); + } else javaCast(author.fullName, 'java.lang.String', isString); + } +} + +/** + * CitationController.getEventCitationObject, given the event: its name, the + * release year and -- from the wrong character of the date, as Java takes + * it -- month, a pathway's DOI or else its page, the release, and the authors + * of its authored edits, else its creator, else its reviewers, initials + * dotted as String.join(".", initial.split("")) dots them. What Java + * throws on -- no name or release date, a short or non-numeric one, a + * person with no initial -- throws the same. + */ +export function citationOfEvent(event, raw, release, isPathway) { + const props = event.properties; + // The Citation constructor's own check. + if (props.displayName == null) throw javaFailure('Title or id can not be null'); + if (props.releaseDate == null) throw unexpected('an event with no release date'); + const date = String(props.releaseDate); + const citation = { + id: raw, + title: props.displayName, + year: substring(date, 0, 4), + month: citationMonth(substring(date, 6, 7)), + doi: null, + urls: [], + authors: null, + }; + if (isPathway && props.doi) { + citation.doi = props.doi; + citation.urls.push(`https://doi.org/${props.doi}`); + } else citation.urls.push(`https://reactome.org/content/detail/${raw}`); + citation.release = release; + const fields = event.fields; + const edits = fields.authored?.length + ? fields.authored + : fields.created + ? [fields.created] + : fields.reviewed?.length + ? fields.reviewed + : null; + if (edits) { + citation.authors = []; + for (const edit of edits) + for (const person of edit.fields?.author ?? []) { + const { surname, initial, firstname } = person.properties; + if (initial == null) throw unexpected('a person with no initial'); + citation.authors.push({ + lastName: surname, + initials: `${[...String(initial)].join('.')}.`, + firstName: firstname, + }); + } + } + return citation; +} + +/** A value joined into text as Java joins it: a missing one is "null". */ +const java = (value) => (value === null || value === undefined ? 'null' : value); + +const byName = (author) => + `${java(author.lastName)}, ${java('firstName' in author ? author.firstName : author.initials)}`; + +function ris(citation, type, date, extra = []) { + let text = `${NOTE(date)}\n\nTY - ${type}\nTI - ${citation.title}\n`; + for (const author of citation.authors ?? []) text += `AU - ${byName(author)}\n`; + text += `AN - ${citation.id}\n`; + if (citation.doi != null) text += `DO - ${citation.doi}\n`; + for (const url of citation.urls ?? []) text += `UR - ${url.trim()}\n`; + if (citation.year != null) { + text += `PY - ${citation.year}\n`; + if (citation.month != null) text += `DA - ${citation.year}/${citation.month}//\n`; + } + for (const [tag, value] of extra) if (value != null) text += `${tag} - ${value}\n`; + return `${text}ER - \n`; +} + +function bibtex(citation, kind, date, middle) { + let text = `@${kind}{${citation.id},\nTitle = {${citation.title}},\n`; + for (const [name, value] of middle) if (value !== undefined) text += `${name} = {${value}},\n`; + return `${text}Note = {${NOTE(date)}},\n}`; +} + +/** EventCitation.toText, toBibtex or toRIS, as `ext` (bib, ris, anything else text) picks. */ +export function formatEventCitation(citation, ext, date) { + const authors = citation.authors?.length ? citation.authors : null; + if (ext === 'bib') + return bibtex(citation, 'misc', date, [ + ['Author', authors ? authors.map(byName).join(' and ') : DEFAULT_AUTHOR], + ['Year', citation.year ?? undefined], + ['Month', citation.month ?? undefined], + ['DOI', citation.doi ?? undefined], + ['URL', citation.urls?.length ? citation.urls[0] : undefined], + ]); + if (ext === 'ris') return ris(citation, 'ELEC', date); + return `Pathway Citation: ${eventText(citation, date)}\nImage Citation: ${imageText(citation, date)}`; +} + +/** EventCitation.eventCitation: authors by their initials, the year, then the common part. */ +export function eventText(citation, date) { + let text = DEFAULT_AUTHOR; + if (citation.authors?.length) { + const names = citation.authors.map( + (author) => `${java(author.lastName)}, ${java(author.initials)}` + ); + text = names.at(-1); + if (names.length > 1) text = `${names.slice(0, -1).join(' ,')} & ${text}`; + } + if (citation.year != null) text += ` (${citation.year}). `; + return text + commonText(citation, date); +} + +export function imageText(citation, date) { + return `Image Citation for ${commonText(citation, date)}`; +} + +function commonText(citation, date) { + let text = `${citation.title}. `; + if (citation.release != null) text += `Reactome, ${citation.release}, `; + if (citation.urls?.length) text += `${citation.urls.join(', ')} `; + return `${text}(${date})`; +} + +/** StaticCitation.toText, toBibtex or toRIS. `date` null is no "Provided by" line. */ +export function formatStaticCitation(citation, ext, date) { + checkStaticAuthors(citation.authors, ext); + if (ext === 'bib') + return bibtex(citation, 'article', date, [ + [ + 'Author', + citation.authors?.length + ? citation.authors.map(byName).join(' and ') + : 'No authors specified', + ], + ['Journal', citation.journal ?? 'No journal specified'], + ['Number', citation.number ?? undefined], + ['Volume', citation.volume ?? 'No volume specified'], + ['ISSN', citation.issn ?? undefined], + ['Pages', citation.pages ?? undefined], + ['Year', citation.year ?? 'No year specified'], + ['Month', citation.month ?? undefined], + ['DOI', citation.doi ?? undefined], + ['URL', citation.urls?.length ? citation.urls[0] : undefined], + ]); + if (ext === 'ris') + return ris(citation, 'JOUR', date, [ + ['JO', citation.journal], + ['IS', citation.number], + ['VL', citation.volume], + ['SN', citation.issn], + ['SP', citation.pages], + ]); + let text = date != null ? `${NOTE(date)}\n\n` : ''; + if (citation.authors?.length) + text += `${citation.authors.map((author) => java(author.fullName)).join(', ')}. `; + text += `${citation.title} `; + if (citation.journal != null) text += `${citation.journal}. `; + if (citation.year != null) { + text += citation.year; + if (citation.month != null) text += ` ${citation.month}`; + } + if (citation.volume != null) { + text += `;${citation.volume}`; + if (citation.number != null) text += `(${citation.number})`; + text += ' '; + } + if (citation.pages != null) text += `${citation.pages}. `; + if (citation.doi != null) text += `doi: ${citation.doi}. `; + if (citation.pmid != null) text += `PubMed PMID: ${citation.pmid}. `; + if (citation.pmcid != null) text += `PubMed Central PMCID: ${citation.pmcid}. `; + return text; +} + +/** + * Object.toString of a value Jackson read: a map {a=1, b=2}, a list [x, y], + * anything else as itself. A null is the NullPointerException Java's + * toString() on it is. + */ +function javaString(value) { + if (value === null || value === undefined) throw new Error('toString of null'); + const inner = (item) => (item === null ? 'null' : javaString(item)); + if (Array.isArray(value)) return `[${value.map(inner).join(', ')}]`; + if (typeof value === 'object') + return `{${Object.entries(value) + .map(([key, item]) => `${key}=${inner(item)}`) + .join(', ')}}`; + return String(value); +} + +/** Java's cast to Map: null passes, anything but an object is its ClassCastException. */ +function asMap(value) { + if (value !== null && (typeof value !== 'object' || Array.isArray(value))) + throw new Error('not a map'); + return value; +} + +/** + * CitationController.getStaticCitationObject: Europe PMC's first result, + * read field by field as Java reads it. Anything Java would fail on -- no + * result, no id or title, a month that is no int -- throws, and the caller + * answers as Java's catch does. + */ +export function staticCitationFrom(answer) { + const map = answer?.resultList?.result?.[0]; + if (!map || map.id == null || map.title == null) + throw new Error('no citation in Europe PMC answer'); + const journalInfo = 'journalInfo' in map ? asMap(map.journalInfo) : null; + const journal = journalInfo && 'journal' in journalInfo ? asMap(journalInfo.journal) : null; + const citation = { id: javaString(map.id), title: javaString(map.title) }; + if ('pageInfo' in map) citation.pages = javaString(map.pageInfo); + if ('pmid' in map) citation.pmid = javaString(map.pmid); + if ('pmcid' in map) citation.pmcid = javaString(map.pmcid); + if (journal && 'title' in journal) citation.journal = javaString(journal.title); + if (journalInfo && 'yearOfPublication' in journalInfo) + citation.year = javaString(journalInfo.yearOfPublication); + if (journalInfo && 'monthOfPublication' in journalInfo) + citation.month = citationMonth(javaString(journalInfo.monthOfPublication)); + if (journalInfo && 'issue' in journalInfo) citation.number = javaString(journalInfo.issue); + if (journalInfo && 'volume' in journalInfo) citation.volume = javaString(journalInfo.volume); + if (journal && 'issn' in journal) citation.issn = javaString(journal.issn); + if ('doi' in map && map.doi != null) { + citation.doi = javaString(map.doi); + citation.urls = [`https://doi.org/${citation.doi}`]; + } + if ('authorList' in map) { + const authorList = asMap(map.authorList); + if (authorList === null) throw new Error('authorList is null'); + if ('author' in authorList) { + const authors = authorList.author; + if (authors !== null && !Array.isArray(authors)) throw new Error('author is not a list'); + citation.authors = authors; + } + } + return citation; +} diff --git a/tools/content-node/citation.spec.mjs b/tools/content-node/citation.spec.mjs new file mode 100644 index 000000000..788c50849 --- /dev/null +++ b/tools/content-node/citation.spec.mjs @@ -0,0 +1,469 @@ +// @vitest-environment node +// +// /citation/pathway/{id}, /citation/static/{id} and /citation/export -- the +// Pathway Browser's "cite this" -- with stand-ins for the graph and Europe +// PMC: content-service's EventCitation and StaticCitation, as Java writes +// them. Java's answers measured 17 Oct 2026. Names here are invented. +import { describe, expect, it, beforeAll, afterAll, vi } from 'vitest'; +import { + citationOfEvent, + formatEventCitation, + formatStaticCitation, + staticCitationFrom, +} from './citation.mjs'; + +const event = (overrides = {}) => ({ + id: 'R-HSA-1', + title: 'A pathway', + year: '2019', + month: 'Jun', + doi: null, + urls: ['https://reactome.org/content/detail/R-HSA-1'], + release: '97', + authors: [ + { lastName: 'Doe', initials: 'J.A.', firstName: 'Jane' }, + { lastName: 'Roe', initials: 'R.', firstName: 'Richard' }, + ], + ...overrides, +}); + +describe('EventCitation', () => { + it('writes the text citation: authors by initials, year, title, release, urls, date', () => { + expect(formatEventCitation(event(), 'txt', 'Fri Oct 17 2026')).toBe( + 'Pathway Citation: Doe, J.A. & Roe, R. (2019). A pathway. Reactome, 97, https://reactome.org/content/detail/R-HSA-1 (Fri Oct 17 2026)\n' + + 'Image Citation: Image Citation for A pathway. Reactome, 97, https://reactome.org/content/detail/R-HSA-1 (Fri Oct 17 2026)' + ); + }); + + it('joins three or more authors as Java does, " ," then " & "', () => { + const three = event({ + authors: [ + { lastName: 'A', initials: 'A.', firstName: 'x' }, + { lastName: 'B', initials: 'B.', firstName: 'y' }, + { lastName: 'C', initials: 'C.', firstName: 'z' }, + ], + }); + expect(formatEventCitation(three, 'txt', 'd')).toMatch( + /^Pathway Citation: A, A. ,B, B. & C, C. \(2019\)/ + ); + }); + + it('writes BibTeX and RIS, first names over initials, DOI when there is one', () => { + const withDoi = event({ doi: '10.3180/R-HSA-1', urls: ['https://doi.org/10.3180/R-HSA-1'] }); + expect(formatEventCitation(withDoi, 'bib', 'd')).toBe( + '@misc{R-HSA-1,\nTitle = {A pathway},\nAuthor = {Doe, Jane and Roe, Richard},\nYear = {2019},\nMonth = {Jun},\n' + + 'DOI = {10.3180/R-HSA-1},\nURL = {https://doi.org/10.3180/R-HSA-1},\nNote = {Provided by Reactome. Citation Accessed on d},\n}' + ); + expect(formatEventCitation(withDoi, 'ris', 'd')).toBe( + 'Provided by Reactome. Citation Accessed on d\n\nTY - ELEC\nTI - A pathway\nAU - Doe, Jane\nAU - Roe, Richard\n' + + 'AN - R-HSA-1\nDO - 10.3180/R-HSA-1\nUR - https://doi.org/10.3180/R-HSA-1\nPY - 2019\nDA - 2019/Jun//\nER - \n' + ); + }); + + it('writes a missing name as Java concatenates it, "null"', () => { + const nameless = event({ authors: [{ lastName: 'Doe', initials: 'J.', firstName: null }] }); + expect(formatEventCitation(nameless, 'bib', 'd')).toMatch(/Author = \{Doe, null\}/); + const collective = staticCitationFrom({ + resultList: { + result: [{ ...europePmc, authorList: { author: [{ collectiveName: 'A consortium' }] } }], + }, + }); + expect(formatStaticCitation(collective, 'ris', 'd')).toMatch(/AU {2}- null, null\n/); + expect(formatStaticCitation(collective, 'txt', null)).toMatch(/^null\. A paper\./); + }); + + it('is The Reactome Consortium when nobody is named', () => { + expect(formatEventCitation(event({ authors: null }), 'bib', 'd')).toMatch( + /Author = \{The Reactome Consortium\}/ + ); + }); +}); + +const europePmc = { + id: '12345', + title: 'A paper.', + pageInfo: '1-9', + pmid: '12345', + journalInfo: { + issue: '3', + volume: '7', + yearOfPublication: 2020, + monthOfPublication: 11, + journal: { title: 'A Journal', issn: '1234-5678' }, + }, + doi: '10.1/x', + authorList: { author: [{ fullName: 'Doe J', lastName: 'Doe', initials: 'J' }] }, +}; + +/** An event as mapResult gives it, with people by initial. */ +const mapped = ({ releaseDate = '2019-06-14', doi, ...fields } = {}) => ({ + properties: { displayName: 'A pathway', releaseDate, ...(doi === undefined ? {} : { doi }) }, + fields, +}); +const edit = (...initials) => ({ + fields: { + author: initials.map((initial, i) => ({ + properties: { surname: `S${i}`, initial, firstname: `F${i}` }, + })), + }, +}); + +describe('citationOfEvent', () => { + it('takes the year, the month from the wrong character of the date, the page, the release', () => { + // 2019-06-14: Java's substring(6, 7) is "6", June -- and 2019-11-01's is "1". + expect(citationOfEvent(mapped(), 'R-HSA-1', '97', false)).toEqual({ + id: 'R-HSA-1', + title: 'A pathway', + year: '2019', + month: 'Jun', + doi: null, + urls: ['https://reactome.org/content/detail/R-HSA-1'], + authors: null, + release: '97', + }); + expect(citationOfEvent(mapped({ releaseDate: '2019-11-01' }), 'x', '97', false).month).toBe( + 'Jan' + ); + expect(citationOfEvent(mapped({ releaseDate: '2019-10-01' }), 'x', '97', false).month).toBe( + null + ); + }); + + it("links a pathway's DOI, not a reaction's, nor an empty one", () => { + const withDoi = mapped({ doi: '10.1/p' }); + expect(citationOfEvent(withDoi, 'x', '97', true)).toMatchObject({ + doi: '10.1/p', + urls: ['https://doi.org/10.1/p'], + }); + expect(citationOfEvent(withDoi, 'x', '97', false)).toMatchObject({ + doi: null, + urls: ['https://reactome.org/content/detail/x'], + }); + expect(citationOfEvent(mapped({ doi: '' }), 'x', '97', true).doi).toBe(null); + }); + + it('names the authors, else the creator, else the reviewers; initials dotted', () => { + const names = (fields) => + citationOfEvent(mapped(fields), 'x', '97', false).authors?.map((a) => a.initials); + const all = { authored: [edit('JA')], created: edit('C'), reviewed: [edit('R')] }; + expect(names(all)).toEqual(['J.A.']); + expect(names({ ...all, authored: [] })).toEqual(['C.']); + expect(names({ reviewed: [edit('R', 'QZ')] })).toEqual(['R.', 'Q.Z.']); + expect(names({ authored: [], reviewed: [] })).toBe(undefined); + expect(citationOfEvent(mapped({ authored: [edit('A')] }), 'x', '97', false).authors).toEqual([ + { lastName: 'S0', initials: 'A.', firstName: 'F0' }, + ]); + }); + + it("throws as Java's NullPointerException does: no release date, a person with no initial", () => { + for (const fields of [{ releaseDate: null }, { authored: [edit(null)] }]) + expect(() => citationOfEvent(mapped(fields), 'x', '97', false)).toThrow( + expect.objectContaining({ unexpected: true }) + ); + }); + + it("throws Java's own message for a short or non-numeric date, or no name", () => { + const failure = (event) => { + try { + citationOfEvent(event, 'x', '97', false); + } catch (thrown) { + return [thrown.unexpected, thrown.javaMessage]; + } + }; + expect(failure(mapped({ releaseDate: '2019-0' }))).toEqual([ + undefined, + 'begin 6, end 7, length 6', + ]); + expect(failure(mapped({ releaseDate: '201' }))).toEqual([ + undefined, + 'begin 0, end 4, length 3', + ]); + expect(failure(mapped({ releaseDate: '2019-0x-01' }))).toEqual([ + undefined, + 'For input string: "x"', + ]); + const unnamed = mapped(); + unnamed.properties.displayName = null; + expect(failure(unnamed)).toEqual([undefined, 'Title or id can not be null']); + }); +}); + +describe('StaticCitation', () => { + it("reads Europe PMC's first result as Java does, and writes text, BibTeX and RIS", () => { + const citation = staticCitationFrom({ resultList: { result: [europePmc] } }); + expect(formatStaticCitation(citation, 'txt', null)).toBe( + 'Doe J. A paper. A Journal. 2020 Nov;7(3) 1-9. doi: 10.1/x. PubMed PMID: 12345. ' + ); + expect(formatStaticCitation(citation, 'bib', 'd')).toBe( + '@article{12345,\nTitle = {A paper.},\nAuthor = {Doe, J},\nJournal = {A Journal},\nNumber = {3},\nVolume = {7},\n' + + 'ISSN = {1234-5678},\nPages = {1-9},\nYear = {2020},\nMonth = {Nov},\nDOI = {10.1/x},\nURL = {https://doi.org/10.1/x},\n' + + 'Note = {Provided by Reactome. Citation Accessed on d},\n}' + ); + expect(formatStaticCitation(citation, 'ris', 'd')).toMatch( + /TY {2}- JOUR\n[\s\S]*JO {2}- A Journal\nIS {2}- 3\nVL {2}- 7\nSN {2}- 1234-5678\nSP {2}- 1-9\nER {2}- \n$/ + ); + }); + + it('reads a map and a list as Java prints them, and treats what Java cannot read as no citation', () => { + const one = (changes) => + staticCitationFrom({ resultList: { result: [{ ...europePmc, ...changes }] } }); + expect(one({ pageInfo: { a: 1, b: [2, null] } }).pages).toBe('{a=1, b=[2, null]}'); + expect(one({ journalInfo: null }).year).toBe(undefined); + expect(one({ authorList: { author: null } }).authors).toBe(null); + for (const changes of [ + { pmcid: null }, + { journalInfo: 'x' }, + { journalInfo: { journal: [1] } }, + { journalInfo: { monthOfPublication: 2147483648 } }, + { authorList: null }, + { authorList: { author: 'x' } }, + ]) + expect(() => one(changes)).toThrow(); + expect(one({ journalInfo: { monthOfPublication: 2147483647 } }).month).toBe(null); + }); + + it("casts the authors as Java's formatters do, outside its try", () => { + const failure = (authors, ext) => { + try { + formatStaticCitation({ ...event(), authors }, ext, 'd'); + } catch (thrown) { + return thrown.unexpected ? 'NPE' : thrown.javaMessage; + } + }; + const cce = (from, to) => + `class ${from} cannot be cast to class ${to} (${from} and ${to} are in module java.base of loader 'bootstrap')`; + expect(failure(['x'], 'txt')).toBe(cce('java.lang.String', 'java.util.Map')); + expect(failure([[1]], 'bib')).toBe(cce('java.util.ArrayList', 'java.util.Map')); + expect(failure([null], 'ris')).toBe('NPE'); + expect(failure([{ lastName: 5 }], 'bib')).toBe(cce('java.lang.Integer', 'java.lang.String')); + expect(failure([{ lastName: 'a', firstName: true }], 'ris')).toBe( + cce('java.lang.Boolean', 'java.lang.String') + ); + // By full name too, to String, one author at a time: the first misfit wins. + expect(failure([{ fullName: 2 ** 40 }, null], 'txt')).toBe( + cce('java.lang.Long', 'java.lang.String') + ); + expect(failure([null, { fullName: 5 }], 'txt')).toBe('NPE'); + expect(failure([{ fullName: 5 }, 'x'], 'txt')).toBe( + cce('java.lang.Integer', 'java.lang.String') + ); + // Only the names a format reads are cast. + expect(failure([{ fullName: 'A B', lastName: 5 }], 'txt')).toBe(undefined); + expect(failure([{ lastName: 'a', initials: 'b', fullName: 5 }], 'bib')).toBe(undefined); + }); +}); + +vi.mock('./graph.mjs', async () => ({ + read: async (cypher, params) => { + if (cypher.includes('DBInfo')) return [{ version: 97 }]; + globalThis.graphAsked = params; + return globalThis.graphRows ?? []; + }, + configured: () => true, + close: async () => {}, + envSetting: (key, fallback = '') => process.env[key] || fallback, +})); + +describe('the citation endpoints', () => { + let base; + let server; + let pmc; + let pmcAsked = []; + + beforeAll(async () => { + const { createServer } = await import('node:http'); + pmc = createServer((request, response) => { + pmcAsked.push(request.url); + response.setHeader('Content-Type', 'application/json'); + response.end(JSON.stringify(globalThis.pmcAnswer ?? { resultList: { result: [europePmc] } })); + }); + await new Promise((resolve) => pmc.listen(0, '127.0.0.1', resolve)); + process.env.EUROPE_PMC_URL = `http://127.0.0.1:${pmc.address().port}/search`; + const { app } = await import('./service.mjs'); + await new Promise((resolve) => { + server = app().listen(0, '127.0.0.1', resolve); + }); + base = `http://127.0.0.1:${server.address().port}`; + }); + + afterAll(async () => { + delete process.env.EUROPE_PMC_URL; + await new Promise((resolve) => server.close(resolve)); + await new Promise((resolve) => pmc.close(resolve)); + }); + + it('/static/{id} asks Europe PMC for the PubMed id, and writes the text', async () => { + pmcAsked = []; + const response = await fetch(`${base}/ContentService/citation/static/12345`); + expect([response.status, response.headers.get('content-type')]).toEqual([ + 200, + 'text/plain; charset=utf-8', + ]); + expect(await response.text()).toMatch(/^Doe J\. A paper\./); + expect(pmcAsked).toEqual([ + '/search?query=src%3Amed+ext_id%3A12345&format=json&resultType=core', + ]); + }); + + it('/pathway/{id} is {} for an id that is no event, and export an empty 200', async () => { + globalThis.graphRows = []; + const pathway = await fetch(`${base}/ContentService/citation/pathway/R-HSA-9?dateAccessed=d`); + expect([pathway.status, await pathway.text()]).toEqual([200, '{}']); + // The id from the path, not the path's own words. + expect(globalThis.graphAsked).toEqual({ id: 'R-HSA-9' }); + const exported = await fetch( + `${base}/ContentService/citation/export?isPathway=true&id=xyz&ext=bib&dateAccessed=d` + ); + expect([exported.status, await exported.text(), exported.headers.get('content-type')]).toEqual([ + 200, + '', + null, + ]); + }); + + it('/static/{id} is "unable to fetch" for an answer Java cannot read', async () => { + globalThis.pmcAnswer = { resultList: { result: [{ ...europePmc, journalInfo: [] }] } }; + try { + const response = await fetch(`${base}/ContentService/citation/static/12345`); + expect([response.status, await response.text()]).toEqual([ + 500, + 'Unable to fetch static citation', + ]); + } finally { + delete globalThis.pmcAnswer; + } + }); + + it('export writes the file name as Tomcat writes a header, é as its Latin-1 byte', async () => { + const url = `${base}/ContentService/citation/export?isPathway=false&id=12345.%E2%82%AC%0D%0Ax%09%7F%C3%A9&ext=bib&dateAccessed=d`; + // fetch reads a header's bytes as Latin-1, so é here is the byte 0xE9. + for (const method of ['GET', 'HEAD']) { + const response = await fetch(url, { method }); + expect([method, response.headers.get('content-disposition')]).toEqual([ + method, + 'attachment; filename="reactome_citation_12345.? x\t é.bib"', + ]); + } + // A 304 -- Express's, for a matching ETag -- ends with no bytes, so Node + // does not re-read the header. By node:http: fetch adds Cache-Control: + // no-cache to a conditional request, which Express then never answers 304. + const etag = (await fetch(url)).headers.get('etag'); + const { get } = await import('node:http'); + const notModified = await new Promise((resolve, reject) => + get(url, { headers: { 'If-None-Match': etag } }, (response) => { + response.resume(); + resolve(response); + }).on('error', reject) + ); + expect([ + notModified.statusCode, + notModified.rawHeaders.includes( + 'attachment; filename="reactome_citation_12345.? x\t é.bib"' + ), + ]).toEqual([304, true]); + }); + + it("writes a Latin-1 file name whatever bytes end the response: a HEAD's Buffer, an empty one", async () => { + const { writeResult } = await import('./service.mjs'); + const { default: express } = await import('express'); + const site = express(); + site.all('/:kind', (request, response) => { + const answer = { + status: 200, + type: 'application/octet-stream', + headers: { 'Content-Disposition': 'attachment; filename="é"' }, + body: request.params.kind === 'empty' ? Buffer.alloc(0) : Buffer.from('x'), + }; + if (request.params.kind !== 'twice') return writeResult(response, answer); + // A first answer that fails to serialise, then the error answer, as + // the service's catch gives it: the header is converted once. + try { + writeResult(response, { ...answer, body: { a: 1n } }); + } catch { + writeResult(response, { status: 500, body: 'failed' }); + } + }); + const listening = await new Promise((resolve) => { + const started = site.listen(0, '127.0.0.1', () => resolve(started)); + }); + try { + for (const [method, kind] of [ + ['HEAD', 'bytes'], + ['GET', 'bytes'], + ['GET', 'empty'], + ['GET', 'twice'], + ]) { + const response = await fetch(`http://127.0.0.1:${listening.address().port}/${kind}`, { + method, + }); + expect([method, kind, response.headers.get('content-disposition')]).toEqual([ + method, + kind, + 'attachment; filename="é"', + ]); + } + } finally { + await new Promise((resolve) => listening.close(resolve)); + } + }); + + it("/static/{id} is GlobalExceptionHandler's 500 for an author Java cannot cast", async () => { + globalThis.pmcAnswer = { + resultList: { result: [{ ...europePmc, authorList: { author: ['x'] } }] }, + }; + try { + const response = await fetch(`${base}/ContentService/citation/static/12345`); + expect([response.status, (await response.json()).messages]).toEqual([ + 500, + [ + "class java.lang.String cannot be cast to class java.util.Map (java.lang.String and java.util.Map are in module java.base of loader 'bootstrap')", + ], + ]); + } finally { + delete globalThis.pmcAnswer; + } + }); + + it("/pathway/{id}'s two citations are in Java's HashMap order, image first", async () => { + const { pathwayCitations } = await import('./service.mjs'); + expect(Object.keys(pathwayCitations(event(), 'd'))).toEqual([ + 'imageCitation', + 'pathwayCitation', + ]); + }); + + it("/pathway/{id} is Java's 500 for an event it cannot cite", async () => { + // A reaction with no release date: Java's getReleaseDate().substring NPEs. + globalThis.graphRows = [ + { + root: { + id: 1, + labels: ['DatabaseObject', 'Event', 'ReactionLikeEvent', 'Reaction'], + props: { dbId: 9, stId: 'R-HSA-9', displayName: 'A reaction', schemaClass: 'Reaction' }, + }, + nodes: [], + relationships: [], + }, + ]; + try { + const response = await fetch( + `${base}/ContentService/citation/pathway/R-HSA-9?dateAccessed=d` + ); + expect([response.status, (await response.json()).messages]).toEqual([ + 500, + ['Something unexpected happened and the error has been reported.'], + ]); + } finally { + globalThis.graphRows = []; + } + }); + + it("is Spring's 400 for a missing parameter", async () => { + const response = await fetch( + `${base}/ContentService/citation/export?id=x&ext=bib&dateAccessed=d` + ); + expect((await response.json()).messages).toEqual([ + "Required request parameter 'isPathway' for method parameter type Boolean is not present", + ]); + }); +}); diff --git a/tools/content-node/service.mjs b/tools/content-node/service.mjs index b42494fe6..998fee9ce 100644 --- a/tools/content-node/service.mjs +++ b/tools/content-node/service.mjs @@ -22,9 +22,17 @@ import { createHash } from 'node:crypto'; import { readdirSync, readFileSync } from 'node:fs'; import { fileURLToPath, URLSearchParams } from 'node:url'; import neo4j from 'neo4j-driver'; -import { read, configured, close } from './graph.mjs'; +import { read, configured, close, envSetting } from './graph.mjs'; import { solr, solrConfigured } from './solr.mjs'; import { sendReport } from './report.mjs'; +import { + citationOfEvent, + eventText, + formatEventCitation, + formatStaticCitation, + imageText, + staticCitationFrom, +} from './citation.mjs'; import { enhancedQuery, findByIdParameters, @@ -2315,6 +2323,106 @@ export const endpoints = [ ); }, }, + { + path: '/ContentService/citation/pathway/{id}', + // CitationController.pathwayCitation: the Pathway Browser's "cite this" + // -- the pathway's citation and its image's, as a HashMap writes them; + // {} for an id that is no event. + handler: async (request) => { + const raw = pathId(rawSegment(request, 4)); + const date = queryValues(request, 'dateAccessed'); + if (date.length === 0) + return javaError(request, 400, 'BAD_REQUEST', requiredString('dateAccessed')); + const { citation, failure } = await eventCitationOrFailure(request, raw); + if (failure) return failure; + return { + status: 200, + type: 'application/json', + body: citation ? pathwayCitations(citation, date.join(',')) : {}, + }; + }, + }, + { + path: '/ContentService/citation/static/{id}', + // CitationController.staticCitation: a paper's citation, by PubMed id, + // from Europe PMC; Java's 500 text when it cannot be had. + handler: async (request) => { + const citation = await staticCitationFor(pathId(rawSegment(request, 4))); + if (!citation) + return { + status: 500, + type: 'text/plain;charset=UTF-8', + body: 'Unable to fetch static citation', + }; + let body; + try { + body = formatStaticCitation(citation, 'txt', null); + } catch (failure) { + return citationFailure(request, failure); + } + return { status: 200, type: 'text/plain;charset=UTF-8', body }; + }, + }, + { + path: '/ContentService/citation/export', + // CitationController.export: a citation to download as BibTeX, RIS or + // text, a pathway's or a paper's. Nothing to cite is an empty 200. + handler: async (request) => { + const flag = queryValues(request, 'isPathway'); + if (flag.length === 0) + return javaError( + request, + 400, + 'BAD_REQUEST', + "Required request parameter 'isPathway' for method parameter type Boolean is not present" + ); + const isPathway = springBoolean(flag); + if (isPathway.error) return javaError(request, 400, 'BAD_REQUEST', isPathway.error); + if (isPathway.value === undefined) + return javaError( + request, + 400, + 'BAD_REQUEST', + "Required request parameter 'isPathway' for method parameter type Boolean is present but converted to null" + ); + const values = {}; + for (const name of ['id', 'ext', 'dateAccessed']) { + const given = queryValues(request, name); + if (given.length === 0) return javaError(request, 400, 'BAD_REQUEST', requiredString(name)); + values[name] = given.join(','); + } + let citation; + if (isPathway.value) { + const found = await eventCitationOrFailure(request, values.id); + if (found.failure) return found.failure; + citation = found.citation; + } else citation = await staticCitationFor(values.id); + if (!citation) return { status: 200 }; + const format = isPathway.value ? formatEventCitation : formatStaticCitation; + let body; + try { + body = format(citation, values.ext, values.dateAccessed); + } catch (failure) { + return citationFailure(request, failure); + } + const [extension, type] = + values.ext === 'bib' + ? ['bib', 'application/x-bibtex'] + : values.ext === 'ris' + ? ['ris', 'application/x-research-info-systems'] + : ['txt', 'text/plain']; + return { + status: 200, + type: `${type};charset=UTF-8`, + headers: { + 'Content-Disposition': tomcatHeader( + `attachment; filename="reactome_citation_${values.id}.${extension}"` + ), + }, + body, + }; + }, + }, { path: '/ContentService/data/instance/{id}/referrers', // SchemaController.getInstanceReferrers, for the website's detail pages: @@ -6385,6 +6493,100 @@ function searchAnswer(request, query, result) { return { ...missing, body: javaJson(envelope) }; } +/** + * CitationController.getEventCitationObject: an event's citation from its + * enhanced object (graph-core's findEnhancedObjectById); undefined for an id + * that is no event. What goes into it is citationOfEvent's. + */ +async function eventCitationFor(raw) { + const id = inDepthId(raw); + if (!id) return undefined; + const [row] = await read( + enhancedQuery({ + idType: id.idType, + summarise: false, + includeDisease: true, + outgoingOnly: false, + }), + { id: id.id } + ); + if (!row) return undefined; + const event = mapResult(row); + if (!isA(event.schemaClass, 'Event')) return undefined; + const version = endpoints.find((e) => e.path.endsWith('/data/database/version')); + const release = String((await version.handler({ params: {}, query: {} })).body); + return citationOfEvent(event, raw, release, isA(event.schemaClass, 'Pathway')); +} + +/** + * An event's citation, or Java's GlobalExceptionHandler 500 when Java's + * getEventCitationObject throws -- no release date, or a person with no + * initial. + */ +async function eventCitationOrFailure(request, raw) { + try { + return { citation: await eventCitationFor(raw) }; + } catch (failure) { + return { failure: citationFailure(request, failure) }; + } +} + +/** GlobalExceptionHandler's 500 for what citation.mjs throws as Java does; anything else is ours. */ +function citationFailure(request, failure) { + if (failure.unexpected) return unexpectedFailure(request); + if (failure.javaMessage) + return javaError(request, 500, 'INTERNAL_SERVER_ERROR', failure.javaMessage); + throw failure; +} + +/** A header value as Tomcat writes it: past Latin-1 a '?', a control character a space. */ +function tomcatHeader(text) { + return [...text] + .map((char) => { + const code = char.codePointAt(0); + if (code > 0xff) return '?'; + return (code < 0x20 && char !== '\t') || code === 0x7f ? ' ' : char; + }) + .join(''); +} + +/** The two citations of /citation/pathway/{id}, in the order Java's HashMap writes them. */ +export function pathwayCitations(citation, date) { + const texts = { + pathwayCitation: eventText(citation, date), + imageCitation: imageText(citation, date), + }; + const body = {}; + for (const key of hashSetOf(['pathwayCitation', 'imageCitation']).keys()) body[key] = texts[key]; + return body; +} + +/** CitationController.getStaticCitationObject: Europe PMC's record of a PubMed id, or undefined. */ +async function staticCitationFor(id) { + const query = new URLSearchParams(); + query.set('query', `src:med ext_id:${id}`); + query.set('format', 'json'); + query.set('resultType', 'core'); + const base = envSetting( + 'EUROPE_PMC_URL', + 'https://www.ebi.ac.uk/europepmc/webservices/rest/search' + ); + // Java's try covers the request and every read of the answer, so anything + // Europe PMC sends that Java cannot read is "unable to fetch". Only a name + // we got wrong is a mistake of ours. + try { + const response = await fetch(`${base}?${query}`, { signal: AbortSignal.timeout(30_000) }); + if (response.status !== 200) { + await response.body?.cancel(); + return undefined; + } + return staticCitationFrom(await response.json()); + } catch (failure) { + if (failure instanceof ReferenceError) throw failure; + return undefined; + } +} + /** A FacetMapping endpoint's answer: the mapping, or Java's empty 200 for its null. */ function facetAnswer(answer) { const mapping = facetMapping(answer); @@ -6508,6 +6710,38 @@ function buildId() { } } +const LATIN1_DISPOSITION = Symbol('latin1Disposition'); + +/** + * Node reads a Content-Disposition value back as UTF-8 when the head goes + * out with a body's bytes counted (nodejs/node#46528) -- so the Latin-1 byte + * Tomcat writes for é became U+FFFD. Decided at end(), on the bytes Node is + * given (a 304's '' and Express's bodiless HEAD are not converted, a HEAD's + * Buffer is): then the value goes in as its UTF-8 bytes, and comes out é as + * long as the head is written on its own, as Latin-1 -- which it is, because + * Express hands end() a Buffer whenever it computes an ETag. Installed once + * per response, so a second writeResult (an error after a first) does not + * convert twice. + */ +function latin1Disposition(response) { + if (response[LATIN1_DISPOSITION]) return; + response[LATIN1_DISPOSITION] = true; + const end = response.end.bind(response); + response.end = (chunk, ...rest) => { + const encoding = typeof rest[0] === 'string' ? rest[0] : 'utf8'; + const bytes = + typeof chunk === 'string' + ? Buffer.byteLength(chunk, encoding) + : chunk && typeof chunk !== 'function' + ? chunk.length + : 0; + const value = bytes > 0 && !response.headersSent && response.getHeader('Content-Disposition'); + if (typeof value === 'string') + response.setHeader('Content-Disposition', Buffer.from(value, 'utf8').toString('latin1')); + return end(chunk, ...rest); + }; +} + /** * A handler's answer on the wire. Objects go out as JSON written as Jackson * writes it (javaJson, not res.json's JSON.stringify); strings as they are, so @@ -6519,8 +6753,9 @@ function buildId() { export function writeResult(response, result) { response.status(result.status); if (result.type) response.type(result.type); - for (const [name, value] of Object.entries(result.headers ?? {})) response.setHeader(name, value); const body = result.body !== undefined || Boolean(result.serialised); + for (const [name, value] of Object.entries(result.headers ?? {})) response.setHeader(name, value); + latin1Disposition(response); const redirect = result.status >= 300 && result.status < 400; if (body && !redirect && response.req && downloadGuard(response.req)) response.setHeader('Content-Disposition', 'inline;filename=f.txt');