{"id":29878283,"url":"https://github.com/annany2002/wisp","last_synced_at":"2026-06-19T21:31:45.615Z","repository":{"id":306627475,"uuid":"1026792849","full_name":"Annany2002/wisp","owner":"Annany2002","description":"Featherlight, lightning fast web server and reverse proxy, built with Go.","archived":false,"fork":false,"pushed_at":"2025-07-26T17:18:15.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-07-26T21:26:22.627Z","etag":null,"topics":["api","golang","proxy","server","tcp-server"],"latest_commit_sha":null,"homepage":"","language":"Go","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/Annany2002.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T16:14:12.000Z","updated_at":"2025-07-26T17:18:18.000Z","dependencies_parsed_at":"2025-07-26T21:37:53.487Z","dependency_job_id":null,"html_url":"https://github.com/Annany2002/wisp","commit_stats":null,"previous_names":["annany2002/wisp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Annany2002/wisp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Annany2002%2Fwisp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Annany2002%2Fwisp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Annany2002%2Fwisp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Annany2002%2Fwisp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Annany2002","download_url":"https://codeload.github.com/Annany2002/wisp/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Annany2002%2Fwisp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268003636,"owners_count":24179293,"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-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["api","golang","proxy","server","tcp-server"],"created_at":"2025-07-31T07:01:44.280Z","updated_at":"2026-06-19T21:31:45.610Z","avatar_url":"https://github.com/Annany2002.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wisp\n\nA minimalist web server and reverse proxy written in Go. Inspired by Nginx's architecture but designed for simplicity.\n\n## Features\n\n- **Static File Server**: Serve static files with MIME type detection\n- **Reverse Proxy**: Route requests to backend services with full body forwarding\n- **Load Balancing**: Upstream groups with round-robin and least-connections algorithms, weighted backends, and automatic health checks\n- **Gzip Compression**: Automatic compression for text-based responses (HTML, CSS, JS, JSON, SVG, XML)\n- **TLS Support**: HTTPS with custom certificates\n- **Nginx-style Config**: Familiar configuration syntax with multiple server blocks\n- **Path-based Routing**: Longest prefix matching for request routing\n- **HTTP Keep-Alive**: Persistent connections for improved performance\n- **Graceful Shutdown**: Clean shutdown on SIGINT/SIGTERM with connection draining\n- **Access Logging**: Structured request logs with client IP, method, URI, status, and duration\n- **Security**: Path traversal protection and connection timeouts\n\n## Quick Start\n\n1. **Build and run**:\n\n   ```sh\n   go build -o wisp cmd/wisp/main.go\n   ./wisp\n   ```\n\n2. **Custom config path**:\n\n   ```sh\n   ./wisp -c /path/to/wisp.conf\n   ```\n\n3. **With Docker**:\n\n   ```sh\n   docker build -t wisp .\n   docker run -v $(pwd)/wisp.conf:/root/wisp.conf -p 8080:8080 wisp\n   ```\n\n4. **With Docker Compose**:\n   ```sh\n   docker compose up\n   ```\n\n## Configuration\n\nWisp uses `wisp.conf` with Nginx-style syntax:\n\n```nginx\nserver {\n    listen 8080;\n    server_name example.com;\n\n    # Serve static files\n    location / {\n        root /var/www/site;\n    }\n\n    # Proxy to backend\n    location /api/ {\n        proxy_pass http://localhost:3000;\n    }\n}\n```\n\n### Multiple Server Blocks\n\nRun multiple servers on different ports from a single config:\n\n```nginx\nserver {\n    listen 8080;\n    server_name web.example.com;\n\n    location / {\n        root /var/www/site;\n    }\n}\n\nserver {\n    listen 8443;\n    server_name api.example.com;\n\n    ssl_certificate     ./cert.pem;\n    ssl_certificate_key ./key.pem;\n\n    location /api/ {\n        proxy_pass http://localhost:3000;\n    }\n}\n```\n\n### Load Balancing\n\nDefine upstream groups to distribute requests across multiple backends:\n\n```nginx\nupstream api_servers {\n    method round_robin;    # or least_conn\n    server 127.0.0.1:3001;\n    server 127.0.0.1:3002;\n    server 127.0.0.1:3003 weight=3;\n}\n\nserver {\n    listen 8080;\n\n    location /api/ {\n        proxy_pass http://api_servers;\n    }\n}\n```\n\n**Algorithms:**\n- `round_robin` (default) — distributes requests evenly, respecting weights\n- `least_conn` — sends to the backend with the fewest active connections, weighted\n\n**Health checks:** Backends are probed via TCP every 10 seconds. Failed backends are automatically removed from rotation and restored when they recover.\n\n### HTTPS Setup\n\n```nginx\nserver {\n    listen 8443;\n    server_name localhost;\n\n    ssl_certificate     ./cert.pem;\n    ssl_certificate_key ./key.pem;\n\n    location / {\n        root ./wisp_test_site;\n    }\n}\n```\n\n### Routing\n\nWisp matches requests to the most specific location:\n\n- `/about.html` -\u003e serves from `/var/www/site/about.html`\n- `/api/users` -\u003e proxies to `http://localhost:3000/users`\n- `/api/v2/users` -\u003e proxies to `http://localhost:3001/users` (if configured)\n\n## Development\n\n**Hot reload with Air**:\n\n```sh\ngo install github.com/air-verse/air@latest\nair\n```\n\n**Run tests**:\n\n```sh\ngo test ./...\n```\n\n**Test site included**: `wisp_test_site/` directory with sample files.\n\n## Configuration Reference\n\n| Directive             | Context  | Description            | Example                             |\n| --------------------- | -------- | ---------------------- | ----------------------------------- |\n| `listen`              | server   | Port to listen on      | `listen 8080;`                      |\n| `server_name`         | server   | Server identifier      | `server_name api.example.com;`      |\n| `ssl_certificate`     | server   | SSL certificate path   | `ssl_certificate ./cert.pem;`       |\n| `ssl_certificate_key` | server   | SSL key path           | `ssl_certificate_key ./key.pem;`    |\n| `root`                | location | Static files directory | `root /var/www/site;`               |\n| `proxy_pass`          | location | Backend or upstream URL| `proxy_pass http://localhost:3000;` |\n| `method`              | upstream | Load balancing method  | `method least_conn;`                |\n| `server`              | upstream | Backend address        | `server 127.0.0.1:3001 weight=3;`  |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannany2002%2Fwisp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannany2002%2Fwisp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannany2002%2Fwisp/lists"}