Feature Proposal: Automatic Package Cleanup – "Vacuum" Option in Aqua

[NikitaCOEUR]

I'd like to propose a new feature for Aqua called "Vacuum", which would automatically clean up unused packages or versions after N days of inactivity.

Feature Overview:

This feature would add a configurable option, such as vacuum: true or vacuum_days: N, in Aqua’s global configuration. Every time a command managed by Aqua is executed, the cleanup task would be triggered. The goal is to maintain a clean environment by automatically uninstalling packages and versions that haven’t been used for a specified period of time.

Example:

Let’s say I have three versions of the gh CLI installed via Aqua—version 1.0.0, version 1.2.0, and version 1.5.0. Each time I use a specific version of gh through Aqua, a timestamp (last usage) would be stored or updated. Each version of every package will have its own timestamp.

Version 1.0.0 might be used frequently, so its timestamp is updated regularly.

Version 1.2.0 might not have been used in a while.

Version 1.5.0 might have been installed but never used.

If the vacuum_days: 30 option is set, and version 1.2.0 hasn’t been used for 30 days, Aqua would automatically uninstall that version. If version 1.5.0 has never been used, it would also be cleaned up. However, version 1.0.0 would remain available because it is used regularly.

Configuration Option:

Here’s an example of how the configuration could look in Aqua’s global settings:

vacuum: true # (default: no)
vacuum_days: 30 # (default: 60)

This would enable the "Vacuum" feature and set the cleanup threshold to 30 days. Aqua would then perform the cleanup process whenever a command is executed.

Timestamp Storage Solution:

To keep track of installed packages and their last usage, Aqua can store a JSON or YAML file locally on the user’s machine (e.g., ~/.aqua/timestamps.json or ~/.aqua/timestamps.yaml). This file would record the installation time and last usage for each package and version.

Here’s an example structure of the file:

{
  "packages": {
    "gh": {
      "1.0.0": {
        "installed_at": "2024-09-01T12:00:00Z",
        "last_used_at": "2024-09-10T15:00:00Z"
      },
      "1.2.0": {
        "installed_at": "2024-09-05T12:00:00Z",
        "last_used_at": "2024-09-07T15:00:00Z"
      },
      "1.5.0": {
        "installed_at": "2024-09-12T08:00:00Z",
        "last_used_at": null
      }
    },
    "kubectl": {
      "1.23.0": {
        "installed_at": "2024-08-01T08:00:00Z",
        "last_used_at": "2024-09-05T12:00:00Z"
      }
    }
  }
}

installed_at: Records the installation timestamp of a package version. (Or nil if not known)

last_used_at: Updates whenever a package version is invoked. If null, it means the package hasn’t been used yet.

How It Works in Go:

When Aqua starts, it reads the timestamps.json (or .yaml) file from the configuration directory. If the file doesn’t exist, it initializes it.

When a package is installed or used, the respective installed_at or last_used_at fields are updated and saved back to the file.

During execution, Aqua checks the timestamps, and if a package version hasn’t been used for more than the specified vacuum_days, it will be automatically uninstalled.

Benefits:

Keeps your environment clean and lightweight by removing unused packages.

Minimizes manual maintenance by automatically handling old or unused package versions.

Regularly used packages are kept available as their timestamps are updated frequently.

---

This proposal introduces the Vacuum feature for automatic cleanup of packages, and the local JSON/YAML storage of timestamps ensures a lightweight and autonomous solution for managing package usage data on a single machine.

---

What do you think about it ?

[suzuki-shunsuke]

Thank you for your detailed proposal!
We can't work on this soon, but I think it's interesting.

Every time a command managed by Aqua is executed, the cleanup task would be triggered.

Executing commands managed by aqua should be fast, so we don't want to add the overhead as much as possible.
We can run the clean up task when commands such as aqua i are run (we can accept the overhead of aqua i to some extent compared with aqua exec), and we can also add the option like aqua rm -vacuum.

Here’s an example of how the configuration could look in Aqua’s global settings:

aqua has the concept of the global configuration file, but this is for installing tools globally and not for global settings.
Instead, we can add environment variables.

e.g.

export AQUA_VACUUM_DAYS=30

Timestamp Storage Solution:

Multiple commands managed by aqua may be executed in parallel, so if they write to the same text file such as ~/.aqua/timestamps.json at the same time, it may cause the trouble.
So we need to consider the solution.

1. Using database such as SQLite

AQUA_ROOT_DIR/
  metadata.sqlite3

2. Create a file per the pair of package and version

e.g.

AQUA_ROOT_DIR/
  metadata/
    github_release/github.com/cli/cli/v2.56.0/gh_2.56.0_macOS_arm64.zip/
      timestamp.json

[NikitaCOEUR]

Why not consider using https://github.com/etcd-io/bbolt to manage entries for this feature?

bbolt offers several advantages that make it an excellent fit for Aqua:

1. No External Dependencies: Being a pure Go library, bbolt doesn’t require external C libraries like SQLite, making it easier to integrate and deploy.

2. Concurrent-safe: It handles multiple readers and a single writer, allowing safe concurrent access, which is critical when managing package installations and updates.

3. Simplicity: It avoids the complexity of SQL syntax and schema management. You can directly store and retrieve Go structs, streamlining code complexity for Aqua's use case.

4. Performance: It's optimized for performance in scenarios involving small to medium-sized datasets, providing fast access and low overhead.

This makes bbolt a lightweight, efficient, and Go-native alternative that aligns well with Aqua's architecture and needs.