rgw/lua: fix doc comments from PR #46550

(will squash before merge)

Signed-off-by: yuval Lifshitz <ylifshit@redhat.com>

doc/radosgw/lua-scripting.rst

@@ -8,24 +8,24 @@ Lua Scripting
 
 This feature allows users to assign execution context to Lua scripts. The supported contexts are:
 
- - ``preRequest`` which will execute a script before each operation is performed
- - ``postRequest`` which will execute after each operation is performed
+ - ``prerequest`` which will execute a script before each operation is performed
+ - ``postrequest`` which will execute after each operation is performed
  - ``background`` which will execute within a specified time interval
- - ``getData`` which will execute on objects' data when objects are downloaded
- - ``putData`` which will execute on objects' data when objects are uploaded
+ - ``getdata`` which will execute on objects' data when objects are downloaded
+ - ``putdata`` which will execute on objects' data when objects are uploaded
 
 A request (pre or post) or data (get or put) context script may be constrained to operations belonging to a specific tenant's users.
-The request context script can also access fields in the request and modify some fields, as well as the background ``RGW`` table.
-The data context script can access the content of the object as well as the request fields an the background ``RGW`` table. 
+The request context script can also access fields in the request and modify certain fields, as well as the `Global RGW Table`_.
+The data context script can access the content of the object as well as the request fields and the `Global RGW Table`_. 
 All Lua language features can be used in all contexts.
 
 By default, all lua standard libraries are available in the script, however, in order to allow for other lua modules to be used in the script, we support adding packages to an allowlist:
 
   - All packages in the allowlist are being re-installed using the luarocks package manager on radosgw restart. Therefore a restart is needed for adding or removing of packages to take effect 
-  - To add a package that contains C source code that needs to be compiled, use the `--allow-compilation` flag. In this case a C compiler needs to be available on the host
+  - To add a package that contains C source code that needs to be compiled, use the ``--allow-compilation`` flag. In this case a C compiler needs to be available on the host
   - Lua packages are installed in, and used from, a directory local to the radosgw. Meaning that lua packages in the allowlist are separated from any lua packages available on the host.
-    By default, this directory would be `/tmp/luarocks/<entity name>`. Its prefix part (`/tmp/luarocks/`) could be set to a different location via the `rgw_luarocks_location` configuration parameter. 
-    Note that this parameter should not be set to one of the default locations where luarocks install packages (e.g. `$HOME/.luarocks`, `/usr/lib64/lua`, `/usr/share/lua`)
+    By default, this directory would be ``/tmp/luarocks/<entity name>``. Its prefix part (``/tmp/luarocks/``) could be set to a different location via the ``rgw_luarocks_location`` configuration parameter. 
+    Note that this parameter should not be set to one of the default locations where luarocks install packages (e.g. ``$HOME/.luarocks``, ``/usr/lib64/lua``, ``/usr/share/lua``)
 
 
 .. toctree::
@@ -40,7 +40,7 @@ To upload a script:
 
 ::
    
-   # radosgw-admin script put --infile={lua-file} --context={preRequest|postRequest|background|getData|putdata} [--tenant={tenant-name}]
+   # radosgw-admin script put --infile={lua-file} --context={prerequest|postrequest|background|getdata|putdata} [--tenant={tenant-name}]
 
 
 * When uploading a script with the ``background`` context, a tenant name may not be specified.
@@ -50,14 +50,14 @@ To print the content of the script to standard output:
 
 ::
    
-   # radosgw-admin script get --context={preRequest|postRequest|background|getData} [--tenant={tenant-name}]
+   # radosgw-admin script get --context={prerequest|postrequest|background|getdata|putdata} [--tenant={tenant-name}]
 
 
 To remove the script:
 
 ::
    
-   # radosgw-admin script rm --context={preRequest|postRequest|background|putData} [--tenant={tenant-name}]
+   # radosgw-admin script rm --context={prerequest|postrequest|background|getdata|putdata} [--tenant={tenant-name}]
 
 
 Package Management via CLI
@@ -157,7 +157,7 @@ Request Fields
 +----------------------------------------------------+----------+--------------------------------------------------------------+----------+-----------+----------+
 | ``Request.Bucket.Tenant``                          | string   | tenant of the bucket                                         | no       | no        | yes      |
 +----------------------------------------------------+----------+--------------------------------------------------------------+----------+-----------+----------+
