couchdb-dev mailing list archives

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


Chris Anderson updated COUCHDB-280:

    Attachment: relative-design-paths.diff

Here is a patch, against r749902. 

The previously mentioned github branch is out of date. If you want to use git, the branch
is here:

> relative links between resources provided by design docs
> --------------------------------------------------------
>                 Key: COUCHDB-280
>                 URL:
>             Project: CouchDB
>          Issue Type: Improvement
>            Reporter: Chris Anderson
>            Assignee: Chris Anderson
>             Fix For: 0.9
>         Attachments: relative-design-paths.diff
> 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:
> 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.

View raw message