Repository navigation
Description
Context
With #1419, OpenCloud deletes old revisions (versions) of files according to a cleanup strategy (OC_REVISIONS_CLEANUP_STRATEGY), e.g. 30d deletes the revisions older than 30 days, and auto keeps fewer revisions the older they get. The cleanup also runs on demand with opencloud storage-users revisions cleanup.
Durations and the time slots of auto are compared with the age of each revision. There are two ways to define that age, and they lead to quite different results for files that are not changed often. This issue is meant to decide which one we want, before the cleanup is used widely.
Current behaviour: the time the content was written
Today, the age of a revision is the time its content was written, i.e. the modification time the file had before it was changed. When a file is changed, its previous content is turned into a revision, and that revision is named after the previous modification time of the file (<node id>.REV.<time>), which is also the date the version list shows for it. Revisions are never modified afterwards.
It is not the time the file was changed, which turned that content into a revision, i.e. when the content was replaced by a newer one. That time is not recorded anywhere today.
For files that change often, both times are close together. For files that stay unchanged for a long time, they are far apart:
- On August 14, a document is saved.
- Nobody touches it for two months.
- On October 14, it is changed. A revision is created to keep the previous content, dated August 14.
- The cleanup runs right after the change. The revision counts as 61 days old.
With a strategy that deletes by duration, e.g. 30d, auto, 30d or 7d, 30d, that revision is deleted right away, and the content the document had until that morning is gone. Strategies that keep a number of revisions (e.g. 5, 30d) or auto alone (one per week, however old) don't have this problem.
This is documented (in the README of the storage-users service and in the description of OC_REVISIONS_CLEANUP_STRATEGY), with the advice to combine durations with a number of revisions.
Alternative: the time the content was replaced
The age of a revision would be the time its content stopped being current, i.e. when the revision was created. In the example above, the revision would count as 0 days old on October 14, and 30d would keep it until November 13.
That arguably matches what users expect from "keep the versions of the last 30 days": being able to go back to any state the file had during the last 30 days.
What it would take:
- Record the creation time of every new revision as metadata, wherever revisions are created: uploads that replace a file (decomposed, decomposeds3, posix), restoring a revision, and with posix, revisions created from changes on disk (
enable_fs_revisions). - Existing revisions don't have it. A fallback is needed, e.g. the modification time of the next newer revision (the content that replaced it), or of the current file for the newest revision. That is only an approximation: modification times can come from clients.
- The reasons the cleanup gives for its decisions (in its log and in the output of the command) would say e.g. "replaced before …" instead of "older than …".
- The version list would still show the time the content was written. The cleanup would then sometimes keep a version that looks older than the configured duration; that needs to be explained in the documentation.
Related: revisions dated in the future
Modification times come from clients (X-OC-Mtime, wrong client clocks) or from changes on disk with posix (touch, restores, skewed clocks on network storage). So a revision can be dated in the future.
Today, such a revision counts as the newest one:
- it takes one of the first places of a number of revisions to keep, e.g. with
2, it can push out one of the actual 2 newest revisions; - no duration deletes it before its date has passed;
autokeeps it in a time slot in the future.
The cleanup logs a warning for every such revision and mentions it in its reason, but doesn't change its decision. Alternatives that were analysed and rejected:
- counting it as "now" (clamping) has no effect on numbers and durations, and makes
autodelete the actual current revision; - counting it as the oldest one trades one risk of losing data for another.
A creation time recorded by the server (the alternative above) would solve this as well, as it doesn't depend on the clocks of clients.
Questions for the team
- Which age should the cleanup use: the time the content of a revision was written (current), or the time it was replaced?
- If the time of replacement: is the fallback for existing revisions good enough, or should existing revisions keep the current behaviour (e.g. until they are gone)?
- Should the version list (and the API) show the time a version was replaced as well, so that what users see matches what the cleanup does?
- How should revisions dated in the future be handled, if we keep the time the content was written?
Notes
- The current behaviour and its limits are documented, so this is not blocking: admins can avoid the problem today by combining a duration with a number of revisions (e.g.
5, 30d) or by usingauto. - Recording the creation time is a change of its own in reva (both the decomposed and the posix trees), and should come with the change of the cleanup in one go, so that the cleanup never mixes both meanings for new revisions.
Metadata
Metadata
Assignees
Type
Projects
- StatusShow more project fieldsDone
Activity
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
butonic commentedon Oct 21, 2026
The current implementation is bug compatible with how oc10 named revisions. Which is arguably wrong. So I would mark this as a bug. Currently, all revisions have the original mtime in their filename, however, the mtime of the revision file should be the time the content was replaced ... unless we explicitly set the mtime manually in the code.
Merge as bug compatible, then fix? Because I'm not sure if we need a migration or if we can rely on the mtime of the revision.
5 remaining items
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
docs: 1419: explain how the age of a revision is measured
feat: 1419: clean up revisions by the time they were created
pbleser-oc commentedon Nov 18, 2026
An update: in his review of opencloud-eu/reva#895, @aduffeck pointed out that going by the content mtime isn't only surprising, but can be abused. Anyone who can write a file, including through a public link with edit rights, chooses that mtime with
X-OC-Mtime:auto, a revision dated one second after an existing one lands in the same slot and pushes that one out;5, 30d, so that every new version is deleted, also after the writer lost access to the file.So I've implemented the time of replacement, as a separate last commit in each of the three PRs: opencloud-eu/reva#895 (39a017723), #3778 (80091c1) and opencloud-eu/docs#1222 (81ccf73b). On the questions above:
CreateRevision(decomposed and posix) and the posix assimilation record it in a new attribute of the revision,user.oc.revision.created. The cleanup orders the revisions and measures their age by it.autonow keeps the oldest revision of each slot: it holds the content the file had when the slot began, while keeping the newest would drop a version that was current for months as soon as the file is saved twice within a slot.X-OC-Mtime. The docs explain that the cleanup goes by another date than the one the list shows, and the verbose output of the command shows the creation time.As this changes what
30dmeans, I'd like more opinions from the team before it's merged: the description of opencloud-eu/reva#895 asks not to merge it before that's decided. If we go with it, opencloud-eu/reva#895 fixes this issue; if not, the three commits are dropped and this issue stays open.aduffeck commentedon Nov 19, 2026
I vote for keeping the three commits. Besides closing the hole from the review, going by the time of replacement is the less confusing behaviour.
30dthen means what people read into it. Every state the file had during the last 30 days can be restored. With the content age, a document that was unchanged for two months loses its previous content the moment it is edited. Undoing the latest edit is the main reason to have versions at all, and nobody would expect30dto exclude it.30dchanges its meaning on running instances. Every revision created until then also has no recorded time and depends on the estimate for as long as it exists. Nobody uses the cleanup yet, so the change costs nothing now.On question 2, I think the estimate is the right approach, since old and new revisions then follow one rule.
pbleser-oc commentedon Nov 19, 2026
Thanks @aduffeck for the arguments. With @butonic's okay too, we go with the time of replacement: the age of a revision is the time it was created, recorded by the server, as implemented in the last commit of opencloud-eu/reva#895, #3778 and opencloud-eu/docs#1222. The three commits stay, and opencloud-eu/reva#895 now closes this issue when it is merged.
Showing the time a version was created in the version list, next to or instead of the date of its content, can come later, as a separate issue.
feat: 1419: clean up revisions by the time they were created
feat: 1419: clean up revisions by the time they were created