palantir / godel-conjure-plugin

godel plugin that generates Conjure for Go projects

godel-conjure-plugin

godel-conjure-plugin is a godel plugin for conjure-go. The plugin runs conjure-go based on project configuration. It also runs as part of the --verify task and verifies that the running the task would not alter the content of the output directory.

Tasks

• conjure: runs Conjure generation. Runs for all of the entries specified in the configuration in order. The working directory is set to be the project directory.
• conjure-publish: publishes IR to a specified destination.

Verify

When run as part of verification that does not apply, the task fails if running the task would alter any of the contents of the output directory. The output directory will not be modified as part of this process. Note that the implementation operates by temporarily making a copy of the output directory. For this reason, one should avoid having large files in the output directory.

Config

The configuration for this plugin is in a file called conjure-plugin.yml. The configuration should be of the following form:

version: 1
projects:
  project-1:
    output-dir: outputDir
    ir-locator: local/conjure-yaml-files
  project-2:
    output-dir: outputDir
    ir-locator: https://host.com/conjure-ir-file.json

The top-level projects is a map where the key is the name of the Conjure task and the value is the configuration for that task. output-dir specifies the base directory into which the output is written. The ir-locator parameter specifies how the IR should be retrieved.

IR locators can specify a local Conjure YAML file, a local directory that contains Conjure YAML files (in which case the IR generated by the input YAML files is used), a URL that points to a Conjure IR file or a local file that specifies Conjure IR.

If the locator is specified as a string, its target is determined as follows:

• If it starts with a URL scheme ("http://", "https://", etc.), it is considered to be a URL
• If the specified path exists and is a file, it is assumed to be a Conjure IR file
• Otherwise, it is assumed to be a Conjure YAML directory

If the inference rules above are not sufficient, then the locator type can be specified explicitly. For example, "localhost:8080/ir.json" will not be inferred to be a remote IR provider because it does not start with a scheme. In order to be used as a remote provider, the type must be specified explicitly:

version: 1
projects:
  project-1:
    output-dir: outputDir
    ir-locator:
      type: remote
      locator: localhost:8080/ir.json

The supported types are remote, yaml and ir-file.

Publish

The conjure-publish task publishes Conjure IR to a location based on the provided arguments. The Conjure IR files that can be published are determined based on the projects defined in conjure-projects block. By default, YAML locator types are considered as possible to publish (because publish workflow most commonly publish IR generated from local YAML). However, publish: true can be set on a project explicitly to allow it to publish its IR.

The publish command uses the Git versioner of distgo to determine the version for the IR and uses distgo's Artifactory publisher to publish the IR to an Artifactory destination.

Here is an example invocation to publish a Conjure definition:

./godelw conjure-publish --group-id=com.palantir.test-group --url https://artifactory.com --repository "$PUBLISH_REPO" --username "$ARTIFACTORY_USERNAME" --password "$ARTIFACTORY_PASSWORD"

The --dry-run flag can be added to print the operation that would be performed (including the upload URL).