mummy README

项目的 README,来自 github.com/guzba/mummy。合并为一个 markdown 文件:README.md。

Mummy

nimble install mummy

Github Actions

API reference

Mummy is a multi-threaded HTTP 1.1 and WebSocket server written entirely in Nim.

A return to the ancient ways of threads.

Mummy has been written specifically to maximize the performance of your server hardware without compromising on programmer happiness.

Mummy requires --threads:on and --mm:orc or --mm:arc.

The Mummy name refers to historical Egypt stuff.

Sites using Mummy

Other libraries built to work with Mummy

How is Mummy different?

Mummy operates with this basic model: handle all socket IO on one thread and dispatch incoming HTTP requests and WebSocket events to a pool of worker threads. Your HTTP handlers probably won't even need to think about threads at all.

This model has many great benefits and is ready to take advantage of continued server core count increases (AMD just announced a 96 core 192 thread server CPU!).

Why use Mummy instead of async?

Why prioritize WebSockets?

WebSockets are wonderful and can have substantial advantages over more traditional API paradigms like REST and various flavors of RPC.

Unfortunately, most HTTP servers pretend WebSockets don't exist.

This means developers need to hack support in through additional dependencies, hijacking connections etc and it all rarely adds up into something really great.

I see no reason why Websockets should not work exceptionally well right out of the box, saving developers a lot of uncertainty and time researching which of the possible ways to wedge WebSocket support in to an HTTP server is "best".

What is Mummy not great for?

Everything comes with trade-offs. Mummy is focused on being an exceptional API server. Think REST, JSON, RPC, WebSockets, HTML from templates etc.

The property these share in common is they are all relatively memory-light. Most things are, which is great, but if you're specifically going to be serving a lot of very large files or expect large file uploads, Mummy is probably not the best choice unless your server has the RAM to handle the large files.

Why is Mummy not great for large files? This is because Mummy dispatches fully received in-memory requests to worker threads and sends in-memory responses. This is great for everything except very large files.

Example HTTP server

import mummy, mummy/routers

proc indexHandler(request: Request) =
  var headers: HttpHeaders
  headers["Content-Type"] = "text/plain"
  request.respond(200, headers, "Hello, World!")

var router: Router
router.get("/", indexHandler)

let server = newServer(router)
echo "Serving on http://localhost:8080"
server.serve(Port(8080))

nim c --threads:on --mm:orc -r examples/basic_router.nim

Example WebSocket server

import mummy, mummy/routers

proc indexHandler(request: Request) =
  var headers: HttpHeaders
  headers["Content-Type"] = "text/html"
  request.respond(200, headers, """
  <script>
    var ws = new WebSocket("ws://localhost:8080/ws");
    ws.onmessage = function (event) {
      document.body.innerHTML = event.data;
    };
  </script>
  """)

proc upgradeHandler(request: Request) =
  let websocket = request.upgradeToWebSocket()
  websocket.send("Hello world from WebSocket!")

proc websocketHandler(
  websocket: WebSocket,
  event: WebSocketEvent,
  message: Message
) =
  case event:
  of OpenEvent:
    discard
  of MessageEvent:
    echo message.kind, ": ", message.data
  of ErrorEvent:
    discard
  of CloseEvent:
    discard

var router: Router
router.get("/", indexHandler)
router.get("/ws", upgradeHandler)

let server = newServer(router, websocketHandler)
echo "Serving on http://localhost:8080"
server.serve(Port(8080))

See the examples/ folder for more sample code, including an example WebSocket chat server.

nim c --threads:on --mm:orc -r examples/basic_websockets.nim

Performance

Benchmarking HTTP servers is a bit like benchmarking running shoes.

Certainly, there are some terrible shoes to run in (heels, clogs, etc), but once you're in a reasonable pair of shoes it is the runner that's going to matter, not the shoes.

In this analogy, the runner is what your handlers are actually doing and the shoes are the HTTP server choice.

With that in mind, I suggest three priorities:

  1. Ensure your HTTP server choice does not unnecessarily hamper performance.

  2. Avoid HTTP servers that have easy performance vulnerabilities.

  3. Prioritize what will enable you to write and maintain performant and reliable handlers.

