jsDAV icon indicating copy to clipboard operation
jsDAV copied to clipboard

How to add a plugin?

Open johnjbarton opened this issue 11 years ago • 9 comments

The jsDAV server seems to support 'plugins', but I have not been able to figure out how to get them to work.

I tried adding an options.plugins but once I read the code it seems that this object is some sort of filter on the DEFAULT_PLUGINS (that alone is very confusing).

Then I tried

jsDAV.createServer({
    node: __dirname + "/..",
    locksBackend: new jsDAV_Locks_Backend_FS(__dirname + "/jsDAV_locks_8686")
}, 8686).plugins.CORS_Plugin = jsDAV_CORS_Plugin;

No luck. I could not find any doc pages or online info.

johnjbarton avatar Jan 04 '13 00:01 johnjbarton

Hi John, this feature is indeed undocumented at the moment.

I understand that the plugin system may appear as confusing, but allow me to explain:

The DEFAULT_PLUGINS is a map, populated at the first require() of server.js with the plugins bundled inside the lib/DAV/plugins/ folder. If you put your plugin inside that folder, it will load automatically.

If you want to use a plugin that is located some place other than the plugins folder of jsDAV - which is quite common, because jsDAV is often used as a module dependency within projects - you can do something like this:

var jsDAV = require("jsdav/lib/jsdav");
var jsDAV_Server = require("jsdav/lib/DAV/server");
var jsDAV_Util = require("jsdav/lib/shared/util");

jsDAV.createServer({
    node: __dirname + "/..",
    plugins: jsDAV_Util.extend(jsDAV_Server.DEFAULT_PLUGINS, {
        "cors": require("./cors")
    })
});

This takes the bundled plugins and combines them with the one you wrote. Additionally, you can forget about the defaults and hand-pick all plugins.

Next up is how to start writing your own plugin, but that's a story that goes a bit further than your question, which I hope I answered (if I did, I will add this to the wiki :wink: ).

mikedeboer avatar Jan 04 '13 21:01 mikedeboer

Thanks! Indeed, I guessed that I could add a file to the folder but wanted to avoid writing in the jsDAV source space.

FWIW, the biggest question I had about implementing plugins was the lifetime: eg when are they created and called? Also, the |server| argument confused me, I tried to add a node-like listener to it but it was not called. Later I realized I needed to use the handler API.

On Fri, Jan 4, 2013 at 1:06 PM, Mike de Boer [email protected]:

Hi John, this feature is indeed undocumented at the moment.

It understand that the plugin system may appear as confusing, but allow me to explain:

The DEFAULT_PLUGINS is a map, populated at the first require() of server.js with the plugins bundled inside the lib/DAV/plugins/ folder. If you put your plugin inside that folder, it will load automatically.

If you want to use a plugin that is located some place other than the plugins folder of jsDAV - which is quite common, because jsDAV is often used as a module dependency within projects - you can do something like this:

var jsDAV = require("jsdav/lib/jsdav");var jsDAV_Server = require("jsdav/lib/DAV/server");var jsDAV_Util = require("jsdav/lib/shared/util"); jsDAV.createServer({ node: __dirname + "/..", plugins: jsDAV_Util.extend(jsDAV_Server.DEFAULT_PLUGINS, { "cors": require("./cors") })});

This takes the bundled plugins and combines them with the one you wrote. Additionally, you can forget about the defaults and hand-pick all plugins.

Next up is how to start writing your own plugin, but that's a story that goes a bit further than your question, which I hope I answered (if I did, I will add this to the wiki [image: :wink:] ).

— Reply to this email directly or view it on GitHubhttps://github.com/mikedeboer/jsDAV/issues/68#issuecomment-11899830.

johnjbarton avatar Jan 05 '13 22:01 johnjbarton

I see the confusion... so far I was lucky enough that my direct colleagues or I were the only ones who wanted to create plugins :smile:

The lifetime of plugins is the following:

  1. The server object is created once, will be resident during the lifetime of the node process. It fires up the HTTP server (if used standalone) and dispatches incoming requests. It also keeps a reference to the plugin objects, so the handler object can find them efficiently.
  2. When a request comes in at the server, it instantiates a new handler, to which the request is passed along. The handler is responsible for handling the request and the response to it. The lifetime of a handler object is parallel to the lifetime of the response object. Upon instantiation, the handler also instantiates each and every plugin. In other words: the lifetime of a plugin is parallel to the handler, thus parallel to the response object.

