micro_traffic_sim gRPC server

This crate exposes the gRPC API for the micro traffic simulation via cellular automata. It can be used as a Rust library (crates.io), run as a server binary, and distributed via Docker. Go and Python client stubs can be generated from the same protos.

Table of Contents

• Prerequisites for building from source
• Build and run (binary)
• Docker
  • Build and run locally
  • Pre-built image from registry
• Pre-built binaries from GitHub releases page
• Usage
  • Run server locally
  • Rust client to micro_traffic_sim gRPC server
  • Golang client to micro_traffic_sim gRPC server
  • Python client to micro_traffic_sim gRPC server
• Client code generation
  • Golang
  • Python

Prerequisites for building from source

• Rust 1.91.0 which is tested with 2024 edition in my case
• protoc available on PATH
• Optional: docker for container builds

Build and run (binary)

• Debug build (library mode):
  • make build
• Run the gRPC server:
  • make run-server
• Release binary:
  • make build-release
  • Binary path: target/release/micro_traffic_sim

Notes:

• The server is behind a Cargo feature flag server. Commands above enable it when needed. Those are basically:

cargo build --release --features server

• Default listen address is 0.0.0.0:50051. Override with MT_SIM_ADDR environment variable (e.g., MT_SIM_ADDR=0.0.0.0:25250).
• Verbose levels are controlled by two environment variables:
  • MT_SIM_VERBOSE — per-session simulation logging (steps, conflicts, movement): 0 = None (default), 1 = Main, 2 = Additional.
  • MT_SIM_SERVICE_VERBOSE — storage-level logging (session create/expire): 0 = None, 1 = Main (default), 2 = Additional.

Docker

There are two supported paths: build locally with Dockerfile, or pull from registry.

Build and run locally

• Build
  • make docker-build IMAGE=micro-traffic-sim/server TAG=latest
• Run
  • make docker-run IMAGE=micro-traffic-sim/server TAG=latest
  • This maps host port 50051 -> container port 50051.

The Docker image is built with a multi-stage process (Rust builder + slim runtime). It compiles with the server feature enabled.

Pre-built image from registry

The server image is available from both Docker Hub and GitHub Container Registry.

Docker Hub:

docker pull dimahkiin/micro-traffic-sim-server:latest
docker run --rm -it -p 50051:50051 -e MT_SIM_ADDR=0.0.0.0:50051 dimahkiin/micro-traffic-sim-server:latest

GitHub Container Registry:

docker pull ghcr.io/lddl/micro-traffic-sim-server:latest
docker run --rm -it -p 50051:50051 -e MT_SIM_ADDR=0.0.0.0:50051 ghcr.io/lddl/micro-traffic-sim-server:latest

Replace latest with a specific version tag (e.g., 0.1.0) for reproducible deployments.

Pre-built binaries from GitHub releases page

Download pre-built binaries from the GitHub Releases page.

Available builds:

• Linux (amd64): micro-traffic-sim-server-{version}-linux-amd64.tar.gz
• Windows (amd64): micro-traffic-sim-server-{version}-windows-amd64.zip

Linux example:

# Download and extract
wget https://github.com/LdDl/micro_traffic_sim_grpc/releases/download/v0.1.0/micro-traffic-sim-server-0.1.0-linux-amd64.tar.gz
tar -xzf micro-traffic-sim-server-0.1.0-linux-amd64.tar.gz

# Run the server
./micro_traffic_sim

Windows example:

# Extract the zip file, then run:
.\micro_traffic_sim.exe

The server listens on 0.0.0.0:50051 by default. Override with MT_SIM_ADDR environment variable (e.g., MT_SIM_ADDR=0.0.0.0:25250). Verbose levels: MT_SIM_VERBOSE for simulation logging, MT_SIM_SERVICE_VERBOSE for storage logging (0/1/2).

Usage

Run server locally

E.g. we can run the server in debug mode with:

cargo run --features server --bin micro_traffic_sim

To use a custom address and verbose levels:

MT_SIM_ADDR=0.0.0.0:25250 MT_SIM_VERBOSE=2 MT_SIM_SERVICE_VERBOSE=1 cargo run --features server --bin micro_traffic_sim

Rust client to micro_traffic_sim gRPC server

Add the crate to your project: cargo add micro_traffic_sim

• API Documentation (docs.rs)
• Example details

export MT_SIM_ADDR=127.0.1.0:50051
cargo run --example rust_client   

Golang client to micro_traffic_sim gRPC server

Here more details: clients/go/README.md

export MT_SIM_ADDR=127.0.1.0:50051
# from repository root
cd ./clients/go
go run ./cmd/example/main.go

Python client to micro_traffic_sim gRPC server

Here more details: clients/python/README.md

export MT_SIM_ADDR=127.0.1.0:50051
# from repository root
cd ./clients/python
source .venv/bin/activate
python examples/main.py

Client code generation

This section describes how I've used to generate client code for different languages from the proto files.

Golang

Client code generation for Golang is done via scripts/gen_go.sh. It requires protoc and protoc-gen-go to be installed and available on PATH.

chmod +x ./scripts/gen_go.sh
./scripts/gen_go.sh clients/go
cd ./clients/go
go mod init github.com/LdDl/micro_traffic_sim_grpc/clients/go
go mod tidy
cd -

Python

Client code generation for Python is done via scripts/gen_python.sh. The script automatically creates a virtual environment and installs all dependencies.

chmod +x ./scripts/gen_python.sh
./scripts/gen_python.sh

The script:

1. Creates .venv in clients/python/ (if not exists)
2. Installs dependencies from requirements.txt
3. Generates *_pb2.py, *_pb2.pyi (type stubs), and *_pb2_grpc.py
4. Installs the micro-traffic-sim package in editable mode