#!/usr/bin/env node /* check-install.mjs — AN INSTALLATION, FOR REAL, FROM END TO END. * * The installer is the most consequential file in this project: it is the one * that writes the configuration, and it runs exactly once on somebody's host, * where nobody is watching. Until this file existed, nothing tested it. The * suite compared its two copies byte for byte and checked nothing about what * it DOES. * * So this runs it: a throwaway copy of webroot/, a real PHP server in front of * it, the form answered as a person would answer it, and then the questions * that matter -- was a configuration written, does it parse, does it declare * what was asked for, is the data file out of reach, and does a second run * refuse rather than overwrite. * * WHY THE WORKER COUNT IS SET, and it is not a detail: the installer proves * the data file is unreachable over HTTP by REQUESTING ITS OWN ADDRESS. A * single-worker development server cannot answer itself while it is busy * serving the installer, so it deadlocks, and the installer -- correctly -- * refuses to finish and says so. That refusal is the right behaviour and this * test would otherwise measure only that. PHP_CLI_SERVER_WORKERS gives the dev * server the second worker a real host has. * * Skipped, loudly, where there is no php: a check that cannot run must not * report that it passed. */ import { spawn, spawnSync } from 'node:child_process'; import { createServer } from 'node:net'; import { mkdtempSync, cpSync, rmSync, existsSync, readFileSync, readdirSync, chmodSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { createHash } from 'node:crypto'; import { join, dirname } from 'node:path'; import { fileURLToPath } from 'node:url'; const here = dirname(fileURLToPath(import.meta.url)); const webroot = join(here, '..', 'server', 'webroot'); const php = spawnSync('php', ['-r', 'echo PHP_VERSION;'], { encoding: 'utf8' }); if (php.error || php.status !== 0) { console.log('install: no php on this machine, nothing was run'); process.exit(0); } if ((spawnSync('php', ['-r', 'echo extension_loaded("pdo_sqlite")?"yes":"no";'], { encoding: 'utf8' }).stdout || '').trim() !== 'yes') { console.log('install: php has no pdo_sqlite, nothing was run'); process.exit(0); } const failures = []; const check = (what, ok, detail) => { if (!ok) failures.push(what + (detail ? '\n ' + String(detail).replace(/\n/g, '\n ') : '')); }; const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); /* EVERY RESPONSE IS READ TO THE END, EVEN WHEN ONLY ITS STATUS IS WANTED. A body left unread keeps the socket with its parser paused -- the installer's page is 90 KB, more than a socket buffers -- and when the test server is killed under it, the fetch of Node 24 (the one GitHub's runners use) dies on `assert(!this.paused)` and takes the whole suite with it. Node 22 did not, which is how it went unseen on a workstation and red in CI. */ const answered = async (response) => { try { await response.arrayBuffer(); } catch (e) { /* the status is what was asked */ } return response; }; /* A PORT NOBODY ELSE HOLDS, ASKED OF THE SYSTEM RATHER THAN CHOSEN. A fixed number cost an afternoon: a crashed run left its server listening, the next run failed to bind, and every request went to the OLD installation -- which answered "already installed" and made the new code look broken. The system knows what is free; we do not. */ const freePort = () => new Promise((resolve, reject) => { const probe = createServer(); probe.on('error', reject); probe.listen(0, '127.0.0.1', () => { const { port } = probe.address(); probe.close(() => resolve(port)); }); }); /** A throwaway installation: its own directory, its own server, its own port. */ const rehearse = async (port, body, prepare) => { const dir = mkdtempSync(join(tmpdir(), 'annotepage-install-')); const root = join(dir, 'web'); cpSync(webroot, root, { recursive: true }); if (prepare) prepare(dir, root); const server = spawn('php', ['-S', '127.0.0.1:' + port], { cwd: root, env: { ...process.env, PHP_CLI_SERVER_WORKERS: '4' }, stdio: 'ignore', }); const url = 'http://127.0.0.1:' + port + '/install.php'; let up = false; for (let i = 0; i < 40 && !up; i += 1) { await sleep(150); try { up = (await answered(await fetch(url, { redirect: 'manual' }))).ok; } catch (e) { /* not listening yet */ } } const form = up ? await (await fetch(url, { redirect: 'manual' })).text() : ''; const done = up ? await (await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: body, redirect: 'manual', })).text() : ''; const again = up ? await (await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: body, redirect: 'manual', })).text() : ''; const configPath = join(root, 'internal', 'config-local.php'); const config = existsSync(configPath) ? readFileSync(configPath, 'utf8') : null; /* THE API, OVER PLAIN HTTP, ON THE INSTALLATION IT JUST WROTE. Not followed: what is being measured IS the redirect. A configuration that let the API answer over http would let a browser reach it without a secure context, and WebCrypto -- which is where the notes are sealed -- does not exist there. */ const api = up ? await answered(await fetch('http://127.0.0.1:' + port + '/api.php?action=diagnostic', { redirect: 'manual' })) : null; return { dir, root, port, up, form, done, again, config, configPath, server, apiStatus: api ? api.status : 0, apiLocation: api ? (api.headers.get('location') || '') : '' }; }; const stop = (run) => { try { run.server.kill('SIGKILL'); } catch (e) { /* already gone */ } rmSync(run.dir, { recursive: true, force: true }); }; /* -- One site's own server, on a file ----------------------------------- */ const own = await rehearse(await freePort(), 'storage=sqlite&audience=mine&updates=cron'); check('the server under test never came up', own.up); /* THE THREE QUESTIONS THE SITE PROMISES. how-to-install-it.html says "Answer its three questions", and these are them: who it answers for, where the notes go, who keeps it current. Everything else on that form belongs to the MySQL answer. If a fourth question ever appears here, the page that promises three has to change with it. */ for (const field of ['audience', 'storage', 'updates']) { check(`the form does not ask "${field}"`, own.form.includes(`name="${field}"`)); } /* AND THE ADDRESS, WHICH IS NOT A QUESTION BUT MUST BE VISIBLE. The browser face reads it off the request that opened the page -- right almost always, invisible always -- and the two cases where it is wrong are ordinary: a proxy or CDN whose public name is not the one PHP sees, and an installation done through a temporary address. It goes into `data-server` on every page, so getting it silently wrong is a tag that loads nothing under a screen that said everything went well. */ check('the form does not show the address it will write into the tag', own.form.includes('name="api_address"')); check('the address field is not pre-filled with the address this request arrived at', own.form.includes('name="api_address" value="http://127.0.0.1:' + own.port + '/api.php"'), (own.form.match(/name="api_address" value="[^"]*"/) || ['(absent)'])[0]); /* EVERY KEY THERE IS, AND A FIELD FOR IT. The form asks three questions and folds the rest, which is a way of not frightening anybody -- but a person looking for one setting must be able to find out whether it exists at all, and the answer cannot be "read config.php". So: every key of ap_config_defaults() is either a field on this form and an option on the command line, or it is in the list below, which names what the three questions and the MySQL box already decide. A key added to config.php and to neither lands here, loudly, on the day it is added. The exemptions are exempt for a reason each, and none of them is "it is specific": `projects` descends from a key this server never receives, and the rest are what the questions answered. */ const decidedByTheQuestions = { active: 'written true by the act of installing', storage: 'the storage question', database: 'the MySQL box, field by field', allow_plain_mode: 'the audience question', require_origin_on_writes: 'the audience question', open_registration: 'the audience question', auto_update: 'the updates question', update_token: 'generated by the updates question, shown once', deployment: 'read from older files, never written by this one', projects: 'descends from a key the browser generates and this server never sees', }; const askPhp = (code) => spawnSync('php', ['-r', 'define("AP_INTERNAL", 1); require ' + JSON.stringify(join(webroot, 'internal', 'install-flow.php')) + '; ' + code], { encoding: 'utf8' }).stdout.trim(); const everyKey = askPhp('echo implode(" ", array_keys(ap_config_defaults()));').split(/\s+/); const options = askPhp('echo implode(" ", array_keys(ap_i_cli_options()));').split(/\s+/); for (const key of everyKey.filter(Boolean)) { if (decidedByTheQuestions[key]) continue; check(`config.php has "${key}" and the form has no field for it` + ' -- every key is either asked or in the list of what the questions decide', own.form.includes(`name="${key}"`)); check(`config.php has "${key}" and the command line has no option for it`, options.includes(key.replace(/_/g, '-'))); } /* AND THE EXAMPLE FILE NAMES THEM TOO. --help sends whoever wants the rest to internal/config-local.example.php, "with every key there is"; that sentence was true when it was written and had stopped being true thirteen keys later. `deployment` is the exception and stays one: it is read from files older installers wrote and is never written again, so naming it in an example would be offering it. */ const example = readFileSync(join(webroot, 'internal', 'config-local.example.php'), 'utf8'); for (const key of everyKey.filter(Boolean)) { if (key === 'deployment') continue; check(`config-local.example.php does not name "${key}", and --help says it names` + ' every key there is', example.includes("'" + key + "'")); } /* THE MySQL FIELDS FOLLOW THE ANSWER, WITH NO JAVASCRIPT. Choosing MySQL used to change nothing on the screen: the five fields the installation cannot do without sat behind a fold somebody had to think to open. They are a box now, hidden by the OTHER answer -- `form:has(#s-sqlite:checked) .if-mysql-box`. That order matters and is what this checks: a browser too old for `:has()` ignores the rule and shows the fields, which is what everybody had before. Never the reverse, which would hide them from the browser that cannot know they should come back. */ check('the MySQL fields are not in a box of their own', own.form.includes('if-mysql-box')); check('the box is hidden by anything other than the SQLite answer being checked', own.form.includes('form:has(#s-sqlite:checked) .if-mysql-box { display: none; }'), (own.form.match(/[^\n]*if-mysql-box[^\n]*display[^\n]*/) || ['(no rule)'])[0]); for (const field of ['host', 'port', 'name', 'user', 'password']) { check(`the form no longer asks for the MySQL ${field}`, own.form.includes(`name="${field}"`)); } /* AND EVERY SETTING IS UNDER A NAMED SECTION, not in one fold called "change anything else" -- which says a list exists without saying what is in it, so whoever came to set a retention has to open it and read fifteen fields to find one. The sections are data, like the settings themselves; this refuses a setting that belongs to none of them, which is what a new key added without a thought would be. */ const sections = askPhp('echo implode(" ", array_keys(ap_i_setting_sections()));') .split(/\s+/).filter(Boolean); check('the installer declares no sections at all', sections.length >= 3, sections.join(' ')); const grouped = askPhp('foreach (ap_i_settings() as $s) { echo $s["key"], "=",' + ' isset($s["group"]) ? $s["group"] : "(none)", "\n"; }') .split('\n').filter(Boolean).map((l) => l.split('=')); for (const [key, group] of grouped) { check(`the setting "${key}" is in no section, so the form would drop it`, sections.includes(group), group); } for (const title of askPhp('foreach (ap_i_setting_sections() as $s) { echo $s["title"], "\n"; }') .split('\n').filter(Boolean)) { check(`the form does not carry the section "${title}"`, own.form.includes(title.replace(/&/g, '&')), title); } /* AND WHAT IS FOLDED STAYS THE EXCEPTION. A fold says "you may ignore this", which is false of the numbers an operator came to set: retention, the caps, the counters. Those are headings now, always on screen. What is left behind a summary is what is genuinely extra -- and its title has to say so, so that nobody has to open it to find out whether it matters. Three folds: the environment report, the rarely-needed settings, and the two that can undo the tool. A fourth means somebody folded something that should be read. */ const folds = [...own.form.matchAll(/([\s\S]*?)<\/summary>/g)] .map((m) => m[1].replace(/<[^>]+>/g, '').replace(/—/g, '--').trim()); check(`the form has ${folds.length} folds, more than the three that earn one`, folds.length <= 3, folds.join(' | ')); /* AND NO SECTION OF SETTINGS IS A FOLD OF ITS OWN. One control opens the panel; inside it the sections are headings, drawn in the order the table declares them. A section behind a second summary puts a setting two clicks away and makes the list of titles unreadable. */ const sectionTitles = askPhp('foreach (ap_i_setting_sections() as $s) {' + ' echo $s["title"], "\n"; }').split('\n').filter(Boolean); for (const title of sectionTitles) { check(`the section "${title}" is behind a fold of its own`, !folds.some((f) => f.includes(title))); } const drawn = [...own.form.matchAll(/

