Mailing-List: contact couchdb-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: couchdb-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of cmlenz@gmx.de designates
 213.165.64.20 as permitted sender)
Message-Id: <F4B05F8C-B492-47B3-9762-D755A0480D18@gmx.de>
From: Christopher Lenz <cmlenz@gmx.de>
To: couchdb-dev@incubator.apache.org
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v919.2)
Subject: Attachment management in Futon
Date: Fri, 23 May 2008 18:14:11 +0200

Hey folks,

I've started playing with attachment support in Futon. As Futon is a  
purely client-side application this is of course tricky (or actually  
impossible), and it'll need some kind of hook on the server side.

I have two separate ideas on how this might be enabled, each with its  
own advantages and disadvantages:

1. POST /_utils/upload/

This would be a special URL in CouchDB that would only exist to  
support Futon. It would take a multipart/form-data POST request, extra  
a file upload, and respond with a JSON representation of that upload,  
with the content base64 encoded:

   handle_upload_request(Req, 'POST') ->
     Form = mochiweb_multipart:parse_form(Req),
     {Name, {ContentType, _}, Content} = proplists:get_value("file",  
Form),
     Json = {obj, [
       {name, Name},
       {type, ContentType},
       {content, couch_util:encodeBase64(Content)}
     ]},
     Body = "<textarea>" ++ cjson:encode(Json) ++ "</textarea>",
     {ok, Req:ok({"text/html", Body})};

The JSON needs to be wrapped in HTML, because AJAX file uploads need  
to go through a separate hidden <iframe> and an impressive number of  
hacks. We'd be using the jQuery Form plugin <http://malsup.com/jquery/form/ 
 > to handle that in Futon.

So after submitting the attachment upload form, Futon would get back a  
JSON representation of the upload, and add that JSON representation to  
the _attachments member of the currently open document. When the  
document is saved, the attachment data is part of the JSON  
representation of the document, and is thus saved in the database.

The main drawback of this approach is that the file data is sent back  
and forth: the initial upload, the server response, and the document  
update request. For large files this will be somewhere between  
noticable and a showstopper.

One advantage is that the attachment is only stored to the database  
when the document is saved, same as for adding, modifying and deleting  
fields. Another advantage is that Futon would be more flexible  
(compared to the alternative presented below), as it could allow users  
to specify the MIME type and maybe the encoding of the file, or to  
provide a different target file name (for example, the local file is  
called "NONAME.rtf" but the user would like to store it in the  
document as "example.rtf").

2. POST /database/docid/

Here we'd accept a multipart/form-data POST on the document URI. The  
form data may have one or more parts called "_attachments", each of  
which would be a file upload that would get added to the attachments  
of the document, possibly replacing existing attachments with the same  
file name.

I don't think POST methods are supposed to use Etags and If-Match, so  
we'd probably have to specify the document revision using a query  
string parameter. So the POST request might look something like:

   POST /database/docid/?rev=123456 HTTP/1.1
   Host: example.org
   Content-Type: multipart/form-data; boundary=AaB03x

   --AaB03x
   Content-Disposition: form-data; name="_attachments";  
filename="example.rtf"
   Content-Type: application/rtf

   ... contents of example.rtf ...
   --AaB03x--

It would need to be decided whether this interface should only be used  
for attachments. It *might* be nice to be able to use this as a sort  
of "edit document" interface, allowing you to add/update individual  
fields, for example:

   POST /database/docid/?rev=123456 HTTP/1.1
   Host: example.org
   Content-Type: multipart/form-data; boundary=AaB03x

   --AaB03x--
   Content-Disposition: form-data; name="full_name"
   Content-Type: application/json

   "Christopher Lenz"
   --AaB03x--
   Content-Disposition: form-data; name="_attachments";  
filename="example.rtf"
   Content-Type: application/rtf

   ... contents of example.rtf ...
   --AaB03x--

Besides adding the attachment as before, this would either add or  
update the "full_name" field in the specified document (or bail with a  
conflict error).


I'm not sure about all this, so feedback / alternative suggestions  
would be highly appreciated.

Thanks,
--
Christopher Lenz
   cmlenz at gmx.de
   http://www.cmlenz.net/