@kronos-integration/service

Base service implementation

Service states

``mermaid
stateDiagram-v2
stopped --> starting [1]
starting --> failed: [2]
starting --> running: [3]
running --> stopping: [4]
running --> failed: [5]
stopping --> failed: [6]
stopping --> stopped: [7]
`

The transitions are:
| Number | From | To | Condition |
| ------ | ---- | -- | --------- |
| 1 | ~stopped~ | ~starting~ | |
| 2 | ~starting~ | ~failed~ | |
| 3 | ~starting~ | ~running~ | |
| 4 | ~running~ | ~stopping~ | |
| 5 | ~running~ | ~failed~ | |
| 6 | ~stopping~ | ~failed~ | |
| 7 | ~stopping~ | ~stopped~ | |

API

$3

* EndpointsMixin
* Parameters
* endpoints
* ServiceConfig
* Properties
* configFor
* Parameters
* clearPreserved
* Parameters
* configureValue
* Parameters
* configure
* Parameters
* autostart
* name
* merge
* Parameters
* defineServiceConsumerProperties
* Parameters
* ServiceLogger
* logEntry
* Parameters
* autostart
* name
* endpoints
* Service
* Parameters
* Properties
* extendetName
* stateChanged
* Parameters
* rejectWrongState
* Parameters
* timeoutForTransition
* Parameters
* \_start
* \_stop
* \_restart
* restartIfRunning
* toStringAttributes
* isServiceProvider
* toString
* toJSONWithOptions
* Parameters
* name
* autostart
* \_configure
* Parameters
* configure
* Parameters
* getCredential
* Parameters
* getCredentials
* Parameters
* storePersistentCredentials
* log
* Parameters
* attributes
* endpoints
* StandaloneServiceProvider
* name

EndpointsMixin

Endpoint accessor mixin.
Manages endpoints in a container.

$3

* superclass

endpoints

Default set of endpoints to create.

Returns Object {} empty set

ServiceConfig

Extends Service

Config providing service.
Dispatches config requests to services.
Also preserves them until a maching service becomes avaliable.

$3

* preservedConfigs Map<string, Object> values for services not already established

$3

Deliver configuration for a given service.

#### Parameters

* name string service name
* config Object

Returns Promise<Object>

$3

Forget about preserved config of a service.

#### Parameters

* name string service name

$3

Set config entry.

#### Parameters

* key string path to the value
* value any

$3

#### Parameters

* config (Array | Object)

$3

We always start immediate.

Returns boolean true

$3

Returns string 'config'

merge

Merge from b into a.
When a and b are arrays of values only the none duplicates are appendend to a.

$3

* a any
* b any

Returns any merged b into a

defineServiceConsumerProperties

Assign services based on a configuration.

$3

* target Object object
* config Object service defintion
* provider Object service provider
* waitUntilFactoryPresent boolean

ServiceLogger

Extends Service

Log receiving service.

$3

#### Parameters

* entry Object

* entry.severity string

$3

We always start immediate.

Returns boolean true

$3

Returns string 'logger'

$3

Adds a log input endpoint to the set of Service endpoints.

Returns Object predefined endpoints

Service

**Extends EndpointsMixin(StateTransitionMixin(LogLevelMixin(class {}), prepareActions({
start: {
stopped: rsfDefault
},
restart: {
stopped: rsfDefault,
running: {
target: "running",
during: "restarting",
timeout
}
},
stop: {
running: ssfDefault,
starting: ssfDefault,
failed: ssfDefault
}
}), "stopped"))**

Service
The initial state is 'stopped'.
All services have at least three endpoints:

log out*: log events
config in*: configuration request
command in*: administrative actions to be executed by the step

$3

* config Object
* ic InitializationContext

$3

* endpoints Object

$3

Used in human readable state messages.
Besides the actual service name it may contain additional short hints.

Returns string

$3

Called when the service state changes.
Emits a serviceStateChanged event to the owner.

#### Parameters

* origin any
* oldState string
* newState string

$3

Called when state transition is not allowed.

#### Parameters

* action string originating action name

* Throws any always

$3

Deliver transition timeout.

#### Parameters

* transition Object

Returns number milliseconds before throwing for a long running transition

$3

Opens all endpoint connections.

$3

Closes all endpoint connections.

$3

Restart action.
default implementation does a \_stop() and a \_start()

Returns Promise\ fulfills after start

$3

Restarts if in running mode.
Otherwise does nothing.

Returns Promise\ resolves when restart is done (or immediate if no restart triggered)

$3

Mapping of properties used in toString.

Returns Object

$3

Base service is not a provider.

Returns boolean false

$3

Returns the string representation of this service.

Returns string human readable name

$3

Deliver json representation.

#### Parameters

* options Object

* options.includeRuntimeInfo boolean include runtime informtion like state
* options.includeDefaults boolean include default endpoints
* options.includeName boolean include name of the service
* options.includeConfig boolean include config attributes
* options.includePrivate boolean include private config attributes

Returns Object json representation

$3

Defaults to the type.

Returns string type

$3

Should we start when beeing registered.

Returns boolean false

$3

Takes attribute values from config parameters
and copies them over to the object.
Copying is done according to attributes.
Which means we loop over all configuration attributes.
and then for each attribute decide if we use the default, call a setter function
or simply assign the attribute value.

#### Parameters

* config Object

Returns Set<string> of modified attributes

$3

Use new configuration.
Internally calls \_configure(config) as the constructor does.
If attribute with needsRestart are touched the restartIfRunning method
will be called.

#### Parameters

* config Object

Returns Promise<undefined> fillfills when config is applied

$3

#### Parameters

* key string

Returns Promise<(string | Uint8Array)>

$3

Retrieve all (filtered) credential attribute values.

#### Parameters

* filter Function (optional, default (name,attribute)=>attribute.credential)

Returns Promise<Object>

$3

Load and store persistent credentials in the service attributes.

Returns Promise<undefined>

$3

Adds service name to the log event.

#### Parameters

* level string the log level
* arg Object log content

$3

Meta information for the config attributes.

* default optional default value of the attribute
* needsRestart optional modification requires a service restart
* setter(newValue,attribute) optional function to be used if simple value assignment is not enough
The Service class only defines the logLevel, and start/stop/restart timeout attribute

Returns Object

$3

Definition of the predefined endpoints.

log out*
config in*

Returns Object predefined endpoints

StandaloneServiceProvider

Extends ServiceProviderMixin(Service)

Simple service manager (for examples and testing only).

$3

Returns string 'standalone-provider'

install

With npm do:

`shell
npm install @kronos-integration/service
``

license

BSD-2-Clause