Cargo#

The BSR exposes a Cargo registry at https://buf.build/gen/cargo/ and serves BSR-generated Rust crates from it. A first install:

$ cargo add --registry buf connectrpc_eliza_community_neoeinstein-prost

For an end-to-end walkthrough across SDK languages, see the generated SDKs quickstart.

Configure the registry#

Add the BSR Cargo registry to your .cargo/config.toml:

.cargo/config.toml

[registries.buf]
index = "sparse+https://buf.build/gen/cargo/"
credential-provider = "cargo:token"

Authenticate#

Create a BSR token; see Authentication: Create a token. Then store it for the buf registry:

$ cargo login --registry buf "Bearer {token}"

The literal string Bearer is part of the credential value; replace {token} with your BSR token.

The registry has to be configured in .cargo/config.toml before cargo login runs; --registry buf resolves through the [registries.buf] block above.

Add a generated SDK#

cargo add --registry buf accepts the BSR crate name:

$ cargo add --registry buf connectrpc_eliza_community_neoeinstein-prost

The example installs the connectrpc/eliza module’s code generated by the community/neoeinstein-prost plugin.

SDK names#

Each crate is named after the module and plugin that produced it:

{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}

For example, connectrpc_eliza_community_neoeinstein-prost is the connectrpc/eliza module produced by the community/neoeinstein-prost plugin. The four components join with _; characters that already appear inside any one component (for example, the hyphen in neoeinstein-prost) stay as-is.

Versions#

A BSR Cargo version concatenates the plugin and module commit:

Version syntax

{pluginVersion}-{commitTimestamp}-{commitShortName}.{pluginRevision}

# Example
0.3.1-20240523144506-ce529d32d80c.1

Part	Example	Source
Version core	`0.3.1`	Plugin version.
Pre-release: timestamp	`20240523144506`	Module commit timestamp (`YYYYMMDDHHMMSS`).
Pre-release: commit	`ce529d32d80c`	First 12 characters of the module commit ID.
Build metadata	`1`	Plugin revision.

Commits pushed to non-default labels carry 00000000000000 as the timestamp, so they sort below released versions. These versions still resolve through cargo add, but copy them verbatim from the module’s SDKs tab on the BSR or from buf registry sdk version rather than constructing them by hand.

To pin a specific plugin version against a chosen module reference, use the buf registry sdk version CLI command.

How generation is triggered#

Unlike the BSR’s other generated SDKs, which generate lazily on request, Rust crates have to be generated eagerly: Cargo’s package index requires a checksum for every crate version before clients can resolve it, and the BSR can’t compute that checksum without producing the crate first.

Once you’ve run cargo add against a crate, every subsequent push to that crate’s repository default label triggers generation of the next version automatically.

To prime generation for a non-default label or a specific commit, navigate to the module on the BSR and switch the label or commit using the dropdown. Future pushes against that reference then generate SDKs for it.

Available plugins#

The full list of supported Rust plugins lives on the BSR plugins page (filter for Rust). For how those plugins are packaged, see the bufbuild/plugins repository; to request a new plugin, file an issue.