feat: cleaner worker thread for File Driver (#13)

Author: Julien-R44

docs/content/docs/cache_drivers.md

@@ -65,8 +65,10 @@ import { fileDriver } from "bentocache/drivers/file";
 const bento = new BentoCache({
   default: 'file',
   stores: {
-    redis: bentostore().useL2Layer(fileDriver({
-      directory: './cache'
+    redis: bentostore().useL2Layer(
+      fileDriver({
+        directory: './cache',
+        pruneInterval: '1h'
     }))
   }
 })
@@ -75,6 +77,11 @@ const bento = new BentoCache({
 | Option | Description | Default |
 | --- | --- | --- |
 | `directory` | The directory where the cache files will be stored. | N/A |
+| `pruneInterval` | The interval in milliseconds to prune expired entries. false to disable. | false |
+
+### Prune Interval
+
+Since the filesystem driver does not have a way to automatically prune expired entries, you can set a `pruneInterval` to automatically prune expired entries. By setting this option, the driver will launch a [worker thread](https://nodejs.org/api/worker_threads.html) that will clean up the cache at the specified interval.
 
 ## Memory
 
@@ -165,7 +172,7 @@ All SQL drivers accept the following options:
 | `tableName` | The name of the table that will be used to store the cache. | `bentocache` |
 | `autoCreateTable` | If the cache table should be automatically created if it does not exist. | `true` |
 | `connection` | An instance of `knex` or `Kysely` based on the driver. | N/A |
-| `pruneInterval` | The interval in milliseconds to prune expired entries. | `60000` |
+| `pruneInterval` | The [Duration](./options.md#ttl-formats) in milliseconds to prune expired entries. | false |
 
 ### Knex
 

packages/bentocache/package.json

@@ -15,7 +15,14 @@
   ],
   "exports": {
     ".": "./build/index.js",
-    "./drivers/*": "./build/src/drivers/*.js",
+    "./drivers/redis": "./build/src/drivers/redis.js",
+    "./drivers/memory": "./build/src/drivers/memory.js",
+    "./drivers/file": "./build/src/drivers/file/file.js",
+    "./drivers/dynamodb": "./build/src/drivers/dynamodb.js",
+    "./drivers/base_driver": "./build/src/drivers/base_driver.js",
+    "./drivers/database": "./build/src/drivers/database/database.js",
+    "./drivers/knex": "./build/src/drivers/database/adapters/knex.js",
+    "./drivers/kysely": "./build/src/drivers/database/adapters/kysely.js",
     "./types": "./build/src/types/main.js",
     "./plugins/*": "./build/plugins/*.js",
     "./test_suite": "./build/src/test_suite.js"
@@ -32,7 +39,7 @@
     "quick:test": "cross-env NODE_NO_WARNINGS=1 node --enable-source-maps --loader=ts-node/esm bin/test.ts",
     "pretest": "pnpm lint",
     "test": "c8 pnpm quick:test",
-    "build": "tsup-node",
+    "build": "pnpm clean && tsup-node",
     "postbuild": "pnpm copy:templates",
     "release": "pnpm build && pnpm release-it",
     "version": "pnpm build",
@@ -113,6 +120,10 @@
       "./index.ts",
       "./src/types/main.ts",
       "./src/drivers/*.ts",
+      "./src/drivers/database/database.ts",
+      "./src/drivers/database/adapters/*.ts",
+      "./src/drivers/file/file.ts",
+      "./src/drivers/file/cleaner_worker.js",
       "./plugins/*.ts",
       "./src/test_suite.ts"
     ],

packages/bentocache/src/drivers/knex.ts packages/bentocache/src/drivers/database/adapters/knex.ts

@@ -1,7 +1,7 @@
 import type { Knex } from 'knex'
 
-import { DatabaseDriver } from './database.js'
-import type { CreateDriverResult, DatabaseAdapter, KnexConfig } from '../types/main.js'
+import { DatabaseDriver } from '../database.js'
+import type { CreateDriverResult, DatabaseAdapter, KnexConfig } from '../../../types/main.js'
 
 /**
  * Create a knex driver

packages/bentocache/src/drivers/kysely.ts packages/bentocache/src/drivers/database/adapters/kysely.ts

@@ -1,7 +1,7 @@
 import { SqliteAdapter, type Kysely, MysqlAdapter } from 'kysely'
 
-import { DatabaseDriver } from './database.js'
-import type { CreateDriverResult, DatabaseAdapter, KyselyConfig } from '../types/main.js'
+import { DatabaseDriver } from '../database.js'
+import type { CreateDriverResult, DatabaseAdapter, KyselyConfig } from '../../../types/main.js'
 
 /**
  * Create a kysely driver

packages/bentocache/src/drivers/database.ts packages/bentocache/src/drivers/database/database.ts

@@ -1,5 +1,6 @@
-import { BaseDriver } from './base_driver.js'
-import type { DatabaseConfig, CacheDriver, DatabaseAdapter } from '../types/main.js'
+import { resolveTtl } from '../../helpers.js'
+import { BaseDriver } from '../base_driver.js'
+import type { DatabaseConfig, CacheDriver, DatabaseAdapter } from '../../types/main.js'
 
 /**
  * A store that use a database to store cache entries
@@ -41,9 +42,8 @@ export class DatabaseDriver extends BaseDriver implements CacheDriver<true> {
       this.#initialized = Promise.resolve()
     }
 
-    if (typeof config.pruneInterval === 'number') {
-      this.#startPruneInterval(config.pruneInterval)
-    }
+    if (config.pruneInterval === false) return
+    this.#startPruneInterval(resolveTtl(config.pruneInterval)!)
   }
 
   /**

packages/bentocache/src/drivers/file/cleaner_worker.js

@@ -0,0 +1,49 @@
+// @ts-check
+
+import { join } from 'node:path'
+import { workerData } from 'node:worker_threads'
+import { readdir, unlink, readFile } from 'node:fs/promises'
+
+const directory = workerData.directory
+const pruneIntervalInMs = workerData.pruneInterval
+
+/**
+ * Read the file content and delete it if it's expired
+ *
+ * @param {string} filePath
+ */
+async function deleteFileIfExpired(filePath) {
+  const content = await readFile(filePath, 'utf-8')
+  const [, expiresAt] = JSON.parse(content)
+
+  const expiry = new Date(expiresAt).getTime()
+  if (+expiry === -1) return
+
+  if (expiry < Date.now()) {
+    await unlink(filePath)
+  }
+}
+
+/**
+ * Get recursive list of files in the cache directory and delete expired files
+ */
+async function prune() {
+  const dirEntries = await readdir(directory, { recursive: true, withFileTypes: true })
+
+  for (const dirEntry of dirEntries) {
+    if (dirEntry.isDirectory()) continue
+
+    const filePath = join(dirEntry.path, dirEntry.name)
+    await deleteFileIfExpired(filePath).catch((error) => {
+      console.error('[bentocache] file cleaner worker error', error)
+    })
+  }
+}
+
+setInterval(async () => {
+  try {
+    await prune()
+  } catch (error) {
+    console.error('[bentocache] file cleaner worker error', error)
+  }
+}, pruneIntervalInMs)

packages/bentocache/src/drivers/file.ts packages/bentocache/src/drivers/file/file.ts

@@ -1,17 +1,16 @@
 import { dirname, join } from 'node:path'
+import { Worker } from 'node:worker_threads'
 import { access, mkdir, readFile, writeFile, rm } from 'node:fs/promises'
 
-import { BaseDriver } from './base_driver.js'
-import type { CacheDriver, CreateDriverResult, FileConfig } from '../types/main.js'
+import { resolveTtl } from '../../helpers.js'
+import { BaseDriver } from '../base_driver.js'
+import type { CacheDriver, CreateDriverResult, FileConfig } from '../../types/main.js'
 
 /**
  * Create a new file driver
  */
 export function fileDriver(options: FileConfig): CreateDriverResult<FileDriver> {
-  return {
-    options,
-    factory: (config: FileConfig) => new FileDriver(config),
-  }
+  return { options, factory: (config: FileConfig) => new FileDriver(config) }
 }
 
 /**
@@ -30,12 +29,28 @@ export class FileDriver extends BaseDriver implements CacheDriver {
    */
   #directory: string
 
+  /**
+   * Worker thread that will clean up the expired files
+   */
+  #cleanerWorker?: Worker
+
   declare config: FileConfig
 
-  constructor(config: FileConfig) {
+  constructor(config: FileConfig, isNamespace: boolean = false) {
     super(config)
 
     this.#directory = this.#sanitizePath(join(config.directory, config.prefix || ''))
+
+    /**
+     * If this is a namespaced class, then we should not start the cleaner
+     * worker multiple times. Only the parent class will take care of it.
+     */
+    if (isNamespace) return
+    if (config.pruneInterval === false) return
+
+    this.#cleanerWorker = new Worker(new URL('./cleaner_worker.js', import.meta.url), {
+      workerData: { directory: this.#directory, pruneInterval: resolveTtl(config.pruneInterval) },
+    })
   }
 
   /**
@@ -95,10 +110,7 @@ export class FileDriver extends BaseDriver implements CacheDriver {
    * Returns a new instance of the driver namespaced
    */
   namespace(namespace: string) {
-    return new FileDriver({
-      ...this.config,
-      prefix: this.createNamespacePrefix(namespace),
-    })
+    return new FileDriver({ ...this.config, prefix: this.createNamespacePrefix(namespace) }, true)
   }
 
   /**
@@ -217,5 +229,7 @@ export class FileDriver extends BaseDriver implements CacheDriver {
     return true
   }
 
-  async disconnect() {}
+  async disconnect() {
+    await this.#cleanerWorker?.terminate()
+  }
 }

packages/bentocache/src/types/options/drivers_options.ts

@@ -3,6 +3,8 @@ import type { Kysely } from 'kysely'
 import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb'
 import type { Redis as IoRedis, RedisOptions as IoRedisOptions } from 'ioredis'
 
+import type { Duration } from '../helpers.js'
+
 /**
  * Options that are common to all drivers
  *
@@ -87,6 +89,14 @@ export type FileConfig = {
    * Directory where the cache files will be stored
    */
   directory: string
+
+  /**
+   * The interval between each expired entry pruning
+   * Can be set to `false` to disable pruning.
+   *
+   * @default false
+   */
+  pruneInterval?: Duration | false
 } & DriverCommonOptions
 
 /**
@@ -110,7 +120,7 @@ export interface DatabaseConfig extends DriverCommonOptions {
    *
    * @default false
    */
-  pruneInterval?: number | false
+  pruneInterval?: Duration | false
 }
 
 /**

packages/bentocache/test_helpers/driver_test_suite.ts

@@ -20,7 +20,12 @@ export function registerCacheDriverTestSuite(options: {
   const { test, group } = options
   const sleepTime = options.supportsMilliseconds ? 20 : 1000
 
-  const cache = options.createDriver()
+  let cache: CacheDriver
+
+  group.setup(async () => {
+    cache = options.createDriver()
+    return () => cache.disconnect()
+  })
 
   group.tap((t) => t.disableTimeout())
   group.each.teardown(async () => {
@@ -29,10 +34,6 @@ export function registerCacheDriverTestSuite(options: {
 
   options.configureGroup?.(group)
 
-  group.teardown(async () => {
-    await cache.disconnect()
-  })
-
   test('get() returns undefined when key does not exists', async ({ assert }) => {
     assert.deepEqual(await cache.get('key'), undefined)
   })

packages/bentocache/tests/drivers/database.spec.ts

@@ -2,20 +2,18 @@ import knex from 'knex'
 import { test } from '@japa/runner'
 import { setTimeout } from 'node:timers/promises'
 
-import { KnexAdapter } from '../../src/drivers/knex.js'
-import { DatabaseDriver } from '../../src/drivers/database.js'
+import { DatabaseDriver } from '../../src/drivers/database/database.js'
+import { KnexAdapter } from '../../src/drivers/database/adapters/knex.js'
 
 test.group('Database', () => {
   test('should prune expired items every x seconds', async ({ assert, cleanup }) => {
-    const adapter = new KnexAdapter({
-      connection: knex({
-        client: 'better-sqlite3',
-        connection: { filename: ':memory:' },
-        useNullAsDefault: true,
-      }),
+    const db = knex({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
     })
 
-    const driver = new DatabaseDriver(adapter, {
+    const driver = new DatabaseDriver(new KnexAdapter({ connection: db }), {
       tableName: 'cache',
       autoCreateTable: true,
       pruneInterval: 500,
@@ -30,7 +28,10 @@ test.group('Database', () => {
 
     await setTimeout(1000)
 
-    assert.isUndefined(await driver.get('foo'))
-    assert.isUndefined(await driver.get('foo2'))
+    const hasFoo = await db('cache').where('key', 'foo').first()
+    const hasFoo2 = await db('cache').where('key', 'foo2').first()
+
+    assert.isUndefined(hasFoo)
+    assert.isUndefined(hasFoo2)
   })
 })

packages/bentocache/tests/drivers/file.spec.ts

@@ -1,8 +1,9 @@
 import { test } from '@japa/runner'
 import { fileURLToPath } from 'node:url'
+import { setTimeout } from 'node:timers/promises'
 
-import { FileDriver } from '../../src/drivers/file.js'
 import { BASE_URL } from '../../test_helpers/index.js'
+import { FileDriver } from '../../src/drivers/file/file.js'
 import { registerCacheDriverTestSuite } from '../../test_helpers/driver_test_suite.js'
 
 test.group('File driver', (group) => {
@@ -14,3 +15,51 @@ test.group('File driver', (group) => {
     },
   })
 })
+
+test.group('File Driver | Prune', () => {
+  test('should prune expired items every x seconds', async ({ assert, fs, cleanup }) => {
+    const driver = new FileDriver({
+      pruneInterval: 500,
+      directory: fileURLToPath(BASE_URL),
+    })
+
+    cleanup(() => driver.disconnect())
+
+    await Promise.all([
+      driver.set('foo', 'bar', 300),
+      driver.set('foo2', 'bar', 300),
+      driver.set('foo3:1', 'bar', 300),
+      driver.set('foo4', 'bar', undefined),
+    ])
+
+    await setTimeout(1000)
+
+    assert.isFalse(await fs.exists('foo'))
+    assert.isFalse(await fs.exists('foo2'))
+    assert.isFalse(await fs.exists('foo3/1'))
+    assert.isTrue(await fs.exists('foo4'))
+  })
+
+  test('continue if invalid file is inside the cache directory', async ({
+    assert,
+    fs,
+    cleanup,
+  }) => {
+    const driver = new FileDriver({
+      pruneInterval: 500,
+      directory: fileURLToPath(BASE_URL),
+    })
+
+    cleanup(() => driver.disconnect())
+
+    await fs.create('foo', 'invalid content')
+
+    await Promise.all([driver.set('foo2', 'bar', 300), driver.set('foo3:1', 'bar', 300)])
+
+    await setTimeout(1000)
+
+    assert.isTrue(await fs.exists('foo'))
+    assert.isFalse(await fs.exists('foo2'))
+    assert.isFalse(await fs.exists('foo3/1'))
+  })
+})