Go Utils

Reusable Go packages for service infrastructure, cryptography and PKI, file processing, and agent memory — plus the gutils command-line toolbox.

Go compatibility · Get started · Package guide · CLI · Safety and migration · Contributing

Go Utils brings common infrastructure tasks into one versioned Go module. Use the root package for caches, HTTP helpers, concurrency, rate limiting, files, and permissions; import subpackages for more specialized work.

• Services: structured logging, expiring caches, token-bucket limits, HTTP clients, SMTP, and database field helpers.
• Security: authenticated encryption, signatures, password hashing, X.509/CSR utilities, JWT verification, and explicit RBAC grants.
• Files and data: gzip/ZIP operations, hashing, text templates, generic data structures, and a file-management CLI.
• Agents: file-storage interfaces, local and MCP backends, conversation history, tiered memory, and context preparation.

This is a library and toolbox, not an application framework, hosted KMS, authentication server, or complete agent runtime. Import the packages you need; they share a module and may bring transitive dependencies. Prefer the standard library when it already covers your use case.

Choose the release line that matches your Go toolchain:

These are the project's historical documented compatibility baselines, not fresh test results or a guarantee of ongoing maintenance for older release lines. Check the selected tag's go.mod for its exact toolchain requirements. The current v6 CI policy below applies to v6; it does not establish an automatic test matrix for the older branches.

The v6 branch declares Go 1.26.0 or newer in go.mod. Use a security-patched toolchain; the minimum language version is not a recommendation to deploy an old patch release.

All v6 imports include /v6. This README and the package guide describe the current v6 branch, which may contain changes not yet included in a tagged release. Check the release history, tags, and changelog before upgrading.

Inside your own Go module:

go get github.com/Laisky/go-utils/v6@latest

@latest follows Go's version selection rules; it is not a promise to install the current branch head. For an unreleased API, replace COMMIT_SHA in go get github.com/Laisky/go-utils/v6@COMMIT_SHA with a reviewed commit from v6. Let Go generate any required pseudo-version. Pin the version you have tested and commit go.mod and go.sum.

Save this as main.go in your application and run go run .:

package main

import (
	"fmt"
	"time"

	gutils "github.com/Laisky/go-utils/v6"
)

// main stores and reads a typed value, then stops the cache's cleanup worker.
func main() {
	cache := gutils.NewTtlCache[string]()
	defer cache.Close()

	cache.Set("greeting", "hello, Go", time.Minute)
	value, ok := cache.Get("greeting")
	fmt.Println(value, ok)
}

Expected output: hello, Go true. Stop users of the cache before closing it; operations after Close panic. More examples, including imports and error handling, are in the package guide.

The entries below are packages within one Go module, not independently versioned modules. Paths are relative to github.com/Laisky/go-utils/v6.

crypto/threshold is the umbrella documentation package; its implementations live in the two subpackages above. agents/internal and internal are implementation details, not public integration APIs. Configuration management previously listed here has moved to go-config.

go install github.com/Laisky/go-utils/v6/cmd/gutils@latest

Go installs the executable in GOBIN, or the first GOPATH entry's bin directory when GOBIN is unset. Add that directory to your PATH, then run gutils --help.

To build the implementation described by this branch instead of a published version:

git clone --branch v6 https://github.com/Laisky/go-utils.git
cd go-utils
go install ./cmd/gutils

# Preview duplicate-file removal. Review the output before omitting --dry.
gutils remove-dup -d ./photos --dry

# Inspect a certificate file or a remote TLS endpoint.
gutils certinfo -f ./cert.pem
gutils certinfo -r example.com:443

# Move files into MD5-based directories. Run only on a backed-up working copy.
gutils md5dir -i ./working-copy

# Sign a file; verification reads the matching artifact.bin.sig sidecar.
gutils rsa sign --prikey ./private.pem --file ./artifact.bin
gutils rsa verify --pubkey ./public.pem --file ./artifact.bin

remove-dup and md5dir can delete or move files. Do not use your only copy as input, and do not treat image similarity as proof that files are interchangeable. MD5-based organization is not a cryptographic integrity check. Use each subcommand's --help to review its current flags.

Provision a password file outside the repository through your secret-management process. On Unix, it must not be accessible by group or others:

chmod 600 ./password.txt

# Writes config.toml.enc.
gutils encrypt aes -i ./config.toml --password-file ./password.txt

# Use a different output path to preserve the original configuration.
gutils decrypt aes -i ./config.toml.enc -o ./config.restored.toml --password-file ./password.txt

Password mode derives a key with Argon2id and writes a versioned encrypted format. --password-file - reads from standard input. --key-file instead accepts a hex-encoded raw AES key; it is not a password input. With neither flag, an interactive terminal prompts without echo; a noninteractive invocation fails.

-s/--secret is no longer accepted. Existing regular output files can be replaced, so select output paths deliberately. See the CLI guide, AES formats and migration, and output-path safety notes.

Security-oriented checks and regression tests do not constitute an independent audit or a guarantee that every use is safe. Deprecated and compatibility APIs remain in the repository; the API reference documents individual contracts. Use command safety guidance when launching subprocesses.

Start from v6. Include a minimal, sanitized reproducer for a bug and preserve it as a behavior/regression test. Keep examples, public API documentation, and migration guidance synchronized with changes.

The main workflow automatically checks formatting and runs seven essential unit tests with the latest patched Go 1.26 toolchain. Full lint, builds, and the Go 1.26/current-stable race and coverage matrix, including Tongsuo integration, run when the Test workflow is dispatched manually. The lint job also checks module tidiness, vulnerabilities, and go vet for Linux, Windows, and macOS targets. Cross-target vetting is not the same as running the test suite on every OS. Separate security workflows retain their automatic checks; see the CI testing policy for the gate's scope and full local qualification commands.

# Install goimports and govulncheck; install the linter used by the workflow separately.
make install
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0

# make lint formats files and runs go mod tidy: inspect the resulting diff.
make lint
go test -race -cover ./...

Tongsuo-backed crypto integration tests need the tongsuo executable. CI builds the version pinned in its workflow; tests that depend on it are skipped when it is absent locally. A run with skipped integrations is not equivalent to the full CI environment. Threshold RSA key generation can also make the suite slow; see its testing notes.

Read AGENTS.md for repository-specific development instructions. Open a GitHub issue for questions or bugs, and a pull request for changes. Never include live credentials, private keys, or sensitive production data in a public report.

Package recipes · API reference · Agent memory manual · Agent memory architecture · MCP FileIO reference · Logging guide · Changelog

MIT. Maintained by Laisky and contributors.