Settings

The settings of the platform: the levels they are set at, the owners of the keys, the settings window, the languages of the interface and the list of all keys.

Introduction

The document describes where the values of settings come from, the owners of the keys, how settings are shown to the person and how the languages of the interface are made. The values are kept by the function settings, the texts are gathered by the function i18n, the meaning of each key is set by its owner. The file format — File formats, section 8, the methods — Methods of the platform services, section 1.

1 Levels

A value is looked for from the narrow level to the wide one and taken from the first level where it is set. In table 1 the levels are listed from wide to narrow.

Table 1 — Levels

There is no level of module settings: what the person sets for a module are the parameters of the node (Modules, section 10).

The keys core.* at any level but session are written into core.json. A key with restart: true in its schema takes effect at the next start; the platform does not show it as applied at once.

2 The schema of settings

Each owner describes its settings in one schema file settings.schema.json beside its code (The make-up of the platform); the program builds it in. There are no other places where the default or the limits of a setting are written — neither in the code of the owner, nor in the function of settings, nor in the window (rule 2.2 of Rules of development). The file format — File formats, section 8.

The schema divides the settings of the owner into subsections. Each key in it has:

• type — string, integer, number (a fraction: a share, millimetres, the temperature of a model), string[] or color (#RGB / #RRGGBB);
• default — the default value;
• default_by — optional: a default that depends on the value of another key of the same owner. So the colours of the shell follow the chosen colour scheme;
• restart — whether a restart is needed for the value to take effect;
• for numbers — min and max, for a closed set of values — choices.

The texts of a setting are kept in the dictionaries of the owner, not in the schema, and are named by a rule; the names of the texts are not written separately (table 2).

Table 2 — The texts of a setting in the dictionaries

The check in make ci does not pass if a key of a schema lacks any of these texts in Russian or English, or if an explanation repeats a number of its schema — a limit or the default, except zero: such a copy would drift from the schema at its first change.

The code of an owner reads its setting through a common helper from the common code of the protocol. The helper asks the function of settings, and when there is no answer takes the default from the same schema file. The code has no fallback values of its own.

The exception is the values of the process level: these are free keys to put into the parameters of nodes (The program: graph and runs, section 15), and they have no schema. They are written by settings.set with the level process, and settings.get with process_id returns them as written (Methods of the platform services, section 1).

3 The owners of keys

The prefix of a key is the address of its owner (rule 2.4). The function of settings keeps values and checks them by the schema, but has no keys of its own: the meaning of each key is set by its owner.

Table 3 — The owners of keys

An owner registers its schema at its start and again each time the function of settings comes up anew (the event function.ready): it keeps the schemas of the owners only while it works, and after its restart, without a new registration, the person's values would stop taking effect. An owner names settings in its description (requires, The make-up of the platform, 3.4.1); make ci checks it. An owner for whom the defaults of its schema are harmless names it as optional (optional) and works on the defaults until it comes — so the function i18n is made; to the graph and the function of modules the settings are required: their values decide what to keep and how many resources to take. Only one's own schema can be registered: the owner is named by the kernel, the sender of the call (Exchange with the kernel, section 3), and the schema of another owner is refused with settings_invalid_owner; the schema holds only keys with one's own prefix, a foreign key is refused with settings_invalid. Registering the same owner again replaces its schema whole.

The kernel starts before the function of settings and cannot ask it. So it reads the keys core.* itself: by its own schema, from core.json and system.json. If a value in these files does not fit the schema — a number out of bounds or a wrong type — the kernel does not start and names the file, the key, the value and the allowed values. It does the same with a file that cannot be parsed.

The function of settings checks by the schema what already lies in the files of the levels too: a file might have been changed by hand. It does not use an unfitting value — it takes the value from a wider level — and publishes the event settings.value_invalid with error_code: settings_value_invalid, the file and the key; by it the function of observation opens a problem.

4 Writing and reset

• A value is checked before it is written; if it does not fit, the old one stays.
• The file is written whole; after writing the event settings.changed is published.
• Reset removes a value from a level: the key is removed from the file or from the memory of the session, and the value is taken again from wider levels and from the schema. The default is not written into the file. A key is taken off the file its write at that level went to: a core.* key — off core.json, as it was written.

5 Secrets

The platform does not keep passwords and access keys. A setting whose name holds secret, password, token, api_key, apikey or private_key (capital and small letters alike) is refused with settings_secret_rejected. This guards against an accidental mistake and does not recognise secrets: the key openai_key passes the check (Protection, 3.5).

6 The settings window

• The section «State» stands first in the column of the window: whether the kernel works, which functions are connected, the latest errors and simple counters. This section is not a list of modules.
• Order. Then come the large sections (kernel, interface, other), inside them the subsections. Subsections are folded by default.
• Changing a value. A value is changed on the tab «Edit» of the panel of the chosen setting (The workshop, 5.1); the key Enter, the button «Write» and going to another setting write the value, like leaving a field of a pulpit; a value that does not pass the check of the schema is not written. A value from a closed set is chosen from a list.
• Help. Each row has a sign «?» that opens its explanation; the explanation, the key, the default and the allowed values are shown on the tab «Information».
• Reset. The button «Reset» on the tab «Edit» returns the default of the setting, the button «Reset all» — the defaults of the whole section.
• Restart. Settings that need a restart are marked.

7 Languages

• In code there are only the keys of strings; the texts themselves are in the JSON dictionaries of the owner of the text: the labels of the window — at the function ui, the names of settings and the texts of errors — at the owner of the key or of the error code (rule 2.2). The function i18n gathers the dictionaries but keeps no texts of others.
• The language of the interface is the setting i18n.language. Its owner is the function i18n; the settings window writes it with an ordinary settings.set, like any other, the language switch of the workshop — with the owner's command i18n.language.set, and the workshop learns the language with the query i18n.language.get, not knowing the key of the setting; the function i18n reads it at every request and keeps no copy of the language of its own.
• Dictionaries. Functions declare the folders of their dictionaries when they introduce themselves (locales); a folder with a segment * means each such folder that exists at the moment of the question, so dictionaries that appeared during work are seen without a new declaration (Exchange with the kernel, section 4). The kernel gives their list with the query core.locales and adds its own folder core/kernel/locales to it; the function i18n reads only these folders and its own.
• The language of a module. A module learns the language in the message init. The function of modules asks the owner for it with the query i18n.language.get at every start of a module; without the function i18n the language in init is null, and the module speaks its default language.
• A missing text for a key is a problem for diagnosis, not a refusal: i18n.translate gives the key itself instead of the text and publishes the event i18n.key_missing with error_code: i18n_key_missing, by which the function of observation opens one problem per key.
• The required languages are Russian and English; a new language is dictionaries, without code. There are no ready sets of settings switched on as a whole: the levels and reset already let one start anew.

8 List of keys

The section holds only the keys and their purpose. The type, the default, the allowed values and whether a restart is needed are written in one place — in the schema file of the owner — and are not repeated in the document: a change of a default is made in one file. The check in make ci does not pass if a key of a schema is not mentioned here, or a key is mentioned that is in no schema.

The kernel — core/kernel/settings.schema.json:

Table 4 — Settings keys of the kernel

The kernel reads its keys at its start, so they take effect after the platform is restarted; the two keys of the room the kernel reads again at every question about the room, and they take effect at once.

The workshop — functions/ui/settings.schema.json:

Table 5 — Settings keys of the workshop

Language — functions/i18n/settings.schema.json:

Table 6 — Settings keys of the language

The graph — functions/graph/settings.schema.json:

Table 7 — Settings keys of the function of the graph

Modules — functions/modules/settings.schema.json:

Table 8 — Settings keys of the function of modules

How long to wait for a module to stop is set by core.process_stop_grace_ms: stopping an OS process is the kernel's business, and there is no second key about the same.

The pulpit — functions/canvas/settings.schema.json, the section of the settings window «Interface of the platform»:

Table 9 — Settings keys of the function of the pulpit

The numbers of the sheet take effect from the next change of the pulpit; sheets that already exist do not change by them. A process may have its own numbers at the level of the settings of the process (The workshop, 6.3).

The keys canvas.theme_* are the look of a pulpit that did not set its own: a pulpit names in its document only the theme keys it set itself, the rest are taken from here (The workshop, 6.5). The section of the schema canvas.theme is at once the closed list of theme keys and the description of what each takes: the document of the pulpit is checked by it as well (File formats, section 7).

The journal — functions/observe/settings.schema.json:

Table 10 — Settings keys of the function of observation

Sources — functions/sources/settings.schema.json (The workshop, 5.6):

Table 11 — Settings keys of the function of sources

The door for programs — functions/gate/settings.schema.json (Methods of the platform services, section 5):

Table 12 — Settings keys of the function of the door

The assistant — functions/assistant/settings.schema.json (Methods of the platform services, section 6):

Table 13 — Settings keys of the function of the assistant

The profile — functions/profile/settings.schema.json (Methods of the platform services, section 7):

Table 14 — Settings keys of the function of the profile