Merge pull request #284 from fangfufu/feature/cache-size-thresholds

feat: add --cache-min-size and --cache-max-size file size threshold options

Author: fangfufu

USAGE.md

@@ -6,8 +6,72 @@ configuration and usage flags supported by HTTPDirFS.
 
 ### Command Syntax
 
+Below is the raw help output displaying all available flags:
+
 ```bash
-httpdirfs [options] URL mountpoint
+usage: httpdirfs [options] URL mountpoint
+
+general options:
+        --config            Specify a configuration file
+    -o opt,[opt...]         Mount options
+    -h  --help              Print help
+    -V  --version           Print version
+    -f                      Foreground operation
+    -s                      Disable multi-threaded operation
+    -d  --debug             Enable debug output (implies -f)
+
+HTTPDirFS options:
+    -u  --username          HTTP authentication username
+    -p  --password          HTTP authentication password
+    -P  --proxy             Proxy for libcurl, for more details refer to
+                            https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html
+        --proxy-username    Username for the proxy
+        --proxy-password    Password for the proxy
+        --proxy-cacert      Certificate authority for the proxy
+        --proxy-capath      Certificate authority directory for the proxy
+        --cache             Enable cache (default: off)
+        --cache-location    Set a custom cache location
+                            (default: "${XDG_CACHE_HOME}/httpdirfs")
+        --cache-clear       Delete the cache directory or the custom location
+                            specified with `--cache-location`, if the option is
+                            seen first. Then exit in either case.
+        --cache-min-size    Set minimum file size threshold for caching, in bytes
+                            (default: none)
+        --cache-max-size    Set maximum file size threshold for caching, in bytes
+                            (default: none)
+        --cacert            Certificate authority for the server
+        --capath            Certificate authority directory for the server
+        --dl-seg-size       Set cache download segment size, in MB (default: 8)
+                            Note: this setting is ignored if previously
+                            cached data is found for the requested file.
+        --http-header       Set one or more HTTP headers
+        --max-conns         Set maximum number of network connections that
+                            libcurl is allowed to make. (default: 6)
+        --refresh-timeout   The directories are refreshed after the specified
+                            time, in seconds (default: 3600)
+        --retry-wait        Set delay in seconds before retrying an HTTP request
+                            after encountering an error. (default: 5)
+        --invalid-refresh   Try refreshing invalid links when reading a directory.
+        --user-agent        Set user agent string (default: "HTTPDirFS-1.3.1")
+        --no-range-check    Disable the built-in check for the server's support
+                            for HTTP range requests
+        --zero-len-is-dir   If a file has a zero length, treat it as a directory
+        --insecure-tls      Disable libcurl TLS certificate verification by
+                            setting CURLOPT_SSL_VERIFYHOST to 0
+        --external-links    Include external (cross-origin) links from
+                            directory listings (default: off)
+        --single-file-mode  Single file mode - rather than mounting a whole
+                            directory, present a single file inside a virtual
+                            directory.
+
+    For mounting a Airsonic / Subsonic server:
+        --sonic-username    The username for your Airsonic / Subsonic server
+        --sonic-password    The password for your Airsonic / Subsonic server
+        --sonic-id3         Enable ID3 mode - this present the server content in
+                            Artist/Album/Song layout
+        --sonic-insecure    Authenticate against your Airsonic / Subsonic server
+                            using the insecure username / hex encoded password
+                            scheme
 ```
 
 ---
@@ -149,6 +213,20 @@ httpdirfs [options] URL mountpoint
 - **Note:** This setting is ignored for files that already have existing cached
   segment data on disk.
 
+#### `--cache-min-size <bytes>`
+
+- **Description:** Sets the minimum file size threshold for caching in bytes.
+  Files with a size smaller than this threshold will bypass the local disk cache
+  and be downloaded directly from the network upon access.
+- **Default:** None (no minimum limit is set).
+
+#### `--cache-max-size <bytes>`
+
+- **Description:** Sets the maximum file size threshold for caching in bytes.
+  Files with a size larger than this threshold will bypass the local disk cache
+  and be downloaded directly from the network upon access.
+- **Default:** None (no maximum limit is set).
+
 ---
 
 ### Network & Performance Options

src/config.c

@@ -86,6 +86,9 @@ void Config_init(void)
 
     CONFIG.data_blksz = DEFAULT_DATA_BLKSZ;
 
+    CONFIG.cache_min_size = -1;
+    CONFIG.cache_max_size = -1;
+
     /*-------------- Sonic related -------------*/
     CONFIG.sonic_username = NULL;
 

src/config.h

@@ -29,6 +29,7 @@
  */
 
 #include <limits.h>
+#include <sys/types.h>
 
 /**
  * \brief the default user agent string
@@ -126,6 +127,10 @@ typedef struct {
     int data_blksz;
     /** \brief The maximum segment count for a single cache file */
     int max_segbc;
+    /** \brief The minimum file size threshold for caching */
+    off_t cache_min_size;
+    /** \brief The maximum file size threshold for caching */
+    off_t cache_max_size;
     /*-------------- Sonic related -------------*/
     /** \brief The Sonic server username */
     char *sonic_username;

src/fuse_local.c

@@ -29,9 +29,14 @@
 #include "fuse_local.h"
 
 #include "cache.h"
+#include "config.h"
 #include "link.h"
 #include "log.h"
 
+/* clang-format off */
+#define BYPASS_FH ((uint64_t)-1)
+/* clang-format on */
+
 /*
  * must be included before including <fuse.h>
  */
