50 lines
2.4 KiB
Markdown
50 lines
2.4 KiB
Markdown
# VerseVDI Protocol repository guidance
|
|
|
|
This repository is the sole source of the VerseVDI Phase 3 wire contract. It
|
|
contains OpenAPI, JSON Schema, Protobuf, registries, fixtures, and generated
|
|
language bindings. It contains no Connection Server business policy,
|
|
database/auth implementation, provider credentials, or media implementation.
|
|
|
|
## Source and generation rules
|
|
|
|
- Edit `schemas/`, `openapi/`, `proto/`, `registries/`, and `fixtures/` only as
|
|
protocol sources. Never hand-edit `gen/`; run `python3 tools/generate.py`.
|
|
- `VERSION` and `compatibility.json` are the version authority. Current, N-1,
|
|
and N-2 fixtures must remain executable.
|
|
- `make verify` runs schema/fixture checks, Protobuf lint/descriptor checks,
|
|
the historical-descriptor breaking check, deterministic generation, Go tests,
|
|
and native conformance runners.
|
|
- Generated output must be byte-for-byte clean after a second generation.
|
|
- `gen/protobuf/phase3a-baseline.binpb` is a generated historical descriptor used
|
|
only by Buf breaking checks; regenerate it from an approved baseline tag,
|
|
never by hand.
|
|
- The Connection Server consumes generated Go types through adapters; it does
|
|
not own a competing wire schema.
|
|
|
|
## Scope boundaries
|
|
|
|
Phase 3A covers control, authorization, resources, broker session actions,
|
|
gateway-only grants/manifests, resumable control events, registered control
|
|
datagrams, and bounded text clipboard. It does not implement a gateway,
|
|
provider transport, video/audio forwarding, file transfer, or a second auth or
|
|
datastore path.
|
|
|
|
## Git and release safety
|
|
|
|
Keep private Gitea work and public-source boundaries explicit. Preserve dirty
|
|
work from other owners. Do not push, merge, publish, or change release
|
|
credentials unless the task separately authorizes it. A local immutable
|
|
candidate tag is allowed only after matching Go/Rust/Swift fixture hashes and
|
|
clean-checkout evidence; it is not a publication.
|
|
|
|
## Private Go module identity
|
|
|
|
- The canonical module path is
|
|
`git.sechmachine.io.vn/sechmachine/VerseVDI-Protocol`.
|
|
- Generated Protobuf `go_package` options and Go consumers must use that path;
|
|
do not restore a GitHub import path or add a filesystem `replace` in a
|
|
consumer checkout.
|
|
- Consumers pin an exact immutable Protocol tag. The Protocol Gitea workflow
|
|
includes a Linux module job that verifies the module identity and builds all
|
|
Go packages; the macOS job remains the full Rust/Swift/conformance gate.
|