[PATCH] add documentation about backend naming for VMOD authors

[Poul-Henning Kamp]

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

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 ?)

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

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

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.

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?)

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.

Comments ?

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

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe    
Never attribute to malice what can adequately be explained by incompetence.