BSR Remote Packages debug tool

An experimental command to print a BSR Remote Package version based on plugin and module inputs.

Bonus, the tool itself leverages Remote Packages (BSR Go module proxy) to download a connect-go client for the Buf Schema Registry API.

The API is backed by connect, and the protobuf definitions are publicly available at bufbuild/buf.

No protobuf, no compilers, no code generation. Just go get ... and you're up and running with an API client in seconds!

Installation

go install github.com/mfridman/bsr-remotever@latest

Example

The go.mod in this repository depends on 2 Go packages from the BSR Go module proxy:

require (
	buf.build/gen/go/bufbuild/buf/bufbuild/connect-go v1.5.2-20230222163843-c806e06ce889.1
	buf.build/gen/go/bufbuild/buf/protocolbuffers/go v1.28.1-20230222163843-c806e06ce889.4
)

You typically go get ... @latest without worrying about versions, so you always have an up-to-date package, which is a combination of the latest plugin by semver and latest module by the latest commit on main.

But, in the odd event we need to obtain the version based on some references, we can use this tool like so:

plugin: bufbuild/connect-go:latest
module: bufbuild/buf:latest

$ bsr-remotever bufbuild/connect-go:latest bufbuild/buf:latest | jq -r .version

v1.5.2-20230222163843-c806e06ce889.1

plugin: protocolbuffers/go:latest
module: bufbuild/buf:latest

$ bsr-remotever protocolbuffers/go:latest bufbuild/buf:latest | jq -r .version

v1.28.1-20230222163843-c806e06ce889.4

Both of these assume buf.build as the remote, but you can also provide the remote like so:

plugin: buf.build/protocolbuffers/go:latest
module: buf.build/bufbuild/buf:latest

Which allows for setting a custom remote. The remote for the plugin and module must be the same.

The module reference can be latest (same as main), a tag, or a draft.

E.g., the bufbuild/buf module has a tag (60ee4a1ad9fe22392fea98967d858de8f15131ac) that resolves to a specific commit (c806e06ce8894eee9ba4932f95c8fa43).

We use the tag as a module reference:

$ bsr-remotever bufbuild/connect-es:latest bufbuild/buf:60ee4a1ad9fe22392fea98967d858de8f15131ac | jq -r .version

v0.8.0-20230222163843-c806e06ce889.1

The same will work for drafts!

Bonus

This command also returns the go get ... or npm install ... commands depending on the plugin, with helpful hints:

Go

$ bsr-remotever bufbuild/connect-go:latest bufbuild/buf:main | jq -r .command

go get buf.build/gen/go/bufbuild/buf/bufbuild/connect-go@v1.5.2-20230222163843-c806e06ce889.1

$ bsr-remotever bufbuild/connect-go:latest bufbuild/buf:main | jq -r .hint

Set GOPRIVATE=buf.build/gen/go

See https://docs.buf.build/bsr/remote-packages/go#private for more details.

NPM

$ bsr-remotever bufbuild/connect-es:latest bufbuild/buf:main | jq -r .command

npm install @buf/bufbuild_buf.bufbuild_connect-es@v0.8.0-20230222163843-c806e06ce889.1

$ bsr-remotever bufbuild/connect-es:latest bufbuild/buf:main | jq -r .hint

Don't forget to update the registry config:

        npm config set @buf:registry https://buf.build/gen/npm/v1/

For private modules you'll need to set the token:

        npm config set //buf.build/gen/npm/v1/:_authToken {token}

See https://docs.buf.build/bsr/remote-packages/npm#private for more details.