Add the FileSystemObserver API #165

nathanmemmott · 2024-07-18T23:58:05Z

Add the FileSystemObserver API

Defines the FileSystemObserver API, an API to observe file system
change events.

At least two implementers are interested (and none opposed):
- Chrome
- Firefox
Tests are written and can be reviewed and commented upon at:
- …
Implementation bugs are filed:
- Chromium: https://crbug.com/320560741
- Gecko: …
- WebKit: …
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

Gives each concept in the concepts section its own section.

Pulls out some implementation-defined concepts into a file system concept. This is so that the file system concept can be extended further in the future.

index.bs

mkruisselbrink

It would be nice if we could somehow specify more precisely what exact change events are triggered by changes to the bucket file system, since that should be entirely under control of user agents, so should be possible to be fully compatible between implementations. Not sure how to be go about doing that. Left a bunch of other comments as well...

index.bs

nathanmemmott · 2024-11-01T00:05:12Z

The errors causing the build to fail were not introduced by this PR.

index.bs

mkruisselbrink · 2024-11-25T18:05:22Z

index.bs

@@ -1721,13 +2066,10 @@ The <dfn method for=StorageManager>getDirectory()</dfn> method steps are:
  1. Set |dir|'s [=directory entry/children=] to an empty [=/set=].
  1. Set |map|["root"] to |dir|.

-1. Let |root| be an [=implementation-defined=] opaque [=string=].
+1. Let |fileSystem| be [=/bucket file system=]'s [=file system/root=].


Somewhere in here fileSystem needs to be linked to a specific storage bottle for the correct storage bucket/origin. As written now it reads like there is one shared file system that all the storage buckets access. The old spec didn't really do this rigorously either, so it's probably okay to keep it a little bit hand-wavy (i.e. you might not need to go the whole way towards calling "obtain a local storage bottle map", and making it explicit that all the data for the file system is stored in the returned map), but we certainly don't want the spec to read like there is one "the bucket file system". Each storage bucket does need its own file system.

Let me know if the update makes sense.

index.bs

annevk · 2024-11-26T11:41:00Z

index.bs

