[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