I believe Mummy clears all three priorities:

  1. Mummy prioritizes efficiency in receiving and dispatching incoming requests and sending outgoing responses. This means things like avoiding unnecessary memory copying, ensuring the CPU spends all of its time in your handlers.

  2. Because Mummy uses multiplexed IO just like async, Mummy is not vulnerable to attacks like low-and-slow which traditionally multi-threaded servers are vulnerable to. Additionally, while a single blocking or CPU heavy operation can stall an entire async server, this is not a problem for Mummy.

  3. Request handlers with Mummy are just plain-old inline Nim code. They have a straightforward request-in-response-out API. Keeping things simple is great for maintenance, reliability and performance.

Benchmarks

Benchmarking was done on an Ubuntu 22.04 server with a 4 core / 8 thread CPU.

The tests/wrk_ servers that are being benchmarked attempt to simulate requests that take ~10ms to complete.

All benchmarks were tested by:

wrk -t10 -c100 -d10s http://localhost:8080

The exact commands for each server are:

Mummy

nim c --mm:orc --threads:on -d:release -r tests/wrk_mummy.nim

Requests/sec: 9,547.56

AsyncHttpServer

nim c --mm:orc --threads:off -d:release -r tests/wrk_asynchttpserver.nim

Requests/sec: 7,979.67

HttpBeast

nim c --mm:orc --threads:on -d:release -r tests/wrk_httpbeast.nim

Requests/sec: 9,862.00

Jester

nim c --mm:orc --threads:off -d:release -r tests/wrk_jester.nim

Requests/sec: 9,692.81

Prologue

nim c --mm:orc --threads:off -d:release -r tests/wrk_prologue.nim

Requests/sec: 9,749.22

NodeJS

node tests/wrk_node.js

Requests/sec: 8,544.60

Go

go run tests/wrk_go.go

Requests/sec: 9,171.55

Testing

A fuzzer has been run against Mummy's socket reading and parsing code to ensure Mummy does not crash or otherwise misbehave on bad data from sockets. You can run the fuzzer any time by running nim c -r tests/fuzz_recv.nim.

mummy (guzba/mummy)

正在搜索数据库…

342 ·GitHub
这是什么?Mummy 是一个适用于 Nim 的多线程 HTTP 1.1 和 WebSocket 服务器库。它在一个线程上处理套接字 IO,并把请求分发给一组工作线程,而不是依赖 async/await。
我需要自己写一个程序来使用它吗?还是 Mummy 可以作为独立服务器运行?它是一个 Nim 库,通过 nimble install mummy 安装后导入到你自己的程序中。你只需编写普通的阻塞式处理函数,线程管理和任务分发由 Mummy 负责。
怎样把它加入项目并让服务器跑起来?用 nimble install mummy 安装,然后使用 --threads:on 和 --mm:orc(或 --mm:arc)参数编译程序,例如:nim c --threads:on --mm:orc -r examples/basicrouter.nim。
Mummy 不擅长做什么?由于 Mummy 会先把完整的请求和响应缓存在内存中,然后再分发给工作线程,因此不太适合提供超大文件或处理大文件上传,除非服务器有足够的内存。
为什么 Mummy 用线程而不是 async?阻塞式处理函数可以避免 async 的“函数颜色”问题,以及因 DNS 查询或文件读取等阻塞操作导致整体卡住的风险;同时它依然使用多路复用的非阻塞套接字 IO,从而获得同样的吞吐量优势。
它的 WebSocket 支持怎么样?WebSocket 从一开始就是一等公民,内置支持。开箱即用,不需要借助额外依赖,也不像许多其他 HTTP 服务器那样通过连接劫持来勉强实现。
Mummy 和其他服务器相比有多快?在一台 4 核 8 线程的 Ubuntu 服务器上的基准测试中,Mummy 每秒可处理约 9,547 个请求,与 HttpBeast 的 9,862 接近,并领先于 AsyncHttpServer(7,979)、Node.js(8,544)和 Go(9,171)。
Mummy 有没有在真实生产环境中使用过?有。一个生产站点在一台配置很小的虚拟机上,CPU 和内存占用都很低,却能处理 500 多个 HTTP 请求每秒;另一个站点能管理 10 万个并发 WebSocket 连接,并且还有空间扩展到 100 万以上。
哪些库可以和 Mummy 搭配使用?Curly 是一个配套库,让 HTTP RPC 调用中使用 libcurl 变得简单;Ready 是专为 Mummy 这类多线程服务器设计的 Redis 客户端。
有哪些类似的项目?aiohttp, uvicorn, h2o, chi, tokio, fasthttp, echo, fiber
作者
guzba
大小
0.6 MB
星标
342
时长
4年
提交 · 90 天