mirror of
https://github.com/TronoSfera/backupy-agent.git
synced 2026-05-18 18:13:30 +03:00
8b0c978337
Source ports from the TronoSfera/backupy-cloud monorepo:
- apps/agent/ — Go agent (WSS client, persistent queue, Docker
discovery, 5 DB drivers: PG/MySQL/Mongo/Redis/SQLite,
pre/post hooks, Prometheus metrics)
- apps/backupy-decrypt/ — standalone CLI for client-side decryption
- packages/proto/ — protobuf wire format (generated .pb.go committed
so the repo builds without protoc)
- docs/ — agent spec + wire-protocol contract
Apache-2.0 license. Image published to ghcr.io/tronosfera/backupy-agent
on every v* tag via .github/workflows/release.yml (multi-arch amd64+arm64).
91 lines
2.7 KiB
Markdown
91 lines
2.7 KiB
Markdown
# `packages/proto`
|
|
|
|
Canonical Protobuf wire format for Backupy.
|
|
|
|
Both the Go agent (`apps/agent`) and the Go server (`apps/server`) consume the
|
|
generated bindings produced from these `.proto` files. The contract itself is
|
|
described in [`docs/07-api-contract.md`](../../docs/07-api-contract.md) — this
|
|
package is the executable form of that document.
|
|
|
|
## Layout
|
|
|
|
```
|
|
packages/proto/
|
|
├── buf.yaml # module config: lint (STANDARD), breaking (FILE)
|
|
├── buf.gen.yaml # codegen plugin config (protoc-gen-go)
|
|
├── v1/
|
|
│ ├── common.proto # shared enums + messages
|
|
│ ├── envelope.proto # Envelope wrapper (oneof of all payloads)
|
|
│ ├── agent_to_server.proto # Register, Heartbeat, JobUpdate, ...
|
|
│ └── server_to_agent.proto # RegisterAck, ConfigUpdate, RunBackup, ...
|
|
└── gen/
|
|
└── go/v1/ # generated Go bindings (committed)
|
|
```
|
|
|
|
Package name: `backup.v1`.
|
|
Go import path: `github.com/backupy/backupy/packages/proto/gen/go/v1`
|
|
(`backupv1` short name).
|
|
|
|
## Prerequisites
|
|
|
|
Install [buf](https://buf.build/docs/installation) and the Go plugin once
|
|
per workstation:
|
|
|
|
```sh
|
|
# from the repo root
|
|
make tools
|
|
```
|
|
|
|
That installs `buf` and `protoc-gen-go` into `$GOBIN` (or `$GOPATH/bin`).
|
|
|
|
## Regenerating code
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
make gen
|
|
```
|
|
|
|
This `cd`s into `packages/proto` and runs `buf generate`. The output is
|
|
written to `packages/proto/gen/go/v1/`.
|
|
|
|
Alternatively, from this directory:
|
|
|
|
```sh
|
|
buf generate
|
|
```
|
|
|
|
## Linting and breaking-change detection
|
|
|
|
```sh
|
|
# from the repo root
|
|
make lint # includes `buf lint`
|
|
|
|
# or directly
|
|
cd packages/proto
|
|
buf lint
|
|
buf breaking --against '.git#branch=main,subdir=packages/proto'
|
|
```
|
|
|
|
`buf.yaml` enables the `STANDARD` lint set and `FILE`-level breaking-change
|
|
detection. Field renames or tag-number changes in any committed `.proto`
|
|
will fail CI.
|
|
|
|
## Adding a new message
|
|
|
|
1. Pick the right file (`agent_to_server.proto` vs `server_to_agent.proto`),
|
|
or add a new shared type to `common.proto`.
|
|
2. Use a fresh field number — never reuse a `reserved` tag.
|
|
3. If it is a new top-level message that flows over WSS, also add it to the
|
|
`Envelope.payload` `oneof` in `envelope.proto`, picking a stable tag in
|
|
the matching direction's range (agent→server: 10..49, server→agent:
|
|
50..99).
|
|
4. Run `make gen` and commit both the `.proto` change and the regenerated
|
|
Go files in the same commit.
|
|
5. Run `buf breaking` locally before pushing.
|
|
|
|
## Versioning
|
|
|
|
The package is `backup.v1`. Any breaking change requires a new package
|
|
(`backup.v2`) plus at least six months of dual-support — see
|
|
[`docs/07-api-contract.md` §11](../../docs/07-api-contract.md).
|