@jrpool/kilotest 52.0.0 → 57.0.1

package/util.ts

@@ -14,6 +14,7 @@ import type {Act, Catalog, Report, StandardInstance} from 'testaro';
 import crypto from 'node:crypto';
 import dns from 'node:dns/promises';
 import fs from 'node:fs/promises';
+import ipaddr from 'ipaddr.js';
 import net from 'node:net';
 import path from 'node:path';
 import querystring from 'node:querystring';
@@ -77,9 +78,13 @@ export type TestRequest = {
 // Test requests by URL.
 export type TestRequests = Record<string, TestRequest[]>;
 
-// Test request addition result.
+// Test request addition result. 'reportExists' means a report already exists for a
+// page a newTest request or order named (an outcome), distinct from the 'retest'
+// requestType discriminant elsewhere in this file, which means the caller asked to
+// retest a page that already has a report (a request kind); the two must not be
+// confused with one another.
 export type TestRequestResult
-= 'url' | 'description' | 'retest' | 'duplicate' | 'superseded' | 'nonreport' | 'ok';
+= 'url' | 'description' | 'reportExists' | 'duplicate' | 'superseded' | 'nonreport' | 'queueFull' | 'ok';
 
 // Target of a new-test or retest request: a description and URL for a new-test request,
 // or the timeStamp and jobID of the cited report for a retest request.
@@ -551,47 +556,41 @@ export const isURL = (string: string): boolean => {
     return false;
   }
 };
