SwiftBox

SwiftBox is a SwiftNIO based package that helps building Swift/NIO-based microservices.

What’s included?

Running microservices with Swift requires:

• logging capabilities
• accessing configuration (e.g from Vault store)
• pushing metrics to the metric store.

Coming soon: Integration with https://github.com/apple/swift-log.

SwiftBox Configuration

SwiftBox Configuration allows to pass type-safe configuration such as command line, environment variables and external providers (e.g Vault) by declaring one simple struct. Configuration can be inherited from multiple sources simultaneously.

Feed the configuration with:

• Command line arguments: ./yourapp --config:simple=test --config:nested.number=1 --config:array.0=string
• Environment variables: SIMPLE=test NESTED_NUMBER=1 ARRAY_0=string ./yourapp
• JSON
• Dictionary

SwiftBox Configuration supports:

• overriding (source that is declared later can override previous values)
• inheritance
• optionals
• type-safety
• nesting (structs and arrays)
• environment variables prefixes (avoid conflicting with system variables)

Usage

1. Import

Import module:

import SwiftBoxConfig

2. Configuration structure

When you create your configuration, remember that it in order to be decoded properly, it must conform to the Configuration protocol.

struct Conf: Configuration {
    let simple: String
    let int: Int
    let double: Double
    let nested: NestedConf // nested configuration
    let array: [String?] // array of optionals
    let arraynested: [NestedConf] // nested array

    struct NestedConf: Configuration {
        let value: String? // optional
    }
}

3. Bootstrap

Configuration must be bootstrapped before use. To do so, you need to conform to the ConfigManager protocol in the first place:

extension Conf: ConfigManager {
    public static var configuration: Conf? = nil
}

Next, call bootstrap method on your ConfigManager and pass sources you want to use:

try Conf.bootstrap(from: [EnvSource()])

Remember that bootstrap must be called before using config and cannot be called more than once. Otherwise, fatalError will be thrown.

4. Usage

After completing all the previous steps you can finally use config in your application. You can access the configuration instance via global property:

Conf.global.simple
Conf.global.int
Conf.global.double
Conf.global.array[0] // Optional[String]
Conf.global.nested.value // Optional[String]
Conf.global.arraynested[0].value // Optional[String]

Sources

Configuration can be fed with multiple sources. Sources are passed into bootstrap function.

If you are using multiple sources, outputs are merged (structs are merged recursively, other values are overridden):

try Conf.bootstrap(from: [
    DictionarySource(dataSource: [
        "int": 1,
        "string": "some",
        "array": [1, 2],
        "nested": ["value1": 1]
    ]),
    DictionarySource(dataSource: [
        "string": "test",
        "array": [2, 3],
        "nested": ["value2": 2]
    ]),
])

// Output config:
[
    "int": 1,
    "string": "test",
    "array": [2, 3],
    "nested": [
        "value1": 1,
        "value2": 2
    ]
]

Dictionary source

Allows reading configuration from Dictionary, may be used to specify in-code defaults for configuration.

Example

try Conf.bootstrap(from: [
    DictionarySource(dataSource: [
        "int": 1,
        "string": "some",
        "array": [1, 2],
        "nested": ["value1": 1]
    ])
])

JSON source

Allows reading configuration from JSON data.

Example

try Conf.bootstrap(from: [
    JSONSource(dataSource: "{\"test\": \"sample\"}")
])

Environment source

Allows reading configuration data from environment.

Example

try Conf.bootstrap(from: [
    EnvSource(prefix: "SAMPLE")
])

Prefix can be set for EnvSource, so it reads only variables which key starts with a given value.

Sample Configuration

struct Conf: Configuration {
    let simple: String
    let int: Int
    let double: Double
    let nested: NestedConf
    let array: [String?]
    let arraynested: [NestedConf]

    struct NestedConf: Configuration {
        let value: String?
    }
}

Above example may be populated using following env variables:

SIMPLE="test"
INT="1"
DOUBLE="1.0"
NULL="null"
NESTED_VALUE="test"
ARRAY_0="test0"
ARRAY_1="test1"
ARRAY_2="null"
ARRAYNESTED_0_VALUE="test0"
ARRAYNESTED_1_VALUE="test1"
ARRAYNESTED_2_VALUE="null"

