mirror of https://github.com/vernonkeenan/lib
Merge pull request #6 from vernonkeenan/docs/readme-changelog-refresh
docs: refresh README.md and CHANGELOG.md to the constellation docs standardpull/7/head
Vernon Keenan
GitHub
commit
f26fd154b3
|
|
@ -0,0 +1,135 @@
|
|||
# Changelog
|
||||
|
||||
All notable changes to `go/lib` (`code.tnxs.net/vernonkeenan/lib`) are
|
||||
documented here. The format is based on
|
||||
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Releases are
|
||||
`v*` git tags cut from `main` via `make release VERSION=vX.Y.Z`
|
||||
(main + PR flow, ADR-KV-014, which also governs KV-C6 lib
|
||||
distribution — see also ADR-KV-004/006 for the mesh-wide branching/release
|
||||
model). **Branch-per-version is retired** as of 2026-07-12: `main` was
|
||||
created from the `v0.7.4` tip and is now the only long-lived branch; the
|
||||
~70 legacy `vX.Y.Z` branches still present in the repo are historical
|
||||
artifacts of the old convention, not active release refs. Every section
|
||||
below corresponds to a real git tag in this repo's history (only `v0.7.5`,
|
||||
cut by the new `make release` script, is an annotated tag — the 71 tags
|
||||
before it are lightweight, a holdover from the old ritual); no tag, date,
|
||||
or PR number is invented.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
No commits on `main` since `v0.7.5` — HEAD is at the `v0.7.5` tag.
|
||||
|
||||
## [v0.7.5] — 2026-07-12
|
||||
|
||||
First release cut with the new `make release` scripted ritual (ADR-KV-014),
|
||||
and the first release with CI behind it.
|
||||
|
||||
### Added
|
||||
- First-ever CI for `lib`: `go build/vet/test ./...` job plus a gitleaks
|
||||
secret-scan job on every push/PR, closing out the last un-covered repo in
|
||||
the 12-repo Go-mesh test-harness program (ci/first-ci-gitleaks, PR #1)
|
||||
- Table-driven unit tests for `app/service-helpers.go`'s pure helpers
|
||||
(test/app-service-helpers, PR #2)
|
||||
|
||||
### Changed
|
||||
- Replaced the manual three-web-UI-plus-CLI release ritual with
|
||||
`scripts/release.sh` / `make release` + `make release-dry-run`
|
||||
(feat/scripted-release, ADR-KV-014, PR #3)
|
||||
- Regenerated all sibling clients under `api/` with go-swagger v0.35.0
|
||||
(feat/regen-clients-processor-token, PR #5)
|
||||
|
||||
### Fixed
|
||||
- `PaymentMethod` swagger def updated for the `card_*` → `processor_token`
|
||||
migration (PR #4)
|
||||
|
||||
## [v0.7.4] — 2025-05-27
|
||||
|
||||
### Added
|
||||
- Generated session-management API client and models
|
||||
|
||||
## [v0.7.3] — 2025-05-01
|
||||
|
||||
### Changed
|
||||
- Refactored swagger defs (`Address`, `CompanyProduct`, `CompanyService`,
|
||||
`Factor`, `FinancialStatement`, `Industry`, `IndustryCompany`,
|
||||
`IndustryProduct`, `IndustryService`, `Observation`, `Topic`) to use
|
||||
external `$ref` component defs instead of inline definitions
|
||||
|
||||
## [v0.7.2] — 2025-04-30
|
||||
|
||||
### Changed
|
||||
- Replaced `AccountID` with `CompanyID` in `GetIndustryCompaniesParams` and
|
||||
the related swagger definitions
|
||||
|
||||
## [v0.7.1] — 2025-04-29
|
||||
|
||||
No code changes — retag of the same commit as `v0.7.0`/`v0.6.7`.
|
||||
|
||||
## [v0.7.0] — 2025-04-29
|
||||
|
||||
No code changes — retag of the same commit as `v0.6.7`.
|
||||
|
||||
## [v0.6.7] — 2025-04-29
|
||||
|
||||
### Added
|
||||
- Enrichment fields on `Account`, `CompanyProduct`, and `CompanyService`
|
||||
models
|
||||
|
||||
## [v0.6.6] — 2025-04-29
|
||||
|
||||
### Changed
|
||||
- General code-structure refactor for readability/maintainability
|
||||
|
||||
## [v0.6.5] — 2024-06-30
|
||||
|
||||
### Added
|
||||
- `Channels` field on `Account` and `Contact` models
|
||||
|
||||
## [v0.6.4] — 2024-06-29
|
||||
|
||||
### Added
|
||||
- `AppExchange` URL field on `CompanyProduct` model
|
||||
|
||||
## [v0.6.3] — 2024-06-28
|
||||
|
||||
### Added
|
||||
- `AppExchange` URL field on `CompanyProduct` model
|
||||
|
||||
## [v0.6.2] — 2024-06-28
|
||||
|
||||
### Added
|
||||
- `AppExchange` URL field on `Account` and `Company` models
|
||||
|
||||
## [v0.6.1] — 2024-06-27
|
||||
|
||||
### Added
|
||||
- `FullDescription` field on `Account` model
|
||||
|
||||
## [v0.6.0] — 2024-01-22
|
||||
|
||||
### Added
|
||||
- `FullDescription` field on `Industry` model
|
||||
|
||||
## Pre-v0.6.0 history (v0.0.1 – v0.5.15, 2021-07-30 – 2023-08-25)
|
||||
|
||||
58 tags predate `v0.6.0`, from `lib`'s original scaffolding through the
|
||||
last patch release before the year-and-a-half gap to `v0.6.0`. Coarse
|
||||
summary by theme (no PR numbers — this history predates the PR-merge
|
||||
convention):
|
||||
|
||||
- **2021 (v0.0.1–v0.1.9):** Initial `app` package scaffolding — config,
|
||||
logger, MySQL, and Salesforce (`go-force`) init helpers; first
|
||||
go-swagger client generation against the estate's early services
|
||||
(including a since-retired Telnexus/Kazoo-era client, still visible as
|
||||
vendored specs under `swagger/`); early devops endpoint moves and
|
||||
`/etc` config-path changes.
|
||||
- **2022 (v0.1.2–v0.4.9):** Buildout of `sf-gate` and `members` swagger
|
||||
clients; schema cleanups; `research` and `plex` microservices added to
|
||||
the platform; user/session/batch-endpoint additions across `sf-gate` and
|
||||
`members`.
|
||||
- **2023 H1 (v0.5.0–v0.5.8):** `members` feature buildout — prompts and
|
||||
prompt answers, favorites, documents, event categories, external
|
||||
accounts — plus a research-domain refactor.
|
||||
- **2023 H2 (v0.5.9–v0.5.15):** Steady patch releases stabilizing the
|
||||
prompts/members surface; `v0.5.15` (2023-08-25) is the last tag before
|
||||
the gap to `v0.6.0`.
|
||||
194
README.md
194
README.md
|
|
@ -1,72 +1,164 @@
|
|||
# lib
|
||||
# go/lib — Shared Go library for the Keenan Vision service mesh
|
||||
|
||||
vernonkeenan Shared Libraries (go)
|
||||
`go/lib` (module `code.tnxs.net/vernonkeenan/lib`) is the shared toolchain
|
||||
every Go microservice in the Keenan Vision mesh pins in its `go.mod`. It is
|
||||
not a service — it ships no server, no Dockerfile, no compose entry — it is
|
||||
a library `app` package (`InitConfig`/`InitDB`/`InitForce`, config
|
||||
accessors, zap logging, Prometheus/CORS middleware, generic marshal
|
||||
helpers) plus a set of go-swagger–generated typed HTTP clients (`api/`)
|
||||
against the sibling services' own swagger specs. Because every mesh service
|
||||
pins the same module, a `lib` bump is a constellation-wide rebuild (KV-C6a).
|
||||
|
||||
## Dependent Systems
|
||||
## Constellation context
|
||||
|
||||
The Gitea server <https://code.tnxs.net> must be up and running with admin access. It hosts world-readable
|
||||
pull-mirrors of this repo at `vernonkeenan/lib` and `work/lib`.
|
||||
- Toolchain member of the Keenan Vision Go mesh governed by `../../kv-meta/`
|
||||
(see `../../kv-meta/CONSTELLATION.md` §1.3, contract KV-C6). Not a
|
||||
deployed service: no swagger server, no port, no entry in the
|
||||
`docker/kvweb` compose on pluto.
|
||||
- KV-C6a: every mesh service (`auth`, `cache`, `crm`, `members`, `pdf`,
|
||||
`plex`, `render`, `research`, `sf-gate`, `stash`) pins an explicit
|
||||
`code.tnxs.net/vernonkeenan/lib` tag in its own `go.mod`; consumption is a
|
||||
per-consumer `go.mod` bump, never automatic.
|
||||
- Distribution is via a world-readable Gitea pull-mirror at
|
||||
`code.tnxs.net/vernonkeenan/lib` (and `work/lib`), enabling
|
||||
credential-free `go get code.tnxs.net/vernonkeenan/lib@vX.Y.Z` from
|
||||
Docker/CI/dev boxes even though the GitHub repo itself is private
|
||||
(ADR-KV-014). Everything committed here is treated as **published,
|
||||
permanently** — a gitleaks CI gate makes leaking a secret a build
|
||||
failure, not a review nit.
|
||||
- CI (self-hosted runner, `go build/vet/test ./...` + gitleaks on every
|
||||
push/PR) landed 2026-07-12 as `lib`'s first-ever pipeline (ADR-KV-014) —
|
||||
`lib` was the only one of the 12 Go-roster repos with no CI at all going
|
||||
into the 2026-07-12 test-harness audit, so this closes out that gap. The
|
||||
`test` job is `lib`'s instance of the mesh-wide unit-test-gate program
|
||||
(ADR-KV-009, amended by ADR-KV-013, which scopes `lib` as one of its 12
|
||||
governed repos); the `gitleaks` job is ADR-KV-014's public-mirror
|
||||
secret-scan gate, specific to `lib` because it's the one repo mirrored
|
||||
world-readable.
|
||||
- `api/` also acts as `lib`'s own internal client of the mesh: `app/auth.go`'s
|
||||
`CheckAPIUser` calls `auth`'s generated client to validate an API key, so
|
||||
`lib` is simultaneously a library *and* a consumer of one sibling service.
|
||||
|
||||
## Release Procedure
|
||||
## Package surface
|
||||
|
||||
As of 2026-07-12 (ADR-KV-014, DT-KV-004) this repo is `main` + `v*` tags — branch-per-version is retired, and
|
||||
so is the old three-web-UI-plus-CLI manual ritual. Releasing is one command: `make release VERSION=vX.Y.Z`.
|
||||
| Path | What it is |
|
||||
|---|---|
|
||||
| `app/root.go` | `InitConfig(systemName, level)` — loads `/etc/vernonkeenan/<systemName>.yaml` via viper, one-time init guard |
|
||||
| `app/config.go` | `Configuration` struct + `Get*`/`Is*` accessors (DBMS, DSN, log level, metrics, service accounts, workers, email, chunk/cache sizing) |
|
||||
| `app/mysql.go` | `InitDB()` — opens `MyDB *sql.DB` against the configured MySQL DSN |
|
||||
| `app/force.go` | `InitForce(serviceAccountName)` — opens a Salesforce `go-force` API connection from a configured service account |
|
||||
| `app/auth.go` | `CheckAPIUser(token)` — validates an API key against `auth`'s generated client |
|
||||
| `app/prometheus.go` | `SetupPrometheusHandler` — CORS + request-count/duration middleware |
|
||||
| `app/service-helpers.go` | Pointer helpers (`String`/`Bool`/`Int64`/…), `GetFieldsAndValues` reflection helper (unit-tested) |
|
||||
| `app/user.go`, `user-helpers.go`, `tenantuser.go`, `userrole.go`, `address.go` | First-class domain structs + swagger marshal/unmarshal helpers shared by consumers |
|
||||
| `app/logger/logger.go` | Thin `zap.SugaredLogger` wrapper (`New(level)`, level constants) |
|
||||
| `api/{auth,crm,members,plex,research,sfgate,stash}/` | go-swagger–generated typed clients + models, one directory per sibling service, regenerated from that service's own spec |
|
||||
| `swagger/*.yaml`, `swagger/defs/`, `swagger/external/` | Copies of each sibling service's spec (the KV-C6b spec-copy problem — no sync mechanism besides `make regen`), shared component defs, and host/path-rewritten copies for external doc publishing; also carries legacy vendored Kazoo/Clerk specs from `lib`'s pre-mesh history |
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* All the sibling service repos (`auth`, `crm`, `stash`, `sf-gate`, `research`, `members`, `plex`) are cloned
|
||||
locally in adjacent directories — `regen` reads each one's `swagger/<service>-vernonkeenan.yaml`.
|
||||
* [`gh`](https://cli.github.com/) installed and authenticated (`gh auth login`) with push access to
|
||||
`vernonkeenan/lib` — the release step calls `gh release create`.
|
||||
* `GITEA_TOKEN` exported, set to a Gitea API token (Settings -> Applications on <https://code.tnxs.net>) with
|
||||
rights to trigger a mirror-sync on `vernonkeenan/lib` and `work/lib`. If unset, `make release` still tags,
|
||||
pushes, and publishes the GitHub release — it just skips the Gitea mirror-sync step with a loud warning, so
|
||||
the mirrors will lag until someone clicks Synchronize Now manually or reruns with the token set. (There is
|
||||
no existing Gitea/tnxs token variable defined anywhere in this workstation's env files today — `GITEA_TOKEN`
|
||||
is a new name, not a rename of something already in use.)
|
||||
|
||||
### 1. Regenerate the API clients (its own PR)
|
||||
## Build, run, test
|
||||
|
||||
```bash
|
||||
make regen
|
||||
go build ./...
|
||||
go vet ./...
|
||||
go test ./... # table-driven unit tests today: app/service-helpers.go pure helpers
|
||||
make install-swagger # install the pinned go-swagger CLI (SWAGGER_VERSION in Makefile)
|
||||
make regen # aka `make swagger` — regenerate api/ from sibling specs
|
||||
make release VERSION=vX.Y.Z
|
||||
make release-dry-run VERSION=vX.Y.Z
|
||||
```
|
||||
|
||||
This installs the pinned go-swagger CLI (`SWAGGER_VERSION` in the `Makefile`, currently `v0.35.0` — bump
|
||||
deliberately and update both places when you do), copies each sibling repo's `swagger/<service>-vernonkeenan.yaml`
|
||||
into `./swagger` and `./swagger/external`, regenerates every client under `api/`, and rewrites the external
|
||||
specs' scheme/host/path exactly as the old `make swagger` ritual did. It fails fast, before touching anything,
|
||||
if any sibling spec is missing.
|
||||
`go test ./...` is CI-gating on every push and PR (ADR-KV-009/013), same as
|
||||
the rest of the mesh; `lib` is a library so there is nothing to "run."
|
||||
|
||||
Review `git status`/`git diff`, commit, open a PR, and merge it to `main` like any other change — client regen
|
||||
is not bundled into the release step itself. `make regen` runs a non-fatal `go build ./...` at the end as an
|
||||
early warning; the real gate is CI on that PR.
|
||||
`make regen` requires the sibling repos `auth`, `crm`, `stash`, `sf-gate`,
|
||||
`research`, `members`, `plex` cloned adjacently — it reads each one's
|
||||
`swagger/<service>-vernonkeenan.yaml`, copies it into `./swagger` and
|
||||
`./swagger/external`, and regenerates every client under `api/`, rewriting
|
||||
the external specs' scheme/host/path the same way the old `make swagger`
|
||||
ritual did. It fails fast, before touching anything, if any sibling spec is
|
||||
missing. Review `git status`/`git diff`, commit, open a PR, and merge it to
|
||||
`main` like any other change — client regen is never bundled into the
|
||||
release step; `make regen` runs a non-fatal `go build ./...` at the end as
|
||||
an early warning, but the real gate is CI on that PR.
|
||||
|
||||
**Known gap:** if any sibling spec has an operation with no top-level `tags:`, go-swagger routes it into a
|
||||
fallback `operations` package whose import path in `<name>_client/<name>_client.go` doesn't respect
|
||||
`--client-package` — reproduced across go-swagger v0.33.2 through v0.35.0 while building this tooling. As of
|
||||
this writing that's `sf-gate-vernonkeenan.yaml`'s `PUT /researchprojectservices` (no `tags:`). Fix it at the
|
||||
source (add a `tags:` entry in the `sf-gate` repo's spec) rather than hand-patching generated code, since the
|
||||
**Known gap (resolved for the current spec set, but can recur):** if any
|
||||
sibling spec has an operation with no top-level `tags:`, go-swagger routes
|
||||
it into a fallback `operations` package whose import path in
|
||||
`<name>_client/<name>_client.go` doesn't respect `--client-package` —
|
||||
reproduced across go-swagger v0.33.2 through v0.35.0 while building this
|
||||
tooling. The one instance found, `sf-gate-vernonkeenan.yaml`'s `PUT
|
||||
/researchprojectservices` (no `tags:`), was fixed at the source (sf-gate
|
||||
#3 added the missing `tags:` entry) and regenerated clean in the v0.7.5
|
||||
`feat/regen-clients-processor-token` PR — `api/sfgate` has no fallback
|
||||
`operations` package today. If a future sibling spec change reintroduces an
|
||||
untagged operation, `make regen`'s non-fatal `go build ./...` step will
|
||||
fail with this same signature; fix it at the source (add a `tags:` entry in
|
||||
that service's spec) rather than hand-patching generated code, since the
|
||||
next regen would just reintroduce it.
|
||||
|
||||
### 2. Cut the release (from a clean `main` checkout)
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
make release VERSION=v0.7.5
|
||||
```
|
||||
`lib` reads no config file of its own. `app.InitConfig(systemName, level)`
|
||||
loads config **on behalf of the calling service**: viper reads
|
||||
`/etc/vernonkeenan/<systemName>.yaml` (YAML), with environment-variable
|
||||
overrides via prefix `VERNONKEENAN_` (`.` replaced by `_` in key names),
|
||||
unmarshalled into `app.Configuration` — `AppName`, `BackendID`,
|
||||
`DBMS`/`DBMSHost`/`DBMSName`/`DBMSUsername`/`DBMSPassword`, `DSN`,
|
||||
`Environment`, `LogLevel`, `GelfURI`, `Metrics` (address/enabled),
|
||||
`ServiceAccounts` (a map of external-system credentials, e.g. the `auth`
|
||||
service account `CheckAPIUser` reads its own API key from), `Workers`,
|
||||
`Email`, `CacheSizes`/`Chunks`. The concrete `/etc/vernonkeenan/<name>.yaml`
|
||||
file lives on each deploy host, not in this repo — see the calling
|
||||
service's own README for its file name and required keys.
|
||||
|
||||
`scripts/release.sh` (invoked by the `release` target):
|
||||
## Versioning & pinning contract (KV-C6a)
|
||||
|
||||
1. Validates `VERSION` is `vMAJOR.MINOR.PATCH` and strictly greater than the latest existing tag.
|
||||
2. Requires you're on `main`, the tree is clean, and local `main` matches `origin/main` (no local-only commits).
|
||||
- **Module:** `code.tnxs.net/vernonkeenan/lib`, fetched via the Gitea
|
||||
anonymous mirror (not GitHub directly — the GitHub repo is private).
|
||||
- **Pin, don't float:** every consumer pins an explicit `vX.Y.Z` tag in its
|
||||
`go.mod`. Bumping the pin is a normal PR in the consumer repo; there is no
|
||||
auto-bump mechanism.
|
||||
- **Release is one command:** `make release VERSION=vX.Y.Z`
|
||||
(`scripts/release.sh`) from a clean `main` checkout that matches
|
||||
`origin/main`:
|
||||
1. Validates `VERSION` is `vMAJOR.MINOR.PATCH` and strictly greater than
|
||||
the latest existing tag.
|
||||
2. Requires you're on `main`, the tree is clean, and local `main` matches
|
||||
`origin/main` (no local-only commits).
|
||||
3. Runs `go build ./...` and `go vet ./...` as a last sanity check.
|
||||
4. Creates an annotated tag at HEAD, pushes it, and runs `gh release create` with generated notes.
|
||||
5. POSTs to the Gitea mirror-sync API for `vernonkeenan/lib` and `work/lib` (skipped with a warning if
|
||||
`GITEA_TOKEN` is unset).
|
||||
4. Creates an annotated tag at HEAD, pushes it, and runs `gh release
|
||||
create` with generated notes.
|
||||
5. POSTs to the Gitea mirror-sync API for `vernonkeenan/lib` and
|
||||
`work/lib` (skipped with a warning if `GITEA_TOKEN` is unset — there is
|
||||
no existing Gitea/tnxs token variable defined anywhere on this
|
||||
workstation today; `GITEA_TOKEN` is a new name, not a rename of
|
||||
something already in use).
|
||||
|
||||
Use `make release-dry-run VERSION=v0.7.5` to run steps 1-3 and print what steps 4-5 would do, without tagging,
|
||||
pushing, publishing, or syncing anything.
|
||||
`make release-dry-run VERSION=vX.Y.Z` runs steps 1-3 and prints what
|
||||
steps 4-5 would do, without tagging, pushing, publishing, or syncing
|
||||
anything.
|
||||
- **A `lib` bump is constellation-wide:** any breaking change to
|
||||
`app.Configuration`, `InitConfig`/`InitDB`/`InitForce`, or a generated
|
||||
client's shape ripples to every pinned service on its next `go.mod` bump.
|
||||
- **Branch-per-version is retired** (ADR-KV-014, 2026-07-12): `lib` moved
|
||||
to main + `v*` tags, replacing the old three-web-UI-plus-CLI manual
|
||||
release ritual. ~70 legacy `vX.Y.Z` branches (one per pre-migration
|
||||
release; `git branch --list 'v*'`) remain in the repo as historical
|
||||
artifacts of the old convention, not the active release mechanism.
|
||||
- **Prerequisites for a release:** the sibling repos (for `make regen`)
|
||||
cloned adjacently; [`gh`](https://cli.github.com/) authenticated with
|
||||
push access to `vernonkeenan/lib`; `GITEA_TOKEN` exported for the
|
||||
mirror-sync step (optional — see above).
|
||||
|
||||
### 3. Downstream consumers
|
||||
## Release & deploy
|
||||
|
||||
Update the `go.mod` line for `code.tnxs.net/vernonkeenan/lib` in each dependent project to the new tag, same
|
||||
as before — that part of the old ritual is unchanged.
|
||||
`main` + PR flow: land changes on `main` via PR (CI runs build/vet/test +
|
||||
gitleaks on the PR and on push to `main`), then cut a release with `make
|
||||
release VERSION=vX.Y.Z`, which tags `main`, publishes a GitHub release, and
|
||||
triggers the Gitea mirror-sync. Unlike the deployed mesh services, `lib` has
|
||||
**no Dockerfile, no container image, and no deploy step** — it is never
|
||||
built into `hub.tnxs.net` and never rolled out via the `docker/kvweb`
|
||||
compose on pluto. "Release" means "a new tag other repos can pin," full
|
||||
stop; downstream rollout happens when each consumer bumps its own `go.mod`
|
||||
line for `code.tnxs.net/vernonkeenan/lib` to the new tag and goes through
|
||||
its own release/deploy path.
|
||||
|
|
|
|||
Loading…
Reference in New Issue