buffrs 0.12.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

## Package Types

Buffrs makes distinctions between two different packages:

```toml
[package]
type = "lib" | "api"
```

This is used in order to fuel composition and type reuse across APIs and thus
enable shared types + wire compatibility.

### `lib` – Libraries

Libraries contain atomic and composite type definitions that describe a domain.
(e.g. `physics`, `auth`, `time` etc.). This pattern is really useful for
scaling systems and maintaining dozens of APIs as they can share types and thus
get the aforementioned benefits of source code and wire compatibility for free.

An example of a proto library named `time` that depends on `google`:

```toml
[package]
name = "time"
type = "lib"
version = "1.0.0"

[dependencies]
google = { version = "=1.0.0", ... }
```

```proto
syntax = "proto3";

package time;

import "google/timestamp.proto";

/// A timestamp wrapper for various formats
message Time {
  oneof format {
    string rfc3339 = 1;
    uint64 unix = 2;
    google.protobuf.Timestamp google = 3;
    ..
  }
}
```

### `api` – APIs

APIs are the next logical building block for real world systems – they define
services and RPCs that your server can implement. You can use the
aforementioned libraries to fuel your development / API definition experience.

A good example of an API could be an imaginary `logging` service that makes use
of the just declared `time.Time`:

```toml
[package]
name = "logging"
type = "api"
version = "1.0.0"

[dependencies]
time = { version = "=1.0.0", ... }
```

```proto
syntax = "proto3";

package logging;

import "time/time.proto";

service Logging {
  rpc critical(LogInput) returns (LogOutput);
  rpc telemetry(LogInput) returns (LogOutput);
  rpc healthiness(HealthInput) returns (HealthOutput);
}

message LogInput { string context = 1; time.Time timestamp = 2; }
message LogOutput { }

message HealthInput { bool db = 1; }
message HealthOutput { }
```