Value “null” is coerced to internal nil value

Command line source

Allows reading configuration data from environment.

Example

Conf.bootstrap(from: [
    CommandLineSource(prefix: "--config:my-prefix-")
])

If a prefix is set, only arguments which start with a given value will be read. Defaults to --config:

Sample Configuration

struct Conf: Configuration {
    let simple: String
    let int: Int
    let double: Double
    let null: String?
    let nested: NestedConf
    let array: [String?]
    let arraynested: [NestedConf]

    struct NestedConf: Configuration {
        let value: String?
    }
}

The example above may be populated using following command line arguments:

--config:simple=test
--config:int=1
--config:double=1.0
--config:null=null
--config:nested.value=test
--config:array.0=test0
--config:array.1=test1
--config:array.2=null
--config:arraynested.0.value=test0
--config:arraynested.1.value=test1
--config:arraynested.2.value=null

Value “null” is coerced to internal nil value

Custom sources

To create custom sources, you need to create a class that conforms to ConfigSource. DictionarySource is the simplest working source that can be used as an example:

public typealias Storage = [String: Any?]

public class DictionarySource: ConfigSource {
    let dataSource: Storage

    public init(dataSource: Storage) {
        self.dataSource = dataSource
    }

    public func getConfig() throws -> Storage {
        return self.dataSource
    }
}

SwiftBoxLogging

Logging system for Swift.

Usage

1. Import

import SwiftBoxLogging

2. Bootstrap

Logging should be bootstrapped before use (it defaults to PrintLogger). Bootstrap requires one parameter which is the logger factory.

Logger factory must return LogHandler from swift-log package.

Logging.bootstrap { label in ElasticsearchLogHandler(label: name) }

2. Usage

Create a logger instance:

fileprivate var logger = Logging.make(#file)

Log a message using one of the available protocol methods:

func trace(_ message: String)
func info(_ message: String)
func debug(_ message: String)
func notice(_ message: String)
func warning(_ message: String)
func error(_ message: String)
func critical(_ message: String)

Custom Loggers

To create custom loggers your class must conform to LoggerProtocol.

Vapor

You can use the same logging by overriding Vapor’s default log handler:

import Logging

LoggingSystem.bootstrap { label in
    ElasticsearchLogHandler(label: label)
}

SwiftBoxMetrics

StatsD and Logger handlers for official swift-metrics API.

Supported metric types:

• Counters
• Timers
• Gauges

Usage

1. Import

import Metrics
import SwiftBoxMetrics

2. Bootstrap

Metrics must be bootstraped with Handler, which conforms to MetricsHandler protocol:

// StatsD Handler initialization
MetricsSystem.bootstrap(
    try! StatsDMetricsHandler(
        baseMetricPath: AppConfig.global.statsd.basePath!,
        client: UDPStatsDClient(
            config: UDPConnectionConfig(
                host: AppConfig.global.statsd.host!,
                port: AppConfig.global.statsd.port!
            )
        )
    )
)

// Logger Handler initialization
MetricsSystem.bootstrap(LoggerMetricsHandler())

3. Usage

Usage details can be found in official swift-metrics GitHub repository.

Handlers

LoggerMetricsHandler

Default metrics handler which sends gathered metrics to its logger.

StatsDMetricsHandler

StatsD Metrics Handler is responsible for sending gathered logs to StatsD server. Supports TCP and UDP protocols. Metrics are sent in separate thread, so operation is non-blocking for application.

try StatsDMetricsHandler(
    baseMetricPath: AppConfig.global.statsd.basePath!,
    client: UDPStatsDClient(
        config: UDPConnectionConfig(
            host: AppConfig.global.statsd.host!,
            port: AppConfig.global.statsd.port!
        )
    )
)

baseMetricPath is a path that will be prepended to every metric sent via handler. client is a TCPStatsDClient or UDPStatsDClient instance.

Custom Handlers

To create custom handlers, conform to MetricsHandler class.