mirror of
https://github.com/falk-werner/webfuse
synced 2024-10-27 20:34:10 +00:00
added more documentation
This commit is contained in:
Falk Werner
parent
b9c0f769d8
commit
36f222577f
108
doc/protocol.md
108
doc/protocol.md
@ -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
|
||||
````
|
||||
|
||||
Loading…
Reference in New Issue
Block a user