You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2012/11/30 11:47:36 UTC
git commit: Document rewriter and vhosts
Updated Branches:
refs/heads/docs eb4914dd9 -> b87c50207
Document rewriter and vhosts
- derived from wiki
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b87c5020
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b87c5020
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b87c5020
Branch: refs/heads/docs
Commit: b87c5020793a24ace68bf6d948cf832f3cbc6f39
Parents: eb4914d
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Nov 30 11:13:40 2012 +0100
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Fri Nov 30 11:46:15 2012 +0100
----------------------------------------------------------------------
share/doc/build/Makefile.am | 4 +-
share/doc/src/index.rst | 3 +-
share/doc/src/pretty_urls.rst | 136 ++++++++++++++++++++++++++++++++++++
3 files changed, 141 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b87c5020/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index a3548e0..a506146 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -48,7 +48,7 @@
# @@ solved by running some commands on:
# @@ http://wiki.apache.org/couchdb/Installing_on_Ubuntu
# @@ but dont know why
-# @@ oh, probably because i didn't install build-essential
+# @@ oh, probably because i didn't install buildExamples:-essential
# @@ design CouchDB theme
@@ -132,6 +132,7 @@ html_files = \
html/os-daemons.html \
html/query-servers.html \
html/range.html \
+ html/pretty_urls.html \
html/release.html \
html/replication.html \
html/search.html \
@@ -176,6 +177,7 @@ src_files = \
../src/query-servers.rst \
../src/os-daemons.rst \
../src/range.rst \
+ ../src/pretty_urls.rst \
../src/release.rst \
../src/replication.rst \
../src/ssl.rst
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b87c5020/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index a4ced76..60de0c5 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -30,6 +30,7 @@ Contents
intro
api-basics
range
+ pretty_urls
configuring
ssl
os-daemons
@@ -47,4 +48,4 @@ Contents
.. This is how you get a TM sign into a link. Haha. Seriously.
.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122
-.. _Apache CouchDB(TM): http://couchdb.apache.org/
\ No newline at end of file
+.. _Apache CouchDB(TM): http://couchdb.apache.org/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b87c5020/share/doc/src/pretty_urls.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/pretty_urls.rst b/share/doc/src/pretty_urls.rst
new file mode 100644
index 0000000..d3f5e9e
--- /dev/null
+++ b/share/doc/src/pretty_urls.rst
@@ -0,0 +1,136 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _pretty_urls:
+
+===========
+Pretty URLs
+===========
+
+CouchDB incorporates a straightforwards URL routing and rewriting engine.
+While it is not as comprehensive as a front-end proxy, it caters for most
+needs out of the box, including using virtual hostnames to map URLs to
+specific databases, and provides more complex use cases through a rewriting
+engine.
+
+This `post
+<http://blog.couchbase.com/what%E2%80%99s-new-apache-couchdb-011-%E2%80%94-part-one-nice-urls-rewrite-rules-and-virtual-hosts>`_ has a detailed example of a combined vhost and rewriter configuration.
+
+Virtual Hosts
+=============
+
+CouchDB, since 0.11.0, can map requests to different locations based on
+the ``Host`` header, even if they arrive on the some inbound IP address.
+
+This allows different virtual hosts on the same machine to map to different
+databases or design documents, etc. The most common use case is to map a
+virtual host to a Rewrite Handler, to provide full control over the
+application's URIs.
+
+To add a virtual host, add a CNAME pointer to the DNS for your domain
+name. For development and testing, it is sufficient to add an entry in
+the hosts file, typically `/etc/hosts`` on Unix-like operating systems:
+
+.. code-block:: console
+
+ # CouchDB vhost definitions, refer to local.ini for further details
+ 127.0.0.1 sofa.couchdb
+
+Test that this is working:
+
+.. code-block:: console
+
+ $ ping sofa.couchdb
+ PING sofa.couchdb (127.0.0.1) 56(84) bytes of data.
+ 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
+ 64 bytes from localhost.localdomain (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
+ ^C
+
+Finally, add an entry to your :ref:`configuration file <configuring>` in the ``[vhosts]``
+section:
+
+.. code-block:: ini
+
+ [vhosts]
+ sofa.couchdb:5984 = /sofa/_design/sofa/_rewrite
+
+If your CouchDB is listening on the default HTTP port, or is sitting
+behind a proxy, then don't specify a port number in the vhost key.
+
+With the above setup, a request to ``http://sofa.couchdb:5984/sweet-o``
+will be mapped to
+``http://127.0.0.1:5984/sofa/_design/sofa/_rewrite/sweet-o``
+
+.. versionchanged:: 0.11.0 added `vhosts` functionality
+
+HTTP Rewrite Handler
+====================
+
+Following on from `virtual hosts`_, CouchDB includes a custom URL rewriter.
+All rewriting is done from ``/dbname/_design/ddocname/_rewrite`` by default.
+
+The rewriter is flexible, and can handle methods and custom query formats.
+
+Each rule should be in the ``rewrites`` top-level key of the design doc.
+Example of a complete rule :
+
+.. code-block:: json
+
+ {
+ ....
+ "rewrites": [
+ {
+ "from": "",
+ "to": "index.html",
+ "method": "GET",
+ "query": {}
+ }
+ ]
+ }
+
+
+**from**: is the path rule used to bind current uri to the rule. It
+uses pattern matching for that.
+
+**to**: rule to rewrite an url. It can contain variables depending on
+binding variables discovered during pattern matching and query args
+(url args and from the query member.)
+
+**method**: method to bind the request method to the rule. If method
+is missing, any method will be matched in the rewrite.
+
+**query**: optional query arguments, that may contain dynamic variables,
+by binding keys in the to be used with the matching URL.
+
+``to`` and ``from`` are paths with patterns. The pattern can be strings starting
+with ``:`` or ``*``, for example ``/somepath/:var/*``.
+
+The pattern matching is done by first matching the request method to a
+rule. Then it will try to match the path to one specific rule. If no rule
+match, then a 404 error is displayed.
+
+The path is converted into an erlang list, by regex splitting on ``/``. Each
+variable is converted into an atom. The subsequent pattern matching step is
+done by splitting ``/`` in the request url into a list of atoms. A string
+pattern will match the equivalent token. The ``*`` atom will match any number
+of tokens, but may only be present as the last pattern in the path. If all
+tokens are matched, and all path terms have been consumed, then the overall
+path specification matches.
+
+Once a matching ``from`` rule is found we rewrite the request url using the
+``from``, ``to``, and ``query`` members. Each identified token will be reused
+within the rule, and in the subsequent query if required. The identified
+tokens are matched to the rule and will replace var. If ``*`` is found in
+the rule it will contain any remaining suffix.
+
+The rewriter is re-entrant, and has a configurable recursion limit, set
+by default at 100.