Archives
/
falk-werner_webfuse
mirror of https://github.com/falk-werner/webfuse
1
0
Fork 0
Code Issues Releases Wiki Activity

added more documentation

Browse Source
pull/105/head
Falk Werner 1 year ago
parent b9c0f769d8
commit 36f222577f
1 changed files with 103 additions and 5 deletions
Show Stats Download Patch File Download Diff File

108
doc/protocol.md
Unescape View File

@ -1,4 +1,4 @@
# Webfuse 2 Protocol
# Webfuse2 Protocol
## Scope
@ -188,6 +188,7 @@ _Note that the following numbers are in `octal` notation._
| Data Type | Description |
| ---------- | --------------------- |
| string | UTF-8 string |
| strings | list of strings |
| bytes | array of bytes |
| timestamp | date and time |
| attributes | file attributes |
@ -200,6 +201,13 @@ _Note that the following numbers are in `octal` notation._
| size | u32 | length of the string in bytes |
| data | u8[] | string data (UTF-8) |
#### strings
| Field | Data Type | Description |
| ----- | --------- | --------------------------------- |
| size | u32 | count of the elements in the list |
| data | string[] | strings |
#### bytes
| Field | Data Type | Description |
@ -232,6 +240,17 @@ _Note that the following numbers are in `octal` notation._
#### statistics
| Field | Data Type | Description |
| ------ | ---------- | -------------------------- |
| bsize | u64 | Filesystem block size |
| frsize | u64 | Fragment size |
| blocks | u64 | Size of the filesystem if `frsize` units |
| bfree | u64 | Number of free blocks |
| bavail | u64 | Number of free blocks for unprivileged users |
| files | u64 | Number of inodes |
| ffree | u64 | Number of free inodes |
| namemax | u64 | Maximum filename length |
## Messages
| Field | Type | Descripton |
@ -246,6 +265,22 @@ The `id` is just a number without any meaning for the `webfuse2 provider`. It is
Most responses contain a `result` encoding the status of the operation. While successful responses may contain additional data, erroneous responses must not be decoded by a `webfuse2 service` implementation beyond the `result` value.
### Unknown requests
There are two reserved message types in `webfuse2`:
- **0x00:** Unknown request
- **0x80:** Unknown response
A `webfuse2 service` may send a request of type `unknown request` for conformance testing reasons.
Since each request requires a response, a `webfuse2 provider` must respond to any unknown requests with a message of `unknown response` type. This allows to add new request types in future.
### Accept additional data in requests
Both, a `webfuse2 provider` and a `webfuse service` must accept messages that contain more data than specified. This allows to add optional fields to existing requests and / or responses in future.
_Note there are no optional fields in the current revision of the `webfuse2 protocol`.
### Message Types
_Note that the following numbers are in `hexadecimal` notation._
@ -631,17 +666,24 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x90) |
| result | result | operation status |
| result | result | amount of byte read or error code |
| data | bytes | requested data |
_Note that results returns the amount of bytes read on success._
### write
Write to a file (see [man write(2)](https://man7.org/linux/man-pages/man2/write.2.html), [man pread(2)](https://man7.org/linux/man-pages/man2/pread.2.html)).
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x17) |
| data | bytes | data to write |
| offset | u64 | offset to write to |
| handle | handle (u64) | handle of the file |
#### Response
@ -649,16 +691,22 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x91) |
| result | result | operation status |
| result | result | amount of bytes written or error code |
_Note that results returns the amount of bytes written on success._
### mkdir
Create a directory (see [man mkdir(2)](https://man7.org/linux/man-pages/man2/mkdir.2.html)).
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x12) |
| path | string | path of the directory |
| mode | mode (u32) | directory permissions |
#### Response
@ -670,12 +718,15 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
### readdir
Reads the contents of a directory.
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x13) |
| path | string | path of the directory |
#### Response
@ -684,15 +735,19 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
| id | u32 | message id |
| type | u8 | message type (0x93) |
| result | result | operation status |
| items | strings | names of the directory entries |
### rmdir
Delete a directory (see [man rmdir(2)](https://man7.org/linux/man-pages/man2/rmdir.2.html)).
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x14) |
| path | string | path of the directory |
#### Response
@ -704,12 +759,15 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
### statfs
Get filesystem statistics (see [man statvfs(3)](https://man7.org/linux/man-pages/man3/statvfs.3.html)).
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x15) |
| path | string | path of the file |
#### Response
@ -718,6 +776,7 @@ Read from a file description (see [man read(2)](https://man7.org/linux/man-pages
| id | u32 | message id |
| type | u8 | message type (0x95) |
| result | result | operation status |
| statistics | statistics | filesystem statistics |
### utimens
@ -752,7 +811,8 @@ _Note that handle might be invalid (-1), even if the file is open._
service -> provider:
00 00 00 01 # message id = 1
02 # message type = getattr request
01 '/' # path = "/"
00 00 00 01 # path.size = 1
'/' # path = "/"
provider -> service:
00 00 00 01 # message id = 1
@ -781,10 +841,48 @@ _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"
00 00 00 04 # path.size = 4
"/foo" # path = "/foo"
provider -> service:
00 00 00 01 # message id = 1
82 # message type = getattr response
ff ff ff fe # result = -2 (ENOENT)
````
### List directory contents
_Note that '.' and '..' should not be included in the response._
````
service -> provider:
00 00 00 02 # message id = 2
13 # message type = readdir request
00 00 00 04 # path.size = 4
'/dir' # path = "/dir"
provider -> service:
00 00 00 02 # message id = 2
93 # message type = readdir response
00 00 00 00 # result = 0 (OK)
00 00 00 03 # items.size = 3
00 00 00 03 # items[0].size = 3
"foo" # items[0] = "foo"
00 00 00 03 # items[0].size = 3
"bar" # items[0] = "bar"
00 00 00 03 # items[0].size = 3
"baz" # items[0] = "baz"
````
### Unknown request
````
service -> provider:
00 00 00 23 # message id = 0x23
42 # message type = ??? (not specified yet)
... # some more data
provider -> service:
00 00 00 23 # message id = 0x23
80 # message type = unknown response
````

Write Preview
Loading…
Cancel
Save