Allow extensions to access the configured directus cache

[stuikomma]

Summary

Extensions may benefit from using a cache for various reasons (caching, synchronization across instances (e.g. locking mechanisms)). However, accessing the default directus cache is not straightforward and requires reimplementing the getCache function.

Ideally, a preconfigured cache could be provided to extensions.

Basic Example

Caching

Simple endpoint that uses the cache to cache responses of an upstream API, but limits access to users who are logged in.

export default defineEndpoint((router, { logger, env, cache }) => {
  router.get('/data', async (req, res) => {
    if (!req.accountability.user) {
      res.status(401).send();
      return;
    }

    const search = req.query.search as string;

    const cachedResult = await cache?.get(search);
    if (cachedResult) {
      res.send(cachedResult);
      return;
    }

    const result = await myService.get(search);
    await cache.set(search, result);
    res.send(cachedResult);
  }
})

Locking

Hook extensions that triggers a long-running action.

export default ({ filter, action, cache }) => {
  filter('items.create', async (payload) => {
    if (await cache.get('runningAction')) {
      // not running actions in parallel
      return;
    }
    try {
      await cache.set('runningAction', true);
      await triggerLongRunningAction(payload);
    } finally {
      await cache.set('runningAction', false);
    }
  });
};

Motivation

Allowing caching in extensions using the interface that directus already provides. This makes the implementation for extension developers much easier, safer and incurs less overhead because we use existing libraries instead of bundling our own.

Detailed Design

Directus provides detailed configuration options for the cache. See https://docs.directus.io/self-hosted/config-options.html#cache.

The extensions cache could be configured the same way:

Variable	Description	Default Value
CACHE_<EXTENSION_NAME>_TTL	controls the TTL only for one extension	CACHE_TTL
CACHE_<EXTENSION_NAME>_NAMESPACE	controls the namespace of the extensions cache	<EXTENSION_TYPE>_<EXTENSION_NAME>

Namespacing the extensions cache will prevent a malicious/broken extension from tampering with directus' internal cache.

An implement for e.g. endpoint extensions could look like this:

	private registerEndpoint(config: EndpointConfig, name: string): PromiseCallback {
                //...
                const scopedCache = this.getCache(`endpoint_${name}`);

		endpointRegistrationCallback(scopedRouter, {
			services,
			env,
			database: getDatabase(),
			emitter: this.localEmitter,
			logger,
			getSchema,
                        cache: scopedCache,
		});
                //...
        }

        private getCache(name: string) {
          const ttl = getMilliseconds(env[`CACHE_${name}_TTL`] ?? env['CACHE_TTL']);
          return getKeyvInstance(env['CACHE_STORE'], ttl, name); // from https://github.com/directus/directus/blob/71236927d2fd3430bd546d8bc022d0d562aab2da/api/src/cache.ts#L50
        }

https://github.com/directus/directus/blob/71236927d2fd3430bd546d8bc022d0d562aab2da/api/src/extensions/manager.ts#L874C1-L881C6

The cache should be provided for these extensions types:

• endpoints
• hooks
• operations

Requirements List

Must Have:

• Cache is provided to extensions as a Keyv instance with a configured namespace
• Type declarations are updated with the new property

Should Have:

• Cache TTL is configurable

Could Have:

• Cache namespace is configurable

Won't Have:

Drawbacks

1. Slightly more complex initialization of extensions.
2. Slightly more complex configuration options. But these are optional and provide sane defaults.
3. The extension interface gets one more property. But this is self-explanatory and usage is optional.
4. A Keyv instance is created for all extensions, although most will not use it. I believe the cost of creating a keyv instance is negligible so there should be no noticeable performance penalty.

--> There are no changes required in existing extensions.

Alternatives

Developers can already roll their own implementation of getCache. This allows for full customization, but a solution provided by directus would be easier and safer to use. E.g. an extension with a custom caching implementation might inadvertently write into the system cache, or, worse, allow users to read from the cache without proper access control.

Adoption Strategy

This is entirely optional to use for extension developers.

The documentation should be updated so extension developers can learn about the new option to get hold of the cache.

Unresolved Questions

No response