Add metadata to resources, and the ability to find them by path

[mstade]

This adds the option of adding a metadata object when registering
a resource definition. The metadata won't actually be used, other
than returned when calling web.find which is a new method to
find resource definitions by path as opposed to by name.

[mstade]

My opinion on this is that it's a stop gap solution until something like #8 comes around. It'll do for now, but really nap should practice what it preaches.

[mstade]

From some offline discussions with @aaronhaines we may actually want to implement this in rhumb instead, and simply expose the match method of rhumb on nap. Again as a stop gap in lieu of #8, but anyway.

[mstade]

HTTP defines the OPTIONS method, which is intended to provide the caller with information on what communication options are available to them. As far as I can tell, the spec doesn't disallow a body, and obviously the response has headers and all that (notably the Allow header which tells us which methods are available to the consumer.)

I'd be keen to implement this in nap, instead of the find function above. However, this would also mean that nap would start moving into the territory of defining methods – this is really a protocol decision and not one that nap should take. As far as I know, the REST dissertation doesn't actually define any methods that a RESTful protocol should implement, however it implies that at the very least you should be able to GET a resource. (Whether it's actually called GET or something else is, I suppose, a different matter entirely.) To that point, I think it would make sense for nap to then also provide the ability to inspect a resource by virtue of the OPTIONS method. We're already assuming that a method-less request should default to GET, so nap has already decided that any protocol implementation should support GET; we could do the same for OPTIONS.

I'd prefer that over a find function, it's nicely extensible as well. Not sure what to call the method though, so as not to reserve the OPTIONS name.

[mstade]

Thinking about this some more, it makes a lot of sense for nap to transition into registering resources via requests, much like what is described in #8. For instance, this would neatly give us a method by which we can extensibly provide resource metadata, as well as the ability to at runtime add, modify, and even remove resources (authorization can be implemented via middleware, and should be a protocol concern.)

With regards to the naming of methods, we can neatly sidestep this by adding (rudimentary) protocol support in the URI resolution:

web.req(
  { method: 'PUT', uri: 'nap:/my/{resource}'
  , headers: { allow: ['GET', 'POST'] }
  }
)

As well, to find what options are available in nap-land:

web.req({ method: 'OPTIONS', uri: 'nap:/my/{resource}' }, function(err, res) {
  // res holds information about the resource at /my/{resource}
})

In effect, nap: would be the only protocol allowed outside of whatever protocol is implemented otherwise. This is just to disambiguate, not any way to add any real protocol support. That could be done anyway either through middleware, or by wrapping nap, so no reason really to get too fancy I don't think. Unless, of course, we change the middleware stack to provide different middleware for different protocols... Hmm, interesting thought..

[Poetro]

👍

[coveralls]

Coverage increased (+0.1%) to 98.438% when pulling b5a7098 on resource-metadata into ef8ba85 on master.

[coveralls]

Coverage increased (+0.1%) to 98.438% when pulling d86af35 on resource-metadata into ef8ba85 on master.