-| ``Request.Bucket.Name``                            | string   | bucket name (writeable only in `preRequest` context)         | no       | yes       | no       |
+| ``Request.Bucket.Name``                            | string   | bucket name (writeable only in ``prerequest`` context)       | no       | yes       | no       |
 +----------------------------------------------------+----------+--------------------------------------------------------------+----------+-----------+----------+
 | ``Request.Bucket.Marker``                          | string   | bucket marker (initial id)                                   | no       | no        | yes      |
 +----------------------------------------------------+----------+--------------------------------------------------------------+----------+-----------+----------+
@@ -316,15 +316,15 @@ The ``Request.Log()`` function prints the requests into the operations log. This
 
 Tracing
 ~~~~~~~
-Tracing functions can be used only in `postRequest` context.
+Tracing functions can be used only in the ``postrequest`` context.
 
-- ``Request.Trace.SetAttribute()`` - sets the attribute for the request's trace.
-  Takes two arguments. The first is the `key`, which should be a string. The second is the value, which can either be a string or a number.
+- ``Request.Trace.SetAttribute(<key>, <value>)`` - sets the attribute for the request's trace.
+  The function takes two arguments: the first is the ``key``, which should be a string, and the second is the ``value``, which can either be a string or a number (integer of double).
   Using the attribute, you can locate specific traces.
 
-- ``Request.Trace.AddEvent()`` - adds an event to the first span of the request's trace
+- ``Request.Trace.AddEvent(<name>, <attributes>)`` - adds an event to the first span of the request's trace
   An event is defined by event name, event time, and zero or more event attributes.
-  Therefore, the function accepts one or two arguments. A string containing the event name should be the first argument, followed by the event attributes, which is optional for events without attributes.
+  Therefore, the function accepts one or two arguments. A string containing the event ``name`` should be the first argument, followed by the event ``attributes``, which is optional for events without attributes.
   An event's attributes must be a table of strings.
 
 Background Context
@@ -334,10 +334,10 @@ The ``background`` context may be used for purposes that include analytics, moni
 
 Data Context
 --------------------
-Both ``getData`` and ``putData`` contexts has a single field named ``Data`` which is read only, optional and iterable (byte by byte).
+Both ``getdata`` and ``putdata`` contexts has a single field named ``Data`` which is read only, optional and iterable (byte by byte).
 The ``Request`` fields and the background ``RGW`` table are also available in these contexts.
 
-Global ``RGW`` Table
+Global RGW Table
 --------------------
 The ``RGW`` Lua table is accessible from all contexts and saves data written to it
 during execution so that it may be read and used later during other executions, from the same context of a different one.
@@ -356,7 +356,6 @@ to atomically increment and decrement numeric values in it. For that the followi
 - if we try to increment or decrement by non-numeric values, the execution of the script would fail
 
 
-
 Lua Code Samples
 ----------------
 - Print information on source and destination objects in case of copy:
@@ -433,15 +432,15 @@ Lua Code Samples
 
 - Add metadata to objects that was not originally sent by the client:
 
-In the `preRequest` context we should add:
+In the ``prerequest`` context we should add:
 
 .. code-block:: lua
 
   if Request.RGWOp == 'put_obj' then
     Request.HTTP.Metadata["x-amz-meta-mydata"] = "my value"
   end
 
-In the `postRequest` context we look at the metadata:
+In the ``postrequest`` context we look at the metadata:
 
 .. code-block:: lua
 
@@ -460,7 +459,7 @@ First we should add the following packages to the allowlist:
   # radosgw-admin script-package add --package=luasocket --allow-compilation
 
 
-Then, do a restart for the radosgw and upload the following script to the `postRequest` context:
+Then, do a restart for the radosgw and upload the following script to the ``postrequest`` context:
 
 .. code-block:: lua
 
@@ -497,20 +496,20 @@ Tracing is disabled by default, so we should enable tracing for this specific bu
 
 
 If `tracing is enabled <https://docs.ceph.com/en/latest/jaegertracing/#how-to-enable-tracing-in-ceph/>`_ on the RGW, the value of Request.Trace.Enable is true, so we should disable tracing for all other requests that do not match the bucket name.
-In the `preRequest` context:
+In the ``prerequest`` context:
 
 .. code-block:: lua
 
   if Request.Bucket.Name ~= "my-bucket" then
       Request.Trace.Enable = false
   end
 
