Microservice (mservice)

Description

Descriptor of a console microservice that is started and kept running.
Started by one or several nodes. On failure it is restarted automatically, but cyclic restarts are excluded (5 times in 10 seconds). If exceeded, the system forcibly disables the account.
Runs as a command line that can contain macros for substituting the domain, URLs of system web servers on the current site, and the path to the log folder.
The command runs in the working directory where the attached zip archive (attachment) is first and mandatorily unpacked. The archive can contain a script, application, or other files. The archive is mandatory.

Limitations

  • The collection is unavailable in the master domain.

Fields

Entity structure
{
  "id": uuid,
  "name": str,
  "cmdline": str,
  "cmdparam": str,
  "enabled": bool,
  "attachment": file,
  "opts": {
    "title": str,
    "comment": str,
    "mode": str,
    "site_mode": str,
    "selected_sites": array<str>,
    "restart_mode": str,
    "heartbeat_timeout": str,
    "attachment_info": object
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Fields
Specification Description

Field: id
Mode: inout
Type: uuid
Default: generated

Identifier. Can be specified at creation, otherwise generated by the system.

Field: name
Mode: in
Type: str
Default: required

Name

Field: cmdline
Mode: in
Type: str
Default: required

Executable command.
May contain the macros %WEBSERVERS%, %WEBSERVERS_EX%, %DOMAIN%, %LOGPATH%, %SERVERNAME%, %TOKEN%, %TOKENFILE%, %CERTPATH%, %CERTPATH(<ConstantToken>)%.

  • DOMAIN - current domain.

  • LOGPATH - absolute path to the microservice log directory.

  • SERVERNAME - name of the current server.

  • WEBSERVERS - list of web server URLs for connection.

  • WEBSERVERS_EX - object with the distribution of web server URLs for connection: local, by tags and sections.

  • TOKEN - substitutes the standard token from the domain through which the product layer was installed. If it was deleted (does not exist), an empty value or error is substituted. In logs the command line is printed with a mask instead of the token.

  • TOKENFILE - substitutes the absolute path to a file with this token in the microservice working directory (<random string>.eratoken, a new name on every start, permissions 0600). The microservice should read the file immediately on startup (before slow initialization) and delete it, keeping the token in memory: the file cannot be read again. The file is created before startup and deleted 10 seconds after startup (if the microservice has not deleted it itself), on process termination, on stop, and on msvc role start; on every start and restart of the microservice, all *.eratoken files in its working directory are deleted. The token does not appear in the process command line; when the token is reissued, the microservice is restarted (same as with %TOKEN%).
    The plaintext token of this channel, written into the command or parameters (for example, by the product layer installer), is replaced by the domain center with %TOKEN%.

  • CERTPATH - substitutes the absolute path to the client certificate associated with this standard integration channel.

  • CERTPATH(custom_token) - where custom_token is a specific constant token used to find the integration channel in the domain, from which the associated client certificate is taken; the absolute path is substituted.

Field: cmdparam
Mode: in
Type: str
Default: required

Parameters added to the executable command.
May contain the macros described in the 'cmdline' parameter.

Macro values are generated automatically based on the active configuration, the current microservice instance, the current domain, and possibly the master domain option https_host.

Field: enabled
Mode: in
Type: bool
Default: true

Activity switch.

Field: attachment
Mode: in
Type: file
Default: empty

Property for uploading the archive with the working directory contents. Mainly contains an executable script or program.
The property is absent in the object itself; only the endpoint path in the REST API is formed from it.
Information about the uploaded archive is available via opts.attachment_info.

Field: opts
Mode: in
Type: object
Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Arbitrary title

Field: opts.comment
Mode: in
Type: str
Default: empty

Arbitrary comment

Field: opts.mode
Mode: in
Type: str
Default: active-passive

Operating mode within the site:

  • active-active. On all msvc role instances allowed to execute the microservice based on the specified section.

  • active-passive. On exactly one msvc role instance within the site.

Field: opts.section
Mode: in
Type: str
Default: empty

Section of msvc role instances where this uploaded microservice may run.
If no section is specified, the filter is not applied.

For each msvc instance, several sections can be specified in the configuration, or none at all.

If the configuration has no msvc instances on the current site serving the specified section, all msvc instances of the current site are allowed to serve the entity (this behavior differs from class.opts.section).

Field: opts.leader_mode
Mode: in
Type: str
Default: hashring

Leader selection mode among msvc instances allowed to execute this microservice taking the specified section into account.
Applied only when active-passive mode is selected.

Selection is performed by sorting on a key:

  • hashring. The key is a hash of the domain, microservice, and node names.

  • ordered. The key is the value of the 'order' configuration option of msvc instances. If not set, it is considered 0 (highest priority). Instances with equal priorities are sorted by hash.

Field: opts.site_mode
Mode: in
Type: empty
Default: "

Operating mode between sites:

  • all. On all sites serving the domain.

  • selected. On the specified sites that serve the domain.

  • any. On any site serving the domain.

Field: opts.selected_sites
Mode: in
Type: str or 'array<object>'
Default: empty

List of sites for site_mode='selected'.

Field: opts.restart_mode
Mode: in
Type: str
Default: permanent

Restart mode:

  • permanent. Restart after any termination.

  • transient. Restart only on a non-zero return code.

  • temporary. Not restarted on termination.

Field: opts.heartbeat_interval
Mode: in
Type: int
Default: 5000

Interval for sending the msvc role instance activity notification (500 - 60000 ms).
For mode='active-passive'.

Field: opts.attachment_info
Mode: out
Type: object
Default: empty

Information about the uploaded attachment, available for reading. The attachment itself is uploaded via the /attachment path in the REST API.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending the compound with arbitrary keys and values

Field: ext.ct
Mode: out
Type: date
Default: generated

Object creation time

Field: ext.lwt
Mode: out
Type: date
Default: generated

Time of last modification of the object