This package manages a local file cache. The local file cache may be used, for example, to ensure that you have backups of files saved when making HTTP requests to API providers. The cached files can be used, for example, to quickly restore backups from the saved responses.

Project overview

The code in this module works on specific "application contexts" and "cache subdirectory paths".

The cache directory path is determined by joining three values together:

• The base directory path for the entire file cache (e.g. "/tmp").

  • This value can be modified in the runtime application config (i.e. in config/runtime.exs):
    • config :local_file_cacher, base_path: System.tmp_dir()

• The application context (e.g. YourProject.SomeApi)

• The cache subdirectory path (e.g. "some_endpoint")

Using the above examples, the cache directory path would be "/tmp/your_project/some_api/some_endpoint".

Using the file cache

This package has functions that can be used to:

• Save files to the configured directory path
• Prune old files from the configured directory path

To prevent your local file cache from getting too large, the functions used to prune the file cache could be invoked automatically by any code that saves files to the cache. By pruning the cache at the same time as files are saved to it, this ensures that the cache size will not grow to an unreasonable level over time.

Saving files to the cache

To save a file to the cache, call LocalFileCacher.save_file_to_cache/5 with the relevant parameters for the context in which you are working.

Pruning (deleting old) files from the cache

To prune a part of the file cache, call LocalFileCacher.prune_file_cache!/2 with the relevant parameters for the context in which you are working.

The number of days to keep a cached file/directory can be modified in the runtime application config (i.e. in config/runtime.exs). For example:

• config :local_file_cacher, days_to_keep_cached_files: 7

Application contexts

The application_context is a module that represents the context of the application you are working with.

Application context examples

• When working in the YourProject.SomeApi context, the application_context should be YourProject.SomeApi.

• When working in the YourProject.SomeApi.SomeCategory context, the application_context should be YourProject.SomeApi.SomeCategory.

Note that in the examples, the application context matches the value of the key in the config files that is used to configure that same context.

Cache subdirectory paths

A file_cache_subdirectory_path represents the subdirectory path of the file cache that is being used for the specific type of file being cached. Use a consistent naming strategy to ensure that files for each endpoint end up in their own subdirectory.

Cache subdirectory path examples

• SomeAPI's someEndpoint endpoint: The endpoint's relative URL path could be used as the file_cache_subdirectory_path: "some_endpoint"

• SomeAPI's someCategory/someEndpoint endpoint: The endpoint's relative URL path could be used as the file_cache_subdirectory_path, e.g. Path.join("some_category", "some_endpoint").

Cache subdirectory path style guide

• Use lowercase letters for all file paths. For example, in an endpoint called "Endpoint", prefer a cache subdirectory name of "endpoint" instead of "Endpoint".

• Separate multiple words with an underscore. For example, in an endpoint called "Some other endpoint", the cache subdirectory path should be called "some_other_endpoint".

• To ensure that path names are rendered correctly on all operating systems, use Path.join/1 if the cache subdirectory path is more than one layer deep. For example, for an endpoint located at "https://some-api.com/v1/someCategory/someEndpoint", prefer a cache subdirectory path of Path.join(["v1", "some_category", "some_endpoint"]) instead of "v1/someCategory/someEndpoint".