README
¶
pstate
pstate is a small, dependency-free persistent JSON state store for scheduled jobs and services. It began as the immutable state core in prangl and is designed for independent angl heartbeat invocations that need to share durable, queryable state without operating a database server.
- Untyped: keys are strings; values are arbitrary JSON.
- Deterministic: values are compacted, object keys and query results are ordered, and queries have explicit JSON semantics.
- Durable: writes use same-directory temporary files, file flushes, atomic replacement, and directory flushes on Unix.
- Process-safe: each transaction locks a sidecar
<store>.lock, reloads the latest revision, and commits once. Concurrent jobs do not overwrite one another. - Snapshot-friendly: the Go package includes an immutable AVL tree with structural sharing and a lock-free CAS model whose background writer coalesces snapshots.
- Portable: Windows and Unix implementations use only the Go standard library.
Install
go install github.com/jack-work/pstate/cmd/pstate@latest
For a Go module:
go get github.com/jack-work/pstate@latest
CLI
Choose a state file explicitly for each job, or set PSTATE_FILE. If neither is set, the default is <user-config>/pstate/state.json.
$state = "$env:LOCALAPPDATA\pstate\deployments.json"
pstate --file $state set jobs/orchard '{"state":"running","attempts":2,"owner":"orchard"}'
pstate --file $state get jobs/orchard
pstate --file $state query 'key ^= "jobs/" && .state == "running"'
pstate --file $state query --keys '.attempts >= 2'
pstate --file $state delete jobs/orchard
get emits the JSON value. query emits a JSON array of {key,value} objects sorted by key. Use --jsonl for one object per line or --keys for plain keys. Successful mutations are quiet, making them safe in angl logs. Diagnostics go to stderr.
Apply several edits in one durable transaction:
@'
[
{"op":"set","key":"jobs/a","value":{"state":"ready"}},
{"op":"set","key":"jobs/b","value":[1,2,3]},
{"op":"delete","key":"jobs/old"}
]
'@ | pstate --file $state apply -
Exit statuses are 0 for success, 1 for operational/query errors, 2 for usage errors, and 3 when get cannot find its key.
Run pstate --help for the complete command guide.
Query language
The query language is deliberately small and deterministic:
key ^= "jobs/" && .state == "failed"
.attempts >= 3 && (.owner == "orchard" || !.owner)
.runs[0].status == "timed-out"
value["odd key"] *= "needle"
Selectors
| Selector | Meaning |
|---|---|
key |
Entry key as a string |
value |
Entire JSON value |
.field, value.field |
Object field |
.runs[0] |
Array index |
value["odd key"] |
Quoted object field |
A bare selector tests existence. Missing paths are false for every comparison, including !=; therefore !.owner means “owner is absent.”
Operators
| Operators | Types / meaning |
|---|---|
==, != |
JSON equality; numbers compare by exact mathematical value (3 == 3.0) |
<, <=, >, >= |
Exact numbers or ordinal strings; mixed types do not match |
^=, $=, *= |
String prefix, suffix, or substring |
!, &&, ||, ( ) |
Negation, short-circuit conjunction/disjunction, grouping |
Literals use JSON syntax. There are no timestamps, environment interpolation, regex engines, locale-dependent comparisons, or implicit string/number conversions.
Go package
Use Store when separate processes may touch the same file:
package main
import (
"log"
"github.com/jack-work/pstate"
)
func main() {
store, err := pstate.Open(`C:\state\job.json`)
if err != nil { log.Fatal(err) }
value, err := pstate.EncodeValue(map[string]any{
"state": "ready",
"attempts": 1,
})
if err != nil { log.Fatal(err) }
snapshot, err := store.Apply(pstate.Patch{}.
Set("jobs/a", value).
Delete("jobs/old"))
if err != nil { log.Fatal(err) }
log.Printf("revision %d contains %d keys", snapshot.Version(), snapshot.Len())
}
Tree and Snapshot are immutable and safe to retain while newer roots are published. Model is for one long-lived process that wants lock-free reads and coalesced asynchronous serialization:
model := pstate.NewModel(initialTree, pstate.WriterFunc(func(s pstate.Snapshot) error {
// Serialize this immutable point-in-time snapshot.
return nil
}))
defer model.Close()
A Model coordinates goroutines in one process; a Store coordinates transactions between processes. Do not use an independently loaded Model as a multi-process read-modify-write mechanism.
File format and recovery
The store is human-readable JSON:
{
"schema": 1,
"revision": 2,
"entries": [
{"key": "jobs/a", "value": {"state": "ready"}}
]
}
Entries are serialized in lexical key order. A mutation that makes no net change does not rewrite the file or increment revision. The .lock file is intentionally persistent and contains no state. A failed or interrupted replacement leaves the preceding complete snapshot readable; temporary files may be removed safely when no writer is active.
Development
go test ./...
go test -race ./...
go vet ./...
The test suite covers AVL invariants and structural sharing, immutable snapshots, CAS concurrency, writer coalescing and failures, durable file round trips, overlapping transactions, query parsing/evaluation, and CLI streams/exit statuses.
License
MIT
Documentation
¶
Overview ¶
Package pstate provides a schema-free persistent JSON state store for jobs and services. It combines immutable ordered snapshots, lock-free in-process models, and process-safe atomic file transactions.
Index ¶
- Variables
- type Entry
- type Model
- func (m *Model) Apply(patch Patch) (Snapshot, error)
- func (m *Model) Close() error
- func (m *Model) Delete(key string) (Snapshot, error)
- func (m *Model) Flush() error
- func (m *Model) Get(key string) (Value, bool)
- func (m *Model) LastError() error
- func (m *Model) Len() int
- func (m *Model) Set(key string, value Value) (Snapshot, error)
- func (m *Model) Snapshot() Snapshot
- type Patch
- type Query
- type Snapshot
- type Store
- type Tree
- type Value
- type Writer
- type WriterFunc
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("pstate: model closed")
ErrClosed is returned by operations that cannot run after Close begins.
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model provides lock-free snapshots and CAS updates. Its single background worker coalesces notifications and calls Writer serially. Use Store for coordination between separate processes.
func NewModel ¶
NewModel starts a model containing initial. A nil writer disables I/O while retaining Flush and Close semantics.
func (*Model) Apply ¶
Apply atomically publishes all edits as one update. A patch with no net change does not advance the version.
func (*Model) Close ¶
Close rejects future updates, flushes the final snapshot, and stops the worker.
func (*Model) Flush ¶
Flush waits until a snapshot at least as recent as the one captured at call start has been persisted successfully.
func (*Model) LastError ¶
LastError returns the most recent background persistence error. A successful write clears it.
type Patch ¶
type Patch struct {
// contains filtered or unexported fields
}
Patch is an immutable ordered batch of edits. Its zero value is empty. If a key occurs more than once, the final edit wins.
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query is a compiled deterministic predicate over an entry. Queries are safe for concurrent use.
func ParseQuery ¶
ParseQuery compiles an expression. An empty expression matches every entry.
Selectors are key, value, .field, value.field, and array/object paths such as .runs[0].status or value["odd key"]. Operators are ==, !=, <, <=, >, >=, ^= (prefix), $= (suffix), and *= (substring). Combine predicates with !, &&, ||, and parentheses. Literals use JSON syntax.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is an immutable point-in-time view. Version increases once per successfully published Model update or Store transaction.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a process-safe file-backed state store. Each mutation takes an exclusive sidecar lock, reloads the latest snapshot, and durably replaces the file, preventing lost updates between independent heartbeat invocations.
func (*Store) Apply ¶
Apply atomically commits a patch against the latest on-disk snapshot. A patch with no net change does not rewrite the file or advance its revision.
type Tree ¶
type Tree struct {
// contains filtered or unexported fields
}
Tree is an immutable, string-keyed ordered map of JSON values. Its zero value is empty. Set and Delete share all unaffected nodes with the original tree.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is an immutable, canonical JSON value. Its zero value is JSON null.
func EncodeValue ¶
EncodeValue converts v to an immutable JSON value.
func ParseValue ¶
ParseValue validates data and returns its deterministic compact encoding.
func (Value) Equal ¶
Equal reports JSON equality. Values are canonical, so this is constant time apart from comparing their encodings.
func (Value) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*Value) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type WriterFunc ¶
WriterFunc adapts a function to Writer.
func (WriterFunc) WriteSnapshot ¶
func (f WriterFunc) WriteSnapshot(snapshot Snapshot) error
WriteSnapshot calls f(snapshot).
Source Files
Directories