[master] c6e3d6b5b param: Infrastructure for deprecated aliases
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Mon Dec 13 17:08:09 UTC 2021
commit c6e3d6b5b91c81ff075112c3008940d15b201ad1
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Mon Dec 13 08:47:48 2021 +0100
param: Infrastructure for deprecated aliases
With this change, we can formalize the renaming of a parameter while
maintaining the old name temporarily for compatibility.
A deprecated alias can be set with either param.set or the -p option,
but won't be listed by:
- param.show [-j]
- param.show [-j] changed
- param.show -l
Only an explicit param.show for the name of the alias will provide a
minimal documentation with a deprecation notice and the current value.
In the manual, there is only a deprecation notice. The rationale is
that administration tools shouldn't pick them up when enumerating the
parameters.
Since we currently don't have deprecated parameters, this can only be
tested manually, for example:
PARAM_ALIAS(vcl_dir, vcl_path)
To ensure that we don't break this, we could consider having a perpetual
deprecated parameter.
diff --git a/bin/varnishd/mgt/mgt_param.c b/bin/varnishd/mgt/mgt_param.c
index dff2ea78d..3502e2820 100644
--- a/bin/varnishd/mgt/mgt_param.c
+++ b/bin/varnishd/mgt/mgt_param.c
@@ -262,6 +262,10 @@ mcf_param_show(struct cli *cli, const char * const *av, void *priv)
pp = pl->spec;
if (lfmt && strcmp(pp->name, av[2]) && strcmp("-l", av[2]))
continue;
+ if (pp->func == tweak_alias && !lfmt)
+ continue;
+ if (pp->func == tweak_alias && strcmp(pp->name, av[2]))
+ continue;
n++;
VSB_clear(vsb);
@@ -383,6 +387,10 @@ mcf_param_show_json(struct cli *cli, const char * const *av, void *priv)
pp = pl->spec;
if (show != NULL && strcmp(pp->name, show) != 0)
continue;
+ if (pp->func == tweak_alias && show == NULL)
+ continue;
+ if (pp->func == tweak_alias && strcmp(pp->name, show))
+ continue;
n++;
VSB_clear(vsb);
@@ -622,6 +630,13 @@ mcf_wash_param(struct cli *cli, struct parspec *pp, enum mcf_which_e which,
}
AN(val);
+ if (pp->func == tweak_alias) {
+ assert(which == MCF_DEFAULT);
+ pp->priv = mcf_findpar(pp->def);
+ pp->def = NULL;
+ return;
+ }
+
VSB_clear(vsb);
VSB_printf(vsb, "FAILED to set %s for param %s: %s\n",
name, pp->name, val);
diff --git a/bin/varnishd/mgt/mgt_param.h b/bin/varnishd/mgt/mgt_param.h
index f31fc1078..f3af67df5 100644
--- a/bin/varnishd/mgt/mgt_param.h
+++ b/bin/varnishd/mgt/mgt_param.h
@@ -66,6 +66,7 @@ struct parspec {
char *dyn_def;
};
+tweak_t tweak_alias;
tweak_t tweak_boolean;
tweak_t tweak_bytes;
tweak_t tweak_bytes_u;
diff --git a/bin/varnishd/mgt/mgt_param_tweak.c b/bin/varnishd/mgt/mgt_param_tweak.c
index 776439959..526fcf64e 100644
--- a/bin/varnishd/mgt/mgt_param_tweak.c
+++ b/bin/varnishd/mgt/mgt_param_tweak.c
@@ -527,3 +527,15 @@ tweak_storage(struct vsb *vsb, const struct parspec *par, const char *arg)
}
return (tweak_string(vsb, par, arg));
}
+
+/*--------------------------------------------------------------------
+ * Tweak alias
+ */
+
+int v_matchproto_(tweak_t)
+tweak_alias(struct vsb *vsb, const struct parspec *par, const char *arg)
+{
+
+ par = TRUST_ME(par->priv);
+ return (par->func(vsb, par, arg));
+}
diff --git a/include/tbl/params.h b/include/tbl/params.h
index e316a4eab..48b89aa76 100644
--- a/include/tbl/params.h
+++ b/include/tbl/params.h
@@ -1641,6 +1641,21 @@ PARAM_PCRE2(
" messages."
)
+/*--------------------------------------------------------------------
+ * Parameter deprecated aliases
+ *
+ * When a parameter is renamed, but the a deprecated alias is kept for
+ * compatibility, its documentation is minimal: only a description in
+ * manual pages, a description and current value in the CLI.
+ */
+
+#define PARAM_ALIAS(al, nm) \
+ PARAM(, , al, tweak_alias, NULL, NULL, NULL, #nm, NULL, \
+ "Deprecated alias for the " #nm " parameter.")
+
+/* PARAM_ALIAS(old, new) */
+
+# undef PARAM_ALIAS
# undef PARAM_ALL
# undef PARAM_PCRE2
# undef PARAM_STRING
More information about the varnish-commit
mailing list