feat: introduce plugin system with routes/hooks, metadata, tests, and docs

.gitignore

@@ -6,6 +6,8 @@
 !docs/**
 !src
 !src/**
+!test/
+!test/**
 !.dockerignore
 !.gitignore
 !constants.js
@@ -14,4 +16,6 @@
 !package.json
 !README.md
 !config.default.js 
-!biome.json
+!biome.json
+!test
+!test/**

README.md

@@ -61,6 +61,45 @@ Once started, NodeLink runs a Lavalink-compatible WebSocket server, ready for im
 
 ---
 
+## Plugins
+NodeLink now supports a simple plugin system so you can add custom HTTP routes and register new sources or lyrics providers without modifying core files.
+
+- Local development: add files under `src/plugins/src/*.js`.
+- Package plugins: install NPM packages named `nodelink-plugin-*`.
+
+See `docs/plugins.md` for the full API and examples. Prefer descriptive names over abbreviations in plugins (e.g., `pluginApi`, `configuration`).
+
+### Audio Cache Plugin Settings
+- Configure in `config.js` under `plugins.audioCache`:
+```js
+plugins: {
+  audioCache: {
+    enabled: true,
+    dir: 'cache/audio',               // cache directory
+    ttlDays: 7,                       // days to keep inactive files
+    cleanupIntervalHours: 12,         // periodic cleanup interval
+    maxSize: '1GB',                   // or maxSizeBytes: 10 * 1024 * 1024 * 1024
+    protectRecentMinutes: 60,         // Do not evict files accessed within this window (minutes)
+    allowExceedWhenAllRecent: true    // If all files are in-use or recently used, allow exceeding max size
+  }
+}
+```
+
+### Prebuffer Plugin Settings
+- Configure in `config.js` under `plugins.prebuffer`:
+```js
+plugins: {
+  prebuffer: {
+    enabled: true,
+    bytes: '512 KB',        // target initial buffered bytes
+    timeoutMs: 2000,        // optional maximum wait for prebuffer
+    highWaterMark: '1 MB'   // internal stream buffer size
+  }
+}
+```
+
+---
+
 ## Usage
 
 NodeLink is compatible with most Lavalink clients, as it implements nearly the entire original API.

config.default.js

@@ -203,5 +203,29 @@ export default {
       delayMs: 500,
       blockDurationMs: 300000 // 5 minutes
     }
+  },
+  plugins: {
+    audioCache: {
+      enabled: false,
+      dir: 'cache/audio',
+      ttlDays: 7,
+      cleanupIntervalHours: 12,
+      maxSize: '1GB', // or maxSizeBytes: 10 * 1024 * 1024 * 1024
+      // Do not evict files accessed within this window (minutes)
+      protectRecentMinutes: 60,
+      // If all files are in-use or recently used, allow exceeding max size
+      allowExceedWhenAllRecent: true
+    },
+    // Start playback only after some data has buffered.
+    // Applies to non-live streams. Uses compressed bytes (source stream) as reference.
+    prebuffer: {
+      enabled: false,
+      // Buffer target before releasing data downstream. Accepts number (bytes) or string: '512KB', '1MB', etc.
+      bytes: '512KB',
+      // Max time to wait before starting even if bytes not reached (ms). Set 0 to disable.
+      timeoutMs: 2000,
+      // Internal stream highWaterMark for the output wrapper
+      highWaterMark: '1MB'
+    }
   }
 }

docs/API.md

@@ -370,3 +370,10 @@ A dynamic range compressor that reduces the volume of loud sounds or amplifies q
 | attack?    | float | The attack time in milliseconds.                  |
 | release?   | float | The release time in milliseconds.                 |
 | gain?      | float | The makeup gain in dB.                            |
+
+
+### Cache Plugin Endpoints
+
+- GET /v4/cache/stats: Returns cache file count, total bytes, optional maxBytes, and usagePercent if a cap is configured.
+- POST /v4/cache/cleanup: Triggers TTL cleanup immediately.
+