Review the runtime errors currently generated by jBallerina

[manuranga]

Description:

Currently the langlib does not specify runtime errors that can occur. Errors are defined in the platform implementation code, and message format is not consistent. This can lead to the situation where the same program has different behaviors under different platforms.

As part of the solution we have started documenting the current runtime errors. https://docs.google.com/document/d/1qjQTIMjpedZTGTNVXRg3WggmmjcAS23SkY4yxn_teDQ/edit

How can we leverage ballerina error design to model this information in the langlib implementation, such that errors will stay consistent across the platforms?

[manuranga]

We have looked at http stdlib's recent changes to use distinct feature to model http runtime errors

https://github.com/ballerina-platform/module-ballerina-http/blob/a158fcbffb9aea641414129b16e0e6afbc553332/http-ballerina/http_errors.bal

But this design still does not capture the error message nor the detailed information. It can still lead to inconsistencies across the platforms.

[jclark]

We need to split this problem up.

The most important split is between errors and panics. There is a fundamental distinction in Ballerina between abnormal errors (which show up as panics) and normal errors (which show up as errors).

Let's consider normal errors first. There are two cases:

1. Normal errors returned by langlib functions. There is already an issue for this Define some standard error types for use by lang.* modules #134
2. Normal errors resulting from language-defined operations. There are (by design) very few of these:
   a. commit errors (already dealt with in Stabilize transactions support #267 (comment))
   b. errors from wait (this is Need distinct error type for errors caused by wait #689)
   c. errors from using the lax typing feature (just made that Need distinct error type for language errors from json and lax typing #806)

For panics, I have made a new issue #807.

[jclark]

We should review your catalog of runtime errors, because there are a lot of things that seem not quite right to me. We should also crosscheck it against #134, #807, #689 and #806 to make sure that the solutions to those issues cover everything.

[jclark]

@manuranga As a start, could you please categorize each entry in the catalog as an error or a panic? (Ideally, split into two sections.) I strongly suggest that code examples not use checkpanic because it confuses the distinction.

I would also recommend not using the json type in code examples, unless you are depending on its special lax typing properties.

[jclark]

I identified quite a number of cases in #807 (comment) for which there is no entry in the jBallerina catalog. These may well be jBallerina bugs.

[jclark]

I would expect the specification only to specify the error type (i.e. distinct type and possibly error detail); I would not expect it to require specific error messages (I don't know of any language specification that does this).

I would prioritize errors (i.e. #134, #689, #806) over panics (#807), because errors affect the types that users write (if they want to be more precise than just error).

[gabilang]

@manuranga As a start, could you please categorize each entry in the catalog as an error or a panic? (Ideally, split into two sections.) I strongly suggest that code examples not use checkpanic because it confuses the distinction.

I would also recommend not using the json type in code examples, unless you are depending on its special lax typing properties.

I updated the catalog with the categorization of normal errors and panics. And also removed the usage of json type in the code examples as much as possible unless we are using its lax typing properties. Please find the link of updated doc here.