couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chris Anderson (JIRA)" <j...@apache.org>
Subject [jira] Created: (COUCHDB-280) relative links between resources provided by design docs
Date Wed, 04 Mar 2009 04:15:56 GMT
relative links between resources provided by design docs
--------------------------------------------------------

                 Key: COUCHDB-280
                 URL: https://issues.apache.org/jira/browse/COUCHDB-280
             Project: CouchDB
          Issue Type: Improvement
            Reporter: Chris Anderson
            Assignee: Chris Anderson
             Fix For: 0.9


In an earlier thread we discussed the costs and benefits of changing CouchDB so that all the
resources provided by a design doc are rooted in the design doc.

Under the current system, there is no way to link among HTML files attached to a design docs,
the HTML output of show and list functions, and view queries. The only way to link between
these resources is by hard-coding the design doc name in your link. By giving the resources
provided by design docs a common root, one can link between them using hrefs like "../../_show/sname/docid".


The current system never posed a problem before, because design docs only provided one type
of resource. However, going forward I can see that design docs could continue to provide new,
unanticipated resources. Jason Davies has proposed an _update resource, which would be a JavaScript
(or other language) function that can accept request with non-JSON bodies (for instance POSTed
XML from a webhook service) and convert them to JSON for storage.

The advantages to decomposing the traditional "accept a request, do whatever you want, send
a reply" app-server model into discrete functions are numerous, the main one being that developers
can support custom non-JSON content-types, while still interacting with the database in a
manner where side-effects and memory / runtime characteristics are controlled.

Show and list break non-JSON rendering down into the right sized granules for safe, cacheable
idempotent requests. But because we we can't link between them (and design doc attachments)
using normal html links (the links must be computed on the server) they aren't enough to provide
a hypermedia interface for CouchDB. Hypermedia is above what CouchDB has been shooting for,
but we are so close now that it seems silly not to go the "rest" of the way.

If it were just the tradeoffs between relative links (good) and slightly uglier urls (bad)
I'd be roughly +0 on this change. But a consequence of giving design doc resources a common
root is that the applications the define can then be proxied with a URL rewriter. The means
that (if written correctly) an application with paths like:

/db/_design/foo/_view/bar?limit=10
/db/_design/foo/_show/docid
/db/_design/foo/index.html

can be proxied so that the "/db/_design/foo" part of the URL is added by the proxy, so that
all clients see is:

/_view/bar?limit=10
/_show/docid
/index.html

This also nicely limits end-client access, so that they may only interact with the database
using resources provided by the design doc. I consider this an edge-case for deployment but
the fact that we can cleanly support makes me think we're on the right track with the change
to a common root for design doc resources.

For more details about these URL path interactions, see the earlier thread:

http://mail-archives.apache.org/mod_mbox/couchdb-dev/200902.mbox/%3Ce282921e0902242116n2cd207c4x7a9d0feced3f10d9@mail.gmail.com%3E

I've implemented a patch (attached to this ticket) that makes it so that views, shows, lists,
and design doc attachments are all rooted under the design doc.

It works by adding a section to the ini file, like this (which we could use to easily add
new resource, like the _update mentioned above):

[httpd_design_handlers]
_view = {couch_httpd_view, handle_view_req}
_show = {couch_httpd_show, handle_doc_show_req}
_list = {couch_httpd_show, handle_view_list_req}

the _design handler itself is just an http_db_handler. 

Points of discussion:

If we want to change the names of any of: _view, _show, _list, or _design now is a good time
to do it. We've been over the names _list and _show many times, and while they aren't perfect,
they are short, and more-or-less descriptive of what they do.

The code is robust about changes to the _design db handler's name. That is, we could continue
to call them design docs, and store them with ids like "_design/name", while changing the
resource root so that the above set of URLs could be something like (modulo an attachments
handler, "_files" here, for clarity):

/db/_baz/foo/_view/bar?limit=10
/db/_baz/foo/_show/docid
/db/_baz/foo/_files/index.html

Before we commit / before 0.9.0:

This patch is a big enough change that I think we should vote on it before I commit it. However,
I'd like to get it in before 0.9.0 to avoid future confusion where trunk is incompatible with
API clients and applications designed to run on our latest release.

Sincerely,
Chris


-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message