What is Mononoke?

Introduction

Mononoke is a scalable source control server designed to handle massive repositories with millions of files, thousands of commits per day, and hundreds of thousands of branches. It serves as the server-side backend for Meta's source control infrastructure.

As a core component of the Sapling source control ecosystem, Mononoke works together with EdenFS (a virtual filesystem) and the Sapling CLI to provide source control operations at large scale.

The Sapling Ecosystem

Mononoke is one piece of a source control solution:

• Sapling CLI - The command-line interface that developers use to interact with source control. Originally based on Mercurial, Sapling provides version control operations.

• EdenFS - A virtual filesystem for massive repositories. Instead of materializing every file in a repository, EdenFS fetches files on-demand from Mononoke as they're accessed.

• Mononoke Server - The server-side component that stores repository history, handles commits, manages branches (called bookmarks), and serves data to clients.

Together, these components allow developers to work with repositories containing millions of files.

Why Mononoke Exists

Traditional version control systems like Git and Mercurial were designed for smaller repositories. While they work well for projects with thousands or tens of thousands of files, they face challenges when repositories grow to millions of files and experience thousands of commits daily.

Mononoke addresses these scalability challenges:

Scale in Multiple Dimensions

• Handles millions of files
• Supports thousands of commits per hour
• Manages hundreds of thousands of active branches
• Stores files ranging from small configuration files to multi-gigabyte binaries

High Availability

• Designed as a distributed service
• Uses redundant storage backends
• Can continue operating when individual components fail

Multi-VCS Support

• Supports Sapling clients
• Serves Git clients using the standard Git protocol
• Maintains a single source of truth across different version control systems

Architectural Characteristics

• Separates write operations from read operations
• Computes expensive indexes asynchronously
• Uses multi-level caching
• Designed for horizontal scaling

What Mononoke Does

At its core, Mononoke is a source control server. When you push a commit using Sapling or Git, or when EdenFS needs to fetch file contents, they communicate with Mononoke. Mononoke handles the following operations:

Repository Operations

• Accepting new commits from developers
• Serving file contents and commit history to clients
• Managing branches (bookmarks) and tags
• Enforcing pre-commit hooks and policies

Data Storage and Retrieval

• Storing commit metadata and file contents in a distributed blobstore
• Maintaining mappings between different version control formats
• Managing repository state like branches and phases
• Computing and caching derived data like manifests and file history

Advanced Features

• Pushrebase - Server-side rebasing that maintains linear history without requiring developers to manually rebase
• Cross-repository sync - Automatically synchronizing commits between different repositories
• Commit Cloud - Sharing uncommitted work across different machines
• Hooks - Running automated checks and validations on every commit

Deployment Scenarios

Mononoke is deployed as a distributed service:

Server Components

• Multiple stateless server instances handle client requests via HTTP
• Microservices handle specialized operations like landing commits or computing derived data
• Background jobs perform maintenance tasks like validation and healing

Storage Backends

• Immutable blob storage (using systems like Manifold, S3, or SQL databases) for commits and files
• SQL databases for mutable state like bookmarks and mappings
• Multi-level caching (in-memory and shared caches) for performance

Client Types

• Sapling CLI users pushing and pulling commits
• EdenFS instances fetching files on-demand
• Git clients using standard Git protocols
• Programmatic clients accessing data via Thrift APIs

This distributed architecture allows Mononoke to scale horizontally—adding more servers increases capacity without architectural changes.

A Brief History

Mononoke's evolution reflects changing needs in source control:

The Mercurial Era Mononoke was originally designed as a scalable backend for Mercurial, which served as Meta's primary version control system. Early Mononoke focused on supporting Mercurial clients and the Mercurial data model while introducing the Bonsai format.

The Sapling Transition As Mercurial evolved into Sapling, Mononoke evolved alongside it. The server added support for EdenAPI (now called SLAPI), an HTTP-based protocol that replaced legacy wire protocols.

Multi-VCS Support Today, Mononoke is VCS-agnostic. Rather than being tied to a specific version control system's data model, Mononoke uses Bonsai—a canonical, VCS-independent format for representing commits. This allows Mononoke to serve Git clients as well as Sapling clients, converting between formats as needed while maintaining a single source of truth.

Written in Rust Mononoke is implemented primarily in Rust, providing memory safety and concurrency support.

Design Principles

Several principles guide Mononoke's design:

Immutability Most data in Mononoke is immutable and content-addressed. Once a commit or file is stored, it never changes. This allows caching, concurrent access, and data distribution across multiple storage backends.

Separation of Concerns Mononoke distinguishes between data that must be stored (commits and files) and data that can be computed (indexes and caches). This separation allows the write path to avoid computing expensive indexes synchronously, while read operations use pre-computed derived data.

Composability Rather than a monolithic repository object, Mononoke uses facets—modular components that can be composed together. Bookmark support is provided by the bookmarks facet, while commit graph traversal is handled by the commit graph facet.

Horizontal Scaling Components are designed to scale horizontally. Capacity can be increased by adding more server instances. Storage capacity can be expanded by adding more blobstore backends.

What's Next?

This document provides a high-level introduction to what Mononoke is and why it exists. To dive deeper:

• Key Concepts - Understand Bonsai, facets, derived data, and other core ideas
• Architecture Overview - Learn how Mononoke's components fit together
• Navigating the Codebase - Find your way around Mononoke's ~55-60 directories

This documentation is intended for developers working on Mononoke or seeking to understand how it fits into the Sapling ecosystem.