-// Returns whether an IPv4 address (in dotted-decimal form) is in a private,
-// loopback, link-local, or otherwise non-public range, including the
-// 169.254.169.254 cloud-metadata address (which falls under link-local).
-const isNonPublicIPv4 = (address: string): boolean => {
-  const octets = address.split('.').map(Number);
-  const [a, b = 0] = octets;
-  return (
-    a === 127 || // loopback
-    a === 10 || // private
-    a === 0 || // "this network"
-    (a === 172 && b >= 16 && b <= 31) || // private
-    (a === 192 && b === 168) || // private
-    (a === 169 && b === 254) || // link-local, incl. cloud metadata
-    (a === 100 && b >= 64 && b <= 127) // carrier-grade NAT
-  );
-};
-// Returns whether an IPv6 address is in a loopback, unique-local, or
-// link-local range.
-const isNonPublicIPv6 = (address: string): boolean => {
-  const normalized = address.toLowerCase();
-  return (
-    normalized === '::1' // loopback
-    || normalized === '::' // unspecified
-    || /^::ffff:/.test(normalized) && isNonPublicIPv4(normalized.replace(/^::ffff:/, '')) // IPv4-mapped
-    || /^f[cd][0-9a-f]{2}:/.test(normalized) // unique local (fc00::/7)
-    || /^fe[89ab][0-9a-f]:/.test(normalized) // link-local (fe80::/10)
-  );
-};
+// The ipaddr.js range labels, for each address family, that are not part of
+// the public, globally routable address space and so must never be a testing
+// target. Sourced from ipaddr.js's own IPv4/IPv6 SpecialRanges tables, which
+// track the IANA special-purpose address registries (e.g. RFC 1918 private
+// ranges, RFC 5737/3849 documentation ranges, RFC 6598 carrier-grade NAT,
+// RFC 6890 link-local, including the 169.254.169.254 cloud-metadata address).
+// A version bump of ipaddr.js is not pinned or specially reviewed here (this
+// deployment always installs the latest of every dependency); instead, the
+// isAllowedTarget/isAllowedRedirectTarget tests enumerate specific addresses
+// in every one of these ranges, so a future release that narrowed this
+// coverage would fail those tests rather than silently allowing an address
+// that should be rejected.
+const nonPublicIPv4Ranges = new Set([
+  'unspecified', 'broadcast', 'multicast', 'linkLocal', 'loopback', 'carrierGradeNat', 'private', 'reserved'
+]);
+const nonPublicIPv6Ranges = new Set([
+  'unspecified', 'linkLocal', 'multicast', 'loopback', 'uniqueLocal', 'deprecatedSiteLocal', 'discard',
+  'rfc6145', 'rfc6052', '6to4', 'teredo', 'benchmarking', 'amt', 'as112v6', 'deprecatedOrchid', 'orchid2'
+]);
 // Returns whether an IP address (v4 or v6) is outside the public address
 // space, i.e. is a loopback, private, link-local, or other reserved address
 // that a public deployment should never intend to test.
 const isNonPublicIP = (address: string): boolean => {
-  const version = net.isIP(address);
-  if (version === 4) {
-    return isNonPublicIPv4(address);
+  let parsed;
+  try {
+    // process(), rather than parse(), so an IPv4-mapped IPv6 address (e.g.
+    // ::ffff:10.0.0.5) is unwrapped and classified by its embedded IPv4 address.
+    parsed = ipaddr.process(address);
   }
-  if (version === 6) {
-    return isNonPublicIPv6(address);
+  catch {
+    // Not a recognizable IP address, so treat it as non-public, i.e. as unsafe.
+    return true;
   }
-  // Not a recognizable IP address, so treat it as non-public, i.e. as unsafe.
-  return true;
+  const ranges = parsed.kind() === 'ipv4' ? nonPublicIPv4Ranges : nonPublicIPv6Ranges;
+  return ranges.has(parsed.range());
 };
 // Returns whether ALLOW_INTERNAL_TARGETS opts this deployment in to testing
 // pages at private, loopback, or link-local addresses. A deployment that
@@ -621,7 +620,9 @@ export const isAllowedTarget = async (url: string, lookup: LookupAll = dns.looku
   }
   let hostname: string;
   try {
-    hostname = new URL(url).hostname;
+    // URL.hostname keeps the surrounding brackets of a literal IPv6 host (e.g.
+    // "[::1]"), which net.isIP and dns.lookup both reject, so they are stripped here.
+    hostname = new URL(url).hostname.replace(/^\[(.*)\]$/, '$1');
   } catch {
     return false;
   }
@@ -640,6 +641,33 @@ export const isAllowedTarget = async (url: string, lookup: LookupAll = dns.looku
     return false;
   }
 };
+// Returns whether a URL, when actually requested, resolves through any
+// redirects to a final response whose URL is an allowed target. isAllowedTarget
+// only resolves DNS, so it cannot see an application-layer redirect (e.g. a
+// legitimately resolving host issuing a 302 to a private address); this
+// check is what can catch that at request time, before a job is ever queued.
+// It cannot catch a redirect introduced after it runs, e.g. an attacker who
+// reconfigures the target host once a request is accepted, so isAllowedReport
+// remains the backstop that re-checks the URL a worker actually visited.
+export const isAllowedRedirectTarget = async (
+  url: string, fetchImpl: typeof fetch = fetch, lookup: LookupAll = dns.lookup
+): Promise<boolean> => {
+  // If this deployment allows internal targets, every syntactically valid URL is
+  // allowed, and no fetch is needed, consistent with isAllowedTarget's own early return.
+  if (allowsInternalTargets()) {
+    return true;
+  }
+  let response: Response;
+  try {
+    // redirect: 'follow' is the default, but named here because observing
+    // where redirects lead is the entire purpose of this request.
+    response = await fetchImpl(url, {redirect: 'follow', signal: AbortSignal.timeout(10000)});
+  } catch {
+    // An unreachable or errored target cannot be verified as safe either way.
+    return false;
+  }
+  return isAllowedTarget(response.url, lookup);
+};
 // Returns whether a string is the authorization code, the shared check every
 // manager-facing page and action uses to gate a submission. Centralized so all call
 // sites compare against process.env.AUTH_CODE the same way.
@@ -1070,11 +1098,40 @@ const getApprovedJobProperty = async (
 // its addition to testRequests.json are both decided inside the lock, as a single
 // atomic operation, so no caller-visible seam exists where an approvability decision
 // could be based on stale information about testRequests.json.
+// Returns the non-negative-integer value of an environment variable, or a default if the
+// variable is unset, empty, or not a non-negative integer. Read at call time, not cached,
+// so a variable set (e.g. in .env) after this module first loads still takes effect. Used
+// by the "inbox full" caps below (test requests, tutorial comments, feature requests),
+// which different Kilotest deployments' maintainers may reasonably want sized differently.
+// A value of 0 means no limit, mirroring how these caps are checked (never reached).
+export const getEnvMax = (name: string, defaultValue: number): number => {
+  const raw = process.env[name];
+  if (!raw) {
+    return defaultValue;
+  }
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : defaultValue;
+};
+// Maximum number of test/retest requests awaiting approval at once, across all URLs.
+// Once reached, a new, distinct request is rejected rather than added, so the pending
+// queue and the manager alert emails it generates cannot grow without bound (see GitHub
+// issue #3, abuse type 3, repeated/automated test-request submissions). Modeled on a full
+// mailbox rejecting new mail, rather than on a submission rate limit, since it is the
+// backlog itself, not how quickly it grows, that costs the manager review time and risks
+// unbounded storage. Configurable via TEST_REQUEST_QUEUE_MAX, since different Kilotest
+// deployments' maintainers may want a different size; a value of 0 means no limit.
+const testRequestQueueMax = () => getEnvMax('TEST_REQUEST_QUEUE_MAX', 20);
+// Returns a cap for display in an alert message: the cap itself, or "no limit" if the
+// cap is 0.
+export const describeMax = (max: number): string => max === 0 ? 'no limit' : String(max);
+// Returns the total number of test/retest requests awaiting approval, across all URLs.
+const getPendingTestRequestCount = (testRequests: TestRequests): number =>
+  Object.values(testRequests).reduce((total, requests) => total + requests.length, 0);
 export const processTestRequest = (
   reason: string,
   target: TestRequestTarget
 ): Promise<ProcessRequestResult> => testRequestsLock(async (): Promise<ProcessRequestResult> => {
-  let requestType: 'test' | 'retest';
+  let requestType: 'newTest' | 'retest';
   let description: string;
   let url: string;
   // Whether the cited report (for a retest) has been superseded by a later one.
@@ -1099,7 +1156,7 @@ export const processTestRequest = (
   }
   // Otherwise, i.e. if the target is a page to test for the first time:
   else {
-    requestType = 'test';
+    requestType = 'newTest';
     ({description, url} = target);
   }
   try {
@@ -1133,13 +1190,20 @@ export const processTestRequest = (
       return {result: 'superseded', description, url};
     }
     // Otherwise, if the request is to test a new page for which a report already exists:
-    if (requestType === 'test') {
+    if (requestType === 'newTest') {
       const reportExtracts = await getReportExtracts();
       if (reportExtracts.some(report => report.description === description && report.url === url)) {
         // Return this.
-        return {result: 'retest', description, url};
+        return {result: 'reportExists', description, url};
       }
     }
+    // Otherwise, i.e. if the request is genuinely new, if the queue of requests awaiting
+    // approval is already full (a cap of 0 means no limit, so the queue is never full):
+    const queueMax = testRequestQueueMax();
+    if (queueMax > 0 && getPendingTestRequestCount(requests) >= queueMax) {
+      // Return this.
+      return {result: 'queueFull', description, url};
+    }
     // The request is eligible, so get the requests awaiting approval.
     const testRequests = await getTestRequests();
     // Add the request to them, initializing them with the URL if necessary.
@@ -1152,10 +1216,14 @@ export const processTestRequest = (
     await fs.writeFile(testRequestsPath(), getJSON(testRequests));
     // Get an email-safe version of the reason.
     const plainReason = getPlainText(reason);
-    // Alert a manager.
+    // Alert a manager, including the resulting queue size, so a maintainer who has been
+    // away sees at a glance how urgently the queue needs review (approval or rejection)
+    // rather than learning this only once it is already full.
+    const requestTypeLabel = requestType === 'newTest' ? 'a new test' : 'a retest';
     await sendAlert(
-      `Kilotest: new ${requestType} request awaits approval`,
-      `Page description: ${description}\nURL: ${url}\nReason: ${plainReason}`
+      `Kilotest: request for ${requestTypeLabel} awaits approval`,
+      `Page description: ${description}\nURL: ${url}\nReason: ${plainReason}\n` +
+      `Requests now awaiting approval: ${getPendingTestRequestCount(testRequests)} of ${describeMax(queueMax)}`
     );
     // Return success.
     return {result: 'ok', description, url};
@@ -1165,6 +1233,169 @@ export const processTestRequest = (
     throw new Error('Failed to process test request', {cause: error});
   }
 });
+// Maximum number of jobs allowed in the job queue (db/jobs/queue) at once. This queue is
+// shared by every path that enqueues a job: manual approval of a pending test/retest
+// request (web/enqueue), and any tool (such as orderNewTest) that enqueues directly. The cap
+// therefore protects the queue itself, not any one source of jobs; a value of 0 means no
+// limit. Configurable via JOB_QUEUE_MAX.
+const jobQueueMax = () => getEnvMax('JOB_QUEUE_MAX', 20);
+// Result of orderJob. description and url are absent only when the result is
+// 'nonreport' (a retest order citing a report that does not exist), matching
+// ProcessRequestResult's own discriminated-union shape. There is no pending approval
+// inbox to compare against, so 'duplicate' (an identical pending request) never applies.
+// jobID (the enqueued job's own identifier, timeStamp-jobID) is present only on 'ok'.
+export type OrderJobResult
+= {result: 'nonreport'}
+| {result: 'ok'; description: string; url: string; jobID: string}
+| {result: Exclude<TestRequestResult, 'nonreport' | 'duplicate' | 'ok'>; description: string; url: string};
+// Orders a test or retest as a transaction: validates the target is not already queued,
+// claimed, or (for a new-page order) reported, then enqueues a job directly into
+// db/jobs/queue, bypassing the pending-approval inbox (testRequests.json) that
+// processTestRequest writes to. This is the auto-approval GitHub issue #111 asks for: a
+// lightweight gate (the same claimed/queued dedup check processTestRequest already
+// performs, plus a cap on the queue itself) substitutes for a maintainer's manual
+// review. Runs under testRequestsLock, the same lock processTestRequest uses, so an
+// orderJob call and a processTestRequest call can never race to enqueue duplicate jobs
+// for the same page. The caller's stated reason is recorded on the job (sources.reason),
+// which survives into the eventual report exactly as sources.worker already does: no
+// approval rule consults it yet, but accumulating real callers' stated reasons is
+// intended to inform the design of more sophisticated, reason-aware approval rules in a
+// later iteration.
+export const orderJob = (
+  target: TestRequestTarget, reason: string
+): Promise<OrderJobResult> => testRequestsLock(async (): Promise<OrderJobResult> => {
+  let description: string;
+  let url: string;
+  // Whether the cited report (for a retest order) has been superseded by a later one.
+  let superseded = false;
+  // If the target identifies a report to retest:
+  if ('timeStamp' in target) {
+    const {timeStamp, jobID} = target;
+    // Get the cited report.
+    const extract = await getReportExtract(timeStamp, jobID);
+    // If it does not exist:
+    if ('error' in extract) {
+      // Return this.
+      return {result: 'nonreport'};
+    }
+    ({description, url} = extract);
+    // Get whether it has been superseded by a later report.
+    const reportExtracts = await getReportExtracts();
+    superseded = reportExtracts.some(
+      ex => ex.timeStamp === timeStamp && ex.jobID === jobID && ex.superseded
+    );
+  }
+  // Otherwise, i.e. if the target is a page to test for the first time:
+  else {
+    ({description, url} = target);
+  }
+  try {
+    // Get any property the page shares with a claimed job.
+    const claimedJobProperty = await getApprovedJobProperty(description, url, 'claimed');
+    // Get any property the page shares with a queued job.
+    const queueJobProperty = await getApprovedJobProperty(description, url, 'queue');
+    // If the page shares a property with a claimed or queued job:
+    if (claimedJobProperty || queueJobProperty) {
+      // Return the property.
+      return {
+        result: (claimedJobProperty || queueJobProperty) as 'description' | 'url',
+        description,
+        url
+      };
+    }
+    // Otherwise, if the order is to retest a page that has been superseded:
+    if ('timeStamp' in target && superseded) {
+      // Return this.
+      return {result: 'superseded', description, url};
+    }
+    // Otherwise, if the order is to test a new page for which a report already exists:
+    if (!('timeStamp' in target)) {
+      const reportExtracts = await getReportExtracts();
+      if (reportExtracts.some(report => report.description === description && report.url === url)) {
+        // Return this.
+        return {result: 'reportExists', description, url};
+      }
+    }
+    // Otherwise, if the job queue is already full (a cap of 0 means no limit, so the
+    // queue is never full):
+    const queueMax = jobQueueMax();
+    const {queue: queuedJobNames} = await getJobNames();
+    if (queueMax > 0 && queuedJobNames.length >= queueMax) {
+      // Return this.
+      return {result: 'queueFull', description, url};
+    }
+    // The page is eligible, so build a job from the template.
+    const jobTemplateJSON = await fs.readFile(path.join(import.meta.dirname, 'job.json'), 'utf8');
+    const job = JSON.parse(jobTemplateJSON);
+    const nowStamp = getNowStamp();
+    const jobIDSuffix = getRandomString(3);
+    const jobName = `${nowStamp}-${jobIDSuffix}`;
+    job.id = jobName;
+    job.creationTimeStamp = nowStamp;
+    job.executionTimeStamp = nowStamp;
+    job.target.what = description;
+    job.target.url = url;
+    job.sources.reason = reason;
+    // Save the job in the queue.
+    await fs.writeFile(path.join(jobsPath(), 'queue', `${jobName}.json`), getJSON(job));
+    console.log(`Test ordered for ${description} as job ${jobName}`);
+    // Return success, with the job identifier so the caller can report it.
+    return {result: 'ok', description, url, jobID: jobName};
+    // If an error occurred:
+  } catch(error) {
+    // Throw it.
+    throw new Error('Failed to order test', {cause: error});
+  }
+});
+// Milliseconds between polls in awaitJob, and the maximum total milliseconds awaitJob
+// waits before giving up. Both are read at call time (not cached), via environment
+// variables, so tests can shrink them well below the real ~2-to-4-minute wait a
+// production caller experiences; AWAIT_JOB_TIMEOUT_MS deliberately exceeds the
+// documented "occasionally up to 4 minutes" a caller is told to expect, leaving margin
+// so a job that is genuinely still running is not mistaken for one that never will
+// finish.
+const awaitJobPollMs = () => getEnvMax('AWAIT_JOB_POLL_MS', 2000);
+const awaitJobTimeoutMs = () => getEnvMax('AWAIT_JOB_TIMEOUT_MS', 5 * 60 * 1000);
+// Result of awaitJob.
+export type AwaitJobResult = 'completed' | 'failed' | 'timedOut' | 'notFound';
+// Waits for a job ordered via orderJob (or, in principle, any job in db/jobs/queue or
+// db/jobs/claimed identified the same way) to leave the queue/claimed pipeline, by
+// polling for the outcome Kilotest already records for it: a completed report at
+// timeStamp-jobID.json (see index.ts's worker/report handler, which is the sole writer
+// of that file), or the job's own file having moved to db/jobs/failed (see
+// index.ts's processJobRequest and worker/report handler, which are the only
+// code that reclassifies a job as failed). Returns 'notFound' immediately, without
+// polling, if the identifier names neither a completed report nor a job anywhere in the
+// queue/claimed/failed pipeline, since there is then nothing to wait for. No progress
+// notifications are emitted during the wait; this is a pure bounded poll.
+export const awaitJob = async (timeStamp: string, jobID: string): Promise<AwaitJobResult> => {
+  const jobFileName = `${timeStamp}-${jobID}.json`;
+  const pollMs = awaitJobPollMs();
+  const timeoutMs = awaitJobTimeoutMs();
+  const deadline = Date.now() + timeoutMs;
+  // Returns the job's outcome if it is now determinable, or null if it is still pending.
+  const checkOutcome = async (): Promise<AwaitJobResult | null> => {
+    if (await getReportStats(timeStamp, jobID)) {
+      return 'completed';
+    }
+    const jobNames = await getJobNames();
+    if (jobNames.failed.includes(jobFileName)) {
+      return 'failed';
+    }
+    if (jobNames.queue.includes(jobFileName) || jobNames.claimed.includes(jobFileName)) {
+      return null;
+    }
+    // The identifier names neither a report nor a job anywhere in the pipeline.
+    return 'notFound';
+  };
+  // If the job is not yet determinable, poll until it is or the deadline passes.
+  let outcome = await checkOutcome();
+  while (outcome === null && Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+    outcome = await checkOutcome();
+  }
+  return outcome ?? 'timedOut';
+};
 
 // METRICS FUNCTIONS
 

package/web/listReports/index.html

@@ -18,7 +18,7 @@
         __requests__
       </ol>
       <p>__noRequests__</p>
-      <p>Should Kilotest <a href="requestTestForm.html">test a page</a> that is not listed below?</p>
+      <p>Should Kilotest <a href="requestNewTestForm.html">test a page</a> that is not listed below?</p>
       <h2>Queued for testing</h2>
       <ol>
         __queue__

package/web/listReports/listReports.test.ts

@@ -84,7 +84,7 @@ test('listReports includes the page URLs in the report details', async () => {
 test('listReports includes a link to request testing a new page', async () => {
   const result: any = await answer();
   const html = parse(result.answerPage);
-  const testLink = html.querySelector('a[href="requestTestForm.html"]');
+  const testLink = html.querySelector('a[href="requestNewTestForm.html"]');
   assert.ok(testLink);
 });
 

package/web/{requestTest → requestNewTest}/index.ts

@@ -34,13 +34,22 @@ export const answer = async (description: string, url: string, reason: string) =
     };
   }
   // Otherwise, if a report is available about a page with the same description and URL:
-  else if (result === 'retest') {
+  else if (result === 'reportExists') {
     // Report this.
     return {
       status: 'error',
       message: 'A report about the page is already available'
     }
   }
+  // Otherwise, if the queue of requests awaiting approval is full:
+  else if (result === 'queueFull') {
+    // Report this, with a fallback channel, since this request cannot be queued here.
+    return {
+      status: 'error',
+      message: 'Too many requests are awaiting approval right now. Please try again later, ' +
+        'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
+    }
+  }
   // Otherwise, i.e. if a request to test a page with the same description or URL is approved:
   else {
     // Report this.

package/web/{requestTest/requestTest.test.ts → requestNewTest/requestNewTest.test.ts}

@@ -1,6 +1,6 @@
 /*
-  requestTest.test.ts
-  Unit tests for web/requestTest/index.ts, covering the success path of answer.
+  requestNewTest.test.ts
+  Unit tests for web/requestNewTest/index.ts, covering the success path of answer.
 */
 
 // IMPORTS
@@ -128,3 +128,19 @@ test('answer returns an error when a report already exists for the page', {timeo
   assert.equal(result.status, 'error');
   assert.equal(result.message, 'A report about the page is already available');
 });
+
+test('answer returns an error with a fallback channel when the request queue is full', {timeout: 500}, async () => {
+  const {answer} = await import('./index.ts');
+  // Fill testRequests.json with 20 pending requests, all for one URL, to reach the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Because filler'
+  }));
+  await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
+  const result: any = await answer(
+    'One Too Many Page', 'https://example.com/one-too-many', 'Because accessibility'
+  );
+  assert.equal(result.status, 'error');
+  assert.ok(result.message.startsWith('Too many requests are awaiting approval right now.'));
+  assert.ok(result.message.includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(result.message.includes('info@kilotest.com'));
+});

package/web/{requestTestForm → requestNewTestForm}/index.html

@@ -14,7 +14,7 @@
     <main>
       <h1><a href="/">Kilotest</a>: Test request</h1>
       <p>You may request that a web page be tested by submitting the following form. All answers are required.</p>
-      <form action="/requestTest.html" method="post">
+      <form action="/requestNewTest.html" method="post">
         <p><label>
           Propose a name for the page.<br>
           <input size="50" maxlength="70" name="description" required>

package/web/{requestTestForm/requestTestForm.test.ts → requestNewTestForm/requestNewTestForm.test.ts}

@@ -1,6 +1,6 @@
 /*
-  requestTestForm.test.ts
-  Unit tests for web/requestTestForm/index.ts.
+  requestNewTestForm.test.ts
+  Unit tests for web/requestNewTestForm/index.ts.
 */
 
 // IMPORTS
@@ -12,7 +12,7 @@ import {answer} from './index.ts';
 
 // TESTS
 
-test('requestTestForm returns an ok status with valid HTML', async () => {
+test('requestNewTestForm returns an ok status with valid HTML', async () => {
   const result = await answer();
   assert.equal(result.status, 'ok');
   assert.ok(result.answerPage);
@@ -20,16 +20,16 @@ test('requestTestForm returns an ok status with valid HTML', async () => {
   assert.equal(html.querySelector('title')?.text, 'Test request | Kilotest');
 });
 
-test('requestTestForm includes a form that posts to /requestTest.html', async () => {
+test('requestNewTestForm includes a form that posts to /requestNewTest.html', async () => {
   const result = await answer();
   const html = parse(result.answerPage);
   const form = html.querySelector('form');
   assert.ok(form);
-  assert.equal(form.getAttribute('action'), '/requestTest.html');
+  assert.equal(form.getAttribute('action'), '/requestNewTest.html');
   assert.equal(form.getAttribute('method'), 'post');
 });
 
-test('requestTestForm includes required inputs for description, url, and why', async () => {
+test('requestNewTestForm includes required inputs for description, url, and why', async () => {
   const result = await answer();
   const html = parse(result.answerPage);
   const inputs = html.querySelectorAll('input');

package/web/requestRetest/index.ts

@@ -51,6 +51,15 @@ export const answer = async (pageArgs: string, reason: string) => {
       message: 'A later report about the page is already available'
     }
   }
+  // Otherwise, if the queue of requests awaiting approval is full:
+  else if (result === 'queueFull') {
+    // Report this, with a fallback channel, since this request cannot be queued here.
+    return {
+      status: 'error',
+      message: 'Too many requests are awaiting approval right now. Please try again later, ' +
+        'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
+    }
+  }
   // Otherwise, i.e. if a request to test a page with the same description or URL is approved:
   else {
     // Report this.

package/web/requestRetest/requestRetest.test.ts

@@ -128,3 +128,17 @@ test('answer returns an error when a matching job is already claimed or queued',
   }
 });
 
+test('answer returns an error with a fallback channel when the request queue is full', async () => {
+  const {answer} = await import('./index.ts');
+  // Fill testRequests.json with 20 pending requests, all for one URL, to reach the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Because filler'
+  }));
+  await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
+  const result: any = await answer('260101T0001/ct', 'Because changes were made');
+  assert.equal(result.status, 'error');
+  assert.ok(result.message.startsWith('Too many requests are awaiting approval right now.'));
+  assert.ok(result.message.includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(result.message.includes('info@kilotest.com'));
+});
+

package/web/tutorialAI/index.ts

@@ -6,13 +6,20 @@
 // IMPORTS
 
 import {sendAlert} from '../../alerts.ts';
-import {checkCommentDuplicate, checkCommentLength, getJSON, getNowStamp} from '../../util.ts';
+import {checkCommentDuplicate, checkCommentLength, describeMax, getEnvMax, getJSON, getNowStamp} from '../../util.ts';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
 // FUNCTIONS (helpers)
 
 const getCommentsPath = () => process.env.TUTORIAL_AI_COMMENTS_PATH || path.join(import.meta.dirname, '../../db/comments/tutorialAI.json');
+// Maximum number of comments held at once. Once reached, a new, distinct comment is
+// rejected rather than stored, so the comments file and the manager alert emails it
+// generates cannot grow without bound (modeled on a full mailbox rejecting new mail; see
+// GitHub issue #3, abuse type 3). Configurable via TUTORIAL_AI_COMMENTS_MAX, since
+// different Kilotest deployments' maintainers may want a different size; a value of 0
+// means no limit.
+const getCommentsMax = () => getEnvMax('TUTORIAL_AI_COMMENTS_MAX', 20);
 
 // FUNCTIONS
 
@@ -60,6 +67,17 @@ export const handleComment = async (content: unknown) => {
   if (duplicateCheck.status === 'error') {
     return duplicateCheck;
   }
+  // If the comments already on file have reached the cap (a cap of 0 means no limit, so
+  // the comments are never full):
+  const commentsMax = getCommentsMax();
+  if (commentsMax > 0 && comments.length >= commentsMax) {
+    // Report this, with a fallback channel, since this comment cannot be stored here.
+    return {
+      status: 'error',
+      message: 'Too many comments are awaiting review right now. Please try again later, ' +
+        'or post your comment at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
+    };
+  }
   // Add the comment to the existing ones.
   comments.push({
     timeStamp: getNowStamp(),
@@ -69,7 +87,11 @@ export const handleComment = async (content: unknown) => {
   await fs.mkdir(path.dirname(commentsPath), {recursive: true});
   // Save the revised comments.
   await fs.writeFile(commentsPath, getJSON(comments));
-  // Send an alert to the manager.
-  await sendAlert('Kilotest: New AI tutorial comment received', 'A new AI tutorial comment has been received.');
+  // Send an alert to the manager, including the resulting count, so a maintainer who has
+  // been away sees at a glance how urgently the comments need review.
+  await sendAlert(
+    'Kilotest: New AI tutorial comment received',
+    `A new AI tutorial comment has been received.\nComments now awaiting review: ${comments.length} of ${describeMax(commentsMax)}`
+  );
   return {status: 'ok'};
 };