search

cognitect-labs / vase

Data driven microservices
Eclipse Public License 1.0
373 stars 42 forks source link

Clarify docs in template #70

Closed danielcompton closed 5 years ago

danielcompton commented 7 years ago

Description

The docstring in part of the vase template is ambiguous/hard to understand.

   ;; You can bring your own non-default interceptors. Make
   ;; sure you include routing and set it up right for
   ;; dev-mode. If you do, many other keys for configuring
   ;; default interceptors will be ignored.
   ;; ::http/interceptors []

https://github.com/cognitect-labs/vase/blob/bf96190bba7a7cc5efd92ea6f60503f0dc7800db/template/src/leiningen/new/vase/service.clj#L29-L33

There's three sentences here:

  1. You can bring your own non-default interceptors.
  2. Make sure you include routing and set it up right for dev-mode.
  3. If you do, many other keys for configuring default interceptors will be ignored.

It's not clear if they are separate or dependent.

1) I think I'm ok with, although I think it would be clearer to say "You can bring your own non-default interceptors to Vase" if that is the intent? Is 2) in relation to bringing non-default interceptors, or does it stand alone? I don't understand how 3) relates to 1) and 2) (if at all?).

Are you able to clarify this documentation section?

ohpauleez commented 7 years ago

Hi @danielcompton! Thanks for reaching out. In the future, you might consider posting questions like this to the Pedestal mailing list or #pedestal on the clojurians slack.

Hopefully I can bring some clarification. That section of code is the "service map" and is part of Pedestal itself. It describes all the settings/toggles for a given service running on a given platform (Jetty). Pedestal includes a collection of common interceptors by default, appropriately named "Default Interceptors" - you can see the code which has a descriptive docstring, or read through the reference docs.

Often times in a production setting you want more control over the default/initial interceptors, opting to specify your own collection of interceptors to use as the initial chain. The ::http/interceptors entry in the service map allows you to specify your own initial chain.

The docstring is saying: You don't need to use the default interceptors, you can specify your own initial chain here. Make sure that the router interceptor is included if your service should perform routing. If you specify your own initial interceptor chain here, the "default interceptors" are ignored and this initial chain will be used instead (e.g. ::http/routes is ignored, as are many other service map settings)

I'm leaving this open issue open because the docstring should be improved in Pedestal and should be altered (and more specific) in the Vase template.

danielcompton commented 7 years ago

Great, thanks! Much appreciated. I opened an issue 'cause it was part of code, but I'll bring doc things like this up on the mailing list next time.

ddeaguiar commented 5 years ago

I think the default-interceptors doc string is pretty clear about this point, it's just a matter of clarifying the comment in the Vase template.

ddeaguiar commented 5 years ago

Actually, this issue is no longer relevant as the service template has changed quite a bit since fern was introduced.