Update mruby sample config with notes on attribute access

diff --git a/raddb/mods-available/mruby b/raddb/mods-available/mruby
index 7943372d11c45801feae0ec5d2b02aa68fc1eb15..980be95cfb165d783934f54aa7e7db36fbf3ff51 100644 (file)
--- a/raddb/mods-available/mruby
+++ b/raddb/mods-available/mruby
@@ -9,17 +9,95 @@
 #
 #  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.
+#
+#  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.
+#
+#  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
 #
-#  If `mruby` is called for a section which does not have a function defined,
-#  it will return `noop`.
-#
 mruby {
        #
        #  filename:: Module to load functions from.