-Note that changing `Request.Trace.Enable` does not change the tracer's state, but disables or enables the tracing for the request only.
+Note that changing ``Request.Trace.Enable`` does not change the tracer's state, but disables or enables the tracing for the request only.
 
 
 - Add Information for requests traces
 
-in `postRequest` context, we can add attributes and events to the request's trace.
+in ``postrequest`` context, we can add attributes and events to the request's trace.
 
 .. code-block:: lua
 
@@ -527,7 +526,7 @@ in `postRequest` context, we can add attributes and events to the request's trac
 
 - Calculate the entropy and size of uploaded objects and print to debug log
 
-in `putData` ccontext, add the following script
+in the ``putdata`` context, add the following script
 
 .. code-block:: lua
 

src/rgw/rgw_admin.cc

@@ -120,6 +120,9 @@ static inline int posix_errortrans(int r)
   return r;
 }
 
+
+static const std::string LUA_CONTEXT_LIST("prerequest, postrequest, background, getdata, putdata");
+
 void usage()
 {
   cout << "usage: radosgw-admin <cmd> [options...]" << std::endl;
@@ -477,7 +480,7 @@ void usage()
   cout << "   --subscription            pubsub subscription name\n";
   cout << "   --event-id                event id in a pubsub subscription\n";
   cout << "\nScript options:\n";
-  cout << "   --context                 context in which the script runs. one of: preRequest, postRequest, background, getData, putData\n";
+  cout << "   --context                 context in which the script runs. one of: "+LUA_CONTEXT_LIST+"\n";
   cout << "   --package                 name of the lua package that should be added/removed to/from the allowlist\n";
   cout << "   --allow-compilation       package is allowed to compile C code as part of its installation\n";
   cout << "\nradoslist options:\n";
@@ -10377,7 +10380,7 @@ int main(int argc, const char **argv)
     }
     const rgw::lua::context script_ctx = rgw::lua::to_context(*str_script_ctx);
     if (script_ctx == rgw::lua::context::none) {
-      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: preRequest, postRequest, background, getData, putData" << std::endl;
+      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: " << LUA_CONTEXT_LIST << std::endl;
       return EINVAL;
     }
     if (script_ctx == rgw::lua::context::background && !tenant.empty()) {
@@ -10398,7 +10401,7 @@ int main(int argc, const char **argv)
     }
     const rgw::lua::context script_ctx = rgw::lua::to_context(*str_script_ctx);
     if (script_ctx == rgw::lua::context::none) {
-      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: preRequest, postRequest, background, getData, putData" << std::endl;
+      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: " << LUA_CONTEXT_LIST << std::endl;
       return EINVAL;
     }
     std::string script;
@@ -10421,7 +10424,7 @@ int main(int argc, const char **argv)
     }
     const rgw::lua::context script_ctx = rgw::lua::to_context(*str_script_ctx);
     if (script_ctx == rgw::lua::context::none) {
-      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: preRequest, postRequest, background, getData, putData" << std::endl;
+      cerr << "ERROR: invalid script context: " << *str_script_ctx << ". must be one of: " << LUA_CONTEXT_LIST << std::endl;
       return EINVAL;
     }
     const auto rc = rgw::lua::delete_script(dpp(), store, tenant, null_yield, script_ctx);

src/rgw/rgw_lua.cc

@@ -26,10 +26,10 @@ context to_context(const std::string& s)
   if (strcasecmp(s.c_str(), "background") == 0) {
     return context::background;
   }
-  if (strcasecmp(s.c_str(), "getData") == 0) {
+  if (strcasecmp(s.c_str(), "getdata") == 0) {
     return context::getData;
   }
-  if (strcasecmp(s.c_str(), "putData") == 0) {
+  if (strcasecmp(s.c_str(), "putdata") == 0) {
     return context::putData;
   }
   return context::none;

src/test/cli/radosgw-admin/help.t

@@ -362,7 +362,7 @@
      --event-id                event id in a pubsub subscription
 
   Script options:
-     --context                 context in which the script runs. one of: preRequest, postRequest, background
+     --context                 context in which the script runs. one of: prerequest, postrequest, background, getdata, putdata
      --package                 name of the lua package that should be added/removed to/from the allowlist
      --allow-compilation       package is allowed to compile C code as part of its installation