Archives/falk-werner_webfuse
1
0
Fork 0
mirror of https://github.com/falk-werner/webfuse synced 2024-10-27 20:34:10 +00:00
Code Issues Releases Wiki Activity

add some documentation

Browse Source
This commit is contained in:
Falk Werner 2023-01-07 11:07:16 +01:00
parent 50e1ec8f5c
commit b9c0f769d8
1 changed files with 204 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
doc/protocol.md
View File

@ -277,16 +277,20 @@ _Note that the following numbers are in `hexadecimal` notation._
## Methods ## Methods
Since `webfuse2` aims to communicate the `libfuse API` over a `websocket` connection, `webfuse2` methods are tightly connected to [fuse operations](https://libfuse.github.io/doxygen/structfuse__operations.html) which itself have a tight connection to `posix filesystem operations`. Therefore, additional information about most `webfuse2` operations can be found in the [fuse operations documentation](https://libfuse.github.io/doxygen/structfuse__operations.html) and / or the [man pages](https://man7.org/index.html).
### access ### access
Checks the user's permissions for a file (see [man access(2)](https://man7.org/linux/man-pages/man2/access.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ----- | ---------------- | ----------- | | ----- | ---------------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x01) | | type | u8 | message type (0x01) |
| path | string | | | path | string | path of file to check |
| mode | access_mode (i8) | | mode | access_mode (i8) | access mode to check |
#### Response #### Response
@ -298,258 +302,337 @@ _Note that the following numbers are in `hexadecimal` notation._
### getattr ### getattr
Retrieve file attributes (see [man getattr(2)](https://man7.org/linux/man-pages/man2/getxattr.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x02) |
| path | string | path |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | --------- | ---------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x82) |
| result | result | operation status | | result | result | operation status |
| attibutes | attributes | attributes of file |
### readlink ### readlink
Read value of a symbolik link (see [man readlink(2)](https://man7.org/linux/man-pages/man2/readlink.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x03) |
| path | string | path of link |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | -------- | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x83) |
| result | result | operation status | | result | result | operation status |
| resolved | string | resolved path |
### symlink ### symlink
Make a new name of a file (see [man symlink(2)](https://man7.org/linux/man-pages/man2/symlink.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | -------- | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x04) |
| target | string | target of link |
| linkpath | string | name of the link |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x84) |
| result | result | operation status | | result | result | operation status |
### link ### link
Make a new name for a file (see [man link(2)](https://man7.org/linux/man-pages/man2/link.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | -------- | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x05) |
| old_path | string | path of the existing file |
| new_path | string | new name of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x85) |
| result | result | operation status | | result | result | operation status |
### rename ### rename
Change the name of a file (see [man rename(2)](https://man7.org/linux/man-pages/man2/rename.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | -------- | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x06) |
| old_path | string | old name of the file |
| new_path | string | new name of the file |
| flags | rename_flags (u8) | flags to control the rename operation |
The following `flags` are defined:
- **0x00:** move the file from `old_path` to `new_path`
- **0x01 (RENAME_NOREPLACE):** do not override `new_path`
This results in an error, when `new_path` already exists.
- **0x02 (RENAME_EXCHANGE):** atomically exchange the files
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x86) |
| result | result | operation status | | result | result | operation status |
### chmod ### chmod
Change permissions of a file (see [man chmod(2)](https://man7.org/linux/man-pages/man2/chmod.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | ---------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x07) |
| path | string | path of the file |
| mode | mode (u32) | new file permissions |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x87) |
| result | result | operation status | | result | result | operation status |
### chown ### chown
Change ownership of a file (see [man chown(2)](https://man7.org/linux/man-pages/man2/chown.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x08) |
| path | string | path of the file |
| uid | uid (u32) | user id of the new owner |
| gid | gid (u32) | group id of the new owning group |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x88) |
| result | result | operation status | | result | result | operation status |
### truncate ### truncate
Truncate a file to a specified length (see [man truncate(2)](https://man7.org/linux/man-pages/man2/truncate64.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | ------------ | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x09) |
| path | string | path of the file |
| size | u64 | new file size |
| handle | handle (u64) | handle of the file |
_Note that handle might be invalid (-1), even if the file is open._
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x89) |
| result | result | operation status | | result | result | operation status |
### fsync ### fsync
Sychronize a file's in-core state with storage device (see [man fsync(2)](https://man7.org/linux/man-pages/man2/fsync.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0a) |
| path | string | path of the file |
| is_datasync | bool | if true, sync only user data |
| handle | handle (u64) | handle of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8a) |
| result | result | operation status | | result | result | operation status |
### open ### open
Open and possibly create a file ([man open(2)](https://man7.org/linux/man-pages/man2/open.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0b) |
| path | string | path of the file |
| flags | open_flags (i32) | flags |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8b) |
| result | result | operation status | | result | result | operation status |
| handle | handle (u64) | handle of the file |
### mknod ### mknod
Create a special or ordinary file (see [man mknod(2)](https://man7.org/linux/man-pages/man2/mknod.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0c) |
| path | string | path of the file |
| mode | mode (u32) | mode of the file |
| dev | dev (64) | device type |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8c) |
| result | result | operation status | | result | result | operation status |
### create ### create
Create a new file or rewrite an existing one (see [man creat(3p)](https://man7.org/linux/man-pages/man3/creat.3p.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0d) |
| path | string | path of the file |
| mode | mode (u32) | mode of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8d) |
| result | result | operation status | | result | result | operation status |
| handle | handle (u64) | handle of the file |
### release ### release
Releases a file handle (see [man close(2)](https://man7.org/linux/man-pages/man2/close.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0e) |
| path | string | path of the file |
| handle | handle (u64) | handle of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8e) |
| result | result | operation status | | result | result | operation status |
### unlink ### unlink
Delete a name and possibly the file it refers to ([man unlink(2)](https://man7.org/linux/man-pages/man2/unlink.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x0f) |
| path | string | path of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x8f) |
| result | result | operation status | | result | result | operation status |
### read ### read
Read from a file description (see [man read(2)](https://man7.org/linux/man-pages/man2/read.2.html), [man pread(2)](https://man7.org/linux/man-pages/man2/pread.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x10) |
| path | string | path of the file |
| buffer_size | u32 | max. amount of bytes requested |
| offset | u64 | offset of the file |
| handle | handle (u64) | handle of the file |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x90) |
| result | result | operation status | | result | result | operation status |
| data | bytes | requested data |
### write ### write
@ -558,14 +641,14 @@ _Note that the following numbers are in `hexadecimal` notation._
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x17) |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x91) |
| result | result | operation status | | result | result | operation status |
### mkdir ### mkdir
@ -575,14 +658,14 @@ _Note that the following numbers are in `hexadecimal` notation._
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x12) |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x92) |
| result | result | operation status | | result | result | operation status |
### readdir ### readdir
@ -592,14 +675,14 @@ _Note that the following numbers are in `hexadecimal` notation._
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x13) |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x93) |
| result | result | operation status | | result | result | operation status |
### rmdir ### rmdir
@ -609,14 +692,14 @@ _Note that the following numbers are in `hexadecimal` notation._
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x14) |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x94) |
| result | result | operation status | | result | result | operation status |
### statfs ### statfs
@ -626,29 +709,82 @@ _Note that the following numbers are in `hexadecimal` notation._
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x15) |
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x95) |
| result | result | operation status | | result | result | operation status |
### utimens ### utimens
Change the file timestamps with nanosecond precision ([man utimesat(2)](https://man7.org/linux/man-pages/man2/utimensat.2.html)).
#### Request #### Request
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x16) |
| path | string | path of the file |
| atime | timestamp | new last access time |
| mtime | timestamp | new last modified time |
| handle | handle (u64) | handle of the file |
_Note that handle might be invalid (-1), even if the file is open._
#### Response #### Response
| Field | Data Type | Description | | Field | Data Type | Description |
| ------ | --------- | ----------- | | ------ | --------- | ----------- |
| id | u32 | message id | | id | u32 | message id |
| type | u8 | message type (0x81) | | type | u8 | message type (0x96) |
| result | result | operation status | | result | result | operation status |
## Examples
### Get file attributes
````
service -> provider:
00 00 00 01 # message id = 1
02 # message type = getattr request
01 '/' # path = "/"
provider -> service:
00 00 00 01 # message id = 1
82 # message type = getattr response
00 00 00 00 # result = 0 (OK)
00 00 00 00 00 00 00 01 # attributes.inode = 1
00 00 00 00 00 00 00 02 # attributes.nlink = 2
00 00 41 a4 # attributes.mode = 0o40644 (S_IDDIR | 0o0644)
00 00 03 e8 # attributes.uid = 1000
00 00 03 e8 # attributes.gid = 1000
00 00 00 00 00 00 00 00 # attributes.size = 0
00 00 00 00 00 00 00 00 # attributes.blocks = 0
00 00 00 00 00 00 00 00 # attrbites.atime.sec = 0
00 00 00 00 00 # attributs.atime.nsec = 0
00 00 00 00 00 00 00 00 # attrbites.mtime.sec = 0
00 00 00 00 00 # attributs.mtime.nsec = 0
00 00 00 00 00 00 00 00 # attrbites.ctime.sec = 0
00 00 00 00 00 # attributs.ctime.nsec = 0
````
### Get file attributes (Failure)
_Note that attributs are skipped in case of an error._
````
service -> provider:
00 00 00 01 # message id = 1
02 # message type = getattr request
04 "/foo" # path = "/foo"
provider -> service:
00 00 00 01 # message id = 1
82 # message type = getattr response
ff ff ff fe # result = -2 (ENOENT)
````