{"id":50499462,"url":"https://github.com/andrewssobral/dse","last_synced_at":"2026-06-02T10:03:09.293Z","repository":{"id":350757372,"uuid":"1208143004","full_name":"andrewssobral/dse","owner":"andrewssobral","description":"Single-process distributed system emulator with deterministic scheduling, fault injection, and trace-driven debugging in C++20.","archived":false,"fork":false,"pushed_at":"2026-04-11T22:46:56.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T00:28:03.534Z","etag":null,"topics":["consensus","cpp20","deterministic-simulation","distributed-systems","emulator","event-driven","fault-injection","leader-election","network-partition","simulation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewssobral.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T21:57:26.000Z","updated_at":"2026-04-11T22:47:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andrewssobral/dse","commit_stats":null,"previous_names":["andrewssobral/dse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/andrewssobral/dse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewssobral%2Fdse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewssobral%2Fdse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewssobral%2Fdse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewssobral%2Fdse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewssobral","download_url":"https://codeload.github.com/andrewssobral/dse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewssobral%2Fdse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33816488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["consensus","cpp20","deterministic-simulation","distributed-systems","emulator","event-driven","fault-injection","leader-election","network-partition","simulation"],"created_at":"2026-06-02T10:03:08.226Z","updated_at":"2026-06-02T10:03:09.278Z","avatar_url":"https://github.com/andrewssobral.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DSE\n\nDistributed System Emulator in a Single Process.\n\n`dse` is a small C++20 project that emulates a distributed system inside one process with a deterministic event loop. It is designed as a fast experimentation environment for leader election, fault injection, network partitions, and trace-driven debugging.\n\n## What It Does\n\n- Runs multiple logical nodes in one process.\n- Uses a virtual clock and an event queue instead of real sockets or threads.\n- Simulates:\n  - message latency\n  - message drops\n  - node crash and recovery\n  - network partitions and heal\n- Exports a readable execution trace.\n- Includes a toy leader election protocol for demonstration.\n\n## Current Scope\n\nThis is a first MVP, not a full consensus implementation.\n\nCurrent characteristics:\n- single-process\n- single-threaded runtime\n- deterministic scheduling from a fixed seed\n- toy leader election protocol with heartbeats and vote requests\n- configurable network behavior for latency, drops, partitions, and reorder/FIFO delivery\n- simple CLI demo runner with input validation\n- 13 smoke/regression tests covering convergence, determinism, drops, reorder semantics, vote safety, and `run_until_idle` behavior\n\nNot implemented yet:\n- real coroutines for nodes\n- real network transport\n- JSON trace export\n- GUI timeline or visualization\n- full Raft or Paxos semantics\n\n## Project Layout\n\n```text\n./dse\n|-- CMakeLists.txt\n|-- README.md\n|-- include/dse\n|   |-- leader_election.hpp\n|   |-- sim.hpp\n|   |-- trace.hpp\n|   `-- types.hpp\n|-- src\n|   |-- leader_election.cpp\n|   `-- sim.cpp\n|-- app\n|   `-- main.cpp\n`-- tests\n    `-- smoke.cpp\n```\n\n## Core Concepts\n\n### Runtime\n\nThe runtime is centered around:\n- a virtual clock (`Tick`)\n- an ordered event queue\n- explicit delivery/timer/action events\n- a seeded random generator for repeatable latency and drop behavior\n\nThe system advances only when events are processed. This makes runs reproducible as long as the seed and scenario are the same.\n\nThe runtime exposes two execution styles:\n- `run_for(delta)` advances simulated time by a fixed amount\n- `run_until_idle(max_ticks = 10'000)` stops when the queue drains and returns `true`, or returns `false` if the safety cap is hit first\n\n### Nodes\n\nEach node is represented by a `Node` implementation. The current demo uses `LeaderElectionNode`, which tracks:\n- role (`follower`, `candidate`, `leader`)\n- current term\n- voted peer\n- known leader\n- timer tokens to invalidate stale timers\n\nOn crash/recover, the node preserves its current term and remembered vote for that term. The stored vote is cleared only when a higher term is observed.\n\n### Network Model\n\nThe network model supports:\n- bounded random latency\n- probabilistic message drop\n- link blocking through partitions\n- optional reordering control:\n  - `reorder = true`: random latency between `min_latency` and `max_latency`\n  - `reorder = false`: fixed `min_latency`, preserving FIFO delivery order for messages sent at the same simulated time\n\nThere is no real I/O. All communication becomes scheduled delivery events.\n\n## Build\n\nFrom `./dse`:\n\n```bash\ncmake -S . -B build\ncmake --build build\n```\n\n## Test\n\n```bash\nctest --test-dir build --output-on-failure\n```\n\nYou can also run the smoke binary directly:\n\n```bash\n./build/dse_smoke\n```\n\nCurrent coverage includes:\n- normal, crash/recover, and partition/heal convergence\n- replay determinism across repeated runs with the same seed\n- convergence across multiple seeds\n- convergence with probabilistic drops\n- FIFO delivery behavior when `reorder` is disabled\n- vote safety across crash/recover within the same term\n- both success and safety-cap paths of `run_until_idle`\n\n## Run\n\nBasic demo:\n\n```bash\n./build/dse_demo\n```\n\nCommon variants:\n\n```bash\n./build/dse_demo --scenario normal\n./build/dse_demo --scenario crash\n./build/dse_demo --scenario partition\n./build/dse_demo --scenario partition --ticks 120 --no-trace\n./build/dse_demo --seed 123 --nodes 5 --ticks 180\n```\n\nSupported flags:\n- `--seed \u003cn\u003e`\n- `--nodes \u003cn\u003e`\n- `--ticks \u003cn\u003e`\n- `--scenario \u003cnormal|crash|partition\u003e`\n- `--no-trace`\n\nInvalid numeric values, unknown options, unknown scenarios, and `--nodes 0` are rejected with a non-zero exit status.\n\n## Example Scenarios\n\n### `normal`\n\nStarts a cluster and lets the election stabilize.\n\nExpected result:\n- one node becomes leader\n- the others converge as followers\n\n### `crash`\n\nCrashes one node and later recovers it.\n\nExpected result:\n- the cluster keeps operating\n- leadership converges again after the failure window\n\n### `partition`\n\nSplits the cluster into two groups and later heals the network.\n\nExpected result:\n- multiple elections may happen during the partition\n- after heal, the system should converge back to one leader\n\n## Design Notes\n\n- The runtime is intentionally explicit and simple.\n- Timer tokens are used to ignore stale scheduled timers after state changes.\n- `run_until_idle` has a safety cap so protocol loops with recurring timers do not block forever.\n- The protocol is meant to demonstrate scheduler behavior and fault injection, not to claim consensus correctness.\n- The most important property right now is deterministic replay of a scenario.\n\n## Next Steps\n\nGood follow-up work:\n- add JSON trace export\n- add richer metrics\n- add timeline visualization\n- replace the toy protocol with a stronger protocol\n- introduce coroutine-based node execution\n- add property-based or fuzz-style scenario tests\n\n## Why This Project Exists\n\nThis project is meant to become a practical lab for distributed systems experiments:\n- build fast scenarios\n- replay failures deterministically\n- inspect traces\n- iterate on protocol ideas without deploying a real cluster\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewssobral%2Fdse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewssobral%2Fdse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewssobral%2Fdse/lists"}