review port documentation (#1363)

* review port documentation; add EACCES as an acceptable error to continue port hopping; avoid out of memory error if no registered port is reachable

* Update src/preview.ts

* MAX_PORT

* Update src/preview.ts

Co-authored-by: Mike Bostock <[email protected]>

* Update docs/getting-started.md

Co-authored-by: Mike Bostock <[email protected]>

* Update docs/getting-started.md

Co-authored-by: Mike Bostock <[email protected]>

* Update docs/getting-started.md

Co-authored-by: Mike Bostock <[email protected]>

* more sh

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

docs/getting-started.md

@@ -164,8 +164,21 @@ You should see something like this:
 ↳ <u><a href="http://127.0.0.1:3000/" style="color: inherit;">http://127.0.0.1:3000/</a></u></pre>
 
 <div class="note">
-  <p>If port 3000 is in use, the preview server will choose the next available port, so your actual port may vary. To specify port 4321 (and similarly for any other port), use <nobr><code>--port 4321</code></nobr>.</p>
-  <p>For security, the preview server is by default only accessible on your local machine using the <a href="https://en.wikipedia.org/wiki/Localhost">loopback address</a> 127.0.0.1. To allow remote connections, use <nobr><code>--host 0.0.0.0</code></nobr>.</p>
+
+If port 3000 is in use, the preview server will choose the next available port, so your actual port may vary. To specify a different port, use <nobr>`--port`</nobr>. For example, to run the preview server with npm on port 4321:
+
+```sh
+npm run dev -- --port 4321
+```
+
+For security, the preview server is by default only accessible on your local machine using the [loopback address](https://en.wikipedia.org/wiki/Localhost) 127.0.0.1. To allow remote connections, use <nobr>`--host 0.0.0.0`</nobr>.
+
+Port numbers below 1024 may need admin privileges. For example, to share your preview server on the default HTTP port 80:
+
+```sh
+sudo npm run dev -- --host 0.0.0.0 --port 80
+```
+
 </div>
 
 Now visit <http://127.0.0.1:3000> in your browser, which should look like:

src/preview.ts

@@ -77,7 +77,8 @@ export class PreviewServer {
     Telemetry.record({event: "preview", step: "start"});
     const server = createServer();
     if (port === undefined) {
-      for (port = 3000; true; ++port) {
+      const MAX_PORT = 49152; // https://en.wikipedia.org/wiki/Registered_port
+      for (port = 3000; port < MAX_PORT; ++port) {
         try {
           await new Promise<void>((resolve, reject) => {
             server.once("error", reject);
@@ -88,6 +89,7 @@ export class PreviewServer {
           if (!isSystemError(error) || error.code !== "EADDRINUSE") throw error;
         }
       }
+      if (port === MAX_PORT) throw new Error(`Couldn’t connect to any port on ${hostname}`);
     } else {
       await new Promise<void>((resolve) => server.listen(port, hostname, resolve));
     }