[PATCH] add documentation about backend naming for VMOD authors

[Poul-Henning Kamp]

--------
In message <CABoVN9Ch55NOui_23_10x0Sr4Swm_cSi91xiO9aYGLx7ppBM6g at mail.gmail.com>, Dridi Bouke
lmoune writes:

>> * All "struct director" (= VCL_BACKEND) have a "vcl_name" which can
>>   be queried from VCL.  VMODs are responsible for doing something
>>   sensible here.
>
>Sounds good.
>
>> * struct director without a struct backend do not appear in CLI/VSM
>>   unless the VMOD implements all the stuff for this.
>
>Sounds good, though I don't know how to implement it.

It would have to be a very magical case before it *should* be
implemented.

>> * struct director with a struct backend, defined in VCL is always
>>   in CLI/VSM, and the vcl_name is the name from the VCL namespace.
>
>Sounds good, and for static backends defined in plain native vcl,
>backend.display_name == vcl.loaded_name + "." + director.vcl_name

*All* backend names has the from "$VCL.something"

>> * struct director with a struct backend, created by VMOD, may or
>>   may not be in CLI/VSM, at the VMODs discretion.
>
>They are currently always in the CLI/VSM, and this is controlled by
>the VCL temperature changes. But I think a struct director with a
>struct backend should always show up in the CLI/VSM.

It probably should *almost* always show up, but there are valid
schenarios where a struct backend is good for a single request
and I can see why you wouldn't want to clutter CLI/VSM with that.

>> * If it is in CLI/VSM, the VRT() used to register it there may
>>   modify the vcl_name to make sure it is globally unique.
>>   (In practice: vcl-unique, because the namespace is $VCL.$BACKEND)
>
>Since the CLI/VSM only show backends (not director) that would be the
>backend's display_name. That is the part I'm not comfortable with, for
>end-users.

I understand that, but I think the alternative, failing backend creation
unpredictably (as seen from the VMOD) is worse.

>> * If the VMOD ensures there are no duplicate vcl_names in the
>>   first place, the vcl_name will not be touched.
>
>The VMOD can enforce proper uniqueness, but can't prevent against name
>collisions from other VMODs.

... which is why the VRT function will have to step in.

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