README
¶
compose
Warning: This package is still in development and things keep changing so things may break slightly
A collection of opinionated modules created for building golang applications quicker while keeping best practices.
Why
Most applications have many components in common:
- Loading config & env variables
- Logging
- Keeping a state
- Long term storage
- APIs
- Authentication
- Role management
In the spirit of keeping it DRY, this package standardizes everything so we can use the same components on every application.
Instalation
go get -u github.com/vanclief/compose
CLI
The compose binary previews API reference pages:
go install github.com/vanclief/compose/cmd/compose@latest
compose reference -head openapi.yaml -base previous.yaml -serve 127.0.0.1:8090
This serves the reference page of openapi.yaml with what changed since previous.yaml, re-rendered on every reload. Use -out page.html instead of -serve to write a standalone file.
Usage
- config - Loading env/ settings
- concurrent writes - why two requests can undo each other's changes to one row, and the helpers that prevent it:
relational.Patchwrites only the columns a request sent,relational.Mutateandrelational.LockRowlock the row and read it again before the write - migrations - how the migration runner and its own connection pool behave, and the schema baseline that replaces old migration files
- scheduler - running recurring jobs on one instance per minute boundary when an app runs several instances
- testing - running an app's tests with no AWS credentials: the in-memory S3 client, the recording SES client and the test database helpers
Dependencies
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
compose
command
Command compose is the command line tool of the compose module.
|
Command compose is the command line tool of the compose module. |
|
components
|
|
|
auth/oidc
Package oidc verifies OpenID Connect ID tokens from Google, Apple and Microsoft.
|
Package oidc verifies OpenID Connect ID tokens from Google, Apple and Microsoft. |
|
auth/session
Package session issues and resolves rotating session tokens for first-party apps.
|
Package session issues and resolves rotating session tokens for first-party apps. |
|
auth/token
Package token generates and checks opaque bearer tokens.
|
Package token generates and checks opaque bearer tokens. |
|
mcp
Package mcp exposes a REST API described by an OpenAPI 3.x document as a Model Context Protocol server with a fixed set of tools:
|
Package mcp exposes a REST API described by an OpenAPI 3.x document as a Model Context Protocol server with a fixed set of tools: |
|
mcp/oauth
Package oauth lets hosted MCP clients such as claude.ai and ChatGPT connect to a compose MCP server.
|
Package oauth lets hosted MCP clients such as claude.ai and ChatGPT connect to a compose MCP server. |
|
rest/api
Package api is compose's declarative REST route registry.
|
Package api is compose's declarative REST route registry. |
|
rest/api/internal/fixture
Package fixture mirrors auditor3's runs module for api registry tests.
|
Package fixture mirrors auditor3's runs module for api registry tests. |
|
rest/api/openapi
Package openapi turns Go request and response types into OpenAPI 3.1 (JSON Schema draft 2020-12) component schemas and parameters.
|
Package openapi turns Go request and response types into OpenAPI 3.1 (JSON Schema draft 2020-12) component schemas and parameters. |
|
rest/api/openapi/internal/fixture
Package fixture mirrors auditor3's runs module for openapi reflector tests.
|
Package fixture mirrors auditor3's runs module for openapi reflector tests. |
|
rest/api/openapi/internal/fixture/a/units
Package units collides by last path segment with fixture/b/units.
|
Package units collides by last path segment with fixture/b/units. |
|
rest/api/openapi/internal/fixture/b/units
Package units collides by last path segment with fixture/a/units.
|
Package units collides by last path segment with fixture/a/units. |
|
rest/api/openapi/internal/fixture/other
Package other holds a type whose name collides with fixture.Run, to prove package-qualified component names keep them apart.
|
Package other holds a type whose name collides with fixture.Run, to prove package-qualified component names keep them apart. |
|
rest/api/validate
Package validate compiles OpenAPI 3.1 schemas with santhosh-tekuri/jsonschema and validates decoded requests against them.
|
Package validate compiles OpenAPI 3.1 schemas with santhosh-tekuri/jsonschema and validates decoded requests against them. |
|
rest/apitest
Package apitest checks recorded responses against the contract of an api.Registry: the strict OpenAPI 3.1 document, where every response object component has additionalProperties:false so undocumented fields fail.
|
Package apitest checks recorded responses against the contract of an api.Registry: the strict OpenAPI 3.1 document, where every response object component has additionalProperties:false so undocumented fields fail. |
|
rest/generator
Package generator derives an OpenAPI 3.0 document from the source of an Echo application built on compose's rest handlers.
|
Package generator derives an OpenAPI 3.0 document from the source of an Echo application built on compose's rest handlers. |
|
rest/reference
Package reference renders an OpenAPI 3.x document as a self-hosted API reference page: an alternative to Scalar and Redoc that ships inside the backend, with no CDN assets.
|
Package reference renders an OpenAPI 3.x document as a self-hosted API reference page: an alternative to Scalar and Redoc that ships inside the backend, with no CDN assets. |
|
scheduler
Package scheduler runs recurring jobs on wall-clock minute boundaries and one-shot jobs on demand, keyed by id, in one process.
|
Package scheduler runs recurring jobs on wall-clock minute boundaries and one-shot jobs on demand, keyed by id, in one process. |
|
scheduler/claims
Package claims keeps the claims of a scheduler.Scheduler in a PostgreSQL table, so that an app running several instances runs each minute boundary of a recurring job on one of them.
|
Package claims keeps the claims of a scheduler.Scheduler in a PostgreSQL table, so that an app running several instances runs each minute boundary of a recurring job on one of them. |
|
drivers
|
|
|
databases/relational/internal/jsonfmt
Package jsonfmt holds the JSON formatter the compose dialects use in place of bun v1.3.0's, which mis-escapes the text \u0000 (https://github.com/uptrace/bun/issues/1472).
|
Package jsonfmt holds the JSON formatter the compose dialects use in place of bun v1.3.0's, which mis-escapes the text \u0000 (https://github.com/uptrace/bun/issues/1472). |
|
databases/relational/postgres/pgtest
Package pgtest is test support for apps that test against a real PostgreSQL: it creates a uniquely named database per test run, empties it between tests, drops it at the end, and sweeps the databases left behind by runs that died.
|
Package pgtest is test support for apps that test against a real PostgreSQL: it creates a uniquely named database per test run, empties it between tests, drops it at the end, and sweeps the databases left behind by runs that died. |
|
integrations
|
|
|
primitives
|
|
|
enums
Package enums validates string-backed enums and adapts them to JSON and database/sql.
|
Package enums validates string-backed enums and adapts them to JSON and database/sql. |
|
utils
|
|
Click to show internal directories.
Click to hide internal directories.