[PATCH] add documentation about backend naming for VMOD authors

[Dridi Boukelmoune]

On Wed, Nov 4, 2015 at 11:40 AM, Poul-Henning Kamp <phk at phk.freebsd.dk> wrote:
> --------
> In message <563894B7.1020904 at uplex.de>, Geoff Simmons writes:
>
>>> Why not keep VRT_new_backend as the only interface for VMODs and
>>> allow this one to fail? (or do the atomic auto-renaming if needed)
>>
>>Um, VRT_new_backend creates a conventional backend (HTTP over TCP)
>>from a vrt_backend config. What if you want to do something entirely
>>different?
>
> Ok, I think we need to wrap this discussion up and move on.
>
> My conclusion for the 5.x perspective is the following:
>
> 1. Our terminology sucks, in particular the director/backend confusion.

Agreed.

> 2. We will not force all directors/backends to appear in CLI/VSC
>         a) Backends defined in VCL -> always listed
>         b) Backends/directors created by VMODS -> vmod decides.
>                 I think it still makes sense to register the
>                 be/dir with the VRT, in order to get the same
>                 cleanup-behaviour.  A flag on the VRT call will
>                 mark it as "unlisted" and disable VSC allocation.
>                 (Or malloc dummy VSC to reduce special-casing ?)

Sounds good.

> 3. Setting non-HTTP directors sick/healthy from CLI makes sense

It does, which means we'd need to make this check in varnishd before
asking the backend. That may already be the case.

> 4. Directors/backends created by VMODs should be tagged so it can
>    be seen in CLI which VMOD created them.  (Possibly also line# ?)

Why not.

It could be something carried by a VRT_CTX, set up by the VCC. Of
course nothing prevents a vmod author to build a context without the
vmod tag/field so it would need to be properly documented.

> 5. The VRT code will take a "unique name" flag argument.
>    When unset, that code will uniqu-ify the backend name with a
>    ".%u" suffix if necessary.  When set the call will fail if a
>    backend already exists with that name.

Why not. It could be useful if combined with 4 for error logging.

> 6. We should support health probing for non-http directors.
>    Some of the bitmaps apply only to HTTP based directors.
>    The overkill version would be for the director to tell which
>    and how many bitmaps it wants to record for health-probes.
>    That could massively complicate VSC handling.
>    A "sneaky" way would be to have VSC contain a fixed number
>    of bitmaps, and let the director name these.  This "only"
>    require a place to stash the names and varnishstat code to
>    pull that info out (A per director implementation VSC segment?)

I suggest the probe would use the director's functions, just like a
bereq. But we'd need to also tell the director not to try recycling a
connection for instance.

> 7. struct VSC_C_vbe seems to be general enough that it makes sense
>    for any kind of director, so there is no point in decoupling
>    CLI/VSC.  The be->vsc pointer needs to be moved up to the
>    director structure.  This may be more messy than it sounds.

Small nitpick, it has a conn field and as you pointed out, we could
have connection-less directors.

> Comments ?
>
> (After this is settled, we'll look at which parts we can also
> put in 4.1.x in ABI/API compatible ways)

Sounds like a good plan!

Best,
Dridi