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

go get cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2@v2.0.0

The module requires Go 1.24 or later.

Parse and validate

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>).

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

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.