Add ability to remove keys by type of API call

Signed-off-by: Oleksandr Porunov <[email protected]>

Author: porunov

docs/content/1.getting-started/1.index.md

@@ -77,6 +77,38 @@ The number of days to keep stale cache data and metadata before deleting it. Set
 
 The port the server should listen on.
 
+#### `ENABLE_TYPED_KEY_PREFIX_REMOVAL`
+
+- Default: `false`
+
+If enabled then any specifically structured keys will be automatically removed if there are more keys of such type than 
+the amount specified via `MAX_STORED_KEYS_PER_TYPE`.
+Key type is defined by the following format:
+`{key_type}{TYPED_KEY_DELIMITER}{optional custom string}`
+
+Usually, it's recommended to use the following key structure:
+`{repository_name}_{branch}_{unique_key_name}{TYPED_KEY_DELIMITER}{hash or other unique data}`
+
+An example could look like:
+`falcondev-oss/github-actions-cache-server_dev_docker-cache@#@16ee33c5f9f59c0`
+
+In such case older keys with prefix `falcondev-oss/github-actions-cache-server_dev_docker-cache` will be automatically 
+removed whenever there are more records for this key type then the one specified via `MAX_STORED_KEYS_PER_TYPE`.
+
+#### `MAX_STORED_KEYS_PER_TYPE`
+
+- Default: `3`
+
+If `ENABLE_TYPED_KEY_PREFIX_REMOVAL` is `true` then this is the maximum amount of the most recent keys to keep per key type. 
+Any other older keys will be automatically removed.
+
+#### `TYPED_KEY_DELIMITER`
+
+- Default: `@#@`
+
+If `ENABLE_TYPED_KEY_PREFIX_REMOVAL` is `true` then this is the delimiter which is used to identify the key type. 
+Any prefix before `@#@` is considered to be the key type.
+
 ## 2. Setup with Self-Hosted Runners
 
 To leverage the GitHub Actions Cache Server with your self-hosted runners, you'll need to configure a couple of environment variables on your runners. This ensures that your runners can authenticate with and utilize the cache server effectively.
@@ -139,3 +171,22 @@ Doing it this way is a bit of a hack, but it's easier than compiling your own ru
 There is no need to change any of your workflows! 🔥
 
 If you've set up your self-hosted runners correctly, they will automatically use the cache server for caching.
+
+## 4. Cache cleanup
+
+Cache cleanup can be triggered automatically via configured eviction policies like:
+- `CLEANUP_OLDER_THAN_DAYS` - eviction by time.
+- `ENABLE_TYPED_KEY_PREFIX_REMOVAL` - eviction by key type (key prefix).
+
+Moreover, an additional API exists which can be used to evict key records by using specified key prefix.
+API path: `/<token>/extra/clear_key_prefix`. API method: `POST`.
+Request body: `{ keyPrefix: string }`.
+
+Any keys with the prefix of `keyPrefix` will be removed and data will be cleared for such keys.
+Usually, it's useful to call keys removal for an archived branch or a closed PR where you know that the cache won't 
+be reused anymore. For such cases you could have a step which is called and clears all keys prefixed with the branch name. 
+For example: 
+```
+- name: Remove keys by prefix
+  run: curl --header "Content-Type: application/json" --request POST --data '{"keyPrefix":"${{ github.head_ref || github.ref_name }}"}' "${ACTIONS_CACHE_URL}extra/clear_key_prefix"
+```

lib/db/index.ts

@@ -202,6 +202,31 @@ export async function findStaleKeys(
     .execute()
 }
 
