diff --git a/index.bs b/index.bs index 881fb19..d381bb0 100644 --- a/index.bs +++ b/index.bs @@ -60,8 +60,60 @@ different storage mechanism with a different API for such files. The entry point ## Concepts ## {#concepts} +### File System ### {#concept-file-system} + +A file system is an [=implementation-defined=] +[=storage endpoint=] that maintains a mapping of [=file system path=]s to +[=file system entry|file system entries=]. + +Each [=/file system=] has an associated root, +an opaque [=string=] whose value is [=implementation-defined=]. + +A file system path is a [=/list=] of one or more [=strings=]. +This may be a virtual path that is mapped to real location on disk or in memory, +may correspond directly to a path on the local file system, or may not +correspond to any file on disk at all. The actual physical location of the +corresponding [=/file system entry=] is [=implementation-defined=]. + +A [=/file system path=] |a| is the same path as +a [=/file system path=] |b| if +|a|'s [=list/size=] is the same as |b|'s [=list/size=] and +[=list/for each=] |index| of |a|'s [=list/indices=] +|a|.\[[|index|]] is |b|.\[[|index|]]. + +
+Each [=/file system=] has an associated +locate an entry +algorithm, which takes [=/file system path=] |path| and runs an +[=implementation-defined=] series of steps returning a [=file system entry=] or null. +A non-null return value |entry| must adhere to these constraints: + +- [=file system/Getting the path=] with |entry| returns |path|, + provided no intermediate file system operations were run. +- |entry|'s [=file system entry/name=] is the last [=list/item=] of |path|. + +
+ +
+Each [=/file system=] has an associated +get the path +algorithm, which takes [=/file system entry=] |entry| and runs an +[=implementation-defined=] series of steps returning a [=file system path=]. The +return value |path| must adhere to these constraints: + +- [=file system/Locating an entry=] with |path| returns |entry|, + provided no intermediate file system operations were run. +- |entry|'s [=file system entry/name=] is the last [=list/item=] of |path|. + +
+ +### File System Entry ### {#concept-file-system-entry} + A file system entry is either a [=file entry=] or a [=directory entry=]. +Each [=/file system entry=] has an associated +file system (a [=/file system=]). + Each [=/file system entry=] has an associated query access algorithm, which takes "`read`" or "`readwrite`" mode and @@ -200,6 +252,41 @@ A [=/file system entry=] |a| is the same entry asfile system locator represents a potential location of a +[=/file system entry=]. A [=/file system locator=] is either a [=file locator=] +or a [=directory locator=]. + +Each [=/file system locator=] has an associated path (a [=/file system path=]), +a kind (a {{FileSystemHandleKind}}), and +a file system (a [=/file system=]). + +Issue(109): Consider giving each locator a [=storage bucket=]. + +A file locator is a [=/file system locator=] whose +[=file system locator/kind=] is "{{FileSystemHandleKind/file}}". +A directory locator is a [=/file system locator=] whose +[=file system locator/kind=] is "{{FileSystemHandleKind/directory}}". + +

For a [=/file system locator=] |locator| +whichs [=locate an entry|locates to=] a [=file entry=] |entry| that conceptually +exists at the path `data/drafts/example.txt` relative to the root directory of +a [=/bucket file system=], +|locator|'s [=file system locator/kind=] has to be "{{FileSystemHandleKind/file}}", +|locator|'s [=file system locator/path=] has to be « "`data`", "`drafts`", "`example.txt`" », and +|locator|'s [=file system locator/file system=] has to be [=/bucket file system=]. + +A [=/file system locator=] |a| is the same locator as +a [=/file system locator=] |b| if +|a|'s [=file system locator/kind=] is |b|'s [=file system locator/kind=], +|a|'s [=file system locator/file system=] is |b|'s [=file system locator/file system=], and +|a|'s [=file system locator/path=] is [=the same path as=] |b|'s [=file system locator/path=]. + +

Let |path| be the [=/list=] +« "`data`", "`drafts`", "`example.txt`" ». +There is no expectation that a file named `example.txt` exists anywhere on disk. +

