Add previewURL support in Devfile format

[l0rd]

Is your enhancement related to a problem? Please describe.

Extend current devfile spec to be allow users to specify a previewURL for a given command

Describe the solution you'd like

 commands:
   - name: run
     previewUrl:
       port: <a port>
       path: <a subpath>
     actions:
       - type: exec
         component: mysql
         command: mvn clean
         workdir: /projects/spring-petclinic

Implementation

• MVP as beta feature. Server side implementation Server support for previewurl #14893
• Validate devfile with schema with matching apiVersion Validate devfile with schema with matching apiVersion #14824
• Theia side for previewurl proposed solution Theia should accept previewurl links #14892
• Theia shows two dialogues when previewUrl is defined in command Theia shows two dialogues when previewUrl is defined in command #14802
• Theia doesn't update command's previewUrl on 2nd workspace start Theia doesn't update command's previewUrl on 2nd workspace start #14803
• Document preferences related to preview URL functionality [docs] Document preferences related to preview URL functionality #14999
• Promote to stable Promote PreviewURL to stable #15412

[skabashnyuk]

@l0rd Does the scope of this issue limited to add previewUrl only in devfile. Or it also means to add some information in workspace runtime. Like

command
    attributes
        previewUrl:https://host:port/path

[skabashnyuk]

@l0rd any comments?

[gorkem]

How would ports-plugin utilize this information?

[skabashnyuk]

The idea is to add a new attribute(look like an old Che6 commands attribute) in commands in runtime previewUrl

Then task-plugin can read it https://github.com/eclipse/che-theia/blob/master/plugins/task-plugin/src/task/task-protocol.ts#L15

[sparkoo]

@l0rd is command executed always on one of existing servers? Or can it start new one?

[sparkoo]

There's an issue how to find correct server with URL.

There are already exposed URL's in object Runtime>Machines>Server>Url. We can select machine by machineName attribute from command object. As @sleshchenko pointed out, it is not ensured that command will have machineName. Next issue is how to select Server. It should be filterable by port.

Another approach would be to create an extra route for previewUrl. I'm going to investigate this option.

[sparkoo]

@l0rd @skabashnyuk are both port and path mandatory? I could imagine we can use /as default path and 80 as default port. But do we want to do that?

[sleshchenko]

are both port and path mandatory? I could imagine we can use /as default path and 80 as default port. But do we want to do that?

I agree that path may be optional with / as default value.
But port - it's not a port that clients should use to access an application, but port of a container that should be exposed. For java default is 8080, for nodejs like 4040, I think it would be better to require this value to be set.

[skabashnyuk]

There are already exposed URL's in object Runtime>Machines>Server>Url. We can select machine by machineName attribute from command object. As @sleshchenko pointed out, it is not ensured that command will have machineName. Next issue is how to select Server. It should be filterable by port.

That is all internal logic of che server. That should not be our focus.

I think that port is mandatory. It can be already declared as an endpoint in devfile https://github.com/eclipse/che-devfile-registry/blob/master/devfiles/java-web-spring/devfile.yaml#L29 or editor https://github.com/eclipse/che-plugin-registry/blob/d9998222c284d40ae0d2e1661452c1bcd5e4fddb/v3/plugins/ws-skeleton/eclipseide/4.9.0/meta.yaml#L17 or plugin, or it can be a command that can start a new server.

[sparkoo]

there is Theia issue that affects the previewUrl feature #14876

[skabashnyuk]

As for the beta feature, I think @sparkos' s solution #13945 (comment) - is ok-ish.
I think one of the trickiest questions before we promote this feature to stable would be - the algorithm of how we proceed if user editing both devfile and task.json at the same time in the same place. And this issue #14876 is one of the sign
of the potential problem of having two sources of commands devfile and task.json.

A couple of question to @sparkos' s solution

• How this id ${previewUrl1} would be calculated. Does it uniquely identify command? CRC?
• @RomanNikitenko what do you do if you didn't find this id after workspace restart. The reason: the user just deletes it in devfile.

[sparkoo]

* How this id ${previewUrl1} would be calculated.  Does it uniquely identify command? CRC?

