Formalizing the rgov API

[w2vy]

Looking at the pyrgov possibilities I see one area that needs improvement

The rholang code is not consistent on return values

We need a defined standard for return values

For example if an unrecoverable exception happens how is that communicated?

Since we have variable return structures available to us (in both python as well as JS and most API languages anyone wants to use) I would like to propose something like this:

[Status, "meaning", {return}]

Status is a boolean that signals that the code executed without exceptions
"meaning" is a human readable meaning of the status
return is an optional element that contains any application data that was returned

Some examples:
[True, "OK"] - the code executed properly no return value
[False, "network not reachable"]
[True, "OK", ["#define", "Balance", 10000000]]
etc

Upon looking at it closer, the return is what the rholang returns, the Status/meaning really comes from the API wrapper.
Does JS have the ability to catch raised exceptions for when the rnode is unreachable or other catastrophic failure?
If not, then maybe this is just useful for the python interface

And a secondary question: why does checkBalance return a #define?

[Bill-Kunj]

I agree with this effort. @jimscarver and I have been haggling about these sorts of conventions for a while now.
@w2vy suggestion is reminiscent of the original K&R kernel: a return of -1 means error.

An alternative inspired by C++ exceptions in regular C:
Return is something like [value, {exception-map}]
And we can standardize the map keys, if necessary.

This allows us to add to the exception-map as we "unwind the stack"
Following @w2vy example:

[True, "OK"] --> [Nil, Nil] // returns only success/failure
[False, "network not reachable] --> [Nil, {"error": "network not reachable", "network": "error.error.com"}] // returns only success/failure

[True, "OK", ["#define", "Balance", 10000000]] --> [["#define", "Balance", 10000000], Nil] // function returns list
[False, "network not reachable", []] --> [[], {"error": "network not reachable", "network": "error.error.com"}] // function returns list

[jimscarver]

there is an rchain standard return of a tuple (succeeded, result ) where if succeeded is false the result is the error message. e.g.

      @RevVault!("findOrCreate", myGovRevAddr, *vaultCh) |
      for (@(true, vault) <- vaultCh) {
         @vault!("balance", *balanceCh) |
         for (@balance <- balanceCh) {
            return!(["#define", "$myBalance", balance])
         } |
      for (@(false, message) <- vaultCh) {
           return (["error", message])
      }

[Bill-Kunj]

there is an rchain standard return of a tuple (succeeded, result ) where if succeeded is false the result is the error message. e.g.

      @RevVault!("findOrCreate", myGovRevAddr, *vaultCh) |
      for (@(true, vault) <- vaultCh) {
         @vault!("balance", *balanceCh) |
         for (@balance <- balanceCh) {
            return!(["#define", "$myBalance", balance])
         } |
      for (@(false, message) <- vaultCh) {
           return (["error", message])
      }

A tuple is fine, but given how difficult it can be to debug rholang, I'm averse to a simple error message. A map containing relevant values will be much more informative to developers, especially new ones.

   @RevVault!("findOrCreate", myGovRevAddr, *vaultCh) |
   for (@(true, vault) <- vaultCh) {
      return!((true, ["#define", "$myBalance", balance]))
   } |
   for (@(false, errorMap) <- vaultCh) {
      return!((false, errorMap.set("revAddr", myGovRevAddr))
   }

[w2vy]

@Bill-Keuntje @jimscarver Why does the checkBalance call return a list of 2 strings and the balance?
["#define", "varname", balance]

Is that required by JS? It is causing me a lot of trouble in python, I can't figure out how to access each field of the return value

[jimscarver]

the #define comes from RHO-bot on discord to define a macro and is intended to be for communicating with javascript but is not used consistently or supported currently. We need to consider lifetime and scope (acct, network) of browser data. See #42

[Bill-Kunj]

@jimscarver
@w2vy
Have we decided that return values in RGOV rholang are either:

(true, data)

or

(false, {error info})

Do we know that there are no display problems in the browser for these tuples?

[w2vy]

I believe we have agreed that since strict structure layouts in Par types that we can create the strict return values in the API layer above rhoang.

If I am correct we can close this issue

[Bill-Kunj]

@w2vy @jimscarver
I agree that we can standardize on (T, value) (F, {error-map})
Are we good and can close this down?

[jimscarver]

yes

[w2vy]

Yes On July 10, 2021 6:56:58 PM EDT, Bill-Kunj ***@***.***> wrote: ***@***.*** @jimscarver

…

I agree that we can standardize on ```(T, value) (F, {error-map})``` Are we good and can close this down? -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #125 (reply in thread)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.