To resolve a @@ -207,8 +294,8 @@ To resolve a 1. Let |result| be [=a new promise=]. 1. [=Enqueue the following steps=] to the [=file system queue=]: - 1. If |child|'s [=FileSystemHandle/locator=]'s [=file system locator/root=] - is not |root|'s [=FileSystemHandle/locator=]'s [=file system locator/root=], + 1. If |child|'s [=FileSystemHandle/locator=]'s [=file system locator/file system=] + is not |root|'s [=FileSystemHandle/locator=]'s [=file system locator/file system=], [=/resolve=] |result| with null, and abort these steps. 1. Let |childPath| be |child|'s [=FileSystemHandle/locator=]'s [=file system locator/path=]. @@ -234,85 +321,36 @@ To resolve a
-A file system locator represents a potential location of a -[=/file system entry=]. A [=/file system locator=] is either a [=file locator=] -or a [=directory locator=]. - -Each [=/file system locator=] has an associated path (a [=/file system path=]), -a kind (a {{FileSystemHandleKind}}), and -a root (a [=file system root=]). - -Issue(109): Consider giving each locator a [=storage bucket=]. - -A file locator is a [=/file system locator=] whose -[=file system locator/kind=] is "{{FileSystemHandleKind/file}}". -A directory locator is a [=/file system locator=] whose -[=file system locator/kind=] is "{{FileSystemHandleKind/directory}}". - -A file system root is an opaque [=string=] whose value is -[=implementation-defined=]. - -

For a [=/file system locator=] |locator| -whichs [=locate an entry|locates to=] a [=file entry=] |entry| that conceptually -exists at the path `data/drafts/example.txt` relative to the root directory of -a [=/bucket file system=], -|locator|'s [=file system locator/kind=] has to be "{{FileSystemHandleKind/file}}", -|locator|'s [=file system locator/path=] has to be « "`data`", "`drafts`", "`example.txt`" », and -|locator|'s [=file system locator/root=] might include relevant identifying -information such as the [=storage bucket=] and the disk drive. - -A [=/file system locator=] |a| is the same locator as -a [=/file system locator=] |b| if -|a|'s [=file system locator/kind=] is |b|'s [=file system locator/kind=], -|a|'s [=file system locator/root=] is |b|'s [=file system locator/root=], and -|a|'s [=file system locator/path=] is [=the same path as=] |b|'s [=file system locator/path=]. -

The locate an entry algorithm given a -[=/file system locator=] |locator| runs an [=implementation-defined=] series of steps adhering to -these constraints: +[=/file system locator=] |locator| runs the following steps: -- If |locator| is a [=file locator=], they return a [=file entry=] or null. -- If |locator| is a [=directory locator=], they return a [=directory entry=] or null. -- If these steps return a non-null |entry|, then: - - [=Getting the locator=] with |entry| returns |locator|, - provided no intermediate file system operations were run. - - |entry|'s [=file system entry/name=] is the last [=list/item=] of |locator|'s - [=file system locator/path=]. +1. Let |file system| be |locator|'s [=file system locator/file system=]. +1. Let |path| be |locator|'s [=file system locator/path=]. +1. Let |entry| be the result of running |file system|'s + [=file system/locate an entry=] given |path|. +1. If |entry| is null, return null. +1. If |locator| is a [=file locator=], [=Assert=]: |entry| is a [=file entry=]. +1. If |locator| is a [=directory locator=], [=Assert=]: |entry| is a [=directory entry=]. +1. Return |entry|.
-The get the locator algorithm given -[=/file system entry=] |entry| runs an [=implementation-defined=] series of steps adhering to these -constraints: - -- If |entry| is a [=file entry=], they return a [=file locator=]. -- If |entry| is a [=directory entry=], they return a [=directory locator=]. -- If these steps return |locator|, then: - - [=Locating an entry=] with |locator| returns |entry|, - provided no intermediate file system operations were run. - - |entry|'s [=file system entry/name=] is the last [=list/item=] of |locator|'s - [=file system locator/path=]. +The get the locator algorithm given a +[=/file system entry=] |entry| runs the following steps: + +1. Let |file system| be |entry|'s [=file system entry/file system=]. +1. Let |path| be the result of running |file system|'s + [=file system/get the path=] given |entry|. +1. Let |locator| be a [=file system locator=] whose [=file system locator/path=] + is |path| and whose [=file system locator/file system=] is |file system|. +1. If |entry| is a [=file entry=], set |locator|'s [=file system locator/kind=] to "file". +1. If |entry| is a [=directory entry=], set |locator|'s [=file system locator/kind=] to "directory". +1. Return |entry|.
-A file system path is a [=/list=] of one or more [=strings=]. -This may be a virtual path that is mapped to real location on disk or in memory, -may correspond directly to a path on the local file system, or may not -correspond to any file on disk at all. The actual physical location of the -corresponding [=/file system entry=] is [=implementation-defined=]. - -

Let |path| be the [=/list=] -« "`data`", "`drafts`", "`example.txt`" ». -There is no expectation that a file named `example.txt` exists anywhere on disk. - -A [=/file system path=] |a| is the same path as -a [=/file system path=] |b| if -|a|'s [=list/size=] is the same as |b|'s [=list/size=] and -[=list/for each=] |index| of |a|'s [=list/indices=] -|a|.\[[|index|]] is |b|.\[[|index|]]. -

