feat: Action Menu protocol (Aries RFC 0509) implementation

[genaris]

Implementation of module fully supporting Aries RFC 0509 for both requester and responder roles.

Protocol states and information are stored in records of type ActionMenuRecord. As this protocol currently defines a single active menu per connection, there will be at most 2 records per connection (as theoretically is possible to serve as requester and responder at the same time). While this information could be stored also in Connection Metadata, specific records were created thinking in a future version/extension of this protocol where multiple menus could be deployed (e.g. a menu per thread).

There are still some tests to do (especially in regards of message processing and protocol state machine asserts) but it would be nice if you guys can do some review, as this protocol is not so explicit as others about state transitions and error management and I'm not sure if it's clear enough in terms of usage.

Module API is quite simple and hopefully understandable:

As a requester:

• requestMenu: to ask for the root menu. If a menu navigation is ongoing, it will be reset
• performAction: to select an option on the last received menu. Framework checks its validity (name exists) before sending
• clearActiveMenu: to discard current flow. It will clear record contents and set protocol state to Null (as it is reset)
• findActiveMenu: to query current menu record (the menu itself, our selection if any, protocol state, etc.)

As a responder:

• sendMenu: to send an action menu. Depending on current state, agent controller will determine if it's the root menu or a submenu based on a selection
• clearActiveMenu: to discard current flow. This is intended to be used when agent controller determines that a timeout has been occurred. Requester will not be informed immediately, but with a Problem Report if they want to perform an action (as suggested by the RFC)
• findActiveMenu: to query current menu record (the menu itself, requester selection if any, protocol state, etc.)

Solves #471
Signed-off-by: Ariel Gentile [email protected]

[codecov-commenter]

Codecov Report

Merging #974 (c8fafbd) into main (f487182) will increase coverage by 0.28%.
The diff coverage is 94.86%.

@@            Coverage Diff             @@
##             main     #974      +/-   ##
==========================================
+ Coverage   88.06%   88.35%   +0.28%     
==========================================
  Files         492      520      +28     
  Lines       11623    12071     +448     
  Branches     1936     1992      +56     
==========================================
+ Hits        10236    10665     +429     
- Misses       1326     1343      +17     
- Partials       61       63       +2     

Impacted Files	Coverage Δ
...modules/action-menu/models/ActionMenuOptionForm.ts	53.84% <53.84%> (ø)
...ction-menu/models/ActionMenuOptionFormParameter.ts	55.55% <55.55%> (ø)
...src/modules/action-menu/models/ActionMenuOption.ts	88.88% <88.88%> (ø)
...modules/action-menu/repository/ActionMenuRecord.ts	94.11% <94.11%> (ø)
...re/src/modules/action-menu/messages/MenuMessage.ts	95.65% <95.65%> (ø)
.../modules/action-menu/services/ActionMenuService.ts	97.98% <97.98%> (ø)
...s/core/src/modules/action-menu/ActionMenuModule.ts	98.07% <98.07%> (ø)
packages/core/src/agent/Agent.ts	95.40% <100.00%> (+0.05%)	⬆️
...s/core/src/modules/action-menu/ActionMenuEvents.ts	100.00% <100.00%> (ø)
...ges/core/src/modules/action-menu/ActionMenuRole.ts	100.00% <100.00%> (ø)
... and 20 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[TimoGlastra]

Nice and tidy 👍 . My preference would go to making this an optional add-on module. However I'm fine with merging it in core in 0.2.0 and then extracting it from core into a separate package (like module-tenants) in 0.3.0. What do you think?

Edit: I see unit tests are missing, but that's probably still todo as you mention in the pr description?

[TimoGlastra]

What if the action menu is currently in progress? Can I just start a new one?

I see you mentioned:

As this protocol currently defines a single active menu per connection, there will be at most 2 records per connection (as theoretically is possible to serve as requester and responder at the same time).

Is this a limitation imposed by the RFC?

[genaris]

From the RFC I understood that this situation would discard current flow and request back the root menu:

At any time a requester can reset the protocol by requesting the root menu from a responder.

The RFC states also that:

both Agents may support both requester and responder roles simultaneously. Such cases would result in two instances of the action-menu protocol operating in parrallel.

So that's why we are supporting one instance per role and connection. At first I thought to create an ActionMenuRecord per interaction (for instance, every time the requester agent selects an option, it creates a new record, which would be set to Done once a new menu is requested and then another record is created). But it could become a bit too complicated considering the simplicity of current specification.

[TimoGlastra]

Do we need to assert state?

[genaris]

Nice and tidy 👍 . My preference would go to making this an optional add-on module. However I'm fine with merging it in core in 0.2.0 and then extracting it from core into a separate package (like module-tenants) in 0.3.0. What do you think?

Edit: I see unit tests are missing, but that's probably still todo as you mention in the pr description?

Thanks! I think it would be a good idea as you say, we can merge it in 0.2.x and then move it to a separate package, as it is not a core protocol.

I'm writing the unit tests and actually found a few issues, so I'll fix them and submit the PR for review shortly (hopefully 😄).

[genaris]

Well now I've added some error handling and tests (with our new friend SonarCloud complaining) I think it's not as nice and tidy as before, but let's see how it goes 😄 . I updated PR description with some more details about the work done and what's left.

[sonarqubecloud]

SonarCloud Quality Gate failed.   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
71 Code Smells

No Coverage information
6.8% Duplication

[TimoGlastra]

I'm a bit hesitant to merge this now as it will be quite a hassle to merge into 0.3.0-pre afterwards. When I get the time to immediately update the implementation to work with 0.3.0-pre I'll merge

[genaris]

I'm a bit hesitant to merge this now as it will be quite a hassle to merge into 0.3.0-pre afterwards. When I get the time to immediately update the implementation to work with 0.3.0-pre I'll merge

Do you mean to merge this module directly on 0.3.0-pre? Or do you want to first update 0.3.0-pre with current main branch status and then merge this one into main?

[TimoGlastra]

Do you mean to merge this module directly on 0.3.0-pre? Or do you want to first update 0.3.0-pre with current main branch status and then merge this one into main?

No it's probably good to have it in 0.2.x if possible, but after it has been merged in main we need to rebase the 0.3.0-pre branch and integrate the changes from main. I'll do that soon, and then we can make an additional PR to extract the action menu into a separate package.

[TimoGlastra]

Can you update once more? Then I'll merge this PR