feat: support cache mode with external links

Refactor the cache system to support external links and secure
cross-origin requests.

- Removed reliance on ROOT_LINK_OFFSET in cache functions.
- Implemented url_to_cache_path() to generate clean, unescaped cache
  paths with ".." path sanitization for both local and external links.
- Updated Cache_create, Cache_open, and Cache_delete to use the new
  url_to_cache_path helper for local filename mapping.
- Added is_same_origin helper in src/link.c to prevent credentials
  and sensitive custom headers from being sent to cross-origin links.
- Resolved clang-tidy repeated branch body warning in Cache_create
  by consolidating SONIC and SINGLE modes.
- Flattens external URL cache keys by replacing '/' and ':' with '_'
  to prevent invalid nested directory creation/failures under
  META_DIR and DATA_DIR.
- Adds defensive NULL check at the beginning of url_to_cache_path()
  before any string operations.
- Adds comprehensive unit tests covering NULL input, local path
  caching, and external URL path flattening/sanitization.
- Adds NULL guards for all url_to_cache_path() calls in cache.c.
- Fixes allocator mismatch for sonic.id in Cache_create() cleanup.
- Add check in Cache_delete for NULL link in NORMAL mode to return early
  instead of falling back to raw path.
- Enable external links cache mode integration tests.

Author: fangfufu

src/cache.c

@@ -832,11 +832,24 @@ static int Cache_exist(const char *fn)
 void Cache_delete(const char *fn)
 {
     Link *link = path_to_Link(fn);
+    char *cache_key = NULL;
     if (CONFIG.mode == SONIC) {
         if (!link) {
             return;
         }
         fn = link->sonic.id;
+    } else if (CONFIG.mode == NORMAL) {
+        if (!link) {
+            return;
+        }
+        cache_key = url_to_cache_path(link->f_url);
+        if (!cache_key) {
+            lprintf(error, "Failed to derive cache key from URL: %s\n",
+                    link->f_url);
+            LinkTable_unref(link->parent_table);
+            return;
+        }
+        fn = cache_key;
     }
 
     char *metafn = path_append(META_DIR, fn);
@@ -850,6 +863,9 @@ void Cache_delete(const char *fn)
     }
     FREE(metafn);
     FREE(datafn);
+    if (cache_key) {
+        FREE(cache_key);
+    }
     if (link) {
         LinkTable_unref(link->parent_table);
     }
@@ -933,18 +949,29 @@ int Cache_create(const char *path)
         return 1;
     }
 
-    char *fn;
+    char *fn = NULL;
+    char *fn_alloc = NULL;
 
     if (CONFIG.mode == NORMAL) {
-        fn = curl_easy_unescape(NULL, this_link->f_url + ROOT_LINK_OFFSET, 0,
-                                NULL);
+        fn_alloc = url_to_cache_path(this_link->f_url);
+        fn = fn_alloc;
     } else if (CONFIG.mode == SINGLE) {
         fn = curl_easy_unescape(NULL, this_link->linkname, 0, NULL);
     } else if (CONFIG.mode == SONIC) {
         fn = this_link->sonic.id;
     } else {
         lprintf(fatal, "Invalid CONFIG.mode\n");
     }
+
+    if (!fn) {
+        lprintf(error,
+                "Failed to derive cache key/name from URL or linkname\n");
+        if (fn_alloc) {
+            FREE(fn_alloc);
+        }
+        LinkTable_unref(this_link->parent_table);
+        return 1;
+    }
     Cache *cf = Cache_alloc();
     cf->path = STRNDUP(fn, PATH_MAX);
     cf->link = this_link;
@@ -988,7 +1015,9 @@ int Cache_create(const char *path)
         lprintf(fatal, "Cache file creation failed for %s\n", path);
     }
 
-    if (CONFIG.mode == NORMAL || CONFIG.mode == SONIC) {
+    if (CONFIG.mode == NORMAL) {
+        FREE(fn_alloc);
+    } else if (CONFIG.mode == SINGLE) {
         curl_free(fn);
     }
 
@@ -1025,9 +1054,22 @@ Cache *Cache_open(const char *fn)
         return link->cache_ptr;
     }
 
+    char *actual_fn_alloc = NULL;
     const char *actual_fn = fn;
     if (CONFIG.mode == SONIC) {
         actual_fn = link->sonic.id;
+    } else if (CONFIG.mode == NORMAL) {
+        actual_fn_alloc = url_to_cache_path(link->f_url);
+        if (!actual_fn_alloc) {
+            lprintf(error, "Failed to derive cache path from URL: %s\n",
+                    link->f_url);
+            lprintf(cache_lock_debug, "thread %lx: unlocking cf_lock;\n",
+                    (unsigned long)pthread_self());
+            PTHREAD_MUTEX_UNLOCK(&cf_lock);
+            LinkTable_unref(link->parent_table);
+            return NULL;
+        }
+        actual_fn = actual_fn_alloc;
     }
 
     if (link->content_length <= 0) {
@@ -1036,6 +1078,9 @@ Cache *Cache_open(const char *fn)
                 (unsigned long)pthread_self());
         PTHREAD_MUTEX_UNLOCK(&cf_lock);
         LinkTable_unref(link->parent_table);
