Modules and execution plans

[bretg]

Having more modules is great, but we've found that execution plans are more difficult to manage than they could be.

• They're quite powerful, but complicated.
• They're not merged like most other configs - if they exist at both the host level and the account level, the module is run twice.
• There's no guidance to host companies on how to determine where to put the execution plan.
• Not all modules support an "enabled" flag to skip the module for accounts that haven't turned it on

So we'd like to propose the following:

• A general recommendation that modules execution plans are defined at the host level. No code changes -- just guidance.
• Every module needs to support an enabled flag in its config so that when the module is called on every request. The idea is that modules need to return as quickly as possible when it's not enabled.
• Documentation should be updated to reflect these guidelines

We discussed having core be aware of the enabled flag, but currently the module config is opaque to PBS-core. It could cause duplicate parsing of config JSON. It would be an upgrade of the module infrastructure to support a core-visible enabled flag.

PBS-Go reads the module config from the merged config, looking for an enabled flag.

We agreed to consider this offline and continue the discussion in this issue.

[bretg]

Discussed these options:

1. Do nothing.
2. PBS-core could start requiring module config in order to call the module. Even empty config. If such module config exists, the module is considered enabled.
3. Have core look for an enabled flag and just don't bother calling the module.
4. Establish a review convention that all modules must support an enabled flag and the first this every module hook does is confirm enablement.

We're leaning heavily towards option 2:

• Execution plan can be global
• PBS-core merges account module config with host-level module config, with account-level taking precedence
• Before actually calling a module hook, PBS-core would look for module config. If no config, no call.
• If a module has host-level config, it will always be called.
• Else, check the account-level config -- the module will only be called if that account has an entry, even a null entry is ok.
• All current open source modules require some kind of config, so this works ok.
• However, there's an implication that if there are any private modules that don't require config, the host company would need to create an empty module config. That would be a breaking change.
• So, the proposal is a new host company flag that would kick core into a mode where module config is required. e.g. settings.modules.require-config-to-invoke. Start off with the default of this flag false
• In the future (4.0?), the default of this config might change. Or not.

We'll bring this up again at next weeks meeting, hopefully for the final time.

[bretg]

We did meet last meeting and confirm Option 2 as detailed above.

[bretg]

As the team has been building this feature in PBS-Java, I've been corrected on a misunderstanding and we've added a feature.

1. host-level config in PBS-Java is the application.yaml file. Module config here is used only in initialization, not at runtime. So even if a module here has config, it won't be seen as runtime configuration.
2. A workaround would be to place empty module config in the default-account-config, but the team found this unappealing.
3. So we're adding a hooks.admin.module-execution option that will allow the host company to define and override which execution plans get called. This is meant to be defines in the default account config and can be overridden for each account, providing a good deal of flexibility in controlling which modules run for each account.

Here's an example with expected behavior.

The application.yaml host-level config contains the execution plans for 4 modules, but modules 1 and 2 don't need any configuration. Pseudo-code:

settings:
  modules:
    require-config-to-invoke: true
execution-plan:
  processed-auction:
    group 1:
      execute module 1
      execute module 2
    group 2:
      execute module 3
  all-processed-bid-responses:
    group 1:
      execute module 4

Default account config:

{
  hooks: {
    admin: {
      module-execution: {  // instead of defining blank global config
        "module1": true             
        "module2": true
      }
   }
}

Account-level config:

• Account A contains config for module 3 and an override hooks.admin.module-execution:module2:false
• Account B contains config for module 4.

Expected results:

1. module 1 is called for both accounts A and B because the default account config set it to true even through there's no config.
2. module 2 is called for account B only because A overrode it to false.
3. module 3 is called for account A only
4. module 4 is called for account B only

[bretg]

Done in PBS-Java 3.16