src, tests, docs: update and add missing docs

docs/deploy.md

@@ -4,7 +4,7 @@ This worker is auto-deployed by Github Actions. The workflow is defined [here](.
 
 ## Staging
 
-This worker is deployed to staging every time a pr is merged into the main branch.
+This worker is deployed to staging every time a pull request is merged into the main branch.
 
 ## Prod
 

docs/dev-setup.md

@@ -24,11 +24,9 @@ Spin up a Workerd instance on your machine that serves this worker
 
 Run `wrangler login`
 
-### R2 Buckets
+### R2 Bucket
 
-Depending on the environment you're running in, you will need a different R2 bucket on your account.
-For dev (the default), it's `dist-dev`. For staging, `dist-staging`. For prod, `dist-prod`.
-These buckets will either need to have a copy of Node's dist folder in them or something mimicing the folder there.
+Create a R2 bucket named `dist-prod`. This is the bucket that the worker read from. It will either need to have a copy of Node's dist folder in it or something mimicing the folder there.
 
 ### Starting the Local Server
 

scripts/update-redirect-links.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';
 import { Linker } from 'nodejs-latest-linker/common.js';
 import { writeFile } from 'node:fs/promises';

src/handlers/get.ts

@@ -59,6 +59,8 @@ const getHandler: Handler = async (request, env, ctx, cache) => {
 
   let response: Response;
   if (bucketPath in VIRTUAL_DIRS) {
+    // Path requested is to be treated as a symlink to a directory,
+    //  list the directory it points to
     response = renderDirectoryListing(
       requestUrl,
       request,
@@ -67,8 +69,10 @@ const getHandler: Handler = async (request, env, ctx, cache) => {
       env
     );
   } else if (isPathADirectory) {
+    // List the directory
     response = await listDirectory(requestUrl, request, bucketPath, env);
   } else {
+    // Fetch the file
     response = await getFile(requestUrl, request, bucketPath, env);
   }
 

src/handlers/strategies/directoryListing.ts

@@ -34,10 +34,12 @@ export function renderDirectoryListing(
   objects: _Object[],
   env: Env
 ): Response {
-  // Holds all the html for each directory and file we're listing
+  // Holds the contents of the listing (directories and files)
   const tableElements = [];
 
-  // Add the default parent directory listing
+  // There shouldn't really be a case where we're listing the root
+  //  directory (/) when this is deployed, so always add the option
+  //  to go up a directory
   tableElements.push({
     href: '../',
     name: '../',

src/handlers/strategies/serveFile.ts

@@ -93,7 +93,7 @@ export async function getFile(
       headers: {
         etag: file.httpEtag,
         'accept-range': 'bytes',
-        // @TODO: Explain why JSON files can be accessed anywhere
+        // https://github.com/nodejs/build/blob/e3df25d6a23f033db317a53ab1e904c953ba1f00/ansible/www-standalone/resources/config/nodejs.org?plain=1#L194-L196
         'access-control-allow-origin': url.pathname.endsWith('.json')
           ? '*'
           : '',

tests/e2e/directory.test.ts

@@ -5,6 +5,12 @@ import { readFile } from 'node:fs/promises';
 import http from 'http';
 import { Miniflare } from 'miniflare';
 
+/**
+ * We make use of the S3 api for directory listing due to
+ *  a size limit in the responses that bindings can return.
+ *  So, we need to mock the ListObjectsV2 call that we send
+ *  to the S3 api.
+ */
 async function startS3Mock(): Promise<http.Server> {
   const server = http.createServer((req, res) => {
     const url = new URL(req.url!, `http://${req.headers.host}`);