FilesysVirtualPlugin

Implementation of the Filesys::Virtual::Plain API over a Foswiki store

This module provides two FUSE-like file system implementations that are tailored for use with the WebDAVContrib (from http://c-dot.co.uk) though they are general and flexible enough to serve in other applications. The advantage of such a virtual file system is that it's easier to map other applications that assume a full filesystem to working on data from a Foswiki store.

The file systems are implementations of the virtual base class Filesys::Virtual implementations:

• A file system layered over a Foswiki store.
• A pure-perl implementation of the same API for accessing files on disk.

See CPAN:Filesys::Virtual::Plain for more information on the basic API this module implements.

Filesys::Virtual::Foswiki

A full filesystem is a lot more generic than a Foswiki store, so there has to be some mapping between what is in the store and the filesystem, and some constraints on what can and can't be done with the filesystem.

In the default configuration, the store is mapped as follows:

• Webs are directories
• Topics are seen as plain files that have a .txt extension, e.g. MyTopic.txt. Other data views, such as .html, are also available.
• Attachments are stored in a Topic_files/ directory, e.g. MyTopic_files/

Foswiki access controls are respected at all levels in the store.

Note: You cannot create subdirectories in a _files directories.

The module currently uses Foswiki::Func methods with the absolute minimum of unavoidable kick-down to the file system when the Foswiki APIs just don't provide the required information. The unavoidable kick-down means that this module will only work with filesystem-based stores, such as RcsWrap, RcsLite and PlainFileStoreContrib. The module also supports a simple lock API, which is driven by the requirements of WebDAV. This lock implementation does not relate in any way to Foswiki leases or atomic locks; it is purely for the support of WebDAV clients that require locks.

Filesys::Virtual::PlainPlusAttrs

Filesys::Virtual::PlainPlusAttrs extends Filesys::Virtual::Plain with extended attributes and locks. This is primarily used for testing WebDAVContrib, by providing that module with a full filesystem interface. It is not directly useful to Foswiki but is provided as a reference implementation of the file system interface that the WebDAVContrib requires, and may be useful as a stand-alone solution to publish files on disk via WebDAV. Note however that this filesystem does not support user logins.

Configuration

Topic views

Foswiki topics are stored internally in TML (Topic Markup Language). TML is the special wiki markup syntax you see if you "Raw View" a topic. Also mixed into topics is meta-data, such as form fields.

Neither TML nor meta-data are supported by commonly available editing tools, such as word processors. So FilesysVirtualPlugin supports different views of the data in topics for read and write. Each view you enable adds another file type to the directory representing a web. For example, if you enable the txt, html, and json views you will see the following files for MyTopic:

• MyTopic.txt
• MyTopic.html
• MyTopic.json

Any of these files can be written to change the content of MyTopic.

The following standard views are available:

View	Description
txt	Presents just the TML text of the topic in a .txt file.
html	Topic text a .html file (mapping provided by the WysiwygPlugin). This allows you to edit topics using an HTML-capable editor.
json	Meta-data in JSON format in a .json file
perl	Meta-data as a serialised perl data structure in a .pl file
raw	Presents the raw text of the topic in a .raw.txt file. The raw topic text includes embedded meta-data macros.

You can choose which views you want using the Foswiki configure interface. Additional views can easily be added.

list_details

The list_details method of the Filesys::Virtual::Plain API is implemented slightly differently to provide better support for Foswiki. Rather than returning an ls - style list of files, it returns a full HTML web page. The web page is built using the Foswiki templates system, using the template file webdav_folder. The FilesysVirtualPlugin does not provide an implementation of this template. However you can find an implementation in the companion WebDAVLinkPlugin. Foswiki skin settings are respected, so overriding this template for customisation is straightforward.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Note: This plugin doesn't actually have to be enabled in order to work. At the moment it uses standard Foswiki access control checking methods, but the plan is to add a permissions cache. For this reason it has to be a plugin so it can implement handlers that watch for topic saves.

Note that locks are stored in a database file, held in the working area for the plugin - usually working/FilesysVirtualPlugin/lockdb. You can delete this file at any time to automatically release all outstanding locks.

Note that for reasons of efficiency the lock database is leaky (locks on deleted files may persist). For this reason it is recommended that the lock database is monitored and deleted during system maintenance if it grows too big.

License

This software is released under the GNU Public License, version 2. However it cost a lot in blood, sweat and tears to develop, and if you find it useful then http://c-dot.co.uk would be grateful for your financial support.

Info

Many thanks to the following sponsors for supporting this work:

• Kontextwork

Dependencies

Name	Version	Description
Data::Dumper	>=0	Required perl module
Filesys::Virtual	>=0	Required perl module
Storable	>=0	Required, used for the locks database
POSIX	>=0	Standard perl module
File::Path	>=0	Standard perl module
IO::File	>=0	Standard perl module
IO::String	>=0	Required perl module
Foswiki::Plugins::WysiwygPlugin	>=0	Optional, required for .html view
JSON	>=0	Optional, required for the .json view

Change History

06 May 2022:	fixed unicode handling of views; extension for raw is .raw.txt; extension for perl is now .pl (Foswiki:Main/MichaelDaum)
20 Oct 2020:	make it work on subwebs (Foswiki:Main/MichaelDaum)
12 Nov 2019:	enable password validation by default; fix several issues flagged by perlcrit (Foswiki:Main/MichaelDaum)
11 Jul 2016:	compatibility with Foswiki-2 (Foswiki:Main/MichaelDaum)
08 Mar 2016:	fixed breakage when not running under Foswiki:Extensions/VirtualHostingContrib (Foswiki:Main/MichaelDaum)