+    Exposed=(DedicatedWorker,SharedWorker,Window),
+    SecureContext,
+    RuntimeEnabled=FileSystemObserver
+] interface FileSystemChangeRecord {


Is there a reason this is a class and not just a dictionary? I think in retrospect DOM's MutationRecord could have just been a dictionary as well. It's also not entirely clear to me why this has a constructor.

I asked the same question, and we had some offline discussion about this. The question of dictionary vs class seems to be the oldest open tag guidance request, but the most recent thinking in the issue thread there (w3ctag/design-principles#11 (comment)) seems to lean arguably in favor of using a class here, or at least not arguing against it (but that guidance certainly has changed a couple of times as the make-up of the tag has changed). I'm not sure what the latest thinking in this area is, and it would be nice if the TAG would actually write up something about this other than in that very long issue thread...

I'm not sure that accurately reflects the upthread discussion though with input from me and @domenic. In particular @domenic made the point there that for observer-related cases where it's just about data a dictionary would be more idiomatic. Having both a class and a constructor for it that takes a dictionary seems quite bloated.

Per https://groups.google.com/a/chromium.org/g/blink-dev/c/6oOaFmia2dc/m/gx0KgpQqBQAJ, the latest plan seems to be to use a dictionary, especially since that is easier to upgrade to an interface later. I think that's a good plan, and updating the spec PR to match that would be good.

Switched to dictionary.

youennf · 2024-11-26T13:22:34Z

index.bs

+);
+
+[
+    Exposed=(DedicatedWorker,SharedWorker,Window),


Why not (Worker, Window), FileSystemHandle is probably exposed in service worker contexts too?

A separate API would be needed for service workers. The service worker becomes inactive after 30 seconds of no events. The change events received in the FileSystemObserver callback would not count as a service worker event. There are also privacy considerations around allowing a site to observe file changes without the user being aware.

index.bs

youennf · 2024-11-26T13:25:27Z

index.bs

+  "errored",
+  "modified",
+  "moved",
+  "unknown",


I am not sure when errored and unknown would happen.
I guess errored could happen if unmounting a disk for instance.
I have no clue for unknown.
If we do not have a good usecase, should we remove from the initial PR?
Giving a description explaining what these values are might be nice.

Added definitions for each with examples.

youennf · 2024-11-26T13:27:00Z

index.bs

+  "appeared",
+  "disappeared",
+  "errored",
+  "modified",


What is modified meaning?
If only touching the file, will it trigger a FileSystemChange?
If so, I would guess that this could trigger events where no information for the web page has changed (IIRC, access/modification dates are not exposed).
Or maybe it is restricted to changes in the content itself?

Ideally this would only be content changes but we have limited information from the OS APIs so we cannot always filter out metadata changes. There will be some noisiness that a user agent can attempt to filter.

youennf · 2024-11-26T13:28:09Z

index.bs

+
+<xmp class=idl>
+dictionary FileSystemObserverObserveOptions {
+  boolean recursive = false;


If a folder being observed is removed, which callback will be called?
One for the folder, or one per each file in the folder, or depending on the OS?

For each observer, there is only one callback. Each observer registration always has their root as the handle that was passed to observe().

A folder may be moved to a recycling bin or deleted permanently. When moved to the recycling bin, this is interpreted as a move out of scope, so will be reported as one "disappeared" on the folder. When permanently deleted, the OS must delete its descendants recursively before deleting the folder. So a "disappeared" event for each descendant will be reported.

youennf · 2024-11-26T13:37:57Z

index.bs

+  "disappeared",
+  "errored",
+  "modified",
+  "moved",


Is moved also covering rename change?

nathanmemmott · 2024-12-19T01:16:33Z

The latest patch adds some logic that we decided on recently. We no longer send the changed handle for "disappeared", "errored", and "unknown".

nathanmemmott · 2024-12-19T18:54:01Z

@annevk @mkruisselbrink @domenic @youennf PTAL again and let me know if this is ready to merge.

@asutherland I don't have permission to add you but please take a look. If someone does have permission, please add him.

Defines the FileSystemObserver API, an API to observe file system change events. See whatwg#123 and WICG/file-system-access#72

mkruisselbrink · 2025-01-06T18:52:09Z

This looks good to me, but it would be good to get at least one other person to sign off on this before merging.

Nathan Memmott and others added 4 commits July 3, 2024 11:48

Editorial: Add sections to Concepts section

61181a1

Gives each concept in the concepts section its own section.

Define File System concept

0440eca

Pulls out some implementation-defined concepts into a file system concept. This is so that the file system concept can be extended further in the future.

Merge branch 'whatwg:main' into define_file_system_concept

f1c7d6f

Define File System concept

69cf44b

Pulls out some implementation-defined concepts into a file system concept. This is so that the file system concept can be extended further in the future.

nathanmemmott changed the title ~~File system observer~~ Add the FileSystemObserver API Jul 19, 2024

nathanmemmott force-pushed the file_system_observer branch from 320d58a to 8047a41 Compare July 19, 2024 16:10

TomokiMiyauci reviewed Aug 19, 2024

View reviewed changes

index.bs Outdated Show resolved Hide resolved

mkruisselbrink reviewed Sep 11, 2024

View reviewed changes

nathanmemmott force-pushed the file_system_observer branch 4 times, most recently from 86ed1e4 to 42a22b9 Compare October 31, 2024 23:54

nathanmemmott force-pushed the file_system_observer branch from 42a22b9 to eb658ba Compare November 20, 2024 00:23

mkruisselbrink reviewed Nov 25, 2024

View reviewed changes

nathanmemmott force-pushed the file_system_observer branch from eb658ba to e7defaa Compare November 25, 2024 20:19

annevk reviewed Nov 26, 2024

View reviewed changes

youennf reviewed Nov 26, 2024

View reviewed changes

nathanmemmott force-pushed the file_system_observer branch from e7defaa to 9ad0813 Compare November 26, 2024 18:34

dslee414 mentioned this pull request Dec 9, 2024

The FileSystemObserver interface w3ctag/design-reviews#868

Closed

1 task

nathanmemmott force-pushed the file_system_observer branch from 9ad0813 to a8d2908 Compare December 19, 2024 01:12

Add the FileSystemObserver API

00b692c

Defines the FileSystemObserver API, an API to observe file system change events. See whatwg#123 and WICG/file-system-access#72

nathanmemmott force-pushed the file_system_observer branch from a8d2908 to 00b692c Compare December 19, 2024 19:02

mkruisselbrink approved these changes Jan 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add the FileSystemObserver API #165

Add the FileSystemObserver API #165

nathanmemmott commented Jul 18, 2024 •

edited by pr-preview bot

Loading

mkruisselbrink left a comment

nathanmemmott commented Nov 1, 2024

mkruisselbrink Nov 25, 2024

nathanmemmott Nov 25, 2024

annevk Nov 26, 2024

mkruisselbrink Nov 26, 2024

annevk Nov 27, 2024

domenic Dec 18, 2024

nathanmemmott Dec 19, 2024 •

edited

Loading

youennf Nov 26, 2024

nathanmemmott Nov 26, 2024

youennf Nov 26, 2024

nathanmemmott Nov 26, 2024

youennf Nov 26, 2024

nathanmemmott Nov 26, 2024

youennf Nov 26, 2024

nathanmemmott Nov 26, 2024

youennf Nov 26, 2024

nathanmemmott Nov 26, 2024

nathanmemmott commented Dec 19, 2024

nathanmemmott commented Dec 19, 2024

mkruisselbrink commented Jan 6, 2025

Add the FileSystemObserver API #165

Are you sure you want to change the base?

Add the FileSystemObserver API #165

Conversation

nathanmemmott commented Jul 18, 2024 • edited by pr-preview bot Loading

mkruisselbrink left a comment

Choose a reason for hiding this comment

nathanmemmott commented Nov 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathanmemmott Dec 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathanmemmott commented Dec 19, 2024

nathanmemmott commented Dec 19, 2024

mkruisselbrink commented Jan 6, 2025

nathanmemmott commented Jul 18, 2024 •

edited by pr-preview bot

Loading

nathanmemmott Dec 19, 2024 •

edited

Loading