summaryrefslogtreecommitdiff
path: root/doc/todo/fileupload/soc-proposal.mdwn
blob: 5e4fa2584167987ebd94f626c6b90619325f5a33 (plain)

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