87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# Barkfile Parser
|
|
|
|
`barkfile-parser` is the Go source of truth for the Barkfile schema. It parses and validates the current PawSQL `pawsql` document and watches a Barkfile for validated revisions so control-plane consumers can reconfigure without owning another parser.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
go get cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2@v2.0.0
|
|
```
|
|
|
|
The module requires Go 1.24 or later.
|
|
|
|
## Parse and validate
|
|
|
|
```go
|
|
cfg, err := barkfile.Load("/etc/pawsql/Barkfile")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
```
|
|
|
|
`Load` reads, parses, and validates a file. `Parse` parses bytes when a caller owns file I/O; call `Config.Validate` before applying a parsed configuration.
|
|
|
|
The current schema defines one `pawsql` block with a listener, an optional TLS `cert`/`key` pair, and one or more `database` routes. A route has exactly one of:
|
|
|
|
- `upstream <host:port>` for an external PostgreSQL server.
|
|
- `postgres { ... }` for a managed PostgreSQL container. Its `image`, `volume`, and `password_secret` directives are required. `password_secret` is a short lowercase reference resolved to the Docker secret `barkstack_<reference>`. `idle_timeout` and `traffic_idle_timeout` accept Go duration strings.
|
|
- `treatvault { ... }` (optional, top-level) configures TreatVault: `file` is the path to the age-encrypted secret source of truth, and `identity_secret` is a short reference for the Docker secret holding the age identity (`barkstack_<reference>`).
|
|
|
|
```text
|
|
pawsql {
|
|
listen :5432
|
|
|
|
tls {
|
|
cert /etc/pawsql/tls/fullchain.pem
|
|
key /etc/pawsql/tls/privkey.pem
|
|
}
|
|
|
|
database application {
|
|
hostname app.db.example.com
|
|
postgres {
|
|
image postgres:18
|
|
volume application-data
|
|
password_secret application_postgres_password
|
|
idle_timeout 10m
|
|
traffic_idle_timeout 1h
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
With TreatVault configured, create the referenced password through the TreatVault page in the Barkstack Console. `barkstack init` creates the identity Docker secret when absent; the TreatVault service initializes the encrypted file and creates the Docker secret on sync.
|
|
|
|
## Watch validated changes
|
|
|
|
```go
|
|
ctx, cancel := context.WithCancel(context.Background())
|
|
defer cancel()
|
|
|
|
changes, err := barkfile.Watch(ctx, "/etc/pawsql/Barkfile", barkfile.WatchOptions{})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
for change := range changes {
|
|
if change.Err != nil {
|
|
log.Printf("Barkfile update rejected: %v", change.Err)
|
|
continue
|
|
}
|
|
apply(change.Config)
|
|
}
|
|
```
|
|
|
|
`Watch` emits the initial valid configuration, then each content change. It polls every 250ms by default; set `WatchOptions.PollInterval` to override it. Invalid or temporarily unreadable revisions are emitted as `Change.Err` and do not stop the watcher. A later valid revision is emitted normally.
|
|
|
|
## Releases
|
|
|
|
Gitea Actions runs tests on each `main` push. The release job reads Conventional Commit messages since the last `v*` tag and pushes a new semantic-version tag when needed:
|
|
|
|
| Commit | Version change |
|
|
| --- | --- |
|
|
| `feat:` | minor |
|
|
| `fix:` or `perf:` | patch |
|
|
| `type!:` or `BREAKING CHANGE:` | major |
|
|
| other types | no release |
|
|
|
|
Go consumers update through standard module versions, for example `go get cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2@latest`.
|