{"id":25469535,"url":"https://github.com/e1732a364fed/ruci","last_synced_at":"2025-11-04T14:30:33.218Z","repository":{"id":222859603,"uuid":"758559649","full_name":"e1732a364fed/ruci","owner":"e1732a364fed","description":"a flexible proxy framework written in rust","archived":false,"fork":false,"pushed_at":"2025-02-17T13:34:42.000Z","size":2672,"stargazers_count":42,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"tokio","last_synced_at":"2025-02-17T14:32:15.508Z","etag":null,"topics":["grpc","h2","lua","proxy","quic","rust","socks5","steganography","tokio","trojan","websocket"],"latest_commit_sha":null,"homepage":"https://e1732a364fed.github.io/ruci/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e1732a364fed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-02-16T15:27:01.000Z","updated_at":"2025-02-17T13:34:45.000Z","dependencies_parsed_at":"2024-03-12T15:29:27.969Z","dependency_job_id":"4b34fc28-88bd-4014-be5e-c057e0915041","html_url":"https://github.com/e1732a364fed/ruci","commit_stats":null,"previous_names":["e1732a364fed/ruci"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e1732a364fed%2Fruci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e1732a364fed%2Fruci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e1732a364fed%2Fruci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e1732a364fed%2Fruci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e1732a364fed","download_url":"https://codeload.github.com/e1732a364fed/ruci/tar.gz/refs/heads/tokio","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239433909,"owners_count":19637806,"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":["grpc","h2","lua","proxy","quic","rust","socks5","steganography","tokio","trojan","websocket"],"created_at":"2025-02-18T08:20:14.857Z","updated_at":"2025-11-04T14:30:33.171Z","avatar_url":"https://github.com/e1732a364fed.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruci (wip)\n\n[![release][1]][2] \n[![FOSSA Status][3]][4]\n\n\n[1]: https://img.shields.io/github/v/release/e1732a364fed/ruci\n[2]: https://github.com/e1732a364fed/ruci/releases/latest\n[3]: https://app.fossa.com/api/projects/git%2Bgithub.com%2Fe1732a364fed%2Fruci.svg?type=shield\n[4]: https://app.fossa.com/projects/git%2Bgithub.com%2Fe1732a364fed%2Fruci?ref=badge_shield\n\n- [X] Ruci : 如此: \n- [X] Rucimp: 如此实现~\n- [X] ruci-cmd: 如此简单！ 见 [ruci-cmd](crates/ruci-cmd/README.md)\n\n项目命名采用了谐音. 同时Ru指代rust, ruci 与 如此谐音.\nrucimp = ruci + imp,\nruci pronounced lucy. \n\n## Intro\n\nA flexible network proxy framework and toolbox written in Rust (Rust 2021 edition 1.81+) using Lua/json as the configuration format.\n\n用户 入门 ruci 可阅读 [ruci 用户手册](https://e1732a364fed.github.io/ruci/index.html)\n\n（book源文件在[SUMMARY.md](doc/book/src/SUMMARY.md))\n\nDeveloper 入门 ruci 可阅读 [Introduction_zh.md](doc/Introduction_zh.md)\n\nSee [notes.md](doc/notes.md) for more notes.\n\n文档所限, 肯定有东西没有涉及到, 可提交issue提问或加入讨论. \n欢迎加入我们. 注意低调. \n\n一个好的解决问题的模式: 有暂时不懂的问题可以先进群问, 确定问题后再发 issue.\n\nDeveloper chat:     https://t.me/+6yL4ggeyKY0yNjIx\n\nUser channel:       https://t.me/+r5hKQKYyeuowMTcx\n\nThe project is work in progress, 功能会陆续添加与调整.\n\n## Roadmap\n\n### ruci\n\n- [x] basic structure (based on \"Map\"s)\n- [x] tcp, udp, unix domain socket, ip (tun, with auto_route)([tun example](rucimp/examples/readme.md#tun))\n- [x] 流量记录 (两种实现, 分别用于记录原始流量(GlobalTrafficRecorder)与实际流量(Counter)) 与实时单连接流量监控 (trace feature)\n- [x] Direct, Blackhole, Listener, BindDialer, Stdio, Fileio\n- [x] fixed_target_addr\n- [x] TLS, Socks5(+ UDP ASSOCIATE,USERPASS), Http proxy, Socks5http, Trojan\n- [x] MathAdder (按字节加法器), Counter, Echo\n- [x] 路由 (tag_route)\n- [x] fallback (回落)\n- [x] DNS: client\n- [x] http1.1 识别\n- [x] MITM ( man in the middle)\n\n### rucimp\n\n- [x] ruci 配置模式 (动态链须为lua格式)\n- [ ] clash 配置模式\n- [ ] verysimple 配置模式\n- [x] static chain (静态链, 可为 lua/json 格式)\n- [x] dynamic chain (finite, infinite) (动态链)(有限动态链, 完全动态链)\n- [x] rucimp/examples\n- [x] rule_route 规则路由\n- [x] clash 规则路由\n- [x] tproxy (with auto_route)\n- [x] native-tls\n- [x] http_filter, websocket(including early data)\n- [x] h2, grpc\n- [x] quic (quinn/s2n-quic)\n- [ ] vpn_test1 （目前只有 单ip转发）\n- [x] tcp/ip stack (smoltcp/lwip)\n- [ ] ss, ~~vmess~~\n- [x] Steganography Protocol Example1\n- [x] User-defined Lua protocol\n- [x] Embedder (Steganography Protocol)\n\n### ruci-cmd\n\n- [x] basic feature\n- [x] api_server\n- [x] api_client\n- [x] static file server \n- [x] utils\n- [ ] system tray\n- [ ] ~~tui: using ratatui~~\n\n### 其它生态\n\n[节点编辑器 webui ](https://github.com/e1732a364fed/ruci-webui)\n\n\n## Structure\n\nThe project is divided to three main parts:\n\nruci is the base framewark, defines some concepts like【映射】(Map), 动态Map迭代器 DMIter; \nimplements chain structure, implements some basic Maps; provides some useful relay facilities.\n\nrucimp provides more Maps, defines the config mode(and file format), provides some example binaries.\nrucimp is the core.\n\nruci-cmd is the ultimate full feature executable, including utils, api-client and api-server\n\n具体名词解释请看下文. \n\n## Configuration Mode\n\nFor lua configuration, see [local.lua](dev_res/local.lua), [remote.lua](dev_res/remote.lua)  和 [lua配置说明](doc/lua.md) \n以及 [ruci 用户手册](https://e1732a364fed.github.io/ruci/index.html)\n\n## Compile/Run\n\n### ruci-cmd\n\nfull featured command-line executable.\n\nSee [ruci-cmd](crates/ruci-cmd/README.md)\n\n\n### rucimp/examples\n\nrucimp provides some example binaries for debugging and testing.\n\nSee [exmaples](rucimp/examples/readme.md)\n\n\n# Dev\n\nSee [doc/CONTRIBGUITING_zh.md](doc/CONTRIBUTING_zh.md) for developper Contributing guidelines in 中文.\n\n## What is \"Proxy\"\n\nA proxy must have both an inbound and an outbound.\n\nIf the app only has an inbound, then it's just a regular web server.\nIf the app only has an outbound, then it's just a regular web browser.\n\nOn client side, having both an inbound and an outbound is called a regular proxy;\nIts outbound is connected to the server's inbound.\n\nOn server side, having both an inbound and an outbound is called a \"reverse proxy\".\nIts outbound is connected to another server's inbound.\n\n## Chain Structure Explained\n\nRuci abstracts proxy, regards any protocols as consisting of one or more Map 【映射】\n\nPseudo code: \n\nStream generator 【单流发生器】(zero to one):  `function(args)-\u003estream`\n\nInjection 【单射】(one to one function, which is the normal stream Map): \n `function(stream1, args...)-\u003e (Option\u003cstream2\u003e, useful_data...) `\n\nMulti-stream generator【多流发生器】(one to many): `function( Option\u003cstream\u003e ,args...)-\u003e[channel-\u003estream]`\n\n流由流发生器产生. \n\n流发生器是一种不接受流参数, 只接受其它参数的(编程意义下的)函数, 是整个链的起点, 是流的源。\n\n单流发生器 可能是 BindDialer, 文件, 或者 Stdio.\n\n多流发生器可能是 Listener (不接受流参数的无中生有 (一般实际上原理上是对接硬件上的流,\n如网卡提供的流) ) 或 inner mux (接受一个流, 对其进行分支处理)。\n其在数学意义下可以理解为泛函。\n\n流映射是数学意义下的函数（映射）。\n流映射可以改变流(如Tls), 也可以不改变而只是在内容上做修改(如MathAdder),\n\n也可以完全不做修改而只提供副作用(如 Counter, 或Trojan/Socks5 先做握手然后不改变流) \n(Maps like this are normally called \"middleware\")\n\n也可以消耗掉流(如 Echo (持有对流的所有权, 自己建立relay loop); Blackhole; \n再如 relay 转发过程 将 in 和 out 调转对接, 同时消耗in 和 out 两个流), \n\n消耗流的映射是整个链的终点 . \n\n也可以替换掉流的源(如socks5中的 udp associate, 是持有tcp流的所有权后, 产生并返回一个新的udp流). \n\n如此, 整个架构抽象把代理分成了一个一个小模块（映射）, 像一个个箭头一样，任由你拼接. \n\n\n虽然看起来没有什么区别, 但是, 你可以很方便地构建一些独特的结构, 比如 TLS+TLS (用于分析 tls in tls, \n你甚至可以累加N个, 变成N*TLS), 比如 `TCP-Counter-TLS-Counter-TLS-Counter-Socks5-Counter` \n(Counter用于统计流量, 并将数据原样传递, 这样每一层的流量就都统计出来了)\n\n其它可能的情况比如 Socks5+WS+TLS+WS+Socks5+TLS., 甚至你可以造出一些逻辑结构, 只要有最终出口就行, \n如 Socks5 - repeat N [TLS1-TLS2] - Socks5\n\n发挥你的想象力吧. \n\n能够定义动态的链式结构 (如跳转, 以及通过跳转实现的 循环)的链式配置文件要采用脚本语言格式.  这里使用 Lua。\n\n只会返回 有限个Map可能 的动态链 是一种 有限状态机. 静态链是一种特化的有限状态机, 其状态转换函数是 `fn(i)-\u003e++i`。\n\n\n经典链\n\n```\n# classic chain\n\n          p1       p2\n            \\       \\\ngenerator-\u003e[s1] -\u003e [s2] -\u003e [ output ]\n             \\       \\\n             o1  -\u003e  o2 -\u003e\n\n# where s1 is tls and s2 is trojan\n# generator is tcp\n# p1 is tls settings, o1 is the tls state (alpn, etc...)\n# p2 is trojan settings, like the password\n# o2 is the trojan state\n# output is the encoded client stream\n```\n\n```mermaid\ngraph LR\np1((p1))--\u003es1_node[stream1]-.-\u003eo1node((o1))\np2((p2))--\u003es2_node[stream2]-.-\u003eo2node((o2))\no1node-..-\u003es2_node\ngenerator--\u003es1_node--\u003es2_node--\u003eoutput\n\ncollector[data_collector]\n\no1node-.-\u003ecollector\no2node-.-\u003ecollector\n\n```\n\n\n#### Goal of The Project\n\n1. 了解协议的细节 以进行数据处理、转换到统一格式和“标注”.\n2. 提供一些新协议的想法\n\n详见 [目标]( doc/GOAL_zh.md)\n\n\n# License\n\nThis project is licensed under the MIT OR Apache-2.0 License.\n\nreadme files and doc files are also distributed with CC0 1.0 Universal License if the related file has no conflict with the MIT OR Apache-2.0 License.\n\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fe1732a364fed%2Fruci.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fe1732a364fed%2Fruci?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe1732a364fed%2Fruci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe1732a364fed%2Fruci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe1732a364fed%2Fruci/lists"}