[PATCH] add documentation about backend naming for VMOD authors

[Dridi Boukelmoune]

>>[...]
>>
>>Crossing fingers that this time I'm making some sense.
>
> Not really.
>
> VMOD objects are only usable if you know the number of such backends
> at the time you write your VCL code.
>
> What about VMODs that create an unknown number of backends ?

Last try, after that I give up.

I tried to answer that point in the "[...]" part but obviously that didn't
work. If we eventually come to mutual understanding by the way,
I can later update the documentation to clarify this point and provide
better guidance to VMOD writers.

If you use the vcl_name of a VMOD object, you have the guarantee that
this name won't conflict with an existing backend:

**** v1    0.1 CLI RX| Message from VCC-compiler:\n
**** v1    0.1 CLI RX| Object name 's1' already used.\n
**** v1    0.1 CLI RX| First usage:\n
**** v1    0.1 CLI RX| ('input' Line 2 Pos 9)\n
**** v1    0.1 CLI RX| backend s1 { .host = "127.0.0.1"; .port = "41338"; }\n
**** v1    0.1 CLI RX| --------##------------------------------------------\n
**** v1    0.1 CLI RX| \n
**** v1    0.1 CLI RX| Redefinition:\n
**** v1    0.1 CLI RX| ('input' Line 8 Pos 21)\n
**** v1    0.1 CLI RX|                 new s1 = named.director("localhost", "...
**** v1    0.1 CLI RX| --------------------##--------------------------------

I believe we already agree on this bit, but I wanted to emphasize it

Backends can only be named using [0-9a-zA-Z_] so a director creating
an unknown number of backends (like vmod-named by the way) should
implement its own suffix starting with an "illegal" character (so that you
don't accidentally end up with the name of another backend).

The VMOD author can pick a ".%d" suffix like the one you suggested
Varnish could use, or "(%s)" like I do with vmod-named or anything
else that may have more meaning to the end-user. If all VMODs use a
unique name as the basis, and a conflict-free naming scheme, the
problem disappears.

Regex-ish pattern: (.+)\.(.+)([^0-9a-zA-Z_])(.+)

Groups:
- name of the vcl
- vmod object's "vcl_name"
- "illegal" separator
- uniqueness bit

Example in vmod-named's test suite:
https://github.com/dridi/libvmod-named/blob/43798d7/src/tests/test01.vtc#L26

VMOD authors have enough tools as of today to ensure uniqueness of
their dynamic backends names, regardless of the number of backends
they create and when they are creating, therefore I want to shift the
responsibility to said VMOD authors and properly document it.

This is also why I'm fine with a plain panic instead of a new function
like VCL_HasBackend.

Best,
Dridi