+        if (actual_fn_alloc) {
+            FREE(actual_fn_alloc);
+        }
         return NULL;
     }
 
@@ -1050,6 +1095,9 @@ Cache *Cache_open(const char *fn)
                         (unsigned long)pthread_self());
                 PTHREAD_MUTEX_UNLOCK(&cf_lock);
                 LinkTable_unref(link->parent_table);
+                if (actual_fn_alloc) {
+                    FREE(actual_fn_alloc);
+                }
                 return NULL;
             }
         }
@@ -1101,6 +1149,9 @@ Cache *Cache_open(const char *fn)
             lprintf(cache_lock_debug, "thread %lx: unlocking cf_lock;\n",
                     (unsigned long)pthread_self());
             PTHREAD_MUTEX_UNLOCK(&cf_lock);
+            if (actual_fn_alloc) {
+                FREE(actual_fn_alloc);
+            }
             return cf;
         }
 
@@ -1121,6 +1172,9 @@ Cache *Cache_open(const char *fn)
             (unsigned long)pthread_self());
     PTHREAD_MUTEX_UNLOCK(&cf_lock);
     LinkTable_unref(link->parent_table);
+    if (actual_fn_alloc) {
+        FREE(actual_fn_alloc);
+    }
     return NULL;
 }
 

src/link.c

@@ -1068,14 +1068,56 @@ LinkTable *LinkTable_alloc(const char *url)
     return linktbl;
 }
 