When #14876 is fixed, we don't have to do any sophisticated calculations. At workspace startup, we basically find URL for command (either it exists by defined endpoint or we create service+route), put it into the map under some key and put this key to command's attribute. Theia then receives this map and command's attributes and must properly update tasks.json with the key received from server. For consistency and human readability I would use something like name.replace(" ", "_")+random_noise() as a key (random noise to fix conflicting names, if someone has run command and run_command in the same devfile).

[sparkoo]

I've just realized that having random noise in key would mean that this key will change at each workspace startup, which is not ok for Theia. We should change tasks.json config only when we really have to. So yes, having some command.name + "-" + CRC(command.name), to have same key for the same name everytime should be enough.

[sparkoo]

we even don't need the tasks.json <> devfile sync to be fixed. Preview url key should be the same for the command name, so we're good here.

[skabashnyuk]

we even don't need the tasks.json <> devfile sync to be fixed. Preview url key should be the same for the command name, so we're good here.

Sounds ok.

[sparkoo]

to sum up the proposed solution:

server will create workspace object like this:

...
    "links": {
      "self": "http://che-eclipse-che.192.168.42.10.nip.io/api/workspace/workspace7grc58gn0jozwkmz",
      "ide": "http://che-eclipse-che.192.168.42.10.nip.io/admin/nodejs-mongo-ymkmt",
      "environment/statusChannel": "ws://che-eclipse-che.192.168.42.10.nip.io/api/websocket",
      "environment/outputChannel": "ws://che-eclipse-che.192.168.42.10.nip.io/api/websocket",
      "previewurl/runthewebapp_123": "http://ingress111aaa.192.168.42.10.nip.io/hello",
      "previewurl/createtestuser_456": "http://ingress222bbb.192.168.42.10.nip.io/some/path"
    },
...
      "commands": [
        {
          "commandLine": "npm install && npm run dev",
          "name": "run the web app",
          "attributes": {
            "componentAlias": "nodejs",
            "machineName": "nodejs",
            "workingDir": "${CHE_PROJECTS_ROOT}/nodejs-mongodb-app"
          },
          "type": "exec",
          "previewUrl": "${previewurl/runthewebapp_123}"
        },
        {
          "commandLine": "curl -X POST --data '{\"user\": {\"username\": \"test\", \"email\": \"test@test.com\", \"password\": \"password\"}}' -H \"Content-Type: application/json\" http://localhost:3000/api/users\n",
          "name": "create test user",
          "attributes": {
            "componentAlias": "nodejs",
            "machineName": "nodejs"
          },
          "type": "exec",
          "previewUrl": "${previewurl/createtestuser_456}"
        }
      ],
...

Theia's responsibility is then to resolve variables in previewUrl attributes, with values from links object.

Key previewurl/run_the_web_app_123 is constructed in this format previewurl/<command_name>_<crc>, where previewurl is hard prefix, <command_name> is command's name without spaces and <crc> is some simple crc hash function applied on commands name. Theia do care only about prefix to know that this is previewurl link and it should create a variable from it. The rest is simple string without any extra meaning for Theia.

[sparkoo]

cc: @l0rd @RomanNikitenko @skabashnyuk

[skabashnyuk]

#13945 (comment)

ok for me

[RomanNikitenko]

@sparkoo

After restarting workspace key previewurl/createtestuser_456 will be the same previewurl/createtestuser_456? I mean crc hash _456 is not changed, right?

[sparkoo]

@sparkoo

After restarting workspace key previewurl/createtestuser_456 will be the same previewurl/createtestuser_456? I mean crc hash _456 is not changed, right?

yes, it will be calculated from command name, so as long as the name won't change, crc will be the same.

[sparkoo]

I've created an issue for Theia support of previewurl by proposed solution #14892

cc: @RomanNikitenko @l0rd

[l0rd]

@sparkoo that's fine for me

[slemeur]

When are you planning to merge this work to stable?

[sparkoo]

@slemeur we can plan it for next sprint, or even include it in current sprint. It should be straightforward patch.

[sparkoo]

@slemeur I've created an issue for that #15412

[sparkoo]

all issues in the scope of this epic are done. closing.