doc/todo/fileupload/soc-proposal.mdwn

   1 # SoC Proposal for Implementation of a File Upload Interface
   2
   3 I intend to extend Ikiwiki such that it accepts file uploads, subject to access
   4 control, and displays image collections in a gallery format. Since the latter
   5 component is dependent on the former, I will defer its planning for now. What
   6 follows is a very rough draft of my thoughts on the matter. Comments are
   7 welcomed, either on the discussion page or via e-mail (_me_ at _inelegant.org_).
   8
   9 I suggest we adopt the Trac/Wikipedia concept of "attaching" files to a given
  10 page. In this scenario, each page for which file upload has been enabled, will
  11 sport an `<input type="file">` construct along with an _Attach_ button. Upon
  12 successfully attaching a file, its name will be appended to an _"Attachments"_
  13 list at the bottom of the page. The names in the list will link to the
  14 appropriate files. Architecturally, this means that after a file has been attached to a page, the
  15 page will have to be rebuilt.
  16
  17 ## Metadata
  18
  19 Uploaded files will have at least the following pieces of metadata:
  20
  21  * Filename
  22  * Upload date
  23  * Page attached to
  24  * Uploader's name
  25  * File size
  26  * File type
  27
  28 The first three pieces of data are associated with every new page on the wiki by
  29 means of the _.ikiwiki/index_ file (_src_/_dest_, _ctime_, and _link_,
  30 respectively). The next two are stored in the RCS log.
  31
  32 Ideally, the list of attachments for a given page will detail, at least, each attachment's
  33 type (so the user knows whether they can open it), size (so the user knows
  34 whether it is worth downloading), and potentially a thumbnail of some sort for
  35 images and videos. It is potentially expensive to query the RCS for this data on
  36 every page rebuild, so I propose the addition of two optional fields to the
  37 index file: _mime_, which contains the MIME type of the _dest_ file, and _size_,
  38 which contains the size in bytes of _dest_.
  39
  40 If a user attached a photograph (_my-cat.png_) to a page (_my-cat_), the
  41 following lines are representative of what _index_ may store:
  42
  43     mtime=1174347925 ctime=1169220485 src=my-cat.png dest=my-cat.png link=my-cat mime=image/png size=73100
  44     mtime=1174347927 ctime=1174347927 src=my-cat.mdwn dest=my-cat/index.html link=my-cat.png
  45
  46 Thus, we define an attachment as file linked from an existing page, with a
  47 non-_text/html_ MIME type.
  48
  49 ## Configuration
  50
  51 In [[todo/fileupload]] it is specified that the upload feature must be highly
  52 configurable. It is suggested that this configuration be achieved by embedding
  53 directives in the wiki pages directly.
  54
  55 Consider an ikiwiki for photographers. The admin decides to allow users to
  56 upload their photographs. Using the Pagespec suggestion, he must enforce this
  57 policy on the front page of his wiki (as preferences cascade horizontally
  58 downwards). He must then lock the front page from editing, in order to prevent
  59 his users from reversing his decision. IOW, he is forced to lock a page purely
  60 to register a configuration preference. He will need to repeat this process for
  61 each layer of the hierarchy he wants to apply a different policy to.
  62
  63 Further, these embedded configuration directives risk overshadowing the content
  64 of the page, and thus confusing users. This would become particularly
  65 problematic for wikis which need to maintain blacklists/whitelists for access
  66 control -- they would need to continually update wiki pages (thus polluting the
  67 RCS logs) just to stem abuse.
  68
  69 I suspect that we can accommodate most use cases by allowing these options to be
  70 set globally in the _ikiwiki.setup_ file. They can then be optionally set on a
  71 page-by-page basis by use of pagespecs or a reworking of the config system such
  72 that ikiwiki dotfiles can be placed at arbitrary levels of the hierarchy, and
  73 have their directives supersede those set by their parents. Clearly, the first
  74 option is significantly simpler.
  75
  76 ## Operation
  77
  78 1. File upload forms will be rendered on all wiki pages which have been allowed
  79 in the global configuration file. By default, this will probably be none of
  80 them.
  81 2. The forms will interface with _ikiwiki.cgi_, passing it the filename, the
  82 file contents, and the name of the page to which it is being attached.
  83 3. The CGI will consult the config file and any embedded pagespecs in turn, to
  84 determine whether the access controls permit the upload. If they don't, an error
  85 message will be displayed to the user, and the process will abort.
  86 4. The uploaded file will be saved to the appropriate directory.
  87 5. The uploaded file will be committed to the RCS.
  88 6. _.ikiwiki/index_ will be modified to reflect the new upload (as above).
  89 7. The page to which the file is attached (and any other
  90 affected pages) will be regenerated.
  91
  92 --Ben