From 40eafc19d70e6d89fdbe95e9f86d4bde8f6d2a61 Mon Sep 17 00:00:00 2001 From: Falk Werner <47070255+falk-werner@users.noreply.github.com> Date: Tue, 12 Mar 2019 15:49:28 +0100 Subject: [PATCH] Document the main use case (#10) * fixes typo * adds motivation * fixes link in contents * fixes some style issues * fixes heading * fixes typo and inconsistent use of fuse-wsfs --- README.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 499022e..f527e19 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,31 @@ fuse-wsfs combines libwebsockets and libfuse. It allows ot attach a remote files ## Contents -- [Workflow and API](#Workflow-and-API) +- [Motivation](#Motivation) +- [Concept](#Concept) +- [Similar Projects](#Similar-Projects) +- [API](#API) - [Build and run](#Build-and-run) - [Dependencies](#Dependencies) -## Workflow and API +## Motivation + +Many embedded devices, such as smart home or [IoT](https://en.wikipedia.org/wiki/Internet_of_things) devices are very limited regarding to their (non-volatile) memory resources. Such devices are typically comprised of an embedded linux and a small web server, providing an interface for maintenance purposes. + +Some use cases, such as firmware update, require to transfer (larger) files to the device. The firmware file is often stored multiple times on the device: + +1. cached by the web server, e.g. [lighttpd](https://redmine.lighttpd.net/boards/2/topics/3451) +2. copied to locally, e.g. /tmp +3. uncompressed, also to /tmp + +Techniques like [SquashFS](https://en.wikipedia.org/wiki/SquashFS) help to avoid the third step, since the upgrade file can be mounted directly. [RAUC](https://rauc.io/) shows the use of SquashFS within an update facility. +However at least one (unecessary) copy of the upload file is needed on the device. + +To avoid Steps 1 and 2, it would be great to keep the update file entirely in web server, just like [NFS](https://en.wikipedia.org/wiki/Network_File_System) or [WebDAV](https://wiki.archlinux.org/index.php/WebDAV). Unfortunately, NFS is not based on any protocol, natively usable by a web application. WebDAV is based on HTTP, but it needs a server providing the update file. + +fuse-wsfs solves this problem by using the [WebSocket](https://en.wikipedia.org/wiki/WebSocket) protocol. The emdedded device runs a service, known as WSFS adapter, awaiting incoming connections, e.g. from a web browser. The browser acts as a file system provider, providing the update file to the device. + +## Concecpt +---------------------+ +-------------+ +------+ | Filesystem Provider | | wsfs daemon | | user | @@ -55,6 +75,16 @@ A reference implementation of such a daemon is provided within the examples. The Currently all requests are initiated by wsfs daemon and responded by filesystem provider. This may change in future, e.g. when authentication is supported. +## Similar Projects + +### Davfs2 + +[davfs2](http://savannah.nongnu.org/projects/davfs2) is a Linux file system driver that allows to mount a [WebDAV](https://wiki.archlinux.org/index.php/WebDAV) resource. WebDAV is an extension to HTTP/1.1 that allows remote collaborative authoring of Web resources. + +Unlike fuse-wsfs, davfs2 mounts a remote filesystem locally, that is provided by a WebDAV server. In contrast, fuse-wsfs starts a server awaiting client connections to attach the remote file system. + +## API + ### Requests, responses and notifications There are three types of messages, used for communication between wsfs daemon and filesystem provider. All message types are encoded in [JSON](https://www.json.org/) and strongly inspired by [JSON-RPC](https://www.jsonrpc.org/). @@ -226,7 +256,7 @@ Open a file. | O_RDWR | 0x002 | open for reading an writing | | O_CREAT | 0x040 | create (a new) file | | O_EXCL | 0x080 | open file exclusivly | -| O_TRUNK | 0x200 | open file to trunkate | +| O_TRUNC | 0x200 | open file to truncate | | O_APPEND | 0x400 | open file to append | #### close