sdk: typed varargs (#563)

NB: this is analogous to #254 , but rebased and simplified

sdk: typed varargs + required explicit arity

Introduce typed C++ wrappers for varargs VDFs (vsql::VarArgs, vsql::AnyArg)
and the matching .varargs() / zero-arity .param() builder methods, so an
extension author can write a variadic SQL function without touching raw ABI
types. Also tightens the v2 builder to require an explicit arity
declaration before .build().

What changes for users
Before, an extension author who wanted a varargs SQL function had to drop
out of the typed SDK and write a raw-ABI body — the typed wrappers covered
fixed-arity only:

// Old: raw vef_vdf_func_t signature, manual invalue extraction
void ba_concat_all(vef_context_t *ctx, vef_vdf_args_t *args,
                   vef_vdf_result_t *result) {
  for (unsigned int i = 0; i < args->value_count; i++) {
    vef_invalue_t v = vsql::func_builder::get_invalue(ctx, args, i);
    if (v.is_null) { result->type = VEF_RESULT_NULL; return; }
    memcpy(result->str_buf + i * N, v.bin_value, N);
  }
  result->type = VEF_RESULT_VALUE;
  result->actual_len = args->value_count * N;
}
After:

// New: typed VarArgs + AnyArg, no raw ABI in the body
void ba_concat_all(vsql::VarArgs args, vsql::StringResult out) {
  auto dst = out.buffer();
  size_t off = 0;
  for (auto a : args) {
    if (a.is_null()) { out.set_null(); return; }
    auto bytes = a.as_custom();
    memcpy(dst.data() + off, bytes.data(), bytes.size());
    off += bytes.size();
  }
  out.set_length(off);
}
Registration picks up .varargs() (and zero-arity .param()):

.func(make_func<&ba_len>("ba_len")
          .returns(INT)
          .param()                     // explicit zero-arity
          .build())
.func(make_func<&ba_concat_all>("ba_concat_all")
          .returns(STRING)
          .varargs()
          .prerun<&ba_concat_all_prerun>()
          .build())
The prerun hook is still raw ABI in this PR; the typed variant lands with
#551 (typed vsql::PrerunArgs / PrerunResult), and ba_concat_all_prerun
will convert to typed form when that merges.

Required-arity change
The v2 builder now rejects make_func<&fn>("name").returns(...).build()
without an arity call. You must pick exactly one of:

.param(TYPE) (one or more, for fixed-arity typed args)
.param() (zero-arity)
.varargs()
Eight in-tree test-extensions had implicit zero-arity functions and pick
up an explicit .param() in this PR. The v1 builder
(villagesql::func_builder, raw-ABI) is unchanged — that cow has left
the barn.

Author: dbentley-vsql

mysql-test/suite/villagesql/extension/r/extension_simple_type_usage.result

@@ -68,6 +68,46 @@ FROM test_bytearray t1, test_bytearray t2
 WHERE t1.id = 1 AND t2.id = 2;
 concatenated
 'hello   world123'
+# Test ba_len function (zero-arity, returns a constant)
+SELECT vsql_simple.ba_len() AS len;
+len
+8
+# ba_concat (declared with two params) rejects a single-arg call
+SELECT vsql_simple.ba_concat(t.data) FROM test_bytearray t WHERE t.id = 1;
+ERROR HY000: Cannot initialize function 'ba_concat': wrong number of arguments (expected 2, got 1)
+# Test ba_concat_all function (varargs, returns STRING)
+SELECT vsql_simple.ba_concat_all(t.data) AS one
+FROM test_bytearray t WHERE t.id = 1;
+one
+hello   
+SELECT vsql_simple.ba_concat_all(t1.data, t2.data, t3.data) AS three
+FROM test_bytearray t1, test_bytearray t2, test_bytearray t3
+WHERE t1.id = 1 AND t2.id = 2 AND t3.id = 3;
+three
+hello   world123abcdefgh
+SELECT CONCAT("'", vsql_simple.ba_concat_all(t1.data, t2.data, t3.data), "'") AS three
+FROM test_bytearray t1, test_bytearray t2, test_bytearray t3
+WHERE t1.id = 1 AND t2.id = 2 AND t3.id = 3;
+three
+'hello   world123abcdefgh'
+# ba_concat_all rejects zero arguments via prerun
+SELECT vsql_simple.ba_concat_all();
+ERROR HY000: Can't initialize function 'ba_concat_all'; ba_concat_all requires at least one argument
+# ba_concat_all rejects non-BYTEARRAY arguments via prerun
+SELECT vsql_simple.ba_concat_all(1);
+ERROR HY000: Can't initialize function 'ba_concat_all'; ba_concat_all: argument 0 must be BYTEARRAY
+# ba_concat_all propagates NULL
+SELECT vsql_simple.ba_concat_all(t1.data, NULL) AS with_null
+FROM test_bytearray t1 WHERE t1.id = 1;
+with_null
+NULL
+# ba_concat_all treats a non-NULL STRING literal as NULL: prerun lets
+# STRING through so NULL literals (typed STRING) work, but cannot
+# distinguish them from real strings, so the body checks is_custom().
+SELECT vsql_simple.ba_concat_all(t1.data, 'abc') AS with_str
+FROM test_bytearray t1 WHERE t1.id = 1;
+with_str
+NULL
 # Clean up
 DROP TABLE test_bytearray;
 # Uninstall the extension

mysql-test/suite/villagesql/extension/t/extension_simple_type_usage.test

@@ -44,6 +44,41 @@ SELECT CONCAT("'", vsql_simple.ba_concat(t1.data, t2.data), "'") as concatenated
 FROM test_bytearray t1, test_bytearray t2
 WHERE t1.id = 1 AND t2.id = 2;
 
+--echo # Test ba_len function (zero-arity, returns a constant)
+SELECT vsql_simple.ba_len() AS len;
+
+--echo # ba_concat (declared with two params) rejects a single-arg call
+--error ER_VILLAGESQL_GENERIC_ERROR
+SELECT vsql_simple.ba_concat(t.data) FROM test_bytearray t WHERE t.id = 1;
+
+--echo # Test ba_concat_all function (varargs, returns STRING)
+SELECT vsql_simple.ba_concat_all(t.data) AS one
+FROM test_bytearray t WHERE t.id = 1;
+SELECT vsql_simple.ba_concat_all(t1.data, t2.data, t3.data) AS three
+FROM test_bytearray t1, test_bytearray t2, test_bytearray t3
+WHERE t1.id = 1 AND t2.id = 2 AND t3.id = 3;
+SELECT CONCAT("'", vsql_simple.ba_concat_all(t1.data, t2.data, t3.data), "'") AS three
+FROM test_bytearray t1, test_bytearray t2, test_bytearray t3
+WHERE t1.id = 1 AND t2.id = 2 AND t3.id = 3;
+
+--echo # ba_concat_all rejects zero arguments via prerun
+--error ER_CANT_INITIALIZE_UDF
+SELECT vsql_simple.ba_concat_all();
+
+--echo # ba_concat_all rejects non-BYTEARRAY arguments via prerun
+--error ER_CANT_INITIALIZE_UDF
+SELECT vsql_simple.ba_concat_all(1);
+
+--echo # ba_concat_all propagates NULL
+SELECT vsql_simple.ba_concat_all(t1.data, NULL) AS with_null
+FROM test_bytearray t1 WHERE t1.id = 1;
+
+--echo # ba_concat_all treats a non-NULL STRING literal as NULL: prerun lets
+--echo # STRING through so NULL literals (typed STRING) work, but cannot
+--echo # distinguish them from real strings, so the body checks is_custom().
+SELECT vsql_simple.ba_concat_all(t1.data, 'abc') AS with_str
+FROM test_bytearray t1 WHERE t1.id = 1;
+
 --echo # Clean up
 DROP TABLE test_bytearray;
 

mysql-test/suite/villagesql/std_data/simple_vdf.cc

@@ -44,10 +44,12 @@ VEF_GENERATE_ENTRY_POINTS(
     make_extension()
         .func(make_func<&simple_int_func_impl>("simple_int_func")
                   .returns(INT)
+                  .param()
                   .build())
         .func(make_func<&simple_string_func_impl>("simple_string_func")
                   .returns(STRING)
                   .buffer_size(100)
+                  .param()
                   .build())
         .func(make_func<&simple_test_impl>("simple_test")
                   .returns(INT)

mysql-test/suite/villagesql/std_data/simple_vdf_alt.cc

@@ -40,8 +40,10 @@ VEF_GENERATE_ENTRY_POINTS(
     make_extension()
         .func(make_func<&simple_int_func_impl>("simple_int_func")
                   .returns(INT)
+                  .param()
                   .build())
         .func(make_func<&alt_string_func_impl>("alt_string_func")
                   .returns(STRING)
                   .buffer_size(100)
+                  .param()
                   .build()))

villagesql/examples/vsql-simple/src/extension.cc

@@ -125,6 +125,56 @@ void ba_concat(CustomArg a, CustomArg b, StringResult out) {
   out.set_length(kBytearrayLen * 2);
 }
 
+// BA_LEN: return the fixed length of a BYTEARRAY (zero-arity constant).
+// Demonstrates .param() (zero-arity) on the func builder.
+void ba_len(IntResult out) { out.set(static_cast<long long>(kBytearrayLen)); }
+
+// BA_CONCAT_ALL: concatenate any number of BYTEARRAY values into a STRING.
+// Demonstrates .varargs() on the func builder paired with a prerun that
+// validates argument types and sizes the result buffer.
+//
+// Prerun: validate that all arguments are BYTEARRAY (or NULL literals,
+// which appear as VEF_TYPE_STRING in the prerun arg-type array) and ask
+// the server to allocate arg_count * kBytearrayLen bytes of result buffer.
+void ba_concat_all_prerun(vef_context_t *, vef_prerun_args_t *args,
+                          vef_prerun_result_t *result) {
+  if (args->arg_count == 0) {
+    result->type = VEF_RESULT_ERROR;
+    snprintf(result->error_msg, VEF_MAX_ERROR_LEN,
+             "ba_concat_all requires at least one argument");
+    return;
+  }
+  for (unsigned int i = 0; i < args->arg_count; i++) {
+    vef_type_id id = args->arg_types[i].id;
+    if (id != VEF_TYPE_CUSTOM && id != VEF_TYPE_STRING) {
+      result->type = VEF_RESULT_ERROR;
+      snprintf(result->error_msg, VEF_MAX_ERROR_LEN,
+               "ba_concat_all: argument %u must be BYTEARRAY", i);
+      return;
+    }
+  }
+  result->result_buffer_size = args->arg_count * kBytearrayLen;
+}
+
+void ba_concat_all(VarArgs args, StringResult out) {
+  auto dst = out.buffer();
+  size_t off = 0;
+  for (auto a : args) {
+    // Prerun accepts VEF_TYPE_STRING so NULL literals (which arrive typed as
+    // STRING) pass type-check, but it cannot distinguish a NULL literal from
+    // a non-NULL string literal like 'abc'. Treat any non-custom argument
+    // here as NULL so we never call as_custom() on a STRING value.
+    if (a.is_null() || !a.is_custom()) {
+      out.set_null();
+      return;
+    }
+    auto bytes = a.as_custom();
+    memcpy(dst.data() + off, bytes.data(), bytes.size());
+    off += bytes.size();
+  }
+  out.set_length(off);
+}
+
 static constexpr const char kBytearrayTypeName[] = "bytearray";
 
 constexpr auto BYTEARRAY = vsql::make_type<kBytearrayTypeName>()
@@ -135,22 +185,29 @@ constexpr auto BYTEARRAY = vsql::make_type<kBytearrayTypeName>()
                                .compare<&bytearray_compare>()
                                .build();
 
-VEF_GENERATE_ENTRY_POINTS(make_extension()
-                              .type(BYTEARRAY)
-                              .func(make_func<&rot13>("rot13")
-                                        .returns(BYTEARRAY)
-                                        .param(BYTEARRAY)
-                                        .build())
-                              .func(make_func<&even_chars>("even_chars")
-                                        .returns(BYTEARRAY)
-                                        .param(BYTEARRAY)
-                                        .build())
-                              .func(make_func<&odd_chars>("odd_chars")
-                                        .returns(BYTEARRAY)
-                                        .param(BYTEARRAY)
-                                        .build())
-                              .func(make_func<&ba_concat>("ba_concat")
-                                        .returns(STRING)
-                                        .param(BYTEARRAY)
-                                        .param(BYTEARRAY)
-                                        .build()))
+VEF_GENERATE_ENTRY_POINTS(
+    make_extension()
+        .type(BYTEARRAY)
+        .func(make_func<&rot13>("rot13")
+                  .returns(BYTEARRAY)
+                  .param(BYTEARRAY)
+                  .build())
+        .func(make_func<&even_chars>("even_chars")
+                  .returns(BYTEARRAY)
+                  .param(BYTEARRAY)
+                  .build())
+        .func(make_func<&odd_chars>("odd_chars")
+                  .returns(BYTEARRAY)
+                  .param(BYTEARRAY)
+                  .build())
+        .func(make_func<&ba_concat>("ba_concat")
+                  .returns(STRING)
+                  .param(BYTEARRAY)
+                  .param(BYTEARRAY)
+                  .build())
+        .func(make_func<&ba_len>("ba_len").returns(INT).param().build())
+        .func(make_func<&ba_concat_all>("ba_concat_all")
+                  .returns(STRING)
+                  .varargs()
+                  .prerun<&ba_concat_all_prerun>()
+                  .build()))

villagesql/sdk/include/villagesql/abi/types.h

@@ -17,6 +17,7 @@
 #ifndef VILLAGESQL_ABI_TYPES_H_
 #define VILLAGESQL_ABI_TYPES_H_
 
+#include <limits.h>
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
@@ -460,6 +461,12 @@ typedef struct {
   const char *custom_type;
 } vef_type_t;
 
+// Sentinel value for vef_signature_t::param_count indicating that the function
+// accepts a variable number of arguments. When set, the framework skips
+// argument count and type validation and delegates to the prerun function
+// instead. `params` is NULL for varargs signatures.
+#define VEF_PARAM_VARARGS UINT_MAX
+
 typedef struct {
   unsigned int param_count;
   const vef_type_t *params;

villagesql/sdk/include/villagesql/detail/func_builder.h

@@ -34,6 +34,7 @@
 #include <villagesql/abi/types.h>
 #include <villagesql/vsql/func_types.h>
 #include <villagesql/vsql/type_params.h>
+#include <villagesql/vsql/var_args.h>
 
 namespace vsql {
 namespace func_builder {
@@ -288,6 +289,7 @@ struct FuncWithMetadata {
         num_params(0),
         buffer_size(0),
         deterministic(false),
+        is_varargs(false),
         check_params_cache_bound(nullptr),
         check_signature(nullptr) {}
 
@@ -301,6 +303,10 @@ struct FuncWithMetadata {
   size_t num_params;
   size_t buffer_size;
   bool deterministic;
+  // When true, the function accepts a variable number of arguments. The
+  // server skips argument validation and delegates to prerun. num_params
+  // and param_types are unused (a varargs StaticFuncDesc has NumParams == 0).
+  bool is_varargs;
   bool (*check_params_cache_bound)();
   const char *(*check_signature)(const vef_type_t *, size_t,
                                  const vef_type_t &);
@@ -409,6 +415,34 @@ struct Wrapper {
   }
 };
 
+// Generates a vef_vdf_func_t for a varargs VDF whose signature is
+//   void func(vsql::VarArgs, ResultWrapper)
+//
+// The wrapper constructs a VarArgs view over args and the declared typed
+// result wrapper, then calls Func. Argument-count and argument-type
+// validation are skipped at this layer (varargs functions delegate that
+// to their prerun).
+template <auto Func>
+struct VarArgsWrapper {
+  using Params = typename FuncParamTypes<decltype(Func)>::type;
+  static_assert(
+      std::tuple_size_v<Params> == 2,
+      "vsql .varargs(): function must take exactly (VarArgs, ResultWrapper)");
+  using ArgsParam = std::tuple_element_t<0, Params>;
+  using ResultParam = std::tuple_element_t<1, Params>;
+  static_assert(std::is_same_v<ArgsParam, ::vsql::VarArgs>,
+                "vsql .varargs(): first parameter must be vsql::VarArgs");
+  static_assert(is_result_wrapper<ResultParam>::value,
+                "vsql .varargs(): second parameter must be a result wrapper "
+                "(IntResult, RealResult, StringResult, CustomResult, or "
+                "CustomResultWith<P>)");
+
+  static void invoke(vef_context_t * /*ctx*/, vef_vdf_args_t *args,
+                     vef_vdf_result_t *result) {
+    Func(::vsql::VarArgs(args), ResultParam(result));
+  }
+};
+
 // Pre-fills result->type / result->error_msg with a default
 // "failed to encode '<input>'" warning, truncating long inputs. Both encode
 // wrappers call this before invoking the extension's from_string so that an
@@ -842,12 +876,24 @@ struct StaticFuncDesc {
   vef_vdf_accumulate_func_t accumulate_;
   size_t buffer_size_;
   bool deterministic_;
+  bool is_varargs_;
   bool (*check_params_cache_bound_)();
   const char *(*check_signature_)(const vef_type_t *, size_t,
                                   const vef_type_t &);
 
   constexpr const char *name() const { return name_; }
-  constexpr size_t num_params() const { return NumParams; }
+  // For varargs: reports VEF_PARAM_VARARGS so materialize_func_desc writes
+  // the sentinel into vef_signature_t::param_count and the server (and
+  // tooling that reads it back, e.g. extension_registration) treat the
+  // function as variadic.
+  constexpr size_t num_params() const {
+    return is_varargs_ ? VEF_PARAM_VARARGS : NumParams;
+  }
+  // Varargs reads args->values (protocol-2 pointer-array layout) without a
+  // protocol-1 fallback, so a varargs VDF cannot run on protocol 1.
+  constexpr vef_protocol_t required_protocol() const {
+    return is_varargs_ ? VEF_PROTOCOL_2 : VEF_PROTOCOL_1;
+  }
   constexpr size_t buffer_size() const { return buffer_size_; }
   constexpr bool deterministic() const { return deterministic_; }
   constexpr auto check_params_cache_bound() const -> bool (*)() {
@@ -877,6 +923,7 @@ struct StaticFuncDesc {
         accumulate_(meta.accumulate),
         buffer_size_(meta.buffer_size),
         deterministic_(meta.deterministic),
+        is_varargs_(meta.is_varargs),
         check_params_cache_bound_(meta.check_params_cache_bound),
         check_signature_(meta.check_signature) {
     for (size_t i = 0; i < NumParams && i < meta.num_params; ++i) {

villagesql/sdk/include/villagesql/detail/vef_register.h

@@ -46,7 +46,13 @@ __attribute__((visibility("hidden"))) vef_func_desc_t *materialize_func_desc(
   static vef_func_desc_t desc;
 
   signature.param_count = static_cast<unsigned int>(func_data.num_params());
-  signature.params = func_data.num_params() > 0 ? func_data.params() : nullptr;
+  // For varargs functions num_params() returns the VEF_PARAM_VARARGS sentinel
+  // and params() is meaningless; null it out so the server reads
+  // param_count alone.
+  signature.params = (func_data.num_params() > 0 &&
+                      func_data.num_params() != VEF_PARAM_VARARGS)
+                         ? func_data.params()
+                         : nullptr;
   signature.return_type = func_data.return_type();
 
   desc.protocol = VEF_PROTOCOL_2;

villagesql/sdk/include/villagesql/vsql.h

@@ -68,6 +68,9 @@
 // Typed argument/result wrappers: IntArg, RealArg, StringArg, CustomArg, etc.
 #include <villagesql/vsql/func_types.h>
 
+// Varargs typed views: vsql::VarArgs and vsql::AnyArg
+#include <villagesql/vsql/var_args.h>
+
 // Object-based type builder: vsql::make_type<Name>()
 #include <villagesql/vsql/type_builder.h>
 

villagesql/sdk/include/villagesql/vsql/extension_builder.h

@@ -74,7 +74,8 @@ struct ExtensionBuilder {
     auto new_funcs = std::tuple_cat(funcs_, std::make_tuple(f));
     return ExtensionBuilder<decltype(new_funcs), TypeTuple,
                             RequiredCapabilityTuple>{
-        new_funcs, types_, required_capabilities_, min_protocol_};
+        new_funcs, types_, required_capabilities_,
+        require_atleast_min(f.required_protocol())};
   }
 
   // Accepts a TypeObject (from vsql::make_type().build()) that carries embedded