web commit by http://id.inelegant.org/: First draft of proposal.
[ikiwiki.git] / 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