An important note is that the handler indeed emits events, but it's not the NodeJS EventEmitter. Instead I use something that I 'invented': asynchronous events. I wanted the plugins to hook into the system through a signal-slot type of connection, but these plugins are very likely to perform asynchronous operations and that doesn't match with the synchronous EventEmitter object provided by NodeJS' events module. Therefore I created an async-capable EventEmitter that mirrors the NodeJS API, which simply adds two simple functions to the Event object: next() and stop(). A good example that shows off this API at work can be found at https://github.com/mikedeboer/jsDAV/blob/master/lib/DAV/plugins/browser.js

I hope this explains it a bit for ya!

mikedeboer avatar Jan 07 '13 12:01 mikedeboer

@johnjbarton I just published a new version of jsDAV: v0.3.0, which includes an entirely revamped object inheritance model, DAVACL and CardDAV (address book) support. Another goal for this version and onward is improved end-user documentation. I will explain how to use and extend jsDAV in more detail on the wiki soon.

If you have any questions, please feel free to drop me a line.

mikedeboer avatar Feb 22 '13 18:02 mikedeboer

@johnjbarton - Sorry to spam this issue, but your post here intrigued me. Are you adding CORS support to jsDAV? If so, are you going to make this publicly available. I have a great interest in this! :-).

Thanks!

bedney avatar Mar 06 '13 21:03 bedney

I started, but the problem I was working around stopped failing, so I stopped. This area is not my focus so as it turns out I left my experimental code around. It may hurt more than help, but here:

https://github.com/google/qpp/blob/master/http/DAVServer.js

johnjbarton avatar Mar 06 '13 23:03 johnjbarton

I'll give it a shot.

Thanks you, sir!

On Wed, Mar 6, 2013 at 5:47 PM, johnjbarton [email protected]:

I started, but the problem I was working around stopped failing, so I stopped. This area is not my focus so as it turns out I left my experimental code around. It may hurt more than help, but here:

https://github.com/google/qpp/blob/master/http/DAVServer.js

— Reply to this email directly or view it on GitHubhttps://github.com/mikedeboer/jsDAV/issues/68#issuecomment-14534011 .

bedney avatar Mar 07 '13 02:03 bedney

Not to keep hijacking this thread John, but I made your code work under the 0.3.0 plugin architecture and have submitted a pull request to Mike here:

https://github.com/mikedeboer/jsDAV/pull/73

If this is not OK, please let me know and I'll throw it out.

Cheers,

  • Bill

On Wed, Mar 6, 2013 at 8:07 PM, William Edney [email protected]:

I'll give it a shot.

Thanks you, sir!

On Wed, Mar 6, 2013 at 5:47 PM, johnjbarton [email protected]:

I started, but the problem I was working around stopped failing, so I stopped. This area is not my focus so as it turns out I left my experimental code around. It may hurt more than help, but here:

https://github.com/google/qpp/blob/master/http/DAVServer.js

— Reply to this email directly or view it on GitHubhttps://github.com/mikedeboer/jsDAV/issues/68#issuecomment-14534011 .

bedney avatar Mar 11 '13 01:03 bedney

Cool, thanks for letting men know.

jjb

On Sun, Mar 10, 2013 at 6:58 PM, William J. Edney [email protected]:

Not to keep hijacking this thread John, but I made your code work under the 0.3.0 plugin architecture and have submitted a pull request to Mike here:

https://github.com/mikedeboer/jsDAV/pull/73

If this is not OK, please let me know and I'll throw it out.

Cheers,

  • Bill

On Wed, Mar 6, 2013 at 8:07 PM, William Edney [email protected]:

I'll give it a shot.

Thanks you, sir!

On Wed, Mar 6, 2013 at 5:47 PM, johnjbarton [email protected]:

I started, but the problem I was working around stopped failing, so I stopped. This area is not my focus so as it turns out I left my experimental code around. It may hurt more than help, but here:

https://github.com/google/qpp/blob/master/http/DAVServer.js

— Reply to this email directly or view it on GitHub< https://github.com/mikedeboer/jsDAV/issues/68#issuecomment-14534011> .

— Reply to this email directly or view it on GitHubhttps://github.com/mikedeboer/jsDAV/issues/68#issuecomment-14694479 .

johnjbarton avatar Mar 11 '13 02:03 johnjbarton