WIP configurable ArNS 404 page support

Author: djwhitt

src/config.ts

@@ -515,6 +515,20 @@ if (APEX_ARNS_NAME !== undefined && ARNS_ROOT_HOST === undefined) {
   throw new Error('ARNS_ROOT_HOST must be defined when APEX_ARNS_NAME is used');
 }
 
+export const ARNS_NOT_FOUND_TX_ID = env.varOrUndefined('ARNS_NOT_FOUND_TX_ID');
+
+export const ARNS_NOT_FOUND_ARNS_NAME = env.varOrUndefined(
+  'ARNS_NOT_FOUND_ARNS_NAME',
+);
+if (
+  ARNS_NOT_FOUND_TX_ID !== undefined &&
+  ARNS_NOT_FOUND_ARNS_NAME !== undefined
+) {
+  throw new Error(
+    'ARNS_NOT_FOUND_TX_ID and ARNS_NOT_FOUND_ARNS_NAME are mutually exclusive but both are set.',
+  );
+}
+
 //
 // Header caching
 //

src/middleware/arns.ts

@@ -37,11 +37,34 @@ export const createArnsMiddleware = ({
   nameResolver: NameResolver;
 }): Handler =>
   asyncMiddleware(async (req, res, next) => {
+    // Skip all ArNS processing if the root ArNS host is not set.
+    if (config.ARNS_ROOT_HOST !== undefined && config.ARNS_ROOT_HOST !== '') {
+      next();
+      return;
+    }
+
+    const hostNameIsArNSRoot = req.hostname === config.ARNS_ROOT_HOST;
+
+    if (
+      // Use apex ID as ArNS root data if it's set.
+      config.APEX_TX_ID !== undefined &&
+      hostNameIsArNSRoot
+    ) {
+      res.header(headerNames.arnsResolvedId, config.APEX_TX_ID);
+      dataHandler(req, res, next);
+    }
+
+    let arnsSubdomain: string | undefined;
     if (
-      // Ignore requests that do end with the ArNS root hostname.
-      (config.ARNS_ROOT_HOST !== undefined &&
-        config.ARNS_ROOT_HOST !== '' &&
-        !req.hostname.endsWith('.' + config.ARNS_ROOT_HOST)) ||
+      // If apex ArNS name is set and hostname matches root use the apex ArNS
+      // name as the ArNS subdomain.
+      config.APEX_ARNS_NAME !== undefined &&
+      hostNameIsArNSRoot
+    ) {
+      arnsSubdomain = config.APEX_ARNS_NAME;
+    } else if (
+      // Ignore requests that do not end with the ArNS root hostname.
+      !req.hostname.endsWith('.' + config.ARNS_ROOT_HOST) ||
       // Ignore requests that do not include subdomains since ArNS always
       // requires a subdomain.
       !Array.isArray(req.subdomains) ||
@@ -51,22 +74,22 @@ export const createArnsMiddleware = ({
     ) {
       next();
       return;
+    } else {
+      arnsSubdomain = req.subdomains[req.subdomains.length - 1];
     }
 
-    const arnsSubdomain = req.subdomains[req.subdomains.length - 1];
-
     if (
       EXCLUDED_SUBDOMAINS.has(arnsSubdomain) ||
-      // Avoid collisions with sandbox URLs by ensuring the subdomain length
-      // is below the minimum length of a sandbox subdomain. Undernames are
-      // are an exception because they can be longer and '_' cannot appear in
-      // base32.
+      // Avoid collisions with sandbox URLs by ensuring the subdomain length is
+      // below the minimum length of a sandbox subdomain. Undernames are are an
+      // exception because they can be longer and '_' cannot appear in base32.
       (arnsSubdomain.length > MAX_ARNS_NAME_LENGTH && !arnsSubdomain.match(/_/))
     ) {
       next();
       return;
     }
 
+    // TODO: add comment explaining this behavior
     if (DATA_PATH_REGEX.test(req.path)) {
       next();
       return;
@@ -77,34 +100,55 @@ export const createArnsMiddleware = ({
       return;
     }
 
-    // NOTE: Errors and request deduplication are expected to be handled by the
-    // resolver
+    // NOTE: Errors and in-flight resolution deduplication are expected to be
+    // handled by the resolver.
     const end = metrics.arnsResolutionTime.startTimer();
-    const { resolvedId, ttl, processId, resolvedAt, limit, index } =
+    let { resolvedId, ttl, processId, resolvedAt, limit, index } =
       await nameResolver.resolve({
         name: arnsSubdomain,
       });
     end();
     if (resolvedId === undefined) {
-      sendNotFound(res);
-      return;
+      res.status(404);
+      if (
+        // ArNS undername should not use custom 404 pages.
+        // TODO: expand this explanation
+        arnsSubdomain.match(/_/) ||
+        // Custom 404s should not be used for Apex ArNS.
+        hostNameIsArNSRoot
+      ) {
+        sendNotFound(res);
+      } else if (config.ARNS_NOT_FOUND_TX_ID !== undefined) {
+        resolvedId = config.ARNS_NOT_FOUND_TX_ID;
+      } else if (config.ARNS_NOT_FOUND_ARNS_NAME !== undefined) {
+        ({ resolvedId, ttl, processId, resolvedAt, limit, index } =
+          await nameResolver.resolve({
+            name: arnsSubdomain,
+          }));
+      } else {
+        sendNotFound(res);
+        return;
+      }
     }
 
     res.header(headerNames.arnsResolvedId, resolvedId);
-    res.header(headerNames.arnsTtlSeconds, ttl.toString());
+    res.header(headerNames.arnsTtlSeconds, ttl?.toString());
     res.header(headerNames.arnsProcessId, processId);
-    res.header(headerNames.arnsResolvedAt, resolvedAt.toString());
-    // limit and index can be undefined if they come from the cache
-    res.header(headerNames.arnsLimit, limit?.toString());
-    res.header(headerNames.arnsIndex, index?.toString());
+    res.header(headerNames.arnsResolvedAt, resolvedAt?.toString());
+    // Limit and index can be undefined if they come from a cache that existed
+    // before they were added.
+    if (limit !== undefined && index !== undefined) {
+      res.header(headerNames.arnsLimit, limit.toString());
+      res.header(headerNames.arnsIndex, index.toString());
 
-    // handle undername limit exceeded
-    if (config.ARNS_RESOLVER_ENFORCE_UNDERNAME_LIMIT && index > limit) {
-      sendPaymentRequired(
-        res,
-        'ArNS undername limit exceeded. Purchase additional undernames to continue.',
-      );
-      return;
+      // handle undername limit exceeded
+      if (config.ARNS_RESOLVER_ENFORCE_UNDERNAME_LIMIT && index > limit) {
+        sendPaymentRequired(
+          res,
+          'ArNS undername limit exceeded. Purchase additional undernames to continue.',
+        );
+        return;
+      }
     }
 
     // TODO: add a header for arns cache status

src/routes/arns.ts

@@ -43,6 +43,7 @@ if (config.ARNS_ROOT_HOST !== undefined) {
   );
 }
 
+// TODO: consider moving this into ar-io router
 arnsRouter.get('/ar-io/resolver/:name', async (req, res) => {
   const { name } = req.params;
   // NOTE: Errors and request deduplication are expected to be handled by the

src/routes/default.ts

@@ -52,6 +52,7 @@ defaultRouter.get('*', async (req, res, next) => {
     return dataHandler(modifiedReq, res, next);
   }
 
+  // TODO: APEX_ARNS_NAME handling into arnsMiddleware
   if (APEX_ARNS_NAME !== undefined) {
     // Modify the request to add APEX_ARNS_NAME as a subdomain
     const modifiedReq = new Proxy(req, {