amps-client-go

amps-client-go

A feature-complete, high-performance Go client for AMPS — built from scratch to match and outperform the official C/C++ client on critical hot paths.

Version: 0.8.20

Why This Client?

AMPS is one of the fastest message brokers on the planet. Building a client worthy of that speed — in Go, without CGO — was the goal. This project delivers:

• 🏎️ Faster than C on the hot path — Go client outperforms the official C library on header parsing and SOW batch processing at p95/p99
• 🔬 261 parity-mapped symbols — full Client and HAClient API surface, tested against C++ 5.3.5.1 behavior
• 🛡️ Production-grade quality gates — 90%+ coverage, zero open parity gaps, enforced regression budgets on every PR
• ⚡ Zero-allocation critical paths — header parse, uint decode, timeout poll, and string conversion all run at 0 allocs/op
• 🔄 HA failover built in — reconnect strategies, bookmark replay, publish stores, and server chooser with no manual plumbing

If you're building on AMPS and you need a Go-native client that doesn't compromise on performance, this is it.

Performance: Go vs Official C Client

All benchmarks run on the same machine, same workload, same measurement methodology (nearest-rank percentiles, 20 samples). Lower is better.

Hot-Path Parity Results (Go vs Official C)

These are the strict parity workloads we currently gate for C-vs-Go comparisons. Lower is better.

This is 5/5 wins on the in-scope hot-path parity suite (p95).

Connect-and-logon timings are tracked separately and treated as out of scope for this steady-state hot-path gate.

Full-Suite Tail Latency (Go Internal Benchmarks)

Every hot path in the client is micro-benchmarked and tracked across commits. Here are the current numbers at p95 (20 samples each):

How We Measure

• Methodology: go test -bench=. -benchtime=1s -count=20 with nearest-rank percentile extraction
• C baselines: compiled from the official AMPS C client library, run with the same fake server and payload profiles
• Regression gates: PRs fail on >7% ns/op regression or >5% allocs/op regression against committed baselines
• Artifacts: all raw data committed in tools/perf_tail_baseline.json, tools/perf_tail_current.json, tools/perf_tail_comparison.json, and tools/perf_side_by_side_baseline.json

Feature Completeness

This isn't a minimal SDK. It's a full-surface client with behavior parity across the entire C++ Client and HAClient public API.

Supported Workflows

Install

go get github.com/Thejuampi/amps-client-go/amps

Spark-Compatible CLI

gofer is the repository's spark-compatible command-line client.

go run ./cmd/gofer help
go run ./cmd/gofer ping -server localhost:9007 -type json
go run ./cmd/gofer publish -server localhost:9007 -type json -topic orders -data '{"id":1}'

Fake AMPS Harness

tools/fakeamps now supports AMPS-style XML server configuration in addition to flags.

go run ./tools/fakeamps --sample-config
go run ./tools/fakeamps --verify-config config.xml
go run ./tools/fakeamps --dump-config config.xml
go run ./tools/fakeamps --config config.xml

It also serves a browser dashboard and monitoring API from the admin listener:

go run ./tools/fakeamps --config config.xml
# then open http://127.0.0.1:8085/

See tools/fakeamps/README.md for the supported XML sections, dashboard/admin routes, the Extensions/FakeAMPS runtime block, and the deterministic validation rules for unsupported custom modules and UDFs.

Quick Start

package main

import (
 "fmt"

 "github.com/Thejuampi/amps-client-go/amps"
)

func main() {
 client := amps.NewClient("example-client")
 if err := client.Connect("tcp://localhost:9000/amps/json"); err != nil {
  panic(err)
 }
 defer client.Close()

 if err := client.Logon(); err != nil {
  panic(err)
 }

 _, err := client.SubscribeAsync(func(message *amps.Message) error {
  fmt.Println(string(message.Data()))
  return nil
 }, "orders")
 if err != nil {
  panic(err)
 }

 if err := client.Publish("orders", `{"id":1}`); err != nil {
  panic(err)
 }
}

Documentation

📖 Full Documentation Index

Build and Test

make build
make static-scan
make leak-check
make fuzz-smoke
make test-race
make test
make integration-test
make integration-live-smoke
make stress-check
make parity-check
make coverage-check
make perf-check
make vuln-scan
make preprod-check
make release

make static-scan now combines go vet, staticcheck, ineffassign, errcheck, the repo-specific patterncheck analyzer, and an expanded bug-focused golangci-lint lane.

go vet ./...
go run honnef.co/go/tools/cmd/staticcheck@v0.7.0 -checks=SA* ./...
go run github.com/gordonklaus/ineffassign@v0.2.0 ./...
go run github.com/kisielk/errcheck@v1.10.0 -ignoretests ./...
go run ./tools/patterncheck ./...
go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8 run --config .golangci.yml ./...
go test -count=1 ./amps
go test -count=1 ./tools/fakeamps -run '^(TestStartLeaseWatcher|TestStopLeaseWatcherStopsBackgroundLoop)$$'
go test ./amps -run=^$$ -fuzz=FuzzParseHeader -fuzztime=5s
go test ./amps -run=^$$ -fuzz=FuzzParseBookmarkToken -fuzztime=5s
go test ./amps -run=^$$ -fuzz=FuzzParseSocketOptions -fuzztime=5s
go test ./amps -run=^$$ -fuzz=FuzzCompositeMessageParser -fuzztime=5s
go test -race ./... -skip Integration
go test ./... -skip Integration
go test ./... -run Integration
go test -count=1 ./amps -run '^(TestIntegrationConnectLogonPublishSubscribe|TestIntegrationSOWAndSowAndSubscribeLifecycle|TestIntegrationQueueAutoAckBatching|TestIntegrationBookmarkResumeAcrossReconnect|TestIntegrationHAConnectAndLogonWithFailoverChooser)$$'
go test -race -shuffle=on -count=20 ./... -skip Integration
go run ./tools/paritycheck -manifest tools/parity_manifest.json
go test -count=1 ./amps/... -coverprofile=coverage.out
go run ./tools/coveragegate -profile coverage.out
make compat-check
make perf-compare-toolchains
go run ./tools/withtoolchain -toolchain go1.25.10+auto -- run ./tools/perfgate -baseline tools/perf_baseline.json
go run ./tools/withtoolchain -toolchain go1.25.10+auto -- run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...

License

MIT. See LICENSE.