[container]: add clean command

[saehejkang]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Closes #1763

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

[jglogan]

All looks good. I'm building locally to test. Only changes are to remove a probably-unneeded test and to ensure blocks are getting returned to the host OS.

[jglogan]

You could do a little white box testing at this point for both this test and for testCleanWithVolume:

• Use /dev/urandom as your input to ensure blocks get allocated. With /dev/zero the OS might optimize those writes.
• Run a sync command in the guest after line 100.
• Measure the number of allocated blocks in the block file on macOS after that.
• Run a sync command in the guest after the clean, just to be safe.
• Measure the number of allocated blocks after the clean, and assert that the number has decreased within some margin of error (say 80%) of the number of blocks that the dd command allocated.

[saehejkang]

Note: updates to the test were made with the help of AI

[jglogan]

Are you missing a new route in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper+Start.swift?

I see:

% container clean d027f0a1-dfae-4c04-8e66-3687d511593b
Warning! Running debug build. Performance may be degraded.
Error: internalError: "failed to clean container" (cause: "internalError: "failed to clean container d027f0a1-dfae-4c04-8e66-3687d511593b (cause: "interrupted: "XPC connection error: Connection interrupted"")"")
Ensure container system service has been started with `container system start`.

[jglogan]

@saehejkang It looks like the root fs gets cleaned but not a mounted named volume?

I'm testing your branch locally and doing this (the --cap-add is only so I can run fstrim):

container volume create scratch
container run -it --rm --name clean-test --cap-add ALL -v scratch:/mnt/data ubuntu:noble

Baseline measurement from the host shell:

du -sm ~/Library/Application\ Support/com.apple.container/containers/clean-test/rootfs.ext4
du -sm ~/Library/Application\ Support/com.apple.container/volumes/scratch/volume.img

In the container:

dd if=/dev/urandom of=/test.dat bs=65536 count=4096
dd if=/dev/urandom of=/mnt/data/test.dat bs=65536 count=4096
sync

The measured sizes of the files should be larger now.

Then, in the container:

rm /test.dat
rm /mnt/data/test.dat
sync

Measured sizes should not decrease yet.

From the host:

container clean clean-test

At this point the measured sizes should be close to the original (or less even, for the root volume).

What I'm seeing is that the root fs decreases but the volume does not. If I run fstrim in the container on the mount point I do see the decrease:

fstrim /mnt/data