diff options
author | Jan Lehnardt <jan@apache.org> | 2013-07-31 19:00:21 +0200 |
---|---|---|
committer | Jan Lehnardt <jan@apache.org> | 2013-08-02 21:17:03 +0200 |
commit | 2bf883f256fefbf20be6da88dceac09768129828 (patch) | |
tree | 552b16700db2c04c5583d60b19b0e8e8a401cd1e | |
parent | 5c90e028388c8451586348f54a35f8e0a19cb365 (diff) | |
download | couchdb-2bf883f256fefbf20be6da88dceac09768129828.tar.gz |
add readme
-rw-r--r-- | src/couch_plugins/README.md | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/src/couch_plugins/README.md b/src/couch_plugins/README.md new file mode 100644 index 000000000..58ad29640 --- /dev/null +++ b/src/couch_plugins/README.md @@ -0,0 +1,164 @@ +Heya, + +I couldn’t help myself thinking about plugin stuff and ended up +whipping up a proof of concept. + +Here’s a <1 minute demo video: + + https://dl.dropboxusercontent.com/u/82149/couchdb-plugins-demo.mov + + (alternative encoding: https://dl.dropboxusercontent.com/u/82149/couchdb-plugins-demo.m4v) + + +In my head the whole plugin idea is a very wide area, but I was so +intrigued by the idea of getting something running with a click on a +button in Futon. So I looked for a minimally viable plugin system. + + +## Design principles + +It took me a day to put this all together and this was only possible +because I took a lot of shortcuts. I believe they are all viable for a +first iteration of a plugins system. + +1. Install with one click on a button in Futon (or HTTP call) +2. Only pure Erlang plugins are allowed. +3. The plugin author must provide a binary package for each Erlang (and + later each CouchDB version). +4. Complete trust-based system. You trust me to not do any nasty things + when you click on the install button. No crypto, no nothing. Only + people who can commit to Futon can release new versions of plugins. +5. Minimal user-friendlyness: won’t install plugins that don’t match + the current Erlang version. +6. Require a pretty strict format for binary releases. + +## Roadmap + +Here’s a list of things this first iterations does and doesn’t do: + +- Pure Erlang plugins only. No C-dependencies, no JavaScript, no nothing. +- No C-dependencies. +- Install a plugin via Futon (or HTTP call). Admin only. +- A hardcoded list of plugins in Futon. +- Loads a pre-packaged, pre-compiled .tar.gz file from a URL. +- Only installs if Erlang version matches. +- No security checking of binaries. +- No identity checking of binaries. + +Here are a few things I want to add before I call it MVP: + +- Uninstall a plugin via Futon (or HTTP call). Admin only. +- Only installs if CouchDB version matches. +- Binaries must be published on *.apache.org. +- Register installed plugins in the config system. +- Make sure plugins start with the next restart of CouchDB. + +*MVP hopefully means you agree we can ship this with a few warnings +so people can get a hang of it. + +Here is a rough list of features squared against future milestones: + +Milestone 2: Be creator friendly + - Make it easy to build a CouchDB plugin by providing one or more easy + to start templates. + - Make it easy to publish new plugins and new versions of existing plugins. + - Make it easy to supply packages for multiple Erlang & CouchDB versions. + +Milestone 3: Public registry + - Instead of hardcoding a list of plugins into Futon/Fauxton, we load + a list of applicable plugins from a central (and configurable) + plugins repository. + - This allows plugin authors to publish new plugins and new versions + of existing plugins independently. + +Milestone 4: Other Languages + - Figure out how to handle C-dependencies for Erlang plugins. + - Figure out how to allow other language plugins + (c.f. non-JS query servers) + +Milestone X: Later + - Add some account/identity/maybe crypto-web-of-trust system for + authors to publish “legit” plugins. + - Sign & verify individual releases + +A few more things that can happen concurrently depending on what +plugins require: + - integrate Erlang/JS tests in the installation + - integrate docs + +## How it works + +This plugin system lives in src/couch_plugins and is a tiny CouchDB +module. + +It exposes one new API endpoint `/_plugins` that an admin user can +POST to. + +The additional Futon page lives at /_utils/plugins.html it is +hardcoded. + +Futon (or you) post an object to `/_plugins` with four properties: + + { + "name": "geocouch", // name of the plugin, must be unique + "url": "http://people.apache.org/~jan", // “base URL” for plugin releases (see below) + "version": "couchdb1.2.x_v0.3.0-11-gd83ba22", // whatever version internal to the plugin + "checksums": { + "R15B03": "ZetgdHj2bY2w37buulWVf3USOZs=" // base64’d sha hash over the binary + } + } + +`couch_plugins` then attempts to download a .tar.gz from this +location: + + http://people.apache.org/~jan/geocouch-couchdb1.2.x_v0.3.0-12-g4ea0bea-R15B03.tar.gz + +(this url is live, feel free to play around with this tarball). + +Next it calculates the sha hash for the downloaded .tar.gz file and +matches it against the correct version in the `checksums` parameter. + +If that succeeds, we unpack the .tar.gz file (currently in `/tmp`, +need to find a better place for this) and adds the extracted directory +to the Erlang code path +(`code:add_path("/tmp/couchdb_plugins/geocouch-couchdb1.2.x_v0.3.0-12-g4ea0bea-R15B03/ebin")`) +and loads the included application (`application:load(geocouch)`) + +Then it looks into the `./config` directory that lives next to `ebin/` +in the plugin directory for a file `config.erlt` (“erl-terms”). with a +list of configuration parameters to load. We parse the file and set +the config directives one by one. + +If that all goes to plan, we report success back to the HTTP caller. + +That’s it! :) + +It’s deceptively simple, probably does a few things very wrong and +leaves a few things open (see above). + +One open question I’d like an answer for is finding a good location to +unpack & install the plugin files that isn’t `tmp`. If the answer is +different for a pre-BigCouch/rcouch-merge and +post-BigCouch/rcouch-merge world, I’d love to know :) + + +## Code + +The main branch for this is 1867-feature-plugins: + + ASF: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=log;h=refs/heads/1867-feature-plugins + GitHub: https://github.com/janl/couchdb/compare/1867-feature-plugins + +I created a branch on GeoCouch that adds a few lines to its `Makefile` +that shows how a binary package is built: + + https://github.com/janl/geocouch/compare/couchbase:couchdb1.3.x...couchdb1.3.x-plugins + + +Please comment and improve heavily. + +If you have any criticism, please phrase it in a way that we can use +to improve this. + +Cheers +Jan |