api on the fly - part 1 - generate forms from mutations

[oliver-sanders]

Addresses the first three points of #339

This PR adds a temporary "mutations" view which lists available mutations and auto-generates forms for them on request.

This is orthogonal to cylc/cylc-flow#3469 which makes the mutations more declarative and brings them more inline with the Cylc CLI.

Getting the nested components and data model working correctly took nearly all the time. Thanks for the <component :is="class" /> suggestion @kinow, I would have wasted days otherwise 👍.

Overview:

• Introspect the GraphQL schema for information about mutations.
• Auto-generate forms to act as interfaces to these mutations.
• When complete output JSON from these forms to be used as arguments in the GraphQL request.

Caveats:

• Some of the default values in the GraphQL schema are presently set as string representations for list types. Either Graphene or GraphQL seems to convert all default types to JSON which is added as a string in the JSON response? This results in traceback and errors. 👀
• Styling not yet complete.
• The abstraction form generator is roughly independent of the component library being used but there is't a proper interface for implementing different libraries as yet. Not a big job but probably a bridge to cross if and when we get to it.

Justification:

There are some tools out there which could have been used, instead I wrote this from scratch. Just to dump my reasoning down here for the record:

There is a potential pathway where we convert GraphQL -> JSONSchema -> Web Form -> JSON -> GraphQL Arguments.

• There are a lot of interfaces here and it gets a bit messy/
• Most of the tools are immature
• None of them seem to work with mutations properly (they are seem focused on the data model)
• Most don't support Vue or are written for other frameworks.
• None work with Vuetify.
• Supporting GraphQL mutation schema natively seems more natural.

TODO:

• Vuetify doesn't have an integer field, it has a "number" mode to the text field. This outputs strings rather than number which won't do.
• Testing (basic).
• Consider using an inheritance or composition model to keep things DRY.
• Fix persistence of the FormGenerator model.

Requirements check-list

• I have read CONTRIBUTING.md and added my name as a Code Contributor.
• Contains logically grouped changes (else tidy your branch by rebase).
• Does not contain off-topic changes (use other PRs for other changes).
• Appropriate tests are included (unit and/or functional).
• Appropriate change log entry included.
• No documentation update required.

[oliver-sanders]

Will output:

{
  "command": "\"put_external_trigger\"",
  "eventId": "1234",
  "eventMessage": "2345",
  "workflows": [
    "foo",
    "bar"
  ]
}

[kinow]

One or other typo I think, but found nothing wrong in the pull request. I think you have experienced pretty much every kind of problem I had with Vue.js 😄 Great work going through some of its limitations and working around its reactivity too. One step closer to mutations! 💥

[kinow]

Oh, I bet it was not really fun to debug why the v-model was not working here ( I thought it would work, or :value.sync, which I tried but also didn't work 👀 )

[oliver-sanders]

Yeah, the data model took much longer than all the rest of the work put together. Really confused the hell out of me!

[oliver-sanders]

I think you have experienced pretty much every kind of problem I had with Vue.js 

Yes, this was a pretty steep learning curve. I think I understand Vue a lot better now though.

[oliver-sanders]

@kinow sneaking in one more commit to use mixins which make the code much D[n]RYer.

[oliver-sanders]

@wxtim I've put you down for second review. This PR should work with the master branches of Cylc Flow and Cylc UIServer.

For second review I reckon:

• Functional test.
• Skim of code.
• Check requirements/todos.

To test:

• Cylc Flow: no suite needed.
• Cylc UIS: launch as usual.
• Cylc UI: build as usual.
• Browser: Navigate to #/mutations.
• Note some errors are to be expected (see caveats in the PR description).

The code is a little funky so some pointers here:

• <component is="Foo" attr="value"> is effectively another way of writing <Foo attr="value">
• Mixins are a way of sharing configuration between components via composition rather than inheritance (similar to Cylc families) https://vuejs.org/v2/guide/mixins.html
• Components with names starting with a V come from Vuetify.

[wxtim]

I think you have experienced pretty much every kind of problem I had with Vue.js 

Yes, this was a pretty steep learning curve. I think I understand Vue a lot better now though.

You can explain it to me now.

[wxtim]

Am I supposed to do anything with the object created by using this?

Can I do something with this, or should something happen? Should I paste it into the console?

{
  "command": "\"nudge\"",
  "workflows": [
    "simple"
  ]
}

[wxtim]

I have:

• Read the code and spot any really obvious issues - at this rate my ability to read JS might overtake my abilities to read Fortran!
• Tried running the UI - looks ok - I was able to nav to #mutations.

As far as I can tell this pull request does what @oliver-sanders intends it to do, and doesn't do other stuff. I've approved it, but I'd quite like answers to my ignorant questions. I'll merge if @oliver-sanders doesn't.

[oliver-sanders]

Am I supposed to do anything with the object created by using this?

The JSON you see at the bottom of the form is just showing the data in the form. It should change as you type. The mutations page is a temporary view whilst we get all the form generation stuff sorted, the JSON is for development purposes.

Once we are finished that JSON will get attached to a GraphQL mutation and sent to the Workflow Server (via the UI Server).

[oliver-sanders]

I'd quite like answers to my ignorant questions

Keep asking, reviews are a great way of learning and even prompting authors to think more about what they've done.

[wxtim]

I'm happy that you've answered all my questions so I'm merging! Happy days.