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

enhance protocol documentation

Browse Source
pull/105/head
Falk Werner 1 year ago
parent 1502ac9397
commit 50e1ec8f5c
1 changed files with 505 additions and 9 deletions
Show Stats Download Patch File Download Diff File

514
doc/protocol.md
Unescape View File

@ -1,4 +1,36 @@
# Webufse 2 Protocol
# Webfuse 2 Protocol
## Scope
This document describes the webfuse 2 communication protocol. The protocol is used to transfer messages between a `webfuse2 service` and a `webfuse2 provider`. In contrast to `legacy webfuse`, which is based on `JSON RPC` the `webfuse2 protocol` is a binary protocol.
## Definitions
### Webfuse2 Service
A `webfuse2 service` is both,
- a [websocket](https://en.wikipedia.org/wiki/WebSocket) service providing the `webfuse2` protocol
- a [fuse](https://github.com/libfuse/libfuse) filesystem attached to a local mountpoint
The `webfuse2 service` awaits incoming connections from a `webfuse2 provider`. Once connected, it communicates all the filesystem requests originated by the `libfuse` to the connected `webfuse2 provider` using the `websocket`-based `webfuse2 protocol`.
By doing so, `webfuse2` allows to inject a filesystem to a remote device.
### Webfuse2 Provider
A `webfuse2 provider` provides a filesystem to a remote device using the `websocket`-based `webfuse2 protocol`. Therefore, a `webfuse2 provider` implements a `websocket` client.
## Message exchange
Once connected, the `webfuse2 protocol` implements a strict request-response scheme, where
- all requests are send by the `webfuse2 service`,
- all requests require a response and
- all responses are send by the `webfuse2 provider`
Note that this communication is reversed the typical client-server-communication scheme. In `webfuse2` the `webfuse2 serive` (server) sends all the requests and the `webfuse provider` (client) sends the responses.
For message transfer, the [websocket](https://en.wikipedia.org/wiki/WebSocket) protocol is used. All messages are in binary form, plain text messages are never used by the `webfuse2 protocol`.
## Endianness
@ -86,7 +118,70 @@ For instance, the uint32 value 1 will be transferred as
| EXDEV | -18 | improper link |
| EWOULDBLOCK | -11 | resource temporarily unavailable |
#### access mode
| Mode | Value | Description |
| ---- | ----- | ----------- |
| F_OK | 0 | Tests, whether the file exists |
| X_OK | 1 | Tests, whether the file is executable |
| W_OK | 2 | Tests, whether the file is writable |
| R_OK | 4 | Tests, whether the file is readable |
#### mode
_Note that the following numbers are in `octal` notation._
| Fields and Flags | Mask | Description |
| ---------------- | -------- | ----------- |
| Protection mask | 0o000777 | Cointains the file protection flags (rwx for owner, group and others) |
| Sticky mask | 0o007000 | Sticky bits |
| S_ISVTX | 0o001000 | Sticky bit |
| S_ISGID | 0o002000 | Set-Group-ID bit |
| S_ISUID | 0o004000 | Set-User-ID bit |
| Filetype mask | 0o170000 | Filetype mask |
| S_IFREG | 0o100000 | regular file |
| S_IFDIR | 0o040000 | directory |
| S_IFCHR | 0o020000 | character device |
| S_IFBLK | 0o060000 | block device |
| S_IFIFO | 0o010000 | named pipe |
| S_IFLNK | 0o120000 | link |
| S_IFSOCK | 0o140000 | socket |
#### open_flags
_Note that the following numbers are in `octal` notation._
| Flags | Value | Description |
| ---------------- | -------- | ----------- |
| O_ACCMODE | 0o03 | Access mode mask |
| O_RDONLY | 0o00 | open file read-only |
| O_WRONLY | 0o01 | open file write-only |
| O_RDWR | 0o02 | open file for reading and writing |
| O_APPEND | 0o000002000 | open file in append mode |
| O_ASYNC | 0o000020000 | enable signal-driven I/O |
| O_CLOEXEC | 0o002000000 | enable close-on-exec |
| O_CREAT | 0o000000100 | create file if path does not exists |
| O_DIRECT | 0o000040000 | try to minimize cache effects on I/O |
| O_DIRECTORY | 0o000200000 | open a directory |
| O_DSYNC | 0o000010000 | write with synchronized I/O data integrity |
| O_EXCL | 0o000000200 | ensure that file exists when specified in conjunction with O_CREATE |
| O_LARGEFILE | 0o000100000 | allow large files to be opened |
| O_NOATIME | 0o001000000 | do not update file last access time |
| O_NOCTTY | 0o000000400 | make device the process's controlling terminal |
| O_NOFOLLOW | 0o000400000 | fail to open, if basename is a symbolic link |
| O_NONBLOCK | 0o000004000 | open in nonblocking mode |
| O_NDELAY | 0o000004000 | open in nonblocking mode |
| O_PATH | 0o010000000 | see manual entry of `open(2)` for details |
| O_SYNC | 0o004010000 | write using synchronized I/O |
| O_TMPFILE | 0o020200000 | create an unnamed temporary file |
| O_TRUNC | 0o000001000 | truncate fole to length 0 |
#### rename_flags
| Flag | Value | Description |
| ---------------- | ----- | ----------- |
| RENAME_NOREPLACE | 1 | do not overwrite the new file |
| RENAME_EXCHANGE | 2 | atomically exchange the files |
### Complex Types
@ -137,22 +232,423 @@ For instance, the uint32 value 1 will be transferred as
#### statistics
## Message
## Messages
| Field | Type | Descripton |
| ------- | ---- | ---------- |
| id | u32 | Unique ID of the message |
| type | u8 | Type of the message |
| payload | u8[] | Payload according to the message type |
The `id` is just a number without any meaning for the `webfuse2 provider`. It is set by the `webfuse2 service` of a request and is copied by the `webfuse2 provider` to the response. A `webfuse2 service` implementation might choose to keep track on pending requests using the `id`.
### Erroneous Responses
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.
### Message Types
_Note that the following numbers are in `hexadecimal` notation._
| Method | Request | Response |
| -------- | ------- | -------- |
| access | 0x01 | 0x81 |
| getattr | 0x02 | 0x82 |
| readlink | 0x03 | 0x83 |
| symlink | 0x04 | 0x84 |
| link | 0x05 | 0x85 |
| rename | 0x06 | 0x86 |
| chmod | 0x07 | 0x87 |
| chown | 0x08 | 0x88 |
| truncate | 0x09 | 0x89 |
| fsync | 0x0a | 0x8a |
| open | 0x0b | 0x8b |
| mknod | 0x0c | 0x8c |
| create | 0x0d | 0x8d |
| release | 0x0e | 0x8e |
| unlink | 0x0f | 0x8f |
| read | 0x10 | 0x90 |
| write | 0x11 | 0x91 |
| mkdir | 0x12 | 0x92 |
| readdir | 0x13 | 0x93 |
| rmdir | 0x14 | 0x94 |
| statfs | 0x15 | 0x95 |
| utimens | 0x16 | 0x96 |
## Methods
### access
#### Request
| Field | Data Type | Description |
| ----- | ---------------- | ----------- |
| | uint32 | message id |
| type | uint8 | message type (0x00) |
| id | u32 | message id |
| type | u8 | message type (0x01) |
| path | string | |
| mode | access_mode (i8) |
#### Response
| Field |
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### getattr
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### readlink
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### symlink
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### link
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### rename
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### chmod
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### chown
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### truncate
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### fsync
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### open
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### mknod
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### create
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### release
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### unlink
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### read
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### write
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### mkdir
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### readdir
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### rmdir
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### statfs
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |
### utimens
#### Request
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
#### Response
| Field | Data Type | Description |
| ------ | --------- | ----------- |
| id | u32 | message id |
| type | u8 | message type (0x81) |
| result | result | operation status |

Write Preview
Loading…
Cancel
Save