buffrs 0.13.0

Modern protobuf package management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

## Local Dependencies

When working on larger projects or in monorepo projects setups you may find
yourself in the situation to consume a locally defined buffrs project.

Imagine the following project setup:

```
mono
├── build.rs
├── Cargo.toml
├── Proto.toml
├── Proto.toml
├── proto
|   └── mono.proto
└── src
    └── main.rs
```

In this scenario the buffrs project for `mono-api` and the cargo project for
the `mono-server` are setup in the very same directory, which is totally fine
as long as this server does not require other buffrs api packages to be
compiled!

#### Problem

Adding a dependency on other (unrelated api packages to `mono-api`) is
complicated in the above scenario because its not clear to buffrs whether you
are trying to reuse third party api definitions for your api or just wanting to
install protos for compilation.

Hence buffrs will throw you an error if you try to publish an api package with
dependencies on other apis!

```
Error:   × failed to publish `mono-api` to `http://<registry-uri>/<repository>`
  ╰─▶ depending on API packages is not allowed
```

#### Solution

Gladly buffrs offers a builtin solution for this! You can separate the
`mono-api` buffrs package (used to publish your api) from the `mono-server`
buffrs projects (used to install protos for compiling the server).

A monorepo setup here could look like this:

```
mono
├── mono-api
|   ├── Proto.toml
|   └── proto
|       └── mono.proto
└── mono-server
    ├── build.rs
    ├── Cargo.toml
    ├── Proto.toml
    ├── proto
    |   └── vendor
    └── src
        └── main.rs
```

Where `mono/mono-api/Proto.toml` has this content:

```
edition = "0.9"

[package]
type = "api"
name = "mono-api"
version = "0.1.0"
```

And `mono/mono-server/Proto.toml` has this content:

```
edition = "0.9"

[dependencies]
mono-api = { path = "../api" }
third-party-api = { version = "=1.0.0", repository = "some-repo", registry = "http://..." }
```

This enables you to:

- Independently publish `mono-api` using `buffrs publish` / `buffrs package`
- Independently declare dependencies for `mono-server`

#### Publishing with Local Dependencies

Since version 0.12, buffrs automatically handles publishing packages with local dependencies:

```bash
cd mono-server
buffrs publish --registry http://... --repository my-repo
```

Buffrs will:
1. Recursively resolve all local dependencies (and their transitive dependencies)
2. Publish each local dependency in topological order
3. Rewrite local references in the published manifest to point to the registry

For example, if `mono-server` depends on `mono-api` (local), buffrs first publishes `mono-api` to the registry, then publishes `mono-server` with the dependency updated to reference the registry location instead of the local path.

This makes it seamless to develop locally while maintaining publishable packages.