Skip to content

Commit

Permalink
Define File System concept
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
Nathan Memmott committed Jun 28, 2024
1 parent b38f13b commit 8a481aa
Showing 1 changed file with 127 additions and 87 deletions.
214 changes: 127 additions & 87 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <dfn export>file system</dfn> 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 <dfn for="file system" export>root</dfn>,
an opaque [=string=] whose value is [=implementation-defined=].

A <dfn export>file system path</dfn> 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 <dfn for="file system path">the same path as</dfn>
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|]].

<div algorithm>
Each [=/file system=] has an associated
<dfn for="file system">locate an entry</dfn>
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|.

</div>

<div algorithm>
Each [=/file system=] has an associated
<dfn for="file system">get the path</dfn>
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|.

</div>

### File System Entry ### {#concept-file-system-entry}

A <dfn export id="entry">file system entry</dfn> is either a [=file entry=] or a [=directory entry=].

Each [=/file system entry=] has an associated
<dfn for="file system entry">file system</dfn> (a [=/file system=]).

Each [=/file system entry=] has an associated
<dfn for="file system entry" id=entry-query-access>query access</dfn>
algorithm, which takes "`read`" or "`readwrite`" <var ignore>mode</var> and
Expand Down Expand Up @@ -200,15 +252,50 @@ A [=/file system entry=] |a| is <dfn for="file system entry">the same entry as</
a [=/file system entry=] |b| if |a| is equal to |b|, or
if |a| and |b| are backed by the same file or directory on the local file system.

### File System Locator ### {#concept-file-system-locator}

A <dfn export>file system locator</dfn> 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 <dfn export for="file system locator" id=locator-path>path</dfn> (a [=/file system path=]),
a <dfn export for="file system locator" id=locator-kind>kind</dfn> (a {{FileSystemHandleKind}}), and
a <dfn export for="file system locator" id=locator-root>file system</dfn> (a [=/file system=]).

Issue(109): Consider giving each locator a [=storage bucket=].

A <dfn export>file locator</dfn> is a [=/file system locator=] whose
[=file system locator/kind=] is "{{FileSystemHandleKind/file}}".
A <dfn export>directory locator</dfn> is a [=/file system locator=] whose
[=file system locator/kind=] is "{{FileSystemHandleKind/directory}}".

<p class=example id=example-locator>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 <dfn for="file system locator">the same locator as</dfn>
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=].

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

<div algorithm>

To <dfn for="file system locator" id=locator-resolve>resolve</dfn> a
[=/file system locator=] |child| relative to a [=directory locator=] |root|:

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=].
Expand All @@ -234,85 +321,36 @@ To <dfn for="file system locator" id=locator-resolve>resolve</dfn> a

</div>

A <dfn export>file system locator</dfn> 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 <dfn export for="file system locator" id=locator-path>path</dfn> (a [=/file system path=]),
a <dfn export for="file system locator" id=locator-kind>kind</dfn> (a {{FileSystemHandleKind}}), and
a <dfn export for="file system locator" id=locator-root>root</dfn> (a [=file system root=]).

Issue(109): Consider giving each locator a [=storage bucket=].

A <dfn export>file locator</dfn> is a [=/file system locator=] whose
[=file system locator/kind=] is "{{FileSystemHandleKind/file}}".
A <dfn export>directory locator</dfn> is a [=/file system locator=] whose
[=file system locator/kind=] is "{{FileSystemHandleKind/directory}}".

A <dfn export>file system root</dfn> is an opaque [=string=] whose value is
[=implementation-defined=].

<p class=example id=example-locator>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 <dfn for="file system locator">the same locator as</dfn>
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=].

<div algorithm>
The <dfn export data-lt="locating an entry">locate an entry</dfn> 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|.

</div>

<div algorithm>
The <dfn export data-lt="getting the locator">get the locator</dfn> 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 <dfn export data-lt="getting the locator">get the locator</dfn> 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|.

</div>

A <dfn export>file system path</dfn> 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=].

<p class=example id=example-path>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 <dfn for="file system path">the same path as</dfn>
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|]].

<p class=warning> 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
Expand Down Expand Up @@ -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|.

Expand All @@ -457,13 +495,13 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm=
<div algorithm>
To
<dfn export data-lt="creating a new FileSystemFileHandle">create a new `FileSystemFileHandle`</dfn>
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|.

Expand Down Expand Up @@ -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|.

Expand All @@ -712,13 +750,13 @@ given a [=directory locator=] |parentLocator| and a string |name| in a [=/Realm=
<div algorithm>
To
<dfn export data-lt="creating a new FileSystemDirectoryHandle">create a new `FileSystemDirectoryHandle`</dfn>
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|.

Expand Down Expand Up @@ -1675,12 +1713,17 @@ guarantee.

# Accessing the Bucket File System # {#sandboxed-filesystem}

The <dfn export id=origin-private-file-system>bucket file system</dfn> is a
[=storage endpoint=] whose
<a spec=storage for="storage endpoint">identifier</a> is `"fileSystem"`,
The <dfn export id=origin-private-file-system>bucket file system</dfn>
is a [=/file system=] implementation
whose [=file system/root=] is an [=implementation-defined=] opaque [=string=]
and whose [=storage endpoint=]'s
<a spec=storage for="storage endpoint">identifier</a> of `"fileSystem"`,
<a spec=storage for="storage endpoint">types</a> are `« "local" »`,
and <a spec=storage for="storage endpoint">quota</a> 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.

Expand Down Expand Up @@ -1721,13 +1764,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 |file system| be [=/bucket file system=]'s [=/ile system/root=].
1. Let |path| be « the empty string ».
1. Let |handle| be the result of <a>creating a new `FileSystemDirectoryHandle`</a>.
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"].
Expand Down

0 comments on commit 8a481aa

Please sign in to comment.