yojimbo Networking Library

The Yojimbo client operates as a state machine that projects the underlying netcode states. The state machine determines how a client moves between connection, disconnection, and error states.

Key State Values:

• CLIENT_STATE_ERROR (-1): A failure state. Negative values indicate failure.
• CLIENT_STATE_DISCONNECTED (0): The idle state. Zero indicates idle.
• CLIENT_STATE_CONNECTING (Positive): Progressing towards a connection.
• CLIENT_STATE_CONNECTED (Positive): Successfully connected.

Callers can use thin predicates like IsConnecting(), IsConnected(), IsDisconnected(), and ConnectionFailed() to check these states.

The Yojimbo 1.0 connection packet is the wire format for payloads carrying messages between client and server. It is designed to be extremely compact by assuming both ends have pre-agreed on the configuration.

Important Prerequisites:

• This format is not self-describing. Both reader and writer must agree in advance on numChannels, channel type, maxMessagesPerPacket, maxBlockSize, blockFragmentSize, disableBlocks, and the number of registered message types.
• This layer assumes netcode has already handled encryption, authentication, and transport.
• All primitives (e.g., serialize_int, serialize_bool) follow the serialize library standard.

You can obtain the latest source code by cloning the repository from GitHub.

git clone https://github.com/mas-bandwidth/yojimbo.git

To check which branches a change reaches in the deserialization sources, use the tools/fuzz_coverage.sh script. It builds a target with source-based coverage instrumentation and runs it against the committed corpus plus pseudo-random inputs, then prints an llvm-cov report.

tools/fuzz_coverage.sh <connection>

Use verify_standard.py to ensure the implementation's connection packet format matches the specification in STANDARD.md. This script decodes the existing fuzz corpus (fuzz/corpus/fuzz_connection) using only the rules defined in STANDARD.md and serialize/STANDARD.md. It checks for bit-level exhaustion, ensuring no bits are left over and no reads occur past the end of a packet, which validates that framing and message bodies are correctly implemented according to the spec.

python3 tools/conformance/verify_standard.py

To build yojimbo on macOS or Linux, ensure you have CMake (3.16 or newer) installed. By default, the build uses a bundled minimal version of libsodium.

For a standard debug build:

1. Configure the build directory.
2. Compile the project.

To create an optimized Release build, pass -DCMAKE_BUILD_TYPE=Release during the configuration step.

# Debug build
cmake -B build
cmake --build build -j

# Release build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

By default, yojimbo uses vendored copies of serialize, reliable, and netcode. To build against system-installed versions of these three libraries instead, use the -DYOJIMBO_SYSTEM_DEPS=ON flag.

Requirements:

• The dependencies must be installed where CMake can find them. Use -DCMAKE_PREFIX_PATH=/path/to/prefix if they are in a custom location.
• In this mode, the bundled libsodium is not used (the system netcode provides its own crypto).
• cmake --install will install the yojimbo headers and library.

Note: The test suite skips the embedded netcode and reliable self-test sections in this configuration because system libraries do not include those test hooks.

cmake -B build -DYOJIMBO_SYSTEM_DEPS=ON
cmake --build build -j
./bin/test
cmake --install build

You can control the client's state transitions using the following methods:

• Connect(): Moves the client from DISCONNECTED, ERROR, or CONNECTED to CONNECTING. If a connect token cannot be generated, the client moves directly to ERROR.
• Disconnect(): Moves the client from any state to DISCONNECTED.

Transition Rules:

• CONNECTING → CONNECTED: Occurs when the underlying netcode handshake completes.
• CONNECTING → ERROR: Occurs on handshake failure (e.g., token expired, invalid, connection denied, or timeouts).
• CONNECTED → DISCONNECTED: Occurs when the server closes the connection cleanly.
• CONNECTED → ERROR: Occurs on transport failure or timeout.

Note: ERROR is a terminal state. The client will not retry automatically; you must call Connect() to start a fresh attempt.

You can install yojimbo using the Conan package manager. The package is available on Conan Center and is maintained by the ConanCenterIndex community.

conan install --requires="yojimbo/[*]" --build=missing

To build the Docker image for the Yojimbo Matcher sample, navigate to the matcher directory and run the docker build command.

docker build --tag=matcher .