+char *url_to_cache_path(const char *url)
+{
+    if (!url) {
+        return NULL;
+    }
+    char *unescaped_path;
+    /*
+     * When --external-links is active a directory link from an external
+     * server may be navigated. Its URL won't share the root server's
+     * origin, so applying ROOT_LINK_OFFSET would produce garbage. Detect
+     * this case by checking whether url is cross-origin from root.
+     */
+    if (ROOT_LINK_TBL && is_cross_origin(ROOT_LINK_TBL->links[0]->f_url, url)) {
+        /* External URL: use the full URL as the cache key path. */
+        char *temp = curl_easy_unescape(NULL, url, 0, NULL);
+        unescaped_path = temp ? STRDUP(temp) : STRDUP(url);
+        if (temp) {
+            curl_free(temp);
+        }
+        /* Sanitize unescaped_path to prevent path traversal via ".." */
+        char *p = unescaped_path;
+        while ((p = strstr(p, ".."))) {
+            p[0] = '_';
+            p[1] = '_';
+            p += 2;
+        }
+        /* Sanitize unescaped_path to prevent path traversal and invalid
+         * directory structures */
+        for (char *sp = unescaped_path; *sp; sp++) {
+            if (*sp == '/' || *sp == ':') {
+                *sp = '_';
+            }
+        }
+    } else {
+        size_t url_len = strlen(url);
+        const char *offset_url = (url_len >= (size_t)ROOT_LINK_OFFSET)
+                                     ? url + ROOT_LINK_OFFSET
+                                     : url;
+        char *temp = curl_easy_unescape(NULL, offset_url, 0, NULL);
+        unescaped_path = temp ? STRDUP(temp) : STRDUP(offset_url);
+        if (temp) {
+            curl_free(temp);
+        }
+    }
+    return unescaped_path;
+}
 
 LinkTable *LinkTable_new(const char *url)
 {
-    char *unescaped_path;
-    size_t url_len = strlen(url);
-    const char *offset_url
-        = (url_len >= (size_t)ROOT_LINK_OFFSET) ? url + ROOT_LINK_OFFSET : url;
-    unescaped_path = curl_easy_unescape(NULL, offset_url, 0, NULL);
+    char *unescaped_path = url_to_cache_path(url);
     LinkTable *linktbl = NULL;
 
     /*
@@ -1138,9 +1180,7 @@ LinkTable *LinkTable_new(const char *url)
         }
     }
 
-    if (unescaped_path) {
-        curl_free(unescaped_path);
-    }
+    FREE(unescaped_path);
     LinkTable_print(linktbl);
     return linktbl;
 }

src/link.h

@@ -266,4 +266,10 @@ int is_cross_origin(const char *page_url, const char *link_url);
  */
 char *external_url_to_filename(const char *url);
 
+/**
+ * \brief Safely generate the cache path for a given URL, handling cross-origin
+ * external links.
+ * \note The caller must free the returned string with FREE().
+ */
+char *url_to_cache_path(const char *url);
 #endif

tests/integration/run_integration_test.sh

@@ -698,7 +698,65 @@ else
     wait "${COMPAT_PID}" 2>/dev/null || true
 fi
 
+# ── Test 6: cache mode with --external-links ───────────────────────────────
+log_info "Test group: External-links cache mode"
 
+# Remove and recreate the cache directory for a completely clean state
+rm -rf "${CACHE_DIR:?}"
+mkdir -p "${CACHE_DIR}"
+
+"${HTTPDIRFS_BIN}" \
+    -f \
+    --external-links \
+    --cache \
+    --cache-location "${CACHE_DIR}" \
+    "${EXT_TEST_URL}" \
+    "${EXT_MOUNT_DIR}" &
+EXT_CACHE_PID=$!
+
+for i in $(seq 1 "${MOUNT_TIMEOUT}"); do
+    mountpoint -q "${EXT_MOUNT_DIR}" 2>/dev/null && break
+    sleep 1
+done
+
+if ! mountpoint -q "${EXT_MOUNT_DIR}" 2>/dev/null; then
+    fail "httpdirfs (--external-links --cache) failed to mount."
+    kill "${EXT_CACHE_PID}" 2>/dev/null || true
+else
+    # 6a. Check file presence
+    if [[ -e "${EXT_MOUNT_DIR}/external_file.txt" ]]; then
+        pass "external_link_cache_mode: file present"
+    else
+        fail "external_link_cache_mode: file missing"
+    fi
+
+    # 6b. Verify content integrity (downloads and caches the file)
+    if [[ -e "${EXT_MOUNT_DIR}/external_file.txt" ]]; then
+        actual=$(sha256sum "${EXT_MOUNT_DIR}/external_file.txt" \
+            | awk '{print $1}')
+        if [[ "${actual}" == "${EXT_FILE_SHA}" ]]; then
+            pass "external_link_cache_mode: content OK"
+        else
+            fail "external_link_cache_mode: content checksum mismatch"
+        fi
+    else
+        skip "external_link_cache_mode: content check skipped (file missing)"
+    fi
+
+    # 6c. Verify re-reading from cache works
+    if [[ -e "${EXT_MOUNT_DIR}/external_file.txt" ]]; then
+        actual_cached=$(sha256sum "${EXT_MOUNT_DIR}/external_file.txt" \
+            | awk '{print $1}')
+        if [[ "${actual_cached}" == "${EXT_FILE_SHA}" ]]; then
+            pass "external_link_cache_mode: cached re-read OK"
+        else
+            fail "external_link_cache_mode: cached re-read checksum mismatch"
+        fi
+    fi
+
+    do_unmount "${EXT_MOUNT_DIR}"
+    wait "${EXT_CACHE_PID}" 2>/dev/null || true
+fi
 
 # Stop the external HTTP server
 cleanup_ext

tests/test_link.c

@@ -401,6 +401,29 @@ void test_Link_preserves_preset_f_url(void)
 /* url_to_cache_path() tests                                                 */
 /* ========================================================================= */
 
+void test_url_to_cache_path_null(void)
+{
+    TEST_ASSERT_NULL(url_to_cache_path(NULL));
+}
+
+void test_url_to_cache_path_local(void)
+{
+    char *path = url_to_cache_path("http://localhost/my%20file.iso");
+    TEST_ASSERT_NOT_NULL(path);
+    TEST_ASSERT_EQUAL_STRING("http://localhost/my file.iso", path);
+    FREE(path);
+}
+
+void test_url_to_cache_path_external_sanitization(void)
+{
+    ROOT_LINK_TBL = LinkTable_alloc("http://localhost/");
+    char *path = url_to_cache_path("http://external.com/my%20file.iso?param=1");
+    TEST_ASSERT_NOT_NULL(path);
+    TEST_ASSERT_EQUAL_STRING("http___external.com_my file.iso?param=1", path);
+    FREE(path);
+    LinkTable_free(ROOT_LINK_TBL);
+    ROOT_LINK_TBL = NULL;
+}
 
 /* ========================================================================= */
 /* Pre-existing tests                                                        */
@@ -582,6 +605,9 @@ int main(void)
     RUN_TEST(test_HTML_external_link_dot_and_dotdot);
     RUN_TEST(test_Link_preserves_preset_f_url);
     /* url_to_cache_path */
+    RUN_TEST(test_url_to_cache_path_null);
+    RUN_TEST(test_url_to_cache_path_local);
+    RUN_TEST(test_url_to_cache_path_external_sanitization);
 
     /* Pre-existing tests */
     RUN_TEST(test_LinkTable_alloc);