README
¶
Go lib
Shared Go library of the A-Novel backend services, holding the glue each would otherwise copy.
What this is
golib collects the boilerplate the A-Novel backend services share, from server wiring to test harnesses, so each service imports it instead of keeping its own copy. It holds no business logic. Each sub-package covers one concern and imports on its own.
Services depend on a released version. The godoc on pkg.go.dev is the full reference.
Installation
go get github.com/a-novel-kit/golib
Sub-packages
| Path | What it's for |
|---|---|
config |
Parses environment variables into typed values. An unset one keeps its default and a malformed one panics at startup, so a service never boots half-configured. |
downtime |
Makes a service refuse every request but liveness from the start of a planned downtime until operators remove it. A marker in each refusal tells it apart from an outage. |
grpcf |
The gRPC counterpart of httpf: the server with its standard interceptors and bounded shutdown, and the dial credentials of a local target or a service in the same Kubernetes cluster. |
httpf |
The HTTP glue on both sides of the wire: the REST server with its standard middleware and rate limits, the responses a handler writes, and the pooled, traced client a service calls others with. |
httpf/httpftest |
Scripts an HTTP server to test outbound calls against. |
logging |
Defines the interfaces a service logs through, so it can swap its log backend without touching call sites. Its presets cover a terminal, for both HTTP and gRPC, and any OpenTelemetry backend. |
otel |
Wires OpenTelemetry tracing and logging under the service's name, and reports each operation's outcome on its span. Its presets export locally or to a hosted backend. |
picture |
Checks a picture a user uploads, such as a profile picture or a logo: a still WebP or a JPEG of the contract's exact aspect ratio and width, which decodes whole. |
postgres |
Carries the database handle on the request context, runs work inside transactions installed on it, and applies migrations. Its presets open the pool from a URL or discrete settings. |
postgres/postgrestest |
Isolates the database work of each test, in a migrated clone, a throwaway schema or a rolled-back transaction, and proves every down migration reverses its up. |
servertls |
Serves TLS from a key pair renewed on disk, such as a certificate cert-manager keeps in a mounted Secret. httpf and grpcf serve TLS through it once their configuration names the files. |
smtp |
Sends transactional mail behind one Sender interface, with a real SMTP sender for production and a debug sender for local runs. |
smtp/smtptest |
Records sent mail in memory, for tests to assert on. |
transaction |
Declares a unit of work in one interface that names no database, so business code can require atomicity without reaching a driver. postgres implements it. |
transaction/transactiontest |
Runs a unit of work in memory, for tests to assert that a caller opened one. |
worker |
Runs the background loops that live beside the request path, each run traced on its own and a failing or panicking run recorded on its span and logged. |
Contributing
Set up your machine with the developer guide. The rules specific to golib are in CONTRIBUTING.md.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
service-token-issuer
command
Command service-token-issuer stands in for a Kubernetes cluster's service-account issuer in a local stack, such as a compose file.
|
Command service-token-issuer stands in for a Kubernetes cluster's service-account issuer in a local stack, such as a compose file. |
|
Package config reads service configuration from environment variables, mapping raw strings to native Go types through composable parser functions.
|
Package config reads service configuration from environment variables, mapping raw strings to native Go types through composable parser functions. |
|
Package downtime lets a service honor a planned downtime: from its start, the service refuses every request except liveness and leaves its database alone.
|
Package downtime lets a service honor a planned downtime: from its start, the service refuses every request except liveness and leaves its database alone. |
|
Package grpcf holds the gRPC glue a service needs on both sides of the wire, as httpf does for HTTP.
|
Package grpcf holds the gRPC glue a service needs on both sides of the wire, as httpf does for HTTP. |
|
Package httpf holds the HTTP glue a service needs on both sides of the wire.
|
Package httpf holds the HTTP glue a service needs on both sides of the wire. |
|
httpftest
Package httpftest scripts an HTTP server for testing outbound calls.
|
Package httpftest scripts an HTTP server for testing outbound calls. |
|
internal
|
|
|
tlstest
Package tlstest signs the certificates golib's TLS tests serve, as cert-manager's CA issuer does in a cluster.
|
Package tlstest signs the certificates golib's TLS tests serve, as cert-manager's CA issuer does in a cluster. |
|
Package logging defines the logging contracts a service wires into its HTTP and gRPC servers.
|
Package logging defines the logging contracts a service wires into its HTTP and gRPC servers. |
|
presets
Package loggingpresets implements the logging contracts for the two environments a service runs in.
|
Package loggingpresets implements the logging contracts for the two environments a service runs in. |
|
Package otel installs an OpenTelemetry backend as the process-global state, and reports the outcome of each operation on its span.
|
Package otel installs an OpenTelemetry backend as the process-global state, and reports the outcome of each operation on its span. |
|
presets
Package otelpresets provides ready-made github.com/a-novel-kit/golib/otel.Config backends, one per destination a service exports its traces and logs to.
|
Package otelpresets provides ready-made github.com/a-novel-kit/golib/otel.Config backends, one per destination a service exports its traces and logs to. |
|
Package picture checks the pictures users upload for a service to store and show, such as a profile picture or a project logo.
|
Package picture checks the pictures users upload for a service to store and show, such as a profile picture or a project logo. |
|
Package postgres carries a PostgreSQL connection on the request context, runs work inside transactions installed on that context, and applies migrations.
|
Package postgres carries a PostgreSQL connection on the request context, runs work inside transactions installed on that context, and applies migrations. |
|
postgrestest
Package postgrestest provides PostgreSQL test harnesses backed by postgres.
|
Package postgrestest provides PostgreSQL test harnesses backed by postgres. |
|
presets
Package postgrespresets builds the PostgreSQL connection pools behind github.com/a-novel-kit/golib/postgres.Config, from a URL or from discrete connection settings.
|
Package postgrespresets builds the PostgreSQL connection pools behind github.com/a-novel-kit/golib/postgres.Config, from a URL or from discrete connection settings. |
|
Package servertls serves TLS from a key pair renewed on disk, such as a certificate cert-manager keeps current in a Kubernetes Secret the kubelet mounts.
|
Package servertls serves TLS from a key pair renewed on disk, such as a certificate cert-manager keeps current in a Kubernetes Secret the kubelet mounts. |
|
Package servicetoken authenticates calls between services with service tokens.
|
Package servicetoken authenticates calls between services with service tokens. |
|
servicetokentest
Package servicetokentest runs a Kubernetes service-account issuer for tests and local stacks.
|
Package servicetokentest runs a Kubernetes service-account issuer for tests and local stacks. |
|
Package smtp sends templated transactional email through a Sender.
|
Package smtp sends templated transactional email through a Sender. |
|
smtptest
Package smtptest provides an in-memory smtp.Sender for tests.
|
Package smtptest provides an in-memory smtp.Sender for tests. |
|
Package transaction declares the scope a unit of work runs in, independently of what stores it.
|
Package transaction declares the scope a unit of work runs in, independently of what stores it. |
|
transactiontest
Package transactiontest provides an in-memory github.com/a-novel-kit/golib/transaction.Transactor for unit tests.
|
Package transactiontest provides an in-memory github.com/a-novel-kit/golib/transaction.Transactor for unit tests. |
|
Package worker holds the loops a service runs in the background, beside the request path.
|
Package worker holds the loops a service runs in the background, beside the request path. |
Click to show internal directories.
Click to hide internal directories.