{"id":18016546,"url":"https://github.com/webassembly/wasi-filesystem","last_synced_at":"2025-04-04T16:12:24.122Z","repository":{"id":38822119,"uuid":"261895262","full_name":"WebAssembly/wasi-filesystem","owner":"WebAssembly","description":"Filesystem API for WASI","archived":false,"fork":false,"pushed_at":"2025-04-03T18:05:04.000Z","size":1075,"stargazers_count":202,"open_issues_count":32,"forks_count":23,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-04T16:12:19.483Z","etag":null,"topics":["proposal","wasi"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebAssembly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-06T22:46:37.000Z","updated_at":"2025-04-04T03:43:16.000Z","dependencies_parsed_at":"2023-02-18T18:01:02.413Z","dependency_job_id":"845bc4eb-f73f-4c7d-9c60-af880afb91bb","html_url":"https://github.com/WebAssembly/wasi-filesystem","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-filesystem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-filesystem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-filesystem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-filesystem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebAssembly","download_url":"https://codeload.github.com/WebAssembly/wasi-filesystem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208142,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["proposal","wasi"],"created_at":"2024-10-30T04:18:26.465Z","updated_at":"2025-04-04T16:12:24.100Z","avatar_url":"https://github.com/WebAssembly.png","language":null,"readme":"# WASI filesystem\n\nA proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.\n\n### Current Phase\n\nWASI-filesystem is currently in [Phase 3].\n\n[Phase 3]: https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-3---implementation-phase-cg--wg\n\n### Champions\n\n- Dan Gohman\n\n### Portability Criteria\n\nWASI filesystem must have host implementations which can pass the testsuite\non at least Windows, macOS, and Linux.\n\nWASI filesystem must have at least two complete independent implementations.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Goals](#goals)\n- [Non-goals](#non-goals)\n- [API walk-through](#api-walk-through)\n  - [Use case 1](#use-case-1)\n  - [Use case 2](#use-case-2)\n- [Detailed design discussion](#detailed-design-discussion)\n  - [[Tricky design choice 1]](#tricky-design-choice-1)\n  - [[Tricky design choice 2]](#tricky-design-choice-2)\n- [Considered alternatives](#considered-alternatives)\n  - [[Alternative 1]](#alternative-1)\n  - [[Alternative 2]](#alternative-2)\n- [Stakeholder Interest \u0026 Feedback](#stakeholder-interest--feedback)\n- [References \u0026 acknowledgements](#references--acknowledgements)\n\n### Introduction\n\nWASI filesystem is a WASI API primarily for accessing host filesystems. It\nhas functions for opening, reading, and writing files, and for working with\ndirectories.\n\nUnlike many filesystem APIs, WASI filesystem is capability-oriented. Instead\nof having functions that implicitly reference a filesystem namespace,\nWASI filesystems' APIs are passed a directory handle along with a path, and\nthe path is looked up relative to the given handle, and sandboxed to be\nresolved within that directory. For more information about sandbox, see\n[WASI filesystem path resolution](path-resolution.md).\n\nWASI filesystem hides some of the surface differences between Windows and\nUnix-style filesystems, however much of its behavior, including the\nsemantics of path lookup, and the semantics of files, directories, and\nsymlinks, and the constraints on filesystem paths, is host-dependent.\n\nWASI filesystem is not intended to be used as a virtual API for accessing\narbitrary resources. Unix's \"everything is a file\" philosophy is in conflict\nwith the goals of supporting modularity and the principle of least authority.\n\nMany of the ideas related to doing capability-based filesystem sandboxing with\n`openat` come from [CloudABI](https://github.com/NuxiNL/cloudabi) and\n[Capsicum](https://wiki.freebsd.org/Capsicum).\n\n### Goals\n\nThe primary goal of WASI filesystem is to allow users to use WASI programs to\naccess their existing filesystems in a straightforward and efficient manner.\n\n### Non-goals\n\nWASI filesystem is not aiming for deterministic semantics. That would either\nrequire restricting it to fully controlled private filesystems, which would\nconflict with the goal of giving users access to their existing filesystems,\nor requiring implementations to do a lot of extra work to emulate specific\ndefined behaviors, which would conflict with the goal of being efficient.\n\n### API walk-through\n\n#### Opening a file\n\n```rust\n/// Write \"Hello, World\" into a file called \"greeting.txt\" in `dir`.\nfn write_hello_world_to_a_file(dir: Descriptor) -\u003e Result\u003c(), Errno\u003e {\n    let at_flags = AtFlags::FollowSymlinks;\n    let o_flags = OFlags::Create | OFlags::Trunc;\n    let descriptor_flags = DescriptorFlags::Write;\n    let mode = Mode::Readable;\n    let file =\n        dir.openat(at_flags, \"greeting.txt\", o_flags, descriptor_flags, mode)?;\n    let message = b\"Hello, World\\n\";\n    let mut view = \u0026message[..];\n    let mut offset = 0;\n    while !view.is_empty() {\n        let num_written = file.pwrite(view.to_owned(), 0)?;\n        offset += num_written;\n        view = \u0026view[num_written..];\n    }\n    // The file descriptor is closed when it's dropped!\n}\n```\n\nPerhaps the biggest change from the preview1 version of openat, called\n`path_open`, is the removal of the *rights* flags. Preview1 associates\na set of flags with every file descriptor enumerating which operations\nmay be performed on it, such as reading, writing, appending, truncating,\nand many other operations. In practice, this created a lot of ambiguity\nabout how it mapped to POSIX semantics, as it doesn't directly correspond\nto any feature in POSIX, or in Windows either.\n\nThe other major change from preview1 is the introduction of the mode\nargument, which controls the permissions of the generated file. There\nwas no way to control permissions in preview1, so this is new\nfunctionality.\n\n#### Streaming read from a file\n\nTODO\n\n#### Reading from a directory\n\nfn read_entries(dir: Descriptor) -\u003e Result\u003c(), Errno\u003e {\n    // TODO: Implement this example.\n}\n\n[etc.\n\n### Detailed design discussion\n\n#### Should WASI filesystem be case-sensitive, case-insensitive, or platform-dependent?\n\nEven just among popular platforms, there are case-sensitive and\ncase-insensitive filesystems in wide use.\n\nIt would be nice to have an API which presented consistent behavior across\nplatforms, so that applications don't have to worry about subtle differences,\nand subtle bugs due to those differences.\n\nHowever, implementing case sensitivity on a case-insensitive filesystem, or\ncase-insensitivity on a case-sensitive filesystem, are both tricky to do.\n\nOne issue is that case insensitivity depends on a Unicode version, so the\ndetails can differ between different case-insensitive platforms. Another\nissue is the WASI filesystem in general can't assume it has exclusive access\nto the filesystem, so approaches that involve checking for files with names\nthat differ only by case can race with other processes creating new files.\n\n### Considered alternatives\n\n#### Fully deterministic filesystem\n\nThe main tradeoff with full determinism is that it makes it difficult to access existing filesystems that the Wasm runtime doesn't have full control over. This proposal is aiming to address use cases where users have existing filesystems they want to access.\n\n### Stakeholder Interest \u0026 Feedback\n\nTODO before entering Phase 3.\n\nPreview1 has a similar filesystem API, and it's widely exposed in toolchains.\n\n### References \u0026 acknowledgements\n\nMany thanks for valuable feedback and advice from:\n\n- [Person 1]\n- [Person 2]\n- [etc.]\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-filesystem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebassembly%2Fwasi-filesystem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-filesystem/lists"}