{"id":26063222,"url":"https://github.com/edgio/is2","last_synced_at":"2025-04-11T11:50:19.504Z","repository":{"id":37054779,"uuid":"161567631","full_name":"Edgio/is2","owner":"Edgio","description":"embedded RESTy http(s) server library from Edgio","archived":false,"fork":false,"pushed_at":"2024-07-17T20:10:27.000Z","size":1575,"stargazers_count":7,"open_issues_count":0,"forks_count":7,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-25T08:11:09.668Z","etag":null,"topics":["http-server","restful-api"],"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/Edgio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-13T01:36:23.000Z","updated_at":"2024-07-17T20:10:32.000Z","dependencies_parsed_at":"2023-01-17T13:45:51.491Z","dependency_job_id":null,"html_url":"https://github.com/Edgio/is2","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fis2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fis2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fis2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edgio%2Fis2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edgio","download_url":"https://codeload.github.com/Edgio/is2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248389694,"owners_count":21095640,"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":["http-server","restful-api"],"created_at":"2025-03-08T16:34:16.174Z","updated_at":"2025-04-11T11:50:19.489Z","avatar_url":"https://github.com/Edgio.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![is2-ci](https://github.com/edgio/is2/workflows/is2-ci/badge.svg)\n\n# is2\n\u003e _Event driven http(s) API server library -in C++_\n\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\n### Abstract\n`is2` is a reasonably performant event driven http(s) API server library written in C++ with support for url routing, tls (with openssl), serving static files, proxying, and subrequests.\n\n### Supports\n- threading\n- [r3](https://github.com/c9s/r3) like url routing with support for slugs \n- URL handler registration inspired by [flask blueprints](https://flask.pocoo.org/docs/0.12/blueprints/)\n- tls with [openssl](https://www.openssl.org/)\n- handler support for files, proxies, and subrequests.\n\n### Architecture Overview\n\n- `is2` starts with a `server` object.\n- `listener` objects -listening on a particular port with a given scheme (TCP/TLS) can be registered with a `server` object.\n- `handler` objects can be routed to the `listener` objects at specified urls.\n\nA basic example of instantation/registration:\n\n```cpp\n  // create a TCP listener on port 12345\n  ns_is2::lsnr *lsnr =\n    new ns_is2::lsnr(12345, ns_is2::SCHEME_TCP);\n  \n  // create request handler --based on ns_is2::default_rqst_h\n  ns_is2::rqst_h *rqst_h = new request_handler();\n\n  // specify route to request handler on the listener\n  lsnr-\u003eadd_route(\"/path1/path2\", rqst_h);  \n\n  // create a server object\n  ns_is2::srvr *srvr = new ns_is2::srvr();\n\n  // register listener with server object\n  srvr-\u003eregister_lsnr(lsnr);\n```\n### The Reactor\n\n`is2` has an [event system](https://github.com/edgio/is2/tree/master/src/evr) similar to [libevent](http://libevent.org/) or [libuv](https://libuv.org/).  The reactor is a `std::priority_queue` of timer events with inverted ordering, for dequeue'ing the next nearest timeout.  The \"next nearest timeout\" is used for the subsequent call to wait for events (`epoll_wait`, `select`, `kqueue`).\n\nReactor loop psuedo code:\n\n```cpp\n  while true:\n\n    // dequeue / handle timer events until timer \u003e now\n    do \n      last_timer = timer_queue.dequeue\n    while(last_timer \u003c now)\n\n    // wait for an event -up to the next timer event\n    events = wait_event(last_timer)\n\n    // handle events if any\n    for each event\n      handle (readable/writeable/etc)\n```\n\n## Install\n\n### Build requirements\n\n#### Packages\n- openssl\n- pthread\n\n#### Building example\n```sh\ng++ ./test.cc -lis2 -lpthread -o test\n```\n\n## Usage\n\n### Basic example\n\n#### Code\n```c++\n#include \u003cis2/srvr/srvr.h\u003e\n#include \u003cis2/srvr/lsnr.h\u003e\n#include \u003cis2/srvr/default_rqst_h.h\u003e\n#include \u003cis2/srvr/api_resp.h\u003e\n\n// define handler\nclass base_handler: public ns_is2::default_rqst_h\n{\npublic:\n        // GET\n        ns_is2::h_resp_t do_get(ns_is2::session \u0026a_session,\n                                ns_is2::rqst \u0026a_rqst,\n                                const ns_is2::url_pmap_t \u0026a_url_pmap)\n        {\n                // send json response\n                return send_json_resp(a_session,\n                                      true,\n                                      ns_is2::HTTP_STATUS_OK,\n                                      \"{\\\"msg\\\": \\\"Hello World\\\"}\");\n        }\n};\n\nint main(void)\n{\n        // create server\n        ns_is2::srvr *l_srvr = new ns_is2::srvr();\n\n        // set server name -for server response\n        l_srvr-\u003eset_server_name(\"hello world server\");\n\n        // create listener\n        ns_is2::lsnr *l_lsnr = new ns_is2::lsnr(12345, ns_is2::SCHEME_TCP);\n\n        // create handler\n        ns_is2::rqst_h *l_rqst_h = new base_handler();\n\n        // add route to listener\n        l_lsnr-\u003eadd_route(\"/hello\", l_rqst_h);\n\n        // register listener with server\n        l_srvr-\u003eregister_lsnr(l_lsnr);\n\n        // num_threads == 0 means run single thread in foreground\n        l_srvr-\u003eset_num_threads(0);\n        l_srvr-\u003erun();\n        \n        // cleanup\n        if(l_srvr) {delete l_srvr; l_srvr = NULL;}\n        if(l_rqst_h) {delete l_rqst_h; l_rqst_h = NULL;}\n        return 0;\n}\n```\n\n#### Running\n```sh\n./test\n```\n\n#### Testing\n```sh\n\u003ecurl 'http://127.0.0.1:12345/hello' -v\n*   Trying 127.0.0.1...\n* Connected to 127.0.0.1 (127.0.0.1) port 12345 (#0)\n\u003e GET /hello HTTP/1.1\n\u003e Host: 127.0.0.1:12345\n\u003e User-Agent: curl/7.47.0\n\u003e Accept: */*\n\u003e \n\u003c HTTP/1.1 200 OK\n\u003c Connection: keep-alive\n\u003c Content-Length: 22\n\u003c Content-type: application/json\n\u003c Date: Thu, 15 Feb 2018 00:42:40 GMT\n\u003c Server: hello world server\n\u003c \n* Connection #0 to host 127.0.0.1 left intact\n{\"msg\": \"Hello World\"}\n```\n\n#### Performance with [hurl](https://github.com/edgio/hurl)\n```sh\n\u003ehurl 'http://127.0.0.1:12345/hello' -t1 -p100 -l5\nRunning 1 threads 100 parallel connections per thread with infinite requests per connection\n+-----------/-----------+-----------+-----------+--------------+-----------+-------------+-----------+\n| Completed / Requested |    IdlKil |    Errors | kBytes Recvd |   Elapsed |       Req/s |      MB/s |\n+-----------/-----------+-----------+-----------+--------------+-----------+-------------+-----------+\n|     58456 /     58556 |         0 |         0 |     11064.94 |     1.00s |   62255.49s |    10.81s |\n|     89685 /     89785 |         0 |         0 |     11100.93 |     1.50s |   62458.00s |    10.84s |\n|    120803 /    120903 |         0 |         0 |     11061.48 |     2.00s |   62236.00s |    10.80s |\n|    151836 /    151936 |         0 |         0 |     11031.26 |     2.50s |   62066.00s |    10.77s |\n|    182631 /    182731 |         0 |         0 |     10946.66 |     3.00s |   61590.00s |    10.69s |\n|    213663 /    213763 |         0 |         0 |     11030.91 |     3.50s |   62064.00s |    10.77s |\n|    244744 /    244844 |         0 |         0 |     11048.32 |     4.00s |   62162.00s |    10.79s |\n|    275814 /    275914 |         0 |         0 |     11044.41 |     4.50s |   62140.00s |    10.79s |\n|    306890 /    306990 |         0 |         0 |     11046.55 |     5.00s |   62152.00s |    10.79s |\n| RESULTS:             ALL\n| fetches:             306890\n| max parallel:        100\n| bytes:               7.949221e+07\n| seconds:             5.001000\n| mean bytes/conn:     259.025090\n| fetches/sec:         61365.726855\n| bytes/sec:           1.589526e+07\n| HTTP response codes: \n| 200 -- 306890\n```\n\n\n## Contribute\n\n- We welcome issues, questions and pull requests.\n\n\n## License\n\nThis project is licensed under the terms of the Apache 2.0 open source license. Please refer to the `LICENSE-2.0.txt` file for the full terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgio%2Fis2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgio%2Fis2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgio%2Fis2/lists"}