lua: add message argument to table constructor of box.error.new

Currently, the error message is specified in the `reason` argument to the
table constructor of `box.error.new`. This is confusing, because the
message is accessed and printed by `error:unpack` as `message`.

Let’s allow users to pass the error message in the `message` argument. We
won’t drop the `reason` argument so as not to break potential users. Let's
also allow to omit the message key by treating the first table constructor
entry as an error message if present.

The error message setting has the following priority: first table
constructor entry > `message` > `reason`.

This change is backwards-compatible and does not require a new `compat`
option.

Closes #9102

@TarantoolBot document
Title: Document `message` argument to table constructor of `box.error.new`
Product: Tarantool
Since: 3.1
Root documents: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/new/
and https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/error

[Link to the design document](https://www.notion.so/tarantool/Error-subsystem-improvements-90faa0a4714b4143abaf8bed2c10b2fc?pvs=4#c984e766372743c99a4a7be79a5783f6)

Author: CuriousGeorgiy

changelogs/unreleased/gh-9102-error-new-message-arg.md

@@ -0,0 +1,4 @@
+## feature/lua
+
+* Added a `message` argument to the table constructor of `box.error.new`
+  (gh-9102).

src/box/lua/error.cc

@@ -78,6 +78,31 @@ luaT_error_add_payload(lua_State *L, struct error *error)
 	region_truncate(gc, used);
 }
 
+/**
+ * In case the error is constructed from a table, retrieves the reason.
+ *
+ * @param L Lua state
+ * @param index table index on Lua stack
+ *
+ * @return reason
+ * @retval "" failed to retrieve reason
+ */
+static const char *
+error_create_table_case_get_reason(lua_State *L, int index)
+{
+	lua_rawgeti(L, index, 1);
+	const char *reason = lua_tostring(L, -1);
+	if (reason != NULL)
+		return reason;
+	lua_getfield(L, index, "message");
+	reason = lua_tostring(L, -1);
+	if (reason != NULL)
+		return reason;
+	lua_getfield(L, index, "reason");
+	reason = lua_tostring(L, -1);
+	return reason != NULL ? reason : "";
+}
+
 /**
  * Parse Lua arguments (they can come as single table or as
  * separate members) and construct struct error with given values.
@@ -146,10 +171,7 @@ luaT_error_create(lua_State *L, int top_base)
 		lua_getfield(L, top_base, "code");
 		if (!lua_isnil(L, -1))
 			code = lua_tonumber(L, -1);
-		lua_getfield(L, top_base, "reason");
-		reason = lua_tostring(L, -1);
-		if (reason == NULL)
-			reason = "";
+		reason = error_create_table_case_get_reason(L, top_base);
 		lua_getfield(L, top_base, "type");
 		if (!lua_isnil(L, -1))
 			custom_type = lua_tostring(L, -1);

test/box-luatest/error_subsystem_improvements_test.lua

@@ -79,3 +79,15 @@ g.test_custom_payload = function()
         custom_type = "MyAppError",
     })
 end
+
+-- Test the `message` argument to the table constructor of `box.error.new`
+-- (gh-9102).
+g.test_error_new_message_arg = function()
+    local msg = 'message'
+    t.assert_equals(box.error.new{msg}.message, msg)
+    t.assert_equals(box.error.new{message = msg}.message, msg)
+    t.assert_equals(box.error.new{reason = msg}.message, msg)
+    t.assert_equals(box.error.new{msg, message = 'other'}.message, msg)
+    t.assert_equals(box.error.new{message = msg, reason = 'other'}.message, msg)
+    t.assert_equals(box.error.new{msg, reason = 'other'}.message, msg)
+end