mirror of https://github.com/TronoSfera/backupy-agent.git synced 2026-05-18 18:13:30 +03:00

History

TronoSfera 8b0c978337 feat(initial): Backupy agent + backupy-decrypt CLI 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).		2026-05-17 20:22:35 +03:00
..
backupv1	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00
gen	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00
.gitignore	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00
buf.gen.yaml	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00
buf.yaml	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00
README.md	feat(initial): Backupy agent + backupy-decrypt CLI	2026-05-17 20:22:35 +03:00

README.md

`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 — 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 and the Go plugin once per workstation:

# from the repo root
make tools

That installs buf and protoc-gen-go into $GOBIN (or $GOPATH/bin).

Regenerating code

From the repository root:

make gen

This cds into packages/proto and runs buf generate. The output is written to packages/proto/gen/go/v1/.

Alternatively, from this directory:

buf generate

Linting and breaking-change detection

# 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

Pick the right file (agent_to_server.proto vs server_to_agent.proto), or add a new shared type to common.proto.
Use a fresh field number — never reuse a reserved tag.
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).
Run make gen and commit both the .proto change and the regenerated Go files in the same commit.
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.