2-common-configuration.md

Configuration Guide: Common Configuration

This chapter documents commonly-used configuration properties and syntax, used for more than one type of component (e.g., both services and applications).

File Names

Several components accept file paths as configured properties, which are typically required to be absolute paths. In some cases, the final name component of the path is treated as a prefix + suffix combination, where the prefix is everything before a final dot (.), and the suffix is the final dot and everything that follows. (For example, some.file.txt would be parsed as prefix some.file and suffix .txt.) These parsed names are used to construct actual file names by inserting something in between the prefix and suffix (such as a date stamp and/or a sequence number), or in some cases just used as-is.

Real-World Units

Several configurations are specified as real-world units, including for example time durations and data quantities. Each type of unit has a corresponding class, and can be specified in a configuration file using that class directly or by providing a string that can be parsed into an instance of that class. The classes are all in either the quant or webapp-util module.

When using a string, the accepted syntax is a number in the usual JavaScript form (including exponents and internal underscores), followed by the unit name(s). The number and unit name are allowed to be separated by a single space or underscore, as is the slash (/) between numerator and denominator units. The slash can be replaced with the word per (which must be separated from the units with a space or underscore).

Examples:

• 1 day
• 1_000ms
• 123_per_sec
• 5/hour
• 120 GiB per day

ByteCount

Amounts of data are specified using the class ByteCount. The available units are:

• byte or B — Bytes.
• kB, MB, GB, or TB — Standard decimal powers-of-1000 bytes.
• KiB, MiB, GiB, or TiB — Standard binary powers-of-1024 bytes.

import { ByteCount } from '@lactoserv/quant';

ByteRate

Rates of data flow are specified using the class ByteRate. The available units are the same as with ByteCount for the numerator and the same as with Frequency for the denominator (except that hertz / Hz isn't allowed).

import { ByteRate } from '@lactoserv/quant';

ConnectionCount and ConnectionRate

Counts and rates of network connections are covered by the classes ConnectionCount and ConnectionRate. The numerator units — connection, conn, and c — are all equivalent and represent a single connection. Denominator units are the same as with Frequency.

import { ConnectionCount, ConnectionRate } from '@lactoserv/webapp-util';

Duration

Durations are specified using the class Duration. The available units are:

• nsec or ns — Nanoseconds.
• usec or us — Microseconds.
• msec or ms — Milliseconds.
• second or sec or s — Seconds.
• minute or min or m — Minutes.
• hour or hr or h — Hours.
• day or d — Days, where a "day" is defined to be exactly 24 hours.

import { Duration } from '@lactoserv/quant';

Frequency

Frequencies are specified using the class Frequency. The available units are:

• /nsec or /ns — Per nanosecond.
• /usec or /us — Per microsecond.
• /msec or /ms — Per millisecond.
• /second or /sec or /s — Per second.
• /minute or /min or /m — Per minute.
• /hour or /hr or /h — Per hour.
• /day or /d — Per (24-hour) day.

As a rarely-useful addition, the numerator unit hertz or Hz is allowed as an equivalent to /sec.

import { Frequency } from '@lactoserv/quant';

RequestCount and RequestRate

Counts and rates of network requests are covered by the classes RequestCount and RequestRate. The numerator units — request, req, and r — are all equivalent and represent a single request. Denominator units are the same as with Frequency.

import { RequestCount, RequestRate } from '@lactoserv/webapp-util';

Rate Limiting

A handful of applications and services have rate-limiting functionality. Rate limiting is modeled as a hybrid-model "leaky token bucket," where a non-empty bucket causes immediate flow (of data, etc.), and an empty bucket causes the system to allow flow at a defined rate.

These applications and services all accept a common set of configuration options. In each specific case, there is a "token unit" and a "flow rate unit." These units are always each a real-world unit of some sort (as described above).

• flowRate — The rate of token flow once any burst capacity is exhausted, and the rate at which burst capacity is built up. The rate must be positive.
• initialBurst — Optional starting amount of available token "burst" before rate limiting takes effect. Minimum value 0, and must be no larger than maxBurst. Defaults to maxBurst.
• maxBurst — The maximum number of tokens that can be built up for a "burst" before rate limiting takes effect. Minimum value 1.
• maxQueue — Optional maximum possible size of the wait queue, in tokens, or null for no limit. Minimum value 1. This is the number of tokens that are allowed to be queued up for a grant, when there is insufficient burst capacity to satisfy all active clients. Attempts to queue up more requests will result in token denials (e.g., network connections closed instead of sending bytes). Defaults to null.
• maxQueueGrant — Optional maximum possible size of a grant given to a requester in the wait queue, in tokens. Minimum value 1. If not specified, it is the same as the maxBurst. Note: This configuration is only used by some rate limiters.

import { SomeSortOfRateLimiter } from '@lactoserv/webapp-builtins';

const services = [
  {
    name:          'limiter',
    class:         SomeSortOfRateLimiter,
    initialBurst:  '1 MiB',
    maxBurst:      '5 MiB',
    flowRate:      '32 KiB/sec',
    maxQueue:      '32 MiB',
    maxQueueGrant: '100 KiB'
  }
];

This diagram might help understand the various configuration options:

Logging

Endpoints, applications, and services all offer the option to log their dispatch processes in detail. This is turned off by default. To turn it on, use the configuration option dispatchLogging: true.

Turning on this option causes dispatch logging to be initiated at the item in question, but it won't turn off logging if initiated earlier in the dispatch. For example, if an application has dispatch logging turned off, but the endpoint which dispatched to it has it on, then the application will perform dispatch logging.

const applications = [
  {
    name:            'chattyAppy',
    class:           ChattyAppy,
    dispatchLogging: true,
    // ... more ...
  }
];

---

Copyright 2022-2025 the Lactoserv Authors (Dan Bornstein et alia).
SPDX-License-Identifier: Apache-2.0