Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Message-ID: <2008097314.1236628430602.JavaMail.jira@brutus>
Date: Mon, 9 Mar 2009 12:53:50 -0700 (PDT)
From: "Chris Anderson (JIRA)" <jira@apache.org>
To: dev@couchdb.apache.org
Subject: [jira] Closed: (COUCHDB-280) relative links between resources
 provided by design docs
In-Reply-To: <329362532.1236140156091.JavaMail.jira@brutus>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


     [ https://issues.apache.org/jira/browse/COUCHDB-280?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Chris Anderson closed COUCHDB-280.
----------------------------------

    Resolution: Fixed

closed in r751813

> 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
>
>         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:
> 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.