# vantage-shared

The private Go module every Vantage service imports. Extracted from the
`vantage` monorepo with its history.

```
vantage-shared/
├── grpc/pb/                    # the agent↔control-plane wire types, hand-written
├── grpc/codec/                 # the JSON codec they travel over
├── proto/vantage/v1/           # vantage.proto - documentation for the above
├── mail/                       # the one email system: transport + templates
├── license/                    # payload, sign, verify, trusted keys, plans
├── models/                     # Instance, User, Settings
├── provision/                  # slug rules, reserved names, instance/user creation
├── backup/                     # dump, restore, verify, manifest, fingerprint
├── cryptobox/                  # the single AES-256-GCM implementation
├── indexes/                    # users.email and instances.slug
└── cmd/lkctl/                  # issue and inspect licences by hand
```

Module path is `gitea.hostxtra.co.uk/vantage/vantage-shared` - **lowercase
`vantage`**, though the Gitea org is canonically `Vantage`. Gitea serves both
spellings; Go module paths are case-sensitive strings, and two spellings would
cache as two modules. Keep the lowercase one.

## Who depends on this, and when they find out

| Repository       | Modules                                  | A change here reaches them                          |
| ---------------- | ---------------------------------------- | ---------------------------------------------------- |
| `vantage`        | `server`, `agent`, `vantagectl`          | `server` at the next push to main after a pin bump; `agent` and `vantagectl` only at their next release tag |
| `vantage-admin`  | `server`                                 | at the next push to main after a pin bump           |
| `vantage-site`   | `server`                                 | at the next push to main after a pin bump           |

**Nothing bumps a pin automatically.** A fix here is live nowhere until each
consumer's `go.mod` moves, and nothing in any of those repositories will remind
you. That is the trade this split made: a service can no longer be shipped
against a version of this module it was never built against, and in exchange the
staleness is now silent rather than impossible.

Tag a release when you change anything: `git tag v0.2.0 && git push origin
v0.2.0`. Consumers pin exact versions.

## `proto/` is documentation, not a generator input

`grpc/pb` is **hand-written** JSON-tagged structs over the codec in
`grpc/codec`. Nothing generates them, and `vantage.proto` is not compiled by any
build. It is the readable statement of the wire contract, and it lives in the
same repository as the Go types precisely so that a message added to one can be
added to the other **in the same commit** - that co-location is the only thing
enforcing the match, so do not split them again.

There used to be two copies of `pb`, in the agent and the server, and they had
already drifted: the agent's `UnimplementedVantageServer` was three methods
stale and carried no `ReportWorkloads` at all. One package now serves both
sides. The agent links the server half as dead code, which the linker drops.

**A wire change lands in three steps, in this order**: release this module, bump
the pin in `vantage/server` (live at the next push to main), bump the pin in
`vantage/agent` (live only at the next `agent/v*` tag). The control plane will
be ahead of the fleet in between, which was true before too - it is just written
down in two `go.mod` files now instead of implied by a shared directory.

## Things that mirror something outside this repository

These cannot be enforced by the compiler and must be changed by hand, in step
with a file in another repository:

- **`backup.ciphertextFields`** names each collection's `*_enc` fields and
  mirrors `server/internal/models` in the `vantage` repository, which this
  module cannot import. Wrong field names fail **silently**: `verify`'s live
  probe finds no ciphertext and reports "this database stores no ciphertext
  yet", so the one gate that catches what a key fingerprint cannot becomes a
  no-op. `settings` is deliberately in neither that map nor
  `CiphertextCollections()` - its ESO read token is a SHA-256 hash, not
  ciphertext.
- **`mail/templates/layout.html.tmpl`** carries the control plane's dark theme
  values as **literal hex**. Email clients support neither `var()` nor a
  reliable `prefers-color-scheme`, so the token indirection the four front ends
  use is not available here. Every colour in the email system is in that one
  file. The tokens it mirrors live in `vantage-site`.
- **`provision`** is the single implementation of the slug rules that both the
  control plane and Vantage HQ depend on. It is the one place those two
  repositories must agree on behaviour, which is why it is here rather than
  copied - but it now also means a change to it is a release and two pin bumps.

`mail/render_test.go` renders every template and fails if one exists that no
case covers. The templates are parsed in `init()`, so without that test a
mistyped field is a boot-time panic in three services.

## Writing style

Never use em dashes (the long dash character) anywhere: code, comments, UI copy, docs, commit messages. Use a plain hyphen ` - `, a comma, a colon, or split the sentence instead.