Document the 'experimental.config.utils.schema' module (#4469)

Resolves #4279.

Co-authored-by: Pavel Semyonov <[email protected]>
Co-authored-by: Elena Shebunyaeva <[email protected]>

doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua

@@ -1,15 +1,20 @@
 -- greeter.lua --
 local log = require('log').new("greeter")
+local schema = require('experimental.config.utils.schema')
+
+local greeter_schema = schema.new('greeter', schema.record({
+ greeting = schema.scalar({
+ type = 'string',
+ allowed_values = { 'Hi', 'Hello' }
+ })
+}))
 
 local function validate(cfg)
- if cfg.greeting then
- assert(type(cfg.greeting) == "string", "'greeting' should be a string")
- assert(cfg.greeting == "Hi" or cfg.greeting == "Hello", "'greeting' should be 'Hi' or 'Hello'")
- end
+ greeter_schema:validate(cfg)
 end
 
 local function apply(cfg)
- log.info("%s from the 'greeter' role!", cfg.greeting)
+ log.info("%s from the 'greeter' role!", greeter_schema:get(cfg, 'greeting'))
 end
 
 local function stop()

doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua

@@ -1,22 +1,46 @@
 -- http-api.lua --
 local httpd
 local json = require('json')
+local schema = require('experimental.config.utils.schema')
 
-local function validate(cfg)
- if cfg.host then
- assert(type(cfg.host) == "string", "'host' should be a string containing a valid IP address")
+local function validate_host(host, w)
+ local host_pattern = "^(%d+)%.(%d+)%.(%d+)%.(%d+)$"
+ if not host:match(host_pattern) then
+ w.error("'host' should be a string containing a valid IP address, got %q", host)
  end
- if cfg.port then
- assert(type(cfg.port) == "number", "'port' should be a number")
- assert(cfg.port >= 1 and cfg.port <= 65535, "'port' should be between 1 and 65535")
+end
+
+local function validate_port(port, w)
+ if port <= 1 or port >= 65535 then
+ w.error("'port' should be between 1 and 65535, got %d", port)
  end
 end
 
+local listen_address_schema = schema.new('listen_address', schema.record({
+ host = schema.scalar({
+ type = 'string',
+ validate = validate_host,
+ default = '127.0.0.1',
+ }),
+ port = schema.scalar({
+ type = 'integer',
+ validate = validate_port,
+ default = 8080,
+ }),
+}))
+
+local function validate(cfg)
+ listen_address_schema:validate(cfg)
+end
+
 local function apply(cfg)
  if httpd then
  httpd:stop()
  end
- httpd = require('http.server').new(cfg.host, cfg.port)
+ local cfg_with_defaults = listen_address_schema:apply_default(cfg)
+ local host = listen_address_schema:get(cfg_with_defaults, 'host')
+ local port = listen_address_schema:get(cfg_with_defaults, 'port')
+ httpd = require('http.server').new(host, port)
  local response_headers = { ['content-type'] = 'application/json' }
  httpd:route({ path = '/band/:id', method = 'GET' }, function(req)
  local id = req:stash('id')

doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/config.yaml

@@ -0,0 +1,12 @@
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ roles: [ http_api ]
+ roles_cfg:
+ http_api:
+ host: '127.0.0.1'
+ port: 8080
+ scheme: 'http'

doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/http_api.lua

@@ -0,0 +1,56 @@
+-- http_api.lua --
+local log = require('log').new("http_api")
+local schema = require('experimental.config.utils.schema')
+
+local function validate_host(host, w)
+ local host_pattern = "^(%d+)%.(%d+)%.(%d+)%.(%d+)$"
+ if not host:match(host_pattern) then
+ w.error("'host' should be a string containing a valid IP address, got %q", host)
+ end
+end
+
+local function validate_port(port, w)
+ if port <= 1 or port >= 65535 then
+ w.error("'port' should be between 1 and 65535, got %d", port)
+ end
+end
+
+local listen_address_schema = schema.new('listen_address', schema.record({
+ scheme = schema.scalar({
+ type = 'string',
+ allowed_values = { 'http', 'https' },
+ default = 'http',
+ }),
+ host = schema.scalar({
+ type = 'string',
+ validate = validate_host,
+ default = '127.0.0.1',
+ }),
+ port = schema.scalar({
+ type = 'integer',
+ validate = validate_port,
+ default = 8080,
+ }),
+}))
+
+local function validate(cfg)
+ listen_address_schema:validate(cfg)
+end
+
+local function apply(cfg)
+ local cfg_with_defaults = listen_address_schema:apply_default(cfg)
+ local scheme = listen_address_schema:get(cfg_with_defaults, 'scheme')
+ local host = listen_address_schema:get(cfg_with_defaults, 'host')
+ local port = listen_address_schema:get(cfg_with_defaults, 'port')
+ log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port)
+end
+
+local function stop()
+ log.info("The 'http_api' role is stopped")
+end
+
+return {
+ validate = validate,
+ apply = apply,
+ stop = stop,
+}

doc/code_snippets/snippets/config/instances.enabled/config_schema_annotations/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/api.lua

@@ -0,0 +1,51 @@
+-- api.lua --
+local log = require('log').new("api")
+local schema = require('experimental.config.utils.schema')
+
+local listen_address = schema.record({
+ scheme = schema.enum({ 'http', 'https' }),
+ host = schema.scalar({ type = 'string' }),
+ port = schema.scalar({ type = 'integer' })
+}, {
+ validate = function(data, w)
+ local protocol = w.schema.computed.annotations.protocol
+ if protocol == 'iproto' and data.scheme ~= nil then
+ w.error("iproto doesn't support 'scheme'")
+ end
+ end,
+})
+
+local http_listen_address_schema = schema.new('http_listen_address', schema.record({
+ name = schema.scalar({ type = 'string' }),
+ listen_address = listen_address,
+}, {
+ protocol = 'http',
+}))
+
+local iproto_listen_address_schema = schema.new('iproto_listen_address', schema.record({
+ name = schema.scalar({ type = 'string' }),
+ listen_address = listen_address,
+}, {
+ protocol = 'iproto',
+}))
+
+local function validate(cfg)
+ http_listen_address_schema:validate(cfg)
+end
+
+local function apply(cfg)
+ local scheme = http_listen_address_schema:get(cfg, 'listen_address.scheme')
+ local host = http_listen_address_schema:get(cfg, 'listen_address.host')
+ local port = http_listen_address_schema:get(cfg, 'listen_address.port')
+ log.info("API endpoint: %s://%s:%d", scheme, host, port)
+end
+
+local function stop()
+ log.info("The 'api' role is stopped")
+end
+
+return {
+ validate = validate,
+ apply = apply,
+ stop = stop,
+}

doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/config.yaml

@@ -0,0 +1,14 @@
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ roles: [ api ]
+ roles_cfg:
+ api:
+ name: 'HTTP listen address'
+ listen_address:
+ host: '127.0.0.1'
+ port: 8080
+ scheme: 'http'

doc/code_snippets/snippets/config/instances.enabled/config_schema_computed_annotations/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/config.yaml

@@ -0,0 +1,12 @@
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ roles: [ http_api ]
+ roles_cfg:
+ http_api:
+ host: '127.0.0.1'
+ port: 8080
+ scheme: 'http'

doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/http_api.lua

@@ -0,0 +1,43 @@
+-- http_api.lua --
+local log = require('log').new("http_api")
+local schema = require('experimental.config.utils.schema')
+
+local listen_address_schema = schema.new('listen_address', schema.record({
+ scheme = schema.enum({ 'http', 'https' }, { env = 'HTTP_SCHEME' }),
+ host = schema.scalar({ type = 'string', env = 'HTTP_HOST' }),
+ port = schema.scalar({ type = 'integer', env = 'HTTP_PORT' })
+}))
+
+local function collect_env_cfg()
+ local res = {}
+ for _, w in listen_address_schema:pairs() do
+ local env_var = w.schema.env
+ if env_var ~= nil then
+ local value = schema.fromenv(env_var, os.getenv(env_var), w.schema)
+ listen_address_schema:set(res, w.path, value)
+ end
+ end
+ return res
+end
+
+local function validate(cfg)
+ local env_cfg = collect_env_cfg()
+ local result_cfg = listen_address_schema:merge(cfg, env_cfg)
+ listen_address_schema:validate(result_cfg)
+end
+
+local function apply(cfg)
+ local env_cfg = collect_env_cfg()
+ local result_cfg = listen_address_schema:merge(cfg, env_cfg)
+ log.info("HTTP API endpoint: %s://%s:%d", result_cfg.scheme, result_cfg.host, result_cfg.port)
+end
+
+local function stop()
+ log.info("The 'http_api' role is stopped")
+end
+
+return {
+ validate = validate,
+ apply = apply,
+ stop = stop,
+}

doc/code_snippets/snippets/config/instances.enabled/config_schema_fromenv/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/config.yaml

@@ -0,0 +1,12 @@
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ roles: [ http_api ]
+ roles_cfg:
+ http_api:
+ host: '127.0.0.1'
+ port: 8080
+ scheme: 'http'

doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/http_api.lua

@@ -0,0 +1,40 @@
+-- http_api.lua --
+local log = require('log').new("http_api")
+local schema = require('experimental.config.utils.schema')
+
+local listen_address_schema = schema.new(
+ "listen_address",
+ schema.record(
+ {
+ scheme = schema.enum({ "http", "https" }),
+ host = schema.scalar({ type = "string" }),
+ port = schema.scalar({ type = "integer" })
+ }
+ ),
+ {
+ methods = {
+ format = function(_self, url)
+ return string.format("%s://%s:%d", url.scheme, url.host, url.port)
+ end
+ }
+ }
+)
+
+local function validate(cfg)
+ listen_address_schema:validate(cfg)
+end
+
+local function apply(cfg)
+ local url_string = listen_address_schema:format(cfg)
+ log.info("HTTP API endpoint: %s", url_string)
+end
+
+local function stop()
+ log.info("The 'http_api' role is stopped")
+end
+
+return {
+ validate = validate,
+ apply = apply,
+ stop = stop,
+}

doc/code_snippets/snippets/config/instances.enabled/config_schema_methods/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/config.yaml

@@ -0,0 +1,15 @@
+groups:
+ group001:
+ replicasets:
+ replicaset001:
+ instances:
+ instance001:
+ roles: [ http-api ]
+ roles_cfg:
+ http-api:
+ - host: '127.0.0.1'
+ port: 8080
+ scheme: 'http'
+ - host: '127.0.0.1'
+ port: 8443
+ scheme: 'https'

doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/http-api.lua

@@ -0,0 +1,34 @@
+-- http_api.lua --
+local log = require('log').new("http_api")
+local schema = require('experimental.config.utils.schema')
+
+local listen_address_schema = schema.new('listen_address', schema.array({
+ items = schema.record({
+ scheme = schema.enum({ 'http', 'https' }),
+ host = schema.scalar({ type = 'string' }),
+ port = schema.scalar({ type = 'integer' })
+ })
+}))
+
+local function validate(cfg)
+ listen_address_schema:validate(cfg)
+end
+
+local function apply(cfg)
+ for _, uri in ipairs(cfg) do
+ local scheme = uri.scheme
+ local host = uri.host
+ local port = uri.port
+ log.info("HTTP API endpoint: %s://%s:%d", scheme, host, port)
+ end
+end
+
+local function stop()
+ log.info("The 'http_api' role is stopped")
+end
+
+return {
+ validate = validate,
+ apply = apply,
+ stop = stop,
+}

doc/code_snippets/snippets/config/instances.enabled/config_schema_nodes_array/instances.yml

@@ -0,0 +1 @@
+instance001: