lib

module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 31, 2026 License: MIT

README

lib

The shared base of a few web apps with one owner (compass, exploreassistant): Go packages, a UI kit each app copies, and a back office with its Go and UI sides.

This repository is a single Go module (github.com/AltSoyuz/lib). Each top-level directory is an importable package unless documented otherwise.

Philosophy

lib's consumers are a few apps with one owner, edited by the same agents. That allows what a public framework cannot do, and asks for what it never needed.

  • The app owns the wiring. An app calls lib from its own code; inversion of control stops at a Mount(mux) and a Config, as in backoffice. Plain net/http, database/sql, log/slog; no hooks, no behavior triggered by a name.
  • Something enters lib at its second real use in an app. Until then it stays in the app.
  • A break ships with its migration. A change that breaks an app lands with the migration of every app that follows lib, in the same pass, on clean trees. No deprecation layer: the API keeps no trace of its past mistakes. Tags stay, so each app deploys at its own pace, and an app pinned to an older version keeps it until someone works on it.
  • Few releases. What still moves (the kit's layout under iOS) is tuned in one app and enters lib once validated on an iPhone: one release per settled change, not one per tweak. Each release costs a bump, make kit and the checks in every app.
  • Conventions are checks. A rule the apps must follow fails a check with what to do (make kit-check), rather than living in prose nobody reads.
  • Properties, not code, from mature frameworks. Security-sensitive code (auth, sessions, CSRF, links sent by email) lists what the closest reference guarantees (phx.gen.auth for auth), builds it from the standard library or golang.org/x/crypto, and makes each property a test.
  • Small, tested, few dependencies. Each package fits in your head; its godoc is the contract, and its first sentence says what it owns and what it calls in the app. Every package ships with *_test.go; CI runs go test -race ./... and go vet ./.... A new dependency needs a justification.

How an app uses lib

An app pins a lib tag in its go.mod (never a committed replace) and calls the Go packages from its own code. The UI kit, web/, is copied into the app by make kit from that same tag, so go.sum checks the copy, and make kit-check, part of make check, refuses a hand-edited one (see web/README.md). The back office has both sides: the backoffice package mounts its routes on the app's mux, and web/admin/ holds its screens.

A change to lib reaches the apps in five steps:

  1. Change lib with its tests and a CHANGELOG.md entry under [Unreleased]. Try it in the apps through a go.work kept outside the repositories.
  2. Release: the entries move under ## [X.Y.Z] in a release: vX.Y.Z commit, tagged vX.Y.Z and pushed with main.
  3. In each app that follows lib: go get github.com/AltSoyuz/lib@vX.Y.Z, then make kit.
  4. Migrate the app if the release breaks it, then make check.
  5. Ship each app through its own release process.

Packages

Package Purpose
audit Audit log of an app: who changed what, written in the transaction of the change, paged for a back office.
auth Authentication subpackages and SQL artefacts: passwords, sessions, magic links, schema.
backoffice The back office the apps share: roles and access, the session check, admin routes, View as, announcement, features kept to the admins, account stats.
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 Google Sign-In through the OAuth 2.0 authorization-code flow with PKCE, standard library only.
web UI kit for the SvelteKit apps, copied from the module into each app (not a Go package).

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 and ship with the migration of the apps.

Documentation

Read lib through godoc, one package or one symbol at a time:

go doc github.com/AltSoyuz/lib/mailer
go doc github.com/AltSoyuz/lib/backoffice Config

Contributing

See CONTRIBUTING.md and AGENTS.md.

License

MIT

Directories

Path Synopsis
Package audit writes who changed what into an app's audit_events table (schema.sql), in the transaction of the change, and pages through it for a back office.
 Package audit writes who changed what into an app's audit_events table (schema.sql), in the transaction of the change, and pages through it for a back office.
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.
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, session policy, and request URL/host detection.
 Package sessions provides session token generation, cookie helpers, session policy, and request URL/host detection.
Package backoffice is the back office the apps share: who may use an app (roles, access states), the session check that enforces it on every request, the admin routes over the accounts, View as, the announcement shown to everyone, the features an admin keeps to the admins, the audit log and the account stats.
 Package backoffice is the back office the apps share: who may use an app (roles, access states), the session check that enforces it on every request, the admin routes over the accounts, View as, the announcement shown to everyone, the features an admin keeps to the admins, the audit log and the account stats.
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 implements Google Sign-In via the OAuth 2.0 authorization-code flow with PKCE (RFC 7636), using only the standard library.
 Package oauthgoogle implements Google Sign-In via the OAuth 2.0 authorization-code flow with PKCE (RFC 7636), using only the standard library.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.