ikiwiki/doc/todo/fileupload/soc-proposal.mdwn

# SoC Proposal for Implementation of a File Upload Interface

I intend to extend Ikiwiki such that it accepts file uploads, subject to access
control, and displays image collections in a gallery format. Since the latter
component is dependent on the former, I will defer its planning for now. What
follows is a very rough draft of my thoughts on the matter. Comments are
welcomed, either on the discussion page or via e-mail (_me_ at _inelegant.org_).

I suggest we adopt the Trac/Wikipedia concept of "attaching" files to a given
page. In this scenario, each page for which file upload has been enabled, will
sport an `<input type="file">` construct along with an _Attach_ button. Upon
successfully attaching a file, its name will be appended to an _"Attachments"_
list at the bottom of the page. The names in the list will link to the
appropriate files. Architecturally, this means that after a file has been attached to a page, the
page will have to be rebuilt. 

## Metadata

Uploaded files will have at least the following pieces of metadata:

 * Filename
 * Upload date
 * Page attached to  
 * Uploader's name
 * File size  
 * File type  

The first three pieces of data are associated with every new page on the wiki by
means of the _.ikiwiki/index_ file (_src_/_dest_, _ctime_, and _link_,
respectively). The next two are stored in the RCS log.

Ideally, the list of attachments for a given page will detail, at least, each attachment's
type (so the user knows whether they can open it), size (so the user knows
whether it is worth downloading), and potentially a thumbnail of some sort for
images and videos. It is potentially expensive to query the RCS for this data on
every page rebuild, so I propose the addition of two optional fields to the
index file: _mime_, which contains the MIME type of the _dest_ file, and _size_,
which contains the size in bytes of _dest_. 

If a user attached a photograph (_my-cat.png_) to a page (_my-cat_), the
following lines are representative of what _index_ may store:

    mtime=1174347925 ctime=1169220485 src=my-cat.png dest=my-cat.png link=my-cat mime=image/png size=73100
    mtime=1174347927 ctime=1174347927 src=my-cat.mdwn dest=my-cat/index.html link=my-cat.png

Thus, we define an attachment as file linked from an existing page, with a
non-_text/html_ MIME type.

## Configuration

In [[todo/fileupload]] it is specified that the upload feature must be highly
configurable. It is suggested that this configuration be achieved by embedding
directives in the wiki pages directly.

Consider an ikiwiki for photographers. The admin decides to allow users to
upload their photographs. Using the Pagespec suggestion, he must enforce this
policy on the front page of his wiki (as preferences cascade horizontally
downwards). He must then lock the front page from editing, in order to prevent
his users from reversing his decision. IOW, he is forced to lock a page purely
to register a configuration preference. He will need to repeat this process for
each layer of the hierarchy he wants to apply a different policy to.

Further, these embedded configuration directives risk overshadowing the content
of the page, and thus confusing users. This would become particularly
problematic for wikis which need to maintain blacklists/whitelists for access
control -- they would need to continually update wiki pages (thus polluting the
RCS logs) just to stem abuse.

I suspect that we can accommodate most use cases by allowing these options to be
set globally in the _ikiwiki.setup_ file. They can then be optionally set on a
page-by-page basis by use of pagespecs or a reworking of the config system such
that ikiwiki dotfiles can be placed at arbitrary levels of the hierarchy, and
have their directives supersede those set by their parents. Clearly, the first
option is significantly simpler.

## Operation

1. File upload forms will be rendered on all wiki pages which have been allowed
in the global configuration file. By default, this will probably be none of
them.
2. The forms will interface with _ikiwiki.cgi_, passing it the filename, the
file contents, and the name of the page to which it is being attached.
3. The CGI will consult the config file and any embedded pagespecs in turn, to
determine whether the access controls permit the upload. If they don't, an error
message will be displayed to the user, and the process will abort.
4. The uploaded file will be saved to the appropriate directory.
5. The uploaded file will be committed to the RCS.
6. _.ikiwiki/index_ will be modified to reflect the new upload (as above).
7. The page to which the file is attached (and any other
affected pages) will be regenerated.

--Ben