{"id":20388388,"url":"https://github.com/wetware/matrix","last_synced_at":"2026-04-28T18:06:07.737Z","repository":{"id":47174866,"uuid":"372291965","full_name":"wetware/matrix","owner":"wetware","description":"In-process cluster simulation for libp2p","archived":false,"fork":false,"pushed_at":"2021-11-09T15:52:53.000Z","size":371,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-15T09:00:29.774Z","etag":null,"topics":["benchmarks","casm","in-process","inproc","libp2p","simulation","simulations","traffic-shaping","unit-testing","wetware","ww"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wetware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-30T18:49:44.000Z","updated_at":"2024-03-29T08:45:06.000Z","dependencies_parsed_at":"2022-09-26T19:40:23.836Z","dependency_job_id":null,"html_url":"https://github.com/wetware/matrix","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wetware%2Fmatrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wetware%2Fmatrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wetware%2Fmatrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wetware%2Fmatrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wetware","download_url":"https://codeload.github.com/wetware/matrix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241940529,"owners_count":20045878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["benchmarks","casm","in-process","inproc","libp2p","simulation","simulations","traffic-shaping","unit-testing","wetware","ww"],"created_at":"2024-11-15T03:09:38.602Z","updated_at":"2026-04-28T18:06:02.690Z","avatar_url":"https://github.com/wetware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matrix\n\n[![GoDoc](https://godoc.org/github.com/wetware/matrix?status.svg)](https://godoc.org/github.com/wetware/matrix)\n[![](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](https://libp2p.io/)\n[![Go](https://github.com/wetware/matrix/actions/workflows/go.yml/badge.svg)](https://github.com/wetware/matrix/actions/workflows/go.yml)\n\nIn-process cluster simulation for libp2p.\n\nMatrix is a library for **in-process** testing, benchmarking and simulating [libp2p](https://github.com/libp2p/go-libp2p) applicaitons in Go.  It is a simple alternative to [Testground](https://github.com/testground/testground) for cases where network IO is not needed or desired.\n\n## Installation\n\n```bash\ngo get -u github.com/wetware/matrix\n```\n\n## Motivation\n\n**TL;DR:**  Testground is too complex for 99% of unit tests, benchmarks and exploratory simulations.\n\n### Testground\n\n[Testground](https://github.com/testground/testground) is a platform for testing, benchmarking, and simulating distributed and p2p systems at scale. It's designed to be multi-lingual and runtime-agnostic, scaling gracefully from 2 to 10k instances, only when needed.\n\nTestground is ideal for complex workloads, such as:\n\n- Compatibility testing between different versions of a P2P application\n- Verifying interoperability between different language implementations of a library\n- Simulations that require real network IO.\n\nThe price to pay for Testground's minimal assumptions and maximal realism come with some limitations and additional complexities.  Test plans:\n\n- require configuration management (`.env.toml`, `manifest.toml`)\n- require a specialized testing environment (Tesground daemon, Redis, Docker, etc.)\n- write data to the local filesystem\n- cannot be embedded in unit tests (no support for `go test`)\n\nTaken together, these characteristics can make Testground overkill for simple unit-tests and benchmarks, especially if these are integrated into your local development workflow (or if you expect contributors to run your tests).  In this common case, an in-process simulation suffices.\n\n### Matrix\n\nMatrix is a library for writing unit-tests, benchmarks and exploratory simulations for libp2p.  Contrary to Testground, everything happens in a single process, without using the network.\n\n#### Goals:\n- Drop-in compatibility with PL stack\n- In-process.  No external services / sidecar processes / environmental dependencies\n- Support for benchmarking, unit-testing and runtime analysis\n- Traffic shaping\n- Stats collecting / offline analysis\n\n#### Non-Goals\n- Simulated time\n- Multilingual Support\n\nMatrix runs your code using actual libp2p code.  It configures [hosts](https://pkg.go.dev/github.com/libp2p/go-libp2p-core/host#Host) to use an [in-process transport](https://godoc.org/github.com/lthibault/go-libp2p-inproc-transport), which allows them to communicate without the network.  **Everything else is exactly the same.**\n\nAdditionally, Matrix provides some utilities to facilitate test setup.  For example, the [`netsim`](pkg.go.dev/github.com/wetware/matrix/pkg/netsim) package provides a specialized [`discovery.Discovery`](https://pkg.go.dev/github.com/libp2p/go-libp2p-core/discovery#Discovery) implementation that allows you to arrange hosts in a specific topology (e.g. a ring).\n\nBut there's more!  Just like Testground, Matrix provides support for sophisticated traffic shaping.\n\n## Usage\n\nThe following example can be found under `examples/basic`.  See the examples directory for more.\n\n```go\nimport (\n    \"context\"\n\n    mx \"github.com/wetware/matrix/pkg\"\n)\n\nconst ns   = \"matrix.test\"\n\n\nctx, cancel := context.WithCancel(context.Background())\ndefer cancel()\n\nsim := mx.New(ctx)\n\n/*\n\n    Most Matrix functions have a corresponding Must* function\n    that panics instead of returning an error.  This provides\n    an (optional) way of reducing error-checking boilerplate.\n\n*/\nh0 := sim.MustHost(ctx)\nh1 := sim.MustHost(ctx)\n\n/*\n    Matrix provides the Operations API, which allows developers\n    to compose operations on collections of hosts.\n\n    Here, we're using the 'Topology' operation to arrange our\n    hosts in a ring configuration.  See examples/selectors to\n    see how operations can be chained.\n\n    Note that the Operations API is orthogonal to simulation.\n    You do not have to use operations if you don't like them.\n*/\nmx.Topology(sim, netsim.SelectRing{}, ns).\n\t\tMustArgs(ctx, h0, h1)\n\n/*\n    h0 and h1 are now connected to each other!\n*/\n```\n\n## Team\n\n### Core Team\n\n- [@lthibault](https://github.com/lthibault) ★\n- [@aratz-lasa](https://github.com/aratz-lasa)\n\n★ Project Lead\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwetware%2Fmatrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwetware%2Fmatrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwetware%2Fmatrix/lists"}