[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75426":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":21,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},75426,"ymawky","imtomt\u002Fymawky","imtomt","MacOS Web Server written entirely in ARM64 assembly",null,"Assembly",529,26,364,0,8,167,62.29,"GNU General Public License v3.0",false,"main",true,[],"2026-06-12 04:01:18","![](docs\u002Fymawky.png)\n\n# *ymawky* -- web server in ARM assembly\nThis is *ymawky* (yuh maw kee), a web server written entirely in ARM64 assembly. ymawky is a syscall-only, no libc, fork-per-connection web server written by hand. While it is developed for MacOS, I've tried to make it as portable as possible -- *however*, it's likely you will still need to make some ~~(hopefully minor)~~ Significant tweaks to get this to run on Linux\u002Fother Unix systems. See [Implementation Notes](#implementation-notes) for more details.\n\n## Building\nRequires Xcode Command Line Tools. Install with `xcode-select --install`.\nymawky only runs on apple silicon (arm64).\n\nRun `make` to build.\n\nEnsure there is a `www\u002F` directory next to the `ymawky` executable. That's the document root where *ymawky* searches for files.\n`GET` with an empty filename (`GET \u002F`) will search for `www\u002Findex.html`, so you might want to make sure there's an `index.html` as well.\n\n*ymawky* will try to serve static error pages when a client's request results in error, eg 404. The pages it searches for in `err\u002F(code).html`, so ensure `err\u002F` exists alongisde `ymawky` and `www\u002F`.\nSee [Configuration](#configuration) to modify the default file and docroot.\n\n## Running\n- `.\u002Fymawky` to start running the web server on `127.0.0.1:8080`.\n- `.\u002Fymawky [port]` to start running the web server on `127.0.0.1:[port]`\n- `.\u002Fymawky [literally-any-character-other-than-0-9]` to start running the web server on 127.0.0.1:8080 in debug mode. Debug mode disables forking, and makes ymawky only handle one request. (*I needed to do this because `lldb` wasn't letting me debug the children, ugh.*)\n\nUnfortunately, while custom ports are supported, custom addresses are not. as of right now, ymawky can only run on `127.0.0.1`. This is solely because I haven't implemented it -- but if you'd like to consider this a safety feature, then I guess it could be intentional.\n\nTo see ymawky in action, start running ymawky with `.\u002Fymawky [port]`. Then open your web browser of choice (or use curl), and visit `127.0.0.1:8080\u002F` or `127.0.0.1:8080\u002Fpretty\u002Findex.html`. Bask in the warmth of assembly.\n\n## What can it do?\nymawky is a ~~static-file~~ dynamic web server. It ~~doesn't~~ **does** support server-side code to generate content on-the-fly, and more advanced URL parsing such as `\u002Fsearch?query=term`, through CGI scripts.\n- Supported HTTP methods:\n    - GET\n    - PUT\n    - DELETE\n    - OPTIONS\n    - HEAD\n    - POST, through CGI scripts\n- Basic protection from slowloris-like Denial of Service attacks\n- Decodes % hex encoding, eg, `%20` decodes to a space in filenames, and `%61` decodes to `a`\n- Smart path traversal detection and prevention. Blocks `..` from traversing paths, while not disallowing multiple periods when they're part of a file:\n  - `GET \u002F..\u002F..\u002F..\u002Fetc\u002Fpasswd` -> `403 Forbidden`\n  - `GET \u002Fohwell...txt` -> `200 OK`\n  - `GET \u002F..\u002Fsrc\u002Fymawky.S` -> `403 Forbidden`\n  - `GET \u002Fhehe..txt` -> `200 OK`\n- Automatically prepends `www\u002F` to requested files. `GET \u002Findex.html` will retrieve `www\u002Findex.html`\n- Empty `GET \u002F` requests default to `GET www\u002Findex.html`\n- `PUT` requests support uploads of up to 1GiB, though this can be configured for larger files\n- `PUT` is atomic due to writing to a temporary file then renaming, allowing concurrent `PUT` requests without leaving partially-written files\n- `Content-Length:` parsing and verification in `PUT` requests\n- MIME type detection, giving `Content-Type` in the response header with the corresponding MIME type\n- Accepts `Range: bytes=` ranges in GET requests, supporting full ranges `bytes=X-N`, suffix ranges `bytes=-N`, and open-ended ranges `bytes=X-`. Video scrubbing is well supported\n- Basic HTTP version parsing. Requests need to specify `HTTP\u002F1.1` or `HTTP\u002F1.0`, and if requesting `HTTP\u002F1.1`, a `Host:` field needs to be present in the header. Currently, ymawky doesn't do anything with Host, but per RFC 9112 Section 3.2, the Header must be sent\n- Serves custom HTML pages for error codes, such as 404, or 500. Look in the `err\u002F` directory for an example\n- If the requested resource is a directory, list all files and subdirs in the directory. Note that this excludes www\u002F (or whatever your docroot is): GET \u002F will always search for index.html if no file is given.\n- CGI script support. All CGI scripts must be located within `CGI_DIR` (defined in `config.S`, default to `(docroot)\u002Fcgi-bin\u002F`).\n  - Query strings (`\u002Fcgi-bin\u002Fratbook?q=do+you+like+rats&a=yes!`) are supported\n  - ymawky parses the CGI script's headers and forwards them to the client response\n  - Enforces some minimal CGI compliance: all CGI scripts must begin their response with a header, if the response has a body as well, the header must contain a Content-Length field.\n  - HTTP response code is determined by the CGI script's Status: header field, so scripts can send their own 404 or 500 or what have you. If no Status is provided, a default of `200 OK` is used.\n\n## \"Safety\"\nThis is a web server written entirely by-hand in ARM64 assembly as a fun project. It's probably got a lot of vulnerabilities I'm unaware of. However, I did do my best to make it safer. Here are some safety precautions ymawky takes.\n- Rejects paths >= PATH_MAX (4096 bytes)\n- Reject any paths that include path traversal -- `\u002F..\u002F..`\n- Reject any requests that do not contain a path within 16 bytes\n- Confined to `www\u002F`. Any path requested gets `www\u002F` prepended to it\n- Rejects any path containing symlinks, with O_NOFOLLOW_ANY\n- PUT writes to a temporary file, `www\u002F.ymawky_tmp_\u003Cpid>`. Upon successfully receiving the whole file, this temporary file is then renamed to the requested filename. This prevents partial or corrupted PUT requests from overwriting existing files.\n- Reject any requests whose path starts with `www\u002F.ymawky_tmp_`. This prevents someone from `GET`ing a temporary file, and prevents someone from sending `PUT \u002F.ymawky_tmp_4533` or something.\n- Must receive data within 10 seconds. If it's slower, the connection will close. If the entire header is not received within 10 seconds total, the connection will be closed. This is to prevent slowloris-like attacks.\n- CGI script support limited to the (configurable) `cgi-bin\u002F` directory. Any request sent through `cgi-bin` gets treated the same, so you can't PUT a file with a destination inside `cgi-bin`, it just gets executed as a CGI script (if it exists).\n- Please note that CGI script support is currently *experimental*, and doesn't have the same strict timeout settings as PUT does. A CGI script could theoretically loop forever, read input forever, hang somewhere forever, and ymawky will not kill the script. You shouldn't run ymawky on a real server (lol), but if you *have* to, remove the `www\u002Fcgi-bin\u002F` directory, and don't allow CGI support.\n\n## CGI Script Support\nCGI, or Common Gateway Interface, is an interface specification that enables web servers to execute an external program to process HTTP user requests (thank you, wikipedia). Basically, a CGI script is an executable script on the server. The script runs and generates dynamic content in response to user requests, rather than serving one static file.\n\nymawky supports query strings: everything after the `?` in URLs. So if you have a CGI script called `logbook`, you could send a request for `\u002Fcgi-bin\u002Flogbook?q=nice+job`, and ymawky will execute logbook with the `QUERY_STRING` environmental variable set to `q=nice+job`.\n\n# CGI Limitations\nCGI support in ymawky is limited. ymawky does not support `PATH_INFO`; in a request like `\u002Fblog\u002F2024\u002F01`, `blog` could be the executable path and `\u002F2024\u002F01` is passed in the `PATH_INFO` environmental variable. ymawky just treats every path as being a literal path, it would look for the file `\u002Fblog\u002F2024\u002F01`.\n\n# CGI Security note\nCGI scripts can have their own vulnerabilities, since they're full programs on their own. They need to do their own error handling, input parsing, etc. What ymawky does is simple (in a manner of speaking): find the executable file, set some environmental variables, fork, execute the CGI script, and write HTTP content between the user and the CGI script.\n\n## HTTP Status Codes\nymawky currently supports and can reply with the following status codes:\n- `200 OK`\n- `201 Created`\n- `204 No Content`\n- `206 Partial Content`\n- `400 Bad Request`\n- `403 Forbidden`\n- `404 Not Found`\n- `408 Request Timeout`\n- `409 Conflict`\n- `411 Length Required`\n- `413 Content Too Large`\n- `414 URI Too Long`\n- `416 Range Not Satisfiable`\n- `418 I'm a teapot`\n- `431 Request Header Fields Too Large`\n- `500 Internal Server Error`\n- `501 Not Implemented`\n- `502 Bad Gateway`\n- `503 Service Unavailable`\n- `505 HTTP Version Not Supported`\n- `507 Insufficient Storage`\n\nCustom HTML pages will be served alongside the error codes (400+). These HTML files are located in `err\u002F(code).html`. You can use `build_err_pages.sh` to create a page for each code, with different text at your leisure. Edit the source code of `build_err_pages.sh` to modify the text per-page, and modify `err\u002Ftemplate.html` to modify the base template. In `err\u002Ftemplate.html`:\n- `{{CODE}}`  - HTTP Code: eg, 404\n- `{{TITLE}}` - Title text: eg, \"Not Found\"\n- `{{MSG}}`   - Custom message: eg, \"the rats ate this page\"\n\n## MIME Types\nMIME types are detected by analyzing the file extension. The following MIME types are recognized.\n\nWeb-related files:\n- `.html`  -> `text\u002Fhtml; charset=utf-8`\n- `.htm`   -> `text\u002Fhtml; charset=utf-8`\n- `.css`   -> `text\u002Fcss; charset=utf-8`\n- `.csv`   -> `text\u002Fcsv; charset=utf-8`\n- `.xml`   -> `text\u002Fxml; charset=utf-8`\n- `.js`    -> `text\u002Fjavascript; charset=utf-8`\n- `.json`  -> `application\u002Fjson`\n- `.wasm`  -> `application\u002Fwasm`\n- `.mjs`   -> `text\u002Fjavascript; charset=utf-8`\n- `.map`   -> `application\u002Fjson`\n\nImage files:\n- `.png`   -> `image\u002Fpng`\n- `.jpg`   -> `image\u002Fjpeg`\n- `.jpeg`  -> `image\u002Fjpeg`\n- `.gif`   -> `image\u002Fgif`\n- `.svg`   -> `image\u002Fsvg+xml`\n- `.ico`   -> `image\u002Fx-icon`\n- `.webp`  -> `image\u002Fwebp`\n- `.avif`  -> `image\u002Favif`\n- `.bmp`   -> `image\u002Fbmp`\n- `.tiff`  -> `image\u002Ftiff`\n- `.apng`  -> `image\u002Fapng`\n\nFont files:\n- `.woff`  -> `font\u002Fwoff`\n- `.woff2` -> `font\u002Fwoff2`\n- `.ttf`   -> `font\u002Fttf`\n- `.otf`   -> `font\u002Fotf`\n\nDocument files:\n- `.txt`   -> `text\u002Fplain; charset=utf-8`\n- `.pdf`   -> `application\u002Fpdf`\n- `.doc`   -> `application\u002Fmsword`\n- `.docx`  -> `application\u002Fvnd.openxmlformats-officedocument.wordprocessingml.document`\n- `.epub`  -> `application\u002Fepub+zip`\n- `.rtf`   -> `application\u002Frtf`\n\nVideo files:\n- `.mp4`   -> `video\u002Fmp4`\n- `.webm`  -> `video\u002Fwebm`\n- `.mkv`   -> `video\u002Fx-matroska`\n- `.avi`   -> `video\u002Fx-msvideo`\n- `.mov`   -> `video\u002Fquicktime`\n\nAudio files:\n- `.mp3`   -> `audio\u002Fmpeg`\n- `.ogg`   -> `audio\u002Fogg`\n- `.wav`   -> `audio\u002Fwav`\n- `.flac`  -> `audio\u002Fflac`\n- `.aac`   -> `audio\u002Faac`\n- `.m4a`   -> `audio\u002Fmp4`\n- `.opus`  -> `audio\u002Fopus`\n\nArchive files:\n- `.zip`   -> `application\u002Fzip`\n- `.gz`    -> `application\u002Fgzip`\n- `.tar`   -> `application\u002Fx-tar`\n- `.7z`    -> `application\u002Fx-7z-compressed`\n- `.bz2`   -> `application\u002Fx-bzip2`\n- `.rar`   -> `application\u002Fvnd.rar`\n\n## Configuration\nYou can configure ymawky with the `config.S` file. The options are documented here.\n- `#define DOCROOT \"www\u002F\"` -- This is the docroot. Change it to wherever your HTML files are, relative to ymawky, or use an absolute path:\n  - `#define DOCROOT \"www\u002F\"`\n  - `#define DOCROOT \"\u002FLibrary\u002FWebServer\u002FDocuments`\n  - `#define DOCROOT \".\u002F\"`\n- `#define CGI_DIR \"cgi-bin\u002F\"` -- This is the directory in which CGI scripts are stored. Only CGI scripts are to be stored in here! Any request within CGI_DIR will execute the requested file\n- `#default ERR_DIR \"err\u002F\"` -- This is the directory in which ymawky will search for custom error HTML pages, eg, `err\u002F404.html` or `err\u002F500.html`\n- `#define DEFAULT_FILE \"index.html\"` -- This is the default file ymawky will serve when it receives an empty `GET \u002F HTTP\u002F1.1` request\n- `.equ RECV_TIMEOUT, 10` -- Number of seconds ymawky will wait to receive datta before closing the connection. If it's more than `RECV_TIMEOUT` seconds between `read()`s, ymawky will close the connection with `408 Request Timed Out`\n- `.equ HEADER_REQ_TIMEOUT_SECS, 10` -- Maximum number of seconds ymawky will wait to receive the full header before timing out. If it takes, longer than this to receive the header, ymawky will close the connection with `408 Request Timed Out`\n- `.equ PUT_GRACE_SECS, 5` -- ymawky dynamically calculates a max-time-per-PUT based on `Content-Length`. The max time is defined as `PUT_GRACE_SECS + Content-Length \u002F PUT_MIN_BPS`. This is the minimum grace period allowed if it calculates a file should take \u003C1 second to upload\n- `.equ PUT_MIN_BPS, 1024 * 16` -- Minimum bytes-per-second. Higher if you want to be stricter, smaller if you want to be more lenient. Since this uses the `.equ` directive, arithmetic is supported, and `1024 * 16` gets calculated at assembly time becoming `16384` or 16KB\n- `.equ MAX_BODY_SIZE, 1024 * 1024 * 1024` -- Maximum bytes PUT allows for Content-Length. By default, 1GB (1024*1024*1024 = 1073741824 bytes). Files with a larger Content-Length larger than this will be rejected with `413 Content Too Large`\n- `.equ MAX_PROCS, 256` -- Maximum number of concurrent proccesses ymawky is allowed to run. Since ymawky is a fork-per-connection server, you want to ensure ymawky doesn't exhaust your PID space. ymawky will reply with `503 Service Unavailable`\n\n## Implementation Notes\nymawky is written for MacOS (sorry...). There are a few (well, more than a *few*) things that are MacOS-specific in this code that won't be portable.\n- Syscalls on MacOS use `x16` for the number and `svc #0x80` to call it. Linux uses `x8` and `svc #0`.\n- Error reporting is different. MacOS sets the carry flag on error, and puts `errno` in `x0`. Linux returns a negative value in `x0`, like `-ENOENT`. Ever `b.cs` would need to be replaced with `cmp x0, #0` \u002F `b.lt ...`, and you'd negate `x0` to get errno.\n- `fork()` works differently, MacOS puts 1 in `x1` in the child process, whereas Linux puts `0` in `x0`.\n- `SO_NOSIGPIPE` doesn't exist on Linux.\n- `O_NOFOLLOW_ANY` is also MacOS-specific.\n- `renameatx_np()` is also MacOS-specific. Linux has `renameat2()`, with different flag values.\n- Struct layouts and offsets will differ. The `stat64` struct, `itimerval` struct, and `sockaddr_in` struct, will all need to be reconsidered.\n- `adr xN, foo@PAGE` \u002F `add xN, xN, foo@PAGEOFF` are Mach-O relocation operators. Linux ELF uses different syntax, like `:pg_hi21:` and `:lo12:`. The `adr_l`, `ldr_l` and `str_l` macros would need to be rewritten or replaced.\n- My personal favorite :3 Signal handling works differently on Linux and MacOS. MacOS's `sigaction` struct contains a `sa_tramp` field that the kernel jumps to before your handler. ymawky utilizes `sa_tramp` directly *as the handler itself*, skipping the libc trampoline and `sigreturn` entirely. Since the handler only sends a 408 and exits, without needing to return, that's fine and works wonderfully without libc. The `sigaction` call would need to be rewritten for POSIX systems.\n\n### Special Thanks:\n- [asmhttpd](https:\u002F\u002Fgithub.com\u002Fjcalvinowens\u002Fasmhttpd), an x86_64 Linux HTTP server, was a big inspiration\n- *Bob Johnson*\n- *Bob Johnson's Therapist*\n","ymawky 是一个完全用 ARM64 汇编语言编写的 MacOS Web 服务器。其核心功能包括支持多种 HTTP 方法（如 GET、PUT、DELETE、OPTIONS、HEAD 和通过 CGI 脚本的 POST），基本的慢速攻击防护，以及智能路径遍历检测和预防。该项目不依赖于 libc 库，采用每个连接创建一个子进程的方式运行。尽管主要针对 MacOS 设计，但开发者也尽量使其具备跨平台特性，不过在其他 Unix 系统上运行可能需要进行一些调整。ymawky 适合用于学习 ARM64 汇编语言及其在网络编程中的应用，同时也可作为小型项目或教学工具使用，展示如何从底层构建一个功能齐全的 Web 服务器。",2,"2026-06-11 03:52:44","CREATED_QUERY"]