README
¶
go-server
This is an opinionated HTTP server which is designed to be used as a base for building API and web applications. It is designed to be extensible and modular, allowing you to add new features and functionality as needed. By default the server includes the following features:
- Anthentication of users using Cognito, Google and LDAP
- Authorization of users using JWT tokens and API keys
- Task queues for running background jobs
- Connection to PostgreSQL databases
- Ability to manage the PostgreSQL database roles, databases, schemas and connections
- Prometheus metrics support
The idea is that you can use this server as a base for your own applications, and add your own features and functionality as needed. More documentation soon on how to do that.
Running
The binary includes both the server-side application and the client-side command-line tools. Both can be run as docker containers.
To run the latest released version as a docker container:
docker run ghcr.io/mutablelogic/go-server:latest
This will print out the help message and provide insight into running both the server application
and interacting with the server through commands. To run the server, you'll need a PostgreSQL
database, and you can set the environment variables PG_HOST, PG_DATABASE, PG_USER and PG_PASS.
Bootstrapping the database server and roles
More information about setting up the databses TODO
Creating a new database
Information about setting up a new database
Building
Download and build
git clone github.com/mutablelogic/go-server
cd go-server
make
The plugins and the server binary will be built in the build directory.
Build requirements
You need the following three tools installed to build the server:
Makefile targets
Binaries are placed in the build directory.
| Target | Description |
|---|---|
make all |
Build all plugins and the server |
make cmd/server |
Build the server binary |
make plugins |
Build the server binary |
make docker |
Build the docker container |
make docker-push |
Push the docker container to remote repository, assuming logged in |
make docker-version |
Prints out the docker container tag |
make test |
Runs unit amd coverage tests |
make unit-test |
Runs unit tests |
VERBOSE=1 make unit-test |
Runs unit tests with verbose output |
make coverage-test |
Reports code coverage |
make tidy |
Runs go mod tidy |
make clean |
Removes binaries and distribution files |
You can also affect the build by setting the following environment variables. For example,
OS=linux ARCH=amd64 make
| Variable | Description |
|---|---|
OS |
The target operating system for the build |
ARCH |
The target architecture for the build |
BUILD_DIR |
The target architecture for the build |
VERBOSE |
Setting this flag will provide verbose output for unit tests |
VERSION |
Explicitly set the version |
DOCKER_REPO |
The docker repository to push to. Defaults to ghcr.io/mutablelogic/go-server |
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HTTPFileServer ¶
type HTTPFileServer interface {
// HandlerPath returns the route path relative to the router prefix.
HandlerPath() string
// HandlerFS returns the filesystem to serve.
HandlerFS() fs.FS
// Spec returns the OpenAPI path-item description for this
// handler, or nil if no spec is provided.
Spec() *openapi.PathItem
}
HTTPFileServer defines methods for static file serving handlers. When the router detects a handler that implements this interface, it uses [Router.RegisterFS] instead of [Router.RegisterFunc] so that the router prefix is correctly stripped from the request path.
type HTTPHandler ¶
type HTTPHandler interface {
// HandlerPath returns the route path relative to the router prefix
// (e.g. "resource", "resource/{id}").
HandlerPath() string
// HandlerFunc returns the HTTP handler function.
HandlerFunc() http.HandlerFunc
// Spec returns the OpenAPI path-item description for this
// handler, or nil if no spec is provided.
Spec() *openapi.PathItem
}
HTTPHandler defines methods for HTTP handlers
type HTTPMiddleware ¶
type HTTPMiddleware interface {
WrapFunc(http.HandlerFunc) http.HandlerFunc
}
HTTPMiddleware defines methods for HTTP middleware
type HTTPRouter ¶
type HTTPRouter interface {
http.Handler
// Spec returns the OpenAPI specification for this router.
Spec() *openapi.Spec
}
HTTPRouter defines methods for a http router
type HTTPServer ¶
type HTTPServer interface {
// Spec returns the OpenAPI server entry for this instance,
// or nil if not yet available.
Spec() *openapi.Server
}
HTTPServer defines methods for an HTTP server instance. The router uses this interface to populate the OpenAPI spec's servers list.
type Logger ¶
type Logger interface {
// Debug logs a debugging message.
Debug(context.Context, ...any)
// Debugf logs a formatted debugging message.
Debugf(context.Context, string, ...any)
// Print logs an informational message.
Print(context.Context, ...any)
// Printf logs a formatted informational message.
Printf(context.Context, string, ...any)
// With returns a new Logger that includes the given key-value pairs
// in its structured log output.
With(...any) Logger
}
Logger defines methods for logging messages and structured data. It can also act as HTTP middleware for request logging.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kaiak
command
|
|
|
pkg
|
|
|
httprouter
Package httprouter provides an HTTP request router with built-in cross-origin request forgery (CSRF) protection, middleware support, and OpenAPI spec generation.
|
Package httprouter provides an HTTP request router with built-in cross-origin request forgery (CSRF) protection, middleware support, and OpenAPI spec generation. |
|
openapi/schema
Package schema provides Go types for the OpenAPI 3.1 specification.
|
Package schema provides Go types for the OpenAPI 3.1 specification. |
|
provider/schema/schematest
Package schematest provides shared mock implementations of schema.Resource and schema.ResourceInstance for use in tests.
|
Package schematest provides shared mock implementations of schema.Resource and schema.ResourceInstance for use in tests. |