Catalyst
started out as a microservice base that can be used to create REST APIs. It contains many features that are essential, such as.
- Configurability
- A basic dependency injection mechanism
- HTTP request, response cycle handling
- Structure and field validations
- Error handling
- Logging
- Database resource management
- Application metrics
Written in Go using the Clean Architecture paradigm it offers clean separation between business (domain) logic and facilitation logic.
A new project can be created in one of two ways.
The easiest way to create a project using Catalyst
as the base is to use Cauldron
.
Cauldron
is a project generation tool that creates new projects using Catalyst
as the base.
More information about Cauldron
can be found here
Begin by installing Cauldron
.
go get github.com/kosatnkn/cauldron
Command
cauldron -n Sample -s github.com/username [-t v1.0.0]
cauldron --name Sample --namespace github.com/username [--tag v1.0.0]
Input Parameters
-n --name
Project name (ex: Sample). The name will be converted to lowercase to be used in module path.-s --namespace
Namespace for the project (ex: github.com/username)-t --tag
Release version ofCatalyst
to be used. The latest version will be used if-t
is not provided-h --help
Show help message
This will create a new project with go.mod module path of github.com/username/sample
Cauldron
will do a git init
on the newly created project but you will have to stage all the files and do the first commit yourself.
git add .
git commit -m "first commit"
This is the work intensive approach.
Clone Catalyst
git clone https://github.com/kosatnkn/catalyst.git <new_project_name>
Remove .git
cd <new_project_name>
rm -rf .git
Change import paths
NOTE: Since
Catalyst
uses go mod the the newly created application will still work. But all the import paths would be as inCatalyst
base project which is not what you will want.
- First change the module name in the
go.mod
file to a module name of your choice - Then do a
Find & Replace
in the entire project to update all the import paths - You may also need to change the splash text in
app/splash/styles.go
- Now run and see whether the project compiles and run properly
- If so you can do a
git init
to the project
Configuration files for a Catalyst
project can be found in configs
directory.
Initially you will have a set of config files with the extension of .yaml.example
. You can create .yaml
configuration files using these example files as a template.
We have included a sample set of endpoints and their corresponding controller and domain logic by default.
This is to make it easier for you to follow through and understand how Catalyst handles the request response cycle for a given request.
The sample set will cover all basic CRUD operations that a REST API will normally need.
There is also an openapi.yaml
file in doc/api
directory that corresponds to the set of Sample APIs that are implemented.
In the context of Catalyst
we use a concept called Transport mediums
to define ways in which you can communicate
with the microservice.
A package inside the transport
directory consists of all the logic needed to handle communication with the
outside world using one type of transport medium.
Out of the box, Catalyst contain two such transport mediums.
http
(to handle REST web requests)metrics
(to expose application metrics)
What makes Catalyst
a REST API is this http
package which handles the complete lifecycle of REST web requests.
REST API is implemented in this package.
Following is the request, response cycle executed when a request comes to a REST endpoint.
+ ------- + + -------- +
| REQUEST | | RESPONSE |
+ ------- + + -------- +
|| /\
\/ ||
+ ------------ + ||
| Middleware | ||
+ ------------ + ||
|| ||
\/ ||
+ ------------ + ||
| Router | ||
+ ------------ + ||
|| ||
|| ||
|| + --------------------------- +
|| | Transformer | Error Handler |
|| + --------------------------- +
|| /\
\/ ||
+ -------------------- + => + -------------- +
| Unpacker | Validator | | Controller |
+ -------------------- + <= + -------------- +
|| /\
\/ ||
+ -------------- +
| Use Case |
+ -------------- +
|| /\
\/ ||
_____________________________________
+ ---------- + + ------- +
| Repository | | Service |
+ ---------- + + ------- +
|| /\ || /\
\/ || \/ ||
+ ---------- + + ------- +
| Database | | APIs |
+ ---------- + + ------- +
Likewise the metrics
transport medium exposes an endpoint to let Prometheus
scrape application metrics.
You can add other transport mediums
to leverage a project based on Catalyst
.
For an example a stream
package can be added to transport
to communicate with a streaming platform like Kafka
,
or an mqtt
package can be added to communicate with IoT
devices.
godoc -http=:6060 -v
Navigate to http://localhost:6060/pkg/github.com/kosatnkn/catalyst/v2
Go mod is used as the dependency management mechanism. Visit here for more details.
Some commonly used go mod commands for quick reference.
Use go mod in projects that are within the GOPATH
export GO111MODULE=on
Initialize go mod
go mod init github.com/my/repo
View final versions that will be used in a build for all direct and indirect dependencies
go list -m all
View available minor and patch upgrades for all direct and indirect dependencies
go list -u -m all
Update all direct and indirect dependencies to latest minor or patch upgrades (pre-releases are ignored)
go get -u or go get -u=patch
Build or test all packages in the module when run from the module root directory
go build ./... or go test ./...
Prune any no-longer-needed dependencies from go.mod and add any dependencies needed for other combinations of OS, architecture, and build tags
go mod tidy
Optional step to create a vendor directory
go mod vendor
To run test and output coverage report
go test -covermode=count -coverprofile=cover.out ./...
To get coverage as a percentage of overall codebase use -coverpkg=./...
go test -covermode=count -coverpkg=./... -coverprofile=cover.out ./...
Catalyst provides a basic multistage Dockerfile so you have a starting point for creating Docker images.
docker build -t <tag_name>:<tag_version> .
NOTE: Do not forget the tailing
.
that indicates the current directory
Example
docker build -t kosatnkn/catalyst:1.0.0 .
You can use it as follows
docker run -it --rm --name catalyst -p 3000:3000 -p 3001:3001 kosatnkn/catalyst:1.0.0
Do both in one go
docker build -t kosatnkn/catalyst:1.0.0 . && docker run -it --rm --name catalyst -p 3000:3000 -p 3001:3001 kosatnkn/catalyst:1.0.0
Wiki pages on technical aspects of the project can be found here
NOTE: Wiki is currently being updated.