# 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`.