Docs and cleanup

[bajtos]

1) API cleanup

Rename "per-request-context" middleware to shorter "per-request".

Introduce "LoopBackContext.perRequest" as a shortcut for way too long
"loopback-context/server/middlewar/per-request"

2) Add big fat warning to README

The module node-continuation-local-storage is known to have many problems, see e.g. issue #59. As a result, loopback-context does not work in many situations, as can be seen from issues reported in LoopBack's issue tracker.

We recommend AGAINST using this module.

If you are running on Node v6, you can try the new alternative cls-hooked.

@raymondfeng@ritch please review

Connect to strongloop-internal/scrum-loopback#989.

[ritch]

We need another alternative that doesn't use CLS at all.

[bajtos]

We need another alternative that doesn't use CLS at all.

Agreed!

[ritch]

LGTM

@crandmck we'll need to update the docs to mention this module.

[bajtos]

@crandmck I edited https://docs.strongloop.com/display/APIC/Using+current+context myself. PTAL and make any improvements as you deem it fit.

[crandmck]

Thanks for doing that @bajtos! I'll make an edit pass.