Debian Codegraph @

wasi/p2/wit/deps/wasi-filesystem-0.2.0/package.wit

raw
1 package wasi:[email protected];
2
3 /// WASI filesystem is a filesystem API primarily intended to let users run WASI
4 /// programs that access their files on their existing filesystems, without
5 /// significant overhead.
6 ///
7 /// It is intended to be roughly portable between Unix-family platforms and
8 /// Windows, though it does not hide many of the major differences.
9 ///
10 /// Paths are passed as interface-type `string`s, meaning they must consist of
11 /// a sequence of Unicode Scalar Values (USVs). Some filesystems may contain
12 /// paths which are not accessible by this API.
13 ///
14 /// The directory separator in WASI is always the forward-slash (`/`).
15 ///
16 /// All paths in WASI are relative paths, and are interpreted relative to a
17 /// `descriptor` referring to a base directory. If a `path` argument to any WASI
18 /// function starts with `/`, or if any step of resolving a `path`, including
19 /// `..` and symbolic link steps, reaches a directory outside of the base
20 /// directory, or reaches a symlink to an absolute or rooted path in the
21 /// underlying filesystem, the function fails with `error-code::not-permitted`.
22 ///
23 /// For more information about WASI path resolution and sandboxing, see
24 /// [WASI filesystem path resolution].
25 ///
26 /// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md
27 interface types {
28 use wasi:io/[email protected].{input-stream, output-stream, error};
29 use wasi:clocks/[email protected].{datetime};
30
31 /// File size or length of a region within a file.
32 type filesize = u64;
33
34 /// The type of a filesystem object referenced by a descriptor.
35 ///
36 /// Note: This was called `filetype` in earlier versions of WASI.
37 enum descriptor-type {
38 /// The type of the descriptor or file is unknown or is different from
39 /// any of the other types specified.
40 unknown,
41 /// The descriptor refers to a block device inode.
42 block-device,
43 /// The descriptor refers to a character device inode.
44 character-device,
45 /// The descriptor refers to a directory inode.
46 directory,
47 /// The descriptor refers to a named pipe.
48 fifo,
49 /// The file refers to a symbolic link inode.
50 symbolic-link,
51 /// The descriptor refers to a regular file inode.
52 regular-file,
53 /// The descriptor refers to a socket.
54 socket,
55 }
56
57 /// Descriptor flags.
58 ///
59 /// Note: This was called `fdflags` in earlier versions of WASI.
60 flags descriptor-flags {
61 /// Read mode: Data can be read.
62 read,
63 /// Write mode: Data can be written to.
64 write,
65 /// Request that writes be performed according to synchronized I/O file
66 /// integrity completion. The data stored in the file and the file's
67 /// metadata are synchronized. This is similar to `O_SYNC` in POSIX.
68 ///
69 /// The precise semantics of this operation have not yet been defined for
70 /// WASI. At this time, it should be interpreted as a request, and not a
71 /// requirement.
72 file-integrity-sync,
73 /// Request that writes be performed according to synchronized I/O data
74 /// integrity completion. Only the data stored in the file is
75 /// synchronized. This is similar to `O_DSYNC` in POSIX.
76 ///
77 /// The precise semantics of this operation have not yet been defined for
78 /// WASI. At this time, it should be interpreted as a request, and not a
79 /// requirement.
80 data-integrity-sync,
81 /// Requests that reads be performed at the same level of integrety
82 /// requested for writes. This is similar to `O_RSYNC` in POSIX.
83 ///
84 /// The precise semantics of this operation have not yet been defined for
85 /// WASI. At this time, it should be interpreted as a request, and not a
86 /// requirement.
87 requested-write-sync,
88 /// Mutating directories mode: Directory contents may be mutated.
89 ///
90 /// When this flag is unset on a descriptor, operations using the
91 /// descriptor which would create, rename, delete, modify the data or
92 /// metadata of filesystem objects, or obtain another handle which
93 /// would permit any of those, shall fail with `error-code::read-only` if
94 /// they would otherwise succeed.
95 ///
96 /// This may only be set on directories.
97 mutate-directory,
98 }
99
100 /// Flags determining the method of how paths are resolved.
101 flags path-flags {
102 /// As long as the resolved path corresponds to a symbolic link, it is
103 /// expanded.
104 symlink-follow,
105 }
106
107 /// Open flags used by `open-at`.
108 flags open-flags {
109 /// Create file if it does not exist, similar to `O_CREAT` in POSIX.
110 create,
111 /// Fail if not a directory, similar to `O_DIRECTORY` in POSIX.
112 directory,
113 /// Fail if file already exists, similar to `O_EXCL` in POSIX.
114 exclusive,
115 /// Truncate file to size 0, similar to `O_TRUNC` in POSIX.
116 truncate,
117 }
118
119 /// Number of hard links to an inode.
120 type link-count = u64;
121
122 /// File attributes.
123 ///
124 /// Note: This was called `filestat` in earlier versions of WASI.
125 record descriptor-stat {
126 /// File type.
127 %type: descriptor-type,
128 /// Number of hard links to the file.
129 link-count: link-count,
130 /// For regular files, the file size in bytes. For symbolic links, the
131 /// length in bytes of the pathname contained in the symbolic link.
132 size: filesize,
133 /// Last data access timestamp.
134 ///
135 /// If the `option` is none, the platform doesn't maintain an access
136 /// timestamp for this file.
137 data-access-timestamp: option<datetime>,
138 /// Last data modification timestamp.
139 ///
140 /// If the `option` is none, the platform doesn't maintain a
141 /// modification timestamp for this file.
142 data-modification-timestamp: option<datetime>,
143 /// Last file status-change timestamp.
144 ///
145 /// If the `option` is none, the platform doesn't maintain a
146 /// status-change timestamp for this file.
147 status-change-timestamp: option<datetime>,
148 }
149
150 /// When setting a timestamp, this gives the value to set it to.
151 variant new-timestamp {
152 /// Leave the timestamp set to its previous value.
153 no-change,
154 /// Set the timestamp to the current time of the system clock associated
155 /// with the filesystem.
156 now,
157 /// Set the timestamp to the given value.
158 timestamp(datetime),
159 }
160
161 /// A directory entry.
162 record directory-entry {
163 /// The type of the file referred to by this directory entry.
164 %type: descriptor-type,
165 /// The name of the object.
166 name: string,
167 }
168
169 /// Error codes returned by functions, similar to `errno` in POSIX.
170 /// Not all of these error codes are returned by the functions provided by this
171 /// API; some are used in higher-level library layers, and others are provided
172 /// merely for alignment with POSIX.
173 enum error-code {
174 /// Permission denied, similar to `EACCES` in POSIX.
175 access,
176 /// Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX.
177 would-block,
178 /// Connection already in progress, similar to `EALREADY` in POSIX.
179 already,
180 /// Bad descriptor, similar to `EBADF` in POSIX.
181 bad-descriptor,
182 /// Device or resource busy, similar to `EBUSY` in POSIX.
183 busy,
184 /// Resource deadlock would occur, similar to `EDEADLK` in POSIX.
185 deadlock,
186 /// Storage quota exceeded, similar to `EDQUOT` in POSIX.
187 quota,
188 /// File exists, similar to `EEXIST` in POSIX.
189 exist,
190 /// File too large, similar to `EFBIG` in POSIX.
191 file-too-large,
192 /// Illegal byte sequence, similar to `EILSEQ` in POSIX.
193 illegal-byte-sequence,
194 /// Operation in progress, similar to `EINPROGRESS` in POSIX.
195 in-progress,
196 /// Interrupted function, similar to `EINTR` in POSIX.
197 interrupted,
198 /// Invalid argument, similar to `EINVAL` in POSIX.
199 invalid,
200 /// I/O error, similar to `EIO` in POSIX.
201 io,
202 /// Is a directory, similar to `EISDIR` in POSIX.
203 is-directory,
204 /// Too many levels of symbolic links, similar to `ELOOP` in POSIX.
205 loop,
206 /// Too many links, similar to `EMLINK` in POSIX.
207 too-many-links,
208 /// Message too large, similar to `EMSGSIZE` in POSIX.
209 message-size,
210 /// Filename too long, similar to `ENAMETOOLONG` in POSIX.
211 name-too-long,
212 /// No such device, similar to `ENODEV` in POSIX.
213 no-device,
214 /// No such file or directory, similar to `ENOENT` in POSIX.
215 no-entry,
216 /// No locks available, similar to `ENOLCK` in POSIX.
217 no-lock,
218 /// Not enough space, similar to `ENOMEM` in POSIX.
219 insufficient-memory,
220 /// No space left on device, similar to `ENOSPC` in POSIX.
221 insufficient-space,
222 /// Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX.
223 not-directory,
224 /// Directory not empty, similar to `ENOTEMPTY` in POSIX.
225 not-empty,
226 /// State not recoverable, similar to `ENOTRECOVERABLE` in POSIX.
227 not-recoverable,
228 /// Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX.
229 unsupported,
230 /// Inappropriate I/O control operation, similar to `ENOTTY` in POSIX.
231 no-tty,
232 /// No such device or address, similar to `ENXIO` in POSIX.
233 no-such-device,
234 /// Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX.
235 overflow,
236 /// Operation not permitted, similar to `EPERM` in POSIX.
237 not-permitted,
238 /// Broken pipe, similar to `EPIPE` in POSIX.
239 pipe,
240 /// Read-only file system, similar to `EROFS` in POSIX.
241 read-only,
242 /// Invalid seek, similar to `ESPIPE` in POSIX.
243 invalid-seek,
244 /// Text file busy, similar to `ETXTBSY` in POSIX.
245 text-file-busy,
246 /// Cross-device link, similar to `EXDEV` in POSIX.
247 cross-device,
248 }
249
250 /// File or memory access pattern advisory information.
251 enum advice {
252 /// The application has no advice to give on its behavior with respect
253 /// to the specified data.
254 normal,
255 /// The application expects to access the specified data sequentially
256 /// from lower offsets to higher offsets.
257 sequential,
258 /// The application expects to access the specified data in a random
259 /// order.
260 random,
261 /// The application expects to access the specified data in the near
262 /// future.
263 will-need,
264 /// The application expects that it will not access the specified data
265 /// in the near future.
266 dont-need,
267 /// The application expects to access the specified data once and then
268 /// not reuse it thereafter.
269 no-reuse,
270 }
271
272 /// A 128-bit hash value, split into parts because wasm doesn't have a
273 /// 128-bit integer type.
274 record metadata-hash-value {
275 /// 64 bits of a 128-bit hash value.
276 lower: u64,
277 /// Another 64 bits of a 128-bit hash value.
278 upper: u64,
279 }
280
281 /// A descriptor is a reference to a filesystem object, which may be a file,
282 /// directory, named pipe, special file, or other object on which filesystem
283 /// calls may be made.
284 resource descriptor {
285 /// Return a stream for reading from a file, if available.
286 ///
287 /// May fail with an error-code describing why the file cannot be read.
288 ///
289 /// Multiple read, write, and append streams may be active on the same open
290 /// file and they do not interfere with each other.
291 ///
292 /// Note: This allows using `read-stream`, which is similar to `read` in POSIX.
293 read-via-stream: func(offset: filesize) -> result<input-stream, error-code>;
294 /// Return a stream for writing to a file, if available.
295 ///
296 /// May fail with an error-code describing why the file cannot be written.
297 ///
298 /// Note: This allows using `write-stream`, which is similar to `write` in
299 /// POSIX.
300 write-via-stream: func(offset: filesize) -> result<output-stream, error-code>;
301 /// Return a stream for appending to a file, if available.
302 ///
303 /// May fail with an error-code describing why the file cannot be appended.
304 ///
305 /// Note: This allows using `write-stream`, which is similar to `write` with
306 /// `O_APPEND` in in POSIX.
307 append-via-stream: func() -> result<output-stream, error-code>;
308 /// Provide file advisory information on a descriptor.
309 ///
310 /// This is similar to `posix_fadvise` in POSIX.
311 advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
312 /// Synchronize the data of a file to disk.
313 ///
314 /// This function succeeds with no effect if the file descriptor is not
315 /// opened for writing.
316 ///
317 /// Note: This is similar to `fdatasync` in POSIX.
318 sync-data: func() -> result<_, error-code>;
319 /// Get flags associated with a descriptor.
320 ///
321 /// Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX.
322 ///
323 /// Note: This returns the value that was the `fs_flags` value returned
324 /// from `fdstat_get` in earlier versions of WASI.
325 get-flags: func() -> result<descriptor-flags, error-code>;
326 /// Get the dynamic type of a descriptor.
327 ///
328 /// Note: This returns the same value as the `type` field of the `fd-stat`
329 /// returned by `stat`, `stat-at` and similar.
330 ///
331 /// Note: This returns similar flags to the `st_mode & S_IFMT` value provided
332 /// by `fstat` in POSIX.
333 ///
334 /// Note: This returns the value that was the `fs_filetype` value returned
335 /// from `fdstat_get` in earlier versions of WASI.
336 get-type: func() -> result<descriptor-type, error-code>;
337 /// Adjust the size of an open file. If this increases the file's size, the
338 /// extra bytes are filled with zeros.
339 ///
340 /// Note: This was called `fd_filestat_set_size` in earlier versions of WASI.
341 set-size: func(size: filesize) -> result<_, error-code>;
342 /// Adjust the timestamps of an open file or directory.
343 ///
344 /// Note: This is similar to `futimens` in POSIX.
345 ///
346 /// Note: This was called `fd_filestat_set_times` in earlier versions of WASI.
347 set-times: func(data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>;
348 /// Read from a descriptor, without using and updating the descriptor's offset.
349 ///
350 /// This function returns a list of bytes containing the data that was
351 /// read, along with a bool which, when true, indicates that the end of the
352 /// file was reached. The returned list will contain up to `length` bytes; it
353 /// may return fewer than requested, if the end of the file is reached or
354 /// if the I/O operation is interrupted.
355 ///
356 /// In the future, this may change to return a `stream<u8, error-code>`.
357 ///
358 /// Note: This is similar to `pread` in POSIX.
359 read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
360 /// Write to a descriptor, without using and updating the descriptor's offset.
361 ///
362 /// It is valid to write past the end of a file; the file is extended to the
363 /// extent of the write, with bytes between the previous end and the start of
364 /// the write set to zero.
365 ///
366 /// In the future, this may change to take a `stream<u8, error-code>`.
367 ///
368 /// Note: This is similar to `pwrite` in POSIX.
369 write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
370 /// Read directory entries from a directory.
371 ///
372 /// On filesystems where directories contain entries referring to themselves
373 /// and their parents, often named `.` and `..` respectively, these entries
374 /// are omitted.
375 ///
376 /// This always returns a new stream which starts at the beginning of the
377 /// directory. Multiple streams may be active on the same directory, and they
378 /// do not interfere with each other.
379 read-directory: func() -> result<directory-entry-stream, error-code>;
380 /// Synchronize the data and metadata of a file to disk.
381 ///
382 /// This function succeeds with no effect if the file descriptor is not
383 /// opened for writing.
384 ///
385 /// Note: This is similar to `fsync` in POSIX.
386 sync: func() -> result<_, error-code>;
387 /// Create a directory.
388 ///
389 /// Note: This is similar to `mkdirat` in POSIX.
390 create-directory-at: func(path: string) -> result<_, error-code>;
391 /// Return the attributes of an open file or directory.
392 ///
393 /// Note: This is similar to `fstat` in POSIX, except that it does not return
394 /// device and inode information. For testing whether two descriptors refer to
395 /// the same underlying filesystem object, use `is-same-object`. To obtain
396 /// additional data that can be used do determine whether a file has been
397 /// modified, use `metadata-hash`.
398 ///
399 /// Note: This was called `fd_filestat_get` in earlier versions of WASI.
400 stat: func() -> result<descriptor-stat, error-code>;
401 /// Return the attributes of a file or directory.
402 ///
403 /// Note: This is similar to `fstatat` in POSIX, except that it does not
404 /// return device and inode information. See the `stat` description for a
405 /// discussion of alternatives.
406 ///
407 /// Note: This was called `path_filestat_get` in earlier versions of WASI.
408 stat-at: func(path-flags: path-flags, path: string) -> result<descriptor-stat, error-code>;
409 /// Adjust the timestamps of a file or directory.
410 ///
411 /// Note: This is similar to `utimensat` in POSIX.
412 ///
413 /// Note: This was called `path_filestat_set_times` in earlier versions of
414 /// WASI.
415 set-times-at: func(path-flags: path-flags, path: string, data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>;
416 /// Create a hard link.
417 ///
418 /// Note: This is similar to `linkat` in POSIX.
419 link-at: func(old-path-flags: path-flags, old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
420 /// Open a file or directory.
421 ///
422 /// The returned descriptor is not guaranteed to be the lowest-numbered
423 /// descriptor not currently open/ it is randomized to prevent applications
424 /// from depending on making assumptions about indexes, since this is
425 /// error-prone in multi-threaded contexts. The returned descriptor is
426 /// guaranteed to be less than 2**31.
427 ///
428 /// If `flags` contains `descriptor-flags::mutate-directory`, and the base
429 /// descriptor doesn't have `descriptor-flags::mutate-directory` set,
430 /// `open-at` fails with `error-code::read-only`.
431 ///
432 /// If `flags` contains `write` or `mutate-directory`, or `open-flags`
433 /// contains `truncate` or `create`, and the base descriptor doesn't have
434 /// `descriptor-flags::mutate-directory` set, `open-at` fails with
435 /// `error-code::read-only`.
436 ///
437 /// Note: This is similar to `openat` in POSIX.
438 open-at: func(path-flags: path-flags, path: string, open-flags: open-flags, %flags: descriptor-flags) -> result<descriptor, error-code>;
439 /// Read the contents of a symbolic link.
440 ///
441 /// If the contents contain an absolute or rooted path in the underlying
442 /// filesystem, this function fails with `error-code::not-permitted`.
443 ///
444 /// Note: This is similar to `readlinkat` in POSIX.
445 readlink-at: func(path: string) -> result<string, error-code>;
446 /// Remove a directory.
447 ///
448 /// Return `error-code::not-empty` if the directory is not empty.
449 ///
450 /// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
451 remove-directory-at: func(path: string) -> result<_, error-code>;
452 /// Rename a filesystem object.
453 ///
454 /// Note: This is similar to `renameat` in POSIX.
455 rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
456 /// Create a symbolic link (also known as a "symlink").
457 ///
458 /// If `old-path` starts with `/`, the function fails with
459 /// `error-code::not-permitted`.
460 ///
461 /// Note: This is similar to `symlinkat` in POSIX.
462 symlink-at: func(old-path: string, new-path: string) -> result<_, error-code>;
463 /// Unlink a filesystem object that is not a directory.
464 ///
465 /// Return `error-code::is-directory` if the path refers to a directory.
466 /// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
467 unlink-file-at: func(path: string) -> result<_, error-code>;
468 /// Test whether two descriptors refer to the same filesystem object.
469 ///
470 /// In POSIX, this corresponds to testing whether the two descriptors have the
471 /// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers.
472 /// wasi-filesystem does not expose device and inode numbers, so this function
473 /// may be used instead.
474 is-same-object: func(other: borrow<descriptor>) -> bool;
475 /// Return a hash of the metadata associated with a filesystem object referred
476 /// to by a descriptor.
477 ///
478 /// This returns a hash of the last-modification timestamp and file size, and
479 /// may also include the inode number, device number, birth timestamp, and
480 /// other metadata fields that may change when the file is modified or
481 /// replaced. It may also include a secret value chosen by the
482 /// implementation and not otherwise exposed.
483 ///
484 /// Implementations are encourated to provide the following properties:
485 ///
486 /// - If the file is not modified or replaced, the computed hash value should
487 /// usually not change.
488 /// - If the object is modified or replaced, the computed hash value should
489 /// usually change.
490 /// - The inputs to the hash should not be easily computable from the
491 /// computed hash.
492 ///
493 /// However, none of these is required.
494 metadata-hash: func() -> result<metadata-hash-value, error-code>;
495 /// Return a hash of the metadata associated with a filesystem object referred
496 /// to by a directory descriptor and a relative path.
497 ///
498 /// This performs the same hash computation as `metadata-hash`.
499 metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
500 }
501
502 /// A stream of directory entries.
503 resource directory-entry-stream {
504 /// Read a single directory entry from a `directory-entry-stream`.
505 read-directory-entry: func() -> result<option<directory-entry>, error-code>;
506 }
507
508 /// Attempts to extract a filesystem-related `error-code` from the stream
509 /// `error` provided.
510 ///
511 /// Stream operations which return `stream-error::last-operation-failed`
512 /// have a payload with more information about the operation that failed.
513 /// This payload can be passed through to this function to see if there's
514 /// filesystem-related information about the error to return.
515 ///
516 /// Note that this function is fallible because not all stream-related
517 /// errors are filesystem-related errors.
518 filesystem-error-code: func(err: borrow<error>) -> option<error-code>;
519 }
520
521 interface preopens {
522 use types.{descriptor};
523
524 /// Return the set of preopened directories, and their path.
525 get-directories: func() -> list<tuple<descriptor, string>>;
526 }
527
528 world imports {
529 import wasi:io/[email protected];
530 import wasi:io/[email protected];
531 import wasi:io/[email protected];
532 import wasi:clocks/[email protected];
533 import types;
534 import preopens;
535 }