@@ -58,7 +63,7 @@ static int fs_release(const char *path, struct fuse_file_info *fi)
 {
     lprintf(info, "%s\n", path);
     (void)path;
-    if (CACHE_SYSTEM_INIT && fi->fh) {
+    if (CACHE_SYSTEM_INIT && fi->fh && fi->fh != BYPASS_FH) {
         Cache_close((Cache *)fi->fh);
     }
     return 0;
@@ -119,10 +124,11 @@ static int fs_read(const char *path, char *buf, size_t size, off_t offset,
 {
     long received;
     if (CACHE_SYSTEM_INIT) {
-        if (fi->fh) {
+        if (fi->fh == BYPASS_FH) {
+            received = path_download(path, buf, size, offset);
+        } else if (fi->fh) {
             received = Cache_read((Cache *)fi->fh, buf, size, offset);
         } else {
-            /* zero-length file: fi->fh was set to 0 in fs_open; return EOF */
             received = 0;
         }
     } else {
@@ -149,6 +155,20 @@ static int fs_open(const char *path, struct fuse_file_info *fi)
             LinkTable_unref(link->parent_table);
             return 0;
         }
+        int bypass_cache = 0;
+        off_t file_size = (off_t)link->content_length;
+        if (file_size < 0 || (size_t)file_size != link->content_length
+            || (CONFIG.cache_min_size >= 0 && file_size < CONFIG.cache_min_size)
+            || (CONFIG.cache_max_size >= 0
+                && file_size > CONFIG.cache_max_size)) {
+            bypass_cache = 1;
+        }
+        if (bypass_cache) {
+            /* bypass cache creation due to size thresholds */
+            fi->fh = BYPASS_FH;
+            LinkTable_unref(link->parent_table);
+            return 0;
+        }
         fi->fh = (uint64_t)Cache_open(path);
         /*
          * The cache definitely cannot be opened for some reason.

src/main.c

@@ -353,6 +353,8 @@ static int parse_arg_list(int argc, char **argv, char ***fuse_argv,
            {"capath", required_argument, NULL, 'L'},          /* 29 */
            {"proxy-capath", required_argument, NULL, 'L'},    /* 30 */
            {"external-links", no_argument, NULL, 'L'},        /* 31 */
+           {"cache-min-size", required_argument, NULL, 'L'},  /* 32 */
+           {"cache-max-size", required_argument, NULL, 'L'},  /* 33 */
            {0, 0, 0, 0}};
     while ((c = getopt_long(argc, argv, short_opts, long_opts, &long_index))
            != -1) {
@@ -475,6 +477,32 @@ static int parse_arg_list(int argc, char **argv, char ***fuse_argv,
             case 31:
                 CONFIG.external_links = 1;
                 break;
+            case 32: {
+                char *endptr;
+                errno = 0;
+                long long val = strtoll(optarg, &endptr, 10);
+                if (errno != 0 || endptr == optarg || *endptr != '\0' || val < 0
+                    || (long long)(off_t)val != val) {
+                    fprintf(stderr,
+                            "Error: --cache-min-size requires a "
+                            "non-negative integer within off_t range\n");
+                    return 1;
+                }
+                CONFIG.cache_min_size = (off_t)val;
+            } break;
+            case 33: {
+                char *endptr;
+                errno = 0;
+                long long val = strtoll(optarg, &endptr, 10);
+                if (errno != 0 || endptr == optarg || *endptr != '\0' || val < 0
+                    || (long long)(off_t)val != val) {
+                    fprintf(stderr,
+                            "Error: --cache-max-size requires a "
+                            "non-negative integer within off_t range\n");
+                    return 1;
+                }
+                CONFIG.cache_max_size = (off_t)val;
+            } break;
             default:
                 fprintf(stderr, "see httpdirfs -h for usage\n");
                 return 1;
@@ -485,6 +513,12 @@ static int parse_arg_list(int argc, char **argv, char ***fuse_argv,
             return 1;
         }
     };
+    if (CONFIG.cache_min_size >= 0 && CONFIG.cache_max_size >= 0
+        && CONFIG.cache_min_size > CONFIG.cache_max_size) {
+        fprintf(stderr, "Error: --cache-min-size cannot be greater than "
+                        "--cache-max-size\n");
+        return 1;
+    }
     return 0;
 }
 
@@ -530,6 +564,10 @@ HTTPDirFS options:\n\
         --cache-clear       Delete the cache directory or the custom location\n\
                             specified with `--cache-location`, if the option is\n\
                             seen first. Then exit in either case.\n\
+        --cache-min-size    Set minimum file size threshold for caching, in bytes\n\
+                            (default: none)\n\
+        --cache-max-size    Set maximum file size threshold for caching, in bytes\n\
+                            (default: none)\n\
         --cacert            Certificate authority for the server\n\
         --capath            Certificate authority directory for the server\n\
         --dl-seg-size       Set cache download segment size, in MB (default: " XSTR(
@@ -548,7 +586,7 @@ HTTPDirFS options:\n\
         --no-range-check    Disable the built-in check for the server's support\n\
                             for HTTP range requests\n\
         --zero-len-is-dir   If a file has a zero length, treat it as a directory\n\
-        --insecure-tls      Disable licurl TLS certificate verification by\n\
+        --insecure-tls      Disable libcurl TLS certificate verification by\n\
                             setting CURLOPT_SSL_VERIFYHOST to 0\n\
         --external-links    Include external (cross-origin) links from\n\
                             directory listings (default: off)\n\