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@v1.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_env directives are required. idle_timeout and traffic_idle_timeout accept Go duration strings.

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_env APPLICATION_POSTGRES_PASSWORD
            idle_timeout 10m
            traffic_idle_timeout 1h
        }
    }
}

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@latest.