{"id":13746158,"url":"https://github.com/openresty/mockeagain","last_synced_at":"2025-07-22T19:03:58.691Z","repository":{"id":1835717,"uuid":"2760087","full_name":"openresty/mockeagain","owner":"openresty","description":"Mocking ideally slow network that only allows reading and/or writing one byte at a time","archived":false,"fork":false,"pushed_at":"2018-05-27T04:21:09.000Z","size":47,"stargazers_count":130,"open_issues_count":2,"forks_count":23,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-06-07T18:07:45.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tscizzle/IPD_Morality","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.markdown","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}},"created_at":"2011-11-12T03:44:17.000Z","updated_at":"2025-01-20T15:09:44.000Z","dependencies_parsed_at":"2022-07-18T08:30:40.910Z","dependency_job_id":null,"html_url":"https://github.com/openresty/mockeagain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/openresty/mockeagain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fmockeagain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fmockeagain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fmockeagain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fmockeagain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/mockeagain/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fmockeagain/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266554006,"owners_count":23947251,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":"2024-08-03T06:00:48.222Z","updated_at":"2025-07-22T19:03:58.669Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"Description\n===========\n\n[![Build Status](https://travis-ci.org/openresty/mockeagain.svg?branch=master)](https://travis-ci.org/openresty/mockeagain)\n\nThis tool emulates an ideally slow network by mocking the\npolling and read/write syscalls exposed by glibc via the\nLD_PRELOAD technique.\n\nBy preloading this dynamic library to your network server\nprocess, it will intercept the \"poll\", \"close\", \"send\", and \"writev\"\nsyscalls, only allow the writing syscalls to actually write a single byte\nat a time (without flushing), and returns EAGAIN until another\n\"poll\" called on the current socket fd.\n\nSimilarly, one can configure this library to intercept the \"read\",\n\"recv\", \"recvfrom\" calls on the C level to emulate extremely slow\nreading operations either with or without slow writes at the same\ntime.\n\nThe socket fd must be called first by a \"poll\" call to mark\nitself to this tool as an \"active fd\" and trigger subsequence\nthe writing syscalls to behave differently.\n\nWith this tool, one can emulate extreme network conditions\neven locally (with the loopback device).\n\nThis tool is intended to supersed the good old\n[etcproxy](https://github.com/chaoslawful/etcproxy) tool.\n\nBuild\n=====\n\nJust issue the following command to build the file mockeagain.so\n\n    make\n\nThe Gnu make and gcc compiler are required.\n\nOn *BSD, it's often required to run the command \"gmake\".\n\nUsage\n=====\n\nFor now, only \"poll\" syscall and slow writing mocking are supported.\n\nHere we take Nginx as an example:\n\n1. Ensure that you have passed the --with-poll_module option while\n   invoking nginx's configure script to build nginx.\n\n2. Ensure that you've enabled the \"poll\" event model in your nginx.conf:\n\n    events {\n        use poll;\n        worker_connections 1024;\n    }\n\n3. Ensure that you've disabled nginx's own write buffer:\n\n    postpone_output 1; # only postpone a single byte, default 1460 bytes\n\nand also have the following line in your nginx.conf:\n\n    env LD_PRELOAD;\n\n4. Run your Nginx this way:\n\n    MOCKEAGAIN=w LD_PRELOAD=/path/to/mockeagain.so /path/to/nginx ...\n\nEnvironments\n============\n\nThe following system environment variables can be used\nto control the behavior of this tool. You should\nuse Nginx's standard \"env\" directive to enable the\nenvironments that you use in your nginx.conf file, as in\n\n    env MOCKEAGAIN_VERBOSE;\n    env MOCKEAGAIN;\n    env MOCKEAGAIN_WRITE_TIMEOUT_PATTERN;\n\nIf you're using the Test::Nginx test scaffold, then these directives are\nautomatically configured for you.\n\nMOCKEAGAIN\n----------\n\nThis environment controls whether to mocking reads or writes or both.\n\nWhen the letter \"r\" or \"R\" appear in the value string, then reads will be mocked.\n\nWhen the letter \"w\" or \"W\" appear in the value string, then writes will be mocked.\n\nWhen this environment is either not set or set to something unrecognized, then no mocking will be performed.\n\nMOCKEAGAIN_VERBOSE\n------------------\n\nYou can set the environment MOCKEAGAIN_VERBOSE to 1 if you want more diagnostical outputs of this tool in stderr. But you'll also have to add the following line to your nginx.conf:\n\n    env MOCKEAGAIN_VERBOSE;\n\nWhen setting MOCKEAGAIN_VERBOSE to 1, you'll get messages like the following in your nginx's error.log file:\n\n    mockeagain: mocking \"writev\" on fd 3 to signal EAGAIN.\n    mockeagain: mocking \"writev\" on fd 3 to emit 1 of 188 bytes.\n    mockeagain: mocking \"writev\" on fd 3 to emit 1 of 187 bytes.\n    mockeagain: mocking \"recv\" on fd 5 to read 1 byte of data only\n\nMOCKEAGAIN_WRITE_TIMEOUT_PATTERN\n--------------------------------\n\nWhen this environment is set to value \"foo bar\", then the when the string \"foo bar\" appears in the output stream (not necessarily in a single write call), then it will trigger an indefinite write timeout.\n\nThis feature is very useful in mocking a write timeout in a particular position in the output stream.\n\nNote that this environment also requires that the MOCKEAGAIN variable value contains \"w\" or \"W\".\n\nFor now, this feature only supports the \"writev\" call.\n\nGlibc API Mocked\n----------------\n\nEvent API\n* poll\n\nWriting API\n* writev\n* send\n\nReading API\n* read\n* recv\n* recvfrom\n\nTests\n=====\n`mockeagain` has a simple testing suite.\n\nTo run tests, simply type `make test`. Note that a working standard Python is needed to run the tests.\n\nTo run tests with Valgrind, run `make test VALGRIND=1` instead.\n\nTo write a new test:\n\nCopy one of the existing test cases to get started. Test case files are\nalways named in the format of `###-name.c`. You need to implement minimum the `run_test()`\nfunction. `run_test()` function takes a single parameter, `fd` which refers to a valid TCP socket\nthat has been connected to an echo server and set to non-blocking mode. You are\nexpected to return zero when all tests passed and non zero when one or more tests failed.\n\nYour test case is responsible for enabling read/write mocks. There is a helper\nfunction `set_mocking()` that accepts a combination of `MOCKING_READS` and\n`MOCKING_WRITES` to enable read and/or write mocking. There is another\nfunction `set_write_timeout_pattern()` that sets the `MOCKEAGAIN_WRITE_TIMEOUT_PATTERN`\nenvironment variable.\n\n*Note:* In general, `set_mocking()` and `set_write_timeout_pattern()` should\nbe called before invocation of any mocked functions above. This is due to\nthe fact that `mockeagain` will lazy load those settings and cache them forever\nafterwards.\n\nTODO\n====\n\n* add support for write, sendto, and more writing syscalls.\n* add support for other event interfaces like epoll, select, kqueue, and more.\n\nSuccess Stories\n===============\n\nngx_echo\n--------\n\nThe echo_after_body directive used to have a bug that the output filter\nfailed to take into account the NGX_AGAIN constant returned from\nthe downstream output filter chain. Enabling mockeagain's writing mode\ncan trivially capture this issue even on localhost.\n\nTo reproduce, update ngx_http_echo_filter.c:165\n\n    #if 0\n\nto\n\n    #if 1\n\nand run ngx_echo's test file t/echo-after-body.t with mockeagain's writing mode enabled.\n\nngx_redis\n---------\n\nngx_redis 0.3.5 and earlier had a subtle bug in its redis reply parser\nas explained here:\n\n    https://groups.google.com/group/openresty/browse_thread/thread/b5ddf1b24d3c9677\n\nEven though this bug was first captured by the [etcproxy](https://github.com/chaoslawful/etcproxy) tool, but mockeagain's reading mode\ncan also capture it reliably even on localhost.\n\nTo reproduce, just compile ngx_redis 0.3.5 with ngx_srcache, and\nthen run the t/redis.t test file in ngx_srcache's test suite, and with mockeagain reading mode enabled.\n\nlibdrizzle\n----------\n\nlibdrizzle 0.8 and earlier had a subtle bug in its MySQL packet parser\nand mockeagain's reading mode can capture it reliably even on localhost.\n\nTo reproduce, just compile libdrizzle 0.8 with ngx_drizzle, and run the t/sanity.t test file in ngx_drizzle's test suite\nwith mockeagain's reading mode enabled.\n\nngx_lua\n-------\n\nThe downstream cosocket API did have a bug in its receive(size) method call that was caught by mockeagain in its reading mode.\n\nTo reproduce, check out ngx_lua v0.5.0rc24 and run its t/067-req-socket.t test file\nwith \"MOCKEAGAIN=R\" and TEST 1 will just hang.\n\nAuthor\n======\n\nYichun \"agentzh\" Zhang (章亦春)\n\nCopyright \u0026 License\n===================\n\nThis module is licenced under the BSD license.\n\nCopyright (C) 2012-2017 by Yichun \"agentzh\" Zhang (章亦春) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n\n* Redistributions of source code must retain the above copyright\nnotice, this list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright\nnotice, this list of conditions and the following disclaimer in the\ndocumentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\nA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\nHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED\nTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\nPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\nLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\nNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fmockeagain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fmockeagain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fmockeagain/lists"}