From: Nick Porter <nick@portercomputing.co.uk>
Date: Tue, 10 Jun 2025 08:20:34 +0000 (+0100)
Subject: Update rlm_mruby docs from raddb
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=48ae14b77ed7c1bb3335d0fd01e8b401e368b493;p=thirdparty%2Ffreeradius-server.git

Update rlm_mruby docs from raddb
---

diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/mruby.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/mruby.adoc
index 226eae6e08c..74b67a7ac4a 100644
--- a/doc/antora/modules/reference/pages/raddb/mods-available/mruby.adoc
+++ b/doc/antora/modules/reference/pages/raddb/mods-available/mruby.adoc
@@ -6,16 +6,94 @@
 
 The `mruby` module processes attributes through a Ruby interpreter.
 
-  * Please see the `src/modules/rlm_mruby/example.rb` sample.
+  * Please see the `mods-config/mruby/example.rb` sample.
   * Please see https://www.ruby-lang.org/en/documentation/ for more
 information about the Ruby language.
 
+The Ruby method names called when the `mruby` module is called are
+automatically derived from the section in which they are called.
 
+If `mruby` is called in `recv Access-Request`, firstly a method
+`recv_access_request` will be looked for.  If that does not exist, then
+a method `recv` will be looked for.
 
-## Configuration Settings
+This can be overridden by setting `func_recv_access_request` or `func_recv`
+to point to a different method name.
+
+Each method called during a packet processing section is passed an
+object which represents the packet.
+
+The object contains 4 methods `request`, `reply`, `control` and `session_state`
+which allow access to the pairs in those FreeRADIUS pair lists.
+
+Nested attributes are accessed by using chained methods.  Each leaf attribute
+has the following methods
+
+[options="header,autowidth"]
+|===
+| Method    | Purpose                            | Arguments
+| get(n)    | Retrieve the value of an attribute | Optional number specifying the attribute instance.
+| set(v, n) | Set the value of an attribute      | Value to set and optional attribute instance.
+| append(v) | Add an instance of an attribute    | Value to set on the new instance.
+| del(n)    | Delete an attribute                | Optional number specifying the attribute instance.
+|===
+
+Where a specific instance of a nested attribute parent is required, the
+method can be passed an argument to specify the instance number.
+
+For example, if the Ruby method is defined `def self.recv(p)`, then
+attributes in the request can be accessed using syntax of the form:
+
+[options="header,autowidth"]
+|===
+| Ruby syntax                  | FreeRADIUS attribute
+| p.request.foo.get            | request.foo
+| p.request.baa.baz.get(1)     | request.baa.baz[1]
+| p.requestbaa(2).baz.get      | request.baa[2].baz
+|===
+
+Where attribute names contain `-` this should be replaced by `_`, e.g.
+`request.User-Name` becomes `p.request.user_name`
+
+The interface between FreeRADIUS and Ruby is mosty string.
+
+Attributes of type `string` are copied to Ruby as-is.
+They are not escaped or interpreted.
 
-If `mruby` is called for a section which does not have a function defined,
-it will return `noop`.
+Attributes of type `octets` are copied to Ruby as-is.
+They are not escaped or interpreted.
+
+Numeric attributes are passed as the appropriate Ruby numeric type.
+
+All other attributes are printed, and passed to Ruby as a string value.
+
+IP addresses are sent as strings, e.g. "192.0.2.25", and not as a 4-byte
+binary value.  The same applies to other attribute data types.
+
+Attributes can be set by using the `set` method of the leaf attributes E.g.
+
+`p.reply.foo.set('baa')`
+
+The return codes from Ruby methods are passed directly to the server.
+A set of predefined constants are provided to use as return values:
+
+[options="header,autowidth"]
+|===
+| Ruby constant       | FreeRADIUS rcode
+| RLM_MODULE_OK       | ok
+| RLM_MODULE_HANDLED  | handled
+| RLM_MODULE_INVALID  | invalid
+| RLM_MODULE_DISALLOW | disallow
+| RLM_MODULE_NOTFOUND | notfound
+| RLM_MODULE_NOOP     | noop
+| RLM_MODULE_UPDATED  | updated
+| RLM_MODULE_REJECT   | reject
+| RLM_MODULE_FAIL     | fail
+|===
+
+
+
+## Configuration Settings
 
 
 filename:: Module to load functions from.