You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2013/07/22 12:29:58 UTC
[1/2] git commit: updated refs/heads/master to 917d898
Updated Branches:
refs/heads/master dfd2199a4 -> 917d89884
Import couch_dbupdates from rcouch.
This creates a new top level API endpoint: `/_db_updates`
that returns a line of JSON for each database event along
with the database name.
A database event is one of `created`, `updated`, `deleted`.
The API endpoint supports a `?feed=` parameter with the
options: `longpoll`, `continuous` and `eventsource`.
A second parameter `timeout=` specifies when the server should
close the connection.
`longpoll` closes the connection after a single notification.
It is the default option.
`continuous` keeps a socket open until the specified `timeout`
or 60 seconds by default.
`heartbeat` decides whether to send a newline character on
`timeout` to avoid clients closing the connection prematurely.
`eventsource` works like continuous, but sends the data in
EventSource format. See http://dev.w3.org/html5/eventsource/
The parameters are modelled after the existing `/_changes` API
endpoint. Note that `/_db_updates` does not support resuming
of notifications via a sequence ID.
This is a port of the existing DbUpdateNotification interface
to the HTTP API.
Functional changes compared to rcouch:
- make _db_updates an admin-only resource
Docs:
- updated api/misc to include basic info on `/_db_updates`
License:
Apache 2 license, updated LICENSE.
Notice:
(c) 2012 Benoit Chesneau, updated NOTICE.
Tests:
- only manual testing of the various API differences due to
complications with asynchronous HTTP requests in the JS
test suite and total annoyance of overly complicated
ibrowse/httpc modules for writing etap tests.
Recommendation to ship this as EXPERIMENTAL until we have tests.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ea18ecdf
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ea18ecdf
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ea18ecdf
Branch: refs/heads/master
Commit: ea18ecdf69290a179570f539f8d0bc8c9529f5a9
Parents: c40b25d
Author: Jan Lehnardt <ja...@apache.org>
Authored: Mon Mar 4 12:02:24 2013 +0100
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Mon Jul 22 12:28:51 2013 +0200
----------------------------------------------------------------------
LICENSE | 6 ++
NOTICE | 2 +
configure.ac | 1 +
etc/couchdb/default.ini.tpl.in | 1 +
license.skip | 1 +
share/doc/src/api/misc.rst | 62 ++++++++++++++++++
src/Makefile.am | 1 +
src/couch_dbupdates/LICENSE | 22 +++++++
src/couch_dbupdates/Makefile.am | 33 ++++++++++
src/couch_dbupdates/NOTICE | 6 ++
src/couch_dbupdates/README.md | 32 +++++++++
src/couch_dbupdates/src/couch_dbupdates.app.src | 11 ++++
src/couch_dbupdates/src/couch_dbupdates.erl | 46 +++++++++++++
.../src/couch_dbupdates_httpd.erl | 69 ++++++++++++++++++++
14 files changed, 293 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/LICENSE
----------------------------------------------------------------------
diff --git a/LICENSE b/LICENSE
index d488036..af0a898 100644
--- a/LICENSE
+++ b/LICENSE
@@ -889,3 +889,9 @@ For src/fauxton/assets/js/plugins/codemirror-javascript.js
Please note that some subdirectories of the CodeMirror distribution
include their own LICENSE files, and are released under different
licences.
+
+For the src/couch_dbupdates component
+
+ 2009-2012 (c) Benoît Chesneau <be...@e-engura.org>
+
+ Apache 2 License, see above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index 8379f97..182c267 100644
--- a/NOTICE
+++ b/NOTICE
@@ -142,4 +142,6 @@ This product also includes the following third-party components:
Copyright 2006-2013 (c) M. Alsup
+ * couch_dbupdates
+ Copyright 2012, Benoît Chesneau <be...@refuge.io>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/configure.ac
----------------------------------------------------------------------
diff --git a/configure.ac b/configure.ac
index 92a1643..9b1b758 100644
--- a/configure.ac
+++ b/configure.ac
@@ -722,6 +722,7 @@ AC_CONFIG_FILES([share/Makefile])
AC_CONFIG_FILES([share/doc/Makefile])
AC_CONFIG_FILES([share/doc/build/Makefile])
AC_CONFIG_FILES([src/Makefile])
+AC_CONFIG_FILES([src/couch_dbupdates/Makefile])
AC_CONFIG_FILES([src/couch_index/Makefile])
AC_CONFIG_FILES([src/couch_mrview/Makefile])
AC_CONFIG_FILES([src/couch_replicator/Makefile])
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/etc/couchdb/default.ini.tpl.in
----------------------------------------------------------------------
diff --git a/etc/couchdb/default.ini.tpl.in b/etc/couchdb/default.ini.tpl.in
index 5eb7ebc..43b13a0 100644
--- a/etc/couchdb/default.ini.tpl.in
+++ b/etc/couchdb/default.ini.tpl.in
@@ -159,6 +159,7 @@ _stats = {couch_httpd_stats_handlers, handle_stats_req}
_log = {couch_httpd_misc_handlers, handle_log_req}
_session = {couch_httpd_auth, handle_session_req}
_oauth = {couch_httpd_oauth, handle_oauth_req}
+_db_updates = {couch_dbupdates_httpd, handle_req}
[httpd_db_handlers]
_all_docs = {couch_mrview_http, handle_all_docs_req}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index db08c31..b398ff7 100644
--- a/license.skip
+++ b/license.skip
@@ -98,6 +98,7 @@
^src/couchdb/priv/couchspawnkillable
^src/couchdb/priv/stat_descriptions.cfg
^src/erlang-oauth/.*
+^src/couch_dbupdates
^src/ejson/.*
^src/etap/.*
^src/fauxton/app/app.js
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/share/doc/src/api/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/misc.rst b/share/doc/src/api/misc.rst
index f9562ae..faac880 100644
--- a/share/doc/src/api/misc.rst
+++ b/share/doc/src/api/misc.rst
@@ -33,6 +33,8 @@ A list of the available methods and URL paths are provided below:
+--------+-------------------------+-------------------------------------------+
| GET | /_all_dbs | Get a list of all the DBs |
+--------+-------------------------+-------------------------------------------+
+| GET | /_db_updates | A feed of database events |
++--------+-------------------------+-------------------------------------------+
| GET | /_log | Return the server log file |
+--------+-------------------------+-------------------------------------------+
| POST | /_replicate | Set or cancel replication |
@@ -153,6 +155,66 @@ The return is a JSON array:
"locations"
]
+``GET /_db_updates``
+====================
+
+* **Method**: ``GET /_db_updates``
+* **Request**: None
+* **Admin Privileges Required**: yes
+* **Query ARguments**:
+
+ * **Argument**: feed
+
+ * **Descroption**: Format of the response feed
+ * **Optional**: yes
+ * **Type**: string
+ * **Default**: longpoll
+ * **Supported Values**:
+
+ * **longpoll**: Closes the connection after the first event.
+ * **continuous**: Send a line of JSON per event. Keeps the socket open until ``timeout``.
+ * **eventsource**: Like, ``continuous``, but sends the events in EventSource format. See http://dev.w3.org/html5/eventsource/ for details,
+
+ * **Argument**: timeout
+
+ * **Descroption**: Number of seconds until CouchDB closes the connection.
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 60
+
+ * **Argument**: heartbeat
+
+ * **Descroption**: Whether CouchDB will send a newline character (``\n``) on ``timeout``.
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: true
+
+* **Return Codes**:
+
+ * **200**
+ Request completed successfully.
+
+Returns a list of all database events in the CouchDB instance.
+
+A database event is one of `created`, `updated`, `deleted`.
+
+For example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_db_events?feed=continuous
+ Accept: application/json
+
+.. code-block:: javascript
+
+ {"dbname":"my-database", "type":"created"}
+ {"dbname":"my-database", "type":"updated"}
+ {"dbname":"another-database", "type":"created"}
+ {"dbname":"my-database", "type":"deleted"}
+ {"dbname":"another-database", "type":"updated"}
+
+
+
``GET /_log``
=============
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/Makefile.am
----------------------------------------------------------------------
diff --git a/src/Makefile.am b/src/Makefile.am
index fbd514c..7b11e15 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -11,6 +11,7 @@
## the License.
SUBDIRS = \
+ couch_dbupdates \
couch_index \
couch_mrview \
couch_replicator \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/LICENSE
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/LICENSE b/src/couch_dbupdates/LICENSE
new file mode 100644
index 0000000..a089916
--- /dev/null
+++ b/src/couch_dbupdates/LICENSE
@@ -0,0 +1,22 @@
+2009-2012 (c) Benoît Chesneau <be...@e-engura.org>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/Makefile.am
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/Makefile.am b/src/couch_dbupdates/Makefile.am
new file mode 100644
index 0000000..d131b9b
--- /dev/null
+++ b/src/couch_dbupdates/Makefile.am
@@ -0,0 +1,33 @@
+## 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.
+
+couch_dbupdateslibdir = $(localerlanglibdir)/couch_dbupdates-0.1
+couch_dbupdatesebindir = $(couch_dbupdateslibdir)/ebin
+
+couch_dbupdatesebin_DATA = $(compiled_files)
+
+EXTRA_DIST = $(source_files)
+CLEANFILES = $(compiled_files)
+
+source_files = \
+ src/couch_dbupdates.erl \
+ src/couch_dbupdates.app.src \
+ src/couch_dbupdates_httpd.erl
+
+compiled_files = \
+ ebin/couch_dbupdates.beam \
+ ebin/couch_dbupdates_httpd.beam
+
+ebin/%.beam: src/%.erl
+ @mkdir -p ebin/
+ $(ERLC) -I$(top_srcdir)/src/couchdb -o ebin/ $(ERLC_FLAGS) ${TEST} $<;
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/NOTICE
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/NOTICE b/src/couch_dbupdates/NOTICE
new file mode 100644
index 0000000..ee00a85
--- /dev/null
+++ b/src/couch_dbupdates/NOTICE
@@ -0,0 +1,6 @@
+couch_dbupdates
+---------------
+
+2012 (c) Benoît Chesneau <be...@refuge.io>
+
+couch_dbupdates is released under the Apache License 2.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/README.md
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/README.md b/src/couch_dbupdates/README.md
new file mode 100644
index 0000000..c683102
--- /dev/null
+++ b/src/couch_dbupdates/README.md
@@ -0,0 +1,32 @@
+# couch_dbupdates
+
+`couch_dbupdates` is a simple couchdb modules to receive databases
+events in couchdb node.
+
+It's actually **supported by all the [refuge](http://refuge.io) projects**:
+
+- [refuge](https://github.com/refuge/refuge)
+- [rcouch](https://github.com/refuge/rcouch)
+- [rcouch_template](https://github.com/refuge/rcouch_template)
+
+
+## HTTP API
+
+To get db events, do a GET to `/_db_updates` .
+
+You can pass an optional query parameters:
+
+* `feed` The feed can be `longpoll` (default) for longpolling, `eventsource`
+ for event stream or `continuous` for continuous feed.
+* `timeout`: timeout before the longpolling connection close or when the
+ heartbeat is emitted.
+* `heartbeat`: true, or false. an empty line is emittend when the
+ timeout occurs to maintain the connection active.
+
+
+## Example of usage
+
+ $ curl http://127.0.0.1:5984/_db_updates?feed=continuous
+ {"type":"created","db_name":"testdb"}
+ {"type":"updated","db_name":"testdb"}
+ {"type":"deleted","db_name":"testdb"}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/src/couch_dbupdates.app.src
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/src/couch_dbupdates.app.src b/src/couch_dbupdates/src/couch_dbupdates.app.src
new file mode 100644
index 0000000..c420283
--- /dev/null
+++ b/src/couch_dbupdates/src/couch_dbupdates.app.src
@@ -0,0 +1,11 @@
+{application, couch_dbupdates,
+ [
+ {description, ""},
+ {vsn, "@version@"},
+ {registered, []},
+ {applications, [
+ kernel,
+ stdlib
+ ]},
+ {env, []}
+ ]}.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/src/couch_dbupdates.erl
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/src/couch_dbupdates.erl b/src/couch_dbupdates/src/couch_dbupdates.erl
new file mode 100644
index 0000000..e37362f
--- /dev/null
+++ b/src/couch_dbupdates/src/couch_dbupdates.erl
@@ -0,0 +1,46 @@
+-module(couch_dbupdates).
+
+-export([handle_dbupdates/3]).
+
+
+handle_dbupdates(Fun, Acc, Options) ->
+ NotifierPid = db_update_notifier(),
+ try
+ loop(Fun, Acc, Options)
+ after
+ couch_db_update_notifier:stop(NotifierPid)
+ end.
+
+
+loop(Fun, Acc, Options) ->
+ [{timeout, Timeout}, {heartbeat, Heartbeat}] = Options,
+ receive
+ {db_updated, Event} ->
+ case Fun(Event, Acc) of
+ {ok, Acc1} ->
+ loop(Fun, Acc1, Options);
+ stop ->
+ Fun(stop, Acc)
+
+ end
+ after Timeout ->
+ case Heartbeat of
+ true ->
+ case Fun(heartbeat, Acc) of
+ {ok, Acc1} ->
+ loop(Fun, Acc1, Options);
+ stop ->
+ Fun(stop, Acc)
+
+ end;
+ _ ->
+ Fun(stop, Acc)
+ end
+ end.
+
+db_update_notifier() ->
+ Self = self(),
+ {ok, Notifier} = couch_db_update_notifier:start_link(fun(Event) ->
+ Self ! {db_updated, Event}
+ end),
+ Notifier.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ea18ecdf/src/couch_dbupdates/src/couch_dbupdates_httpd.erl
----------------------------------------------------------------------
diff --git a/src/couch_dbupdates/src/couch_dbupdates_httpd.erl b/src/couch_dbupdates/src/couch_dbupdates_httpd.erl
new file mode 100644
index 0000000..96058d3
--- /dev/null
+++ b/src/couch_dbupdates/src/couch_dbupdates_httpd.erl
@@ -0,0 +1,69 @@
+-module(couch_dbupdates_httpd).
+
+-export([handle_req/1]).
+
+-include_lib("couch_db.hrl").
+
+-record(state, {resp, feed}).
+
+handle_req(#httpd{method='GET'}=Req) ->
+ ok = couch_httpd:verify_is_server_admin(Req),
+ Qs = couch_httpd:qs(Req),
+ Feed = proplists:get_value("feed", Qs, "longpoll"),
+
+ Timeout = list_to_integer(
+ proplists:get_value("timeout", Qs, "60000")
+ ),
+
+ Heartbeat0 = proplists:get_value("heartbeat", Qs),
+ Heartbeat = case {Feed, Heartbeat0} of
+ {"longpoll", _} -> false;
+ {_, "false"} -> false;
+ _ -> true
+ end,
+
+ Options = [{timeout, Timeout}, {heartbeat, Heartbeat}],
+
+ {ok, Resp} = case Feed of
+ "eventsource" ->
+ Headers = [
+ {"Content-Type", "text/event-stream"},
+ {"Cache-Control", "no-cache"}
+ ],
+ couch_httpd:start_json_response(Req, 200, Headers);
+ _ ->
+ couch_httpd:start_json_response(Req, 200)
+ end,
+
+ State = #state{resp=Resp, feed=Feed},
+ couch_dbupdates:handle_dbupdates(fun handle_update/2,
+ State, Options).
+
+handle_req(Req, _Db) ->
+ couch_httpd:send_method_not_allowed(Req, "GET").
+
+handle_update(stop, #state{resp=Resp}) ->
+ couch_httpd:end_json_response(Resp);
+handle_update(heartbeat, #state{resp=Resp}=State) ->
+ {ok, Resp1} = couch_httpd:send_chunk(Resp, "\n"),
+ {ok, State#state{resp=Resp1}};
+handle_update(Event, #state{resp=Resp, feed="eventsource"}=State) ->
+ EventObj = event_obj(Event),
+ {ok, Resp1} = couch_httpd:send_chunk(Resp, ["data: ",
+ ?JSON_ENCODE(EventObj),
+ "\n\n"]),
+ {ok, State#state{resp=Resp1}};
+handle_update(Event, #state{resp=Resp, feed="continuous"}=State) ->
+ EventObj = event_obj(Event),
+ {ok, Resp1} = couch_httpd:send_chunk(Resp, [?JSON_ENCODE(EventObj) |
+ "\n"]),
+ {ok, State#state{resp=Resp1}};
+handle_update(Event, #state{resp=Resp, feed="longpoll"}) ->
+ {Props} = event_obj(Event),
+ JsonObj = {[{<<"ok">>, true} | Props]},
+ couch_httpd:send_chunk(Resp, ?JSON_ENCODE(JsonObj)),
+ stop.
+
+event_obj({Type, DbName}) ->
+ {[{<<"type">>, couch_util:to_binary(Type)},
+ {<<"db_name">>, couch_util:to_binary(DbName)}]}.
[2/2] git commit: updated refs/heads/master to 917d898
Posted by ja...@apache.org.
Merge branch '1684-feature-db-updates'
* 1684-feature-db-updates:
Import couch_dbupdates from rcouch.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/917d8988
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/917d8988
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/917d8988
Branch: refs/heads/master
Commit: 917d89884e3dc9317eba1728ec1702f88d2ba670
Parents: dfd2199 ea18ecd
Author: Jan Lehnardt <ja...@apache.org>
Authored: Mon Jul 22 12:29:42 2013 +0200
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Mon Jul 22 12:29:42 2013 +0200
----------------------------------------------------------------------
LICENSE | 6 ++
NOTICE | 2 +
configure.ac | 1 +
etc/couchdb/default.ini.tpl.in | 1 +
license.skip | 1 +
share/doc/src/api/misc.rst | 62 ++++++++++++++++++
src/Makefile.am | 1 +
src/couch_dbupdates/LICENSE | 22 +++++++
src/couch_dbupdates/Makefile.am | 33 ++++++++++
src/couch_dbupdates/NOTICE | 6 ++
src/couch_dbupdates/README.md | 32 +++++++++
src/couch_dbupdates/src/couch_dbupdates.app.src | 11 ++++
src/couch_dbupdates/src/couch_dbupdates.erl | 46 +++++++++++++
.../src/couch_dbupdates_httpd.erl | 69 ++++++++++++++++++++
14 files changed, 293 insertions(+)
----------------------------------------------------------------------