fix(dev): take the next registered port when 3000 is busy (#159)

* fix(dev): take the next registered port when 3000 is busy

`npm run dev` refused to start when port 3000 was in use, telling the
user to free it or re-provision against another port. Provisioning
already registers an OAuth callback for every port from 3000 to 3009,
precisely so a forwarded dev server can land anywhere in that range and
still log in, so refusing was throwing away a fallback the backend was
built to support.

The dev server now takes the first free port in the range and prints
where it landed. A PORT named in the environment is left alone: that one
is a decision, so a busy one is still an error.

Two guards get more accurate as a result:

- The callback check no longer fails when OAUTH_CALLBACK names 3000 and
  the server runs on 3005. Both are registered, so login works.
- Running out of ports is now its own message, rather than being
  reported as "port 3000 is in use".

The port list lives in scripts/lib.mjs and is asserted against the
`range()` call in drupal/.devtools/provision, so widening it on one side
fails the tests rather than breaking login on the other.

* fix(dev): refuse a frontend port with no registered OAuth callback

`PORT=4000 npm run dev` started fine and then failed only at login. The
browser builds its callback from the port it is on, and Drupal registers
3000-3009 plus whatever OAUTH_CALLBACK names, so 4000 was rejected as
invalid_client with the rest of the site working - the exact failure
mode the other guards in this script exist to prevent.

The guard now asks whether anything registers the port, rather than
whether OAUTH_CALLBACK happens to name it. A backend this repo did not
provision is left alone: its consumer was registered somewhere this
checkout cannot see, so `backendIsProvisionedHere` gates the check.

Port selection also moves to the last step before Nuxt starts. Nuxt 2
answers a bind failure with a random port, so nothing can fully close
the gap between finding a port free and Nuxt taking it, but none of the
configuration checks need the port, and running them first makes the gap
as small as this script can make it.

The test backend now answers the OAuth check the way a provisioned
Drupal does, so the port cases run through the whole script instead of
stopping at the consumer check.

Author: Decipher

CHANGELOG.md

@@ -90,8 +90,17 @@ minor is for.
   that terminal corrupted `vendor/` and `node_modules/`.
 - `composer install` retries: a transient registry error no longer ends
   a first run.
-- The dev server refuses to start on a taken port. Nuxt falls back to a
-  random one, which silently breaks the OAuth callback.
+- The dev server moves to the next free port between 3000 and 3009 when
+  3000 is taken, and prints which one it took. Nuxt's own fallback picks a
+  random port, which silently breaks the OAuth callback; every port in
+  that range has a callback registered, so any of them is safe. A `PORT`
+  you name is still yours - a busy one fails, rather than moving
+  somewhere you did not ask for.
+- The dev server refuses a port with no registered OAuth callback. A
+  `PORT` outside 3000-3009 that `OAUTH_CALLBACK` does not name started
+  fine and then failed only at login, since the browser builds its
+  callback from the port it is on. Backends this repo did not provision
+  are left alone: their consumers were registered out of sight.
 - The dev container no longer leaves Xdebug active, which made every
   `php` and `composer` call wait for a debugger.
 - The druxt patch is described without a link to a private merge

README.md

@@ -81,7 +81,8 @@ WSL2, or a container backend - see [Windows](#windows).
    ```
 
    - Drupal backend: http://127.0.0.1:8888
-   - Nuxt frontend: http://localhost:3000
+   - Nuxt frontend: http://localhost:3000 (or the next free port up to
+     3009, which it prints)
    - One-time Drupal login: `npm run login`
 
 `npm run dev` and `npm run start` automatically start the local backend
@@ -150,6 +151,23 @@ Then:
 3. `npm run dev` as above. `npm run drush -- <command>` is proxied
    through `lando drush`.
 
+### Troubleshooting
+
+#### Port 3000 is already in use
+
+`npm run dev` takes the next free port between 3000 and 3009 and says
+which one it picked. Provisioning registers an OAuth callback for every
+port in that range, so login keeps working on whichever one it uses.
+
+Naming a port yourself turns that off: `PORT=3005 npm run dev` uses
+3005 or fails, because a port you asked for is a decision rather than a
+default. If the whole range is busy, `npm run dev` says so instead of
+letting Nuxt fall back to a random port and break login.
+
+A port outside 3000-3009 has no registered callback, so `npm run dev`
+refuses that too. To use one, set `OAUTH_CALLBACK` in `.env` to
+`http://localhost:<port>/callback` and re-run `npm run provision`.
+
 #### Login fails with invalid_client in a dev container
 
 The browser builds the OAuth callback from its own address. An IDE
@@ -198,7 +216,7 @@ npm run dev
 ```
 
 - Drupal backend: http://127.0.0.1:8888
-- Nuxt frontend: http://localhost:3000
+- Nuxt frontend: http://localhost:3000 (or the next free port up to 3009)
 
 ## How to use it
 
@@ -210,7 +228,7 @@ In a Development Container (VS Code, Codespaces, DevPod), forwarded ports are ac
 
 | Port   | Service                                                                               |
 | ------ | ------------------------------------------------------------------------------------- |
-| `3000` | Nuxt.js                                                                               |
+| `3000` | Nuxt.js (3000-3009: `npm run dev` takes the first free one)                           |
 | `3003` | Storybook                                                                             |
 | `8888` | Drupal (local `.devtools` backend - DDEV serves at its own `*.ddev.site` URL instead) |
 

scripts/dev.mjs

@@ -7,89 +7,164 @@
 
 import { checkOauth } from './check-oauth.mjs'
 import {
+  FRONTEND_PORTS,
   NUXT_DIR,
+  backendIsProvisionedHere,
   ensureBackend,
   ensureOauthClientId,
   exitWithError,
+  firstFreePort,
   foregroundNpm,
   isPortOpen,
+  portIsRegistered,
   readEnv,
 } from './lib.mjs'
 
-const PORT = Number(process.env.PORT) || 3000
+// Nuxt binds 0.0.0.0 (see nuxt.config.js), which answers on loopback
+// too, so this is the probe for "is that port taken".
+const HOST = '127.0.0.1'
+const PORT_RANGE = `${FRONTEND_PORTS[0]}-${FRONTEND_PORTS[FRONTEND_PORTS.length - 1]}`
+const ENV_PORT = Number(process.env.PORT)
+// A usable PORT in the environment is a decision; the default is only a
+// starting point. An empty or unparsable one is neither.
+const PORT_IS_EXPLICIT = Number.isInteger(ENV_PORT) && ENV_PORT > 0
+const REQUESTED_PORT = PORT_IS_EXPLICIT ? ENV_PORT : FRONTEND_PORTS[0]
 
 /**
- * Refuse to start when the frontend port is taken.
+ * Pick the port to serve the frontend on.
  *
  * Nuxt's dev server does not fail on a busy port - it falls back to a
  * random one. The OAuth consumer in Drupal is registered against a fixed
- * callback URL, so the login round trip then fails with a bare
+ * set of callback URLs, so the login round trip then fails with a bare
  * `invalid_client` from Drupal, pointing nowhere near the real cause.
+ *
+ * Provisioning registers all of FRONTEND_PORTS for exactly that reason,
+ * which makes a busy default a choice rather than a failure: take the
+ * next registered port and say so. A port the user named is theirs.
+ *
+ * Something else can still take the port between this check and Nuxt
+ * binding it, which lands back on Nuxt's own random fallback - the same
+ * place an unguarded start would have been anyway.
  */
-async function ensureFrontendPortFree() {
-  if (!(await isPortOpen('127.0.0.1', PORT))) {
-    return
+async function resolveFrontendPort() {
+  if (!(await isPortOpen(HOST, REQUESTED_PORT))) {
+    return REQUESTED_PORT
   }
 
-  const callback = readEnv().OAUTH_CALLBACK || `http://localhost:${PORT}/callback`
-  exitWithError(
-    `Port ${PORT} is already in use.\n\n` +
-      `  Nuxt would fall back to a random port, and login would then fail with\n` +
-      `  {"error":"invalid_client"} - Drupal has the consumer registered for\n` +
-      `  ${callback}, which would no longer match.\n\n` +
-      `  Free the port (another dev server, or another copy of this project),\n` +
-      `  or commit to a different one: set OAUTH_CALLBACK in .env to the port\n` +
-      `  you want, re-run \`npm run provision\` to re-register the consumer,\n` +
-      `  then start with \`PORT=<port> npm run dev\`.`
-  )
+  if (PORT_IS_EXPLICIT) {
+    exitWithError(
+      `Port ${REQUESTED_PORT} is already in use, and PORT asks for it by name.\n\n` +
+        `  Nuxt would fall back to a random port, and login would then fail with\n` +
+        `  {"error":"invalid_client"} - Drupal only accepts a callback it has\n` +
+        `  registered.\n\n` +
+        `  Free the port (another dev server, or another copy of this project),\n` +
+        `  or drop PORT and let \`npm run dev\` take the first free one of\n` +
+        `  ${PORT_RANGE}.`
+    )
+  }
+
+  const port = await firstFreePort(HOST)
+  if (port === null) {
+    exitWithError(
+      `Ports ${PORT_RANGE} are all in use.\n\n` +
+        `  Nuxt would fall back to a random port, and login would then fail with\n` +
+        `  {"error":"invalid_client"} - those are the only callbacks Drupal has\n` +
+        `  registered.\n\n` +
+        `  Free one of them, or commit to a port outside the range: set\n` +
+        `  OAUTH_CALLBACK in .env to that port, re-run \`npm run provision\` to\n` +
+        `  re-register the consumer, then start with \`PORT=<port> npm run dev\`.`
+    )
+  }
+
+  console.log(`Port ${REQUESTED_PORT} is in use - starting on ${port} instead.`)
+  console.log(`Login still works: Drupal accepts the callback on any of ${PORT_RANGE}.`)
+  console.log('')
+  return port
+}
+
+/** The port OAUTH_CALLBACK names, or null when it names nothing usable. */
+function callbackPort(callback) {
+  if (!callback) {
+    return null
+  }
+  try {
+    const parsed = new URL(callback)
+    return Number(parsed.port) || (parsed.protocol === 'https:' ? 443 : 80)
+  } catch {
+    return null
+  }
 }
 
 /**
- * The consumer is registered for one callback URL. Serving the frontend
- * on a different port than that URL names fails the same way a busy
- * port does, just without anything else looking wrong.
+ * Refuse a frontend port Drupal has no callback registered for.
+ *
+ * The browser builds redirect_uri from its own origin, so serving on an
+ * unregistered port fails login with `invalid_client` while the rest of
+ * the site works. Provisioning registers FRONTEND_PORTS plus whatever
+ * OAUTH_CALLBACK names, and those are the only safe ports.
+ *
+ * Checking REQUESTED_PORT covers the port actually served: resolution
+ * either keeps that port or moves inside FRONTEND_PORTS, which is
+ * registered either way.
  */
-function ensureCallbackMatchesPort() {
-  const callback = readEnv().OAUTH_CALLBACK
-  if (!callback) {
+function ensurePortHasCallback(backend) {
+  if (portIsRegistered(REQUESTED_PORT)) {
     return
   }
 
-  let parsed
-  try {
-    parsed = new URL(callback)
-  } catch {
+  const callback = readEnv().OAUTH_CALLBACK
+  const port = callbackPort(callback)
+  if (port === REQUESTED_PORT) {
     return
   }
 
-  const callbackPort = Number(parsed.port) || (parsed.protocol === 'https:' ? 443 : 80)
-  if (callbackPort === PORT) {
+  if (port !== null) {
+    exitWithError(
+      `OAUTH_CALLBACK names port ${port}, but the dev server would run on ${REQUESTED_PORT}.\n\n` +
+        `  Login would fail with {"error":"invalid_client"} - Drupal only accepts the\n` +
+        `  callback it has registered (${callback}).\n\n` +
+        `  Either start on that port with \`PORT=${port} npm run dev\`, or set\n` +
+        `  OAUTH_CALLBACK to port ${REQUESTED_PORT} and re-run \`npm run provision\` to\n` +
+        `  re-register the consumer.`
+    )
+  }
+
+  // Nothing registers this port. Only say so for a backend this repo
+  // provisioned - a remote one registered its consumer out of sight.
+  if (!backendIsProvisionedHere(backend)) {
     return
   }
 
   exitWithError(
-    `OAUTH_CALLBACK names port ${callbackPort}, but the dev server would run on ${PORT}.\n\n` +
-      `  Login would fail with {"error":"invalid_client"} - Drupal only accepts the\n` +
-      `  callback it has registered (${callback}).\n\n` +
-      `  Either start on that port with \`PORT=${callbackPort} npm run dev\`, or set\n` +
-      `  OAUTH_CALLBACK to port ${PORT} and re-run \`npm run provision\` to\n` +
-      `  re-register the consumer.`
+    `PORT is ${REQUESTED_PORT}, which has no OAuth callback registered.\n\n` +
+      `  Login would fail with {"error":"invalid_client"} while the rest of the\n` +
+      `  site works - the browser builds its callback from the port it is on,\n` +
+      `  and Drupal registers ${PORT_RANGE} plus whatever OAUTH_CALLBACK names.\n\n` +
+      `  Use a port from ${PORT_RANGE}, or set OAUTH_CALLBACK in .env to\n` +
+      `  http://localhost:${REQUESTED_PORT}/callback and re-run \`npm run provision\`\n` +
+      `  to register it.`
   )
 }
 
 async function main() {
-  await ensureBackend()
+  const backend = await ensureBackend()
   ensureOauthClientId()
-  ensureCallbackMatchesPort()
-  await ensureFrontendPortFree()
+  ensurePortHasCallback(backend)
   // Confirm the backend will actually accept this consumer. Nuxt reads
   // OAUTH_CLIENT_ID once at startup, so a stale value - or a consumer
   // left over from an older provision - shows up only as a failed login
   // in the browser, with nothing in the terminal to explain it.
   await checkOauth()
-  console.log(`Starting the Nuxt dev server -> http://localhost:${PORT}`)
+  // Last thing before the spawn. Everything above is config, and none of
+  // it needs the port, so choosing one here leaves the smallest window
+  // for another process to take it in the meantime.
+  const port = await resolveFrontendPort()
+  console.log(`Starting the Nuxt dev server -> http://localhost:${port}`)
   console.log('')
-  process.exitCode = await foregroundNpm(['run', 'dev'], { cwd: NUXT_DIR })
+  process.exitCode = await foregroundNpm(['run', 'dev'], {
+    cwd: NUXT_DIR,
+    env: { PORT: String(port) },
+  })
 }
 
 main().catch((error) => exitWithError(error.message))

scripts/lib.mjs

@@ -225,6 +225,42 @@ export async function waitForPort(host, port, timeoutSeconds = 30) {
   return false
 }
 
+/**
+ * The ports the frontend may serve on. Provisioning registers an OAuth
+ * callback for every one of them (drupal/.devtools/provision and
+ * .ddev/commands/web/druxt-add-consumer), so moving between them never
+ * breaks login. Anything outside the list does, because the browser
+ * builds redirect_uri from its own origin and Drupal rejects an
+ * unregistered one as, confusingly, invalid_client.
+ */
+export const FRONTEND_PORTS = Array.from({ length: 10 }, (_, index) => 3000 + index)
+
+/**
+ * True when this repo's own tooling provisioned the backend, and so
+ * knows what its OAuth consumer has registered. A remote backend was
+ * set up somewhere this checkout cannot see, so its registrations are
+ * not this repo's to assert.
+ */
+export function backendIsProvisionedHere(backend) {
+  return Boolean(backend.managed || backend.ddev || backend.lando)
+}
+
+/** True when a port has an OAuth callback registered for it. */
+export function portIsRegistered(port) {
+  return FRONTEND_PORTS.includes(port)
+}
+
+/**
+ * The first of `ports` nothing is listening on, or null when they are
+ * all taken. Checked in order, so a free 3000 always wins.
+ */
+export async function firstFreePort(host, ports = FRONTEND_PORTS) {
+  for (const port of ports) {
+    if (!(await isPortOpen(host, port, 500))) return port
+  }
+  return null
+}
+
 /**
  * Run a command to completion, inheriting stdio. Throws on failure.
  */