CLI for Bootstrapping Patterns

[jpgough-ms]

Feature Request

Description of Problem:

Patterns implemented as JSON Schema help to constrain and define reusable architectures. Developers can use tooling to "autocomplete" patterns, as demonstrated at #52 and at our monthly call.

We would like to propose the creation of a simple command line interface CLI that:

• Fetches a pattern
• Validates that it conforms to the CALM schema
• Runs Linting against the pattern
• Generates the target pattern instantiation in JSON or YAML
• Makes it obvious to the developer the fields that they are required to contribute to

[willosborne]

For the final bullet point - it would be great if the linter could pick up fields that weren't filled in and give the user a list of things to do on the CLI. Also, since Spectral has IDE plugins we could even get this information directly into their editor.

We could do this by just filling the blanks with some placeholder like MISSING_VALUE and then just having a spectral rule that looks for any property set to MISSING_VALUE.

[willosborne]

One consideration here is which language we should use for the bootstrap CLI. In my mind we have two main options, Python and Node (i.e. JS or TypeScript.) I've had a think about some pros/cons - would be good to hear people's thoughts

Python

Pros

• Great argument parser (click) that also has strong support for subcommands
• More native libraries for JSON Schema validation than Node
• Can publish CLI tool to pypi for easy consumption

Cons

• No native interop with visualisation tool as that is based on JS - would need to call out via subprocess
• No native interop with Spectral, would need to call out via subprocess

Node / JavaScript

Pros

• Similar arg parser library based on Python's click (Commander)
• Native interop with visualization tool @aidanm3341 is working on
• Native interop with Spectral - can use it from within a Node app
• Can publish CLI tool to NPM for easy consumption
• Option for strong typing via TypeScript

Cons

• Strong typing may be a hindrance in early stages as CALM schema is volatile - more refactoring needed
• Main option for JSON Schema validation is ajv - if that doesn't work we will need to call out to another CLI tool via subprocess

Other languages

Java:

• CLI tools are weaker than Node/Python
• No interop with tools in use,
• Heavier CLI size due to fat jar
• CLI install may be more difficult

Go:

• Less widely used language, so experience may be limited

[aidanm3341]

We've been discussing this in person and I'm in favour of Node. I've already been working on embedding the new Mermaid visualizer tool in a simple Commander CLI just for the purposes of making it usable and found to be very easy to work with (PR for that incoming soon). So if we go that way, the groundwork will already have been done as well.

[rocketstack-matt]

I think the only question against Node would be is schema validation tools are week, especially as most of our other tools are currently Node. What do we need to do to close out on the schema validation questions?

[willosborne]

We need to confirm that we can validate JSON schemas against a metaschema with libraries available in Node.
Given that OpenAPI is a metaschema this should be possible - will take a look at this today.

[Budlee]

Golang, negatives I would disagree with?
It's a very viable choice for creating a CLI and is very widely used. There are some fantastic frameworks for CLI development in Go and the flags package is in the std lib which for most cases more than enough to develop a good quality CLI.

[willosborne]

Another question is how the CLI is going to fetch pattern files. This relates to #69 - the CLI needs to be able to pull patterns not only from this industry-standard repository but also internal repositories for an organisation.

Our suggestion is that we keep this as simple as possible from the pattern CLI's perspective by letting you provide either a HTTP URL (with no auth) or a file reference, and the CLI will load it.

In other words, no CLI or similar abstraction for 'looking up' patterns by name yet; we can always add this later if need be.

Something like the following:

• calm generate -s FILE/URL (-s for source) to load a schema from a file or URL (can tell based on the presence of a URL scheme)

In future we could add a dictionary of pattern names to file/URL references to the project to allow resolution by a pattern name. This is a separate topic - we can proceed without implement this if people are happy with the above suggestion.

[Budlee]

Would you not want to start by looking up a file and then a future improvement will be sourcing from a URL if it's a feature that is required?

[aidanm3341]

We've been testing out the AJV JSON Schema library and so far it seems promising. For the basic case of validating a pattern instantiation, it works as expected. The case we're interested in is validating the pattern against the meta schema. We've been able to get this to work by fixing what we believe to be some mistakes in the core.json and api-gateway.json, e.g.

• The required field in core.json should be outside of the properties object, not inside it
• The way we use the items keyword is required to be called prefixItems as of JSON Schema 2020-12
• In api-gateway.json, many of the nodes don't have node-type defined, despite it being a required field on a node

I can raise an issue for the above problems unless anyone thinks we're wrong.

Once fixing those issues, we're still running into one problem where all properties on a node are required to have the field nodes for some reason. We'll continue looking into that issue tomorrow, but we are definitely encouraged about this library based on the progress that we made today.

[willosborne]

Raised a discussion here about approach for instantiation to avoid polluting this thread with multiple concurrent discussions: #71

[rocketstack-matt]

We've been testing out the AJV JSON Schema library and so far it seems promising. For the basic case of validating a pattern instantiation, it works as expected. The case we're interested in is validating the pattern against the meta schema. We've been able to get this to work by fixing what we believe to be some mistakes in the core.json and api-gateway.json, e.g.

• The required field in core.json should be outside of the properties object, not inside it
• The way we use the items keyword is required to be called prefixItems as of JSON Schema 2020-12
• In api-gateway.json, many of the nodes don't have node-type defined, despite it being a required field on a node

I can raise an issue for the above problems unless anyone thinks we're wrong.

Once fixing those issues, we're still running into one problem where all properties on a node are required to have the field nodes for some reason. We'll continue looking into that issue tomorrow, but we are definitely encouraged about this library based on the progress that we made today.

Happy for you to go ahead and raise a PR for the changes . . . for the pattern that just shows we didn't update it along with the schema changes and shows we have a gap to close around keeping patterns up to date with manifest changes; this isn't a simple validation because they currently reference specific schema versions and even if we were to move to a 'current' version we would need to merge and publish it before it would be spotted that it broke something.

[rocketstack-matt]

Another question is how the CLI is going to fetch pattern files. This relates to #69 - the CLI needs to be able to pull patterns not only from this industry-standard repository but also internal repositories for an organisation.

Our suggestion is that we keep this as simple as possible from the pattern CLI's perspective by letting you provide either a HTTP URL (with no auth) or a file reference, and the CLI will load it.

In other words, no CLI or similar abstraction for 'looking up' patterns by name yet; we can always add this later if need be.

Something like the following:

• calm generate -s FILE/URL (-s for source) to load a schema from a file or URL (can tell based on the presence of a URL scheme)

In future we could add a dictionary of pattern names to file/URL references to the project to allow resolution by a pattern name. This is a separate topic - we can proceed without implement this if people are happy with the above suggestion.

Fine with this for a first version, although we should probably raise an issue to track adding a central supported patterns repo as a fairly high priority.

[rocketstack-matt]

This issue is complete, specific additions will br tracked in their own issues.