([^<]*)<\/p>/g)] .map((m) => m[1].replace(/—/g, '--').trim()); const declared = sectionTitles.map((t) => t.replace(/—/g, '--').trim()); check('the sections are not drawn in the order the table declares them', drawn.join('|') === declared.join('|'), drawn.join(' | ') + ' against ' + declared.join(' | ')); /* AND IT STAYS A FORM, NOT A BOOK. Every setting used to print the whole paragraph that --help prints, and the screen measured 1756 words -- more than the entire install page of the website. A fold that opens onto a book is a fold nobody reads, so the settings that matter get skipped along with the rest. The form prints the short line; --help prints the paragraph. Two rules, because prose comes back one sentence at a time: a ceiling on the whole screen, and a ceiling on any one line under a field. */ const words = (html) => { const text = html.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/g, ' ') .replace(/<[^>]+>/g, ' '); return (text.match(/[A-Za-z'\u2019-]+/g) || []).length; }; /* TWO CEILINGS, AND THE TIGHT ONE IS ON THE THING THE RULE WAS WRITTEN FOR. It was one number over the whole document, which measured the wrong thing the moment the page gained a heading that says what is about to be written and a table of what an untouched install will write -- 89 and 107 words of fact that nobody should cut. The defect was never "words on the page", it was a PARAGRAPH UNDER EVERY FIELD: 1756 words of which 1214 sat in those notes. So the prose under the fields has its own ceiling, close to what it costs today, and the document keeps a looser one that still catches the day somebody prints `say` again. */ /* MEASURED ON WHAT IS SHOWN, NOT ON WHAT IS SENT. The page carries both registers of every sentence since the reader stopped having to reload for the long one; counting the markup would count a paragraph nobody is looking at and read as a page twice as wordy as it is. The long spans come out first -- and the check above refuses a page that has lost them, so this cannot become a way of hiding prose from the count. */ const shown = own.form.replace(/[\s\S]*?<\/span>/g, ''); const noteWords = [...shown.matchAll(/

([\s\S]*?)<\/p>/g)] .reduce((n, m) => n + words(m[1]), 0); check(`the sentences under the fields are ${noteWords} words, over the 450 they` + ' are allowed -- that is where the 1214 were when this screen was a book', noteWords <= 450); const onScreen = words(shown); check(`the install screen is ${onScreen} words, over the 1200 it is allowed` + ' -- it printed 1756 once, and a screen that opens onto a book is not read', onScreen <= 1200); for (const line of askPhp('foreach (ap_i_settings() as $s) { echo $s["key"], "=",' + ' $s["hint"], "\n"; }').split('\n').filter(Boolean)) { const [key, hint] = [line.slice(0, line.indexOf('=')), line.slice(line.indexOf('=') + 1)]; check(`the line under "${key}" is ${hint.length} characters, over the 140 a form` + ' owes: what does not fit belongs in --help', hint.length <= 140, hint); } /* AND THE THIRD UPDATE ANSWER IS OFFERED ON BOTH FACES. It was refused by the shell and drawn as unavailable on a host whose PHP interface cannot hand the response over -- which reads as prudence and is a refusal: `auto_update` is the answer for a host with neither a shell nor a scheduler, and on such a host it was the only route there was. It is not broken there, it is a wait: 0.3 s for the daily check, 2.3 s for an update that replaces nine files, measured against the real release. The installer says the number instead of taking the choice away. */ check('the form does not offer "It updates itself"', own.form.includes('value="self"') && !own.form.includes('id="u-self" disabled')); const self = spawnSync('php', [join(webroot, 'install.php'), '--help', '--verbose'], { encoding: 'utf8' }).stdout || ''; check('--help says the third answer is not offered', !/There is no --updated-by=self/.test(self)); check('no configuration was written', own.config !== null, own.done.slice(0, 400)); if (own.config) { const parses = spawnSync('php', ['-l', own.configPath], { encoding: 'utf8' }); check('the configuration it wrote does not parse', parses.status === 0, parses.stdout); for (const [what, wanted] of [ /* The word that used to say both is gone; the two things it decided are written as themselves. An older configuration still carrying it is read as before -- there are two such fixtures below. */ ['plain mode allowed', "'allow_plain_mode' => true"], ['no Origin required', "'require_origin_on_writes' => false"], ['storage', "'storage' => 'sqlite'"], ['retention', "'max_note_age_days' => 90"], ['server totals, off', "'publish_server_totals' => false"], ['an empty projects array', "'projects' => array()"], /* TURNED OFF, NOT LEFT TO BE MET. On a server carrying one site's own notes there is nobody to defend against: everybody who can write is already behind the same door as the site. A limit that can only ever refuse honest work is friction wearing a security shape. */ ['the project write limit switched off', "'rate_writes_per_project' => 0"], ['the export limit switched off', "'rate_exports_per_ip' => 0"], ]) { check(`the configuration does not declare ${what}`, own.config.includes(wanted)); } /* THE DATA FILE, AND THE ONE THING THAT MATTERS ABOUT IT. Inside the document root it can be fetched over HTTP, and an .htaccess does nothing under nginx -- so the installer places it above, and only falls back to inside with two guard files. Both outcomes are acceptable; a bare file inside is not. */ const file = (own.config.match(/'file'\s*=>\s*'([^']+)'/) || [])[1]; check('the configuration names no data file', Boolean(file)); if (file) { const inside = file.startsWith(own.root + '/'); const guarded = inside && existsSync(join(dirname(file), '.htaccess')) && existsSync(join(dirname(file), 'index.php')); check('the data file sits in the document root with no guard', !inside || guarded, file); } } /* WHAT THE LAST SCREEN HANDS OVER. ONE daily line, with the real path of this installation in it -- the update, which maintains after it updates. It handed over two, update and sweep, and a reader asked why a server needs two jobs; a second line on this screen now would be that question coming back. An example is a thing to adapt, and the adaptation is where it goes wrong on a host whose operator has a control panel and no shell. */ check('the last screen hands over a second cron line for the sweep', !own.done.includes('internal/maintenance.php')); check('the last screen does not hand over the update line', own.done.includes('internal/update.php')); check('the last screen does not say the update line also sweeps', own.done.includes('--only-maintenance')); check('the last screen does not say how long a remark is kept', own.done.includes('How long a remark is kept')); /* AND IT REFUSES THE SECOND TIME. An installer that rewrote a live configuration because somebody reloaded a page would be a way to lose a server, and this is the only place that can prove it does not. */ check('a second run did not refuse', own.again.includes('already installed'), own.again.slice(0, 300)); const after = own.config === null ? null : readFileSync(own.configPath, 'utf8'); check('a second run rewrote the configuration', after === own.config); check('the API answers over plain http after the install', own.apiStatus === 308, 'status ' + own.apiStatus); check('the redirect does not lead to the same address in https', /^https:\/\/127\.0\.0\.1:\d+\/api\.php/.test(own.apiLocation), own.apiLocation); /* ONE SCRIPT, AND THE POLICY ADMITS THAT SCRIPT AND NOTHING ELSE. The page had no script for thirty releases; it has the copy button now, and what keeps an installer from running somebody else's code is that the header names the one it runs by its bytes. So: exactly one