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/%[email protected]%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.
