{"id":13632588,"url":"https://github.com/memc-rs/memc-rs","last_synced_at":"2026-04-12T20:19:49.125Z","repository":{"id":45253686,"uuid":"434377167","full_name":"memc-rs/memc-rs","owner":"memc-rs","description":" A general-purpose distributed memory cache system compatible with Memcached","archived":false,"fork":false,"pushed_at":"2025-05-04T19:20:19.000Z","size":691,"stargazers_count":314,"open_issues_count":1,"forks_count":23,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-04T20:28:27.140Z","etag":null,"topics":["key-value-store","memcached","rust","rustlang"],"latest_commit_sha":null,"homepage":"https://memc.rs","language":"Rust","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/memc-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"Code_of_Conduct.md","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}},"created_at":"2021-12-02T21:15:47.000Z","updated_at":"2025-05-04T19:20:22.000Z","dependencies_parsed_at":"2024-03-01T21:31:16.881Z","dependency_job_id":"b3d0b043-e4d2-40f1-a792-69399b21f868","html_url":"https://github.com/memc-rs/memc-rs","commit_stats":{"total_commits":379,"total_committers":3,"mean_commits":"126.33333333333333","dds":0.00527704485488123,"last_synced_commit":"1a4e015eddb82ac813870ea93f2eb065dfc62dd8"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memc-rs%2Fmemc-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memc-rs%2Fmemc-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memc-rs%2Fmemc-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memc-rs%2Fmemc-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/memc-rs","download_url":"https://codeload.github.com/memc-rs/memc-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"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":["key-value-store","memcached","rust","rustlang"],"created_at":"2024-08-01T22:03:07.805Z","updated_at":"2026-04-12T20:19:49.118Z","avatar_url":"https://github.com/memc-rs.png","language":"Rust","funding_links":[],"categories":["Rust","C"],"sub_categories":[],"readme":"# memcrsd memcached server implementation in Rust\n\nmemcrsd is a key value store implementation in Rust. It is compatible with binary protocol of memcached server.\n\n## Changelog (since memcrsd-0.0.1k)\n\n**Important:** Configuration options for Moka and DashMap store engines are now separated. Options like `--max-capacity` and `--eviction-policy` apply only to Moka, while `--memory-limit` applies only to DashMap. This makes configuration clearer and prevents confusion when switching between store engines.\n\n## Supported features and compatibility\n\nTo check compatibility with memcached server implementation memcrsd project\nis using [memcapable](https://awesomized.github.io/libmemcached/bin/memcapable.html) tool from [libmemcached-awesome library](https://github.com/awesomized/libmemcached)\n\nHere is a capability status for memcrsd:\n\n```sh\ndocker run --rm --network host memcrs/memcached-awesome:latest\nHostname was provided.127.0.0.1\nbinary noop                             [pass]\nbinary quit                             [pass]\nbinary quitq                            [pass]\nbinary set                              [pass]\nbinary setq                             [pass]\nbinary flush                            [pass]\nbinary flushq                           [pass]\nbinary add                              [pass]\nbinary addq                             [pass]\nbinary replace                          [pass]\nbinary replaceq                         [pass]\nbinary delete                           [pass]\nbinary deleteq                          [pass]\nbinary get                              [pass]\nbinary getq                             [pass]\nbinary getk                             [pass]\nbinary getkq                            [pass]\nbinary incr                             [pass]\nbinary incrq                            [pass]\nbinary decr                             [pass]\nbinary decrq                            [pass]\nbinary version                          [pass]\nbinary append                           [pass]\nbinary appendq                          [pass]\nbinary prepend                          [pass]\nbinary prependq                         [pass]\nbinary stat                             [pass]\nAll tests passed\n```\n\nHere is a memcached integration tests output:\n\n```sh\nok 1 - start_server\nok 2 - binary_noop\nok 3 - binary_set\nok 4 - binary_setq\nok 5 - binary_add\nok 6 - binary_addq\nok 7 - binary_replace\nok 8 - binary_replaceq\nok 9 - binary_delete\nok 10 - binary_deleteq\nok 11 - binary_get\nok 12 - binary_getq\nok 13 - binary_getk\nok 14 - binary_getkq\nok 15 - binary_incr\nok 16 - binary_incrq\nok 17 - binary_decr\nok 18 - binary_decrq\nok 19 - binary_version\nok 20 - binary_flush\nok 21 - binary_flushq\nok 22 - binary_append\nok 23 - binary_appendq\nok 24 - binary_prepend\nok 25 - binary_prependq\nok 26 - binary_illegal\nok 27 - binary_pipeline_hickup\nok 28 - stop_server\n```\n\n## Bug reports\n\nFeel free to use the issue tracker on github.\n\n**If you are reporting a security bug** please contact a maintainer privately.\nWe follow responsible disclosure: we handle reports privately, prepare a\npatch, allow notifications to vendor lists. Then we push a fix release and your\nbug can be posted publicly with credit in our release notes and commit\nhistory.\n\n## Website\n\n* [https://memc.rs/](https://memc.rs/)\n\n## Running\n\n`memcrsd` is configured via command-line options. Most options have sensible defaults; below are the primary flags and their meanings (see the `--help` output for the full list).\n\n* `-p, --port \u003cPORT\u003e`: TCP port the server will bind to for incoming connections. Default: `11211`.\n\n* `-c, --connection-limit \u003cCONNECTION-LIMIT\u003e`: maximum number of simultaneous client connections allowed. Default: `1024`.\n\n* `-b, --backlog-limit \u003cLISTEN-BACKLOG\u003e`: backlog queue size for pending TCP connections. Default: `1024`.\n\n* `-i, --item-size-limit \u003cMAX-ITEM-SIZE\u003e`: maximum allowed size for a single item (between 1KiB and 1024MiB). Default: `1MiB`.\n\n* `-t, --threads \u003cTHREADS\u003e`: number of worker threads (defaults to number of CPU cores). Default: `8`.\n\n* `-v, --verbose...`: increase log verbosity (can be repeated).\n\n* `-l, --listen-address \u003cLISTEN-ADDRESS\u003e`: IP address or interface the server will bind to. Default: `127.0.0.1`.\n\n* `-r, --runtime-type \u003cRUNTIME-TYPE\u003e`: execution runtime: `current-thread` or `multi-thread`.\n\n  Possible values:\n  - `current-thread`: every thread will create its own runtime which will handle work without thread switching\n  - `multi-thread`:   work stealing threadpool runtime\n\n  Default: `current-thread`.\n\n* `--cpu-no-pin`: do not pin worker threads to cores (aplicable only for `current-thread` runtime, ignored in `multi-thread`).\n\n* `-s, --store-engine \u003cSTORE-ENGINE\u003e`: which underlying storage engine to use. Available options:\n\n  - `dash-map` – use the DashMap-based memory store\n  - `moka`     – use the Moka-based memory store (default)\n\n  Default: `moka`.\n\n* `--max-capacity \u003cCAPACITY\u003e`: maximum Moka cache capacity (key-\u003evalue pairs). Default: `1048576`.\n\n* `--eviction-policy \u003cEVICTION-POLICY\u003e`: eviction policy to use.\n\n  Possible values:\n  - `tiny-lfu`: tiny LFU\n  - `lru`: least recently used (default)\n\n  Default: `least-recently-used`.\n\n* `--memory-limit \u003cMEMORY-LIMIT\u003e`: memory limit in megabytes. Default: `64MiB`.\n\n* `-h, --help`: Print help (see a summary with '-h').\n\n* `-V, --version`: Print version.\n\nNotes:\n\n* Size values accept suffixes (examples: `1MiB`, `10k`).\n* Some defaults (e.g. thread count or OS limits on connections) may be influenced by the host system.\n* `--max-capacity` and `--eviction-policy` are only applicable when `--store-engine` is set to `moka`. When using `dash-map`, these options will cause an error.\n* `--memory-limit` is only applicable when `--store-engine` is set to `dash-map` (it controls memory usage in megabytes). When using `moka`, control cache size with `--max-capacity`; `--memory-limit` will cause an error for `moka`.\n\n## Docker image\n\nDocker image is available at docker hub: [https://hub.docker.com/r/memcrs/memc-rs](https://hub.docker.com/r/memcrs/memc-rs)\n\n### Building docker image\n\nDocker image contains only one binary, so image is pretty small(~8MB). To be able to build docker image additional memory needs to be granted to container that builds final image. Building docker image is divided in 2 stages. In stage one rust:latest image is used to compile static binary and the second stage contains just copies built binary into to final image.\n\nTo build docker image memcrsd sources have to be cloned and `docker build -m 512m .` command executed:\n\n```sh\ngit clone git@github.com:memc-rs/memc-rs.git memc-rs\ncd memc-rs\ndocker build -m 4096m .\n```\n\n### Publishing docker image\n\n```sh\ngit checkout memcrsd-0.0.1b\ndocker pull rust\ndocker build -m 4096m -t memcrsd .\ndocker images\n# tag docker image\ndocker tag 769dba683c8b memcrs/memc-rs:0.0.1b\ndocker tag memcrs/memc-rs:0.0.1b memcrs/memc-rs:latest\ndocker push memcrs/memc-rs:latest\ndocker push memcrs/memc-rs:0.0.1b\n```\n\n### Releasing a new memc-rs version\n\nThe release process uses an annotated git tag containing the release notes and publishes the Docker image from that tagged commit.\n\n1. Create an annotated git tag with release notes:\n\n```sh\ngit tag -a memcrsd-0.0.1c -m \"Release memcrsd 0.0.1c\\n\\nRelease notes:\\n- Add support for X\\n- Fix Y bug\"\ngit push origin memcrsd-0.0.1c\n```\n\n2. Build the Docker image from the git tag:\n\n```sh\ngit checkout memcrsd-0.0.1c\ndocker pull rust\ndocker build -m 4096m -t memcrs/memc-rs:0.0.1c .\n```\n\n3. Tag and publish the Docker image:\n\n```sh\ndocker tag memcrs/memc-rs:0.0.1c memcrs/memc-rs:latest\ndocker push memcrs/memc-rs:0.0.1c\ndocker push memcrs/memc-rs:latest\n```\n\n4. Optionally, if you want a separate patch or stable tag, create and push a lightweight alias:\n\n```sh\ngit tag memcrsd-latest memcrsd-0.0.1c\ngit push origin memcrsd-latest\n```\n\n### Getting docker image from docker hub\n\nTo get latest version of memcrsd run following command:\n\n```sh\ndocker image pull memcrs/memc-rs:latest\n```\n\nIf you want specific version please take a look at available tags: [https://hub.docker.com/r/memcrs/memc-rs/tags](https://hub.docker.com/r/memcrs/memc-rs/tags)\n\n### Runnig docker image\n\n```sh\ndocker run -p 127.0.0.1:11211:11211/tcp -d memcrs/memc-rs\n```\n\n## Testing\n\nmemcrsd project is tested using different types of tests:\n\n* unit testing,\n* fuzzy testing,\n* end-2-end tests\n\n### Unit testing\n\n```sh\ncargo test --lib -- --nocapture\n```\n\n### Fuzzy testing\n\nAt the moment decoding network packets is fuzzy tested.\n\n```sh\ncargo install -f cargo-fuzz\ncargo +nightly fuzz build\ncargo +nightly fuzz run  -j 8 fuzz_binary_decoder --  -rss_limit_mb=4192 -timeout=60\ncargo +nightly fuzz coverage fuzz_binary_decoder\n```\n\nWorkaround to see fuzzing test results:\n\n```sh\n~/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin/llvm-cov show fuzz/target/x86_64-unknown-linux-gnu/release/fuzz_binary_decoder  --format=html -Xdemangler=rustfilt --ignore-filename-regex=\"\\.cargo\" -instr-profile=fuzz/coverage/fuzz_binary_decoder/coverage.profdata \u003e index.html\n```\n\n### Generating test coverage reporting\n\nTo generate test coverage there is a convenient shell script that compiles and executed unit tests:\n\n```sh\ncd memcrs\n./coverage.sh\nfirefox ./target/llvm-cov/html/index.html\n```\n\nCoverage reporting is generated using cargo llvm-cov tool. Alternatively one can execute it from shell:\n\n```sh\ncargo llvm-cov test --lib \u0026\u0026 cargo llvm-cov report --html\n```\n\nThe plan in the future is to have coverage ~90%.\n\n### Integration testing\n\nFor end-to-end integration testing we are using the Rust client library memcache[https://crates.io/crates/memcache]. See tests directory for further details.\n\n```sh\ncargo test --test '*' -- --nocapture\n```\n\nA subset of memcached integration tests is executed, restricted to the binary protocol commands currently supported by memcrsd. These compatibility checks are driven through `testapp.Dockerfile`, which builds a helper container for the supported command set.\n\n```sh\ndocker build -f testapp.Dockerfile -t memc-testapp .\ndocker run --rm -it memc-testapp\n```\n\nTo run regression tests with a precompiled memcapable binary (on x86-64 architecture) from [https://github.com/awesomized/libmemcached](libmemcached-awesome), you can use the following Docker command:\n\n```sh\ndocker run --rm --network host memcrs/memcached-awesome:latest\n```\n\n## Measuring performance\n\nMeasuring performance can be tricky, thats why to measure performance memcrsd\nproject is using industry standard benchmarking tool for measuring performance\nof memcached server which is memtier_benchmark.\nThis tool can be used to generate various traffic patterns. It provides a robust\nset of customization and reporting capabilities all wrapped into a convenient and\neasy-to-use command-line interface.\nMore information about memtier benchmark tool can be found on [RedisLabs blog.](https://redislabs.com/blog/memtier_benchmark-a-high-throughput-benchmarking-tool-for-redis-memcached/)\n\n### Memtier benchmark installation\n\nMemtier benchmark is available on github, it needs to be cloned and compiled:\n\n```sh\ngit clone https://github.com/RedisLabs/memtier_benchmark.git\nautoreconf -ivf\n./configure\nmake\nmake install\n```\n\n### Generating flamegraph\n\nTo be able to sample and resolve Kernel functions:\n\n* we need to expose kernel addresses([kptr_restrict](https://sysctl-explorer.net/kernel/kptr_restrict/))\n* grant unprivileged users access to performance events in kernel([perf_event_paranoid](https://sysctl-explorer.net/kernel/perf_event_paranoid/))\n\n```sh\nsudo sh -c \" echo 0 \u003e /proc/sys/kernel/kptr_restrict\"\nsudo sh -c \" echo -1 \u003e\u003e /proc/sys/kernel/perf_event_paranoid\"\n```\n\nGenerating flamegraphs:\n\n```sh\nsudo apt install -y linux-tools-common linux-tools-generic\ncargo install flamegraph\ncd ~/projects/memix\ncargo flamegraph\ncargo flamegraph --bin memcrsd\n```\n\n### Attaching perf\n\nBy default release profile is built with debug symbols, see Cargo.toml:\n\n```toml\n[profile.release]\nopt-level = 3\ndebug=true\n```\n\nOn Ubuntu install required packages:\n\n```sh\nsudo apt install -y linux-tools-common linux-tools-generic\n```\n\nWe can start a server:\n\n```sh\n./target/release/memcrsd -v \u0026 perf record -F 99 -p `pgrep memcrsd`\n```\n\n* First we run the memcrsd server and we send it to the background using the ampersand (\u0026) symbol.\n* Next to it, so it executes immediately, we run perf that receives the process identifier (PID) courtesy of pgrep memcrsd.\n* The pgrep command returns the PID of a process by name.\n\nAfter benchmarks are executed reports can be displayed using perf report:\n\n```sh\nperf report\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemc-rs%2Fmemc-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmemc-rs%2Fmemc-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemc-rs%2Fmemc-rs/lists"}