Description
docs/04_filesystem_interface.md says that symbolic links are an internal implementation detail and that Workspace.fs does not expose symlink or readlink. It also says there is no public lstat method and no way to change the mode of an existing file.
The shipped API does not match those statements. WorkspaceFilesystem publicly exposes symlink, readlink, lstat and chmod. WorkspaceFilesystemStub mirrors those methods across the Workers RPC boundary and the Dynamic Worker filesystem adapters use them to provide the supported node:fs behavior.
This makes the filesystem specification misleading for callers and maintainers. The implementation history and current consumers indicate that the methods are intentionally public, so the documentation should describe the shipped API. Removing the methods instead would be a breaking API change and would require updates to the Worker runtime adapters.
Expected outcome
- Add
symlink, readlink, lstat and chmod to the documented Workspace.fs API.
- Document the relevant return values and errors, including
ENOENT, EINVAL and ELOOP.
- Update the comparison with
node:fs/promises and remove the statement that symbolic links are internal only.
- Explain that
stat follows a trailing symbolic link while lstat reports the link itself.
Description
docs/04_filesystem_interface.mdsays that symbolic links are an internal implementation detail and thatWorkspace.fsdoes not exposesymlinkorreadlink. It also says there is no publiclstatmethod and no way to change the mode of an existing file.The shipped API does not match those statements.
WorkspaceFilesystempublicly exposessymlink,readlink,lstatandchmod.WorkspaceFilesystemStubmirrors those methods across the Workers RPC boundary and the Dynamic Worker filesystem adapters use them to provide the supportednode:fsbehavior.This makes the filesystem specification misleading for callers and maintainers. The implementation history and current consumers indicate that the methods are intentionally public, so the documentation should describe the shipped API. Removing the methods instead would be a breaking API change and would require updates to the Worker runtime adapters.
Expected outcome
symlink,readlink,lstatandchmodto the documentedWorkspace.fsAPI.ENOENT,EINVALandELOOP.node:fs/promisesand remove the statement that symbolic links are internal only.statfollows a trailing symbolic link whilelstatreports the link itself.