README
¶
lib
Small, focused, dependency-light Go libraries.
This repository is a single Go module (github.com/AltSoyuz/lib). Each
top-level directory is an importable package unless documented otherwise.
Philosophy
- Minimal external dependencies. Adding a dep requires justification.
- Stable APIs. Breaking changes bump the minor version (pre-1.0) or
require a
/v2module path (post-1.0). No silent breakage. - Tests are mandatory. Every package ships with
*_test.go. CI runsgo test -race ./...andgo vet ./...on every push and PR. - No frameworks, no magic. Plain
net/http, plaindatabase/sql,log/slog. Composition over inheritance. - Read the code. Each package is small enough to fit in your head.
Packages
| Package | Purpose |
|---|---|
auth |
Authentication subpackages and SQL artefacts: passwords, sessions, magic links, schema. |
buildinfo |
Version flag handling and build info metric registration through -ldflags. |
claude |
Minimal Anthropic Messages API client with normal and streaming completions. |
db |
database/sql helpers: null conversion, SQLite uniqueness checks, migrations, transactions, and tracing. |
envflag |
flag parsing with environment-variable fallback and optional env prefix. |
httpserver |
HTTP helpers for serving, graceful shutdown, JSON, IP detection, rate limiting, and embedded UI assets. |
logger |
Small structured logger with flag-based level/output/timezone settings and stdlib bridge. |
mailer |
Email delivery through blackhole, SMTP, AWS SES v2, or Resend, plus verification URL helper. |
oauthgoogle |
Placeholder Google OAuth provider API that currently reports not available. |
telegram |
Telegram Bot API client for allowed-user checks, sending messages, polling updates, and command parsing. |
Install
go get github.com/AltSoyuz/lib@latest
import (
"github.com/AltSoyuz/lib/httpserver"
"github.com/AltSoyuz/lib/logger"
)
Versioning
Standard Go module semver. Tags are vMAJOR.MINOR.PATCH. While the module is
v0.x.y the API may change between minor versions; breaking changes are
called out in CHANGELOG.md.
Documentation
Use godoc for package-level details:
go doc github.com/AltSoyuz/lib/mailer
go doc github.com/AltSoyuz/lib/auth/passwords
Contributing
See CONTRIBUTING.md and AGENTS.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth documents the authentication-related subpackages and SQL artefacts in this module.
|
Package auth documents the authentication-related subpackages and SQL artefacts in this module. |
|
magiclinks
Package magiclinks holds shared semantics for one-shot email tokens used by the verify-email and password-reset flows: TTL defaults and stable purpose strings used as DB enums.
|
Package magiclinks holds shared semantics for one-shot email tokens used by the verify-email and password-reset flows: TTL defaults and stable purpose strings used as DB enums. |
|
passwords
Package passwords provides bcrypt password hashing, email normalization, and breach-check via the HaveIBeenPwned k-anonymity API.
|
Package passwords provides bcrypt password hashing, email normalization, and breach-check via the HaveIBeenPwned k-anonymity API. |
|
schema
Package schema documents the authentication SQL artefacts shipped with this module.
|
Package schema documents the authentication SQL artefacts shipped with this module. |
|
sessions
Package sessions provides session token generation, cookie helpers, and request URL/host detection.
|
Package sessions provides session token generation, cookie helpers, and request URL/host detection. |
|
Package buildinfo exposes application version metadata initialized through linker flags and registered as a VictoriaMetrics info metric.
|
Package buildinfo exposes application version metadata initialized through linker flags and registered as a VictoriaMetrics info metric. |
|
Package claude provides a minimal client for the Anthropic Messages API, including non-streaming and streaming text completions.
|
Package claude provides a minimal client for the Anthropic Messages API, including non-streaming and streaming text completions. |
|
Package db provides small database/sql helpers for nullable values, SQLite constraint checks, migrations, transactions, and query tracing.
|
Package db provides small database/sql helpers for nullable values, SQLite constraint checks, migrations, transactions, and query tracing. |
|
Package envflag extends flag parsing with environment-variable fallback.
|
Package envflag extends flag parsing with environment-variable fallback. |
|
Package httpserver provides HTTP server helpers for graceful shutdown, JSON responses, strict JSON decoding, pagination, trusted-proxy client IP detection, rate limiting, built-in metrics routes, and embedded UI assets.
|
Package httpserver provides HTTP server helpers for graceful shutdown, JSON responses, strict JSON decoding, pagination, trusted-proxy client IP detection, rate limiting, built-in metrics routes, and embedded UI assets. |
|
Package logger provides a small structured logger with flag-based level, output, and timezone settings.
|
Package logger provides a small structured logger with flag-based level, output, and timezone settings. |
|
Package mailer sends email through blackhole, SMTP, AWS SES v2, or Resend backends and includes helpers for verification links.
|
Package mailer sends email through blackhole, SMTP, AWS SES v2, or Resend backends and includes helpers for verification links. |
|
Package oauthgoogle defines a minimal Google OAuth provider API.
|
Package oauthgoogle defines a minimal Google OAuth provider API. |
|
Package telegram provides a small Telegram Bot API client for sending messages, polling updates, restricting allowed users, and parsing commands.
|
Package telegram provides a small Telegram Bot API client for sending messages, polling updates, restricting allowed users, and parsing commands. |
Click to show internal directories.
Click to hide internal directories.