The contents of a [=/file system locator=], including its [=file system locator/path=], are not expected to be shared in their entirety with the website process. The [=/file system path=] might contain components @@ -443,12 +481,12 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm= 1. Let |handle| be a [=new=] {{FileSystemFileHandle}} in |realm|. 1. Let |childType| be "{{FileSystemHandleKind/file}}". -1. Let |childRoot| be a copy of |parentLocator|'s [=file system locator/root=]. +1. Let |childFileSystem| be the |parentLocator|'s [=file system locator/file system=] 1. Let |childPath| be the result of [=list/clone|cloning=] |parentLocator|'s [=file system locator/path=] and [=list/append|appending=] |name|. 1. Set |handle|'s [=FileSystemHandle/locator=] to a [=/file system locator=] whose [=file system locator/kind=] is |childType|, - [=file system locator/root=] is |childRoot|, and + [=file system locator/file system=] is |childFileSystem|, and [=file system locator/path=] is |childPath|. 1. Return |handle|. @@ -457,13 +495,13 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm=

To create a new `FileSystemFileHandle` -given a [=/file system root=] |root| and a [=/file system path=] |path| +given a [=/file system=] |file system| and a [=/file system path=] |path| in a [=/Realm=] |realm|: 1. Let |handle| be a [=new=] {{FileSystemFileHandle}} in |realm|. 1. Set |handle|'s [=FileSystemHandle/locator=] to a [=/file system locator=] whose [=file system locator/kind=] is "{{FileSystemHandleKind/file}}", - [=file system locator/root=] is |root|, and + [=file system locator/file system=] is |file system|, and [=file system locator/path=] is |path|. 1. Return |handle|. @@ -698,12 +736,12 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm= 1. Let |handle| be a [=new=] {{FileSystemDirectoryHandle}} in |realm|. 1. Let |childType| be "{{FileSystemHandleKind/directory}}". -1. Let |childRoot| be a copy of |parentLocator|'s [=file system locator/root=]. +1. Let |childFileSystem| be the |parentLocator|'s [=file system locator/file system=]. 1. Let |childPath| be the result of [=list/clone|cloning=] |parentLocator|'s [=file system locator/path=] and [=list/append|appending=] |name|. 1. Set |handle|'s [=FileSystemHandle/locator=] to a [=/file system locator=] whose [=file system locator/kind=] is |childType|, - [=file system locator/root=] is |childRoot|, and + [=file system locator/file system=] is |childFileSystem|, and [=file system locator/path=] is |childPath|. 1. Return |handle|. @@ -712,13 +750,13 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm=
To create a new `FileSystemDirectoryHandle` -given a [=/file system root=] |root| and a [=/file system path=] |path| +given a [=/file system=] |file system| and a [=/file system path=] |path| in a [=/Realm=] |realm|: 1. Let |handle| be a [=new=] {{FileSystemDirectoryHandle}} in |realm|. 1. Set |handle|'s [=FileSystemHandle/locator=] to a [=/file system locator=] whose [=file system locator/kind=] is "{{FileSystemHandleKind/directory}}", - [=file system locator/root=] is |root|, and + [=file system locator/file system=] is |file system|, and [=file system locator/path=] is |path|. 1. Return |handle|. @@ -1675,12 +1713,17 @@ guarantee. # Accessing the Bucket File System # {#sandboxed-filesystem} -The bucket file system is a -[=storage endpoint=] whose -identifier is `"fileSystem"`, +The bucket file system +is a [=/file system=] implementation +whose [=file system/root=] is an [=implementation-defined=] opaque [=string=] +and whose [=storage endpoint=]'s +identifier of `"fileSystem"`, types are `« "local" »`, and quota is null. +Note: [=/bucket file system=]'s [=file system/root=] might include relevant +identifying information such as the [=storage bucket=]. + Issue: Storage endpoints should be defined in [[storage]] itself, rather than being defined here. So merge this into the table there. @@ -1721,13 +1764,10 @@ The getDirectory() 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 |file system| be [=/bucket file system=]'s [=/ile system/root=]. 1. Let |path| be « the empty string ». 1. Let |handle| be the result of creating a new `FileSystemDirectoryHandle`. - given |root| and |path| in the [=current realm=]. - - Note: |root| might include relevant identifying information such as the - [=storage bucket=]. + given |file system| and |path| in the [=current realm=]. 1. Assert: [=locating an entry=] given |handle|'s [=FileSystemHandle/locator=] returns a [=directory entry=] that is [=the same entry as=] |map|["root"].