Resource Content API

Resource Content API Alpha Version (AF-2172)

This Epic covers the first version of Kogito Resource Content API.

William did a great job leading this effort, with the guidance of TiagoB. Congrats to both.

How does this work?

On this PR, we are pushing the GWT bridge (ResourceContentService) that we hope will be useful for you guys. This API has, for now, two methods:

Promise<String> get(String uri): that returns the content of a given file
Promise<String[]> list(String pattern): given a [GLOB|https://github.com/begin/globbing] pattern [1], we will return a list of files that matches this pattern.

[1] We used the GLOB pattern because it's the most used API on Javascript world and we can leverage third-party libraries for VSCode and GitHub.

Which use cases are currently supported?
On this first release, we target our focus to support the Work Item Handlers use cases in both VSCode and Chrome Extension.
To achieve the best validation of the API we took the time to upgrade the mocked version of WorkItemDefinitionClientService (calling our resourceContentService bridge) and also William wrote a basic WorkItemDefinitionParser. That parser was helpful to us to validate the USE case and could be a good starting point for the real implementation.

Which use channels are currently supported?

In this version we focused on two channels:

• On VSCode, we can query any file from the current workspace. See the video.
• On Github, we can query any file inside the current repository. So this means that an editor can load the data from a work item handler inside our GitHub extension. See gif.

What are the current limitations?

Our first Github integration was based on the raw version of the GitHub files. This was acceptable as a first POC but has limitations for production use:
There is a lag between committing a file and Github updating the raw version content. This could be potentially misleading for users because you edit a file and don't see the results immediately when you reload the diagram (a common workflow during PR reviews);
There is no way to query all the contents of a repository via raw files, restricting our list use case.

• So given these restrictions we decided to go ahead and integrate Octokit support on kogito tooling, but to achieve this we will need to authenticate to GitHub API via OAuth and follow the quota limit[2].
• This means that as soon as the user reaches the limit of his quota, we will have to fall back to the raw api, disabling the file 'list' functionality. The user GitHub access token is the most simple token required, no need for any permission - if we are not fetching a private - repo and we don't store user token. Take a look at this video of the user flow (and also the cool new kogito logo for our chrome extension).
  This process will not be necessary as soon as we are allowed to have some kind of backend or function (serverless) able to authenticate user with GitHub (a simple function that executes the token manipulation and request coordination to authenticate User and Github via oauth).
  So from the editors perspective consuming the API, until we have some sort of backend functionality you will need to deal with this tradeoff:
• On Chrome Extension, If you want to scan directories/repositories with our list API, user will have to be authenticated or limit their requests below the quota. If user doesn't authenticate and overload the quota, our list API will return an empty result.

[2] The current quota limitation is 60 req/hour for an unauthenticated ip and 5000 req/hour for someone authenticated.

Next steps

As soon as we are able to merge this API William will go start the second stage of this API (https://issues.jboss.org/browse/AF-2389), Google Drive support and after this, Local FileSystem Support (that will be used by our Desktop Online Modeler).