+export async function findPrefixedKeysForRemoval(
+  db: DB,
+  { keyPrefix, skipRecentKeysLimit }: { keyPrefix: string; skipRecentKeysLimit?: number; },
+) {
+
+  let query = db
+    .selectFrom('cache_keys')
+    .where('key', 'like', `${keyPrefix}%`)
+
+  if (skipRecentKeysLimit && skipRecentKeysLimit > 0){
+    query = query.where(({ eb, selectFrom, not }) => not(eb(
+      'id',
+      'in',
+      selectFrom('cache_keys')
+        .select('cache_keys.id')
+        .orderBy('cache_keys.accessed_at desc')
+        .limit(skipRecentKeysLimit)
+    )))
+  }
+
+  return query
+    .selectAll()
+    .execute()
+}
+
 export async function createKey(
   db: DB,
   { key, version, date }: { key: string; version: string; date?: Date },

lib/env.ts

@@ -10,6 +10,9 @@ const envSchema = z.object({
   STORAGE_DRIVER: z.string().toLowerCase().default('filesystem'),
   DB_DRIVER: z.string().toLowerCase().default('sqlite'),
   DEBUG: booleanSchema.default('false'),
+  ENABLE_TYPED_KEY_PREFIX_REMOVAL: booleanSchema.default('false'),
+  MAX_STORED_KEYS_PER_TYPE: z.number().int().min(0).default(3),
+  TYPED_KEY_DELIMITER: z.string().default('@#@'),
 })
 
 const parsedEnv = envSchema.safeParse(process.env)

lib/storage/index.ts

@@ -10,6 +10,7 @@ import {
   updateOrCreateKey,
   uploadExists,
   useDB,
+  findPrefixedKeysForRemoval,
 } from '~/lib/db'
 import { ENV } from '~/lib/env'
 import { logger } from '~/lib/logger'
@@ -20,6 +21,7 @@ import type { Buffer } from 'node:buffer'
 import type { Readable } from 'node:stream'
 
 export interface Storage {
+  pruneCacheByKeyPrefix: (keyPrefix: string) => Promise<void>
   getCacheEntry: (
     keys: string[],
     version: string,
@@ -63,6 +65,41 @@ export async function initializeStorage() {
     const db = useDB()
 
     storage = {
+
+      async pruneCacheKeys(keysForRemoval){
+        if (keysForRemoval.length === 0) {
+          logger.debug('Prune: No caches to prune')
+          return
+        }
+
+        await driver.delete({
+          objectNames: keysForRemoval.map((key) => getObjectNameFromKey(key.key, key.version)),
+        })
+
+        await pruneKeys(db, keysForRemoval)
+      },
+
+      async pruneStaleCacheByType(key){
+        if (!ENV.ENABLE_TYPED_KEY_PREFIX_REMOVAL){
+          return
+        }
+        let keyTypeIndex = key.indexOf(ENV.TYPED_KEY_DELIMITER)
+        if (keyTypeIndex < 1){
+          return
+        }
+        let keyType = key.substring(0, keyTypeIndex)
+        logger.debug(`Prune by type is called: Type [${keyType}]. Full key [${key}].`)
+        let keysForRemoval = await findPrefixedKeysForRemoval(db, { keyPrefix: keyType, skipRecentKeysLimit: ENV.MAX_STORED_KEYS_PER_TYPE } )
+        logger.debug(`Removing ${keysForRemoval.length} keys for prefix [${keyType}].`)
+        await this.pruneCacheKeys(keysForRemoval)
+      },
+
+      async pruneCacheByKeyPrefix(keyPrefix){
+        let keysForRemoval = await findPrefixedKeysForRemoval(db, { keyPrefix: keyPrefix, skipRecentKeysLimit: 0 } )
+        logger.debug(`Removing ${keysForRemoval.length} keys for prefix [${keyPrefix}].`)
+        await this.pruneCacheKeys(keysForRemoval)
+      },
+
       async reserveCache(key, version, totalSize) {
         logger.debug('Reserve:', { key, version })
 
@@ -97,6 +134,8 @@ export async function initializeStorage() {
           uploadId,
         })
 
+        this.pruneStaleCacheByType(key)
+
         return {
           cacheId: uploadId,
         }

routes/[token]/extra/clear_key_prefix.post.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+import { auth } from '~/lib/auth'
+import { useStorageAdapter } from '~/lib/storage'
+
+const bodySchema = z.object({
+  keyPrefix: z.string().min(1),
+})
+
+export default defineEventHandler({
+  onRequest: [auth],
+  handler: async (event) => {
+    const body = (await readBody(event)) as unknown
+    const parsedBody = bodySchema.safeParse(body)
+    if (!parsedBody.success)
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Invalid body: ${parsedBody.error.message}`,
+      })
+
+    const { keyPrefix } = parsedBody.data
+
+    await useStorageAdapter().pruneCacheByKeyPrefix(keyPrefix)
+  },
+})