Cloudflare Foundations: A Comprehensive Rust Library for Building Robust, Scalable Services

[or1k]

Cloudflare announced the release of Foundations: a powerful Rust library for building distributed, production-grade systems. Initially developed as part of the Oxy proxy framework, Foundations has evolved into a versatile library designed to simplify the complexities of deploying and managing services at scale. This open-source project, now available on GitHub, empowers engineers to focus on core business logic rather than getting bogged down by intricate production operation setups.

Foundations address the challenges that emerge when transitioning from a simple local prototype to a full-fledged service in a global production environment. The key differentiators include observability, configuration, and security. Foundations, rooted in Cloudflare's experience in developing numerous services, serve as a comprehensive solution to these critical distinctions.

The key principles of the development of Foundations are:

• High Modularity: Foundations is designed with high modularity, allowing teams to adopt individual components at their own pace, facilitating a smooth transition for existing services.

• API Ergonomics: Prioritizing user-friendly interactions, Foundations leverages Rust's procedural macros to offer an intuitive and well-documented API, minimizing friction in usage.

• Simplified Setup and Configuration: Foundations aims to be 'plug and play,' providing essential functions that work immediately while offering adjustable settings for fine-tuning. The focus on ease of setup is tailored for specific, production-tested environments.

The components that Foundations offers are necessary for most service needs:

• Logging: Records arbitrary textual information, aiding in documenting operational errors.
• Tracing: Offers detailed timing breakdowns of service components for identifying performance bottlenecks.
• Metrics: Provides quantitative data points crucial for monitoring the overall health and performance of the system.

Foundations' logging API builds upon tokio/tracing and slog, introducing enhancements to handle hierarchical logging contextual information seamlessly. Leveraging future instrumentation machinery, Foundations enables implicit passing of the current logger for each request, streamlining the process and preventing obstruction of business logic.

Tracing in Foundations is similar to tokio/tracing but differs for:

• Simplified API: Foundations streamlines the setup process for tracing, adopting a minimalistic approach.
• Enhanced Trace Sampling Flexibility: Allows selective override of sampling ratios in specific code branches for detailed performance investigations.
• Distributed Trace Stitching: Supports integration of trace data from multiple services, contributing to a comprehensive view of the entire pipeline.
• Trace Forking Capability: Addresses challenges in long-lasting connections with numerous multiplexed requests, simplifying analysis and improving performance.

For metrics, Foundations incorporates the official Prometheus Rust client library. It offers enhancements for ease of use and introduces a procedural macro for a simplified definition of new metrics with typed labels. An example is the following snippet:

use foundations::telemetry::metrics::{metrics, Counter, Gauge};
use std::sync::Arc;

#[metrics]
pub(crate) mod http_server {
    /// Number of active client connections.
    pub fn active_connections(endpoint_name: &Arc<String>) -> Gauge;

    /// Number of failed client connections.
    pub fn failed_connections_total(endpoint_name: &Arc<String>) -> Counter;

    /// Number of HTTP requests.
    pub fn requests_total(endpoint_name: &Arc<String>) -> Counter;

    /// Number of failed requests.
    pub fn requests_failed_total(endpoint_name: &Arc<String>, status_code: u16) -> Counter;
}

The memory profiling is implemented enabling jemalloc memory allocation, with a straightforward and safe Rust API for accessible integration. Foundations is also equipped with a built-in, customizable telemetry server endpoint. This server automates functions such as health checks, metric collection, and memory profiling.

In Foundations, security is assured by robust and ergonomic API for seccomp, a Linux kernel feature for syscall sandboxing, adding a layer of security against threats. Foundations provides a simple way to allow syscalls, also allowing compositions of multiple lists:

use foundations::security::common_syscall_allow_lists::{ASYNC, NET_SOCKET_API, SERVICE_BASICS};
use foundations::security::{allow_list, enable_syscall_sandboxing, ViolationAction};

allow_list! {
    static ALLOWED = [
        ..SERVICE_BASICS,
        ..ASYNC,
        ..NET_SOCKET_API
    ]
}
enable_syscall_sandboxing(ViolationAction::KillProcess, &ALLOWED)

The Cloudflare team says:

Foundations has been instrumental in reducing our development friction

and they believe can be useful to the community, this is why they open sourced the Foundations library.