63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# Application singleton
|
|||
|
|
|
||
|
|
This is a structure that controls the whole application's lifecycle:
|
||
|
|
|
||
|
|
- Startup (in `Start() error` function).
|
||
|
|
- Shutdown (in `Shutdown() []error` function).
|
||
|
|
- Domains registry (`[]Domain`).
|
||
|
|
- Base logger (see [Logging](logging.md)).
|
||
|
|
|
||
|
|
This structure is passed to all parts of application - domains, storages, clients to external services and so on, for re-using domains, global context, logger and other parts.
|
||
|
|
|
||
|
|
## Structure initialization
|
||
|
|
|
||
|
|
Structure initialization for that singleton should be done with `New()` without returning any error, as it will initialize internal state and nothing else. It consists of:
|
||
|
|
|
||
|
|
- Global `context.Context` creation to use (with `Context() context.Context` function for retrieving that context).
|
||
|
|
- Internal storage creation for domains registry.
|
||
|
|
- Base logger creation (see [Logging](logging.md)).
|
||
|
|
|
||
|
|
## App startup and shutdown
|
||
|
|
|
||
|
|
Application's startup and shutdown are done in `Start() error` and `Shutdown() []error` functions respectively.
|
||
|
|
|
||
|
|
Startup function sequentially runs these functions for every registered domain, each function in a separate iteration:
|
||
|
|
|
||
|
|
- `ConnectDependencies() error`.
|
||
|
|
- `Configure() error`.
|
||
|
|
- `LaunchStartupTasks() error`.
|
||
|
|
|
||
|
|
It should return a wrapped error if anything goes wrong here.
|
||
|
|
|
||
|
|
As startup function calls domain functions in iterations, you should put domains initialization in `main()` function in proper order - if some domain requires configuration of another domain, it should be placed after that domain.
|
||
|
|
|
||
|
|
Shutdown function is different as it should run `Shutdown() error` on every registered domain, add every returned error to `[]error` and return that slice. Domains order is reversed compared to `Start()` function.
|
||
|
|
|
||
|
|
Singleton provides `ShutdownChan()` function that returns a channel to which a signal will be sent when SIGTERM is received.
|
||
|
|
|
||
|
|
## Domains registry
|
||
|
|
|
||
|
|
Simple `[]Domain` field in Application structure. Two functions should be present:
|
||
|
|
|
||
|
|
- `RegisterDomain(domain Domain) error` which registers domain by adding it in `[]Domain` or returns error if domain with such name is already registered.
|
||
|
|
- `Domain(name string) Domain` which returns domain by name or nil if domain isn't registered.
|
||
|
|
|
||
|
|
Also domains registry field should be secured with `sync.RWMutex` so every part of application can safely retrieve any required dependency on any stage.
|
||
|
|
|
||
|
|
### Registering a domain
|
||
|
|
|
||
|
|
Domain's registration should happen with `RegisterDomain(domain Domain) error` function:
|
||
|
|
|
||
|
|
- Checks if domain with same name (obtained via `Name() string` interface's function) is already registered. If so - returns an error.
|
||
|
|
- Registers domain with registry by adding it to `[]Domain`.
|
||
|
|
- Runs `Initialize() error` function from domain and returns wrapped error if initialization function returned it.
|
||
|
|
|
||
|
|
### Retrieving a domain
|
||
|
|
|
||
|
|
Domain retrieval should be done via `Domain(name string) Domain` function in a proper domain's `ConnectDependencies() error` function.
|
||
|
|
|
||
|
|
If requested domain is not registered, that function should return nil and domain that requested unknown domain should return an `ErrDomainUnknown` error from `application` package.
|
||
|
|
|
||
|
|
## Logging
|
||
|
|
|
||
|
|
Comprehensive logging documentation can be found in [Logging](logging.md).
|