How to add a plugin?

[mikedeboer]

How to add a plugin?

[mikedeboer]

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 😉 ).

[johnjbarton]

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: 😉] ).

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

[mikedeboer]

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 😄

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]

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

[bedney]

@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!

[johnjbarton]

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

[bedney]

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//issues/68#issuecomment-14534011
.

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

#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//issues/68#issuecomment-14534011
.

[johnjbarton]

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:

#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//issues/68#issuecomment-14694479
.