A configuration validator, and associated plugin error conformance utility, for GAPIC config proto annotations.

The protoc-gen-gapic-validator protoc plugin ensures that the given protobuf files contain valid GAPIC configuration values. The configuration values are supplied via proto annotations defined at googleapis/api-common-protos.

To provide a tool that emits actionable messages when protobufs are inproperly configured for GAPIC generation.

Furthermore, to provide a utility that enables GAPIC micro-generator error message conformance testing.

To use the plugin, protoc must be installed.

> curl -sSL https://github.com/googleapis/gapic-config-validator/releases/download/v$SEMVER/gapic-config-validator-$SEMVER-$OS-$ARCH.tar.gz | tar xz
> chmod +x protoc-gen-gapic-validator
> export PATH=$PATH:`pwd`

> go get github.com/googleapis/gapic-config-validator/cmd/protoc-gen-gapic-validator

> mkdir -p $GOPATH/src/github.com/googleapis
> cd $GOPATH/src/github.com/googleapis
> git clone https://github.com/googleapis/gapic-config-validator.git
> cd gapic-config-validator
> go install ./cmd/protoc-gen-gapic-validator

make install executes that last go install command for ease of development.

protoc -I $COMMON_PROTO -I . --gapic-validator_out=. a.proto b.proto

The $COMMON_PROTO variable represents a path to the googleapis/api-common-protos directory to import the configuration annotations.

For the time being, the output directory specified by gapic-validator_out is not used because there is nothing generated. This value can be anything.

It is recommended that this validator be invoked prior to gapic-generator-* micro-generator invocation.

protoc -I $COMMON_PROTO \
    -I . \
    --gapic-validator_out=. \
    --go_gapic_out $GO_GAPIC_OUT \
    --go_gapic_opt $GO_GAPIC_OPT
    a.proto b.proto

In your WORKSPACE, include the project:

http_archive(
  name = "com_googleapis_gapic_config_validator",
  strip_prefix = "gapic-config-validator-0.2.6",
  urls = ["https://github.com/googleapis/gapic-config-validator/archive/v0.2.6.zip"],
)

load("@com_googleapis_gapic_config_validator//:repositories.bzl", "com_googleapis_gapic_config_validator_repositories")

com_googleapis_gapic_config_validator_repositories()

In your BUILD file, configure the target:

load("@com_googleapis_gapic_config_validator//:rules_validate/validate.bzl", "gapic_config_validation")

gapic_config_validation(
  name = "validate_acme_proto",
  srcs = [":acme_proto"],
)

The GAPIC v1 config comparison feature can be invoked with the gapic_yaml attribute:

gapic_config_validation(
  name = "validate_acme_proto",
  srcs = [":acme_proto"],
  gapic_yaml = ":acme_gapic.yaml"
)

Note: this feature will eventually be removed once the GAPIC v1 config is deprecated fully.

A successful build means there are not issues or discrepancies. A failed build means there were findings to report, which are found on stderr.

Micro-generator authors (or other GAPIC config-based plugin authors) can test the conformance of their error messages against the gapic-config-validator using the provided gapic-error-conformance testing tool.

The gapic-error-conformance utility is a binary that exercises both the gapic-config-validator and the targeted plugin against a set of error mode scenarios. The error emitted by the given plugin is diff'd against that of the validator and reported to the user. If a plugin error does not conform, the gapic-error-conformance utility will have an exit code of one.

> curl -sSL https://github.com/googleapis/gapic-config-validator/releases/download/v$SEMVER/gapic-config-validator-$SEMVER-$OS-$ARCH.tar.gz | tar xz
> chmod +x gapic-error-conformance
> export PATH=$PATH:`pwd`

> go get github.com/googleapis/gapic-config-validator/cmd/gapic-error-conformance

> mkdir -p $GOPATH/src/github.com/googleapis
> cd $GOPATH/src/github.com/googleapis
> git clone https://github.com/googleapis/gapic-config-validator.git
> cd gapic-config-validator
> go install ./cmd/gapic-error-conformance

make install executes that last go install command for ease of development.

> gapic-error-conformance -plugin="protoc-gen-go_gapic" -plugin_opts="go-gapic-package=foo.com/bar/v1;bar"

• -plugin: the plugin command to execute. This could the path to an executable or just the executable itself if it's in the PATH.
• -plugin_opts: comma-delimited string of options to supply the plugin executable.
• -verbose: verbose logging mode. Logs the error messages of the validator and plugin

The scenarios exercised by gapic-error-conformance are built into the binary. This means the protobufs provided as CodeGeneratorRequest input are built dynamically. The scenarios() method builds the list of scenarios to exercise. Adding a new scenario means adding the code to build the protobuf & CodeGeneratorRequest here.

Note: the proto dependencies required by the GAPIC config annotations are loaded and provided via the common() method.

If you are contributing to this project, run the tests with make test.

To view code coverage, run make coverage.

Some tests require more well-defined descriptors than it makes sense to define by hand in the tests themselves.

The internal/validator/testdata directory contains protos and their generated types that are used in tests.

Should a change be made to the protos in this directory, the generated types need to be regenerated via make gen-testdata. You will need the aforementioned $COMMON_PROTO set properly.

Create a new tag with the form vX.Y.Z and push it git push --tags. GitHub Actions will create the release and the appropriate assets.

This is not an official Google product.