roles: list differences between cartridge roles and tarantool 3 roles

[Totktonada]

Related dev. issue(s): tarantool/tarantool#9078
Related doc. issue(s): #3702

Product: Tarantool
Since: 3.0.0
Audience/target: application and module developers
Root document: A migration guide inside the Developing applications with Tarantool section
SME: @ Totktonada

Details

There are a couple of differences between cartridge's roles and tarantool 3 roles. I propose to list them in the documentation to ease UX for developers who migrate its application from cartridge to tarantool 3.

The list of known differences:

• No role_name parameter. A name of tarantool 3 role is the name of the module (foo/bar/baz.lua is a foo.bar.baz role).
• No init function. An initialization code is what the module itself executes on require, IOW, the code outside functions on the top level.
• The role code is loaded after first box.cfg(), not before.
• Different function names: validate_config -> validate, apply_config -> apply.
• validate and apply receive cfg argument that represents a configuration of the given role (roles_cfg.<role name>), not a full config. A full config can be acquired using config:get().
• No second old_cfg argument.
• <role>.apply is not invoked on RO/RW changes. Use box.watch('box.status', <...>) to react on the RO/RW mode changes.
• stop() is called in the reverse order (according to dependencies). So, higher level roles are stopped first.
• validate, apply, stop should raise a Lua error to report an unrecoverable error. Any return value (including return nil, err) is considered as success.