{"id":50708048,"url":"https://github.com/posit-dev/chaosfs","last_synced_at":"2026-06-09T13:01:57.757Z","repository":{"id":359297042,"uuid":"1172776894","full_name":"posit-dev/chaosfs","owner":"posit-dev","description":"An eventually consistent FUSE filesystem that mounts multiple client views over the same backing store to reproduce multi-host shared-storage consistency anomalies (stale reads, delayed visibility, write propagation lag) typical of read-write NFS setups.","archived":false,"fork":false,"pushed_at":"2026-05-21T07:51:19.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T14:55:37.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/posit-dev.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-03-04T17:17:24.000Z","updated_at":"2026-05-21T12:53:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/posit-dev/chaosfs","commit_stats":null,"previous_names":["posit-dev/chaosfs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/posit-dev/chaosfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchaosfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchaosfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchaosfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchaosfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posit-dev","download_url":"https://codeload.github.com/posit-dev/chaosfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchaosfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34107866,"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-09T02:00:06.510Z","response_time":63,"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":[],"created_at":"2026-06-09T13:01:57.536Z","updated_at":"2026-06-09T13:01:57.751Z","avatar_url":"https://github.com/posit-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChaosFS\n\nChaosFS is a local FUSE harness for reproducing NFS-style consistency issues without using production systems. It lets you mount multiple ChaosFS clients over one backing directory and inject delayed visibility, stale metadata/listing views, and operation failures so concurrent read/write workflows can be tested under realistic race conditions.\n\n## Project layout\n\n- `src/chaosfs/`: installable ChaosFS package that exposes `ChaosFS` and the `chaosfs` CLI.\n- `demo/`: optional walkthroughs and validators that run against mounted ChaosFS clients.\n- `tests/`: regression tests for the ChaosFS implementation.\n\n## Prerequisites\n\n- Python 3.10 or newer.\n- [`fusepy`](https://github.com/fusepy/fusepy) installed (the package metadata already depends on it).\n- A FUSE implementation available for unprivileged mounts (`fusermount`, `fusermount3`, or `umount`).\n\n## Installation\n\nInstall from the repo root on any platform that needs ChaosFS:\n\n```bash\npip install -e .\n```\n\nThe installation exposes `chaosfs` as the primary user-facing command.\n\n## CLI usage\n\n`chaosfs mount \u003cbacking\u003e \u003cmountpoint\u003e` starts a FUSE client that surfaces a delayed, write-late, cache-incoherent view of `\u003cbacking\u003e` at `\u003cmountpoint\u003e`. The command reads sensible defaults for the chaos knobs from environment variables (see the *Chaos knobs* section) but lets you override them as flags.\nBy default, logs are written to the terminal; use `--log-file` or `--log-dir` to persist them.\n\n`chaosfs umount` can tear down a single mount point with `--mount \u003cpath\u003e` or sweep an entire directory tree with `--mount-base \u003cdir\u003e`.\n\n### Preparing backing and mount paths\n\nCreate the backing and mount directories before calling `chaosfs mount`. The command intentionally fails if:\n- the backing directory does not exist\n- the target mount directory does not exist\n- the target mount directory is not empty\n\nOnce you have a backing tree you care about, create one mountpoint per client:\n\n```bash\nBACKING_DIR=/tmp/chaosfs/backing\nMOUNT_BASE=/tmp/chaosfs/mnt\nLOG_DIR=/tmp/chaosfs/logs\n\nmkdir -p \"$BACKING_DIR\" \"$MOUNT_BASE\" \"$LOG_DIR\"\n\nchaosfs mount \"$BACKING_DIR\" \"$MOUNT_BASE/clientA\" \\\n  --client-id clientA --log-dir \"$LOG_DIR\" --background\nchaosfs mount \"$BACKING_DIR\" \"$MOUNT_BASE/clientB\" \\\n  --client-id clientB --log-dir \"$LOG_DIR\" --background\n```\n\nBoth mounts point at the same backing data. You can run as many clients as you like against a single backing directory (there is no requirement to create more than one mount point, single-client workloads are also valid).\n\nUse `--background` if you want the CLI command to return immediately; omit it when running one mount in a dedicated foreground terminal for debugging.\nWhen running in background without `--log-dir`/`--log-file`, `chaosfs` still runs but prints a warning because logs may not be visible.\nIn foreground mode, when the process exits, `chaosfs` performs a best-effort unmount of that mountpoint.\n\nTo unmount everything later:\n\n```bash\nchaosfs umount --mount-base \"$MOUNT_BASE\"\n```\n\nOr target a single mount:\n\n```bash\nchaosfs umount --mount \"$MOUNT_BASE/clientA\"\n```\n\n### Chaos knobs\n\n| Env var | Default | Description |\n| --- | --- | --- |\n| `CHAOSFS_META_TTL_MS` | `1500` | Metadata and directory listing TTL per client. |\n| `CHAOSFS_WRITE_DELAY_MS` | `800` | How long writes take to become globally visible. |\n| `CHAOSFS_RENAME_DELAY_MS` | `1200` | Delay for rename/directory visibility and cache invalidation. |\n| `CHAOSFS_DROP_PROB` | `0.0` | Probability that each operation fails with `EIO`. |\n| `CHAOSFS_SEED` | unset | Seed for deterministic randomness. |\n| `CHAOSFS_CLIENT_ID` | `client` | Namespace used for per-client caches. |\n\nYou can also provide these values as CLI flags (`--meta-ttl`, `--write-delay`, etc.) in milliseconds.\n\n## Using ChaosFS in tests\n\nChaosFS provides context managers that handle all the FUSE mounting boilerplate:\n\n```python\nfrom chaosfs import mount, dual_mount\n\ndef test_single_client(tmp_path):\n    backing = tmp_path / \"backing\"\n    mnt = tmp_path / \"mnt\"\n    backing.mkdir()\n    mnt.mkdir()\n\n    with mount(backing, mnt, client_id=\"c1\", meta_ttl=0.5) as mp:\n        (mp / \"hello.txt\").write_text(\"world\")\n    # automatically unmounted on exit\n\ndef test_writer_reader(tmp_path):\n    with dual_mount(tmp_path) as (writer, reader):\n        (writer / \"data.txt\").write_text(\"content\")\n        time.sleep(2.5)  # wait for reader TTL to expire\n        assert (reader / \"data.txt\").read_text() == \"content\"\n    # both mounts cleaned up\n```\n\n`mount()` takes the same chaos knobs as the CLI (in seconds, not milliseconds): `meta_ttl`, `write_delay`, `rename_delay`, `drop_prob`, `seed`, and `client_id`.\n\n`dual_mount(base_path)` creates `backing/`, `writer/`, and `reader/` subdirectories under `base_path` and mounts two ChaosFS instances — a writer with low delays and a reader with high metadata TTL — to simulate the common two-client NFS pattern.\n\n## Demos \u0026 use cases\n\nSee `demo/README.md` for the demo catalog, including a generic race visualizer and a concurrent-venv reproduction scenario.\nDemo scripts use `LOG_DIR` when provided.\n\n## Testing\n\n```bash\nruff format --check .\nruff check .\npython -m unittest tests/test_chaosfs.py\npython -m chaosfs.cli --help\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fchaosfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposit-dev%2Fchaosfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fchaosfs/lists"}