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).

Assets

godel-conjure-plugin supports external executables—called assets—to extend its functionality through a simple, well-defined protocol.

godel-conjure-plugin Asset Specification

An asset for godel-conjure-plugin is an executable that communicates via JSON through standard output and receives input through command-line arguments. The contract is as follows:

1. Asset Discovery (_assetInfo Probe):

• When invoked with a single argument _assetInfo, the asset must output a JSON object to stdout.
• This JSON object must include at least a type key, whose value determines how the asset will be used by godel-conjure-plugin.
• Example:

{ "type": "conjure-ir-extensions-provider" }

Note: conjure-ir-extensions-provider is currently the only supported type.

• If the asset does not output a valid JSON object with a type field, godel-conjure-plugin will fail.
• If the asset outputs a valid JSON object where the type key maps to an unknown value, godel-conjure-plugin will ignore that asset and continure execution.

2. Asset Invocation:

• For its primary operation, the asset is invoked with a single argument: a JSON-encoded object containing contextual information (the schema depends on the asset type).
• The asset should process this input and output a JSON object to stdout.
• On error, the asset should return a non-zero exit code; on success, it should exit with code 0.

3. Argument Handling:

• The asset must immediately fail if invoked with anything other than one argument.
• All information must be passed via the single JSON-encoded argument.

---

Conjure IR Extensions Asset

The only asset type currently supported by godel-conjure-plugin is "conjure-ir-extensions-provider". This asset type allows you to add key-value pairs to the extensions block of the Conjure IR during publishing.

Requirements

Type Declaration:

• The asset must respond to the _assetInfo probe with:

  { "type": "conjure-ir-extensions-provider" }

Invocation:

• When invoked, the asset receives a JSON object matching this schema with ALL of the keys having non-empty values:

struct {
  PluginConfigFile string `json:"config"`
  CurrentIRFile    string `json:"current-ir-file"`
  URL              string `json:"url"`
  GroupID          string `json:"group-id"`
  ProjectName      string `json:"project-name"`
  Version          string `json:"version"`
}

• The asset should output a JSON object to stdout. Each key-value pair in this object will be merged into the extensions block of the Conjure IR.

Example:

If you invoke the asset as follows:

./asset '{"config":"godel/config/conjure-plugin.yml",...}'

and the asset outputs:

{
  "hello": "world"
}

then the resulting Conjure IR will include:

{
  "versions": ...,
  "services": ...,
  ...
  "extensions": {
    "hello": "world"
  }
}

Key Overwrites:

• If multiple assets provide the same keys, last write wins. The order in which assets are invoked is indeterminate and should not be relied upon.

Error Handling:

• If the asset is invoked with more than one argument, it must immediately fail.
• If the asset output is not a valid JSON object, godel-conjure-plugin will fail.

Example: Minimal conjure-ir-extensions-provider Asset

#!/bin/sh

# Fail if not exactly one argument
if [ "$#" -ne 1 ]; then
    exit 1
fi

# Respond to the _assetInfo probe
if [ "$1" = "_assetInfo" ]; then
    printf '%s\n' '{ "type": "conjure-ir-extensions-provider" }'
    exit 0
fi

if <$1 is valid JSON conforming to the expected schema>; then
  # Output an empty object (no extensions)
  printf '%s\n' '{}'
  exit 0
fi

# fail
exit 1

This example asset:

• Responds to _assetInfo with the required JSON and type.
• Accepts only a single argument (the JSON object) and outputs a valid JSON object when invoked.